# Client 财务模块指引

## 路径基准与读取顺序

- 本文件适用于 `src/modules/finance/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，账单与资金细则见 `../../../docs/business-index.md`。
- 本模块只做客户可见的账单查询、客户确认与资金账户；费用来源、核销与账期归 `backend finance/`，不在前端重算。
- 后端只查 `finance/`（账单、收款、账户与授信）；文件下载归 `file/`。

## 页面与入口

| 目标 | 页面/路由 | API 与后端 |
|---|---|---|
| 客户财务账单列表、筛选与未收余额 | `views/FinanceBillsView.vue`；`finance/bills` | `api/finance.ts`；`finance/` 账单 |
| 账单详情、入仓码联查与客户确认 | `views/FinanceBillDetailView.vue`；`finance/bills/:billNo/detail` | `api/finance.ts`、`adapters.ts`；`finance/` |
| 客户资金账户、授信与充值申请 | `views/FinanceAccountView.vue`；`finance/account` | `api/account.ts`；`finance/` 资金账户 |
| 跨页契约与稳定类型 | `contracts.ts` | 服务端 DTO |

## 关键边界

- 账单行只显示服务端返回的 `inboundCode`；缺失时显示“—”，不用内部 ID 或本地拼接回退。
- 实际、冻结、可用余额、授信与流水只消费 Finance 权威结果，前端不自行汇总或推算。
- 客户确认按服务端允许动作开放，提交金额与状态以服务端返回为准；已确认账单不得在前端改回。
- 充值申请与账户操作携带幂等键与提交中状态，失败保留原输入。
- 费用明细与柜级分摊只展示服务端结果；前端不参与分摊计算，也不把退税额或汇率写死。

## 验证

- 定向：`pnpm test src/modules/finance/<目标测试>`；接口或金额字段变化同时运行 `pnpm typecheck`。
- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。