yml2213
3631e70321
- 新增 order_checkouts 表，支持结账明细（消耗/押金扣除/退回/号主入账） - 租客发起结账 → 号主确认 → 已完成（正常路径） - 号主修改结账 → 租客确认修正 → 已完成（修正路径） - 结账阶段任一方发起争议 → 后台仲裁 → 已完成/已关闭/异常（争议路径） - 争议模块适配结账争议类型，仲裁结果新增 mark_abnormal - 超时任务适配新的 pending_checkout_confirm 状态 - 前端结账明细面板、发起结账/确认/修正/拒绝表单全部实现 - 移除旧的 SubmitReturn/ConfirmReturn 接口
192 lines
13 KiB
Markdown
192 lines
13 KiB
Markdown
# 业务规则
|
||
|
||
业务规则以 [项目计划](project-plan.md) 为准。
|
||
|
||
一期关键边界：
|
||
|
||
- 哈夫币是游戏账号内资产，不是平台币。
|
||
- 哈夫币数量由号主手动填报，订单创建时生成账号资产快照。
|
||
- 平台不保存游戏账号密码，不代收验证码，不绕过游戏安全机制。
|
||
- 账号交接采用号主手动交接。
|
||
- 资金先做账务模型，不直接接真实支付和提现。
|
||
- 押金、交接超时、归还超时、短信限流等阈值进入系统配置。
|
||
|
||
## 开发态实名认证
|
||
|
||
- 当前实现为 mock 实名服务。
|
||
- 提交合法姓名和 18 位身份证号后直接通过认证。
|
||
- 后端只返回脱敏姓名和脱敏证件号。
|
||
- 用户表 `realname_status` 会同步更新为 `verified`。
|
||
- 后续接入阿里云或腾讯云实名服务时，保持 `POST /api/realname/start` 和 `GET /api/realname/status` 的业务语义不变。
|
||
|
||
## 开发态租号发布
|
||
|
||
- 发布租号前必须登录并完成实名认证。
|
||
- 一期创建发布时同时创建 `game_accounts` 和 `rental_listings`。
|
||
- 哈夫币数量是号主手动填报值，不代表实时值。
|
||
- 号主可上传账号资产截图，地址保存在 `game_accounts.screenshot_urls`，最多保留 12 个。
|
||
- 当前提交审核会进入 `review_status = pending`，由后台商品审核通过后才上架。
|
||
- 后台审核通过后，发布状态变为 `published`，审核状态变为 `approved`，账号状态变为 `published`。
|
||
- 后台审核拒绝后，发布保留为草稿，审核状态变为 `rejected`，拒绝原因写入 `review_reason`。
|
||
- 公开列表只展示 `status = published` 且 `review_status = approved` 的发布。
|
||
|
||
## 开发态订单创建
|
||
|
||
- 创建订单需要登录。
|
||
- 一期创建订单暂不接真实支付和押金冻结，创建成功后直接进入 `pending_handoff`。
|
||
- 创建订单时会在数据库事务内锁定发布和账号，防止同一账号重复出租。
|
||
- 创建订单时生成 `account_snapshot`，记录下单时账号资产状态。
|
||
- 订单创建后发布状态变为 `rented`，不再出现在公开租号列表。
|
||
- 待交接订单可以由租客取消，取消后发布状态恢复为 `published`。
|
||
|
||
## 开发态账号交接
|
||
|
||
- 创建订单后状态为 `pending_handoff`，交接状态为 `pending_owner`。
|
||
- 只有号主可以提交交接说明。
|
||
- 号主提交交接说明后，交接状态变为 `pending_renter_confirm`。
|
||
- 只有租客可以确认收号。
|
||
- 租客确认收号后，订单状态变为 `renting`，交接状态变为 `received`。
|
||
- 确认收号时会重新计算租赁开始时间和结束时间。
|
||
- 交接记录保存在 `handoff_records`，订单双方都可以查看。
|
||
|
||
## 开发态结账与完成
|
||
|
||
- 租赁中订单可以由租客发起结账，填写使用结束说明、消耗金额、哈夫币消耗量、其他扣款和证据链接。
|
||
- 逾期中订单仍允许租客发起结账，但后台和号主可以根据逾期情况发起申诉或客服处理。
|
||
- 租客发起结账后，订单状态变为 `pending_checkout_confirm`，交接状态变为 `pending_owner_checkout`。
|
||
- 只有号主可以确认结账或修改结账。
|
||
- 号主直接确认结账后，订单状态变为 `completed`，交接状态变为 `returned`，结算状态标记为 `settled`。
|
||
- 号主修改结账后，订单状态变为 `pending_checkout_accept`，交接状态变为 `pending_renter_checkout`，必须等待租客确认修正。
|
||
- 待号主确认结账或待租客确认修正时，任一方都可以发起结账争议。
|
||
- 结账争议后订单状态变为 `checkout_disputing`，交接状态变为 `checkout_disputed`，由客服仲裁。
|
||
- 订单完成后，账号和发布状态恢复为 `published`。
|
||
- 当前会生成开发态模拟钱包流水，不代表真实支付或提现。
|
||
|
||
## 开发态超时任务
|
||
|
||
- 后端启动后会运行订单超时扫描任务，默认每 1 分钟执行一次。
|
||
- 任务从 `system_configs` 读取超时阈值，包括号主待交接、租客确认收号、租客结账宽限和号主确认结账。
|
||
- 号主待交接超时：订单保持 `pending_handoff`，交接状态变为 `owner_timeout`，租客仍可取消订单或发起申诉。
|
||
- 租客确认收号超时：订单状态变为 `abnormal`，交接状态变为 `renter_confirm_timeout`，进入客服介入。
|
||
- 租客逾期未结账：订单状态变为 `overdue`，交接状态变为 `return_overdue`，租客仍可发起结账，号主可发起申诉。
|
||
- 号主确认结账超时：订单状态变为 `abnormal`，交接状态变为 `owner_checkout_confirm_timeout`，进入客服复核。
|
||
- 每个超时动作只推进一次状态，避免重复通知。
|
||
- 超时动作会给相关用户写入站内信，并以 `system` 身份写入 `audit_logs`。
|
||
|
||
## 开发态文件上传
|
||
|
||
- 文件上传接口为 `/api/files/upload`，文件访问接口为 `/api/files/object`。
|
||
- 开发环境使用 MinIO，配置项包括 `STORAGE_ENDPOINT`、`STORAGE_BUCKET`、`STORAGE_ACCESS_KEY_ID` 和 `STORAGE_SECRET_ACCESS_KEY`。
|
||
- 当前支持上传 10MB 内的 JPG、PNG、WebP 和 PDF。
|
||
- 上传场景包括账号截图、交接附件、申诉证据、实名回执引用和头像等。
|
||
- 账号资产截图已接入发布页面，商品审核和商品详情后台可通过后台文件代理查看。
|
||
- 申诉证据已在订单详情页接入上传，上传成功后会把文件访问地址追加到证据列表。
|
||
- 文件访问通过后端代理读取私有对象，后续接 OSS/COS 时保持业务接口不变。
|
||
|
||
## 开发态钱包账务
|
||
|
||
- 钱包账务当前为模拟流水，不代表真实支付、充值或提现。
|
||
- 创建订单时为租客生成一笔冻结流水，金额为租金加押金。
|
||
- 取消待交接订单时释放租客冻结金额。
|
||
- 订单完成时释放租客冻结金额，给号主生成租金入账流水，并给租客生成押金退回流水。
|
||
- 每笔流水记录 `balance_after`，用于后续对账。
|
||
- 后台资金流水接口为 `/api/admin/wallet/ledger`，前端页面为 `/admin/wallet-ledger`。
|
||
- 后台可按用户、订单和业务类型查看最近流水，用于客服核对押金、租金、释放和结算记录。
|
||
- 后续接入真实支付后，需要把模拟冻结替换为支付成功后的真实冻结。
|
||
|
||
## 开发态站内信
|
||
|
||
- 订单创建后通知号主和租客。
|
||
- 租客取消订单后通知号主和租客。
|
||
- 号主提交交接说明后通知租客。
|
||
- 租客确认收号后通知号主。
|
||
- 租客发起结账后通知号主。
|
||
- 号主确认结账后通知号主和租客。
|
||
- 号主修改结账后通知租客。
|
||
- 租客拒绝修正结账后通知双方并进入争议。
|
||
- 发起申诉后通知对方和发起人。
|
||
- 仲裁完成后通知号主和租客。
|
||
- 站内信支持列表查询和标记已读。
|
||
|
||
## 开发态申诉仲裁
|
||
|
||
- 订单双方都可以在非终态订单发起申诉。
|
||
- 同一个订单同一时间只允许存在一个 `open` 或 `processing` 申诉。
|
||
- 发起普通申诉后订单状态变为 `disputing`，发起结账争议后订单状态变为 `checkout_disputing`，账号和发布保持锁定。
|
||
- 开发态后台仲裁接口为 `/api/admin/disputes`，当前只要求登录，后续接后台管理员和 RBAC。
|
||
- 仲裁会释放开发态模拟冻结金额，并根据结果生成钱包流水。
|
||
- 全额退款：释放冻结金额后，将租金加押金作为可用余额退给租客，订单置为 `closed`。
|
||
- 部分退款：需要填写退给租客的金额，剩余冻结金额结算给号主，订单置为 `closed`。
|
||
- 释放押金：租金结算给号主，押金退给租客，订单置为 `completed`。
|
||
- 扣押金/赔付号主：可填写从押金中赔付给号主的金额；不填默认处理全额押金，订单置为 `completed`。
|
||
- 关闭订单：只释放冻结金额，不产生可用余额结算，订单置为 `closed`，关联商品和账号下架。
|
||
- 仲裁完成会写入 `audit_logs`，记录裁决结果、金额、订单状态和资金处理。
|
||
- 当前仍是开发态模拟账务，不代表真实退款、扣款或提现；接入真实支付后需要替换为支付渠道退款、分账和对账逻辑。
|
||
|
||
## 开发态系统配置
|
||
|
||
- 系统配置接口为 `/api/admin/system-configs`。
|
||
- 首次查询会自动补齐一组默认配置，包括交接超时、归还确认超时、短信限流、最低押金、实名下单开关、平台抽成和提现门槛。
|
||
- 更新配置会写入 `audit_logs`，记录操作人、配置项、修改前值和修改后值。
|
||
- 当前后台接口已使用独立管理员登录和后台 JWT；后续接入角色和权限后再限制可操作配置项。
|
||
|
||
## 开发态后台登录
|
||
|
||
- 后台登录接口为 `/api/admin/auth/login`，前端页面为 `/admin/login`。
|
||
- 后台页面使用独立管理布局，不再混用用户端侧边栏。
|
||
- 后台登录前必须先请求 `/api/admin/auth/captcha` 获取图形验证码。
|
||
- 图形验证码为后端生成的 SVG，验证码答案保存在 Redis，默认 3 分钟过期，校验后立即删除。
|
||
- 后台 JWT 与普通用户 JWT 区分 `admin` 和 `user`，普通用户 Token 不能访问 `/api/admin/*`。
|
||
- 开发态首次后台登录会自动初始化默认管理员：用户名 `admin`，密码 `admin123456`。
|
||
- 默认管理员只用于本地开发；正式部署前必须改为初始化脚本、强密码和管理员密码修改流程。
|
||
|
||
## 开发态后台仪表盘
|
||
|
||
- 后台仪表盘接口为 `/api/admin/dashboard`，前端页面为 `/admin/dashboard`。
|
||
- 当前统计用户数、实名用户数、商品数、上架数、订单数、租赁中订单、今日订单、今日钱包流水。
|
||
- 待处理事项包括待审核商品、待仲裁申诉、待交接订单和待结账确认订单。
|
||
- 最近订单和最近申诉用于运营快速定位问题，后续接入后台订单管理和商品审核后再跳转到对应详情页。
|
||
|
||
## 开发态用户管理
|
||
|
||
- 用户管理接口为 `/api/admin/users`，前端页面为 `/admin/users`。
|
||
- 后台可查看用户手机号、实名状态、风险状态、信用分、订单数、发布数和申诉数。
|
||
- 冻结用户会将 `users.status` 改为 `frozen`，`risk_status` 改为 `frozen`，被冻结用户不能继续登录。
|
||
- 解冻用户会将 `users.status` 改为 `active`，`risk_status` 改为 `normal`。
|
||
- 冻结和解冻都会写入 `audit_logs`，记录管理员、用户、前后状态和原因。
|
||
|
||
## 开发态订单管理
|
||
|
||
- 订单管理接口为 `/api/admin/orders`，前端页面为 `/admin/orders`。
|
||
- 后台可查看全量订单、租客、号主、订单状态、交接状态、结算状态、租金和押金。
|
||
- 订单详情页 `/admin/orders/:id` 展示订单状态、双方用户、租期、交接记录和账号资产快照。
|
||
- 高风险客服操作集中放在订单详情页处理，必须填写原因并写入审计日志。
|
||
|
||
## 开发态商品管理
|
||
|
||
- 商品管理接口为 `/api/admin/listings`，前端页面为 `/admin/listings`。
|
||
- 后台可查看全量商品、号主、账号 ID、区服、平台、段位、哈夫币、时租、押金、商品状态和审核状态。
|
||
- 当前支持按号主 ID、商品状态、审核状态和查询条数筛选。
|
||
- 商品详情页为 `/admin/listings/:id`，支持查看完整账号、价格、租期、审核信息和账号资产截图。
|
||
- 后台可对非租赁中的商品执行强制下架和标记异常。
|
||
- 强制下架会将商品和账号状态改为 `offline`，标记异常会将商品和账号状态改为 `abnormal`。
|
||
- 强制下架和标记异常必须填写原因，写入 `audit_logs`，并通知号主。
|
||
- 租赁中的商品暂不允许直接下架或标记异常，需要先处理关联订单。
|
||
|
||
## 开发态订单客服操作
|
||
|
||
- 订单详情页 `/admin/orders/:id` 支持客服关闭订单和标记异常。
|
||
- 已完成、已取消、已关闭订单为终态，不允许再次客服关闭或标记异常。
|
||
- 客服关闭订单会将订单状态改为 `closed`，交接状态改为 `admin_closed`，结算状态改为 `closed`。
|
||
- 客服关闭订单会释放开发态模拟冻结金额，并将关联商品和账号下架为 `offline`。
|
||
- 标记异常会将订单状态改为 `abnormal`，交接状态改为 `admin_abnormal`，关联商品和账号改为 `abnormal`。
|
||
- 客服关闭和标记异常必须填写原因，写入 `audit_logs`，并通知租客和号主。
|
||
- 当前不处理真实退款、扣款或赔付，真实支付接入后需要补充资金裁决逻辑。
|
||
|
||
## 开发态审计日志
|
||
|
||
- 审计日志接口为 `/api/admin/audit-logs`，前端页面为 `/admin/audit-logs`。
|
||
- 当前可查看管理员、操作动作、业务类型、业务 ID、IP、User-Agent、操作明细和创建时间。
|
||
- 当前已写入审计日志的动作包括系统配置创建/更新、用户冻结和用户解冻。
|
||
- 审计日志只做追加和只读查询，不提供后台删除或修改入口。
|