# 财务模块开发指南 —— 业务-记账流程与数据流

> **怎么用这份文档**：新开发直接跳 **〇章「30 分钟上手」**（含原型点击清单，跑一遍最快）；后续按 第一章（总览图）→ 第五章（数据影响链）→ 第六章（走查）深入；开发具体页面时查第三、四、七章，术语不懂查《术语表.md》。
> 配套：需求见《业财一体化财务核算需求文档.md》、技术实现见《自动记账技术方案.md V3》、规则明细见《会计规则目录.md》、页面评级见《页面原型完整度清单.md》；**41 个可交互原型**（本地起 HTTP 服务即可点，是活的交互文档）。
> 日期：2026-10-09

---

## 〇、30 分钟上手（新开发从这里开始）

**四步剧本**：

| 步骤 | 时长 | 做什么 |
|---|---|---|
| ① 读总览 | 5 分钟 | 《项目说明.md》：双模式 + 管道图（本指南第一章同源） |
| ② **跑原型**（最快） | 15 分钟 | 按下方**点击清单**亲手走一遍全链——交互即答案 |
| ③ 看骨架 | 10 分钟 | 本指南第一章（管道图）+ 第五章（数据影响链） |
| ④ 随时查 | — | 《术语表.md》（会计概念字典）+ 本指南第八章 FAQ |

**启动方式**：本地 `python3 -m http.server 8731` 后开 `http://127.0.0.1:8731/财务模块/`；或用线上最新快照 `https://yx.endatai.cn/latest/财务模块/`。

### 原型点击清单（12 步，每步 1 分钟）

| # | 打开 | 操作 | 学到什么 |
|---|---|---|---|
| 1 | finance-dashboard.html | 看"业财核算"指标区 → 点"进入事项工作台" | 全局 KPI：事件 128 / 待复核 1 / 差异 60,880 |
| 2 | accounting-events.html | 筛选"待复核" → 打开 AE-0611-011（或直接打开 AE-0630-001 看已生成凭证） | 确认条件逐条 ✓✗、金额分层（确认 100,000/已结算 30,000）、状态→按钮联动 |
| 3 | accounting-event-detail.html?id=AE-0605-004 | 读四个裁定候选（现销/预收/冲应收/往来） | "未匹配收款禁止默认认收入"的落地 |
| 4 | accounting-bills.html | 销项票页签看 FP0061"待补证" → 点徽章 → "补充证据" | 证据中心的冻结态与补证回流 |
| 5 | accounting.html | 记-0048（AI·待审核）→ 审核（选王五）→ 入账 | 凭证状态机；不可自审；入账后按钮变冲销 |
| 6 | accounting.html | 记-0007 点"冲销" | 红字凭证 记-0049（借贷反向、关联原凭证） |
| 7 | accounting-books.html | 明细账选"1002 银行存款" → 点凭证号 | 账证互查：账簿→凭证 |
| 8 | accounting-recon.html | "合同履约↔收入"页签 → 点"生成事项" | 差异 32,400 → 0.00 的闭环 |
| 9 | accounting-close.html | 读 8 项检查（5 阻断+3 警告）→ 一键结账 → 反结账 | 结转损益系统强制生成 记-0038；锁期 |
| 10 | accounting-rules.html | REVENUE_SERVICE_V2 → 试运行 → 版本历史 | 规则不入账试运行；v1→v2 预收冲抵 diff |
| 11 | accounting-exceptions.html | 打开 EX-2026-0601 → 读建议动作 → 关闭（填理由） | 异常处置与留痕 |
| 12 | finance-config.html → accounting-settings.html | 会计政策页签 → 操作日志 | 规则引擎读的口径；刚才 11 步的动作全有日志 |

> 跑完这 12 步，你已亲手经历了：**业务/票据 → 事项裁定 → 凭证审核入账 → 账簿 → 对账 → 结账** 全部环节，且每一步的按钮背后就是你要开发的业务逻辑。

---

## 一、一页纸总览：业务发生 → 报表

```mermaid
flowchart LR
  subgraph S1["① 业务发生（业务经办）"]
    A1["合同履约确认"]
    A2["采购验收入库"]
    A3["报销审批通过"]
    A4["收/付款到账"]
    A5["出库 / 薪资批次 / 资产投用"]
  end
  subgraph S2["② 票据与证据（财务）"]
    B["票据池·证据中心<br/>发票 / 流水 / 费用票"]
  end
  subgraph S3["③ 会计确认（财务复核岗）"]
    C["会计事项中心<br/>确认·计量·防重"]
    D["规则引擎<br/>41 条规则"]
  end
  subgraph S4["④ 凭证与账簿（财务复核岗）"]
    E["待审核凭证"] --> F["已审核"] --> G["已记账（入账）"]
  end
  S5["⑤ 账簿·报表·对账·结账"]
  A1 --> C
  A2 --> C
  A3 --> C
  A4 --> C
  A5 --> C
  B -->|候选事项| C
  C --> D --> E
  G --> S5
  G -. "状态回写" .-> B
  G -. "状态回写" .-> C
```

**五个阶段的职责一句话**（对应侧边栏 ①~⑦ 分组）：

| 阶段（侧边栏） | 谁操作 | 做什么 | 产物 |
|---|---|---|---|
| ① 业务台账 | 业务经办 | 产生业务事实（合同/验收/报销/收付款…）——**不产生会计影响** | 业务单据 |
| ② 票据与资金 | 财务（或自动采集） | 导入流水与发票、银行对账、核销——票据/流水是**证据与候选事项来源** | 票据池记录（未记账） |
| ③ 会计确认 | 财务复核岗 | 事项复核、异常裁定、补证、规则维护——**确认条件满足才产生会计影响** | 会计事项（七态） |
| ④ 凭证与账簿 | 财务复核岗 | 凭证审核（不可自审）→ 入账——**最后一道人工闸门** | 已记账凭证 |
| ⑤ 对账与结账 | 财务负责人 | 业财对账勾稽 → 期末结账（分级拦截）→ 锁期出正式报表 | 锁定的期间 + 正式报表 |
| ⑥⑦ 资产库存/基础配置 | 财务 | 固定资产、库存、科目、政策、规则等支撑 | 主数据 |

**一条红线**：**只有"已记账"凭证参与科目余额汇总**——账簿、报表永远从已记账凭证取数。业务审批 ≠ 会计确认 ≠ 入账，三道关各自独立。

**双模式（重要）**：系统同时兼容「**业财一体**」（模式 A，默认——业务模块发事件驱动记账）与「**纯记账**」（模式 B——只用本系统做账：建账 → 导入票据/流水 → 自动生成 → 复核 → 账簿报表）。**两模式同一引擎、同一数据模型**：差别仅在输入源（B 无业务事件，票据推断直达）、UI 启用范围（B 隐藏①业务台账组、对账裁剪为两组）与事项层的透明化（B 下事项由引擎自动创建，用户只做"导入 + 复核"两件事）。模式可升降级、数据无损。开发时注意：菜单渲染与对账组按账套 `run_mode` 动态裁剪。

---

## 二、角色权限矩阵（谁能操作什么）

| 角色 | 系统角色 | 能干什么 | 不能干什么（硬约束） |
|---|---|---|---|
| **业务经办** | 业务模块用户 | 建合同/提交验收/发起报销/发起收付款申请；查看自己单据的记账状态 | 不产生任何会计影响；看不到凭证编辑 |
| **财务复核岗（记账岗）** | 记账员 | ① 票据池：指定模板（选择已有，一次性）、按单/汇总生成凭证（模板治理在规则中心） ② 事项工作台：复核事项、裁定、补证 ③ 记账管理：审核凭证、入账、冲销、手动记账、复制、凭证号整理 ④ 异常中心：处理/关闭异常（理由必填）⑤ 账簿查询 | **不能审核自己制单的凭证**；不能跳过审核直接入账；不能删除已入账凭证（只能冲销）；不能手工录结转损益 |
| **财务负责人** | 主管 | ① 会计政策变更 ② 结账"警告项"例外审批 ③ 反结账（授权+留痕）④ 大额凭证审批（>50 万复杂流程）⑤ 反核销审批 | 所有高风险动作留痕、需二次授权 |
| **规则管理员** | 规则配置 | 规则新建/编辑/试运行/发布/停用 | 规则发布与凭证复核**职责分离**；版本不可覆盖；不能直接过账 |
| **AI** | 服务 | 推荐模板、解释依据、给出置信度 | **不能直接过账、不能改规则、不能裁定**（只输出建议） |

---

## 三、页面流转规则（从哪来 → 做什么 → 去哪）

> 规则：所有跳转都是"**从队列到处理页，从数据到源单据**"——任何一行数据都能反向追到源头。

### 阶段② 票据与资金
| 页面 | 入口（从哪来） | 页面动作 | 去向 |
|---|---|---|---|
| 发票管理 | 菜单；采购/报销要求补票 | 查票/红冲作废/查看详情 | 未记账徽章 → **票据池**；已记账徽章 → **记账管理** |
| 流水管理 | 菜单；银行导入 | 查流水/匹配发票 | 流水号 → 票据池对应行 |
| 票据池（证据中心） | 菜单；发票/流水页回写 | 指定模板（选择已有）/按单/汇总生成凭证；模板新建/治理 → **规则中心** | 生成 → **记账管理**（待审核）；待定性 → **异常中心**；票据号 → 发票/流水/报销页 |
| 核销中心 | 菜单；收/付款页 | 核销/反核销审批/拆分核销 | 关联事项 → **事项详情** |

### 阶段③ 会计确认
| 页面 | 入口 | 页面动作 | 去向 |
|---|---|---|---|
| 事项工作台 | 菜单；仪表盘 | 筛选/复核/批量复核 | 复核 → 生成凭证 → **记账管理**；KPI"异常" → **异常中心**；"差异额" → **业财对账** |
| 事项详情 | 工作台/异常中心/凭证来源列 | 生成凭证 / 裁定（四候选）/ 补证 / 驳回 | 生成凭证 → **记账管理** |
| 异常中心 | 菜单；票据池"待定性"徽章 | 分派/建议动作/关闭（理由必填）/升级 | 关联事项 → **事项详情**；缺规则 → **规则中心** |
| 规则中心 | 菜单；异常中心 | 编辑/试运行/发布/版本对比 | 台账规则 → 台账中心 |

### 阶段④⑤ 凭证·账簿·结账
| 页面 | 入口 | 页面动作 | 去向 |
|---|---|---|---|
| 记账管理（凭证中心） | 菜单；事项/票据池/结账生成后自动入列 | 审核→入账/反审核/反记账/冲销/删除(回收站)/手动记账/复制/凭证号整理 | "来源"列 → 事项详情/票据池/结账页/流水；"对应单据" → 源单据 |
| 账簿查询 | 菜单 | 总账/明细账/凭证汇总表/科目余额表/核算项目余额表 | **明细账凭证号 → 记账管理**（账证互查） |
| 期末结账 | 菜单；业财对账"前往结账" | 8 项检查→一键结账→锁定/反结账 | 结转凭证号 → **记账管理** |
| 业财对账 | 菜单；事项工作台"差异额" | 四组对账/差异行闭环 | 差异行 → 生成事项/前往裁定/查看异常/生成核销 |
| 财务报表 | 菜单；仪表盘 | 标准三表+纳税+管理口径报表 | 未结账角标提示去**期末结账** |

---

## 四、数据实体与存放地（数据在哪）

| 数据实体 | 落库（技术方案 DDL） | 产生于 | 展示于 | 备注 |
|---|---|---|---|---|
| 业务单据（合同/验收/报销/收付款单） | 业务模块自有表 | 业务台账页 | 各业务页 | 事件源；**不是**会计数据 |
| 票据池记录 | `bill_pool`（UNIQUE: source_type+source_id 去重） | 发票/流水/报销导入 | 票据池、发票管理（记账状态列） | 一表两视图：发票管理=档案，票据池=队列 |
| 标准事件 | `business_event` + `outbox_event` | 业务模块同事务发出 | 无 UI（后台） | Inbox 幂等 |
| **会计事项** | `accounting_event`（六要素唯一键） | 事项中心 | 事项工作台/详情、凭证"来源"列、业财对账 | 防重与追溯的枢纽 |
| 事项-证据关联 | `accounting_event_evidence` | 匹配引擎 | 事项详情"证据"区 | 发票/流水/验收 N:M |
| 会计规则 | `accounting_rule`（版本不可覆盖） | 规则中心 | 规则中心；引擎消费 | 41 条见《会计规则目录.md》 |
| **凭证** | `voucher` + `voucher_entry` | 事项/票据池/结账/手工 | 记账管理、账簿 | status ∈ 待审核/已审核/已记账/已报税 |
| 事项-凭证关联 | `accounting_event_voucher`（N:M） | 生成时写入 | 凭证"来源"列、事项详情 | 汇总凭证=多事项一凭证 |
| 科目/期初 | `subject` / `opening_balance` | 建账向导/科目档案/初始余额 | 科目档案、账簿、报表 | 期初修改须反结账 |
| 期间结账 | `period_close` | 期末结账 | 期末结账"结账记录" | 锁期状态全系统校验 |
| 核销 | `settlement_allocation` | 核销中心 | 核销中心、应收回款对账 | 一笔到账可拆多笔应收 |
| 异常 | `accounting_exception` | 引擎/人工 | 异常中心 | 关闭理由留痕 |
| 操作日志 | `op_log` | 全系统敏感动作 | 核算设置"操作日志"、审计日志中心 | 不可删改 |

---

## 五、数据影响链（改一处，波及哪里）★核心章节

### A. 正向链（业务 → 报表，每步的落点）

```mermaid
flowchart TD
  ENT["业务事件<br/>（履约/验收/报销…）"] --> AE["会计事项<br/>状态：待复核"]
  AE -->|"复核通过"| V1["凭证<br/>待审核"]
  V1 -->|"审核（不可自审）"| V2["凭证<br/>已审核"]
  V2 -->|"入账"| V3["凭证<br/>已记账"]
  V3 --> L1["① 科目余额增量"]
  V3 --> L2["② 账簿 / 明细账 / 余额表"]
  V3 --> L3["③ 报表取数（三表）"]
  V3 --> W1["④ 事项 → 已入账"]
  V3 --> W2["⑤ 票据/流水/报销 回写：已记账 + 凭证号"]
  V3 --> W3["⑥ 辅助台账：存货结存 / 资产净值 / 辅助核算余额"]
```

**每条影响的验收口径**（改完必须回头验）：

| 入账后联动 | 验收口径 |
|---|---|
| 科目余额 | 凭证汇总表合计 = 科目余额表"本期发生额" |
| 账簿 | 明细账逐笔 = 凭证分录，余额连续 |
| 报表 | 资产负债表平衡（资产=负债+权益）；利润表=损益类发生额 |
| 事项回写 | 事项状态=已入账，凭证号可反查 |
| 票据回写 | 票据池/发票/流水/报销 显示"已记账 + 记-XXXX" |
| 辅助台账 | 存货结存金额=1403 余额；资产原值=1601、月折旧=1602 发生额 |

### B. 逆向链（纠错必须按顺序）

```
已入账 → 反记账 → 已审核 → 反审核 → 待审核 → 删除(回收站30天) 
已报税/已结账期间：先【反结账】解锁 → 再走上面的逆向
已入账凭证的正确纠错方式 = 【冲销】（红字凭证，借贷反向、关联原凭证），不是删除
```
每次逆向动作 = 上面 A 表全部联动**同步回退**（余额、账簿、报表、回写状态）。

### C. 支线影响（特定业务的数据连锁）

| 源操作 | 立即影响 | 下游影响 |
|---|---|---|
| 库存出库单审核 | 成本凭证（借6401/贷1403） | 存货结存↓、利润表成本↑、资产负债表存货↓ |
| 期末计提折旧（记-0036） | 借660202/贷1602 | 资产卡片净值↓、资产负债表累计折旧↑ |
| 薪资批次确认 → 发放 | 计提凭证（2211↑）→ 发放凭证（2211↓ + 代扣2221/2241） | 资产负债表应付职工薪酬归零、个税挂2221 |
| 缴纳社保公积金 | 借2211/2241 / 贷1002 | 2211 单位部分与 2241 个人代扣同步减少 |
| **期初余额修改** | 科目余额表期初 | 资产负债表年初数（**前提：反结账**） |
| **规则发布新版本** | 之后生成的凭证用新版本 | 历史凭证保留旧版本快照，**不追溯** |
| **会计政策变更** | 现行规则读取新口径 | 历史不追溯，生效区间按期间 |
| 冲销 | 红字凭证入队待审核 | 审核入账后 A 表全部对冲 |

### D. 勾稽红线（任何开发改动都不能破坏）

1. 期初：借方合计 = 贷方合计（当前样例 726,240.50）；
2. 凭证汇总表合计 = 科目余额表本期发生额；
3. 存货汇总表结存金额 = 1403 原材料余额；
4. 固定资产原值合计 = 1601；月折旧合计 = 1602 本期发生额；
5. 银行已入账流水合计 = 1002 明细账借贷发生；
6. 试算平衡 = 0 是结账硬门槛；
7. 已记账凭证不可删改（只可冲销）；操作日志不可删。

---

## 六、四条端到端走查（直接拿这些数据当测试用例）

### 走查 1｜销售闭环（主路径，事件驱动）
```
① 合同模块：合同 HT2026-001 签署（不发会计事项）
② 预收：流水/收款单到账 30,000 → 事项 AE-0520-007（预收）→ 凭证：借1002 / 贷2203合同负债
③ 履约：验收单确认 → 事项 AE-0630-001（收入确认·待复核）
   └ 事项详情复核 → 生成凭证 记-0048：借1122应收70,000 + 借2203合同负债30,000 / 贷6001收入100,000
④ 记账管理：审核（王五，不可自审）→ 入账 → ①应收辅助余额+70,000 ②合同负债-30,000 ③利润表收入+100,000
⑤ 开票：发票管理开票 → 只做税额处理（贷2221），【不重复确认收入】
⑥ 回款：流水 70,000 到账 → 事项（应收回款）→ 凭证：借1002 / 贷1122 → 核销中心冲应收
```

### 走查 2｜采购闭环（验收在前、发票在后、付款第三）
```
① 验收入库 RK-2026-06-001 → 事项 AE-0628-002 → 记-0018：借1403 / 贷2202（30,000）
② 发票 FP0063 到达 → 匹配：价税 30,000 vs 验收 29,520 差 480 → 异常 EX-2026-0605（调差，不重复确认成本）
③ 付款 55,000（合并此前应付）→ 记-0015：借2202 / 贷1002 → 应付余额 96,750+30,000-55,000=71,750
```

### 走查 3｜票据兜底（无业务数据客户）
```
① 导入销项发票 FP0061（47,000）→ 票据池【待补证】（缺履约证据）
② 补证（验收/交付）→ 事项转"待复核" → 复核 → 凭证：借1122 47,000 / 贷6001 45,720 + 贷2221 1,280
③ 未匹配流水 28,000 → 异常中心【待定性】→ 事项详情人工裁定四候选（现销/预收/冲应收/往来）→ 生成对应凭证
```

### 走查 4｜月末结账
```
① 事项工作台清"待复核/待补证" → 异常中心清异常 → 业财对账差异归零
② 期末结账：8 项检查（5 阻断+3 警告可例外审批）→ 一键结账
   └ 自动生成：记-0030 计提工资（借660201/贷2211）、记-0036 计提折旧（借660202/贷1602）、
              记-0038 结转损益（系统强制：收入103,000 轧入本年利润，净利 6,500）
③ 试算平衡 → 期间锁定 → 报表去"未结账"角标出正式口径 → 结账记录留痕
④ 如需调整：反结账（授权留痕）→ 改期初/反审核 → 重新结账
```

---

## 七、页面速查表（41 页：开发时的定位索引）

| 阶段 | 页面 | 数据进 | 数据出 | 评级 |
|---|---|---|---|---|
| 首页 | 财务仪表盘 / 财务待办 | 聚合指标 | 三中心入口 | B/C |
| ① | 应收/应付/收款/付款/预收预付/费用/报销/借款/保证金/薪资/社保/税费/预算/财务结算 | 业务单据 | **业务事件** | B（收付款/报销/薪资含记账状态列） |
| ② | 发票管理 / 发票风险 / 流水管理 / 核销中心 / **票据池** | 导入/采集 | 候选事项、核销分配 | 票据池 A，其余 B |
| ③ | **事项工作台 / 事项详情 / 异常中心 / 规则中心** | 业务事件、候选人 | 待审核凭证 | **全 A** |
| ④ | **记账管理 / 账簿查询 / 财务报表** | 待审核凭证 | 科目余额、账簿、报表 | **全 A** |
| ⑤ | **业财对账 / 期末结账** / 检测报告 | 业务↔账面口径 | 锁定期、正式报表 | 对账/结账 A，检测 B |
| ⑥ | 固定资产 / 库存管理 | 资产卡片/出入库 | 折旧凭证、成本凭证 | A |
| ⑦ | 建账向导 / 科目档案 / 初始余额 / 财务配置 / 核算设置 / 审计日志 | 迁移数据/配置 | 主数据、政策、日志 | A（审计日志 B） |

（评级口径见《页面原型完整度清单.md》；**A 级 17 页就是开发 1:1 实现的验收基准**。）

---

## 八、开发 FAQ（高频疑问）

1. **为什么"验收/签合同"不直接产生凭证？** 业务变化 ≠ 会计确认。合同签署只建台账；收入在"满足确认条件（验收/履约）"时才形成会计事项。见需求文档 4.1。
2. **为什么凭证要过"审核→入账"两道？** 生成 ≠ 记账。审核是人工确认（AI 生成强制人工审、制单人不可自审），入账才写余额。账簿/报表只吃"已记账"。
3. **发票管理 vs 票据池重复吗？** 不重复：一张 `bill_pool` 两个视图——发票管理=全量档案（红冲/回款跟踪），票据池=待处理队列（未记账/审核中/待定性/待补证）。见需求文档 11.1。
4. **事项和凭证为什么 N:M？** 支持汇总凭证（记-0046 一张凭证汇总 2 张费用票）与多事项一凭证；同时红字冲销是独立凭证关联原凭证。防重靠事项唯一键（六要素），不靠凭证。
5. **数字对不上先查哪里？** 固定排查顺序：试算平衡（结账页）→ 凭证汇总表 = 科目余额表发生额（账簿页）→ 明细账逐笔 → 源头单据（凭证"来源"列反查）。
6. **反记账和冲销怎么选？** 未报税期间改错 → 反记账回退修改；已入账的正式纠错 → **冲销**（红字凭证，留审计链）；已报税/已结账 → 先反结账。
7. **AI 在哪些环节出现？** 仅三处：票据模板推荐（低置信转人工）、凭证 AI 标记（强制人工审核）、异常解释建议。AI 不碰过账/规则/裁定。
8. **新客户数据从哪进？** 建账向导（科目余额表七步导入）；无账客户走三表兜底；历史凭证只读（LEGACY 标记）。见《账套迁移建账需求文档.md》。

---

## 附：配套文档索引

| 想了解 | 看这个 |
|---|---|
| 业务需求与验收标准 | 《业财一体化财务核算需求文档.md》 |
| 技术实现（架构/DDL/API/伪代码） | 《自动记账技术方案.md（V3）》 |
| 41 条规则明细 | 《会计规则目录.md》 |
| 开发排期与任务包 | 《自动记账任务清单.md》 |
| 页面完整度与补全优先级 | 《页面原型完整度清单.md》 |
| 建账迁移细节 | 《账套迁移建账需求文档.md》 |
| 发票分流关键词库 | 《发票管理.md》 |
| 会计概念速查 | 《术语表.md》 |
| 干活的时候 | 起本地服务打开原型（41 页可点，交互即答案） |