# Admin Finance Module Instructions

## 范围与入口

- 本文件适用于 `src/modules/finance/`。产品范围和状态读取 `../../../../../docs/财务管理/` 的产品确认与验收契约，后端读取 `../../../../../baiyue-firstleg/finance/AGENTS.md`。
- 页面从 `pages/` 进入，统一 API 从 `api/finance.ts` 进入；费用来源和柜次成本快照联查 `firstleg/`，凭证与异步导出联查 `file/`。
- 正式范围包括客户资金账户、充值申请审核、平台手工充值/扣款、授信额度维护、客户应收应付、应收款统计、客户对账单、应收结算单和应付结算单。业务冻结/结算/释放由服务端内部接口和跨区事件调用，不在 Admin 页面复制；第三方支付回调尚未接入，不要从历史原型自动扩大其他财务功能。

## 客户资金账户

- `pages/FinanceCustomerAccountsView.vue` 的列表和详情展示实际余额、冻结金额、授信额度、授信有效期、已用授信、冻结授信和总可用余额；操作列固定第一列。授信到期日必须晚于今天且不限制最远日期，到期日当天仍有效。客户上传的充值申请在详情内按待审核优先展示，审核、驳回及凭证预览以服务端申请版本和客户归属为准。
- 平台手工充值、扣款和授信调整必须提交账户版本与幂等键；扣款及授信下限由服务端校验。页面只展示服务端余额、授信和流水结果，不在浏览器补算或回退静态数据。

## 客户筛选与统计

- 六个正式列表页统一加载全部 `ACTIVE` 客户并使用可筛选下拉框；用户可见选项只显示 `tenantName`，以 `customerId` 作为接口筛选值。
- 不恢复自由输入客户关键词，不把客户编码、联系人或手机号拼入下拉标签；业务单号和费用项目继续使用独立筛选字段。
- 应收款统计从 `pages/FinanceReceivableStatisticsView.vue`、`api/finance.ts` 进入，只汇总指定生成月份的 CNY 正式应收结算单。
- 统计月份使用 `yyyy-MM`；当前页打印留在页面，Excel 通过 `FINANCE_RECEIVABLE_STATISTICS` 进入 File 下载中心异步导出。

## 费用付款与凭证快速入口

- 入库费用的应付/直接已付表单在 `../unified-orders/components/InboundFeeDetailManager.vue`，柜次费用在 `../loading-lists/components/ContainerFeesPanel.vue`；柜级公共费用在同一面板按服务端返回的真实客户与订单分摊，入仓 ID/入仓码同时选填或同时为空；对应 API 分别为 `../unified-orders/api/inboundFeeDetails.ts`、`../loading-lists/api/containerFees.ts`。
- 柜级分摊请求的各行金额之和必须精确等于公共费用总额；创建后使用 `allocationGroupId` 整组审核、驳回、调整或作废，前端不得调用单行接口造成部分成功，也不得提交柜外客户、订单或入仓归属。
- `DIRECT_PAID` 必须提交已付时间、付款方式，以及付款流水号或至少一个付款凭证；凭证由费用 API 调用 `/platform/finance/v1/vouchers` 上传为 `FINANCE_VOUCHER`，并绑定当前客户。
- 后端事实入口为 Firstleg `FeePaymentSnapshotValidator`、入库/柜次费用服务，文件元数据归 File；Finance 只消费已发布的费用来源快照，不在前端或 Finance 中重建付款事实。
- 财务与柜级公共费用分摊统一从 `pages/` 和 `api/finance.ts` 进入；`allocationGroupId` 整组审核、驳回、调整或作废，不允许按单条分摊明细绕过整组状态机。

## 权限与验证

- 列表和详情只读遵守 `*:list` 统一语义；确认、审核、导出、上传等写入或产出文件的动作继续使用独立权限。
- 修改筛选、DTO 或请求参数时同步检查页面、API 类型、Mock/Fixture、测试、Finance OpenAPI 和实际消费者。
- 至少运行 Finance 模块受影响测试和 `pnpm typecheck`；交付前按项目指引运行 `pnpm test` 与 `pnpm build`。