feat(finance): 人工支出改为从客服备用金扣款

2026-10-23 11:31:47 +08:00
parent cd9bb1419c
commit 2aeb789e20
7 changed files with 396 additions and 124 deletions
@@ -1,12 +1,13 @@
 # 人工支出登记落地方案（2026-10-18 修订）

-> 状态：**已实施 P0（`dev` 分支，迁移 111；订单页人工录单为 2026-10-22 增量）**
-> 最后校准：2026-10-22
-> 代码基线：`dev @ 7c883207 + 财务 108–112`
+> 状态：**已实施 P0（`dev` 分支，迁移 111；订单页人工录单、备用金扣款为 2026-10-22/23 增量）**
+> 最后校准：2026-10-23
+> 代码基线：`dev @ cd9bb141 + 财务 108–112`
 > 依据：业务口径「人工块当前不以 SLA 监管为目标，先把流程搞清楚：哪个客服处理了哪些东西、付了多少钱、什么项目、关联哪个订单」。
 > 数据来源：本地只读克隆（生产快照，数据截至 2026-10-14）+ 现有代码盘点。
 > 重要：**客服备用金支出已经实施**（`manual_expenses`）；**公司人工支出登记**（`manual_expense_records`）也已实施，两张表通过 `fund_expense_id` 关联，不是同一张表。
 > 重要：人工成本**逐单、按实际金额**录入，入口在订单界面；**不按小时，也不按固定单量/固定单价**。
+> 重要：**人工支出实际上都走客服备用金**——登记时必须选择备用金账户，系统在同一事务内扣减余额、写 `fund_entries` 与 `manual_expenses`，再回填 `manual_expense_records.fund_expense_id`。
 > 相关文档：[成本中心与三块履约模型.md](成本中心与三块履约模型.md) §8 · [财务系统集成方案.md](财务系统集成方案.md) §八 · [客服备用金台账实施方案](客服备用金台账实施方案-2026-10-18.md) ·
 > DDL 草案 [drafts/2026-10-17-人工支出登记-DDL草案.sql](drafts/2026-10-17-人工支出登记-DDL草案.sql)

@@ -23,18 +24,19 @@

 1. 客服侧已经收口的是“备用金余额与用途”，解决“客服手里有多少钱、这笔钱花到哪”。
 2. **公司口径的实际支出/垫付已落地**：后台「人工支出」页（`/admin/manual-expenses`）支持登记、审批、驳回、报销；通过后按成本项写 `cost_snapshots`，没有有效成本版本时进入异常队列。
-3. 订单界面已接入「人工录单」：订单列表对人工单显示按钮、订单详情始终可录，弹窗锁定订单号并逐单填写**实际金额**，不存在小时单价或固定单量计价。
-4. 两张表通过 `fund_expense_id` 关联：如果这笔公司支出来源于客服备用金，就填；公司直付则留空。
+3. 订单界面已接入「人工录单」：订单列表对人工单显示按钮、订单详情始终可录，弹窗锁定订单号、选择**备用金账户**并逐单填写**实际金额**，不存在小时单价或固定单量计价。
+4. 两张表通过 `fund_expense_id` 关联，且该字段由系统写入：人工支出先从客服备用金账户扣款并生成 `manual_expenses`，再写 `manual_expense_records`。
 5. **不要**把 `manual_expenses` 直接改名为 `manual_expense_records`，也不要让两张表共用索引/约束名。

-实现落点（2026-10-22）：
+实现落点（2026-10-23）：

 - 迁移：`apps/backend/src/db/migrations/111_manual_expense_records.sql`
- 服务：`apps/backend/src/services/finance/manual-expense-service.ts`
+- 服务：`apps/backend/src/services/finance/manual-expense-service.ts`；备用金扣款唯一写入口 `admin-fund-service.ts` 的 `writeFundExpense`
 - 接口：`apps/backend/src/routes/admin/finance.ts` 的 `/finance/manual-expenses*`；订单页专用 `POST /finance/manual-order-costs`
 - 页面：`apps/frontend/src/pages/admin/AdminManualExpensePage.tsx`，入口 `/admin/manual-expenses`
- 订单入口：订单列表/详情「人工录单」打开 `ManualOrderCostModal`，锁定订单号、选择订单项、填写本单实际金额；支持深链 `/admin/orders/:orderId?manualCost=1`
+- 订单入口：订单列表/详情「人工录单」打开 `ManualOrderCostModal`，锁定订单号、选择订单项与备用金账户、填写本单实际金额；支持深链 `/admin/orders/:orderId?manualCost=1`
 - 权限：查看 `finance.view` / `fund.view`，登记 `fund.expense` / `finance.config`，审核 `finance.review`
+- 资金流：登记时锁定 `fund_accounts` 行 → 校验余额 → 扣减 → 写支出流水 → 写 `manual_expenses` → 写 `manual_expense_records.fund_expense_id`，全程同一事务；余额不足直接拒绝
 - 成本快照：通过后以 `subject_type='manual_case'`、`subject_id=expense.id` 写 `actual` 快照；同一订单项多笔支出可累加，不会互相覆盖

 ---
@@ -108,7 +110,7 @@
 | 字段 | 谁提供 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | 订单号 / 订单项 | 自动（订单） | 是（无订单支出除外） | 从订单详情/列表发起时锁定 |
-| 客服备用金来源 | 人工关联 | 否 | 若这笔钱从客服备用金出，关联 `manual_expenses.id`；公司直付留空 |
+| **客服备用金账户** | **人工选** | **是** | 决定这笔钱从哪个客服的备用金扣；同一事务内扣余额、写流水与 `manual_expenses` |
 | 平台 / 店铺 / 商品 / 规格 / 数量 | 自动（订单） | 是 | 只读展示，避免手抄错 |
 | 用户实付 | 自动（订单） | 是 | 只读，用于毛利 |
 | 支付时间 | 自动（订单） | 是 | 校验支出时间不早于它 |
@@ -134,6 +136,7 @@

 > **人工成本计价口径（2026-10-22 确认）**：人工单**逐单、按实际金额**登记，**不按小时、不按固定单量/固定单价**——每一单的实际付款都可能不同。
 > 订单号是必填前置条件；同一订单项的多笔实际支出逐笔累加，未录入即保持 `cost_missing`，不按均价自动补齐。
+> **资金来源（2026-10-23 确认）**：人工支出实际上都是客服备用金出的，因此登记时**必须选择备用金账户**；公司直付不再作为默认路径。

 ### 3.3 一对多关系（必须允许）

@@ -518,9 +518,10 @@ pending_assign -> assigned -> processing -> waiting_customer

 > **业务口径（2026-10-22 确认）**：人工成本**不能按小时，也不能按固定单量/固定单价**——每一单的实际付款都不一样。
 > 必须**先关联订单号，再逐单录入这一单实际付出去的钱**。
+> **资金来源（2026-10-23 确认）**：人工支出实际上都走客服备用金，登记时必须选择备用金账户。

- 入口在订单界面：订单列表对人工单显示「人工录单」，订单详情始终有「人工录单」；弹窗锁定订单号，订单项多于 1 个时由人工选择。
- 接口 `POST /api/v1/admin/finance/manual-order-costs`：写入 `manual_expense_records`，成本项固定为 `sys_manual_service`，金额即本单实际支出。
+- 入口在订单界面：订单列表对人工单显示「人工录单」，订单详情始终有「人工录单」；弹窗锁定订单号、选择**备用金账户**，订单项多于 1 个时由人工选择。
+- 接口 `POST /api/v1/admin/finance/manual-order-costs`：同一事务内扣减备用金余额、写 `fund_entries` 与 `manual_expenses`，再写 `manual_expense_records`（成本项固定 `sys_manual_service`，`fund_expense_id` 必填），金额即本单实际支出；余额不足直接拒绝。
 - 有审核权限（`admin` / `finance` / `finance.review`）且选择立即生效时，当场审批并写 `actual` 快照；否则留在 `submitted`，由财务在「人工支出」页审核。
 - 快照以 `subject_type='manual_case'`、`subject_id=expense.id` 写入并携带 `order_item_id`；销售事实按 `cost_snapshots.order_item_id` 汇总，同一订单项的多笔支出（渠道费 + 加急费 + 补差价）累加。
 - 工时只作为后续可选的分析字段，不参与成本计算；不设「按单固定单价」。