2026-08-20 09:10:36 +08:00
|
|
|
# Admin Finance Module Instructions
|
|
|
|
|
|
|
|
|
|
## 范围与入口
|
|
|
|
|
|
|
|
|
|
- 本文件适用于 `src/modules/finance/`。产品范围和状态读取 `../../../../../docs/财务管理/` 的产品确认与验收契约，后端读取 `../../../../../baiyue-firstleg/finance/AGENTS.md`。
|
|
|
|
|
- 页面从 `pages/` 进入，统一 API 从 `api/finance.ts` 进入；费用来源和柜次成本快照联查 `firstleg/`，凭证与异步导出联查 `file/`。
|
2026-09-05 08:34:40 +08:00
|
|
|
- 正式范围包括客户资金账户、客户应收应付、应收款统计、客户对账单、应收结算单和应付结算单。资金账户当前只接充值申请审核和平台手工充值/扣款，冻结/解冻、消费及支付回调后续接入；不要从历史原型自动扩大其他财务功能。
|
|
|
|
|
|
|
|
|
|
## 客户资金账户
|
|
|
|
|
|
|
|
|
|
- `pages/FinanceCustomerAccountsView.vue` 的列表和详情展示实际余额、冻结金额、可用余额；操作列固定第一列。客户上传的充值申请在详情内按待审核优先展示，审核、驳回及凭证预览以服务端申请版本和客户归属为准。
|
|
|
|
|
- 平台手工充值和扣款必须提交账户版本与幂等键；扣款不得超过服务端可用余额。页面只展示服务端余额和流水结果，不在浏览器补算或回退静态数据。
|
2026-08-20 09:10:36 +08:00
|
|
|
|
|
|
|
|
## 客户筛选与统计
|
|
|
|
|
|
|
|
|
|
- 六个正式列表页统一加载全部 `ACTIVE` 客户并使用可筛选下拉框；用户可见选项只显示 `tenantName`，以 `customerId` 作为接口筛选值。
|
|
|
|
|
- 不恢复自由输入客户关键词，不把客户编码、联系人或手机号拼入下拉标签；业务单号和费用项目继续使用独立筛选字段。
|
|
|
|
|
- 应收款统计从 `pages/FinanceReceivableStatisticsView.vue`、`api/finance.ts` 进入，只汇总指定生成月份的 CNY 正式应收结算单。
|
|
|
|
|
- 统计月份使用 `yyyy-MM`；当前页打印留在页面，Excel 通过 `FINANCE_RECEIVABLE_STATISTICS` 进入 File 下载中心异步导出。
|
|
|
|
|
|
2026-08-20 19:55:26 +08:00
|
|
|
## 费用付款与凭证快速入口
|
|
|
|
|
|
2026-09-02 20:49:19 +08:00
|
|
|
- 入库费用的应付/直接已付表单在 `../unified-orders/components/InboundFeeDetailManager.vue`，柜次费用在 `../loading-lists/components/ContainerFeesPanel.vue`；柜级公共费用在同一面板按服务端返回的真实客户与订单分摊，入仓 ID/入仓码同时选填或同时为空；对应 API 分别为 `../unified-orders/api/inboundFeeDetails.ts`、`../loading-lists/api/containerFees.ts`。
|
|
|
|
|
- 柜级分摊请求的各行金额之和必须精确等于公共费用总额；创建后使用 `allocationGroupId` 整组审核、驳回、调整或作废，前端不得调用单行接口造成部分成功，也不得提交柜外客户、订单或入仓归属。
|
2026-08-20 19:55:26 +08:00
|
|
|
- `DIRECT_PAID` 必须提交已付时间、付款方式，以及付款流水号或至少一个付款凭证；凭证由费用 API 调用 `/platform/finance/v1/vouchers` 上传为 `FINANCE_VOUCHER`，并绑定当前客户。
|
|
|
|
|
- 后端事实入口为 Firstleg `FeePaymentSnapshotValidator`、入库/柜次费用服务，文件元数据归 File；Finance 只消费已发布的费用来源快照，不在前端或 Finance 中重建付款事实。
|
2026-09-02 20:32:42 +08:00
|
|
|
- 财务与柜级公共费用分摊统一从 `pages/` 和 `api/finance.ts` 进入；`allocationGroupId` 整组审核、驳回、调整或作废，不允许按单条分摊明细绕过整组状态机。
|
2026-08-20 19:55:26 +08:00
|
|
|
|
2026-08-20 09:10:36 +08:00
|
|
|
## 权限与验证
|
|
|
|
|
|
|
|
|
|
- 列表和详情只读遵守 `*:list` 统一语义；确认、审核、导出、上传等写入或产出文件的动作继续使用独立权限。
|
|
|
|
|
- 修改筛选、DTO 或请求参数时同步检查页面、API 类型、Mock/Fixture、测试、Finance OpenAPI 和实际消费者。
|
|
|
|
|
- 至少运行 Finance 模块受影响测试和 `pnpm typecheck`；交付前按项目指引运行 `pnpm test` 与 `pnpm build`。
|
