# 云印享 - 前端 API 使用指南

本文档面向前端开发者，详细说明如何调用云印享后端 API 接口。后端基于 gRPC 构建，前端通过 HTTP RESTful 风格接口进行通信。

## 目录

- [基础配置](#基础配置)
- [认证服务 (Auth)](#认证服务-auth)
- [文件管理服务 (File)](#文件管理服务-file)
- [订单服务 (Order)](#订单服务-order)
- [打印服务 (Print)](#打印服务-print)
- [支付服务 (Pay)](#支付服务-pay)
- [价目表服务 (Price)](#价目表服务-price)
- [错误处理](#错误处理)
- [注意事项](#注意事项)

---

## 基础配置

### API 基础地址

API 地址配置在 [`src/config/api.ts`](src/config/api.ts:1) 中：

```typescript
const DEV_API_URL = "http://localhost:8080";
const PROD_API_URL = "http://localhost:8080";
export const API_BASE_URL =
  process.env.NODE_ENV === "development" ? DEV_API_URL : PROD_API_URL;
```

### 请求封装

项目已封装统一的请求工具 [`src/utils/request.ts`](src/utils/request.ts:1)，自动处理：

- Token 注入（Bearer 认证）
- 401 未授权处理（自动登出）
- 错误捕获

```typescript
// 使用示例
import { request } from "../utils/request";

const response = await request({
  url: "/auth/userinfo",
  method: "GET",
});
```

### 统一响应格式

所有 API 返回遵循统一格式：

```typescript
interface ApiResponse<T = any> {
  code: number; // 状态码，0 表示成功
  message: string; // 响应消息
  data: T; // 实际数据
}
```

---

## 认证服务 (Auth)

**基础路径**: `/auth`

### 1. 微信登录

获取用户访问令牌。

| 项目         | 说明                                                                |
| ------------ | ------------------------------------------------------------------- |
| **接口地址** | `POST /auth/login`                                                  |
| **请求参数** | `{ code: string }` - 微信登录凭证 code                              |
| **返回数据** | `{ accessToken: string; refreshToken: string; userInfo: UserInfo }` |

**代码示例**：

```typescript
import { authApi } from "./api/auth";

// 调用登录接口
const response = await authApi.login(wxCode);
// response.accessToken   // 访问令牌
// response.refreshToken  // 刷新令牌
// response.userInfo      // 用户信息
```

**响应示例**：

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "userInfo": {
    "id": 1,
    "openid": "oXXXX-xxxxx",
    "nickname": "用户昵称",
    "avatar": "https://xxx.com/avatar.jpg",
    "balance": 10.5,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

### 2. 刷新 Token

使用刷新令牌获取新的访问令牌。

| 项目         | 说明                       |
| ------------ | -------------------------- |
| **接口地址** | `POST /auth/refresh`       |
| **请求参数** | `{ refreshToken: string }` |
| **返回数据** | `{ accessToken: string }`  |

**代码示例**：

```typescript
const { accessToken } = await authApi.refreshToken(refreshToken);
```

### 3. 获取用户信息

获取当前登录用户的详细信息。

| 项目         | 说明                              |
| ------------ | --------------------------------- |
| **接口地址** | `GET /auth/userinfo`              |
| **请求参数** | 无                                |
| **返回数据** | [`UserInfo`](src/types/user.ts:1) |

**代码示例**：

```typescript
const userInfo = await authApi.getUserInfo();
console.log(userInfo.nickname, userInfo.balance);
```

### 4. 更新用户信息

更新用户昵称和头像。

| 项目         | 说明                                     |
| ------------ | ---------------------------------------- |
| **接口地址** | `POST /auth/update`                      |
| **请求参数** | `{ nickname?: string; avatar?: string }` |
| **返回数据** | [`UserInfo`](src/types/user.ts:1)        |

**代码示例**：

```typescript
const updatedUser = await authApi.updateUser({
  nickname: "新昵称",
  avatar: "https://new-avatar.jpg",
});
```

### 5. 手机号登录

使用手机号和短信验证码登录。

| 项目         | 说明                                                                |
| ------------ | ------------------------------------------------------------------- |
| **接口地址** | `POST /auth/phone/login`                                            |
| **请求参数** | `{ phone: string; code: string }`                                   |
| **返回数据** | `{ accessToken: string; refreshToken: string; userInfo: UserInfo }` |

**代码示例**：

```typescript
import { authApi } from "./api/auth";

// 调用手机号登录接口
const response = await authApi.phoneLogin({
  phone: "13800138000",
  code: "123456",
});
```

### 6. 发送短信验证码

发送短信验证码到指定手机号。

| 项目         | 说明                  |
| ------------ | --------------------- |
| **接口地址** | `POST /auth/sms/code` |
| **请求参数** | `{ phone: string }`   |
| **返回数据** | `void`                |

**代码示例**：

```typescript
import { authApi } from "./api/auth";

// 发送短信验证码
await authApi.sendSmsCode({ phone: "13800138000" });
```

---

## 文件管理服务 (File)

**基础路径**: `/file`

### 1. 上传文件

支持分片上传，使用 Taro 原生上传能力。

| 项目         | 说明                                  |
| ------------ | ------------------------------------- |
| **接口地址** | `POST /file/upload`                   |
| **请求参数** | `filePath: string` - 本地文件路径     |
| **返回数据** | `{ fileId: number; fileUrl: string }` |

**代码示例**：

```typescript
import { fileApi } from "./api/file";

// 上传文件
const result = await fileApi.upload(tempFilePath);
console.log(result.fileId, result.fileUrl);
```

### 2. 获取文件列表

分页获取用户上传的文件列表。

| 项目         | 说明                                                              |
| ------------ | ----------------------------------------------------------------- |
| **接口地址** | `GET /file/list`                                                  |
| **请求参数** | `{ page?: number; pageSize?: number }` - 默认 page=1, pageSize=20 |
| **返回数据** | `{ files: FileInfo[]; total: number }`                            |

**代码示例**：

```typescript
const { files, total } = await fileApi.getFileList(1, 20);
```

### 3. 获取文件详情

| 项目         | 说明                              |
| ------------ | --------------------------------- |
| **接口地址** | `GET /file/:fileId`               |
| **请求参数** | `fileId: number`                  |
| **返回数据** | [`FileInfo`](src/types/file.ts:1) |

**代码示例**：

```typescript
const fileInfo = await fileApi.getFile(123);
```

### 4. 删除文件

| 项目         | 说明                   |
| ------------ | ---------------------- |
| **接口地址** | `DELETE /file/:fileId` |
| **请求参数** | `fileId: number`       |
| **返回数据** | `void`                 |

**代码示例**：

```typescript
await fileApi.deleteFile(123);
```

### 5. 添加水印

| 项目         | 说明                                      |
| ------------ | ----------------------------------------- |
| **接口地址** | `POST /file/:fileId/watermark`            |
| **请求参数** | `fileId: number`, `{ watermark: string }` |
| **返回数据** | `{ watermarkUrl: string }`                |

**代码示例**：

```typescript
const { watermarkUrl } = await fileApi.addWatermark(123, "仅供打印使用");
```

---

## 订单服务 (Order)

**基础路径**: `/order`

### 1. 创建订单

| 项目         | 说明                                          |
| ------------ | --------------------------------------------- |
| **接口地址** | `POST /order/create`                          |
| **请求参数** | [`CreateOrderRequest`](src/types/order.ts:22) |
| **返回数据** | [`Order`](src/types/order.ts:4)               |

**请求参数结构**：

```typescript
{
  fileId: number; // 文件ID
  printerId: number; // 打印机ID
  printType: "A4" | "A3" | "照片"; // 打印类型
  colorType: "黑白" | "彩色"; // 颜色类型
  copies: number; // 份数
}
```

**代码示例**：

```typescript
import { orderApi } from "./api/order";

const order = await orderApi.createOrder({
  fileId: 123,
  printerId: 1,
  printType: "A4",
  colorType: "黑白",
  copies: 2,
});
```

### 2. 获取订单详情

| 项目         | 说明                            |
| ------------ | ------------------------------- |
| **接口地址** | `GET /order/:orderId`           |
| **请求参数** | `orderId: number`               |
| **返回数据** | [`Order`](src/types/order.ts:4) |

**代码示例**：

```typescript
const order = await orderApi.getOrder(456);
```

### 3. 获取订单列表

| 项目         | 说明                                   |
| ------------ | -------------------------------------- |
| **接口地址** | `GET /order/list`                      |
| **请求参数** | `{ page?: number; pageSize?: number }` |
| **返回数据** | `{ orders: Order[]; total: number }`   |

**代码示例**：

```typescript
const { orders, total } = await orderApi.getOrderList(1, 10);
```

### 4. 更新订单状态

| 项目         | 说明                                    |
| ------------ | --------------------------------------- |
| **接口地址** | `PUT /order/:orderId/status`            |
| **请求参数** | `orderId: number`, `{ status: number }` |
| **返回数据** | [`Order`](src/types/order.ts:4)         |

**订单状态枚举**：
| 值 | 状态 |
|----|------|
| 0 | 待支付 |
| 1 | 已支付 |
| 2 | 打印中 |
| 3 | 已完成 |
| 4 | 已取消 |

**代码示例**：

```typescript
await orderApi.updateOrderStatus(456, 1); // 标记为已支付
```

### 5. 取消订单

| 项目         | 说明                            |
| ------------ | ------------------------------- |
| **接口地址** | `PUT /order/:orderId/cancel`    |
| **请求参数** | `orderId: number`               |
| **返回数据** | [`Order`](src/types/order.ts:4) |

**代码示例**：

```typescript
await orderApi.cancelOrder(456);
```

---

## 打印服务 (Print)

**基础路径**: `/print`

### 1. 获取打印机列表

| 项目         | 说明                                  |
| ------------ | ------------------------------------- |
| **接口地址** | `GET /print/printers`                 |
| **请求参数** | 无                                    |
| **返回数据** | [`Printer[]`](src/types/printer.ts:3) |

**代码示例**：

```typescript
import { printerApi } from "./api/printer";

const printers = await printerApi.getPrinters();
```

### 2. 获取打印机状态

| 项目         | 说明                                   |
| ------------ | -------------------------------------- |
| **接口地址** | `GET /print/printer/:printerId/status` |
| **请求参数** | `printerId: number`                    |
| **返回数据** | [`Printer`](src/types/printer.ts:3)    |

**打印机状态枚举**：
| 值 | 状态 |
|----|------|
| 0 | 空闲 |
| 1 | 打印中 |
| 2 | 离线 |

**代码示例**：

```typescript
const printer = await printerApi.getPrinterStatus(1);
```

### 3. 注册打印机

| 项目         | 说明                                 |
| ------------ | ------------------------------------ |
| **接口地址** | `POST /print/printer/register`       |
| **请求参数** | `{ name: string; location: string }` |
| **返回数据** | [`Printer`](src/types/printer.ts:3)  |

**代码示例**：

```typescript
const printer = await printerApi.registerPrinter("打印机1", "一楼大厅");
```

### 4. 提交打印任务

| 项目         | 说明                                     |
| ------------ | ---------------------------------------- |
| **接口地址** | `POST /print/job/submit`                 |
| **请求参数** | `{ orderId: number; printerId: number }` |
| **返回数据** | `{ jobId: number }`                      |

**代码示例**：

```typescript
const { jobId } = await printerApi.submitPrintJob(456, 1);
```

### 5. 取消打印任务

| 项目         | 说明                           |
| ------------ | ------------------------------ |
| **接口地址** | `PUT /print/job/:jobId/cancel` |
| **请求参数** | `jobId: number`                |
| **返回数据** | `void`                         |

**代码示例**：

```typescript
await printerApi.cancelPrintJob(789);
```

---

## 支付服务 (Pay)

**基础路径**: `/pay`

### 1. 创建微信支付订单

| 项目         | 说明                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **接口地址** | `POST /pay/create`                                                                             |
| **请求参数** | `{ orderId: number }`                                                                          |
| **返回数据** | `{ prepayId: string; paySign: string; timeStamp: string; nonceStr: string; signType: string }` |

**代码示例**：

```typescript
import { payApi } from "./api/pay";

const payParams = await payApi.createWxPayOrder(456);
// 使用返回参数调起微信支付
```

### 2. 查询支付状态

| 项目         | 说明                      |
| ------------ | ------------------------- |
| **接口地址** | `GET /pay/query/:orderId` |
| **请求参数** | `orderId: number`         |
| **返回数据** | `{ status: number }`      |

**支付状态枚举**：
| 值 | 状态 |
|----|------|
| 0 | 待支付 |
| 1 | 支付中 |
| 2 | 成功 |
| 3 | 失败 |

**代码示例**：

```typescript
const { status } = await payApi.queryPayStatus(456);
```

### 3. 余额支付

| 项目         | 说明                   |
| ------------ | ---------------------- |
| **接口地址** | `POST /pay/balance`    |
| **请求参数** | `{ orderId: number }`  |
| **返回数据** | `{ success: boolean }` |

**代码示例**：

```typescript
const { success } = await payApi.payByBalance(456);
```

---

## 价目表服务 (Price)

**基础路径**: `/price`

### 1. 获取价目表

| 项目         | 说明                                  |
| ------------ | ------------------------------------- |
| **接口地址** | `GET /price/list`                     |
| **请求参数** | 无                                    |
| **返回数据** | [`PriceItem[]`](src/types/price.ts:3) |

**代码示例**：

```typescript
import { priceApi } from "./api/price";

const priceList = await priceApi.getPriceList();
```

**价目表示例**：

```json
[
  { "id": 1, "name": "A4黑白打印", "type": "A4", "price": 0.1, "unit": "页" },
  { "id": 2, "name": "A4彩色打印", "type": "A4", "price": 0.3, "unit": "页" },
  { "id": 3, "name": "A3黑白打印", "type": "A3", "price": 0.2, "unit": "页" },
  { "id": 4, "name": "A3彩色打印", "type": "A3", "price": 0.6, "unit": "页" },
  { "id": 5, "name": "照片打印", "type": "照片", "price": 2.0, "unit": "张" }
]
```

---

## 错误处理

### HTTP 状态码

| 状态码 | 说明           | 处理建议                     |
| ------ | -------------- | ---------------------------- |
| 200    | 请求成功       | 正常处理响应数据             |
| 400    | 请求参数错误   | 检查请求参数格式             |
| 401    | 未授权         | Token 过期或无效，需重新登录 |
| 403    | 禁止访问       | 权限不足                     |
| 404    | 资源不存在     | 检查请求的资源 ID            |
| 500    | 服务器内部错误 | 联系后端排查                 |

### 统一错误处理

[`request.ts`](src/utils/request.ts:1) 已封装错误处理逻辑：

```typescript
try {
  const result = await orderApi.createOrder(orderData);
} catch (error) {
  if (error.message === "Unauthorized") {
    // 处理未授权，跳转登录
    Taro.redirectTo({ url: "/pages/login/index" });
  } else {
    // 显示错误提示
    Taro.showToast({ title: error.message, icon: "none" });
  }
}
```

---

## 注意事项

### 1. 认证机制

- 所有需要用户身份的接口都需要在请求头中携带 `Authorization: Bearer <token>`
- Token 由 [`request.ts`](src/utils/request.ts:16) 自动注入，无需手动处理
- Token 过期时，服务器返回 401，前端自动触发登出

### 2. 文件上传

- 使用 Taro 原生 `uploadFile` API，支持断点续传
- 上传成功后返回 `fileId` 和 `fileUrl`，用于后续订单创建

### 3. 分页查询

- 文件列表和订单列表接口支持分页
- 默认 `page=1`, `pageSize=20`
- 响应中包含 `total` 字段表示总记录数

### 4. 状态枚举

- 订单状态、支付状态、打印机状态均使用数字枚举
- 类型定义文件（如 [`order.ts`](src/types/order.ts:1)）中提供了状态映射表，便于显示

### 5. 数据格式

- 所有时间字段使用 ISO 8601 格式字符串（如 `"2024-01-01T12:00:00Z"`）
- 价格字段使用数字类型，单位为元（如 `0.10` 表示 0.1 元）

### 6. 开发环境配置

- 开发环境 API 地址：`http://localhost:8080`
- 确保后端服务已启动且端口正确
- 如需修改地址，编辑 [`src/config/api.ts`](src/config/api.ts:1)

### 7. 类型安全

- 所有 API 接口都有完整的 TypeScript 类型定义
- 导入对应的类型文件（如 `import type { Order } from '../types'`）
- 使用类型提示可以减少运行时错误

---

## 快速开始示例

以下是一个完整的打印流程示例：

```typescript
import { authApi } from "./api/auth";
import { fileApi } from "./api/file";
import { orderApi } from "./api/order";
import { printerApi } from "./api/printer";
import { payApi } from "./api/pay";

// 1. 登录
const { accessToken, userInfo } = await authApi.login(wxCode);

// 2. 上传文件
const { fileId } = await fileApi.upload(tempFilePath);

// 3. 获取打印机列表
const printers = await printerApi.getPrinters();
const availablePrinter = printers.find((p) => p.status === 0);

// 4. 创建订单
const order = await orderApi.createOrder({
  fileId,
  printerId: availablePrinter.id,
  printType: "A4",
  colorType: "黑白",
  copies: 2,
});

// 5. 发起支付
const payParams = await payApi.createWxPayOrder(order.id);
// 调起微信支付...

// 6. 查询支付状态
const { status } = await payApi.queryPayStatus(order.id);
if (status === 2) {
  // 支付成功，提交打印任务
  await printerApi.submitPrintJob(order.id, availablePrinter.id);
}
```

---

## 更新日志

- 2024-01-01: 初始版本，基于后端 README 和前端现有实现整理

---

**文档维护**: 前端开发团队  
**最后更新**: 2024-01-01