From 411ee8293d4c82e12f3e5091ffc2d7eeeec4f86a Mon Sep 17 00:00:00 2001 From: zetaloop Date: Sat, 28 Feb 2026 07:26:26 +0800 Subject: [PATCH] docs: align API doc with backend TypeB --- 接口文档.md | 70 +++++++++++++++++++++++++++-------------------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/接口文档.md b/接口文档.md index 79b71be..2c8ca4f 100644 --- a/接口文档.md +++ b/接口文档.md @@ -8,34 +8,30 @@ ## 2. 全局约定 ### 2.1 认证与授权 (Auth) -- 采用 JWT (JSON Web Token) 进行无状态认证。 -- 客户端在请求头中携带 Token：`Authorization: Bearer `。 -- 刷新令牌 (Refresh Token) 存储在 HttpOnly Cookie 中，用于获取新的 Access Token。 + +- 采用 Cookie `JToken` 进行认证（Phase 2 接入后端时实现）。 +- Phase 1 阶段仅为纯前端 Mock，不涉及真实后端交互。 - 接口权限标识： - 🔒：需要登录认证。 - 🛡️：需要管理员权限。 ### 2.2 错误响应格式 + 所有失败的请求均返回统一的 JSON 结构，并附带 HTTP 状态码（如 400, 401, 403, 404, 500）。 + ```json { - "ok": false, - "reasonCode": "AUTH_REQUIRED", - "message": "请先登录" + "code": 401, + "msg": "请先登录" } ``` -**ReasonCode 枚举值**： -- `AUTH_REQUIRED`: 未登录或 Token 失效 -- `NOT_FOUND`: 资源不存在 -- `NOT_PARTICIPANT`: 非参与者（无权操作该订单/会话等） -- `ROLE_FORBIDDEN`: 角色权限不足 -- `INVALID_STATUS`: 状态不合法（如订单状态不允许当前操作） -- `ALREADY_DONE`: 操作已完成（如已评价） -- `DISPUTE_LOCKED`: 处于争议状态，操作被锁定 -- `PAYMENT_FAILED`: 支付失败或余额不足 -- `IDEMPOTENT_NOOP`: 幂等操作（重复请求，无副作用） -- `VALIDATION_FAILED`: 参数校验失败 -- `DUPLICATE_REQUEST`: 重复请求 + +**常见错误码 (code)**： +- `401`: 未登录或 Token 失效 +- `403`: 角色权限不足或非参与者 +- `404`: 资源不存在 +- `400`: 参数校验失败、状态不合法、重复请求等 +- `500`: 服务器内部错误 ### 2.3 分页规范 采用 `offset` 和 `limit` 进行分页（与前端 `SearchResponse` 保持一致）。 @@ -52,11 +48,13 @@ } ``` -### 2.4 文件上传 -- **端点**: `POST /api/v1/upload` +### 2.4 文件上传与访问 + +- **上传端点**: `POST /api/v1/upload` - **Content-Type**: `multipart/form-data` - **参数**: `file` (文件), `type` (枚举: `avatar`, `chat`, `post`, `verification`, `dispute`) -- **响应**: 返回文件的 CDN URL。 +- **响应**: 返回文件的 CDN URL 或文件 ID。 +- **访问端点**: `GET /api/v1/files/:fileId` (获取文件内容) ### 2.5 时间戳格式 所有时间字段均采用 ISO 8601 格式的 UTC 时间字符串，例如：`2024-03-20T12:00:00.000Z`。 @@ -67,6 +65,10 @@ - `owner`: 店铺店长 - `admin`: 平台管理员（隐藏角色，用于后台管理） +### 2.7 ID 规范 + +所有 ID 均由后端使用 Snowflake 算法生成，类型为 `int64`。在前端交互和 JSON 序列化时，统一作为 `string` 处理，以避免精度丢失。 + --- ## 3. 数据模型 @@ -76,12 +78,12 @@ | ------------------ | ---------- | ---------------------------------------------------- | | id | string | 用户唯一标识 | | username | string | 登录用户名 | +| email | string | 邮箱地址 (可选) | | nickname | string | 昵称 | | avatar | string | 头像 URL | | role | UserRole | 当前激活的角色 | | verifiedRoles | UserRole[] | 已认证的角色列表 | | verificationStatus | object | 各角色的认证状态 (`pending`, `approved`, `rejected`) | -| phone | string | 手机号 (可选) | | bio | string | 个人简介 (可选) | | createdAt | string | 注册时间 | @@ -285,12 +287,12 @@ | 方法 | 路径 | 权限 | 说明 | | ------ | ------------------------------------- | ---- | --------------------------------- | -| POST | `/auth/register` | | 用户注册 | -| POST | `/auth/login` | | 用户登录，返回 JWT | -| POST | `/auth/logout` | 🔒 | 退出登录，清除 Cookie | -| POST | `/auth/refresh` | | 刷新 Token | -| POST | `/auth/forgot-password` | | 忘记密码（发送验证码） | -| POST | `/auth/reset-password` | | 重置密码 | +| POST | `/auth/register` | | 用户注册 (username + email + password + vcode) | +| POST | `/auth/login` | | 用户登录 (username + password) | +| POST | `/auth/logout` | 🔒 | 退出登录，清除 Cookie | +| POST | `/auth/forgot-password/send` | | 忘记密码（发送验证码到邮箱） | +| POST | `/auth/reset-password` | | 重置密码 (email + vcode + newPassword) | +| POST | `/email/verification-code/send` | | 发送邮箱验证码 | | GET | `/users/me` | 🔒 | 获取当前登录用户信息 | | PUT | `/users/me` | 🔒 | 更新个人资料 (昵称, 头像, 简介等) | | POST | `/users/me/switch-role` | 🔒 | 切换当前激活角色 | @@ -303,22 +305,23 @@ | DELETE | `/users/:id/follow` | 🔒 | 取消关注用户 | **请求示例：登录** + ```json // POST /api/v1/auth/login { - "phone": "13800138000", - "password": "...", - "remember": true + "username": "zhangsan", + "password": "..." } ``` + **响应示例：登录成功** + ```json { - "accessToken": "eyJhbGciOiJIUzI1NiIs...", - "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g...", "user": { "id": "u1", "username": "zhangsan", + "email": "zhangsan@example.com", "nickname": "张三", "avatar": "https://cdn.juwan.com/avatars/u1.jpg", "role": "consumer", @@ -497,7 +500,6 @@ **响应示例：订单创建成功** ```json { - "ok": true, "order": { "id": "ord-20240320-001", "consumerId": "u1",