第 5 阶段：纠纷、通知与后台-1

docs/api.md

@@ -39,5 +39,16 @@ API 规划以 [项目计划](project-plan.md) 第 10 章为准。
 - `POST /api/orders/{id}/confirm-receive`
 - `POST /api/orders/{id}/return`
 - `POST /api/orders/{id}/confirm-return`
+- `POST /api/orders/{id}/dispute`
+- `GET /api/disputes`
+- `GET /api/disputes/{id}`
 - `GET /api/wallet/balance`
 - `GET /api/wallet/ledger`
+- `GET /api/notifications`
+- `POST /api/notifications/{id}/read`
+- `GET /api/admin/disputes`
+- `POST /api/admin/disputes/{id}/arbitrate`
+- `GET /api/admin/system-configs`
+- `PUT /api/admin/system-configs/{key}`
+
+说明：`/api/admin/*` 当前是开发态 mock 后台接口，只要求登录，后续接入后台管理员账号、RBAC 和 Casbin 权限后再收紧访问控制。

docs/business-rules.md

@@ -53,7 +53,7 @@
 - 只有号主可以确认归还。
 - 号主确认归还后，订单状态变为 `completed`，交接状态变为 `returned`，结算状态先标记为 `settled`。
 - 订单完成后，账号和发布状态恢复为 `published`。
-- 当前只做状态闭环，不生成真实钱包流水，资金流水后续接入。
+- 当前会生成开发态模拟钱包流水，不代表真实支付或提现。
 
 ## 开发态钱包账务
 
@@ -63,3 +63,32 @@
 - 订单完成时释放租客冻结金额，给号主生成租金入账流水，并给租客生成押金退回流水。
 - 每笔流水记录 `balance_after`，用于后续对账。
 - 后续接入真实支付后，需要把模拟冻结替换为支付成功后的真实冻结。
+
+## 开发态站内信
+
+- 订单创建后通知号主和租客。
+- 租客取消订单后通知号主和租客。
+- 号主提交交接说明后通知租客。
+- 租客确认收号后通知号主。
+- 租客提交归还后通知号主。
+- 号主确认归还后通知号主和租客。
+- 发起申诉后通知对方和发起人。
+- 仲裁完成后通知号主和租客。
+- 站内信支持列表查询和标记已读。
+
+## 开发态申诉仲裁
+
+- 订单双方都可以在非终态订单发起申诉。
+- 同一个订单同一时间只允许存在一个 `open` 或 `processing` 申诉。
+- 发起申诉后订单状态变为 `disputing`，账号和发布保持锁定。
+- 开发态后台仲裁接口为 `/api/admin/disputes`，当前只要求登录，后续接后台管理员和 RBAC。
+- 仲裁结果先只落状态和通知：全额退款、部分退款、关闭订单会将订单置为 `closed`；扣押金、释放押金、赔付号主会将订单置为 `completed`。
+- 仲裁完成后账号和发布恢复为 `published`。
+- 当前仲裁不做真实扣款、退款、赔付落账，后续接真实支付后再补资金流水和审计日志。
+
+## 开发态系统配置
+
+- 系统配置接口为 `/api/admin/system-configs`。
+- 首次查询会自动补齐一组默认配置，包括交接超时、归还确认超时、短信限流、最低押金、实名下单开关、平台抽成和提现门槛。
+- 更新配置会写入 `audit_logs`，记录操作人、配置项、修改前值和修改后值。
+- 当前后台接口仍是开发态 mock 权限，只要求登录；后续接入后台管理员、角色和权限后再限制可操作配置项。

docs/project-plan.md

@@ -621,12 +621,12 @@
 - `GET /admin/listings/pending`：待审核商品。
 - `POST /admin/listings/{id}/approve`：审核通过。
 - `POST /admin/listings/{id}/reject`：审核拒绝。
-- `GET /admin/orders`：订单列表。
-- `GET /admin/disputes`：纠纷列表。
-- `POST /admin/orders/{id}/arbitrate`：订单仲裁。
-- `GET /admin/wallet/ledger`：资金流水。
-- `GET /admin/system-configs`：系统配置列表。
-- `PUT /admin/system-configs/{key}`：更新系统配置。
+- `GET /api/admin/orders`：订单列表。
+- `GET /api/admin/disputes`：纠纷列表。
+- `POST /api/admin/disputes/{id}/arbitrate`：纠纷仲裁。
+- `GET /api/admin/wallet/ledger`：资金流水。
+- `GET /api/admin/system-configs`：系统配置列表。
+- `PUT /api/admin/system-configs/{key}`：更新系统配置。
 - `GET /admin/audit-logs`：审计日志。
 
 ## 11. 安全与风控