feat(finance): P2 手动退款登记与成本异常闭环

- 迁移 112：order_refunds（订单项级退款，整单拆多条共享 batch_no，source/external_ref 预留平台 API）+ cost_exceptions.resolution_note
- 新服务 order-refund-service：整单/指定商品退款、可退金额校验、撤销、全额退完同步 pay_status
- 销售事实改为按有效退款记录冲减；无记录时仍兼容 pay_status=refunded 的历史全额退款
- 订单详情新增退款登记与退款记录表，商品明细显示收入/已退/可退
- 全额退款自动关闭该订单项成本异常并写处理备注；成本异常处理改为带备注弹窗
- 财务事件 UNION 接入退款记录，文档同步 P2 状态与 API

docs/财务与履约口径总纲-2026-10-23.md

@@ -152,12 +152,12 @@
 | P0 | 统一履约事实（`fulfillment_mode`）+ 成本模型正交 | **已完成（本地，未部署生产）** |
 | P0.5 | 人工成本链路收敛为「人工录单 → 扣备用金 → 写快照」（下线登记/审批/报销） | **已完成（本地，未部署生产）** |
 | P1 | 人工商品归一（`man:<skuId>`）+ 上线后人工成本全覆盖 | **已完成（本地，未部署生产）** |
-| P2 | 退款冲减与异常闭环 | 未实施 |
+| P2 | 退款冲减与异常闭环 | **已完成（手动登记先行，平台退款 API 待接入）** |
 | P3 | 影子总账与对账 | 未实施 |
 
 P0 的具体迁移、回填、代码清单与验收 SQL 见 [成本中心与履约模型](成本中心与履约模型.md)；接口契约见 [成本中心API契约](成本中心API契约.md)。
 
-> 下一步只做 P2，不要同时改总账。
+> 下一步只做 P3，不要同时改总账与平台对接。
 
 ---
 
@@ -178,11 +178,12 @@ P0 的具体迁移、回填、代码清单与验收 SQL 见 [成本中心与履
 | 人工成本链路收敛为「人工录单 → 扣备用金 → 写快照」 | **已实施（本地库已改造）** | 迁移 `108_drop_manual_expense_records`；下线登记单与审批报销 |
 | 人工商品归一 `man:<skuId>` | **已实施（本地库已归一）** | `manual-product-normalization-service` + `POST /cost-center/manual-products/normalize`；1,116 个 `man:` 商品、91,606 个人工订单项归一，人工未归一 = 0 |
 | 人工商品归一后的销售事实 | **已实施** | 94 天分 30 天窗口重算：26,507 行；人工 ¥1,219.20 万收入全部按 `man:` 商品归集 |
-| 退款冲减、异常闭环 | **未实施** | §六 P2 |
+| 退款冲减、异常闭环 | **已实施（手动登记先行）** | 迁移 `112_order_refunds`；订单页「退款登记」（整单/指定商品、可撤销）；销售事实按有效退款冲减；全额退完后自动关闭该订单项成本异常并写 `resolution_note` |
+| 平台退款 API 接入 | **未实施** | 预留 `order_refunds.source='api'/'platform'` 与 `external_ref` |
 | 影子总账、对账、关账 | **未实施** | §六 P3 |
 
 > 历史平台仍有 53,901 个订单项（¥389.12 万）未归一，不属于 P1 范围；人工历史成本按既定口径不补录，因此人工毛利当前是“收入已归商品、成本仅新单有”的状态。
-> 分支事实：以上实现已快进合并到 `dev`；迁移 `103–111` **未推送远端、未部署生产**。生产口径仍以 `main` 为准。
+> 分支事实：以上实现已快进合并到 `dev`；迁移 `103–112` **未推送远端、未部署生产**。生产口径仍以 `main` 为准。
 
 ---
 

docs/财务系统集成方案.md

@@ -399,9 +399,13 @@ POST /api/v1/admin/finance/sales-facts/rebuild
 POST /api/v1/admin/cost-center/snapshots/sync
 GET  /api/v1/admin/finance/manual-order-cost-items
 POST /api/v1/admin/finance/manual-order-costs
+GET  /api/v1/admin/orders/:orderId/refunds
+POST /api/v1/admin/orders/:orderId/refunds
+POST /api/v1/admin/orders/:orderId/refunds/:refundId/void
 ```
 
 > 2026-10-23 下线了 `/finance/manual-expenses*` 全套接口（登记/审批/报销），改为上表的人工录单接口。
+> 2026-10-24 上线手动退款登记（`order_refunds`）：整单退款按订单项拆条、共享 `batch_no`，销售事实按有效退款冲减；后续平台退款 API 只需写 `source='api'/'platform'` + `external_ref`，其余聚合与冲减逻辑复用。
 
 总账层建议新增前缀 `/api/v1/admin/finance`：