docs: align API doc with backend TypeB

接口文档.md

@@ -8,34 +8,30 @@
 ## 2. 全局约定
 
 ### 2.1 认证与授权 (Auth)
-- 采用 JWT (JSON Web Token) 进行无状态认证。
+
-- 客户端在请求头中携带 Token：`Authorization: Bearer <access_token>`。
+- 采用 Cookie `JToken` 进行认证（Phase 2 接入后端时实现）。
-- 刷新令牌 (Refresh Token) 存储在 HttpOnly Cookie 中，用于获取新的 Access Token。
+- Phase 1 阶段仅为纯前端 Mock，不涉及真实后端交互。
 - 接口权限标识：
   - 🔒：需要登录认证。
   - 🛡️：需要管理员权限。
 
 ### 2.2 错误响应格式
+
 所有失败的请求均返回统一的 JSON 结构，并附带 HTTP 状态码（如 400, 401, 403, 404, 500）。
+
 ```json
 {
-  "ok": false,
+  "code": 401,
-  "reasonCode": "AUTH_REQUIRED",
+  "msg": "请先登录"
-  "message": "请先登录"
 }
 ```
-**ReasonCode 枚举值**：
+
-- `AUTH_REQUIRED`: 未登录或 Token 失效
+**常见错误码 (code)**：
-- `NOT_FOUND`: 资源不存在
+- `401`: 未登录或 Token 失效
-- `NOT_PARTICIPANT`: 非参与者（无权操作该订单/会话等）
+- `403`: 角色权限不足或非参与者
-- `ROLE_FORBIDDEN`: 角色权限不足
+- `404`: 资源不存在
-- `INVALID_STATUS`: 状态不合法（如订单状态不允许当前操作）
+- `400`: 参数校验失败、状态不合法、重复请求等
-- `ALREADY_DONE`: 操作已完成（如已评价）
+- `500`: 服务器内部错误
-- `DISPUTE_LOCKED`: 处于争议状态，操作被锁定
-- `PAYMENT_FAILED`: 支付失败或余额不足
-- `IDEMPOTENT_NOOP`: 幂等操作（重复请求，无副作用）
-- `VALIDATION_FAILED`: 参数校验失败
-- `DUPLICATE_REQUEST`: 重复请求
 
 ### 2.3 分页规范
 采用 `offset` 和 `limit` 进行分页（与前端 `SearchResponse` 保持一致）。
@@ -52,11 +48,13 @@
 }
 ```
 
-### 2.4 文件上传
+### 2.4 文件上传与访问
-- **端点**: `POST /api/v1/upload`
+
+- **上传端点**: `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/register`                      |      | 用户注册 (username + email + password + vcode) |
-| POST   | `/auth/login`                         |      | 用户登录，返回 JWT                |
+| POST   | `/auth/login`                         |      | 用户登录 (username + password)                 |
-| POST   | `/auth/logout`                        | 🔒    | 退出登录，清除 Cookie             |
+| POST   | `/auth/logout`                        | 🔒    | 退出登录，清除 Cookie                          |
-| POST   | `/auth/refresh`                       |      | 刷新 Token                        |
+| POST   | `/auth/forgot-password/send`          |      | 忘记密码（发送验证码到邮箱）                   |
-| POST   | `/auth/forgot-password`               |      | 忘记密码（发送验证码）            |
+| POST   | `/auth/reset-password`                |      | 重置密码 (email + vcode + newPassword)         |
-| POST   | `/auth/reset-password`                |      | 重置密码                          |
+| 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",
+  "username": "zhangsan",
-  "password": "...",
+  "password": "..."
-  "remember": true
 }
 ```
+
 **响应示例：登录成功**
+
 ```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",