diff --git a/接口文档_TypeB.md b/接口文档.md similarity index 100% rename from 接口文档_TypeB.md rename to 接口文档.md diff --git a/接口文档_TypeA.md b/接口文档_TypeA.md deleted file mode 100644 index 7bbb356..0000000 --- a/接口文档_TypeA.md +++ /dev/null @@ -1,1357 +0,0 @@ -# 聚玩 后端 API 接口文档（v1 设计） - -最后更新：2026-02-25 -文档版本：0.1 - -本文档面向真实后端落地，覆盖当前前端演示项目已使用的接口形态，以及计划内但前端尚未接通的关键能力（认证、上传、通知推送、邀请流程等）。接口以可实现、可演进为目标，尽量与前端现有数据模型保持对齐，同时补足演示阶段缺失的安全边界与数据契约。 - -## 1. 通用约定 - -### 1.1 Base URL 与版本 - -- Base URL：`{API_BASE}/v1` -- 生产环境建议通过配置注入 `{API_BASE}`，前端不硬编码域名 - -### 1.2 数据格式 - -- 请求与响应：`application/json; charset=utf-8` -- 时间：ISO 8601 字符串（示例：`2026-02-25T12:34:56.789Z`） -- ID：不限定格式，统一使用 string。示例沿用演示项目风格：`ord-1700000000000-1` - -### 1.3 鉴权与身份视角 - -鉴权采用 Bearer Token： - -``` -Authorization: Bearer -``` - -多身份视角（consumer/player/owner）用于列表筛选与权限校验。服务端以登录用户的已认证角色为准，客户端可选传递当前视角： - -``` -X-Actor-Role: consumer | player | owner -``` - -约定： - -- `X-Actor-Role` 仅用于表达前端当前视角，服务端需要校验该角色是否在用户已认证角色集合中 -- 未提供 `X-Actor-Role` 时，服务端默认以用户的主角色或 consumer 视角处理 - -### 1.4 分页 - -列表接口统一支持： - -- `limit`：默认 20，最大 100 -- `offset`：默认 0 - -响应统一携带： - -```json -{ - "items": [], - "meta": { "total": 0, "offset": 0, "limit": 20 } -} -``` - -### 1.5 幂等 - -涉及资金、下单、创建类操作建议支持幂等键： - -``` -Idempotency-Key: -``` - -服务端应以 `(userId, Idempotency-Key)` 维度去重，返回相同结果。 - -### 1.6 错误响应 - -错误响应使用 HTTP 状态码表达大类，响应体提供机器可读 code 与人类可读 message： - -```json -{ - "code": "AUTH_REQUIRED", - "message": "请先登录", - "requestId": "req_xxx" -} -``` - -`code` 推荐复用前端演示项目中已有的 ReasonCode（便于迁移）： - -- `AUTH_REQUIRED`：未登录或 token 失效（401） -- `ROLE_FORBIDDEN`：身份不允许（403） -- `NOT_PARTICIPANT`：非资源参与方（403） -- `NOT_FOUND`：资源不存在（404） -- `INVALID_STATUS`：状态机不允许该操作（409） -- `ALREADY_DONE`：重复提交（409） -- `DUPLICATE_REQUEST`：幂等冲突或短时间重复请求（409） -- `VALIDATION_FAILED`：参数校验失败（422） -- `PAYMENT_FAILED`：支付失败（409/422） -- `DISPUTE_LOCKED`：争议锁定导致操作受限（409） - -服务端可扩展： - -- `RATE_LIMITED`（429） -- `INTERNAL_ERROR`（500） - -## 2. 核心数据模型（摘要） - -以下为接口层建议使用的字段集合。为了匹配真实落地场景，对演示模型做了两处补充： - -1) 订单补充 `quantity`，用于表达服务数量（演示前端已有数量输入） -2) 服务 `unit` 不限制为固定枚举，推荐使用字符串并约束可选值集合 - -### 2.1 User - -```json -{ - "id": "u1", - "username": "chen", - "nickname": "小陈", - "avatar": "/avatars/u1.png", - "role": "consumer", - "verifiedRoles": ["consumer", "player"], - "verificationStatus": { "player": "approved", "owner": "pending" }, - "phone": "138****0000", - "bio": "简介", - "createdAt": "2026-02-25T12:00:00.000Z" -} -``` - -### 2.2 PlayerService - -```json -{ - "id": "svc-1", - "playerId": "u5", - "gameId": "g1", - "gameName": "英雄联盟", - "title": "LOL双排上分", - "description": "服务描述", - "price": 25, - "unit": "局", - "rankRange": "黄金-铂金", - "availability": ["工作日晚上9点后", "周末全天"] -} -``` - -`unit` 推荐值：`局`、`星`、`次`、`小时`、`段`（服务端可按业务扩展）。 - -### 2.3 Order - -```json -{ - "id": "ord-1", - "consumerId": "u1", - "consumerName": "小陈", - "playerId": "u6", - "playerName": "Winter", - "shopId": "shop2", - "shopName": "Yuki 小屋", - "service": { "id": "s4", "playerId": "u6", "gameId": "g2", "gameName": "王者荣耀", "title": "王者双排稳上星", "description": "...", "price": 18, "unit": "星", "availability": [] }, - "quantity": 3, - "status": "pending_accept", - "totalPrice": 54, - "note": "3星，我用鲁班", - "createdAt": "2026-02-25T12:00:00.000Z", - "acceptedAt": null, - "closedAt": null, - "completedAt": null -} -``` - -`status` 取值与状态机见 7.5。 - -### 2.4 Dispute（详情态） - -争议详情建议返回扩展字段，匹配前端现有展示与时间线： - -```json -{ - "id": "disp-1", - "orderId": "ord-1", - "initiatorId": "u1", - "initiatorName": "小陈", - "reason": "争议原因", - "evidence": ["https://cdn/.../a.png"], - "respondentReason": "回应理由", - "respondentEvidence": ["https://cdn/.../b.png"], - "status": "reviewing", - "result": null, - "appealReason": null, - "appealedAt": null, - "createdAt": "2026-02-25T12:00:00.000Z", - "timeline": [ - { "id": "timeline-1", "type": "created", "content": "小陈 提交争议", "createdAt": "2026-02-25T12:00:00.000Z" }, - { "id": "timeline-2", "type": "response", "content": "对方已提交回应材料", "createdAt": "2026-02-25T12:10:00.000Z" } - ] -} -``` - -### 2.5 Game - -```json -{ - "id": "g1", - "name": "英雄联盟", - "icon": "lol", - "category": "MOBA" -} -``` - -### 2.6 Player - -```json -{ - "id": "u5", - "user": { "id": "u5", "username": "jun", "nickname": "俊俊", "avatar": "/avatars/u5.png", "role": "player", "createdAt": "..." }, - "rating": 4.2, - "totalOrders": 156, - "completionRate": 0.94, - "status": "available", - "games": ["英雄联盟", "王者荣耀"], - "services": [], - "shopId": "shop1", - "shopName": "老王游戏工作室", - "tags": ["准时上线"] -} -``` - -### 2.7 Shop - -```json -{ - "id": "shop1", - "owner": { "id": "u10", "username": "wang", "nickname": "老王", "avatar": "/avatars/u10.png", "role": "owner", "createdAt": "..." }, - "name": "老王游戏工作室", - "banner": "/banners/shop1.jpg", - "description": "店铺简介", - "rating": 4.7, - "totalOrders": 3842, - "playerCount": 14, - "commissionType": "percentage", - "commissionValue": 15, - "allowMultiShop": false, - "allowIndependentOrders": false, - "dispatchMode": "manual", - "announcements": ["公告1"], - "templateConfig": { - "sections": [ - { "type": "intro", "enabled": true, "order": 1 }, - { "type": "players", "enabled": true, "order": 2 } - ] - } -} -``` - -### 2.8 Review - -```json -{ - "id": "rev-1", - "orderId": "ord-1", - "fromUserId": "u1", - "fromUserName": "小陈", - "fromUserAvatar": "/avatars/u1.png", - "toUserId": "u6", - "rating": 5, - "content": "体验很好", - "sealed": true, - "createdAt": "..." -} -``` - -### 2.9 Post - -```json -{ - "id": "post-1", - "author": { "id": "u1", "username": "chen", "nickname": "小陈", "avatar": "/avatars/u1.png", "role": "consumer", "createdAt": "..." }, - "authorRole": "consumer", - "title": "标题", - "content": "内容", - "images": ["https://cdn.../p1.png"], - "tags": ["英雄联盟", "攻略"], - "linkedOrderId": "ord-1", - "quotedPostId": null, - "likeCount": 10, - "commentCount": 2, - "liked": false, - "pinned": false, - "createdAt": "..." -} -``` - -### 2.10 Comment - -```json -{ - "id": "comment-1", - "postId": "post-1", - "author": { "id": "u2", "username": "ling", "nickname": "玲玲", "avatar": "/avatars/u2.png", "role": "consumer", "createdAt": "..." }, - "content": "评论内容", - "likeCount": 0, - "liked": false, - "createdAt": "..." -} -``` - -### 2.11 Notification - -```json -{ - "id": "notif-1", - "type": "order", - "title": "订单待接单", - "content": "xxx 已支付，等待接单", - "read": false, - "link": "/order/ord-1", - "createdAt": "..." -} -``` - -### 2.12 Favorite - -```json -{ - "id": "fav-1", - "userId": "u1", - "targetType": "player", - "targetId": "u6", - "createdAt": "..." -} -``` - -### 2.13 WalletTransaction（建议扩展字段） - -```json -{ - "id": "tx-1", - "type": "payment", - "amount": -54, - "orderId": "ord-1", - "shopId": "shop2", - "description": "支付订单 ord-1", - "createdAt": "..." -} -``` - -### 2.14 ChatSession - -```json -{ - "id": "chat-ord-1", - "type": "order", - "orderId": "ord-1", - "participants": [ - { "id": "u1", "name": "小陈", "avatar": "/avatars/u1.png" }, - { "id": "u6", "name": "Winter", "avatar": "/avatars/u6.png" } - ], - "lastMessage": "你好", - "lastMessageAt": "...", - "unreadCount": 0, - "readonly": false -} -``` - -### 2.15 ChatMessage - -```json -{ - "id": "msg-1", - "sessionId": "chat-ord-1", - "senderId": "u1", - "senderName": "小陈", - "senderAvatar": "/avatars/u1.png", - "type": "text", - "content": "你好", - "createdAt": "..." -} -``` - -### 2.16 File（上传结果） - -```json -{ - "id": "file-1", - "url": "https://cdn.example.com/files/file-1.png", - "contentType": "image/png", - "size": 123456 -} -``` - -## 3. 上传（文件/图片） - -演示前端目前大量使用 `URL.createObjectURL` 或固定占位路径。切真实后端时，建议统一通过上传接口获得可复现的 URL，再写入业务资源（头像、帖子图片、聊天图片、争议证据、认证材料等）。 - -### 3.1 上传文件 - -`POST /v1/files` - -- Auth：需要 -- Content-Type：`multipart/form-data` - -表单字段： - -- `file`：文件二进制 -- `purpose`：`avatar | post_image | chat_image | dispute_evidence | verification_material` - -响应： - -```json -{ - "id": "file-1", - "url": "https://cdn.example.com/files/file-1.png", - "contentType": "image/png", - "size": 123456 -} -``` - -约束建议： - -- 图片类限制 MIME 与大小（例如单张 ≤ 5MB） -- 上传结果 URL 建议为不可枚举地址或带访问控制 - -## 4. Auth（登录/注册/会话） - -### 4.1 注册 - -`POST /v1/auth/register` - -请求： - -```json -{ - "username": "chen", - "password": "******", - "nickname": "小陈" -} -``` - -响应： - -```json -{ - "accessToken": "token...", - "refreshToken": "token...", - "user": { "id": "u1", "username": "chen", "nickname": "小陈", "avatar": "", "role": "consumer", "createdAt": "..." } -} -``` - -### 4.2 登录 - -`POST /v1/auth/login` - -请求： - -```json -{ - "username": "chen", - "password": "******", - "remember": true -} -``` - -响应同 4.1。 - -### 4.3 刷新 token - -`POST /v1/auth/refresh` - -请求： - -```json -{ "refreshToken": "token..." } -``` - -响应： - -```json -{ "accessToken": "token..." } -``` - -### 4.4 获取当前用户 - -`GET /v1/auth/me` - -响应：User - -### 4.5 退出登录 - -`POST /v1/auth/logout` - -响应： - -```json -{ "ok": true } -``` - -### 4.6 找回密码（计划内） - -前端已有找回密码页面的 UI 行为，真实后端建议提供： - -- `POST /v1/auth/password/forgot`：发送验证码或重置链接 -- `POST /v1/auth/password/reset`：提交新密码 - -## 5. 用户与设置 - -### 5.1 获取用户信息 - -`GET /v1/users/{userId}` - -响应：User - -### 5.2 更新个人资料 - -`PATCH /v1/users/me` - -请求： - -```json -{ - "nickname": "新昵称", - "bio": "新简介", - "avatar": "https://cdn.../avatar.png" -} -``` - -响应：User - -### 5.3 更新通知偏好与外观偏好 - -`PATCH /v1/users/me/preferences` - -请求： - -```json -{ - "notificationPrefs": { "order": true, "community": true, "system": false }, - "themePreference": "system" -} -``` - -响应： - -```json -{ "ok": true } -``` - -### 5.4 身份认证（打手/店主） - -演示前端的身份认证页面包含真实姓名、身份证号、游戏资质描述与证明材料占位。真实后端建议将认证作为独立资源管理，并避免在任何对外接口返回敏感字段（例如身份证号原文与证件照片的可公开 URL）。 - -`GET /v1/verifications/me` - -响应示例： - -```json -{ - "items": [ - { "id": "ver-1", "role": "player", "status": "pending", "reason": null, "createdAt": "..." } - ], - "meta": { "total": 1, "offset": 0, "limit": 20 } -} -``` - -`POST /v1/verifications` - -请求示例： - -```json -{ - "role": "player", - "realName": "张三", - "idNumber": "110***********1234", - "qualificationText": "段位、经历等", - "materialFileIds": ["file-1", "file-2", "file-3"] -} -``` - -响应： - -```json -{ - "id": "ver-1", - "role": "player", - "status": "pending", - "createdAt": "..." -} -``` - -审核（平台后台，计划内）： - -- `GET /v1/admin/verifications?status=pending` -- `POST /v1/admin/verifications/{verificationId}/approve` -- `POST /v1/admin/verifications/{verificationId}/reject`（携带 reason） - -## 6. 店铺、打手、服务 - -### 6.1 游戏列表 - -`GET /v1/games` - -响应： - -```json -{ - "items": [{ "id": "g1", "name": "英雄联盟", "icon": "lol", "category": "MOBA" }], - "meta": { "total": 1, "offset": 0, "limit": 20 } -} -``` - -### 6.2 打手列表 / 详情 - -`GET /v1/players` - -查询参数（可选）： - -- `shopId` -- `gameId` 或 `gameName` -- `status`：`available | busy | offline` - -响应：分页 `items: Player[]` - -`GET /v1/players/{playerId}` - -响应：Player（可选包含 services 简要信息，或通过 6.4 获取） - -### 6.2.1 更新打手状态（计划内） - -`PATCH /v1/players/me/status` - -- Auth：需要 -- 允许角色：`player` - -请求： - -```json -{ "status": "available" } -``` - -响应： - -```json -{ "ok": true } -``` - -### 6.3 店铺列表 / 详情 - -`GET /v1/shops` - -查询参数（可选）： - -- `gameId` 或 `gameName` -- `dispatchMode`：`manual | auto` - -响应：分页 `items: Shop[]` - -`GET /v1/shops/{shopId}` - -响应：Shop - -### 6.3.1 创建店铺（计划内） - -`POST /v1/shops` - -- Auth：需要 -- 允许角色：`owner` - -请求： - -```json -{ - "name": "我的店铺", - "description": "店铺简介", - "banner": "https://cdn.../banner.png" -} -``` - -响应：Shop - -### 6.4 服务列表 / 详情 - -`GET /v1/services` - -查询参数（可选）： - -- `playerId` -- `shopId` -- `gameId` - -响应：分页 `items: PlayerService[]` - -`GET /v1/services/{serviceId}` - -响应：PlayerService - -### 6.5 服务管理（打手/店主） - -`POST /v1/services` - -- Auth：需要 -- 允许角色：`player`（创建自己的服务），`owner`（为自己店铺的员工创建服务） - -请求： - -```json -{ - "playerId": "u6", - "gameId": "g2", - "title": "王者双排稳上星", - "description": "描述", - "price": 18, - "unit": "星", - "rankRange": "钻石-星耀", - "availability": ["每天下午3点到凌晨"] -} -``` - -响应：PlayerService - -`PATCH /v1/services/{serviceId}`：更新服务 -`DELETE /v1/services/{serviceId}`：删除服务 - -### 6.6 店铺管理（店主） - -`GET /v1/shops/me` - -- Auth：需要 -- 允许角色：`owner` - -响应：Shop - -`PATCH /v1/shops/{shopId}` - -用于店铺规则、抽成、派单模式、公告等更新。建议服务端按字段做权限与范围校验。 - -请求示例（规则设置页）： - -```json -{ - "allowMultiShop": true, - "allowIndependentOrders": true, - "dispatchMode": "auto", - "commissionType": "percentage", - "commissionValue": 12 -} -``` - -请求示例（模板编辑页）： - -```json -{ - "templateConfig": { - "sections": [ - { "type": "intro", "enabled": true, "order": 1 }, - { "type": "players", "enabled": true, "order": 2 } - ] - } -} -``` - -请求示例（公告编辑）： - -```json -{ - "announcements": ["公告1", "公告2"] -} -``` - -响应：Shop - -### 6.7 员工邀请与店铺归属（计划内，替代直接改字段） - -演示前端当前通过直接修改 `player.shopId/shopName` 模拟邀请，真实后端建议改为显式的邀请与同意流。 - -`POST /v1/shops/{shopId}/employee-invitations` - -请求： - -```json -{ "playerId": "u7", "message": "欢迎加入" } -``` - -响应： - -```json -{ - "id": "inv-1", - "shopId": "shop1", - "playerId": "u7", - "status": "pending", - "createdAt": "..." -} -``` - -`GET /v1/employee-invitations/me`：当前用户收到的邀请 -`POST /v1/employee-invitations/{invitationId}/accept`：接受邀请 -`POST /v1/employee-invitations/{invitationId}/reject`：拒绝邀请 - -店铺员工列表与移除（店主）： - -- `GET /v1/shops/{shopId}/employees` -- `DELETE /v1/shops/{shopId}/employees/{playerId}` - -移除建议约束： - -- 存在进行中订单时，服务端可拒绝移除并返回 `INVALID_STATUS` 或 `VALIDATION_FAILED` -- 移除行为建议记录审计字段（操作者、原因、时间） - -服务端校验建议： - -- `allowMultiShop=false` 时，禁止玩家同时存在多个有效 shop 归属 -- `allowIndependentOrders=false` 时，玩家只能接本店订单（见 7.6） - -## 7. 订单 - -### 7.1 订单列表 - -`GET /v1/orders` - -查询参数（可选）： - -- `status`（可重复）：例如 `status=pending_accept&status=in_progress` -- `asRole`：`consumer | player | owner`（等价于 `X-Actor-Role`，二选一） -- `shopId`：店主视角下可选 - -响应：分页 `items: Order[]` - -权限： - -- consumer：仅可见自己下的单 -- player：仅可见自己作为打手的单 -- owner：仅可见自己店铺的单 - -### 7.2 订单详情 - -`GET /v1/orders/{orderId}` - -响应：Order - -### 7.3 下单与支付 - -`POST /v1/orders` - -- Auth：需要（consumer 视角） - -请求： - -```json -{ - "serviceId": "s4", - "quantity": 3, - "note": "3星，我用鲁班", - "payNow": true, - "paymentMethod": "wallet" -} -``` - -响应：Order（创建成功时建议直接返回 `pending_accept` 状态） - -### 7.4 订单动作（状态机） - -以下接口建议返回更新后的 Order。 - -`POST /v1/orders/{orderId}/pay` -`POST /v1/orders/{orderId}/accept` -`POST /v1/orders/{orderId}/close/request` -`POST /v1/orders/{orderId}/close/confirm` -`POST /v1/orders/{orderId}/cancel` - -状态约束建议与演示状态机一致（见 7.5）。 - -### 7.5 状态机（与前端演示一致） - -订单状态： - -- `pending_payment` → `pending_accept` → `in_progress` → `pending_close` → `pending_review` → `completed` -- 取消：`pending_payment | pending_accept` → `cancelled` -- 争议：`in_progress | pending_close` → `disputed` →（店主/平台处理）→ `pending_review` - -动作与允许迁移： - -- `PAY`：`pending_payment` → `pending_accept` -- `ACCEPT`：`pending_accept` → `in_progress` -- `REQUEST_CLOSE`：`in_progress` → `pending_close` -- `CONFIRM_CLOSE`：`pending_close` → `pending_review`（或超时自动进入） -- `CANCEL_PRE_ACCEPT`：`pending_payment | pending_accept` → `cancelled`（已扣款场景需退款） -- `OPEN_DISPUTE`：`in_progress | pending_close` → `disputed` -- `RESOLVE_DISPUTE`：`disputed` → `pending_review` -- `SUBMIT_REVIEW`：`pending_review` → `completed`（双方评价均提交后揭晓） - -### 7.6 店铺规则在订单侧的执行（计划内） - -当玩家已挂靠店铺且 `allowIndependentOrders=false` 时： - -- 玩家不得接店铺外的独立订单 -- 服务的可见范围建议由服务端控制（例如只暴露店铺内服务） - -当 `dispatchMode=auto` 时： - -- 接单动作可由服务端自动分配给某位员工，并记录分配原因与时间 - -## 8. 评价（密封机制） - -### 8.1 按订单查看评价 - -`GET /v1/orders/{orderId}/reviews` - -响应：分页 `items: Review[]` - -约束建议： - -- `sealed=true` 且双方未同时提交时，对非作者隐藏 `content`（可返回空字符串或省略字段） - -### 8.2 提交评价 - -`POST /v1/orders/{orderId}/reviews` - -请求： - -```json -{ "rating": 5, "content": "体验很好" } -``` - -响应： - -```json -{ "ok": true } -``` - -### 8.3 按打手查看评价 - -`GET /v1/users/{userId}/reviews` - -查询参数（可选）： - -- `targetRole=player` - -响应：分页 `items: Review[]` - -## 9. 争议 - -### 9.1 发起争议 - -`POST /v1/orders/{orderId}/dispute` - -请求： - -```json -{ - "reason": "争议原因", - "evidence": ["https://cdn.../a.png"] -} -``` - -响应：Dispute（详情态） - -### 9.2 获取争议详情 - -`GET /v1/orders/{orderId}/dispute` - -响应：Dispute（详情态） - -### 9.3 提交回应材料 - -`POST /v1/disputes/{disputeId}/response` - -请求： - -```json -{ - "reason": "回应理由", - "evidence": ["https://cdn.../b.png"] -} -``` - -响应： - -```json -{ "ok": true } -``` - -### 9.4 提交申诉 - -`POST /v1/disputes/{disputeId}/appeal` - -请求： - -```json -{ "reason": "申诉理由" } -``` - -响应： - -```json -{ "ok": true } -``` - -### 9.5 仲裁（店主/平台） - -演示前端用定时器自动推进争议状态。真实后端建议提供显式仲裁接口，并落审计字段。 - -`POST /v1/disputes/{disputeId}/resolve` - -请求： - -```json -{ - "result": "partial_refund", - "refundAmount": 10, - "note": "处理说明" -} -``` - -响应：Dispute（详情态） - -### 9.6 争议列表（店主/平台） - -`GET /v1/disputes` - -查询参数（可选）： - -- `status=open | reviewing | resolved | appealed` - -响应：分页 `items: Dispute（详情态或摘要态）[]` - -## 10. 社区（帖子/评论/点赞/置顶） - -### 10.1 帖子列表 - -`GET /v1/posts` - -查询参数（可选）： - -- `authorId` -- `tag`（可重复） -- `sort=latest | hot` - -响应：分页 `items: Post[]` - -### 10.2 帖子详情 - -`GET /v1/posts/{postId}` - -响应：Post - -### 10.3 发帖 - -`POST /v1/posts` - -请求： - -```json -{ - "title": "标题", - "content": "内容", - "images": ["https://cdn.../p1.png"], - "tags": ["英雄联盟", "攻略"], - "linkedOrderId": "ord-1", - "quotedPostId": "post-1" -} -``` - -约束建议： - -- `linkedOrderId` 仅允许 consumer 且订单已完成 -- `quotedPostId` 必须存在，且引用关系不应形成环 - -响应：Post - -### 10.4 点赞（帖子） - -`PUT /v1/posts/{postId}/like`：点赞（幂等） -`DELETE /v1/posts/{postId}/like`：取消点赞（幂等） - -响应： - -```json -{ "ok": true } -``` - -### 10.5 置顶（计划内） - -`PUT /v1/posts/{postId}/pin`：作者置顶（建议限制每人最多 N 条） -`DELETE /v1/posts/{postId}/pin`：取消置顶 - -响应： - -```json -{ "ok": true } -``` - -### 10.6 评论列表与发表评论 - -`GET /v1/posts/{postId}/comments`：分页评论列表 - -`POST /v1/posts/{postId}/comments` - -请求： - -```json -{ "content": "评论内容" } -``` - -响应：Comment - -### 10.7 点赞（评论） - -`PUT /v1/comments/{commentId}/like` -`DELETE /v1/comments/{commentId}/like` - -响应： - -```json -{ "ok": true } -``` - -## 11. 收藏（关注） - -演示前端以 Favorite 表达收藏打手或店铺。后端建议以当前用户为主语管理收藏关系。 - -### 11.1 获取我的收藏 - -`GET /v1/favorites/me` - -查询参数（可选）： - -- `targetType=player | shop` - -响应：分页 `items: Favorite[]` - -### 11.2 收藏与取消收藏 - -`PUT /v1/favorites/{targetType}/{targetId}`：收藏（幂等） -`DELETE /v1/favorites/{targetType}/{targetId}`：取消收藏（幂等） - -响应： - -```json -{ "ok": true } -``` - -### 11.3 获取某用户的公开收藏（可选） - -`GET /v1/users/{userId}/favorites` - -约束建议： - -- 默认仅允许本人读取 -- 若产品需要公开展示，可增加用户侧开关并在此接口执行隐私校验 - -## 12. 通知 - -### 12.1 通知列表 - -`GET /v1/notifications` - -查询参数（可选）： - -- `type=order | community | system` -- `unreadOnly=1` - -响应：分页 `items: Notification[]` - -### 12.2 标记已读 - -`POST /v1/notifications/{notificationId}/read` -`POST /v1/notifications/read-all` - -响应： - -```json -{ "ok": true } -``` - -### 12.3 Web Push 订阅（计划内） - -`POST /v1/push/subscriptions` - -请求（示例，按 Web Push 标准字段落地）： - -```json -{ - "endpoint": "https://push.service/...", - "keys": { "p256dh": "...", "auth": "..." }, - "userAgent": "..." -} -``` - -响应： - -```json -{ "id": "push-1", "ok": true } -``` - -`DELETE /v1/push/subscriptions/{subscriptionId}` - -## 13. 钱包与交易 - -### 13.1 获取钱包信息 - -`GET /v1/wallets/me` - -响应示例： - -```json -{ - "consumerBalance": 275, - "earningsBalance": 0 -} -``` - -### 13.2 交易流水 - -`GET /v1/wallets/me/transactions` - -查询参数（可选）： - -- `type=topup | payment | income | withdrawal | refund` -- `shopId`：按店铺过滤（店主视角） -- `orderId`：按订单过滤 - -响应：分页 `items: WalletTransaction[]` - -建议在 WalletTransaction 中补充结构化字段，替代前端演示中的 description 解析： - -```json -{ - "id": "tx-1", - "type": "payment", - "amount": -54, - "orderId": "ord-1", - "shopId": "shop2", - "description": "支付订单 ord-1", - "createdAt": "..." -} -``` - -### 13.3 充值（计划内真实支付） - -`POST /v1/wallets/me/topups` - -请求： - -```json -{ "amount": 100, "channel": "mock" } -``` - -响应： - -```json -{ "ok": true, "transactionId": "tx-1" } -``` - -### 13.4 提现 - -`POST /v1/wallets/me/withdrawals` - -请求： - -```json -{ "amount": 320, "destination": { "type": "bank_card", "maskedNo": "****1234" } } -``` - -响应： - -```json -{ "ok": true, "transactionId": "tx-2" } -``` - -## 14. 搜索 - -演示项目唯一的 HTTP 链路是 `/api/search`。真实后端建议提供等价能力，并保留相同查询语义，便于迁移。 - -`GET /v1/search` - -查询参数： - -- `q`：关键词 -- `game`：可重复，游戏名或 id（建议最终统一为 id） -- `min`/`max`：价格区间（字符串或数字均可，推荐数字） -- `online=1`：仅在线 -- `minRating`：最低评分 -- `sort`：`composite | rating | orders | price_asc | price_desc` -- `limit`/`offset` - -响应（与前端 `SearchResponse` 对齐）： - -```json -{ - "items": [ - { - "type": "player", - "player": { "id": "u5", "user": { "id": "u5", "nickname": "俊俊", "avatar": "", "username": "", "role": "player", "createdAt": "..." }, "rating": 4.2, "totalOrders": 156, "completionRate": 0.94, "status": "available", "games": ["英雄联盟"], "services": [], "tags": [] }, - "minPrice": 25, - "unit": "局", - "rating": 4.2, - "orders": 156 - }, - { - "type": "shop", - "shop": { "id": "shop1", "owner": { "id": "u10", "nickname": "老王", "avatar": "", "username": "", "role": "owner", "createdAt": "..." }, "name": "老王游戏工作室", "description": "店铺简介", "rating": 4.7, "totalOrders": 3842, "playerCount": 14, "commissionType": "percentage", "commissionValue": 15, "allowMultiShop": false, "allowIndependentOrders": false, "dispatchMode": "manual", "announcements": [], "templateConfig": { "sections": [] } }, - "minPrice": 25, - "unit": "局", - "rating": 4.7, - "orders": 3842, - "games": ["英雄联盟", "王者荣耀"], - "hasAvailable": true - } - ], - "meta": { "total": 2, "offset": 0, "limit": 12 } -} -``` - -## 15. 聊天 - -演示计划提到 WebSocket + 持久化。真实后端建议提供 REST 用于会话与历史消息，WebSocket 用于实时收发。 - -### 15.1 会话列表 - -`GET /v1/chat/sessions` - -响应：分页 `items: ChatSession[]` - -服务端必须按当前用户过滤会话参与者，避免返回无关会话。 - -### 15.2 会话消息 - -`GET /v1/chat/sessions/{sessionId}/messages` - -响应：分页 `items: ChatMessage[]` - -### 15.3 发送消息（HTTP 兜底） - -`POST /v1/chat/sessions/{sessionId}/messages` - -请求： - -```json -{ "type": "text", "content": "你好" } -``` - -或： - -```json -{ "type": "image", "content": "https://cdn.../img.png" } -``` - -响应：ChatMessage - -### 15.4 咨询会话（计划内） - -`POST /v1/chat/sessions` - -请求： - -```json -{ "type": "consultation", "targetUserId": "u5" } -``` - -响应：ChatSession - -### 15.5 WebSocket（建议） - -`GET /v1/ws/chat`（升级为 WebSocket） - -- 鉴权：在 query 或 headers 里携带 access token -- 服务端按 sessionId 与 participant 校验收发权限