# 结算后订单利润调整方案

## 1. 背景与目标

订单完成结算后，用户可能继续发生售后补偿、部分退款、号主收入修正等情况。需要在不破坏正式结算快照和历史资金流水的前提下，记录每次调整，并展示订单的最终实际收入和平台利润。

本方案针对正常租赁订单，提号订单已有类似实现，可复用其“追加调整流水”的思路。

## 2. 当前系统结算口径

- 正式结算基准使用最终结算记录 `order_checkouts` 的正式金额，不能使用发布价格、预计价格或订单初始价格。
- 号主正式收入为 `order_checkouts.owner_income_amount_cent`。
- 普通订单结算时通过 `wallet_ledger` 给号主入账。
- 平台代管订单结算时把待付号主金额记录在 `rental_orders.offline_settlement_amount_cent`。
- 订单过程留痕使用 `process_events`，管理员操作审计使用 `audit_logs`。
- 财务明细目前通过结算记录、号主钱包入账和平台代管线下结算金额计算平台净额。

相关代码：

- `backend/internal/modules/order/checkout_finalize.go`
- `backend/internal/modules/order/queries.go`
- `backend/internal/modules/adminfinance/detail.go`
- `backend/internal/model/order_checkout.go`
- `backend/internal/modules/pickup/repository.go`

## 3. 核心设计

不要修改原始结算记录、订单线下结算金额或已有钱包流水。新增不可变的订单财务调整流水：

```text
admin_order_financial_adjustments
```

建议字段：

```text
id
order_id
adjustment_no                 唯一调整单号，用于幂等
settlement_mode               owner_wallet / platform_managed
owner_income_delta_cent       号主收入调整，可正可负
renter_compensation_cent      本次租客补偿金额
compensation_bearer           platform / owner
platform_profit_delta_cent    系统计算的利润变化，不允许前端直接填写
owner_settlement_status       settled / pending / recovery_pending
renter_refund_status          none / pending / refunded / failed
reason
reference_no                  售后单号或外部凭证号
created_by
processed_by
processed_at
remark
created_at
```

最终结果按流水累计：

```text
最终号主收入 = 正式结算号主收入 + 所有有效 owner_income_delta_cent
最终租客退款 = 正式结算退款 + 所有已完成 renter_compensation_cent
最终平台利润 = 正式结算利润 + 所有 platform_profit_delta_cent
```

`platform_profit_delta_cent` 由服务端根据补偿承担方和号主收入变化自动计算，避免出现“号主收入、租客退款、平台利润”三者不一致。

## 4. 后台操作口径

后台输入“目标最终金额”，系统自动计算差额，不建议让客服手工输入差额：

1. 展示正式结算号主收入和当前实际号主收入。
2. 输入调整后的号主最终收入（可不调整）。
3. 输入本次售后补偿金额。
4. 选择补偿承担方：平台或号主。
5. 填写售后单号、原因和备注。
6. 提交前预览本次差额、最终号主收入、最终平台利润和待处理资金状态。

示例：正式号主收入 100 元，平台利润 20 元，售后补偿 3 元：

- 平台承担：号主仍为 100 元，平台利润减少 3 元。
- 号主承担：号主最终收入减少 3 元，并产生 3 元退款；平台利润原则上不变。

## 5. 资金处理

### 普通号主钱包订单

- 增加号主收入：在同一数据库事务中追加钱包入账流水。
- 减少号主收入：余额足够时追加钱包扣款流水。
- 余额不足：记录 `recovery_pending`，不能把钱包扣成负数，后续由财务处理追回。
- 平台承担租客补偿：提交支付退款任务，退款完成后再将调整标记为已处理。

### 平台代管订单

- 原线下款尚未支付：调整金额并入待打款任务，原始结算金额保持不变。
- 原线下款已支付：增加新的待补款或待追回任务。
- 不直接覆盖 `offline_settlement_amount_cent`，否则会丢失首次结算记录。

### 退款幂等

当前退款逻辑按订单和 `biz_type` 查找已有退款单。多次售后不能共用同一个退款业务键，应使用 `adjustment_no` 作为每次退款的唯一幂等键，并补充退款重试和失败状态。

## 6. API、权限与页面

建议接口：

```text
GET  /admin/orders/:id/financial-adjustments
POST /admin/orders/:id/financial-adjustments
POST /admin/order-financial-adjustments/:id/settle
```

新增权限：

```text
order:financial_adjust
```

不建议复用订单关闭或标记异常权限。

订单详情的结算区域增加：

- 正式结算号主收入
- 售后调整合计
- 当前实际号主收入
- 正式退款与售后补偿
- 当前实际平台利润
- 调整流水、退款状态、补款/追回状态
- “新增售后补偿/修改利润”按钮

需要同步修改订单详情、财务明细、财务仪表盘和线下出款待办的聚合查询。

## 7. 状态与审计

号主资金和租客退款可能分别处于不同状态，因此不能只使用一个总状态。建议分别保存号主结算状态和租客退款状态，再由接口计算调整单的整体状态。

创建调整、钱包入账/扣款、退款任务创建、退款完成/失败、线下补款/追回确认，都要写入 `process_events` 和 `audit_logs`，并记录调整前后金额、操作人、原因和凭证号。

## 8. 测试范围

- 普通订单增加或减少号主收入。
- 钱包余额不足进入待追回。
- 平台代管未打款时调整。
- 平台代管已打款后补款或追回。
- 平台承担补偿与号主承担补偿。
- 退款失败、重试和重复请求幂等。
- 同一订单多次售后调整的累计结果。
- 正式结算记录和原始钱包流水不可被修改。
- 财务明细、仪表盘和出款待办金额一致。

## 9. 分支核查（2026-08-30）

- 当前 `main`：`98f6ee9`，包含最近的客服上传账号统计。
- 本地 `dev`：`85332df`。
- 远端 `gitea/dev`：`85332df`，与本地 `dev` 一致。
- `dev` 包含 `80e55ba 支持提号完成后财务调整`，相关实现位于 `admin_pickup_financial_adjustments`、提号仓库/服务和提号管理页面。
- `dev` 尚未包含正常租赁订单的结算后利润调整。
- `dev` 与 `main` 的共同基点为 `f48da14`；`dev` 有 1 个独有提交，`main` 有 49 个后续提交。不能直接整体合并 `dev`，如需保留其中的接口最小化和私有文件加固，应单独评审后再移植 `85332df`。

## 10. 实施顺序

1. 增加迁移和 `AdminOrderFinancialAdjustment` 模型。
2. 增加订单调整仓库、服务、接口、权限和审计。
3. 接入钱包、退款幂等键、平台代管补款/追回。
4. 修改订单详情和财务聚合查询。
5. 补齐普通订单、平台代管、余额不足、退款失败和重复调整测试。

实施前需要确认：补偿承担方规则、退款是否全部原路退回、以及是否统一采用“目标最终金额”输入。推荐采用本文方案。