Merge pull request 'HEL-56: 整理项目说明手册' (#8) from agent/agent/e89028e267fd into main

Reviewed-on: http://192.168.200.36:3200/leefer/caiwuzongzhang/pulls/8

docs/HANDOFF.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。当前代码状态请看 `README.md`、`项目需求.md`、`最新进度.md` 和 `任务清单.md`。
+
 # 项目交接说明
 
 更新时间：2026-08-06

docs/README.md

@@ -0,0 +1,21 @@
+# 总账项目手册
+
+最后核对：2026-08-23。核对依据是当前 `main` 最新代码（`5f21527`）、数据库迁移、接口、测试和近期提交记录。
+
+这是接手本项目的第一站。阅读顺序如下：
+
+1. [项目需求](项目需求.md)：先知道系统要解决什么问题，以及哪些规则绝不能碰。
+2. [最新进度](最新进度.md)：再确认哪些能力已经真实完成，哪些仍未完成。
+3. [任务清单](任务清单.md)：最后挑选下一项工作，避免重复做已经完成的事。
+4. 需要技术细节时，再查看 `decisions/` 中的技术决定和 `issues/` 中保留的历史任务规格。
+
+## 维护规矩
+
+- 每新增、开始、完成、取消一项任务，负责的智能体都要在同一次提交里更新 `最新进度.md` 和 `任务清单.md`。
+- 新功能改变产品规则时，同时更新 `项目需求.md`；技术方案有变化时，补充 `decisions/` 的决定记录。
+- 写进手册的“已完成”必须能在代码、测试或已合并提交中找到依据；只有计划、页面演示或口头讨论的内容，一律写为“未完成”。
+- 不删除历史文档。旧内容与当前代码不一致时，在旧文件开头加“已过时，仅留档备查”提示，并在本目录写新版说明。
+
+## 旧交接说明
+
+`HANDOFF.md` 是 2026-08-06 的历史交接稿，已经不反映当前实现，保留仅作对照。当前事实以本手册三份正文为准。

docs/issues/001-p0-repository-data-hygiene.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P0] 仓库银行样本数据分级与脱敏治理
 
 ## 背景

docs/issues/002-p0-persistence-and-immutable-imports.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P0] 持久化层与不可变银行导入基础
 
 ## 背景

docs/issues/003-p0-auth-and-tenant-isolation.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P0] 正式认证、RBAC 与公司级数据隔离
 
 ## 背景

docs/issues/004-p1-dynamic-master-data.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P1] 动态公司、用户、账户和别名主数据
 
 ## 背景

docs/issues/005-p1-import-api-hardening.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P1] 银行导入 API 加固与回归测试
 
 ## 背景

docs/issues/006-p1-canonical-transfer-matching.md

@@ -1,3 +1,5 @@
+⚠️ 本文档已过时，仅留档备查，请勿删除。该历史任务已落地；当前状态见 `../任务清单.md`。
+
 # [P1] 规范转账事件、双边匹配与调拨排除
 
 ## 背景

docs/任务清单.md

@@ -0,0 +1,29 @@
+# 任务清单
+
+最后核对：2026-08-23。状态以当前代码和已合并提交为准。
+
+## 正在做
+
+- 当前没有已确认正在进行的业务功能开发。下一项工作开始前，先在此处写明负责人、范围和验收标准。
+
+## 已做完
+
+- 六类银行流水模板识别与解析。
+- 数据库迁移、不可变原始证据、导入批次和重复导入处理。
+- 管理员/公司用户登录、密码策略、会话、限流、服务端公司隔离和审计。
+- 动态公司、用户、银行账户、别名与账户审核流程。
+- 导入接口加固、逐工作表确认、失败诊断和导出。
+- 规范转账事件、双边匹配、同公司调拨排除与个人过账映射。
+- 登录页视觉融合改版。
+
+## 还没安排
+
+- 公司间余额和四类往来科目的正式计算，已批准手工记录入账，以及从余额逐层查回原始流水。
+- 起算日、期初余额、流水覆盖断档检测和无业务校准。
+- 月结、重开、调整/冲销审批与审计报告。
+- 服务端流水查询、筛选、分页和可追溯导出。
+- 站内提醒与状态流转；外部通知只预留扩展位置，不默认启用。
+- 前端全面接入真实接口，移除模拟金额、静态业务记录和 `localStorage` 业务状态。
+- 测试环境之外的运行保障，包括 HTTPS、备份、监控和正式部署方案。
+
+每完成或新增一项任务，必须在同一次提交里把它从本清单的相应栏目移走或补上，并同步更新 `最新进度.md`。

docs/最新进度.md

@@ -0,0 +1,24 @@
+# 最新进度
+
+最后核对：2026-08-23。以下“已完成”均以当前代码、数据库迁移、接口和自动化测试为依据，不把页面演示当作真实功能。
+
+## 已经真实完成
+
+- 支持中信、农行、工行、建行、河南农商行、郑州银行六类样本的 `.xls` / `.xlsx` 流水解析；能识别变动的表头位置和列顺序，并校验余额连续性。
+- 已有 SQLite 数据库和 5 次版本迁移。原始文件按内容哈希保存，导入批次、工作表、源行和异常都有记录；原始文件、工作表和源行被数据库规则保护，不能直接改或删。
+- 已实现管理员与公司用户登录、首次改密、会话失效、登录失败限流、服务端权限隔离和审计记录。
+- 已实现公司、用户、银行账户、别名等主数据管理；公司提交的银行账户需管理员审核后才能参与上传和识别。
+- 已实现导入、逐工作表确认或忽略、失败诊断、重复上传处理和 CSV 导出；未确认的工作表不进入后续处理。
+- 已实现规范转账事件和双边流水匹配。匹配决定保留历史，无法自动判断的记录进入人工审核；同公司调拨、外部流水和未锁定的单边记录不进入已确认的公司间往来。
+- 已有登录页、总账端和公司端页面，最近一次合并完成了登录页视觉改版。
+
+## 仍未完成或不能当成已完成
+
+- 公司间余额与会计科目的正式计算、已批准手工记录入账和逐层余额追溯尚未完成。
+- 全局起算日、期初余额、流水覆盖断档、无业务校准、月结、重开和调整审批尚未完成。
+- 提醒、完整的服务端查询导出，以及前端彻底移除演示数据和浏览器本地业务状态尚未完成。
+- 生产部署所需的 HTTPS、反向代理、备份、监控和正式运行保障尚未完成；本项目当前只允许测试环境部署。
+
+## 最近验证
+
+2026-08-23 已运行完整 Python 自动化测试：解析、持久化、认证与权限、导入接口、主数据和双边匹配相关测试均通过。后续修改功能时，必须再次运行完整测试并在本文件记录结果。

docs/项目需求.md

@@ -0,0 +1,26 @@
+# 项目需求
+
+## 这个系统做什么
+
+这是河南金牛实业集团有限公司内部各公司之间的资金往来管理系统。它把各公司的银行流水集中起来，识别同一笔公司间转账的两边记录，形成可以一路查回原始银行流水的往来结果。
+
+系统有两个独立入口：
+
+- 总账管理端：管理公司、公司账号、银行账户、导入记录、异常和公司间转账匹配。
+- 公司出纳端：只处理本公司的账户登记、流水上传、工作表确认和本公司相关异常。
+
+## 必须做到的业务规则
+
+- 银行原始文件和原始流水是证据，导入后不能直接修改或删除；修正必须通过可追溯的审核决定、冲销或调整完成。
+- 一笔公司间转账的收、付两边只能算作一个经济事件，不能因为有两条银行流水就重复计算。
+- 同一家公司不同银行账户之间调拨，不计入公司间往来。
+- 账号、金额、方向、日期和余额等可核对信息优先于户名；信息不完整或有歧义时进入异常审核，不能猜。
+- 已确认金额和待确认金额必须分开；所有余额都要说明统计截止日期和未决金额。
+- 公司用户只能查看、上传和导出本公司的数据。这个限制由服务端执行，页面上“看不见”不等于有权限限制。
+- 起算日前的流水必须保留，但不参与期内计算；期初余额、流水覆盖断档、无业务校准、月结和调整都要留痕。
+
+## 当前技术边界
+
+项目使用 Python 标准库服务、SQLite 数据库和浏览器页面。银行模板支持 `.xls` 与 `.xlsx`，按表头识别而非依赖固定行列。金额使用精确十进制，真实运行数据放在 `data/`，不进入代码仓库。
+
+系统目前仍是测试环境项目，不能当作已完成生产部署：正式上线前仍需补齐核算、期初与断档、月结、备份、监控和 HTTPS 等能力。