dachui/order_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin): 收口人工履约入口并修复履约筛选

Browse Source
This commit is contained in:
yml2213
2026-10-24 17:42:07 +08:00
parent faf56e567e
commit 790de676c6
27 changed files with 495 additions and 1327 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+5 -5
View File
@@ -46,12 +46,12 @@
### 5. 人工成本只有一条链路
```text
订单页「人工录单」→ 扣客服备用金（manual_expenses）→ 写 cost_snapshots（manual_case）
订单列表/详情「确认履约」→ 扣客服积分/备用金 → 写 cost_snapshots（manual_case）
```
| 名称 | 业务含义 | 当前状态 |
| --- | --- | --- |
| `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100）；人工录单也写这里 |
| `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100）；确认履约的现金支出也写这里 |
| `cost_snapshots` | **人工成本的唯一落点**：`subject_type='manual_case'`，`subject_id=manual_expenses.id` | 已实施（迁移 104） |
**没有独立的登记单，也没有审批与报销环节。** `manual_expense_records` / `manual_expense_events` 已随迁移 `108` 删除。后续做财务系统时，人工成本的钱与账都从这条链路走，不要再另造一张人工支出表。
@@ -80,7 +80,7 @@
| 商品主数据 + 渠道 SKU 映射 | **已实施 P0** | 745 个标准商品、4,426 条映射；只覆盖自动发货 38 个 + 接单平台 707 个。人工 11,349 项虽已归一但全部挂 `tpl:*` 模板商品，需在 P1 复核；人工专用商品尚未建立 |
| 成本中心 | **已实施 P0** | 迁移 `104`；`cost_items.cost_model` 取代 `cost_type + carrier_type`；38 个商品级版本 + 662 个规则级版本；人工走 `sys_manual_service` 实际快照 |
| 销售事实 / 订单毛利 | **已实施 P0** | 迁移 `105`；94 天事实收入 ¥2,650.87 万、成本 ¥950.27 万；`sales_daily_facts.fulfillment_mode` |
| 人工成本录入（人工录单） | **已实施 P0** | 迁移 `106/108`；录入即扣客服备用金并写 `actual` 快照；无登记单/审批/报销；客服只能使用本人账户 |
| 人工成本录入（确认履约） | **已实施 P0（2026-10-24 入口收敛到订单页）** | 人工履约页已下线；确认即扣积分/备用金并写 `actual` 快照；无登记单/审批/报销 |
| 履约方式统一 | **已实施 P0** | 迁移 `107`；316,585 项已回填，四项计数与总纲 §二 一致；订单页、成本快照、销售事实只读 `fulfillment_mode` |
| 人工商品归一 | **未实施（P1）** | 人工单按 `spec.skuId` 建 `man:<skuId>`；历史 11,349 项 `tpl:*` 商品待复核 |
| 影子总账 | 未实施 | 现有财务页仍是 `UNION ALL` 业务事件拼装，不是复式总账 |
@@ -95,7 +95,7 @@
0. 统一履约事实（fulfillment_mode + 成本模型正交） 已完成 P0（迁移 107）
1. 商品主数据 + 渠道 SKU 映射 已完成 P0（仅自动发货/接单平台）
2. 成本中心 + 销售事实 已完成 P0
2.5 人工成本链路收敛（人工录单 → 扣备用金 → 写快照） 已完成 P0（迁移 106/108）
2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照） 已完成 P0（迁移 106/108）
3. 人工商品归一与上线后人工成本全覆盖 未实施（下一阶段）
4. 退款冲减与异常队列 未实施
5. 影子总账（订单、工单、押金、提现、寄卖、售后） 未实施
@@ -126,7 +126,7 @@
| [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL |
| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103–107`；履约回填；本地库原地改造；索引与性能 |
| [成本中心API契约.md](成本中心API契约.md) | 现行 | 成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 8 面板） |
| [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 人工录单字段/流程/权限、客服备用金台账、本人账户与编号规则 |
| [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 确认履约流程/权限、客服备用金台账、本人账户与编号规则 |
| [财务系统集成方案.md](财务系统集成方案.md) | 现行方案（总账未实施） | 复式记账、总账表、对账、关账 |
| [影子总账说明.md](影子总账说明.md) | 现行说明（未实施） | 影子总账是什么、和钱包流水的区别、对账与转正标准 |
| [项目全量分析报告-2026-10-17.md](项目全量分析报告-2026-10-17.md) | 历史参考 | 2026-10-17 架构与风险；财务口径以总纲为准 |
docs/人工支出与备用金.md
+6 -5
View File
@@ -1,20 +1,21 @@
# 人工支出与客服备用金
> 状态：**现行（P0 已实施，未部署生产）**。
> 最后校准：2026-10-23
> 最后校准：2026-10-24
> **2026-10-24 变更**：独立「人工履约」页面已下线，订单列表/详情里的「人工录单」改为「确认履约」；`/finance/manual-order-cost*` 接口已删除。资金链路不变（扣积分/备用金 → 写 `manual_case` 快照）。
> 代码基线：`dev @ 43f402cf + 迁移 100/101/106/108`（已合并到 `dev`，**未推送、未部署生产**）
> **业务口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文只负责人工录单的字段、流程、权限与备用金台账。
> 本文合并自原《人工支出登记落地方案-2026-10-17.md》与《客服备用金台账实施方案-2026-10-18.md》。
---
## 〇、只有一条链路：人工录单
## 〇、只有一条链路：确认履约（原人工录单）
2026-10-23 口径调整：**公司人工支出登记单与审批报销状态机整链下线**。人工成本现在只有一条路径。
```text
订单页「人工录单」
→ 扣客服备用金余额（写 fund_entries + manual_expenses）
订单列表/详情「确认履约」
→ 扣客服积分或备用金余额（写 fund_entries / platform_credit_entries）
→ 写 cost_snapshots（subject_type='manual_case'，subject_id=manual_expenses.id）
```
@@ -147,7 +148,7 @@ evidenceJson -- 凭证（对象存储 key / 流水号 / 聊天记
---
## 四、订单页「人工录单」
## 四、订单页「确认履约」
订单里的数据足够预填 90%：店铺、商品、规格、数量、用户实付、支付时间、平台单号、履约标签、状态，后台订单列表/详情已经全部具备。客服实际只需要补 **4 件事**：渠道/项目、金额、收款方、凭证（外加默认带出的「谁、什么时候」）。
docs/成本中心API契约.md
+1 -1
View File
@@ -16,7 +16,7 @@
| `product_catalog.carrier_type` | （删除，改由 `canonical_sku` 前缀推导） | DB / 商品接口 |
| `sales_daily_facts.carrier_type` | `sales_daily_facts.fulfillment_mode` | DB / 销售事实接口 |
| `work_product_rules.legacy_cost_source` | （删除） | DB |
| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走人工录单） | DB |
| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB |
## 二、枚举映射
docs/成本中心与履约模型.md
+2 -2
View File
@@ -63,7 +63,7 @@ orders ──┬── order_items ──── fulfillment_mode (唯一履约
| `work_product_rules.legacy_cost_source` | （删除） | DB |
| `cost_versions.cost_item_carrier_type` | `cost_versions.cost_item_cost_model` | 成本版本接口 |
| `pricing_mode: per_hour / fixed_daily` | （删除，只剩三种） | 成本项接口 |
| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走人工录单） | DB |
| `manual_expense_records` / `manual_expense_events` | （删除，人工成本只走确认履约） | DB |
### 1.2 成本模型映射
@@ -222,7 +222,7 @@ cost_versions
| --- | --- | --- |
| `sys_work_order_reward` | `work_order_reward` | 662 个接单模板各一条规则级版本；全局 0 元版本只作"按工单实际结算"的占位 |
| `sys_affiliate_purchase` | `affiliate_purchase` | 上游 SKU 固定成本版本，38 个商品级 |
| `sys_manual_service` | `manual_actual` | 订单页人工录单写入 `actual` 快照；版本先为 `draft` 占位 |
| `sys_manual_service` | `manual_actual` | 订单页确认履约写入 `actual` 快照；版本为 0 元占位 |
工单报酬的三种快照：
docs/财务系统集成方案.md
+10 -11
View File
@@ -18,13 +18,13 @@
| 客服备用金台账（`fund_*` / 备用金 `manual_expenses`） | **已实施 P0**；账户编号 `FA-<用户名>`；客服只能使用本人账户 |
| 商品主数据 / 渠道 SKU 映射 / 成本中心 | **已实施 P0（`dev` 分支）**，迁移 `103/104`；标准商品 745 个，只覆盖自动发货 38 + 接单平台 707 |
| `sales_daily_facts` / 订单级毛利 | **已实施 P0（`dev` 分支）**，迁移 `105`；94 天收入 ¥2,650.87 万、成本 ¥950.27 万 |
| 人工成本录入（人工录单 → 扣备用金 → 写快照） | **已实施 P0（`dev` 分支）**，迁移 `106/108`；**无登记单、无审批、无报销** |
| 人工成本录入（确认履约 → 扣积分/备用金 → 写快照） | **已实施 P0（`dev` 分支）**，迁移 `106/108`；2026-10-24 人工履约页下线、入口收敛到订单页；**无登记单、无审批、无报销** |
| 履约方式统一 `fulfillment_mode` | **已实施 P0（`dev` 分支）**；迁移 `107`，316,585 项已回填；订单页、成本快照、销售事实统一读该字段 |
| `finance_accounts` / `finance_business_events` / `finance_journal_*` | 未实施 |
| `finance_settlements` / `finance_reconciliations` | 未实施 |
| 现有 `admin-finance-service.ts` | 仍是业务事件 `UNION ALL`，不是总账 |
**人工成本只有一条链路**：订单页人工录单 → 扣客服备用金（`manual_expenses`）→ 写 `cost_snapshots`（`subject_type='manual_case'`，`subject_id=manual_expenses.id`）。没有独立的人工支出登记表，也没有审批与报销环节。
**人工成本只有一条链路**：订单列表/详情点「确认履约」→ 扣客服积分或备用金 → 写 `cost_snapshots`（`subject_type='manual_case'`）。没有独立的人工支出登记表，也没有审批与报销环节。
---
@@ -83,7 +83,7 @@
| 自动发货 | `affiliate_dash` | 上游固定成本 → `cost_versions` | 采购成本 |
| 接单平台 | `work_orders` | 模板规则版本 / 工单实际报酬 | 履约成本 + 押金负债 |
| 历史平台 | `ct_assisted` / `feifei`（已下线） | 历史成本未采集则单列 | 仅历史报表 |
| 人工 | 无工单、无自动发货任务、无历史平台任务 | **逐单实际金额**，人工录单直接从客服备用金扣款 | 人工成本 + 备用金 |
| 人工 | 无工单、无自动发货任务、无历史平台任务 | **逐单实际金额**，确认履约直接扣积分/备用金 | 人工成本 + 备用金 |
电子凭证只是核销码，不进入上述分类。
@@ -313,7 +313,7 @@ CREATE TABLE finance_reconciliation_items (
| 寄卖验收货款 | 5001 商品采购成本 | 2002 应付卖家货款 | 货款金额取 `cost_price_fen || asking_price_fen` |
| 支付卖家货款 | 2002 应付卖家货款 | 1001 银行存款 | 需结算单 |
| 平台服务费 | 5401 平台服务费 | 2101 应付平台服务费 | 从平台账单导入 |
| 人工录单（客服垫付） | 5102 履约成本-人工客服（按 `cost_item_id` 映射科目） | 2005 其他应付-垫付人 | 扣客服备用金时同步发生；不需要单独审批 |
| 确认履约（客服垫付） | 5102 履约成本-人工客服（按 `cost_item_id` 映射科目） | 2005 其他应付-垫付人 | 扣客服积分/备用金时同步发生；不需要单独审批 |
| 客服备用金发放 | 1001 银行存款 | 2005 其他应付-垫付人 | 主管发放时发生 |
| 退款冲正（预留） | 反向凭证 `reversal_of_id` 指向原凭证 | — | 退款/仲裁暂未接入，先预留不实现 |
@@ -359,7 +359,7 @@ postBusinessEvent({
| `after-sales-repo.ts` | 售后扣款/欠款抵扣发事件 |
| `worker-finance-request-service.ts` | 充值/提现审核发事件 |
| `consignment-deposit-repo.ts` | 发布押金、货款结算发事件 |
| `services/finance/manual-order-cost-service.ts`（已实施） | 人工录单成功时发事件；主体是 `manual_expenses.id` |
| `services/finance/manual-fulfillment-service.ts`（已实施） | 确认履约成功时发事件；主体是积分流水 / 备用金支出 |
| `admin-finance-service.ts` | 改为读总账/试算平衡，不再用 `UNION ALL` 拼报表 |
### 4.3 钱包投影一致性
@@ -397,14 +397,13 @@ GET /api/v1/admin/finance/sales-profit/overview
GET /api/v1/admin/finance/sales-facts
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-23 下线了 `/finance/manual-expenses*` 全套接口（登记/审批/报销）。
> 2026-10-24 下线 `/finance/manual-order-cost*`（人工录单），改为 `GET /finance/manual-fulfillment/pending` + `POST /finance/manual-fulfillment/confirm`。
> 2026-10-24 上线手动退款登记（`order_refunds`）：整单退款按订单项拆条、共享 `batch_no`，销售事实按有效退款冲减；后续平台退款 API 只需写 `source='api'/'platform'` + `external_ref`，其余聚合与冲减逻辑复用。
总账层建议新增前缀 `/api/v1/admin/finance`：
@@ -440,14 +439,14 @@ POST /periods/:key/close
## 六、总账层分期
> 项目级顺序以 [README.md](README.md) §三 为准；本节只描述“总账层”内部阶段。
> 进入 P0 前应已完成：统一履约事实、商品主数据、渠道 SKU 映射、成本中心、销售事实、人工录单（`manual-order-cost-service`）。
> 进入 P0 前应已完成：统一履约事实、商品主数据、渠道 SKU 映射、成本中心、销售事实、确认履约（`manual-fulfillment-service`）。
### P0：影子总账（1–2 周）
> 前置：先完成统一履约事实、商品主数据、渠道 SKU 映射、成本中心与销售事实（见 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md)）。否则影子总账只能记“总额”，无法按店铺/皮肤/成本版本出毛利。
- 建 `finance_accounts / business_events / journal_entries / journal_lines / periods`。
- 先接高频且核心的事件：订单支付、工单结算、押金冻结/释放/没收、提现，以及人工录单。
- 先接高频且核心的事件：订单支付、工单结算、押金冻结/释放/没收、提现，以及确认履约。
- 写总账但不改现有钱包逻辑。
- 每日对账：钱包余额 vs 总账余额。
- 补金额守恒与幂等测试。
@@ -508,7 +507,7 @@ POST /periods/:key/close
| 5 | 寄卖货款的采购成本确认时点 | ⏳ 待定 | 决定存货/成本 |
| 6 | 提现通道费、平台服务费由谁承担 | ⏳ 待定 | 决定费用科目与结算 |
| 7 | 退款、拒付、仲裁的冲减规则 | ✅ **已确认：暂未接入，先预留**（字段 + `reversal_of_id` + 事件类型，不实现逻辑） | 决定售后与收入冲回 |
| 8 | 人工支出如何入账 | ✅ **已确认：逐单实际金额，人工录单直接从客服备用金扣款并写成本快照，客服只能用本人账户；无登记单/审批/报销；历史人工支出找不回来、直接放弃** | 决定人工成本与备用金 |
| 8 | 人工支出如何入账 | ✅ **已确认：逐单实际金额，确认履约直接扣积分/备用金并写成本快照；无登记单/审批/报销；历史人工支出找不回来、直接放弃** | 决定人工成本与备用金 |
| 9 | 电子凭证是否作为履约/成本分类 | ✅ **不参与分类**；电子凭证只是快手核销码 | 决定报表口径 |
| 10 | 历史人工支出 | ✅ **不补录**，只取少量样本校准；上线后人工单必须 100% 有成本记录 | 决定上线范围 |
| 11 | 是否需要发票/税务 | ⏳ 待定 | 决定发票表与税额 |