PrintMiniProgram/frontend
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
frontend/API_GUIDE.md

697 lines
19 KiB
Markdown
Raw Permalink Normal View History

feat: 添加手机号登录和短信验证码功能，更新 API 地址，重构用户状态管理
2026-03-31 02:24:20 +08:00
# 云印享 - 前端 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
Reference in New Issue Copy Permalink