实现结账流程：替换旧归还逻辑为完整结账-修正-争议流程

- 新增 order_checkouts 表，支持结账明细（消耗/押金扣除/退回/号主入账） - 租客发起结账 → 号主确认 → 已完成（正常路径） - 号主修改结账 → 租客确认修正 → 已完成（修正路径） - 结账阶段任一方发起争议 → 后台仲裁 → 已完成/已关闭/异常（争议路径） - 争议模块适配结账争议类型，仲裁结果新增 mark_abnormal - 超时任务适配新的 pending_checkout_confirm 状态 - 前端结账明细面板、发起结账/确认/修正/拒绝表单全部实现 - 移除旧的 SubmitReturn/ConfirmReturn 接口
2026-05-24 02:17:36 +08:00
parent 25e5599e0a
commit 3631e70321
29 changed files with 991 additions and 197 deletions
@@ -7,7 +7,7 @@ API 规划以 [项目计划](project-plan.md) 第 10 章为准。
 - 认证：短信验证码、手机号登录、Token 刷新、退出登录。
 - 实名：发起认证、查询状态、服务回调。
 - 发布：创建、修改、提交审核、下架、列表、详情。
- 订单：创建、取消、确认收号、提交归还、确认归还、发起申诉。
+- 订单：创建、取消、确认收号、发起结账、确认结账、修改结账、确认/拒绝修正、发起申诉。
 - 交接：提交交接说明、查看交接记录。
 - 钱包：余额、流水、提现预留。
 - 通知：站内信列表、标记已读。
@@ -37,8 +37,10 @@ API 规划以 [项目计划](project-plan.md) 第 10 章为准。
 - `POST /api/orders/{id}/handoff`
 - `GET /api/orders/{id}/handoff-records`
 - `POST /api/orders/{id}/confirm-receive`
- `POST /api/orders/{id}/return`
- `POST /api/orders/{id}/confirm-return`
+- `POST /api/orders/{id}/checkout`
+- `POST /api/orders/{id}/checkout/confirm`
+- `POST /api/orders/{id}/checkout/counter`
+- `POST /api/orders/{id}/checkout/accept`
 - `POST /api/orders/{id}/dispute`
 - `GET /api/disputes`
 - `GET /api/disputes/{id}`
@@ -49,24 +49,27 @@
 - 确认收号时会重新计算租赁开始时间和结束时间。
 - 交接记录保存在 `handoff_records`，订单双方都可以查看。

-## 开发态归还与完成
+## 开发态结账与完成

- 租赁中订单可以由租客提交归还。
- 逾期中订单仍允许租客提交归还，但后台和号主可以根据逾期情况发起申诉或客服处理。
- 租客提交归还后，订单状态变为 `pending_return_confirm`，交接状态变为 `pending_owner_return_confirm`。
- 只有号主可以确认归还。
- 号主确认归还后，订单状态变为 `completed`，交接状态变为 `returned`，结算状态先标记为 `settled`。
+- 租赁中订单可以由租客发起结账，填写使用结束说明、消耗金额、哈夫币消耗量、其他扣款和证据链接。
+- 逾期中订单仍允许租客发起结账，但后台和号主可以根据逾期情况发起申诉或客服处理。
+- 租客发起结账后，订单状态变为 `pending_checkout_confirm`，交接状态变为 `pending_owner_checkout`。
+- 只有号主可以确认结账或修改结账。
+- 号主直接确认结账后，订单状态变为 `completed`，交接状态变为 `returned`，结算状态标记为 `settled`。
+- 号主修改结账后，订单状态变为 `pending_checkout_accept`，交接状态变为 `pending_renter_checkout`，必须等待租客确认修正。
+- 待号主确认结账或待租客确认修正时，任一方都可以发起结账争议。
+- 结账争议后订单状态变为 `checkout_disputing`，交接状态变为 `checkout_disputed`，由客服仲裁。
 - 订单完成后，账号和发布状态恢复为 `published`。
 - 当前会生成开发态模拟钱包流水，不代表真实支付或提现。

 ## 开发态超时任务

 - 后端启动后会运行订单超时扫描任务，默认每 1 分钟执行一次。
- 任务从 `system_configs` 读取超时阈值，包括号主待交接、租客确认收号、租客归还宽限和号主确认归还。
+- 任务从 `system_configs` 读取超时阈值，包括号主待交接、租客确认收号、租客结账宽限和号主确认结账。
 - 号主待交接超时：订单保持 `pending_handoff`，交接状态变为 `owner_timeout`，租客仍可取消订单或发起申诉。
 - 租客确认收号超时：订单状态变为 `abnormal`，交接状态变为 `renter_confirm_timeout`，进入客服介入。
- 租客逾期未归还：订单状态变为 `overdue`，交接状态变为 `return_overdue`，租客仍可提交归还，号主可发起申诉。
- 号主确认归还超时：订单状态变为 `abnormal`，交接状态变为 `owner_return_confirm_timeout`，进入客服复核。
+- 租客逾期未结账：订单状态变为 `overdue`，交接状态变为 `return_overdue`，租客仍可发起结账，号主可发起申诉。
+- 号主确认结账超时：订单状态变为 `abnormal`，交接状态变为 `owner_checkout_confirm_timeout`，进入客服复核。
 - 每个超时动作只推进一次状态，避免重复通知。
 - 超时动作会给相关用户写入站内信，并以 `system` 身份写入 `audit_logs`。

@@ -97,8 +100,10 @@
 - 租客取消订单后通知号主和租客。
 - 号主提交交接说明后通知租客。
 - 租客确认收号后通知号主。
- 租客提交归还后通知号主。
- 号主确认归还后通知号主和租客。
+- 租客发起结账后通知号主。
+- 号主确认结账后通知号主和租客。
+- 号主修改结账后通知租客。
+- 租客拒绝修正结账后通知双方并进入争议。
 - 发起申诉后通知对方和发起人。
 - 仲裁完成后通知号主和租客。
 - 站内信支持列表查询和标记已读。
@@ -107,7 +112,7 @@

 - 订单双方都可以在非终态订单发起申诉。
 - 同一个订单同一时间只允许存在一个 `open` 或 `processing` 申诉。
- 发起申诉后订单状态变为 `disputing`，账号和发布保持锁定。
+- 发起普通申诉后订单状态变为 `disputing`，发起结账争议后订单状态变为 `checkout_disputing`，账号和发布保持锁定。
 - 开发态后台仲裁接口为 `/api/admin/disputes`，当前只要求登录，后续接后台管理员和 RBAC。
 - 仲裁会释放开发态模拟冻结金额，并根据结果生成钱包流水。
 - 全额退款：释放冻结金额后，将租金加押金作为可用余额退给租客，订单置为 `closed`。
@@ -139,7 +144,7 @@

 - 后台仪表盘接口为 `/api/admin/dashboard`，前端页面为 `/admin/dashboard`。
 - 当前统计用户数、实名用户数、商品数、上架数、订单数、租赁中订单、今日订单、今日钱包流水。
- 待处理事项包括待审核商品、待仲裁申诉、待交接订单和待归还确认订单。
+- 待处理事项包括待审核商品、待仲裁申诉、待交接订单和待结账确认订单。
 - 最近订单和最近申诉用于运营快速定位问题，后续接入后台订单管理和商品审核后再跳转到对应详情页。

 ## 开发态用户管理
@@ -113,7 +113,7 @@

 - 租客选择商品和租期后创建订单。
 - 系统锁定商品库存，避免同一账号被重复出租。
- 订单流转覆盖待确认、待交接、租赁中、待归还确认、已完成、已取消、申诉中。
+- 订单流转覆盖待确认、待交接、租赁中、待号主确认结账、待租客确认修正、结账争议中、已完成、已取消、申诉中。

 钱包账务：

@@ -142,10 +142,10 @@
 2. 订单确认后，商品进入锁定状态，订单进入待交接。
 3. 号主在订单内提交交接说明，例如登录方式、注意事项、联系说明或外部交接备注。
 4. 租客确认收到账号后，订单进入租赁中，并记录租赁开始时间和预计结束时间。
-5. 租期即将结束时，系统通过站内信和短信提醒租客归还。
-6. 租客提交归还申请，上传必要的租后截图或说明。
-7. 号主确认账号状态无误后，订单进入结算。
-8. 如任一方对交接、使用、归还或资产变化有异议，订单进入申诉仲裁。
+5. 租期即将结束时，系统通过站内信和短信提醒租客完成使用并发起结账。
+6. 租客发起结账，填写使用结束说明、消耗金额、哈夫币消耗量和必要证据。
+7. 号主确认账号状态无误后直接完成结算，或修改结账金额后交由租客确认。
+8. 租客同意修正后订单完成；拒绝修正或任一方对交接、使用、结账、资产变化有异议时，订单进入申诉仲裁。

 回收边界：

@@ -158,8 +158,8 @@

 - 号主待交接超时：订单进入待交接后，默认 30 分钟未提交交接说明，租客可取消订单或发起申诉。
 - 租客确认收号超时：号主提交交接说明后，默认 30 分钟未确认收号，订单进入客服介入，不自动开始租期。
- 租客归还超时：超过租期结束时间仍未提交归还，系统提醒后进入逾期中，号主可发起申诉。
- 号主确认归还超时：租客提交归还后，默认 2 小时未确认，订单进入自动确认候选或客服复核。
+- 租客结账超时：超过租期结束时间仍未发起结账，系统提醒后进入逾期中，号主可发起申诉。
+- 号主确认结账超时：租客发起结账后，默认 2 小时未确认，订单进入客服复核。
 - 所有超时阈值必须进入 `system_configs` 管理，后台可调整。

 订单状态机：
@@ -173,12 +173,16 @@
 | 待交接     | 申诉中     | 租客/号主 | 交接争议或安全验证无法完成          |
 | 待收号确认 | 租赁中     | 租客      | 租客确认收到账号并可正常登录        |
 | 待收号确认 | 申诉中     | 租客/系统 | 租客确认超时、无法登录或描述不符    |
-| 租赁中     | 逾期中     | 系统      | 超过租期结束时间仍未提交归还        |
-| 租赁中     | 待归还确认 | 租客      | 租客提交归还和租后凭证              |
-| 逾期中     | 待归还确认 | 租客      | 租客补交归还申请                    |
+| 租赁中     | 逾期中     | 系统      | 超过租期结束时间仍未发起结账        |
+| 租赁中     | 待号主确认结账 | 租客  | 租客发起结账和租后凭证              |
+| 逾期中     | 待号主确认结账 | 租客  | 租客补交结账申请                    |
 | 逾期中     | 申诉中     | 号主/系统 | 逾期未归还或疑似资产损失            |
-| 待归还确认 | 已完成     | 号主/系统 | 号主确认归还，或超时后客服/系统确认 |
-| 待归还确认 | 申诉中     | 号主/租客 | 归还争议、资产损失或封号异常        |
+| 待号主确认结账 | 已完成 | 号主      | 号主确认结账                        |
+| 待号主确认结账 | 待租客确认修正 | 号主 | 号主修改结账金额                    |
+| 待租客确认修正 | 已完成 | 租客      | 租客同意修正结账                    |
+| 待号主确认结账 | 结账争议中 | 任一方    | 发起结账争议                        |
+| 待租客确认修正 | 结账争议中 | 任一方    | 发起结账争议                        |
+| 结账争议中 | 已完成/已关闭/异常 | 客服      | 后台仲裁                            |
 | 申诉中     | 已完成     | 客服      | 仲裁为正常完成或部分扣款后完成      |
 | 申诉中     | 已取消     | 客服      | 仲裁为订单取消和退款                |
 | 申诉中     | 已关闭     | 客服      | 仲裁为异常关闭、冻结用户或冻结商品  |
@@ -216,7 +220,7 @@
 结算规则：

 - 正常完成订单后，租金按平台抽成规则分账给号主。
- 押金在号主确认归还后释放给租客。
+- 押金在双方结账确认或客服仲裁后释放给租客。
 - 如发生资产损失、无法登录、封号或超时归还，可由客服仲裁后扣除部分或全部押金。
 - 如号主虚假描述、超时未交接或账号无法使用，可裁定全额或部分退款。
 - 仲裁导致的扣款、退款、赔付必须生成资金流水和审计日志。
@@ -281,8 +285,9 @@
 - 号主提交交接说明。
 - 租客确认收号。
 - 租期即将结束。
- 租客提交归还。
- 号主确认归还。
+- 租客发起结账。
+- 号主确认或修改结账。
+- 租客确认或拒绝修正结账。
 - 订单完成结算。
 - 发起申诉。
 - 仲裁结果。
@@ -592,8 +597,10 @@
 - `GET /api/orders/{id}`：订单详情。
 - `POST /api/orders/{id}/cancel`：取消订单。
 - `POST /api/orders/{id}/confirm-receive`：租客确认收号。
- `POST /api/orders/{id}/return`：租客提交归还。
- `POST /api/orders/{id}/confirm-return`：号主确认归还。
+- `POST /api/orders/{id}/checkout`：租客发起结账。
+- `POST /api/orders/{id}/checkout/confirm`：号主确认结账。
+- `POST /api/orders/{id}/checkout/counter`：号主修改结账。
+- `POST /api/orders/{id}/checkout/accept`：租客同意修正结账。
 - `POST /api/orders/{id}/dispute`：发起申诉。

 交接：
@@ -835,8 +842,8 @@ hfb_sys/
 - 实现订单账号资产快照。
 - 实现号主提交交接说明。
 - 实现租客确认收号。
- 实现租客提交归还、号主确认归还。
- 实现交接、确认收号、归还、确认归还的超时处理。
+- 实现租客发起结账、号主确认或修改结账、租客确认或拒绝修正结账。
+- 实现交接、确认收号、结账逾期、确认结账超时处理。
 - 实现钱包账户、押金冻结、租金流水、结算流水。
 - 预留支付和提现接口。

@@ -887,9 +894,9 @@ hfb_sys/
 - 商品草稿、待审核、已上架、已下架、审核拒绝状态流转正确。
 - 审核未通过商品不能下单。
 - 同一账号并发下单只能成功一单。
- 订单待交接、租赁中、待归还确认、已完成、申诉中状态流转正确。
+- 订单待交接、租赁中、待号主确认结账、待租客确认修正、结账争议中、已完成、申诉中状态流转正确。
 - 非法订单状态转换会被拒绝。
- 交接、收号、归还、确认归还超时会按配置触发取消、申诉、逾期或客服复核。
+- 交接、收号、结账逾期、确认结账超时会按配置触发取消、申诉、逾期或客服复核。
 - 押金冻结、释放、扣款、退款流水一致。
 - 每笔 `wallet_ledger` 正确记录 `balance_after`。
 - 租金、平台抽成、号主结算流水一致。