juwan/juwan-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
411ee8293d4c82e12f3e5091ffc2d7eeeec4f86a
juwan-frontend/接口文档.md
T
zetaloop 411ee8293d docs: align API doc with backend TypeB
2026-02-28 07:26:26 +08:00

37 KiB
Raw Blame History

聚玩 (Juwan) API 设计文档

1. 文档概述

本文档为“聚玩”游戏陪玩平台的后端 API 设计规范，旨在指导后端开发人员实现真实的 API 接口，以替换当前纯前端的 Mock 系统。

  • 基础路径 (Base URL): /api/v1
  • 数据格式: application/json

2. 全局约定

2.1 认证与授权 (Auth)

  • 采用 Cookie JToken 进行认证（Phase 2 接入后端时实现）。
  • Phase 1 阶段仅为纯前端 Mock，不涉及真实后端交互。
  • 接口权限标识：
    • 🔒：需要登录认证。
    • 🛡️：需要管理员权限。

2.2 错误响应格式

所有失败的请求均返回统一的 JSON 结构，并附带 HTTP 状态码（如 400, 401, 403, 404, 500）。

{
  "code": 401,
  "msg": "请先登录"
}

常见错误码 (code)：

  • 401: 未登录或 Token 失效
  • 403: 角色权限不足或非参与者
  • 404: 资源不存在
  • 400: 参数校验失败、状态不合法、重复请求等
  • 500: 服务器内部错误

2.3 分页规范

采用 offset 和 limit 进行分页（与前端 SearchResponse 保持一致）。 请求参数：?offset=0&limit=20 响应格式：

{
  "items": [...],
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

2.4 文件上传与访问

  • 上传端点: POST /api/v1/upload
  • Content-Type: multipart/form-data
  • 参数: file (文件), type (枚举: avatar, chat, post, verification, dispute)
  • 响应: 返回文件的 CDN URL 或文件 ID。
  • 访问端点: GET /api/v1/files/:fileId (获取文件内容)

2.5 时间戳格式

所有时间字段均采用 ISO 8601 格式的 UTC 时间字符串，例如：2024-03-20T12:00:00.000Z。

2.6 角色系统 (UserRole)

  • consumer: 普通消费者（老板）
  • player: 陪玩打手
  • owner: 店铺店长
  • admin: 平台管理员（隐藏角色，用于后台管理）

2.7 ID 规范

所有 ID 均由后端使用 Snowflake 算法生成，类型为 int64。在前端交互和 JSON 序列化时，统一作为 string 处理，以避免精度丢失。

3. 数据模型

3.1 User (用户)

字段 类型 说明
id string 用户唯一标识
username string 登录用户名
email string 邮箱地址 (可选)
nickname string 昵称
avatar string 头像 URL
role UserRole 当前激活的角色
verifiedRoles UserRole[] 已认证的角色列表
verificationStatus object 各角色的认证状态 (pending, approved, rejected)
bio string 个人简介 (可选)
createdAt string 注册时间

3.2 Game (游戏)

字段 类型 说明
id string 游戏 ID
name string 游戏名称
icon string 游戏图标 URL
category string 分类 (MOBA, FPS, 动作, RPG)

3.3 Player & PlayerService (打手与服务)

PlayerService:

字段 类型 说明
id string 服务 ID
playerId string 打手 ID
gameId string 游戏 ID
gameName string 游戏名称
title string 服务标题
description string 服务描述
price number 价格
unit string 计价单位 (局, 星, 次)
rankRange string 段位范围 (可选)
availability string[] 可接单时间段

Player:

字段 类型 说明
id string 打手 ID
user User 关联的用户信息
rating number 综合评分
totalOrders number 总接单数
completionRate number 完单率 (0-1)
status string 状态 (available, busy, offline)
games string[] 擅长游戏 ID 列表
services PlayerService[] 提供的服务列表
shopId string 所属店铺 ID (可选)
shopName string 所属店铺名称 (可选)
tags string[] 个人标签

3.4 Shop (店铺)

字段 类型 说明
id string 店铺 ID
owner User 店长信息
name string 店铺名称
banner string 店铺招牌图 (可选)
description string 店铺简介
rating number 综合评分
totalOrders number 总单量
playerCount number 打手数量
commissionType string 抽成方式 (fixed, percentage)
commissionValue number 抽成数值
allowMultiShop boolean 是否允许打手兼职
allowIndependentOrders boolean 是否允许打手私下接单
dispatchMode string 派单模式 (manual, auto)
announcements string[] 店铺公告列表
templateConfig object 店铺主页模板配置

3.5 Order (订单)

字段 类型 说明
id string 订单 ID
consumerId string 消费者 ID
consumerName string 消费者昵称
playerId string 打手 ID
playerName string 打手昵称
shopId string 店铺 ID (可选)
shopName string 店铺名称 (可选)
service PlayerService 购买的服务快照
status OrderStatus 订单状态
totalPrice number 订单总价
note string 备注 (可选)
createdAt string 创建时间
acceptedAt string 接单时间 (可选)
closedAt string 申请结算时间 (可选)
completedAt string 完成时间 (可选)

OrderStatus 枚举: pending_payment, pending_accept, in_progress, pending_close, pending_review, disputed, completed, cancelled

3.6 Review (评价)

字段 类型 说明
id string 评价 ID
orderId string 关联订单 ID
fromUserId string 评价人 ID
fromUserName string 评价人昵称
fromUserAvatar string 评价人头像
toUserId string 被评价人 ID
rating number 评分 (1-5)
content string 评价内容 (可选)
sealed boolean 是否处于密封状态（双方未互评前不可见）
createdAt string 评价时间

3.7 Dispute & DisputeRecord (争议)

字段 类型 说明
id string 争议 ID
orderId string 关联订单 ID
initiatorId string 发起人 ID
initiatorName string 发起人昵称
reason string 争议原因
evidence string[] 证据图片 URL 列表
status string 状态 (open, reviewing, resolved, appealed)
result string 仲裁结果 (full_refund, full_payment, partial_refund)
respondentReason string 被诉方回应理由 (可选)
respondentEvidence string[] 被诉方证据 (可选)
appealReason string 申诉理由 (可选)
appealedAt string 申诉时间 (可选)
timeline object[] 争议处理时间线
createdAt string 创建时间

3.8 ChatSession & ChatMessage (聊天)

ChatSession:

字段 类型 说明
id string 会话 ID
type string 会话类型 (order, consultation)
orderId string 关联订单 ID (仅 order 类型)
participants object[] 参与者列表 {id, name, avatar}
lastMessage string 最后一条消息内容
lastMessageAt string 最后一条消息时间
unreadCount number 未读消息数
readonly boolean 是否只读（如订单完成/咨询超时后）

ChatMessage:

字段 类型 说明
id string 消息 ID
sessionId string 会话 ID
senderId string 发送者 ID
senderName string 发送者昵称
senderAvatar string 发送者头像
type string 消息类型 (text, image, system)
content string 消息内容
createdAt string 发送时间

3.9 Post & Comment (社区)

Post:

字段 类型 说明
id string 帖子 ID
author User 作者信息
authorRole UserRole 作者发帖时的角色
title string 标题
content string 内容
images string[] 图片列表
tags string[] 标签列表
linkedOrderId string 关联的订单 ID (秀单帖)
quotedPostId string 引用的帖子 ID (引用帖)
likeCount number 点赞数
commentCount number 评论数
liked boolean 当前用户是否已赞
pinned boolean 是否被作者置顶
createdAt string 发布时间

Comment:

字段 类型 说明
id string 评论 ID
postId string 关联帖子 ID
author User 评论者信息
content string 评论内容
likeCount number 点赞数
liked boolean 当前用户是否已赞
createdAt string 评论时间

3.10 WalletTransaction (钱包流水)

字段 类型 说明
id string 流水 ID
type string 类型 (topup, payment, income, withdrawal, refund)
amount number 金额 (正数为收入/充值/退款，负数为支出/提现)
description string 描述
orderId string 关联订单 ID (可选，用于结构化统计，替代前端正则匹配)
createdAt string 发生时间

3.11 Favorite (收藏)

字段 类型 说明
id string 收藏 ID
userId string 用户 ID
targetType string 收藏目标类型 (player, shop)
targetId string 收藏目标 ID
createdAt string 收藏时间

3.12 Notification (通知)

字段 类型 说明
id string 通知 ID
type string 通知类型 (order, community, system)
title string 通知标题
content string 通知内容
read boolean 是否已读
link string 关联跳转链接 (可选)
createdAt string 通知时间

4. 认证与用户

方法 路径 权限 说明
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 🔒 切换当前激活角色
POST /users/me/verification 🔒 提交角色认证材料
GET /users/me/verification 🔒 获取认证状态
PUT /users/me/preferences/notifications 🔒 更新通知偏好设置
PUT /users/me/preferences/theme 🔒 更新主题偏好设置
GET /users/:id 获取指定用户信息
POST /users/:id/follow 🔒 关注用户
DELETE /users/:id/follow 🔒 取消关注用户

请求示例：登录

// POST /api/v1/auth/login
{
  "username": "zhangsan",
  "password": "..."
}

响应示例：登录成功

{
  "user": {
    "id": "u1",
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "nickname": "张三",
    "avatar": "https://cdn.juwan.com/avatars/u1.jpg",
    "role": "consumer",
    "verifiedRoles": ["consumer", "player"],
    "verificationStatus": { "consumer": "approved", "player": "approved" },
    "createdAt": "2024-01-15T08:00:00.000Z"
  }
}

请求示例：提交认证材料

// POST /api/v1/users/me/verification
{
  "role": "player",
  "materials": {
    "idCardFront": "https://cdn.juwan.com/uploads/xxx.jpg",
    "idCardBack": "https://cdn.juwan.com/uploads/yyy.jpg",
    "gameScreenshot": "https://cdn.juwan.com/uploads/zzz.jpg"
  }
}

请求示例：切换角色

// POST /api/v1/users/me/switch-role
{ "role": "player" }

请求示例：更新通知偏好

// PUT /api/v1/users/me/preferences/notifications
{ "order": true, "community": true, "system": false }

5. 游戏数据

方法 路径 权限 说明
GET /games 获取游戏列表 (支持分页)
GET /games/:id 获取指定游戏详情

6. 打手与服务

方法 路径 权限 说明
GET /players 获取打手列表 (支持分页、筛选)
GET /players/:id 获取打手公开主页详情
PUT /players/me/status 🔒 更新打手接单状态 (available, busy, offline)
GET /services 获取所有服务列表
GET /services/:id 获取服务详情
GET /players/:id/services 获取指定打手的服务列表
POST /services 🔒 创建服务 (仅 player)
PUT /services/:id 🔒 更新服务 (仅 player)
DELETE /services/:id 🔒 删除服务 (仅 player)

7. 店铺系统

方法 路径 权限 说明
GET /shops 获取店铺列表
GET /shops/:id 获取店铺公开主页详情
GET /users/:id/shop 获取指定店长的店铺
POST /shops 🔒 创建店铺 (仅 owner)
PUT /shops/:id 🔒 更新店铺基础信息及规则
PUT /shops/:id/template 🔒 更新店铺主页模板配置
PUT /shops/:id/announcements 🔒 更新店铺公告
POST /shops/:id/invitations 🔒 邀请打手加入店铺
POST /shops/invitations/:id/accept 🔒 打手接受店铺邀请
DELETE /shops/:id/players/:playerId 🔒 将打手移出店铺
GET /shops/:id/income-stats 🔒 获取店铺收入统计 (仅 owner)

| GET | /shops/mine | 🔒 | 获取当前登录店主的店铺详情 | | GET | /shops/:id/players | | 获取店铺下的打手列表 | | POST | /shops/:id/announcements | 🔒 | 新增店铺公告 | | DELETE | /shops/:id/announcements/:index | 🔒 | 删除店铺公告 | | DELETE | /shops/invitations/:id | 🔒 | 拒绝店铺邀请 (打手调用) |

请求示例：更新店铺规则

// PUT /api/v1/shops/:id
{
  "name": "星耀电竞工作室",
  "description": "专业英雄联盟代练工作室",
  "commissionType": "percentage",
  "commissionValue": 15,
  "allowMultiShop": false,
  "allowIndependentOrders": true,
  "dispatchMode": "auto"
}

请求示例：更新店铺模板

// PUT /api/v1/shops/:id/template
{
  "sections": [
    { "type": "banner", "enabled": true, "order": 0 },
    { "type": "intro", "enabled": true, "order": 1 },
    { "type": "services", "enabled": true, "order": 2 },
    { "type": "players", "enabled": true, "order": 3 },
    { "type": "announcements", "enabled": false, "order": 4 },
    { "type": "reviews", "enabled": true, "order": 5 }
  ]
}

响应示例：店铺收入统计

// GET /api/v1/shops/:id/income-stats
{
  "monthlyIncome": 12800.00,
  "pendingSettlement": 3200.00,
  "totalWithdrawn": 54000.00,
  "totalOrders": 156,
  "completedOrders": 142
}

8. 订单系统

8.1 订单状态机 (Order State Machine)

当前状态 触发动作 下一状态 允许的角色 副作用
pending_payment PAY pending_accept consumer CLEAR_TIMEOUT, SCHEDULE_TIMEOUT
pending_accept ACCEPT in_progress player, owner CLEAR_TIMEOUT, SYNC_CHAT_SESSION
pending_accept CANCEL_PRE_ACCEPT cancelled consumer CLEAR_TIMEOUT
pending_accept AUTO_TIMEOUT_PENDING_ACCEPT cancelled system CLEAR_TIMEOUT
in_progress REQUEST_CLOSE pending_close consumer, player CLEAR_TIMEOUT, SCHEDULE_TIMEOUT, SYNC_CHAT_SESSION
in_progress OPEN_DISPUTE disputed consumer, player CLEAR_TIMEOUT, SYNC_CHAT_SESSION
pending_close CONFIRM_CLOSE pending_review consumer, player CLEAR_TIMEOUT, SCHEDULE_TIMEOUT, SYNC_CHAT_SESSION
pending_close OPEN_DISPUTE disputed consumer, player CLEAR_TIMEOUT, SYNC_CHAT_SESSION
pending_close AUTO_TIMEOUT_PENDING_CLOSE pending_review system CLEAR_TIMEOUT, SCHEDULE_TIMEOUT, SYNC_CHAT_SESSION
pending_review SUBMIT_REVIEW completed consumer, player CLEAR_TIMEOUT, PAYOUT_INCOME, SYNC_CHAT_SESSION
pending_review AUTO_TIMEOUT_PENDING_REVIEW completed system CLEAR_TIMEOUT, PAYOUT_INCOME, SYNC_CHAT_SESSION
disputed RESOLVE_DISPUTE pending_review owner, admin CLEAR_TIMEOUT, SCHEDULE_TIMEOUT, SYNC_CHAT_SESSION

8.2 超时配置 (Timeout Configs)

后端需实现定时任务（如 Redis 延迟队列）来处理以下超时逻辑：

  • ORDER_ACCEPT_TIMEOUT_MS: 待接单超时自动取消（默认 5 分钟）。
  • ORDER_CLOSE_TIMEOUT_MS: 申请结算后对方未确认，超时自动进入待评价（默认 24 小时）。
  • ORDER_REVIEW_TIMEOUT_MS: 待评价超时自动好评并完成订单（默认 72 小时）。

8.3 订单接口

方法 路径 权限 说明
GET /orders 🔒 获取当前用户的订单列表
GET /orders/:id 🔒 获取订单详情
POST /orders 🔒 创建订单 (状态: pending_payment)
POST /orders/paid 🔒 创建并直接支付订单 (快捷下单)
POST /orders/:id/pay 🔒 支付订单 (PAY)
POST /orders/:id/accept 🔒 接单 (ACCEPT)
POST /orders/:id/request-close 🔒 申请结算 (REQUEST_CLOSE)
POST /orders/:id/confirm-close 🔒 确认结算 (CONFIRM_CLOSE)
POST /orders/:id/cancel 🔒 接单前取消 (CANCEL_PRE_ACCEPT)
POST /orders/:id/reorder 🔒 再来一单 (基于原订单快速创建新订单)
GET /orders 支持查询参数：role (consumer/player/owner)、status (状态过滤)、offset、limit。后端根据 Token 中的 userId 和 role 参数自动过滤，不允许查看他人订单。

请求示例：创建并支付订单 (快捷下单)

// POST /api/v1/orders/paid
{
  "playerId": "p1",
  "shopId": "shop1",
  "serviceId": "svc1",
  "quantity": 3,
  "note": "希望晚上8点后开始"
}

响应示例：订单创建成功

{
  "order": {
    "id": "ord-20240320-001",
    "consumerId": "u1",
    "consumerName": "张三",
    "playerId": "p1",
    "playerName": "小明",
    "shopId": "shop1",
    "shopName": "星耀电竞",
    "service": { "id": "svc1", "title": "英雄联盟代练", "price": 50, "unit": "局" },
    "status": "pending_accept",
    "totalPrice": 150,
    "createdAt": "2024-03-20T12:00:00.000Z"
  }
}

请求示例：再来一单

// POST /api/v1/orders/:id/reorder
// 无请求体，后端基于原订单的 playerId、serviceId、shopId 创建新订单

9. 争议仲裁

方法 路径 权限 说明
GET /disputes 🔒 获取当前用户的争议列表
GET /orders/:id/dispute 🔒 获取指定订单的争议详情
POST /orders/:id/dispute 🔒 发起争议 (OPEN_DISPUTE)
POST /disputes/:id/response 🔒 被诉方提交回应及证据
POST /disputes/:id/appeal 🔒 对仲裁结果发起申诉

争议处理时间线 (Timeline):

  • created: 争议发起
  • response: 被诉方回应
  • reviewing: 店长/平台介入审查
  • resolved: 给出仲裁结果
  • appealed: 发起申诉，转交平台管理员 请求示例：发起争议
// POST /api/v1/orders/:id/dispute
{
  "reason": "打手未按约定时间上线",
  "evidence": [
    "https://cdn.juwan.com/uploads/evidence1.jpg",
    "https://cdn.juwan.com/uploads/evidence2.jpg"
  ]
}

请求示例：被诉方回应

// POST /api/v1/disputes/:id/response
{
  "reason": "当时网络故障，已与客户沟通并补时",
  "evidence": ["https://cdn.juwan.com/uploads/response1.jpg"]
}

请求示例：申诉

// POST /api/v1/disputes/:id/appeal
{
  "reason": "仲裁结果不合理，请求平台复核"
}

10. 评价系统

密封机制 (Sealed Mechanics): 评价提交后默认为 sealed: true。只有当双方都完成评价，或者评价超时（ORDER_REVIEW_TIMEOUT_MS）后，评价才会解封并公开显示。

方法 路径 权限 说明
POST /orders/:id/review 🔒 提交评价 (SUBMIT_REVIEW)
GET /reviews 获取公开评价列表
GET /orders/:id/reviews 🔒 获取指定订单的评价（受密封机制限制）
GET /users/:id/reviews 获取指定用户收到的评价

11. 聊天系统

11.1 会话类型

  • order: 订单会话。随订单创建而建立，订单完成后变为只读。
  • consultation: 咨询会话。用户在下单前与打手沟通。24小时无回复自动关闭。可升级为订单会话。
方法 路径 权限 说明
GET /chat/sessions 🔒 获取当前用户的会话列表
GET /chat/sessions/:id 🔒 获取会话详情
GET /chat/sessions/:id/messages 🔒 获取会话历史消息 (分页)
POST /chat/sessions/order 🔒 确保订单会话存在 (不存在则创建)
POST /chat/sessions/consultation 🔒 创建咨询会话
POST /chat/sessions/:id/upgrade 🔒 将咨询会话升级为订单会话
POST /chat/sessions/:id/messages 🔒 发送消息 (文本/图片)
GET /shops/:id/chat-sessions 🔒 店长查看员工的业务会话 (需员工同意)

12. 社区系统

方法 路径 权限 说明
GET /posts 获取帖子列表 (支持分页、标签筛选)
GET /posts/:id 获取帖子详情
POST /posts 🔒 发布帖子 (支持普通帖、秀单帖、引用帖)
POST /posts/:id/like 🔒 点赞帖子
DELETE /posts/:id/like 🔒 取消点赞帖子
POST /posts/:id/pin 🔒 作者置顶帖子 (最多 N 条)
DELETE /posts/:id/pin 🔒 取消置顶
GET /posts/:id/comments 获取帖子评论列表
POST /posts/:id/comments 🔒 发表评论
POST /comments/:id/like 🔒 点赞评论
DELETE /comments/:id/like 🔒 取消点赞评论
GET /users/:id/posts 获取指定用户的帖子列表
GET /posts 支持查询参数：tags (标签过滤)、gameId (游戏过滤)、sortBy (new/hot)、offset、limit。
请求示例：发布秀单帖 
// POST /api/v1/posts
{
  "title": "超棒的代练体验",
  "content": "从银到铂金，只用了三天！",
  "images": ["https://cdn.juwan.com/uploads/post1.jpg"],
  "tags": ["英雄联盟", "代练"],
  "linkedOrderId": "ord-20240320-001"
}

13. 收藏与关注

方法 路径 权限 说明
GET /favorites 🔒 获取当前用户的收藏列表 (打手/店铺)
POST /favorites 🔒 添加收藏
DELETE /favorites/:id 🔒 取消收藏
GET /users/:id/favorites/check 🔒 检查是否已收藏指定目标
请求示例：添加收藏 
// POST /api/v1/favorites
{ "targetType": "player", "targetId": "p1" }

检查收藏状态

GET /api/v1/users/u1/favorites/check?targetType=player&targetId=p1
→ { "favorited": true }

14. 搜索与发现

方法 路径 权限 说明
GET /search 统一搜索接口

请求参数:

  • q: 搜索关键词
  • selectedGames: 游戏 ID 数组
  • min, max: 价格区间
  • onlyOnline: 是否仅看在线 (true/false)
  • minRating: 最低评分
  • sort: 排序方式 (composite, rating, orders, price_asc, price_desc)
  • offset, limit: 分页参数 | GET | /recommendations/home | | 首页推荐信息流 (混合打手与店铺卡片) | 响应示例：搜索结果
{
  "items": [
    {
      "type": "player",
      "player": { "id": "p1", "user": {...}, "rating": 4.8, "status": "available", ... },
      "minPrice": 30,
      "unit": "局",
      "rating": 4.8,
      "orders": 256
    },
    {
      "type": "shop",
      "shop": { "id": "shop1", "name": "星耀电竞", ... },
      "minPrice": 25,
      "unit": "局",
      "rating": 4.6,
      "orders": 1024,
      "games": ["英雄联盟", "CS2"],
      "hasAvailable": true
    }
  ],
  "meta": { "total": 42, "offset": 0, "limit": 12 }
}

15. 钱包与资金

15.1 收入计算公式 (Income Calculation)

订单完成后，系统根据店铺规则计算打手实际收入：

  • 无店铺 (独立接单): income = totalPrice
  • 比例抽成 (percentage): income = totalPrice * (1 - commissionValue / 100)
  • 固定抽成 (fixed): income = Math.max(0, totalPrice - commissionValue) 剩余部分作为店铺收入（若有店铺）。

15.2 钱包接口

方法 路径 权限 说明
GET /wallet/balance 🔒 获取当前余额
GET /wallet/transactions 🔒 获取资金流水 (包含结构化的 orderId)
POST /wallet/topup 🔒 充值
POST /wallet/withdraw 🔒 提现

16. 通知系统

方法 路径 权限 说明
GET /notifications 🔒 获取通知列表
PUT /notifications/:id/read 🔒 标记单条通知为已读
PUT /notifications/read-all 🔒 标记所有通知为已读
POST /notifications/push-subscription 🔒 订阅 Web Push 推送

17. 管理后台 (Admin)

方法 路径 权限 说明
GET /admin/verifications 🛡️ 获取待审核的认证申请
POST /admin/verifications/:id/approve 🛡️ 批准认证申请
POST /admin/verifications/:id/reject 🛡️ 拒绝认证申请
GET /admin/disputes 🛡️ 获取需要平台介入的争议列表
POST /admin/disputes/:id/resolve 🛡️ 平台管理员给出最终仲裁结果

18. WebSocket 事件

客户端连接到 wss://api.juwan.com/api/v1/ws，通过 JWT 鉴权。

下发事件类型:

  • chat:message: 收到新聊天消息。
  • order:status_changed: 订单状态变更（触发前端重新拉取订单详情）。
  • notification:new: 收到新系统通知。
  • dispute:updated: 争议状态或时间线更新。
  • wallet:balance_changed: 余额变动通知。

19. 安全与校验清单

  1. 数据隔离 (Data Isolation):
    • 用户只能查询自己的订单、钱包流水、私聊会话。
    • 店长只能查询本店铺的订单和员工数据。
  2. 并发控制 (Concurrency Control):
    • 订单状态流转必须使用乐观锁或数据库事务，防止并发导致状态机错乱。
    • 钱包扣款必须保证原子性，防止超扣。
  3. 权限校验 (Authorization):
    • 严格校验 Actor 的 role。例如，只有 player 才能创建服务，只有 owner 才能修改店铺规则。
    • 订单操作必须校验操作者是否为该订单的 consumerId、playerId 或关联的 shopId 的店长。
  4. 幂等性 (Idempotency):
    • 支付、接单、结算等核心操作必须保证幂等性，重复请求返回 IDEMPOTENT_NOOP。
Reference in New Issue View Git Blame Copy Permalink