kaidi/docs/财务系统开发交付总方案.md

财务项目基础系统开发交付总方案

文档编号：KD-FIN-DELIVERY-001
版本：V3.26（Preview.9 公共 Release 一键安装）
状态：第一版 Preview 候选包已具备 22 页功能框架、核心业务链和可部署制品；PAGE-13/14 已通过模块验收，PAGE-12/16/17/18/19/20/21/22 为 IMPLEMENTED_PENDING_ACCEPTANCE，PAGE-15 正式业务矩阵仍为 IN_PROGRESS；整套 R1 尚未达到第 12.9 节 Definition of Done，不得把 Preview 上线等同于甲方最终验收
编制依据：2026-08-05 腾讯会议转写、14 张 OA 表单、财务岗位职责资料、项目管理流程图
最新项目决策：按既定 Java/TDesign 技术栈交付第一版 Preview；2026-08-17 已完成 PAGE-08 来源、记账、档案双向穿透，PAGE-20 审计稳定排序/筛选/脱敏导出、PAGE-21 权限与配置、PAGE-22 公共 Gitea 签名在线更新、OA-04/OA-06 动态附件矩阵、OA-06 财务终审付款投影、Release/SBOM/依赖门禁、Linux i386/i486/i586/i686 外部 MySQL 8.4.x 单命令安装、更新请求持久领取/中断恢复/数据库备份校验/回滚健康复核，以及隔离超级管理员全部功能权限和全局数据范围；本轮新增 PAGE-23 首次安装向导、无业务数据库启动上下文、MySQL 8.4 DDL/DML 预检、一次性安装码和安装状态锁定，数据库基线新增 V072。远端仓库 https://git.awaioi.com/ERP-Team/kaidi.git 与 Release 均已公开；安装和在线更新默认不使用 Token，安装器内置发布公钥指纹，推送符合 SemVer 的 v* tag 后由带签名密钥的发布流程生成 Release；PAGE-15 完整业务矩阵继续保持 DRAFT，须经 D-02/D-09 确认后才允许作为正式规则发布
实际开发技术：Java 17 + Spring Boot 3.5.16 + MyBatis 3.0.5 + MySQL 8.4 + TDesign Vue Next Starter；前端仍只允许在现有 frontend/ Starter 中原位增加菜单、页面、组件和真实功能 文档性质：本项目唯一 PRD、SPEC、开发任务书、测试验收与交付基线
文档用途：甲方需求确认、产品设计、开发拆分、测试验收和交付培训
阅读方式：第 0～10 章说明“做什么和业务逻辑”，第 11～12 章说明“怎么开发”，第 13～19 章说明“怎么验收、交付和控制风险”

0. 给非技术人员的一页说明

0.1 这次要做的系统

首期做一套“项目财务基础系统”，把资料从进入系统到可查询的全过程串起来：

项目/业务人员提供资料
  → 系统校验并留存附件
  → 项目或财务人员审批、退回补件
  → 形成收款、发票、成本、付款等财务记录
  → 生成记账准备资料并登记人工记账结果
  → 资料人员检查、归档
  → 按项目、合同、金额、状态和附件查询分析

0.2 第一轮必须交付的“完整”

完整不是“把所有财务和税务都做完”，而是第 12.9 节定义的 R1 全部完成：22 个页面、14 类表单、真实 Java/MySQL 数据、三类业务身份和独立系统管理员、审批、财务台账、记账准备、档案、报表、权限、审计、测试、部署和交付材料都能实际使用。银行网银/U 盾、电子税务局、自然人税务系统、第三方账号/API、RPA 和自动付款/报税/过账明确不在 R1。

0.3 前端唯一规则

前端只能在现有 frontend/ TDesign Vue Next Starter 中增加菜单、路由、页面和业务组件。按钮、表单、表格、弹窗、抽屉、分页、标签、图标和反馈必须使用 TDesign 或经批准的 TDesign 组合组件；不能新建第二个前端、引入 Ant Design/Element Plus 等第二套 UI、用原生控件替代 TDesign，或用静态页面/Mock 冒充真实功能。具体例外和批准流程见 11.2 节。

0.4 开发团队的责任

开发执行期由开发团队负责“实现 → 自测 → 联调 → 定位 → 修复 → 同类扫描 → 回归 → 部署 → 证据 → 验收”的完整闭环。甲方只确认业务规则和验收结果，不负责替开发人员查代码、改数据库、补接口或发现基础缺陷。

0.5 当前状态

项目已按 2026-08-11 最新指令进入 R1 开发执行阶段。当前采用“模块逐项验收、整套系统统一交付”的口径：一个页面只有真实前端、Java 接口、MySQL 持久化、权限/状态/金额控制、自动化测试和浏览器实操都通过，才可标记为模块级完成；模块级完成不等于整套 R1 已交付。

层级	当前状态	准确结论
Preview 工程实现	100%	PAGE-01～22、核心业务链、构建制品、签名安装/更新框架和自动化发布门禁均已具备；该比例只表示第一版可预览框架，不表示全部业务规则已由甲方确认
整体 R1 工程实现估算	约 95%	按当前已冻结范围估算代码、页面、接口、迁移和开发自验证进度；正式 UAT、部署恢复、性能、培训、规则确认和签字仍单独阻断 R1 交付
整体 R1	IN_PROGRESS	PAGE-01～22 尚未全部完成，第 12.9 节 DoD 尚未满足，不得对甲方宣称整套系统交付完成
PAGE-12 主数据中心	IMPLEMENTED_PENDING_ACCEPTANCE	已新增部门主数据表、共享字典权限范围升级回填、完整草稿/编辑/提交/异人复核/生效/停用链路、重复编码/版本冲突/审计断言、八类资源版本记录/版本对比、旧编号映射和 TDesign 部门页签；MasterDataIntegrationTest 8/8、PAGE-12 三档行为测试 3/3 通过。正式异常矩阵、Chrome/Edge UAT 和甲方证据包仍未完成
PAGE-13 合同与成本	MODULE_ACCEPTED	合同额度、变更、结算、开票、应付、付款汇总与下钻已连接真实接口；应付登记/确认职责分离、OA-04/OA-11 已批准来源和金额口径已通过自动化及浏览器验收
PAGE-14 收款与发票	MODULE_ACCEPTED	收款草稿/确认/核销/作废、正式应收、开票申请/审核/人工结果/作废/红冲、合同额度、权限范围、金额上限、SOD、乐观锁、查询分页和 CSV 导出已接真实接口并通过本节记录的验收
OA-04/05/08 来源投影	IMPLEMENTED_PENDING_ACCEPTANCE	财务终审已分别生成已确认应付、已确认收款和开票候选；来源专项自动化已通过；OA-08 已审批候选退回后的“来源更正→新版本→重新终审”闭环、正式三档浏览器 UAT、迁移升级预检和证据包仍待补齐
PAGE-15 进度款与付款	IN_PROGRESS	付款主链、OA-06 v2 稳定引用及财务终审 OFFLINE_PENDING 付款投影、成本类型附件规则、同项目并发余额控制、独立逐笔资金台账和例外申请/复核/消费机制已实现并通过定向验证；正式矩阵仍为 DRAFT，正式规则确认和浏览器证据仍未完成
PAGE-16 记账准备	IMPLEMENTED_PENDING_ACCEPTANCE	财务事件、凭证草稿、编辑、复核、导出、人工结果登记/异人复核、已完成结果冲销/异人重开、分轮证据和历史下载、历史外部凭证号唯一、授权额度/数据范围、SOD、乐观锁、幂等和审计已实现；AccountingIntegrationTest 18/18、PAGE-16 三档专项 12/12 通过，正式外部导入样例、Chrome/Edge 业务 UAT 和甲方证据包仍未完成
PAGE-17 项目归档	IMPLEMENTED_PENDING_ACCEPTANCE	已实现财务资料完整确认、档案包生成门禁、缺件清单、对象快照、检查、提交、异人审核、退回补件、归档、冻结及保管到期状态提示；正式 Chrome/Edge 三档全流程、异常状态 fixture 和甲方证据包仍未完成
PAGE-18 文件检索与借阅	IMPLEMENTED_PENDING_ACCEPTANCE	检索、扫描/归档状态、详情、受控预览、隔离文件可恢复重扫、异人批准借阅/归还及范围外直链下载回归已贯通；正式 Chrome/Edge 三档全流程、axe 和甲方证据包仍未完成
PAGE-19 查询与报表	IMPLEMENTED_PENDING_ACCEPTANCE	六类报表、汇总、同权限下钻、筛选快照及两阶段导出已实现，MySQL 8.4 全量集成回归已通过；D-08、日期口径、流程时长样本和正式 UAT 仍阻断验收
S3 财务收支阶段	IN_PROGRESS	PAGE-13/14 已完成模块级验收；PAGE-15 核心付款链已通过定向验证，但模块级阻断项仍未清零，S3 付款与例外任务继续按各自证据单独判断
S0 决策与合同	并行收口	D-01～D-11、全量机器合同和其他页面 fixture 仍要继续完成；未确认规则继续阻断其影响到的具体模块，不回滚已通过验证的 PAGE-14 事实
范围外事项	OUT_OF_SCOPE	网银/U 盾、税务平台、第三方权限/API、RPA、自动付款、自动报税、自动缴税和自动过账继续不做

剩余时间估算（以甲方规则、样本和环境按时到位为前提）：第一版 Preview 候选包可在 Git 仓库和 Release 地址配置完成后当天发布；剩余代码与内部验证约 1～2 个工作日，正式 Chrome/Edge UAT、异常/权限证据、staging/恢复/性能、培训与签字约 5～8 个工作日。并行推进时，整套 R1 预计还需 5～8 个工作日；D-02/D-07/D-08/D-09、正式样本、生产域名/证书或甲方验收人延迟的时间不计入该估算并顺延交付日期。

0.6 V3.22 本次修订记录

修订项	本版固定结果
页面层级	PAGE-03～21 以路由合同面包屑作为静态页面名称的唯一可见来源；工作台、列表、台账、报表和配置页删除内容区重复的模块名、页面名及功能说明，只保留读屏标题和紧凑操作栏。项目详情、表单详情继续显示不与面包屑重复的业务编号、对象名称和状态
Preview.6	在 Preview.5 基础上，窄屏表格固定列统一降级为横向滚动列，顶部账号文本增加省略保护；通过 TypeScript、ESLint、Stylelint、Vitest 10 files / 56 tests、production build/hygiene、完整 Playwright 198/198（含 390px 固定列几何回归）；真实 Edge 复测权限与配置、系统更新、财务工作台和记账准备页面无整体横向溢出或控件重叠
Preview.8 安装向导	新增 PAGE-23 独立无库启动上下文；首次访问 /setup 以一次性安装码验证 MySQL 8.4 连接及 DDL/DML，执行 Flyway、创建自定义 SYSTEM_ADMIN 和全局权限，写入受限运行时配置并锁定向导；32 位 curl 路径不再把数据库密码放进命令行，安装完成后的修复重装优先读取运行时覆盖文件；通过 Java 编译、无库 HTTP smoke、TDesign 输入可访问性和 setup wizard Playwright 回归
超级管理员权限	V071 将 SYSTEM_ADMIN 固定为隔离超级管理员，逐条授予全部 iam_permission 和无额度 GLOBAL scope，并由启动同步补齐后续权限；前端菜单、直链和按钮统一放行全部 PAGE-04～21。管理员可管理跨人员表单/导入/付款草稿，PAGE-15 增加仅管理员可见的“全部付款”，三类业务工作台显示跨人员项目、资金、档案和全部待办；审批实际处理人、SOD、状态机、资金、附件安全和审计继续强制执行
OA-06 付款投影	V070 发布 OA-06 v2，新增生效合同、供应商和已确认应付稳定引用；财务终审在来源审批事务内生成 OFFLINE_PENDING 付款，执行付款检查、冻结项目资金并追加资金流水。余额不足等投影失败时来源状态、审批任务、付款、资金控制和流水整体回滚；不产生银行付款指令，不接网银、U 盾或第三方平台
OA 动态附件矩阵	OA-04/OA-06 的条件附件行支持 TDesign 布尔开关、长文本、不涉及原因和嵌套文件上传；仅 required=true 的行要求文件或原因，可选空行不阻断。上传状态按字段和表格单元隔离，上传期间锁定刷新、保存、校验和提交；更新请求不再携带创建专用字段，校验前自动保存当前草稿
本轮运行验收	最近完整后端 MySQL 8.4/Testcontainers 基线 213/213，Failures/Errors/Skipped 均为 0，迁移基线扩展至 V072；本轮新增 setup context smoke、安装器/包装器夹具和 PAGE-23 Playwright 回归；1.0.0-preview.8 已发布 9 个验签资产，Preview.9 进一步将公共仓库安装入口精简为单行 `curl
第一版 Preview	PAGE-01～22 页面和菜单框架齐备，真实前后端核心链保持可用；Preview 上线与整套 R1 最终验收分开计量
来源表格校验	V068 为 14 类 OA 的 33 个 TABLE 字段补齐嵌套类型、必填和文件引用规则；V069 保留 OA-02 v1 历史账户表格契约，避免 v2 字段追溯污染
PAGE-20 审计	增加不可变事件序号、四种稳定排序、URL 查询状态、同排序 CSV 导出、脱敏详情及 OpenAPI 422 参数门禁
PAGE-22 在线更新	更新源固定为公共 Gitea Latest Release API，默认不使用 Token；“获取版本”只读取最新版本信息，发现新版本后由管理员点击“立即更新”开始下载。下载、验签完成进入 READY/下载完成 后显示“立即更新并重启”。安装健康检查成功后页面从 10 秒倒计时自动刷新；刷新、短暂断线或命令响应丢失时恢复状态轮询。后台只写固定结构请求，由 root oneshot 服务验签、验哈希、备份、切换和回滚，不接受页面传入地址、Token 或命令
Release 工程	.gitea/workflows/release.yml 监听严格 SemVer v* tag；Maven revision、npm、JAR、前后端 SBOM、签名 manifest 与 tag 必须同版本。工作流执行 Java/前端/OpenAPI/Playwright/依赖审计，使用至少 3072 位 RSA 密钥生成并独立验收恰好 9 个资产；先创建不可见草稿、逐项上传并核对名称/大小，最后发布为可被 /releases/latest 读取的正式 Release
Linux 32 位	i386/i486/i586/i686 下载 Java 17 i686 JRE；JRE 元数据和归档均使用仅允许 HTTPS/TLS 1.2 及以上的受限下载器；由于 MySQL 8.4 无对应服务端镜像，要求预置外部 MySQL 8.4.x，curl 安装只开启 /setup 向导，数据库密码在浏览器中提交并完成连接、版本及 DDL/DML 预检
更新可靠性	下载和安装拆为两个持久动作；下载阶段不停止业务服务，安装阶段只接受同版本 READY 缓存并重新验签。公共 Gitea 默认不使用 Token；如改接私有镜像，Token 仅从权限为 0600 的 root 配置/临时文件读取，不进入 curl 参数、页面、状态或日志，且只允许同源 API/资产使用；请求原子领取到持久 processing，systemd 限制失败重试；mysqldump、新旧版本健康和回滚均有独立门禁，跨来源拒绝、成功、健康回滚、下载失败、备份失败和不安全请求夹具纳入 CI
阶段口径	把“开发前冻结”更新为“R1 开发中”；明确模块级验收与整套 R1 交付是两个层级，避免一页完成后虚报整套系统完成
PAGE-13 页面	完成合同执行汇总、筛选、服务端分页、来源下钻、CSV 导出、合同详情及变更/结算/应付操作；页面仅使用现有 TDesign Starter 和 TDesign 组件
PAGE-13 后端	新增 contractcost:payable:create，项目经理可登记但不可确认；同人登记/确认返回 422 SOD_VIOLATION；应付必须关联已批准 OA-04，结算必须关联已批准 OA-11，同一来源不得重复消费
PAGE-13 金额口径	展示层分列“待确认应付”和“已应付”；待确认应付仍预占合同额度，避免连续登记绕过限额
PAGE-14 页面	在唯一 TDesign Starter 内完成收款/发票双页签、筛选、服务端分页、详情抽屉、草稿录入/编辑、状态动作、金额格式化、CSV 导出及加载/空态/错误反馈
PAGE-14 后端	完成正式应收、收款确认与多对多核销、收款作废、开票提交/复核/人工结果、发票作废/红冲、自动生成应收与财务事件，并由 Java 后端执行权限范围、金额阈值、SOD、状态机和版本冲突控制
OA-04/05/08 审批投影	财务终审在同一事务内分别生成 CONFIRMED 应付、CONFIRMED 收款和 DRAFT 开票候选；来源版本、公司/项目/客户/合同快照、额度、SOD、资金台账、会计事件和重复消费由 Java/MySQL 共同约束
OA-08 合同口径	投影前锁定合同控制行，分别复核合同金额快照、已开票快照和包含 DRAFT/REVIEWING 候选的在途预占额；本次申请与在途候选累计超过合同额度，或快照过期时，终审整体回滚，不能留下已批准但无法继续复核的超额候选
PAGE-15 页面	在唯一 TDesign Starter 的付款申请弹窗中，把 OA 来源自由文本改为按当前项目加载的 TDesign 下拉；只显示已批准 OA-06，切换项目清空并重载，编辑历史草稿可回显已关联来源
PAGE-15 后端	OA 来源保持可选；一旦选择，保存草稿和财务批准时均要求 OA-06、同公司、同项目、当前版本存在 APPROVED 审批实例，并允许来源进入批准后的结果/归档后续状态；批准前发生版本替换会阻断付款
PAGE-15 付款主链	付款申请、项目/合同/应付/账户/通用附件/精确重复/项目风险检查、线下结果登记、异人复核、部分支付、失败、退汇和重付已实现；不产生银行付款指令，不接网银、U 盾或第三方平台
PAGE-15 条件附件	应付成本分类命中生效矩阵后，TDesign 页面逐项显示齐全/缺失/文件检查中并要求每个文件选择资料类型；Java 在保存时固化参数版本和分类规则快照，批准时按快照阻断缺件、矩阵外类型及未通过检查的文件
附件兼容与发布	历史付款及无生效规则路径继续按通用附件检查；生效矩阵下旧 attachmentFileIds 在保存时明确拒绝，必须改用结构化 attachments；包含 allowNotApplicable=true 的矩阵在例外复核闭环完成前禁止发布
PAGE-15 并发资金控制	资金控制行存在时以冲突更新先获取排他锁，再读取余额并冻结；两笔各 600 元付款并发竞争 1,000 元项目余额时，固定只有一笔批准、一笔返回 422 FUNDS_INSUFFICIENT，最终冻结额为 600 元，不出现超支或 500 死锁错误
数据库	当前最高迁移为 V071；V064 完成八类主数据旧编号映射，V065 完成人工记账结果冲销/重开，V066 增加审计全局时间线索引，V067 增加系统更新查看/执行权限，V068 补齐来源表格嵌套列的类型、必填和文件校验元数据，V069 保留 OA-02 v1 历史账户表格契约，V070 完成 OA-06 v2 与批准来源付款投影约束，V071 完成超级管理员全权限和全局范围回填；V062/V063 的部门及字典范围升级兼容继续保留
PAGE-12	部门复用 masterdata:dictionary:* 权限和全局范围，后端覆盖创建、列表/详情、编辑、提交、异人复核、停用、重复编码、版本冲突和审计；八类资源新增独立授权的版本分页接口，快照清除执行人相关 allowedActions；TDesign 页面新增部门页签、版本记录和双版本字段差异；MasterDataIntegrationTest 8/8、FinanceOperationsIntegrationTest 10/10、三档 PAGE-12 行为测试 3/3 通过，两个 Testcontainers 测试库均从空库迁移至 V063
PAGE-11	待办列表新增项目、任务状态、到达日期、逾期和排序服务端筛选，返回申请人、关键金额和当前节点；列表退回先读取最新任务详情，再按详情版本与字段退回点提交；workflow:task:view 按公司/项目数据范围校验；OpenAPI 已重新导出并通过合同门禁，真实财务账号组合查询无 Console 错误；后端查询专项 1/1、退回三档 E2E 3/3 通过
PAGE-16	状态机扩展为 COMPLETED → RESULT_REVERSED → EXPORTED；冲销恢复来源事件、重开递增结果轮次并清空当前结果，新旧证据和备注按轮次隔离，历史外部凭证号不得复用；两命令分别执行权限、公司/项目/金额范围、异人 SOD、版本、幂等和审计控制，理由按去空格后的至少 2 个有效字符校验；AccountingIntegrationTest 18/18、三档 PAGE-16 专项 12/12 通过，测试库从空库迁移至 V065
PAGE-17	财务管理人员在 PAGE-08 确认项目财务资料完整后，PAGE-17 才允许生成档案包；服务端执行权限、范围、状态、版本和审计校验，页面展示保管到期日及 PENDING/ACTIVE/DUE_SOON/EXPIRED/FROZEN 状态，到期仅提示、不自动删除；ProjectIntegrationTest#financeConfirmationIsRequiredBeforeArchiveGenerationAndUsesScopeVersionAndAudit 1/1 通过，测试库从空库迁移至 V061
兼容查询合同	/api/v1/contracts、/costs、/payables 保留现有 keyword/status/sort/page/size 合同；未知 query 参数固定返回 400 QUERY_PARAMETER_UNKNOWN，非法排序格式、字段、方向、重复项或超过 3 项固定返回 400 SORT_FIELD_NOT_ALLOWED，不再混用笼统错误码
生产密钥门禁	新增 production profile 回归：缺失 FIELD_ENCRYPTION_KEY 或使用仓库公开的本地开发默认值时，敏感字段组件初始化失败；注入 Base64 编码的 256 位密钥后，银行账户和来源敏感值两个加密组件均可初始化
PAGE-15 逐笔资金台账	核对 V037 追加式 fund_ledger、付款冻结/支付和收款变动写入、来源事件幂等键、范围权限、审计、/api/v1/funds/ledger 查询及 TDesign 资金流水抽屉；OpenAPI operationId 已统一为 listFundLedger，真实 MySQL 8.4 数据查询已验证
PAGE-18	扫描器不可用时，隔离文件仍建立带公司/项目范围的 file_link；重扫采用“持久化意图 → 同 FileStore 原子移动 → 独立事务确认”流程，崩溃后可从源或目标恢复；同幂等键保持首次 503/200/422 结果，成功后转为 AVAILABLE 并清空转存意图
PAGE-18 借阅闭环	资料身份申请、财务身份批准、资料身份登记归还的真实浏览器流程已完成；申请、批准、归还分别形成 ARCHIVE_BORROW_APPLY/APPROVE/RETURN 成功审计，申请人与审批人不同，最终状态为 RETURNED
PAGE-19	导出改为“服务端预检冻结 → 页面显示预计行数/排序/筛选/脱敏说明 → 用户确认 → 服务端重新校验并生成文件”；一次 POST 直接导出入口已移除
前端三档门禁	Playwright + axe 合同驱动覆盖 PAGE-01～22 的 1366×768、1440×900、1920×1080；完整 Playwright 套件已扩展为 198/198，另含 390px 固定列几何回归和超级管理员逐页打开全部业务页面，无 serious/critical WCAG 违规、整体横向溢出或 Console error
本轮验证	2026-08-17 最近完整后端全量基线 213/213（Failures/Errors/Skipped 均为 0），MySQL 8.4 Testcontainers 在 9 分 19 秒内完成全量回归并从空库执行 71 个 Flyway 迁移至 V071；OA-06 成功链、FUNDS_INSUFFICIENT 回滚链及超级管理员跨人员数据可见/审批处理人拒绝已通过集成测试；前端 ESLint/Stylelint、Vitest 10 files / 56 tests、TypeScript、production build/hygiene、npm 完整依赖树 0 vulnerabilities、Playwright 198/198、在线更新专项 15/15、真实 Edge 管理员 390px/1440px 页面复测、OpenAPI、ShellCheck、Actionlint、安装器/更新/Gitea 发布夹具均通过
证据文件一致性	三张本地浏览器证据按真实 JPEG 格式改为 .jpg；重扫图按实际像素命名为 archive-rescan-1366x612.jpg，批准/归还图保持实际 1366×768，总文档引用已同步
浏览器验收	PAGE-13 在真实 Java/MySQL 环境验证 OA-04 应付来源与 OA-11 结算来源的 TDesign 下拉、项目范围筛选及必填提示，未提交验收业务数据；默认桌面宽度和 1440×900 无整体横向溢出、按钮重叠或控制台错误
PAGE-15 浏览器验收	财务身份打开新建付款申请，选择 P-DEMO-001 后 OA-06 下拉只显示临时已批准来源，选择后正确回显；未保存草稿，桌面弹窗无控件重叠，Console 无 warning/error，临时付款和来源数据已清理
PAGE-15 剩余阻断	D-02/D-09 正式矩阵确认和发布、正式三档浏览器/异常状态证据和甲方验收仍未完成；PAGE-15 不升级为 MODULE_ACCEPTED
剩余质量项	Starter 演示页面/API/组件/资产已从 production 源码移除，全仓 ESLint、Vitest、release build、source/dist hygiene 及 Chromium 三档 Playwright + axe 基线已通过；真实 API 关键动作、键盘焦点、Edge、异常状态矩阵和正式 FE-GATE 证据仍未完成
前端硬规范	把“使用 TDesign”落成 Starter 实际布局基线、组件来源、菜单/页面新增步骤、原生控件、图标、Token、例外批准和机器合同规则；页面必须在唯一 Starter 内原位实现
新增功能规则	新增菜单、路由、页面、组件、按钮、筛选、图表时，必须同步页面合同、COMP-*/OPS-*、OpenAPI、权限、状态、审计和测试，禁止只摆界面后再补功能
页面与功能	保留 PAGE-01～PAGE-22、14 类表单和既有页面合同；新增页面、菜单或平行入口必须走变更，不得绕开本文件
第一轮交付	明确 R1 是前端、Java、MySQL、权限、流程、文件、审计、测试、部署和交付材料的完整闭环，不是静态页面或局部接口
修复责任	增加“复现 → 定位 → 修复 → 同类扫描 → 回归 → 部署 → 证据”的开发团队闭环，甲方不承担基础调试和补实现责任
范围边界	继续排除银行/U 盾、电子税务局、自然人税务系统、第三方权限/API、RPA 和自动执行；不因“完整系统”而扩回范围
资料状态	已从微信正式文件目录找回并复核 14 张 OA 表单图和 12 份财务岗位职责表，记录三份原始资料 SHA-256；项目管理流程图仍未找回，须在 D-03 前补齐或书面确认
当前基线复核	PAGE-12 已补部门主数据、升级库字典范围兼容和旧编号映射，PAGE-13/14 维持模块级已验收；OA-04/05/06/08 来源到财务对象的事务投影已实现并通过来源审批专项回归，但正式三档浏览器 UAT 和证据包仍待补齐；PAGE-15 的核心主链、OA-06 自动付款投影和条件附件技术能力已验证，但正式业务规则仍未发布；PAGE-16 已补已完成结果冲销/重开和分轮历史；PAGE-17 已补财务确认门禁和保管到期状态，PAGE-18 已补可恢复重扫和异人借阅闭环，PAGE-19/20/21 已形成 Preview 实现并等待正式验收；SYSTEM_ADMIN 已升级为全部页面/权限/全局数据可见且保留业务控制的隔离超级管理员。数据库当前最高迁移为 V071
基线材料	把签字版总方案、21 页原型、14 类字段/附件字典、fixture、状态/数据/OpenAPI 合同、D-01～D-11 和任务追溯表合并定义为唯一《R1 基线包》；材料不齐时，对应未确认模块不得通过模块验收或进入发布

1. 先说结论

1.1 甲方现在真正要的东西

甲方暂时不是要一套把所有财务、税务、银行和自动化都做完的大系统，而是要一套看得懂、用得起来、能把项目资料和财务流程串起来的基础系统。

系统首期只解决这一条主线：

业务人员提交资料
    → 项目/财务人员审批和复核
    → 形成收款、发票、成本、付款等财务数据
    → 形成可供记账的凭证资料
    → 项目完成后归档
    → 按项目、合同、金额和状态查询

会议原文明确了四个方向：

1. 先做简单版本，原有系统继续保留，避免用户一开始看不懂。
2. 登录后先选择身份，首期分为项目管理人员、财务管理人员、资料管理人员三类。
3. 14 个 OA 表单不是 14 个孤立页面，而是要按角色放进一条项目财务数据流。
4. 报税、网银/U 盾、第三方权限和跨系统自动化暂时不做；记账先做成可供现有系统或人工使用的结果。

1.2 我们最终要交付什么

交付类别	交付内容	甲方得到的结果
可运行系统	一个 Java Web 系统，可部署、可登录、可演示	三类人员从各自入口开展工作
项目业务	项目、供应商、合同、进度、收款、发票、付款等基础数据	项目资料不再散落在表格和聊天记录里
审批复核	表单提交、待办、审核、退回、驳回、状态跟踪	每个决定都有操作人、时间和意见
记账准备	财务事件、凭证草稿或标准导出、人工登记结果	财务可以接着现有记账系统工作
资料归档	项目档案包、附件版本、检索、下载和归档审核	项目结束后资料可查、可追溯
查询分析	项目台账、合同执行、收付款和流程进度	管理人员能看到项目处于什么阶段、钱和资料在哪里
交付材料	源代码、数据库、部署包、测试报告、模板、操作手册	甲方能够部署、验收和后续维护

1.3 首期不交付什么

以下内容明确排除在本期之外：

• 不登录、不控制、不保存网银、银企直连、U 盾、电子税务局、自然人税务系统。
• 不申请 OA、T+、HR 或其他第三方账号、Token、证书、Webhook、SSO 权限。
• 不做 RPA、自动付款、自动报税、自动缴税、自动过账和无人值守定时任务。
• 不做完整税务申报模块；税务资料以后可作为扩展模块。
• 不替换现有法定总账系统；首期输出记账准备数据和人工登记结果。
• 不首期建设完整人力资源、工资、固定资产、预算、融资和合并报表系统。

1.4 V2.8 冻结基线与 V2.9 执行关系

V2.8 冻结的范围、页面、技术和质量规则继续有效；V2.9 只把项目阶段更新为开发执行，并记录已经形成客观证据的 PAGE-14，不降低整套 R1 的完成标准。

1. 当前状态更新为“R1 开发中”；Starter 导入本身仍不算业务完成，只有通过模块级代码、数据、测试和浏览器验收的功能才计入实际进度。
2. 前端继续锁定为现有 TDesign Vue Next Starter 原位开发，只能在其中加菜单、页面、组件和真实功能；文件级保留、重写、删除和新增范围按 11.2 节执行，不引入第二套 UI 或平行前端。
3. 21 个页面补齐默认进入状态、主操作顺序、完成标志、TDesign 组件、路由、查询语义、接口组和验收条件。
4. 已逐张复核原始压缩包中的 14 张 OA 表单图，并回填可见字段、重复明细和人材机/进度款条件附件；原图没有给出的必填条件、枚举、金额公式、审批时限和下游映射仍按第 18 节资料可复核性规则在开工前签字，不把设计推导当成原表事实。
5. 权限判定、权限码、分域状态码、状态按钮、数据库列/约束/索引基线、R1 接口 DTO 规则、幂等并发、文件状态、安全参数和测试判定已统一。
6. 岗位职责资料按“R1 吸收、仅留内部记录、后续单独立项”分类，不把网银/U 盾、税务、工资社保或自动化执行重新带回第一轮。
7. D-01～D-11 和 S0 技术合同继续并行冻结；未签字、未形成字段字典、OpenAPI 快照和数据字典时，受影响模块不得验收或发布，不允许边开发边猜关键规则。
8. 每一个前端菜单、页面和可见操作都必须同时绑定本地路由、TDesign 组件、权限码、对象状态、OpenAPI operationId、成功/失败结果、审计事件和自动化测试；缺少任一项不得合并，也不得计入完成率。
9. “第一轮完整系统”的完成口径统一为第 12.9 节 R1 Definition of Done 全部满足，包含 PAGE-01～PAGE-21、OA-01～OA-14、真实前后端闭环、P0/P1 缺陷清零和可独立部署；阶段演示、单条样例或局部接口不得替代完整交付。
10. 前端增加唯一工程、唯一入口、依赖白名单、ECharts 使用边界、组件批准记录、逐操作状态矩阵、可访问性和验收证据包门禁，使“使用 Starter 和 TDesign”能够由 CI 与 UAT 客观检查，不依赖口头判断。
11. 每个页面和功能固定按“需求/页面合同 → 数据合同 → OpenAPI → Java 实现 → Starter/TDesign 页面 → 联调测试 → 证据验收”顺序完成；COMP-*、OPS-* 和路由页面合同在 S1 落为可由 CI 校验的机器文件，但不新增第二份 PRD/SPEC。
12. 会议原话、后续项目决策、方案设计基线和待确认事项按 2.3 节分级记录；21 个页面、完整 R1、Java 技术栈和 TDesign 唯一前端属于后续项目决策与设计冻结，不冒充 2026-08-05 会议逐字结论。
13. 开发团队在开工后承担“实现 → 自测 → 联调 → 修复 → 回归 → 交付”的完整责任，不能把局部页面、局部接口或甲方代测当成完成。
14. 仓库中的 Java、数据库、部署和接口代码按模块逐项评审：PAGE-13/14 已有完整证据的部分按本版记录为模块级完成；其他代码在通过所属任务评审和验收前仍不得计入 S1～S5 完成率。
15. 三类业务身份与超级管理员身份不混授：项目、财务、资料是普通业务身份；仅隔离的 SYSTEM_ADMIN 账号在 PAGE-02 显示“超级管理员”入口并默认进入 PAGE-21。进入系统后，超级管理员可访问全部业务菜单、页面、功能权限和全局数据，但不会被伪装成普通业务角色，也不能绕过审批处理人、异人复核、状态机、资金硬控制和审计。
16. 正式页面不得出现“页面已接入”“功能建设中”“后续实现”等占位提示，也不得保留空按钮、空表格或共用占位组件；这类内容只可存在于隔离原型，不能进入 production 或计入页面完成率。
17. Starter 的 side + light 布局、侧栏/顶部/内容区基线、TDesign Token、组件与图标来源、页面密度和目标分辨率已经冻结；新增菜单、页面、组件和功能必须执行 11.2 节七步流程和逐项变更表。
18. 第 3.6 节 A～F 统一称为《R1 基线包》；当前开发已启动，但未完成的基线材料必须继续收口，且总方案、页面、业务、技术合同、样本测试和执行计划未全部确认前，整套 R1 不得进入发布或整体验收。

1.5 当前是否可以进入正式开发

结论：第一轮正式开发已经开始，但整套 R1 尚未完成。 PAGE-13/14 已通过模块级验收；技术栈、前端实现方式、R1 总范围和交付责任继续按本文件执行。D-01～D-11、21 页原型、14 类字段/附件字典、完整 OpenAPI 快照、数据字典及其他页面实现仍须按第 3.6 节完成和确认。

判断项	当前结论	接下来要做什么
产品方向	已冻结	按“来源 → 审批 → 财务处理 → 记账准备 → 归档 → 查询”做完整 R1
前端规范	已冻结	当前及后续只在现有 frontend/ Starter 原位增加菜单、页面、组件和真实功能
技术架构	已冻结	使用第 11 章 Java 模块化单体、MySQL、Flyway、OpenAPI 和测试规范
业务细节	尚待甲方签字	完成 D-01～D-11，尤其是字段、金额公式、审批节点、导出格式和报表口径
当前开发状态	已启动	按“一个功能一条真实纵向闭环”继续开发；未通过证据验收的代码不计完成
当前已验收模块	PAGE-14	按 8.15.1、11.6.3、11.7.3.1、12.5 和 13.1.1 的实际记录维护
整体发布	尚未触发	《R1 基线包》和第 12.9 节全部通过后，才能形成唯一 R1 整体验收结论

“已进入第一轮开发”不表示可以跳过未完成的 S0 基线工作。每个后续模块仍须从已冻结的页面、数据、接口和测试合同开始；缺少关键决策时只阻断受影响模块，不允许开发人员自行猜测。

1.6 第一轮开发执行口径

这一节给甲方、产品、开发和测试统一使用，避免把“马上开发”“完整系统”和“使用 TDesign”理解成不同事情。

问题	固定答案
现在是否已经正式开发	已经开始。当前 R1 为 IN_PROGRESS，PAGE-14 为 MODULE_ACCEPTED，整套系统仍未交付
后续模块什么时候可以开始	其页面、数据、接口、权限、状态、fixture 和验收人已经明确时即可进入实现；关键规则未确认则阻断该模块
前端在哪里开发	只在仓库现有 frontend/ TDesign Vue Next Starter 中原位增加和修改，不新建第二工程、不换模板、不用 iframe 拼装
前端怎么做	按 7.3 节加菜单和路由，按 8.24～8.26 节逐页实现，通用控件和图标只使用 TDesign；业务组合组件也必须由 TDesign 组件组成
每个功能怎么完成	同一个功能按“页面/业务规则 → 数据库 → OpenAPI → Java → TDesign 页面 → 联调测试 → 验收证据”纵向做完，不把空页面、空接口或 Mock 留到最后补
第一轮交付什么	一次性交付第 12.9 节定义的完整 R1：21 个页面、14 类表单、真实数据闭环、权限、文件、测试、部署和交付材料全部可用
谁负责修改和修复	开发团队负责实现、自测、联调、定位、修复、回归和部署；甲方负责确认业务规则和验收业务结果，不替开发团队查代码、改库或补测试
哪些仍然不做	银行/U 盾、税务平台、第三方账号/API/SSO、RPA、自动付款、自动报税、自动缴税和自动过账继续排除

按 S1～S5 分阶段开发和内部演示，但对甲方只有一个“第一轮完成”结论：完整 R1 通过验收。PAGE-14 的模块级完成可以作为阶段进度和复用基线，不能单独称为已交付系统。

2. 会议结论转成产品规则

2.1 会议内容和系统决策

下表左列是会议原文的业务方向，右列是为便于开发而做的产品化表达。产品化表达包含必要设计推导，不等于会议逐字确认；其确认等级和生效规则统一按 2.3 节执行。

会议说法	转成开发规则
“先做简单的，后面再做加法”	首期只做 P0 闭环；每个功能必须有明确页面、输入、输出和验收，不把未来模块混进首期
“用户看不懂，做出来给他们看”	先做可演示原型和一家公司/一个项目样例，再用真实操作反馈迭代
“登录后选择身份”	登录后显示当前账号被授权的角色卡片；选择角色后进入对应工作台，服务端仍然再次校验权限
“至少两类，后面加资料审核”	首期固定三类普通业务身份：项目管理、财务管理、资料管理；SYSTEM_ADMIN 是隔离的超级管理员身份，只对纯管理员账号显示入口，不与业务身份混授，但自动拥有全部功能权限和全局数据范围
“14 个界面分成两类”	14 个表单按发起/财务审核/资料归档分配；页面可合并，但表单代码和数据关系不能混淆
“记账可以用现有系统做”	本系统生成凭证草稿/标准文件并登记人工记账结果，不调用现有系统接口
“报税先不管”	首期不开发申报执行；只保留税务字段扩展位，不把报税作为 MVP 验收条件
“把数据流打通”	每条记录必须能从来源单号追到审批、财务结果、记账准备和档案附件

2.2 用通俗话解释系统逻辑

• 项目管理人员：把项目资料填进来，补附件，跟进审批，查看自己的项目进度。
• 财务管理人员：检查项目、合同、供应商、金额、收款、发票和付款资料，确认哪些数据可以进入财务台账和记账准备。
• 资料管理人员：项目完成后检查资料是否齐全、文件是否可读、档案包是否完整，然后归档。
• 超级管理员：使用独立账号查看和管理全部业务及系统配置；系统自动展开全部权限码和 GLOBAL 数据范围。它仍以 SYSTEM_ADMIN 身份留痕，不冒充审批节点处理人，同人登记/复核、状态机、资金余额、附件和审计控制继续生效。
• 系统：负责记录谁在什么时候做了什么，不替人登录外部系统，也不替人自动付款或报税。

2.3 需求来源与确认等级

为了让普通使用者、产品、开发和测试都能分清“甲方说过什么、方案补充了什么、还有什么没定”，本文件中的要求按以下四级管理：

等级	含义	本项目中的典型内容	是否允许开发自行修改
CONFIRMED-MEETING	2026-08-05 会议明确提出的业务方向	先做基础版本、原系统保留、按身份进入、14 类表单进入数据流、报税先不做	不允许；变化必须走需求变更
CONFIRMED-PROJECT	会议后由项目方继续明确的实施决定	Java 技术栈、现有 TDesign Starter 唯一前端、第一轮交付完整 R1、2026-08-11 进入开发执行、第三方权限和自动化排除	不允许；变化必须由项目负责人书面确认
DESIGN-BASELINE	为把业务要求变成可开发系统而形成的产品/技术设计	PAGE-01～21、菜单路由、模块边界、接口、数据表、权限、状态机、测试和部署规则	文档批准后即为开发基线；只能按变更流程修改
PENDING-DECISION	仍需甲方拿样例和选项确认的具体规则	D-01～D-11 的人员、字段、金额、流程、导出、报表、文件、容量和品牌	不允许猜测；未确认时阻塞受影响模块验收和整套 R1 发布

本文件对来源的处理规则如下：

1. 会议原文优先用于确认业务目标和范围方向，不从含糊表述中擅自推导具体金额、状态、字段或接口规则。
2. 2026-08-10 后续项目决策明确：第一轮不是只交原型或局部模块，而是交付第 12.9 节定义的完整 R1，前端必须采用当前已拉取的 TDesign Vue Next Starter；2026-08-11 最新执行决定进一步启动 R1 开发，并要求已完成模块按客观证据写回本文件。上述内容均属于 CONFIRMED-PROJECT，不是会议逐字原话。
3. PAGE-01～PAGE-21、六类报表、权限码、SOD、审计、文件版本和工程门禁属于 DESIGN-BASELINE。甲方批准本文件后即具有约束力，但不能写成“会议已经逐项确认”。
4. 记账首期固定为“凭证草稿/标准导出 + 人工登记和复核结果”，不接现有记账系统接口，不自动过账；其最终文件样式和字段仍由 D-07 确认。
5. 需求冲突时按“最新书面项目决策 → 已批准的本文件 → 会议原始方向 → 开发个人理解”处理；如冲突影响范围、权限、金额、状态或交付日期，先停止相关实现并完成变更确认。

3. 首期范围和后续范围

3.1 MVP 必须做完的闭环

MVP 范围必须全部完成。“一家公司、一个项目、一组完整样例”只是最低端到端验收数据集，不表示只开发一家公司、一个项目或只实现样例触发的功能。该数据集必须能跑通：

1. 登录并选择三类身份。
2. 创建或导入项目、供应商、合同基础资料。
3. 提交并审批项目立项、供应商准入、成本合同等表单。
4. 记录人材机成本确认、收款确认、发票申请、进度款支付。
5. 财务人员审核金额、附件、合同和项目关联关系。
6. 生成财务台账和凭证草稿/记账导出文件，人工登记记账结果。
7. 项目资料归档，资料人员完成归档审核。
8. 按项目查询全过程和未完成事项。

3.2 后续再做的加法

阶段	扩展方向	本期处理方式
V1	银行流水人工导入、对账、更多凭证规则、项目成本分析	预留数据结构，首期可先用人工台账
V1	工资、社保、固定资产、折旧摊销	只接收人工结果，不做完整子系统
V2	税务日历、税会核对、申报资料包	不接税务平台，不自动申报
V2	报表、经营分析、移动端	先完成基础查询和导出
单独项目	OA/T+/银行/税务 API、RPA、自动化执行	重新立项、重新评估第三方权限和安全责任

3.3 现有系统如何处理

旧系统不删除、不替换、不要求一次性迁移。首期新系统作为“项目财务资料和流程中台”：

• 旧系统继续承担已有工作。
• 新系统接收人工导出的数据和附件。
• 新系统把财务审核、台账、记账准备、归档和查询做清楚。
• 未来要不要替换旧系统，等 MVP 使用稳定后再决定。

3.4 当前模块是否齐全

结论：整套财务系统的模块仍未齐全，但已经不再是全部待开发。 PAGE-14 收款与发票已通过模块级验收；其余页面必须按各自实现和证据判断。当前仍不能证明 PAGE-01～21 和完整端到端业务闭环已经全部实现，也不能把“Starter 能打开”“接口能返回”“有一张表格”或“某个页面完成”扩大解释为整套系统完成。

业务区域	当前材料能证明什么	当前缺口判断	本期要开发的结果
14 类 OA 表单	有表单样式、字段和审批业务基础	表单之间仍是分散数据，未形成统一编号、版本和下游关系	模板化录入/导入、校验、审批快照、内部处理和归档
人员岗位职责	有财务岗位分工资料	系统角色、数据范围、金额权限和岗位互斥尚未落地	三类业务身份、管理员账号和服务端权限控制
项目与主数据	表单中反复出现项目、供应商、合同、账户	重复录入、编码和历史版本没有统一控制	公司、项目、往来单位、合同、账户和字典中心
审批与财务复核	OA 可提供原审批痕迹	来源审批、内部财务复核和补件状态未串成一条链	来源快照、待办、退回/驳回、财务确认和审计记录
收款、发票、成本、付款	PAGE-13/14 已完成合同成本与收款发票模块级验收；付款仍须按 PAGE-15 单独验收	PAGE-13/14 不再是缺口；PAGE-15 和跨模块全链路仍未据此自动完成	保持 PAGE-13/14 回归稳定，继续完成付款检查、线下结果登记及异人复核的独立验收
记账	现有记账系统可继续使用	业务单据到记账资料之间仍需人工重新整理	财务事件、凭证草稿、标准导出和人工凭证结果登记
资料归档	有附件和资料岗位职责	缺少统一档案包、文件版本、检索、借阅和下载留痕	项目档案包、缺件检查、归档审核、检索和借阅
查询分析	主要依赖表格临时汇总	数据口径、下钻和权限不统一	项目、合同、收付款、流程和资料完整性报表
银行、税务和外部自动化	业务客观存在	涉及第三方权限和执行责任	本期不开发，只保留人工结果和附件的内部记录

3.5 第一轮开发必须交付什么

第一轮开发不是只交一套页面、一个原型或几个接口，而是交付一个前端、后端、数据库、文件、权限、测试和部署全部可用的完整 R1 系统。这里的“完整”指第 12.9 节 R1 Definition of Done 全部完成，包括 P0/MVP 全范围、P0/P1 缺陷清零和完整交付证据；不代表把明确排除的银行、税务平台和第三方自动化重新纳入范围。

完整性维度	第一轮必须达到的结果
前端完整	基于 TDesign Vue Next Starter 完成 PAGE-01～PAGE-21，菜单、按钮、表单、列表、详情和异常状态都可操作
后端完整	Java 模块、权限、状态机、金额规则、审计、文件和导出接口全部实现，不用 Mock 代替正式业务
数据完整	Flyway 可从空库建立数据库；主数据、14 类表单、审批、财务记录、记账准备和档案关系可持续保存
流程完整	“来源资料 → 审核 → 财务处理 → 记账准备 → 归档 → 查询”能用真实接口端到端跑通
权限完整	项目、财务、资料三类身份及系统管理员按功能、公司/项目、金额和流程节点生效，越权由后端拒绝
交付完整	可在 staging/production 部署，具备初始化、备份恢复、日志监控、测试报告、操作手册和验收证据

第一轮内部仍按 S1～S5 分阶段开发和演示，但这些阶段不是五个可以单独验收的残缺产品。对甲方的第一轮正式交付只有一个：S1～S5 全部完成后的 R1 完整系统。

以下情况不算第一轮完成：只有静态页面；页面仍调用 Mock；按钮没有后端逻辑；只完成部分 OA 表单；权限只隐藏菜单；数据刷新后丢失；关键流程靠开发人员改数据库；不能独立部署；P0 或 P1 缺陷未清零。

R1 继续排除：网银/U 盾、银企直连、电子税务局、自然人税务系统、第三方账号/API/Token/SSO、RPA、自动付款、自动报税、自动缴税和自动过账。它们不是“完整系统”的缺口，而是已经签字确认的范围外事项。

3.6 当前阶段和第一轮基线门槛

当前处于R1 开发执行阶段。frontend/ 是唯一 TDesign Vue Next Starter 前端，Java/MySQL 和业务页面按模块纵向实现。PAGE-13/14 已有模块级验收事实，但它们不代表 PAGE-01～PAGE-21、全部 Java 模块、数据库关系和端到端业务闭环已经完成。

仓库代码统一按证据分级：通过页面、接口、数据、权限、状态、自动化测试和浏览器验收的模块可记录为 MODULE_ACCEPTED；只具备局部页面、局部接口或技术可行性的代码仍按“待评审实现”处理。任何模块在通过所属任务验收前，不能据此把整个阶段或 R1 标记为完成。

低保真原型继续只用于确认尚未开发页面的结构和业务理解，必须与 production 真实链路明确区分；已进入正式开发的页面不得再使用 Mock、静态占位或原型状态冒充业务结果。

以下六项现在作为各模块验收和 R1 整体发布的共同基线；缺项时阻断受影响模块验收，并阻断整套 R1 发布：

1. D-01～D-11 全部有书面结论和确认人，不残留 TBD、口头规则或“开发中再定”的临时默认值。
2. PAGE-01～PAGE-21 的低保真原型使用 TDesign Starter 框架完成，三类身份分别走查并签字。
3. OA-01～OA-14 每类具备脱敏的成功、必填失败、重复、越权四类 fixture 和正式字段字典；付款、凭证、档案另具备成功、业务阻断、并发冲突和 SOD fixture。每个 fixture 都已写清前置数据、执行身份、输入、预期页面/HTTP/业务状态、金额、下游对象和审计事件。
4. 关键金额公式、状态机、岗位互斥、附件矩阵和记账导出格式已经冻结。
5. 前后端目录、逐表数据字典、分域状态机、OpenAPI operation/DTO、Flyway 规则、错误码、测试门槛和发布方式按第 11 章冻结。
6. R1 范围、负向范围、Definition of Done 和 UAT-001～UAT-035 进入项目管理工具并关联负责人。

六项基线全部通过后，项目经理形成书面《R1 基线确认》，至少记录文档版本、决策项版本、样本版本、原型/页面评审结论、开发启动日期和各模块负责人。当前已启动开发不免除这项工作；没有完整确认时，整套 R1 不得进入 production 发布或最终验收。

为避免开发和验收时分散寻找材料，上述六项统一组成一份《R1 基线包》，只允许引用这一份总方案中的编号，不再另写一套含义不同的 PRD/SPEC：

基线包分册	必须包含	通过标志
A. 需求基线	本文件 V2.9 签字版、R1 正向/负向范围、PAGE/F/OA 编号和变更记录	甲方负责人、产品、技术和测试签字，文档哈希固定
B. 页面基线	PAGE-01～PAGE-21 低保真原型、三类业务身份与系统管理员逐页走查、菜单/路由/模板/组件清单	每页有进入状态、主操作、完成结果、异常状态和验收人
C. 业务基线	OA-01～OA-14 字段/附件字典、状态机、金额公式、权限/SOD、D-01～D-11 结论	没有 TBD、口头默认值或“开发时再定”
D. 技术合同	逐表数据字典、ER 关系、OpenAPI 快照、错误码、routes/components/operations 机器合同设计	前端、后端、DBA、测试共同评审，无互相矛盾字段
E. 样本和测试	脱敏 fixture、UAT-001～035 前置数据、账号/身份/范围、预期状态、金额和审计断言	样本可重复初始化，成功、失败、重复、越权和并发均有明确预期
F. 执行计划	S1～S5 任务、负责人、主责闭环人、前置项、环境、证据位置、缺陷处理和发布时间	每项可进入 READY，且所有关键路径都有负责人和验收人

《R1 基线确认》只在 A～F 全部通过后签发。若变更页面数量、表单含义、金额公式、权限、状态或范围，必须先更新本文件和受影响合同，再继续受影响实现；开发人员不能用聊天记录或临时口头决定覆盖基线包。

任何人口头提出的新功能先登记为变更，不直接插入当前迭代。影响 R1 范围、金额口径、权限或状态机的变更，必须评估页面、接口、数据迁移、测试和交付日期后，由甲方和项目负责人共同确认。

开发执行期允许和禁止的工作

类别	当前允许	当前禁止
需求	修改本文件、补字段字典、流程、页面、权限、状态、验收和决策项	口头规则不落文档就直接开发
原型	为尚未实现页面制作与 production 链路隔离的低保真走查稿，明确标记“原型”	用 Mock、静态 JSON、硬编码数据或原型页面宣称正式业务功能完成
样本	整理、脱敏、编号 OA-01～OA-14 成功/失败/重复/越权样本	把原始账号、密码、身份证、银行卡等敏感资料提交到仓库
技术	按页面/数据/OpenAPI 合同实现 Java、Flyway、TDesign 页面并完成真实联调	绕过合同、权限、状态、测试或审计直接实现；把局部成功扩大为阶段完成
项目管理	建立 TODO、负责人、前置项、验收人和证据位置；按 MODULE_ACCEPTED 记录已通过模块	没有完整证据就把任务、阶段或 R1 标为已完成

本阶段的过程交付物包括本文件、原型、字段/附件字典、脱敏样本、D-01～D-11 决策记录，以及通过模块验收的源代码、迁移、测试和证据。开发团队负责从实现、联调、测试、缺陷修复一直处理到第 12.9 节 Definition of Done；甲方负责确认业务规则和验收结果，不负责替开发团队定位代码、改数据库或补齐未实现按钮。

3.7 当前工程差距基线

截至 2026-08-17，仓库使用唯一 frontend/ Starter，R1 已进入开发。PAGE-12 已补部门主数据、升级库字典范围兼容、旧编号映射和三档动作回归；PAGE-13 已按 8.14.1 和 13.1.2、PAGE-14 已按 8.15.1 和 13.1.1 形成模块级验收；OA-04/05/06/08 来源终审投影已完成代码和专项回归，但正式页面 UAT 仍未签字；PAGE-15 已按 8.16.1、13.1.3 和 13.1.9 完成核心付款链、条件附件技术能力及 OA-06 付款投影定向验证，但仍为 IN_PROGRESS；PAGE-16 已形成 COMPLETED → RESULT_REVERSED → EXPORTED 冲销/重开闭环；数据库当前最高迁移为 V071，并完成隔离超级管理员全部权限、全局数据范围和三类业务工作台跨人员数据可见。PAGE-17 已补齐财务确认门禁、归档状态机和保管到期提示，PAGE-18 已补齐隔离文件可恢复重扫和本地异人借阅/归还闭环，PAGE-19/20/21 已进入 Preview 阶段验收，相关页面均未达到 MODULE_ACCEPTED。其他页面仍按下表逐项评审，任何“已有页面/接口/测试”都不自动等于模块完成，更不等于整套 R1 完成。

当前现状	与 R1 的差距	对应处理
PAGE-01～06 已出现 Session/CSRF、身份选择和工作台真实接口实现	尚缺正式 OpenAPI、权限/状态矩阵、全异常状态和对应模块自动化验收的完整证据	TODO-S1-007～TODO-S1-012、TODO-S1-019～TODO-S1-023 逐项评审，不直接标记完成
PAGE-01～21 已声明本地路由和菜单，已建立 routes.json、components.json、operations.json 初版机器合同，并由 Vitest 校验页面、运行时路由及 API wrapper 映射	Starter 演示源码清理和 source/dist hygiene 门禁已完成；机器合同尚未覆盖全量 query 白名单、逐操作状态/fixture/拒绝码，逐操作 allowedActions、权限版本失效测试和全量正向/越权证据仍未完成	TODO-S0-017、TODO-S1-022、TODO-S1-028、UAT-029、UAT-035
PAGE-07～08 已有独立项目列表/详情实验；PAGE-09～11 已有表单中心、动态填写/导入和审批任务实验，并接入来源表单、两阶段导入及审批命令	PAGE-07/08 尚缺正式十页签、导入导出和全异常验收；PAGE-09～11 尚缺经 D-02/D-03 冻结的 14 类完整字段/附件/路线、逐操作合同、正式 OpenAPI 和全部 fixture。已有正常路线不能代表 S2 完成	TODO-S2-006～TODO-S2-028、8.24～8.26 节、UAT-004～UAT-010、UAT-026
PAGE-14 已有独立 ReceiptsInvoicesPage、真实 API、分域 DTO、服务端 allowedActions、应收/核销/发票命令、V017 数据结构增量、专项测试和浏览器证据	模块级功能已经验收；初版机器合同已建立，但全量操作字段、前端组件覆盖率和三档正式桌面 UAT 证据包尚未完成，因此不满足整套 R1 DoD	维持 MODULE_ACCEPTED，按 8.15.1、11.6.3、11.7.3.1、13.1.1 回归；全局门禁归 TODO-S1-023/028、TODO-S5-018/019/021 收口
PAGE-13 已有独立 ContractCostLedgerPage、真实 API、分域 DTO、服务端 allowedActions、合同/变更/结算/应付命令、V034/V035 迁移、专项/全量测试和浏览器证据	模块级功能已经验收；三档 Chrome/Edge 标准证据包仍归全局 UAT 收口，不因本页完成而满足整套 R1 DoD	维持 MODULE_ACCEPTED，按 8.14.1、13.1.2 回归；继续 PAGE-15 和 TODO-S3-011/015
PAGE-18 已有独立 TDesign 文件检索/借阅页、空条件不查敏感文件、扫描/归档状态筛选、版本详情、受控水印预览和隔离文件重扫；工作台“隔离文件”已按 scanStatus=QUARANTINED 精确跳转	本地浏览器已验证检索、详情、水印预览、重扫、异人批准借阅和归还；范围外直链下载回归及 Chromium 三档空态 axe/溢出门禁已通过。真实数据 Chrome/Edge 三档全流程、正式负向 fixture 和标准证据包仍待完成	状态为 IMPLEMENTED_PENDING_ACCEPTANCE；保持 TODO-S4-011/012 未完成，按 13.1.4、UAT-020～022 收口
PAGE-19 已有独立 TDesign 报表页、六类报表、后端汇总、同筛选下钻、中文状态、两位小数和权限范围哈希；已实现服务端预检、冻结排序/筛选/列/预计行数、页面确认及确认时重新鉴权的两阶段导出，MySQL 8.4 全量集成回归已通过	D-08 尚未确认；日期口径仍混合业务日期与更新时间；流程时长真实样本、三档真实数据浏览器和标准证据包未完成	状态为 IMPLEMENTED_PENDING_ACCEPTANCE；保持 TODO-S4-013/014/015 未完成，按 13.1.4、UAT-023 收口
PAGE-12、PAGE-15～21 已分别使用 MasterDataPage、PaymentsPage、AccountingPage、ProjectArchivesPage、ArchiveFilesPage、ReportsPage、AuditLogsPage、SystemSettingsPage	独立页面和初版 API 合同不等于验收完成；正式 DTO、详情、下钻、受控导出、逐页筛选、全量数据范围、失败状态和 UAT 证据仍须逐页核验	TODO-S2-001～TODO-S2-005、TODO-S3-008～TODO-S3-017、TODO-S4-001～TODO-S4-016
PAGE-15 已有独立 PaymentsPage、分域前端 API/机器操作合同、payment/fund 后端模块、V012/V036～V041/V053/V054/V070 数据结构和 PaymentIntegrationTest；核心付款链、OA-06 当前批准版本及终审付款投影、条件附件规则/快照、并发余额控制、逐笔资金台账及例外机制已通过付款 29/29、来源审批 37/37 专项和页面/HTTP 验证	正式附件矩阵仍待 D-02/D-09 确认和发布；三档浏览器、异常状态和标准证据包尚未完成	维持 IN_PROGRESS，按 8.16.1、13.1.3、13.1.9 和 TODO-S3-011/015 继续收口
已新增基于 TDesign Input 和 decimal.js@10.6.0 的 MoneyInput，PAGE-14 已使用十进制字符串	PAGE-14 金额由 Java BigDecimal 最终复算并通过专项回归；跨页面 COMP-*、组件测试、可访问性和全部金额页面迁移仍未完成	PAGE-14 保持回归，组件级全局工作归 TODO-S1-020、TODO-S1-028
新增运营查询服务目前使用 Map<String,Object> 读模型，并由前端做 snake_case 到 camelCase 归一化	尚未达到 11.7.4 合同：后端应返回分域 DTO，财务金额应为十进制字符串，筛选/排序字段应逐项枚举；公司/项目数据范围过滤尚未对所有查询分支形成完整证据	TODO-S0-024、TODO-S1-019、TODO-S4-014、UAT-003、UAT-023
Starter 演示 API、页面、组件、资产及 /dashboard/base 死链已从 production 源码移除，source/dist hygiene 门禁、release build 和 Chromium 三档 Playwright + axe 路由基线已通过	仍需把真实 API 动作、Chrome/Edge、键盘、Network/Storage 和逐按钮证据纳入正式 FE-GATE 包	TODO-S1-023、TODO-S1-028、TODO-S5-018～021、UAT-028、UAT-034、UAT-035
npm test 已接入 Vitest，当前 9 files / 53 tests 通过；Playwright + axe 已接入 test:e2e/test:a11y，合同驱动三档路由基线 63/63、完整 Playwright 套件 183/183 通过	当前 Playwright fixture 已覆盖路由基线及 PAGE-07/08/09/10/11/12/13/14/15/16/17/18/20/21 定向行为，但仍不替代真实 API 全业务矩阵、正式 Chrome/Edge UAT、键盘路径和逐操作权限证据	TODO-S1-023、TODO-S5-001、TODO-S5-018～020
frontend/contracts/routes.json、components.json、operations.json 已形成初版并由 Vitest 校验；OpenAPI 生成客户端尚未形成	初版合同已能校验页面、路由、基础组件要求和 API wrapper，但完整 OPS 状态矩阵、query 合同、OpenAPI 类型及生成无差异门禁仍待完成	TODO-S0-017、TODO-S0-024、TODO-S1-019、TODO-S1-028
前端生产构建可完成，但当前主包仍明显超过 11.11 节预算	页面和图表尚未完成代码拆分，也未生成正式 FE-GATE 证据	TODO-S1-023、TODO-S1-027、UAT-034、UAT-035
仓库已包含 IAM、项目、主数据、来源表单、审批、文件、工作台、运营查询、合同成本、PAGE-14、付款、记账、档案、报表、审计、在线更新及 V001～V071 迁移	当前编译和已执行的定向验证只证明对应基线可回归，不证明每个页面均满足 PAGE 合同、浏览器 UAT 和 R1 DoD	PAGE-13/14 之外继续按第 11～13 章逐项形成“保留/重写/补齐”结论和验收证据

后续工程基线评审必须逐项给出“保留/重写/补齐”结论、负责人和验证证据。除明确标记 MODULE_ACCEPTED 的 PAGE-14 外，表中代码即使能够登录、返回数据或通过局部测试，也不能自动标记页面完成；在第 12.9 节全部满足前，不得称为“第一轮完整系统”。

4. 三类业务身份与系统管理权限

4.1 登录流程

flowchart LR
    A["输入账号密码"] --> B["校验账号是否启用"]
    B --> C["显示该账号可用的角色卡片"]
    C --> D["选择项目管理人员"]
    C --> E["选择财务管理人员"]
    C --> F["选择资料管理人员"]
    C --> J["选择系统管理"]
    D --> G["项目管理工作台"]
    E --> H["财务管理工作台"]
    F --> I["资料管理工作台"]
    J --> K["系统配置"]

“选择身份”只是让用户进入容易理解的工作界面，不是绕过权限。比如一个人同时被授予项目管理和财务管理角色，必须分别进入两个工作台；服务端按角色、公司、项目和流程节点再次判断能否操作。

R1 固定行为：所有账号每次新登录都先进入 PAGE-02。单身份账号只显示一张可用身份卡，用户点击“进入系统”后进入对应工作台；多业务身份账号显示全部已授权业务卡片供选择。仅超级管理员账号显示一张“超级管理员”卡并默认进入 PAGE-21，不显示三类业务卡，也不得与任何业务身份授予同一账号；该卡只是隔离身份入口，不是页面权限上限，进入后侧栏展示全部业务和治理菜单。系统不因只有一个身份而自动跳过 PAGE-02，避免用户不清楚当前身份。会话未失效时刷新页面保留当前身份；主动切换身份必须重新经过 PAGE-02，并清空上一身份的页签、页面缓存和待办查询。

4.2 角色权限矩阵

功能	项目管理人员	财务管理人员	资料管理人员	超级管理员
查看本人/授权项目	可查看	可查看授权公司/项目	可查看授权归档范围	查看全部公司、项目和跨人员记录
新建项目和业务表单	可新建、补件、提交	可代录入但需留痕	不负责	可新建并管理跨人员草稿/导入，全部动作留痕
项目立项/供应商/合同业务审核	查看进度，不审批本人	审核财务条件和金额	只审核资料完整性	可查看全部任务；流程审批仍只允许实际节点处理人
收款、发票、付款财务处理	查看状态	负责审核和登记	不负责	具有全部功能权限；同人登记/复核和资金硬控制继续生效
记账准备/凭证草稿	不可修改	生成、复核、导出、登记结果	只读关联资料	可访问全部功能；制单/复核和登记/复核仍须异人
项目完成归档	提交归档	确认财务资料完整	接收、审核、归档	可访问全部档案功能；同人提交/审核限制继续生效
删除正式数据	只能删除草稿	只能作废/冲销	不能删除	不增加物理删除正式数据能力，仍按作废/冲销/版本处理
用户和权限配置	不可	不可	不可	可管理用户、角色、范围、模板、参数和在线更新

超级管理员的“全部权限”指功能权限、菜单页面和数据可见范围完整，不等于跳过业务完整性控制。Java 后端仍逐项执行状态、版本、幂等、实际审批处理人、SOD、合同/应付/资金余额、附件安全和审计规则。

4.3 权限判断的四个问题

每次查询或操作都必须回答：

1. 这个人有没有这个功能权限？
2. 他能看哪家公司、哪个项目？
3. 这笔金额是否超过他的授权额度？
4. 当前流程是否已经到他可以处理的节点？

4.4 三类入口与实际岗位权限的关系

三类身份是让普通用户容易理解的工作台入口，不是把所有财务人员都授予同一套万能权限。后台仍按甲方实际人员逐人组合岗位权限、公司/项目范围、金额阈值和流程节点。首期至少预置以下岗位权限模板：

岗位权限模板	进入的身份工作台	首期主要权限	必须禁止
项目经办/负责人	项目管理	发起项目、14 类业务表单、补件、查看本人项目	审批本人申请、登记付款/记账结果
成本/应付审核	财务管理	审合同、成本、应付、发票和付款附件	登记并复核同一笔线下付款结果
收款/开票经办	财务管理	确认收款、应收核销、开票申请和人工开票结果	自批本人录入的例外和结果
线下付款结果登记	财务管理	对已批准单据登记线下付款结果和回单	在系统内发起银行指令；复核本人登记结果
结算/资金复核	财务管理	复核项目余额、合同可付额、付款结果和退汇	修改已批准来源金额、代替记账复核
记账会计	财务管理	生成/编辑凭证草稿、导出、登记外部凭证号	同时制单和复核同一张凭证
财务负责人	财务管理	金额阈值内终审、批准允许例外、查看汇总报表	绕过永不允许例外的账户/SOD/重复硬控制
资料管理员	资料管理	缺件检查、档案审核、检索、借阅和归还	修改合同、金额、付款和凭证状态
超级管理员	PAGE-02 的隔离入口，默认进入 PAGE-21，侧栏展示全部页面	全部功能权限、全局数据范围、跨人员草稿/导入管理和系统治理	与任一业务身份共用账号；冒充审批节点处理人；绕过 SOD、状态机、资金、附件或审计控制

一个业务账号可以被授予多个业务岗位模板，但每次只能在一个业务身份上下文中工作；互斥模板不能同时对同一业务对象生效。超级管理员必须使用独立账号，不能与任何业务身份或岗位模板组合；系统通过 SYSTEM_ADMIN 自动展开全部权限码和全局范围，不通过混授普通角色实现。是否展示按钮由当前身份和权限摘要共同决定，是否允许执行永远由 Java 后端重新判断。D-01、D-03、D-05 必须把实际姓名、岗位模板、公司/项目范围、金额阈值和互斥关系确认到人。

4.5 服务端授权判定顺序

每个查询、下载和写命令都按同一顺序判断，任一步不满足即拒绝，默认规则是“没有明确授权就是无权”：

1. Session 有效、账号启用、密码不处于强制修改状态。
2. 当前会话已经选择一个有效身份，且该身份仍在账号授权范围内。
3. 当前身份具有本动作的权限码。
4. 请求对象所属公司/项目落在该权限授权的数据范围内。
5. 涉及金额时，金额不大于该动作在该公司/项目下的授权阈值；等于阈值允许，大于阈值进入更高审批节点或返回 403，不能由前端自行放行。
6. 业务对象当前状态和流程节点允许该动作，当前用户是节点处理人或明确授权的候补处理人。
7. 岗位互斥、自审自批、同人登记/复核、制单/复核等禁止规则没有命中。
8. 写命令的版本号、幂等键、前置数据和附件仍然有效。

同一普通身份下可以组合多个岗位模板：功能和数据范围只合并明确授予的正向权限；禁止规则、岗位互斥和对象级拒绝优先于允许。金额阈值必须绑定“权限码 + 公司/项目范围”，不能把一个项目的高额度带到另一个项目。SYSTEM_ADMIN 在第 3～5 步自动按“全部权限码 + GLOBAL + 无 IAM 人员授权额度上限”判定，但第 6～8 步的节点处理人、SOD、状态、版本、幂等、业务余额和附件规则完全不变。超级管理员身份和普通业务身份禁止同时存在于同一账号；授权变更保存成功后立即使相关旧会话失效，用户重新登录后生效。每次拒绝至少记录用户、当前身份、权限码、对象、请求编号和拒绝原因，但响应不泄露无权对象的敏感内容。

4.6 权限码目录

权限码固定使用 模块:资源:动作，不使用页面名称或中文作为持久化权限值。OpenAPI、路由 meta.permission、按钮指令、后端鉴权和测试样本必须引用同一权限码。

权限域	R1 权限码动作集合	主要页面
项目	project:project:view/create/edit/submit/export、project:risk-flag:view/create/resolve	PAGE-04、07、08
来源表单	source:form:view/create/edit/import/validate/submit/withdraw/void	PAGE-09、10
审批任务	workflow:task:view/approve/return/reject/reassign	PAGE-11
主数据	masterdata:company:*、project:*、counterparty:*、bank-account:*、contract:*、dictionary:*；动作限 view/create/edit/submit/review/activate/disable	PAGE-12
合同成本	contractcost:ledger:view/export、contractcost:payable:view/create/confirm	PAGE-13
收款发票	receivable:receipt:view/create/edit/confirm/allocate/void/export、receivable:invoice:view/create/edit/submit/review/record-result/void/red-letter/export	PAGE-14
付款	payment:request:view/create/review/approve/record-result/verify-result/refund/export	PAGE-15
记账准备	accounting:event:view/generate、accounting:voucher:view/edit/review/export/record-result/verify-result/reverse-result/reopen-result/void	PAGE-16
档案文件	archive:package:view/create/submit/review/archive、archive:file:view/preview/download、archive:borrow:apply/approve/return	PAGE-17、18
查询报表	report:finance:view/export	PAGE-19
审计	audit:log:view/export	PAGE-20
系统治理	admin:user:*、admin:role:*、admin:scope:*、admin:template:*、admin:parameter:*；动作限 view/create/edit/enable/disable/publish；在线更新固定使用 admin:update:view/execute	PAGE-21、PAGE-22
敏感字段	sensitive:identity:view、sensitive:bank-account:view、sensitive:payroll:view	PAGE-08、12、15、18

表中的 * 只是在本文件中压缩展示，数据库和接口中禁止保存或判断通配符权限；S0 冻结时必须展开成逐条权限码。查询默认只授予脱敏视图；查看完整敏感字段、下载、导出、审批和结果登记必须分别授权，不能因为拥有 view 就自动获得其他动作。

SYSTEM_ADMIN 不使用数据库通配符。V071 把当前 iam_permission 的每一条真实权限码和对应无额度 GLOBAL scope 授予隔离超级管理员账号，启动同步负责补齐后续新增权限；会话返回展开后的真实权限码清单，前端菜单、直链和按钮统一把 SYSTEM_ADMIN 识别为超级身份。禁用账号或角色仍会阻断登录。

权限常量不可自行改名：业务身份代码固定为 PROJECT_MANAGER、FINANCE_MANAGER、ARCHIVE_MANAGER，独立系统管理员固定为 SYSTEM_ADMIN。ADMIN、all、project:read、workflow:task:read 等历史试验代码、缩写或通配写法均不是 R1 合法值；正式路由、OpenAPI、Java 鉴权、按钮指令、fixture 和测试必须引用本节展开后的同一权限码。发现旧值时先做映射和迁移评审，再改代码和测试，不能在前端兼容多个别名后继续发布。

5. 总体业务流程和数据流

5.1 一条主数据流

flowchart TB
    S["来源资料\nOA导出/Excel/人工录入/附件"] --> V["资料校验\n必填、格式、主数据、重复"]
    V -->|"错误"| R["错误清单\n补资料后重新提交"]
    R --> S
    V -->|"通过"| P["项目业务确认\n内部审批或只读 OA 审批快照"]
    P -->|"退回/驳回"| R
    P -->|"通过"| F["财务管理复核"]
    F -->|"退回/例外"| R
    F --> E["财务业务记录\n成本/收款/发票/付款"]
    E --> B["记账准备\n凭证草稿/导出文件/人工结果"]
    E --> A["项目档案\n附件、版本、归档包"]
    B --> A
    A --> Q["查询和分析\n项目、合同、金额、状态"]

5.2 三种来源如何进入审批

同一张表单允许三种来源，但进入系统后的处理路线必须明确，避免把 OA 已完成的审批再审批一遍，也避免历史数据未经确认就直接成为正式财务记录。

来源方式	适用场景	系统处理路线	必须保留的证据
系统在线填写	新业务直接在本系统发起	草稿 → 项目审核 → 财务复核 → 形成业务记录	表单版本、每次审批动作、附件版本
OA 已审批资料导入	OA 已完成业务审批，本系统接收结果	来源校验 → 保存只读 OA 审批快照 → 财务接收复核 → 形成业务记录	OA 单号、审批链、意见、时间、原始导出文件和哈希
Excel/人工历史导入	期初数据或旧资料迁移	导入批次 → 错误修正 → 业务确认 → 财务确认 → 形成期初/历史记录	导入人、确认人、批次、原始文件、差异说明和对账结果

OA 导入路线不重新判断原 OA 的业务审批结论，但财务金额、主数据、附件和重复性检查仍必须通过。历史导入不得直接把数据标成“已付款”或“已记账”；必须同时提供回单、凭证号等证据并由财务确认。单纯补充附件时，要关联原单据并生成附件新版本，只重新进入受影响的财务或资料节点。

5.3 每条记录都要带的“身份证”

不论是表单、合同、收款还是附件，都必须至少带：

内部编号 + 来源单号 + 所属公司 + 项目 + 业务日期 + 金额（如有）+ 当前状态 + 当前版本 + 创建人/时间 + 审核记录

这样财务人员点开一笔付款时，可以反查：它来自哪个表单、谁审批过、使用了哪个合同、有哪些发票和附件、是否已经生成记账资料、是否已经归档。

5.4 状态的通用规则

所有业务对象都遵循：

草稿 → 提交 → 审核中 → 通过/退回/驳回 → 形成财务记录 → 记账准备 → 归档

正式数据不直接删除。错误通过退回、作废、冲销或新版本修正；每个动作留下操作人、时间、意见和前后状态。

6. 系统总体功能拆分

6.1 功能总览

功能编号	功能组	要解决的问题	MVP
F-01	登录与身份选择	用户不知道从哪里进入、权限混在一起	必做
F-02	项目工作台	项目资料、待办和进度分散	必做
F-03	财务工作台	财务审核任务找不到、口径不统一	必做
F-04	资料工作台	项目结束后资料无法归档和检索	必做
F-05	项目与主数据	项目、供应商、合同重复录入	必做
F-06	14 类来源表单	OA 数据无法进入财务流程	必做
F-07	审批与复核	审批结果和财务审核断开	必做
F-08	成本与合同	合同额度、成本和付款无法核对	必做
F-09	收款与发票	收款、开票和项目关联不清	必做
F-10	进度款与付款	付款前缺少金额、附件和责任控制	必做
F-11	记账准备	业务数据无法变成可记账资料	必做
F-12	档案管理	文件散落、版本不清、找不到依据	必做
F-13	查询和导出	管理人员无法快速查项目和财务状态	必做
F-14	审计和运行管理	出问题无法还原谁改了什么	必做
F-15	银行对账	银行资料无法勾稽	后续加法
F-16	税务准备	申报资料缺少统一底稿	后续加法

6.2 首期最小可用闭环

首期不要求 14 个表单都产生复杂会计分录，但必须做到：

• 14 个表单都能收进系统、查看、审批、退回、归档。
• 财务核心表单能产生结构化业务记录。
• 每条结构化业务记录能进入项目台账和记账准备队列。
• 所有附件能从项目或单据反向查到。

7. 页面结构总览

7.1 页面导航

登录
└── 身份选择
    ├── 项目管理工作台
    │   ├── 我的项目
    │   ├── 待办审批
    │   ├── 14类表单
    │   ├── 项目详情
    │   └── 项目进度
    ├── 财务管理工作台
    │   ├── 财务待办
    │   ├── 项目/合同/成本
    │   ├── 收款确认
    │   ├── 发票申请
    │   ├── 进度款/付款
    │   ├── 记账准备
    │   └── 财务查询
    └── 资料管理工作台
        ├── 待归档项目
        ├── 档案包审核
        ├── 文件检索
        └── 借阅/归还记录

上图是业务功能视图，不代表每个叶节点都要做成左侧菜单。第一轮真正的左侧菜单、隐藏路由和页面数量只以 7.3 节为准：例如“我的项目”“财务待办”“档案包审核”是对应工作台的卡片、页签或带初始筛选的快捷入口，不新增平行页面。工作台快捷入口必须跳转到 7.3 节既有页面，并通过 URL query 保存非敏感筛选条件，以便刷新和返回时结果一致。

7.2 页面数量和合并原则

首期固定交付 18 个业务页面 + 3 个公共页面，共 21 个页面。14 张 OA 表单在页面上可以按业务分组，但每张表单必须保留独立的表单代码、字段校验、审批路线和数据映射。

公共页面：登录、身份选择、个人中心。
业务页面：三类工作台、项目、表单、审批、财务、记账、档案、查询、审计等。

页面分类固定为：公共 PAGE-01～03；工作台 PAGE-04～06；项目 PAGE-07～08；表单审批 PAGE-09～11；财务 PAGE-12～16；资料档案 PAGE-17～18；查询分析 PAGE-19；系统治理 PAGE-20～21。PAGE-01、02 使用公共入口，PAGE-03 使用顶部头像入口，PAGE-08、10 是隐藏业务路由，其余业务页面按 7.3 节进入左侧菜单。工作台卡片、页签、抽屉、对话框和项目详情的十个页签都不是新增页面，不得据此增加 PAGE 编号或平行菜单。

7.3 Starter 菜单、路由与页面映射

登录后的整体框架直接使用 TDesign Starter 的左侧菜单、顶部栏、页签和内容区。菜单层级已经表达业务归属，首期不在内容区显示面包屑，避免与菜单和页签重复；详情、编辑等隐藏路由必须保留安全返回路径。

一级菜单/入口	二级菜单	页面	路由	默认可见身份
公共入口	登录	PAGE-01	/login	未登录用户
公共入口	身份选择	PAGE-02	/role-select	已登录用户
顶部头像菜单	个人中心	PAGE-03	/profile	全部已登录用户
工作台	项目管理工作台	PAGE-04	/workbench/project	项目管理
工作台	财务管理工作台	PAGE-05	/workbench/finance	财务管理
工作台	资料管理工作台	PAGE-06	/workbench/archive	资料管理
项目管理	项目列表	PAGE-07	/projects	项目/财务/资料
隐藏详情路由	项目详情	PAGE-08	/projects/:projectId	按项目数据范围
表单审批	表单中心	PAGE-09	/forms	项目/财务
隐藏编辑路由	表单填写/导入	PAGE-10	/forms/:formType/:documentId?	项目/财务按动作权限
表单审批	待办审批	PAGE-11	/tasks	当前节点处理人
财务管理	主数据中心	PAGE-12	/finance/master-data	授权财务/管理员只读配置
财务管理	合同与成本	PAGE-13	/finance/contracts-costs	项目/财务
财务管理	收款与发票	PAGE-14	/finance/receipts-invoices	财务
财务管理	进度款与付款	PAGE-15	/finance/payments	项目/财务
财务管理	记账准备	PAGE-16	/finance/accounting	财务
资料档案	项目归档	PAGE-17	/archives/projects	项目/财务/资料按动作权限
资料档案	文件检索与借阅	PAGE-18	/archives/files	三类身份中的授权查询人
查询分析	查询与报表	PAGE-19	/reports	三类身份按数据范围
系统治理	审计日志	PAGE-20	/governance/audit	授权审计/管理员
系统治理	权限与配置	PAGE-21	/governance/settings	系统管理员
系统治理	系统更新	PAGE-22	/governance/update	系统管理员

本地路由表固定声明组件映射，后端只返回当前身份、权限码和数据范围，前端据此过滤菜单和按钮；后端不得下发任意组件文件路径。业务页面路由的 meta 至少包含 pageId、pageType、pageTemplate、title、permission 和 requiresAuth；历史 breadcrumb 字段可保留作路由合同和返回路径元数据，但不得渲染为可见导航。出现在菜单中的路由组沿用 Starter 的 orderNo 排序字段，不再另造 menuOrder。S0 页面追溯表还要逐路由冻结本地 componentPath、默认入口、URL query 白名单、首个读取 operationId（没有接口时明确记 N/A 和原因）及证据 ID；菜单、路由和页面不得出现三份不同配置。

同一账号切换身份时必须清空当前身份的页签、页面缓存、待办查询和按钮权限，再加载新身份菜单；不能沿用上一个身份打开的详情页。手工输入隐藏路由或无权路由时统一进入 Starter 的 403 页面，后端接口同时返回 403 并写审计日志。

8. 页面清单与每页功能

8.1 页面总表

页面 ID	页面名称	主要用户	主要功能
PAGE-01	登录页	全部用户	登录、失败提示、密码重置入口、账号锁定说明
PAGE-02	身份选择页	全部已登录用户（含单身份）	显示已授权角色卡片、角色说明、进入对应工作台
PAGE-03	个人中心	全部用户	查看账号、修改密码、切换身份、退出登录
PAGE-04	项目管理工作台	项目管理人员	我的项目、我的待办、被退回表单、项目进度和快捷发起
PAGE-05	财务管理工作台	财务管理人员	财务待办、异常、待记账、付款资料、项目资金概览
PAGE-06	资料管理工作台	资料管理人员	待归档、缺资料、借阅到期和已归档统计
PAGE-07	项目列表	项目/财务/资料人员	按公司、项目、负责人、阶段和状态筛选项目
PAGE-08	项目详情	三类角色	项目总览、表单、合同、收付款、进度、人员、附件和操作时间线
PAGE-09	表单中心	项目和财务人员	14 类表单分组、模板下载、创建、导入、草稿和状态查询
PAGE-10	表单填写/导入页	项目和财务人员	动态字段、附件、Excel 导入、校验、预览和提交
PAGE-11	待办审批页	当前节点处理人	待我处理、通过、退回、驳回、意见和审批记录
PAGE-12	主数据中心	授权财务人员	公司、项目、供应商、账户、合同、成本类别维护和版本审核
PAGE-13	合同与成本台账	项目和财务人员	合同额、变更、结算、应付、已付、开票和成本分类
PAGE-14	收款与发票页	财务人员	收款确认、应收核销、开票申请、人工开票结果和异常
PAGE-15	进度款与付款页	项目和财务人员	付款申请、额度检查、附件检查、结果登记、退汇和回单
PAGE-16	记账准备中心	财务人员	财务事件、凭证草稿、复核、导出和人工记账结果
PAGE-17	项目归档页	项目、财务和资料人员按动作权限	生成档案包、缺件检查、归档审核和项目关闭
PAGE-18	文件检索与借阅页	三类身份中的授权查询人员	条件检索、预览、下载、借阅、归还和水印
PAGE-19	查询与报表页	三类角色按权限	项目台账、合同、收付款、流程、附件完整性和导出
PAGE-20	审计日志页	审计/授权管理员	查询登录、查看、修改、审批、导入、导出和结果登记记录
PAGE-21	权限与配置页	系统管理员	用户、角色、数据范围、模板和参数版本
PAGE-22	系统更新页	系统管理员	当前/最新版本、显式下载、下载完成确认、安装重启和历史更新记录

8.2 PAGE-01 登录页

页面目的：让用户安全进入系统，同时把错误原因说清楚。

页面内容：

• 账号、密码、登录按钮。
• 密码是否可见的切换按钮。
• 账号锁定、停用、密码错误和会话超时提示。
• 首次登录/管理员重置后的强制改密入口。

页面规则：

• 连续输错密码后临时锁定。
• 停用或离职账号立即停止登录。
• 密码重置由用户发起申请、系统管理员执行重置并要求下次登录改密；首期不依赖短信、邮件或第三方身份服务。
• 登录成功后不直接进入复杂首页，而是进入 PAGE-02 身份选择页。
• 登录成功、失败、锁定和退出全部留审计记录。

验收结果：正确账号可登录；错误、锁定和停用账号得到不同提示；旧会话在账号停用后失效。

8.3 PAGE-02 身份选择页

页面目的：用当前账号被授权的入口卡片告诉用户“你现在要以什么身份工作”。业务账号显示三类业务卡中的一张或多张；纯超级管理员账号只显示隔离的超级管理员卡。

角色卡片：

• 项目管理人员：发起项目业务、补资料、看项目进度。
• 财务管理人员：做财务审核、付款检查和记账准备。
• 资料管理人员：检查资料、归档、检索和借阅。
• 超级管理员：只对独立的 SYSTEM_ADMIN 账号显示，默认进入 PAGE-21；进入后可通过侧栏访问全部业务和治理页面。

页面规则：

• 只显示当前账号已授权的角色。
• 单角色账号只显示一张身份卡，并由用户点击“进入系统”；不自动跳过本页。
• 系统管理卡不得与三类业务卡同时出现在同一账号；发生冲突时登录后阻断进入并记录配置错误审计。
• 切换身份不会扩大数据范围；未经授权的角色 URL 直接访问也要被服务端拒绝。

8.4 PAGE-03 个人中心

功能：查看姓名、部门、当前角色和授权公司/项目；修改密码；切换身份；退出全部会话；查看最近登录记录。

不提供：自行增加角色、扩大项目范围、查看其他人的敏感信息。

8.5 PAGE-04 项目管理工作台

首页要回答五个问题：我有哪些项目？有什么待办？哪些被退回？哪些资料缺失？项目现在到哪一步？

页面区块：

1. 数字概览：进行中项目、待我处理、被退回、即将到期。
2. 我的待办：表单名称、项目、当前节点、提交时间、剩余时限。
3. 我的项目：项目名称、负责人、阶段、合同额、最近动作。
4. 快捷发起：项目立项、供应商准入、合同会签、收款确认、进度款申请等。
5. 异常提示：缺附件、超期、合同/供应商未生效、表单版本过旧。

可操作：新建、继续编辑草稿、补件、撤回未处理单据、查看审批进度。

不可操作：财务终审、修改已通过金额、登记付款结果、生成正式凭证。

8.6 PAGE-05 财务管理工作台

首页要回答六个问题：今天要审什么？哪些金额异常？哪些付款待处理？哪些数据待记账？哪些项目资料不齐？哪些事情快超时？

页面区块：

1. 财务待办：按立项、供应商、合同、收款、发票、应付、付款分类。
2. 阻断异常：余额不足、合同超额、账户未生效、疑似重复、附件缺失。
3. 待记账：已财务确认但未生成凭证草稿的业务。
4. 待登记结果：需要人工登记付款、开票或记账结果的事项。
5. 项目资金概览：收款、成本、已付、待付和可用余额。
6. 月度工作：本月已完成、待完成和超时事项。

可操作：审核、退回、发起例外、确认财务事件、生成记账草稿、导出和登记人工结果。

8.7 PAGE-06 资料管理工作台

页面区块：待接收档案包、缺失附件、待复核原件、借阅到期、已归档项目和近期下载。

可操作：检查文件、标注原件类型和存放位置、退回补件、确认档案包、借阅/归还登记。

不可操作：改项目金额、改合同额度、审批付款、修改凭证。

8.8 PAGE-07 项目列表

筛选条件：公司、项目编号/名称、负责人、客户、项目阶段、财务状态、归档状态、开始/结束日期。

列表字段：项目编号、项目名称、公司、负责人、合同额、已收、已付、当前阶段、待办数、资料完整率、状态。

页面操作：新建项目、导入、查看详情、导出当前筛选结果。导出必须使用和页面相同的权限及脱敏规则。

8.9 PAGE-08 项目详情

这是系统最重要的“总账页”，不是会计总账，而是一个项目的全过程总览。

顶部信息：项目编号、名称、公司、客户、负责人、状态、合同额、项目起止时间。

页签：

1. 总览：关键金额、当前阶段、异常和待办。
2. 业务表单：14 类表单及状态。
3. 合同与成本：合同、变更、结算、成本分类。
4. 收款与发票：应收、收款、开票和核销。
5. 付款：应付、申请、结果、回单和退汇。
6. 进度与验收：履约进度、任务、照片和验收。
7. 人员：中标人员、班组人员、变更和押证费。
8. 记账准备：财务事件、凭证草稿和人工结果。
9. 档案：附件、版本、原件位置和档案包。
10. 时间线：谁在何时提交、审核、修改、退回、作废和归档。

8.10 PAGE-09 表单中心

表单按业务阶段分组展示：

• 项目准备：OA-01、OA-02、OA-03。
• 收支执行：OA-04、OA-05、OA-06、OA-08、OA-13。
• 项目过程：OA-09、OA-10、OA-14。
• 结束归档：OA-11、OA-12。
• 银行资料：OA-07。

每张表单卡片显示：名称、用途、适用角色、当前模板版本、我的草稿数、待处理数和新建按钮。

支持操作：在线填写、下载标准模板、上传 Excel/CSV、查看草稿和历史版本。

8.11 PAGE-10 表单填写/导入页

页面区块：

1. 基本信息：公司、项目、来源单号、版本、申请人和日期。
2. 表单字段：根据 OA-01～OA-14 动态显示。
3. 明细表格：人员、支付明细、附件矩阵等重复行。
4. 附件区：文件类型、是否必需、是否齐全、“不涉及”原因。
5. 校验结果：错误、警告和可提交项。
6. 审批快照：原 OA 节点、人员、意见和时间。

操作顺序：保存草稿 → 校验 → 预览 → 提交。Excel 导入使用“上传校验 → 查看错误 → 确认入库”两步，错误数据不进入正式表。

8.12 PAGE-11 待办审批页

列表分类：待我处理、我已处理、我发起、被退回、已完成。

详情区同时展示：原始表单、关键金额、附件、历史意见、项目/合同/供应商摘要和系统校验结果。

允许动作：通过、退回补件、驳回、撤回、作废、提交例外申请。所有动作必须记录意见；退回时选择需要修改的字段或附件。

8.13 PAGE-12 主数据中心

对象：公司、部门、项目、客户/供应商、供应商账户、公司银行账户、合同、成本类别、科目、税率字典。

功能：新增、编辑草稿、提交复核、版本对比、生效、停用、旧编号映射和重复检查。

关键规则：

• 项目编号在同一公司内唯一。
• 供应商按证照号去重。
• 银行账户新增或变更必须由另一名财务人员复核后生效。
• 停用主数据不影响历史单据，但不能用于新单据。

8.14 PAGE-13 合同与成本台账

合同列表字段：合同编号、项目、供应商、原合同额、批准变更、结算金额、已开票、已应付、已付款、可付余额、状态。

成本视图：人工、材料、机械、专业分包、运输、设备、间接费和其他成本。

支持下钻：点击“已付款”能看到付款单和回单；点击“已开票”能看到发票和来源表单。

8.14.1 PAGE-13 已实现页面与业务合同（2026-08-13）

PAGE-13 当前为 MODULE_ACCEPTED。本结论只覆盖合同执行、结算、应付及联动汇总，不代表 PAGE-15、整个 S3 或整套 R1 完成。

• 合同列表、全量筛选汇总、详情下钻和 CSV 导出均使用服务端权限范围、分页和金额重算。
• “待确认应付”仅统计 PENDING；“已应付”统计 CONFIRMED/PART_PAID/PAID；待确认记录仍参与合同额度预占。
• 项目经理使用 contractcost:payable:create 登记应付，财务使用 contractcost:payable:confirm 确认；登记人不得确认同一笔应付。
• 应付来源必须是同公司、同项目、当前版本已批准的 OA-04；结算来源同理必须是 OA-11。两类来源均不接受自由文本输入，也不允许重复生成业务记录。
• OA-04 财务终审现在直接在同一事务中生成 CONFIRMED 应付，写入合同额度占用、含税发票汇总和唯一 PAYABLE 会计事件；不是先生成一个待确认空壳再依赖人工补确认。历史/人工登记入口仍按原状态机执行，来源单据不得重复消费。
• 前端使用 TDesign Select、Form、Table、Tabs、Statistic、对话框和抽屉；来源下拉只查询当前项目已批准单据，最终约束仍由 Java 后端执行。

8.15 PAGE-14 收款与发票页

收款功能：登记/接收收款确认单、匹配项目和客户、分配到应收、处理暂收款、查看已收/未收。

发票功能：接收开票申请、检查合同额度和已开票金额、登记人工开票结果、关联已上传并通过检查的票据文件、处理红冲/作废；直接上传交互归统一 FileUploader 全局任务收口。

首期不做：连接发票平台、自动验真、自动开票。

8.15.1 PAGE-14 已实现页面与业务合同（2026-08-11）

PAGE-14 当前为 MODULE_ACCEPTED。该结论只覆盖本节列出的收款、应收和发票闭环，不代表 PAGE-15、整个 S3 或整套 R1 已完成。PAGE-13 的独立模块结论见 8.14.1 和 13.1.2。

页面和功能

区域	已实现内容	用户得到的结果
公共查询	收款/开票双页签；关键词、公司、项目、客户/开票对象、状态、业务日期和排序筛选；20/50/100 服务端分页；当前筛选 CSV 导出	页面刷新和翻页后从 Java/MySQL 重新查询，金额不由前端临时合计
收款列表与详情	收款编号、公司、项目、客户、日期、金额、已分配、未分配、状态；详情抽屉展示流水号、确认人、作废原因和逐笔核销明细	可从一笔收款反查核销到哪些应收、项目和合同，以及每笔应收剩余金额
收款动作	新建/编辑草稿、异人确认、分配到应收、未分配收款作废；项目和客户可暂不选择以形成待匹配暂收款	支持一收多应收和一应收多次收款；分配后收款与应收余额同步更新
发票列表与详情	开票业务号、公司、项目、对象、申请日期、金额、税率、发票号和状态；详情显示合同额度、累计占用、剩余额度、提交/复核/结果人员、意见、原票和终止原因	审核人员能在一个抽屉内核对申请、额度、人员分工和后续结果
发票动作	新建/编辑草稿、提交复核、通过/退回/驳回、登记人工开票结果、作废、登记红冲；可关联已通过本地检查的结果文件	不连接外部发票平台；人工结果、原票/红字票关系、终止原因和责任人可追溯
OA 来源结果	OA-05 财务终审直接生成 CONFIRMED 收款、项目资金控制增量、资金台账和待处理 RECEIPT 会计事件；OA-08 财务终审生成带来源版本的 DRAFT 开票候选，后续仍由 PAGE-14 人工提交、异人复核和登记开票结果	来源审批和 PAGE-14 人工处理不重复生成收款/发票；失败时来源状态、工作流任务、财务对象、台账和会计事件整体回滚
页面反馈	TDesign Tabs/Table/Form/Drawer/Dialog/Tag/Alert/Empty/Pagination；金额使用 MoneyInput 和 decimal.js 字符串；必填意见/发票号/日期/原因校验；401/403/404/409/422/5xx 分级提示	重复点击、版本冲突或业务阻断不会在前端伪造成功；写成功后重新读取列表、引用项和已打开详情

状态和硬控制

对象	已实现状态主线	后端硬控制
收款	DRAFT → CONFIRMED → PARTIALLY_ALLOCATED → ALLOCATED；未发生分配的 DRAFT/CONFIRMED 可进入 VOID	登记人与确认人必须不同；分配额不得超过收款未分配额和应收未收额；公司、项目、客户、币种必须匹配；重复公司+流水号拒绝；每次命令校验权限范围、金额上限和版本
应收	人工开票结果自动生成 OPEN；核销后进入 PARTIALLY_SETTLED/SETTLED；未核销发票被作废或红冲时进入 VOID	一张有效发票只生成一条应收；未收余额保持在 0～原额；核销使用数据库行锁和乐观锁，禁止超收
发票	DRAFT/RETURNED → REVIEWING → RESULT_PENDING → ISSUED；审核可进入 RETURNED/REJECTED；终止可进入 VOID/RED_LETTERED	提交人与复核人必须不同；审核通过和登记结果都复算合同可开票额；同公司发票号唯一；已核销应收不得直接作废/红冲；红冲生成关联原票的红字票并按净额进入合同/报表统计

实际权限码

receivable:receipt:view/create/edit/confirm/allocate/void/export；receivable:invoice:view/create/edit/submit/review/record-result/void/red-letter/export。页面按钮来自服务端 allowedActions；Java 后端再次执行功能权限、公司/项目范围、金额阈值、对象状态、SOD 和版本校验。

8.16 PAGE-15 进度款与付款页

页面分区：付款申请列表、待财务检查、待线下付款、待登记结果、已支付、失败/退汇。

付款前检查：项目可用余额、合同可付余额、应付余额、供应商账户版本、发票和附件、重复风险、审批是否完成。

结果登记：由经办人填写线下付款日期、金额、结果和回单；另一名财务人员复核。同一人不能同时登记和复核。

首期不做：系统发起银行付款、读取 U 盾、保存网银密码或 PIN。

8.16.1 PAGE-15 当前实现边界（2026-08-13）

PAGE-15 当前为 IN_PROGRESS。下表用于区分“已经能用的核心付款链”和“模块验收前必须补齐的控制”，不能把存在页面或接口等同于整页完成。

区域	当前已经实现	仍须完成
页面与查询	六个业务页签；关键词、公司、项目、供应商、状态、风险、日期、排序筛选；服务端分页、详情抽屉、检查清单、CSV 导出；新建/编辑及各状态动作均使用 TDesign	三档 Chrome/Edge 正式证据包、全部失败/无权/慢请求状态和包体预算仍归 S5 收口
付款申请	选择公司、项目、合同、供应商、可选应付、生效收款账户、金额、日期、币种和附件；应付分类命中生效规则时，页面逐项显示必需资料的齐全/缺失/文件检查中状态，每个文件必须选择矩阵内资料类型；后端复核对象归属、数据范围、金额权限并保存规则版本和分类快照；附件“不涉及”申请已接入异人财务复核和消费审计	D-02/D-09 确认并发布正式完整矩阵；正式矩阵的必需项与“不涉及”范围未确认前禁止发布
OA 来源	OA-06 来源为可选；选择后页面只查询当前项目已批准 OA-06，后端在保存和批准时复核表单类型、公司、项目、当前版本及其 APPROVED 实例；OA-06 v2 财务终审已在同一事务内生成 OFFLINE_PENDING 付款、冻结资金并写入流水	自动投影只形成待线下付款记录，不产生银行指令；PAGE-15 正式矩阵、三档浏览器证据和甲方验收仍按本页独立收口
批准前检查	项目可用余额、合同余额、应付余额、生效账户、通用或按成本类型的附件完整性/文件状态、精确/近似重复付款、OA 来源和项目阻断风险；批准事务内锁资金控制行、合同、应付和付款；同项目余额并发竞争只允许余额覆盖的付款成功；历史无规则快照付款继续按通用附件语义检查；独立逐笔资金台账已记录并可查询	D-02/D-09 正式矩阵和业务口径确认
线下结果	登记成功/部分成功/失败及回单；另一人复核；部分支付保留剩余冻结额；失败释放未支付额；退汇逆转资金、应付和会计事件；重付关联原付款和序号	正式桌面端全状态业务证据包及跨模块记账/档案追溯仍须补齐
例外	DUPLICATE、PROJECT_RISK 支持一次性申请；申请人与财务复核人必须分离，最多 7 天有效，批准时重算指纹并在付款批准事务内原子消费；附件“不涉及”同样要求理由、异人复核和消费审计	账户未生效、同人登记/复核、项目资金/合同/应付额度、附件硬要求、OA 来源、重复有效来源/事件等硬控制永不允许例外；正式矩阵仍须 D-02/D-09 确认

当前主要状态主线：DRAFT/RETURNED → REVIEWING → OFFLINE_PENDING → RESULT_RECORDED → PART_PAID/PAID；批准或线下阶段可按规则进入 FAILED/VOID，已复核结果可登记 REFUNDED 并创建关联重付。所有写动作继续由 Java 后端校验权限、范围、金额、状态、SOD、幂等键和版本，前端不得自行推进状态。

8.17 PAGE-16 记账准备中心

页面分区：待生成、草稿、待复核、已导出、待登记结果、已完成、已冲销、已作废。

功能：

• 从已确认的收款、应付、付款、发票等财务记录生成凭证草稿。
• 显示借方、贷方、摘要、项目、往来单位和来源依据。
• 财务人员修改科目或金额时填写原因。
• 借贷不平或缺辅助信息时阻止复核。
• 导出标准文件，人工导入现有记账系统后登记凭证号和结果。
• 已复核完成但外部结果错误时，由非原登记人填写原因执行冲销；冲销后来源事件回到可更正状态，旧凭证号、登记/复核信息和证据保留在不可变历史中。
• 已冲销结果由另一名具备权限的财务人员重开，进入已导出待重新登记状态；新一轮结果与旧轮证据隔离，旧外部凭证号不得再次使用。
• 冲销和重开都校验独立权限、公司/项目/金额范围、当前版本、状态、岗位分离和幂等键，并记录操作人、时间、原因、前后版本及审计日志。

首期不做：调用 T+ 接口、自动过账、自动修改外部账套。

8.18 PAGE-17 项目归档页

流程：财务管理人员在 PAGE-08 对授权项目执行“确认财务完整” → 项目财务状态变为 COMPLETED → 用户在 PAGE-17 主动生成档案包 → 系统检查缺件 → 财务提交 → 资料人员异人审核 → 退回补件或确认归档。未完成财务确认时，服务端拒绝生成档案包；确认命令同时校验权限、公司/项目范围、项目状态、财务状态和版本，并记录 PROJECT_FINANCE_CONFIRM 审计。

档案包应包含：项目基础资料、14 类相关表单、审批记录、合同、发票、收付款资料、记账准备结果、验收资料和文件清单。

每个文件保存 SHA-256 哈希，用来判断文件是否改变；替换文件生成新版本，旧版本继续保留。

档案记录保管期限、纸质原件位置和冻结标记。归档后计算 retentionExpiresOn，保管状态固定为 PENDING、ACTIVE、DUE_SOON（90 天内）、EXPIRED、FROZEN。到期只在页面提示，不自动删除或销毁；处于审计、争议或其他冻结状态的档案禁止处理。档案销毁审批不纳入 MVP。

8.19 PAGE-18 文件检索与借阅页

检索条件：公司、项目、合同、供应商、表单、文件名、上传人、日期、原件类型、归档状态和扫描状态。

操作：预览、下载、查看版本、申请借阅、批准借阅、登记归还。下载显示用户和时间水印并记录审计。

当前实现状态（2026-08-15）：本地真实浏览器已验证首次进入不自动查询、项目条件检索、文件版本详情、受控水印预览，以及工作台“隔离文件”按扫描状态精确跳转。扫描器不可用时，系统保留 QUARANTINED 文件并建立带公司/项目范围的 file_link；用户可在扫描服务恢复后重扫，成功时文件进入 AVAILABLE、正式路径存在、隔离源消失、转存意图清空，503/200/422 幂等结果保持首次语义。资料身份申请、财务身份批准、资料身份归还的异人流程已在真实页面和数据库贯通，范围外档案直链下载回归已通过。移动 390×844 只作为补充视口检查，不属于 R1 正式支持范围；Chrome/Edge 三档全流程、axe、正式负向 fixture 和甲方证据包仍须按 TODO-S4-011/012、UAT-020～022 收口，PAGE-18 当前不是 MODULE_ACCEPTED。

8.20 PAGE-19 查询与报表页

首期报表：

1. 项目综合台账：项目、合同、收款、成本、付款、记账和归档状态。
2. 合同执行台账：合同额、变更、结算、开票、应付和已付。
3. 收款/开票台账：本次及累计收款、开票和未收。
4. 付款进度台账：申请、审核、线下结果、回单和记账状态。
5. 流程时效：各节点停留时间、退回次数和未处理任务。
6. 资料完整性：缺失、待补、不涉及和已齐全。

所有汇总数据必须能点击下钻到明细、来源表单、审批记录和附件。

当前实现状态（2026-08-16）：六类报表、服务端汇总、筛选快照和同权限下钻已实现；金额按两位小数显示，业务状态中文化，下钻四类子查询再次复用当前用户、角色、权限和完整父行筛选。导出已改为两阶段：服务端预检冻结人员/身份/权限范围指纹、口径版本、筛选、列、排序和预计行数，页面展示筛选快照与脱敏说明后由用户确认，服务端再次鉴权和校验全部快照后才生成文件。MySQL 8.4 全量集成回归已通过；D-08、各指标日期口径、流程时长真实样本和正式浏览器证据尚未完成，PAGE-19 当前只能标记 IMPLEMENTED_PENDING_ACCEPTANCE，不得标记 MODULE_ACCEPTED。

8.21 PAGE-20 审计日志页

可查询：登录、敏感字段查看、创建、修改、提交、审批、退回、导入、导出、下载、结果登记、作废、归档和权限变化。

日志显示：用户、角色、公司/项目范围、操作时间、对象、动作、前后值、原因和请求编号。普通业务人员不能删除或修改审计日志。

8.22 PAGE-21 权限与配置页

配置对象：用户、角色、公司/项目数据范围、金额阈值、互斥规则、表单模板、字典、附件矩阵、审批路线和版本。

本页只管理权限和业务配置，不配置系统名称、系统域名，也不承载在线更新。用户、角色和数据范围变更后，受影响账号的既有会话失效，必须重新登录获取最新权限。

PAGE-21 只向超级管理员开放。超级管理员账号不得混授普通业务角色，但其 SYSTEM_ADMIN 身份本身自动拥有全部财务和治理功能权限；审批处理人、异人复核、状态机、资金和审计控制继续由后端强制执行。

8.22.1 PAGE-22 系统更新页

系统更新使用独立入口 /governance/update，同时显示当前版本、最新版本、更新状态、四步进度和最近更新记录。拥有 admin:update:view 的隔离系统管理员可进入页面；下载与重启安装仍由 admin:update:execute 和服务端 allowedActions 共同控制。未启用或 Release 地址无效时显示明确禁用状态并禁用“获取版本”。

更新固定为“检查、下载、安装”三个服务端阶段和四个明确用户反馈。管理员点击“获取版本”时只请求最新版本、发布时间和发布说明，不提交下载；发现新版本后显示“立即更新”，再次确认后才提交 DOWNLOAD。root oneshot 从固定 Gitea Latest Release API 下载 manifest、签名和应用包，验签/验哈希后写入 root-only 版本缓存并进入 READY/下载完成，期间当前业务版本继续运行。此时页面显示“立即更新并重启”，点击后只允许安装同版本缓存，并在切换前重新验证。页面以 3 秒轮询显示排队、下载、校验、备份、安装和重启状态；命令已经被服务端接受但 HTTP 响应丢失时也会主动重读状态。健康检查成功后显示 10 秒倒计时并自动刷新；失败时保留明确状态并恢复已验证的上一版本。

页面只提交目标版本和原因，不接收下载地址、Token、脚本或任意命令。公共 Gitea 默认不配置 Token；如改接私有镜像，只读 Token 仅存在于权限为 0600 的 root 环境文件和临时 Header 文件，不进入进程参数、DTO、状态 JSON、审计参数或页面响应；API 和资产必须同 scheme、host、port，认证请求不跟随跨来源重定向。文件锁和 inbox/processing 双路径防止并发覆盖，独立 root oneshot 执行 RSA/SHA-256 校验、可验证数据库备份、持久事务、应用与运维文件原子切换、新旧版本健康检查和失败回滚。

8.23 页面通用要求

• 列表有搜索、筛选、分页、排序和列显示设置。
• 详情页固定显示业务编号、状态、版本、创建人和更新时间。
• 按钮只显示当前状态允许的操作，但后端仍必须做权限校验。
• 删除只用于草稿；正式数据使用作废、冲销或新版本。
• 保存和提交后给出明确结果，失败信息定位到字段或附件。
• 页面上的金额使用千分位和两位小数；日期、状态和颜色保持一致。
• 所有页面在常见办公电脑分辨率下不横向溢出；复杂明细允许表格内部滚动。

8.24 页面开发交付矩阵

下表是前端、后端和测试共同使用的页面级开发合同。组件列表示必须优先采用的 TDesign 组件基线，不是允许开发人员另做一套同类控件；接口组最终以评审通过的 OpenAPI 为准。

页面	Starter 内实现位置	主要 TDesign 组件	必须接通的真实接口组	核心权限/完成结果
PAGE-01 登录	pages/login	Form、Input、Button、Alert	/api/v1/auth/login、session、logout、csrf	未登录可访问；成功后获得服务端会话，失败/锁定/停用分别反馈并留痕
PAGE-02 身份选择	pages/role-select	Card、Button、Tag、Alert	/api/v1/auth/roles、select-role	只显示已授权入口；业务账号显示业务身份，纯管理员只显示系统管理卡；选择后清空旧身份状态并进入对应页面
PAGE-03 个人中心	pages/profile	Descriptions、Form、Timeline、Dialog	/api/v1/auth/profile、password、sessions	只能处理本人账号；切换身份、改密和退出全部会话真实生效
PAGE-04 项目工作台	pages/workbench/project	Statistic、Table、Tag、Timeline	/api/v1/workbenches/project	仅汇总本人授权项目、待办、退回和缺件；数字均可下钻
PAGE-05 财务工作台	pages/workbench/finance	Statistic、Table、Tabs、Alert	/api/v1/workbenches/finance	展示授权范围内财务待办、阻断异常、待记账和待登记结果
PAGE-06 资料工作台	pages/workbench/archive	Statistic、Table、Tag、Timeline	/api/v1/workbenches/archive	展示待归档、缺件、借阅到期和归档统计，不提供金额修改入口
PAGE-07 项目列表	pages/projects/list	Form、Table、Pagination、Dropdown	/api/v1/projects、/api/v1/projects/imports、/api/v1/projects/exports	服务端筛选/分页/排序；查看和导出执行同一数据范围与脱敏规则
PAGE-08 项目详情	pages/projects/detail	Descriptions、Tabs、Table、Timeline	/api/v1/projects/{id} 及表单、财务、风险标记等详情子资源	十个页签可从项目穿透到表单、财务、记账、档案和审计证据；人工风险标记只向授权人员开放
PAGE-09 表单中心	pages/forms/index	Tabs、Card、Table、Tag	/api/v1/source/templates、/api/v1/source/forms	14 类模板、版本、草稿、待办和历史状态完整；按身份显示发起能力
PAGE-10 表单填写/导入	pages/forms/editor	Form、Table、Upload、Alert、Steps	/api/v1/source/forms、validate、imports、submit	保存草稿、校验、预览、提交和两阶段导入均真实落库且可定位错误
PAGE-11 待办审批	pages/tasks	Table、Descriptions、Timeline、Dialog	/api/v1/workflow/tasks 及 approve/return/reject/withdraw/void	只允许当前节点处理人操作；意见、字段/附件退回点和状态迁移完整
PAGE-12 主数据	pages/finance/master-data	Tabs、Table、Form、Dialog、Descriptions	/api/v1/masterdata/*	新增、变更、版本对比、复核、生效和停用完整；提交人与复核人分离
PAGE-13 合同与成本	pages/finance/contracts-costs	Form、Table、Tabs、Statistic	/api/v1/contracts/*、/api/v1/costs/*	合同原额/变更/结算、开票/应付/已付和成本分类可计算、下钻、导出
PAGE-14 收款与发票	pages/finance/receipts-invoices	Tabs、Table、Form、Drawer、Dialog	/api/v1/receivables/*、/api/v1/receipts/*、/api/v1/invoices/*	收款分配、暂收、正式应收、开票申请及人工开票/红冲/作废结果可追溯；当前已通过模块级验收
PAGE-15 进度款与付款	pages/finance/payments	Tabs、Table、Descriptions、Dialog、Alert	/api/v1/payments/*	额度/账户/附件/重复/SOD 检查生效；只登记和复核线下结果，不产生银行指令
PAGE-16 记账准备	pages/finance/accounting	Tabs、Table、Form、Dialog	/api/v1/accounting/*	财务事件、借贷草稿、复核、导出、人工结果登记/异人复核、结果冲销/异人重开和分轮证据完整且幂等
PAGE-17 项目归档	pages/archives/projects	Table、Steps、Timeline、Drawer、Dialog	/api/v1/projects/{id}/finance-complete、/api/v1/archive/packages/*	仅项目财务状态为 COMPLETED 后允许主动生成档案包；缺件、退回补件、复核、冻结版本和保管到期状态完整
PAGE-18 文件检索借阅	pages/archives/files	Form、Table、Pagination、Dialog	/api/v1/archive/files/*、/api/v1/archive/borrows/*	受控预览/下载/版本/借阅/归还；敏感访问、水印和审计有效
PAGE-19 查询报表	pages/reports	Tabs、Form、Table、按需 ECharts	/api/v1/reports/{reportCode}、drilldown、exports	六类报表同口径汇总、下钻、导出；不以硬编码数字或前端合计冒充结果
PAGE-20 审计日志	pages/governance/audit	Form、Table、Drawer、Tag	/api/v1/audit/logs、/api/v1/audit/exports	授权审计人员按请求编号还原关键动作；日志不可由业务页面修改/删除
PAGE-21 权限与配置	pages/governance/settings	Tabs、Tree、Table、Form、Dialog	/api/v1/admin/users、roles、scopes、templates、parameters	仅超级管理员可用；用户、角色、范围、模板和参数按版本与动作白名单管理
PAGE-22 系统更新	pages/governance/update	Steps、Table、Alert、Tag、Button	/api/v1/admin/system-update/{check,download,install}、/api/v1/audit/logs	获取版本只检查；立即更新才下载；下载完成后显示立即更新并重启；健康后 10 秒刷新；历史操作来自不可变审计日志

每个页面只有同时满足以下条件才算完成：

1. 路由、菜单、面包屑、返回路径、页签标题和当前身份规则正确。
2. 页面所有可见数据和操作均接真实 OpenAPI；不存在 Mock、静态 JSON、空按钮或“后续实现”。
3. 菜单、按钮、接口、数据范围、状态、金额阈值和岗位互斥都通过正向及越权测试。
4. 首次加载、刷新、空结果、字段错误、401、403、404、409、422、500 和网络失败均有确定界面。
5. 正常、失败、重复点击、并发冲突、未保存离开和刷新恢复测试通过。
6. Chrome、Edge 三档目标分辨率截图通过评审，无重叠、截断、异常跳动和页面整体横向溢出。

8.25 页面进入、主操作和完成结果

下表锁定“进入页面先看到什么、用户按什么顺序操作、做到什么算这次操作完成”。它与 8.24 节共同组成页面合同；开发不能只把路由和空壳组件做出来。

页面	默认进入状态	主操作顺序	本次操作完成标志
PAGE-01	未登录表单，账号为空、密码为空	获取 CSRF → 输入账号密码 → 登录	服务端建立 Session，跳转 PAGE-02；失败停留本页并显示稳定错误码
PAGE-02	显示当前账号全部已授权入口；单业务身份或纯管理员也只显示一张卡	选择身份卡 → 点击“进入系统”	服务端保存当前身份并返回权限摘要；业务身份进入对应工作台，SYSTEM_ADMIN 进入 PAGE-21
PAGE-03	本人资料、当前身份、授权范围和最近登录	改密/切换身份/退出指定或全部会话 → 确认	服务端返回新会话状态；切换身份后旧页签和缓存清空
PAGE-04	授权项目的概览、待办、退回和缺件，更新时间倒序	点击指标/待办/项目/快捷发起	进入既有目标页面并带初始筛选；返回后保持非敏感筛选条件
PAGE-05	财务待办、阻断异常、待记账、待登记结果	点击分类 → 打开对应单据 → 执行授权动作	服务端状态改变并重新计算工作台数字；数字与明细数量一致
PAGE-06	待接收档案、缺件、借阅到期和近期下载	打开档案包/文件/借阅记录 → 处理	对象进入新状态，工作台计数和对应列表同步更新
PAGE-07	当前身份全部授权项目，按最近更新时间倒序	筛选/排序/分页 → 查看、新建、导入或导出	详情路由可刷新；导出使用相同筛选、权限和脱敏口径
PAGE-08	项目总览页签和项目摘要，保留来源列表返回路径	在十个页签查看/下钻 → 执行当前身份允许的业务入口	每个金额、状态、表单和附件能回到唯一来源；对象不存在显示业务 404
PAGE-09	14 类模板按业务阶段分组，显示可用版本和本人数量	选模板 → 新建、导入、继续草稿或查看历史	进入 PAGE-10 并携带表单类型和已有单据 ID；无发起权时只读
PAGE-10	新建空表单、已有草稿或导入校验批次三种模式之一	保存草稿 → 完整校验 → 预览 → 提交；导入为上传校验 → 确认入库	获得唯一业务编号和版本，状态进入 SUBMITTED；错误批次不产生正式数据
PAGE-11	默认“待我处理”，按到达时间升序	打开任务 → 核对表单/金额/附件/历史 → 通过、退回或驳回	当前任务关闭并生成下一任务或终态；意见、退回点和审计记录可查
PAGE-12	默认显示公司/项目等主数据页签及生效状态	新增/变更草稿 → 提交复核 → 另一人复核 → 生效或停用	新版本生效且历史单据仍引用原版本；同人复核被拒绝
PAGE-13	合同执行台账，默认授权范围、最近更新排序	筛选合同/项目 → 查看额度与成本 → 下钻或导出	汇总值与来源明细一致，合同可付额由后端重算
PAGE-14	默认进入“收款记录”页签，按最近更新倒序加载当前范围数据，可切换“开票申请”	收款新建/编辑 → 异人确认 → 分配/作废；或开票新建/编辑 → 提交 → 异人审核 → 登记人工结果/作废/红冲	形成可追溯收款、应收分配或发票结果并重读服务端详情；不调用外部发票平台
PAGE-15	项目身份进入“我的申请”，财务身份进入“待财务检查”	申请 → 检查额度/账户/附件/重复 → 审批 → 登记线下结果 → 另一人复核	状态到 PAID、FAILED 或 REFUNDED，回单和人员分工完整；不产生银行指令
PAGE-16	默认“待生成”，显示已确认财务事件	生成草稿 → 编辑分录 → 另一人复核 → 导出 → 登记并复核人工记账结果；结果有误时由异人冲销 → 再由异人重开 → 登记新一轮结果	借贷平衡、导出批次/哈希、当前结果和分轮历史完整；旧凭证号及旧证据可追溯且不与新轮混合
PAGE-17	项目人员显示财务确认状态和待生成/待提交，财务显示待检查，资料人员显示待审核	财务确认完整 → 用户主动生成包 → 缺件检查 → 提交 → 资料异人审核/退回 → 归档	未确认时生成被拒绝；成功生成不可静默覆盖的归档版本；已归档包只允许受控后续动作
PAGE-18	空查询条件，不自动加载完整敏感文件全集	输入条件 → 查询 → 预览/下载或发起借阅 → 审批/归还	每次敏感访问带水印和审计；无权对象不出现在结果中
PAGE-19	默认项目综合台账和当前月份/授权范围	筛选 → 汇总 → 点击金额下钻 → 导出	汇总、明细和导出同一口径；每个数字可到来源对象
PAGE-20	默认最近 24 小时授权范围内审计记录	按用户/对象/动作/请求编号查询 → 查看前后值或导出	可用请求编号还原完整动作链；前后值按敏感规则脱敏
PAGE-21	默认用户管理页签，只向系统管理员开放	编辑草稿 → 校验冲突 → 保存/发布新配置版本	新版本有生效时间和发布人；权限变更使受影响旧会话立即失效
PAGE-22	当前版本、最新版本、更新状态和最近更新记录	获取版本 → 立即更新并下载验签 → 下载完成 → 立即更新并重启 → 等待健康检查	健康检查成功后倒计时 10 秒自动刷新；失败状态和审计历史可查询

所有列表默认每页 20 条；默认排序已在上表写明，未单独写明时使用 updatedAt,desc。无功能权限的动作隐藏；有功能权限但当前状态、资料或岗位互斥不允许的动作禁用并说明原因。任何写操作成功后都必须重新读取服务端对象和允许动作，不能只修改前端状态；失败时保留尚未提交成功的用户输入。

8.26 列表查询、列和动作白名单

列表查询条件之间默认使用 AND；同一个多选条件内部使用 OR。空字符串、空数组和未传参数都表示“不限制”，但 false、0 和明确的空值筛选不能被后端当成未传。日期范围含首尾日期，页面按北京时间选择，后端换算为 UTC 半开区间。URL 只保存下表允许的非敏感条件；身份证、手机号、银行账号、工资和自由审批意见不得写入 URL。

页面/默认视图	允许筛选参数	允许排序字段	固定主列与动作
PAGE-04 项目工作台	owner=current、taskStatus、projectStage、issueType	卡片明细仅 dueAt/updatedAt	指标、待办、项目、异常；点击只跳 /projects、/forms、/tasks 的既有路由并携带白名单 query
PAGE-05 财务工作台	taskType、blockingCode、accountingStatus、resultStatus、month	dueAt/amount/updatedAt	财务待办、阻断异常、待记账、待登记结果、项目资金；动作进入 PAGE-11/13/14/15/16
PAGE-06 资料工作台	packageStatus、missingType、borrowStatus、dueBefore	dueAt/updatedAt	待归档、缺件、借阅到期、近期下载；动作进入 PAGE-17/18
PAGE-07 项目列表	companyId、keyword、ownerId、customerId、stage、financeStatus、archiveStatus、startDateFrom/To、endDateFrom/To	updatedAt/businessNo/name/contractAmount/status	项目编号、名称、公司、负责人、合同额、已收、已付、阶段、待办数、资料完整率、状态；新建、导入、详情、导出
PAGE-09 表单中心	groupCode、formType、templateVersion、sourceSystem、status、createdByMe、keyword、createdDateFrom/To	updatedAt/createdAt/businessNo/status	表单名称、来源、项目、版本、状态、当前节点、更新时间；新建、导入、继续草稿、查看历史
PAGE-11 待办审批	view=todo/processed/created/returned/completed、formType、projectId、status、arrivedDateFrom/To、overdue	arrivedAt/dueAt/updatedAt	任务、表单号、项目、申请人、关键金额、当前节点、到达/到期时间；查看、通过、退回、驳回，其他动作按状态进入“更多”
PAGE-12 主数据	resource、companyId、keyword、status、versionStatus	businessNo/name/status/updatedAt	各资源固定编号/名称/所属/版本/状态/更新人；新增、编辑草稿、提交复核、版本对比、生效、停用
PAGE-13 合同与成本	companyId、projectId、counterpartyId、contractKeyword、contractStatus、costCategory、businessDateFrom/To	updatedAt/originalAmount/settlementAmount/pendingPayableAmount/payableAmount/paidAmount	11.6 节合同金额列、已开票/待确认应付/已应付/已付/可付余额；查看、下钻、导出
PAGE-14 收款与发票	页面页签 receipts/invoices；接口参数 companyId、projectId、counterpartyId、keyword、status、dateFrom/To、page、size	收款：updatedAt/receiptDate；发票：updatedAt/requestedDate/amount	收款/开票业务号、公司、项目、客户/对象、金额、分配或发票号、状态、日期；新建/编辑、确认/分配、审核、登记结果、红冲/作废、导出
PAGE-15 进度款与付款	tab=my/finance-check/offline/result/paid/failed、companyId、projectId、supplierId、status、riskCode、submittedDateFrom/To	submittedAt/amount/dueAt/updatedAt	付款号、项目、合同、供应商、申请额、可付额、账户版本、阻断数、状态、申请时间；申请、检查、审核、登记/复核线下结果、退汇/重付
PAGE-16 记账准备	tab=pending/draft/review/exported/result/completed/reversed/void、period、projectId、eventType、status、externalVoucherNo	period/businessDate/amount/updatedAt	事件/凭证号、来源、项目、期间、借/贷合计、状态、导出批次、外部凭证号、当前结果轮次；生成、编辑、复核、导出、登记/复核结果、冲销、重开、历史证据下载、作废
PAGE-17 项目归档	view=prepare/check/returned/archived、companyId、projectId、status、completeness、frozen	updatedAt/completeness/archivedAt	项目、档案包版本、完整率、缺件数、状态、保管到期日、保管状态、提交/审核人；财务确认后生成、检查、提交、退回、补件、归档、冻结/解冻
PAGE-18 文件检索与借阅	companyId、projectId、contractId、counterpartyId、formType、fileName、uploadedBy、uploadedDateFrom/To、originalType、archiveStatus、scanStatus	uploadedAt/displayName/sizeBytes	首次进入不查询；至少填写一个有效条件后返回文件名、类型、项目/对象、版本、大小、上传人、扫描/归档/借阅状态；预览、下载、版本、借阅、归还
PAGE-19 查询与报表	reportCode 加该报表冻结的公司/项目/对象/状态/日期条件；默认当前月	每个报表只开放其列代码，最终补业务编号	六类报表列以 D-08 为准；汇总、下钻、导出必须使用同一 filter hash 和口径版本
PAGE-20 审计日志	occurredFrom/To（默认近 24 小时）、actorId、identityCode、objectType、objectId、action、requestId、result	occurredAt（默认倒序）、eventSequence	时间、用户、身份、范围摘要、对象、动作、结果、原因、请求编号；查看脱敏前后值、导出；没有修改/删除
PAGE-21 权限与配置	resource、keyword、status、versionStatus、effectiveDate	name/code/status/updatedAt/effectiveAt	用户/角色/范围/模板/参数的代码、名称、版本、状态、生效时间、发布人；新增、编辑、启停、发布，按资源动作白名单执行
PAGE-22 系统更新	固定读取当前状态与 objectType=SYSTEM_UPDATE 历史	历史按 occurredAt,desc	当前/最新版本、状态、发布说明、操作时间、目标版本、动作、操作人和结果；获取版本、立即更新、立即更新并重启

列代码、筛选参数、排序字段和导出字段在 OpenAPI 中逐项枚举，前端不得把任意对象属性透传为查询字段。金额汇总由后端在同一筛选下返回，前端只格式化显示；当前页合计与全量合计必须使用不同标签。每个工作台快捷入口都要有 Playwright 断言，证明目标路由、初始筛选、返回恢复和数据数量一致。

9. 14 个表单怎么落地

9.1 统一表单骨架

每张表单都由五部分组成，不把 OA 原样截图当成唯一数据：

1. 来源信息：来源系统、来源单号、来源版本、导入批次、原始文件哈希。
2. 业务信息：公司、项目、合同、往来单位、日期、金额和业务字段。
3. 附件信息：附件名称、类型、是否必需、版本、哈希和“不涉及”说明。
4. 审批信息：节点、人员、意见、时间、动作和前后状态。
5. 财务结果：财务确认、财务事件号、记账准备号、归档状态。

9.2 表单分工和输出

编号	表单	主要发起角色	财务处理角色	首期结构化输出	首期完成标志
OA-01	项目立项审批表	项目管理	财务管理审核预算/付款约定	项目主数据、预算基线、项目事件	项目生效且审批快照完整
OA-02	供应商准入申请	项目管理	财务管理审核税号、账户和资质	往来单位、账户待生效版本	供应商和账户分别复核
OA-03	项目成本合同会签审批单	项目管理	财务管理审核合同额、清单和额度	成本合同、合同额度控制	合同生效、变更可追溯
OA-04	人材机合同应付资金确认单	项目管理	财务管理审核应付、发票和附件	财务终审直接生成 CONFIRMED 应付、合同额度占用和 PAYABLE 会计事件	应付确认且附件齐全
OA-05	项目收款确认单	项目管理	财务管理确认收款和应收核销	财务终审直接生成 CONFIRMED 收款、项目资金台账和 RECEIPT 会计事件；后续再做应收核销	收款证据和审核记录齐全
OA-06	项目进度款支付	项目管理	财务管理检查额度、附件和付款	付款申请、冻结金额、付款任务	通过财务检查并待线下处理
OA-07	银行账户开户审批及账户信息表	项目/财务人员	财务管理复核账户资料	公司银行账户待生效版本	独立复核后可供新业务选择
OA-08	发票开具申请表	项目管理	财务管理审核合同额度和开票条件	带来源版本的 DRAFT 销项开票候选	人工开票结果登记或退回
OA-09	农民工班组实名入场	项目管理	财务管理检查付款附件引用	人员名册版本、工资资料来源	资料归档，人员字段受限访问
OA-10	项目履约进度申报表	项目管理	财务管理复核产值/成本依据	进度版本、收入/成本建议事件	进度审核完成、照片归档
OA-11	项目成本合同结算审批单	项目管理	财务管理确认结算和付款上限	合同结算版本、付款上限	结算附件和审核意见齐全
OA-12	项目验收信息登记表	项目管理	财务管理查看关闭前置项	验收事件、归档触发信号	验收结论和附件完成
OA-13	项目押证费用收取明细表	项目管理	财务管理审核费用口径	扣费/应收候选事件	作为资料和费用依据归档
OA-14	中标项目人员信息表	项目管理	财务管理审核与工资/押证资料关联	项目人员名册版本	新增/变更/驻派记录可追溯

9.3 14 个表单的关键字段

下表是对 14 张原始 OA 截图逐张复核后的源字段清单。它说明源资料中有什么，不表示截图上的每一格都必填；必填条件、下拉值、长度、金额精度和审批路线必须按 9.3.1 节冻结后才能开发对应正式模板。

编号	源图可见的基本字段	重复明细、附件和审批信息
OA-01 项目立项	项目所属公司、申请人/部门、中标时间、项目名称/编号、建设单位、项目地址、建设单位联系人/联系方式、中标金额、项目归属、代理公司/联系方式、是否 EPC、联合体单位	中标人员：岗位、姓名、类别、电话、投标社保要求时段、证件类型、是否上岗；设计：中标设计负责人、设计费、设计资质、联系人/电话；施工：合同名称、对方、金额、资金来源、工程内容、监理方/总监、开竣工日、工期、工程/合同类别、签订/归档时间、合同文本、工程资料；成本：原额/增量、预算总成本、人工/材料/机械/安全文明/间接/税金/不可预见/暂列/暂估/其他成本；财务：付款约定、建设方账号、结算方式、付款描述/比率/金额；审批意见
OA-02 供应商准入	公司名称、供应商名称、联系人、电话、产品、税号、采购额、营业执照、通用附件、供应商类型、纳税人资格类型、诚信资料、账期、是否开通银行承兑、是否主材	账户明细：户名、开户行、账号、准入原因；资质明细：资质、证件号码、有效期、附件；审批意见
OA-03 成本合同会签	公司、是否集采/研发、申请人/部门/时间、项目编号/名称、系统编号、成本合同名称/编号/金额/占比、合同文本及台账、标的物简写、合同类型/子类、供应商、户名、开户行、账号、账龄截止日期	资质附件：营业执照、资质证书、安全生产许可；项目实时成本：目标合同金额、累计签订/支付/收款/扣费、项目余额；量价审核：数量、单价、成本计划、预计超清单、超清单总额、核查情况/审核意见/备注；各节点审批意见
OA-04 人材机应付确认	公司、单据号、填报人/部门/时间、项目编号/名称、成本合同编号/名称/金额/类型/子类、供应商、合同附件/备注、累计应付/已付/已开票、发票文件、含税/不含税金额、税额/税率、发票类型/号码/日期、实际供货时间、本次费用成本类型、本次应付金额、账套、借贷方科目、往来单位	按材料、机械、劳务、业务、运输、临时用工、专业分包、设备采购等成本类型显示条件附件，详见 9.3.2；审批节点和财务意见
OA-05 项目收款确认	到款公司、项目名称/编号、工程类型/地址、业主单位、收款方式、开票申请流程、开票金额、结算方式、本次收款金额、收款账户/账号、收款内容描述	收款证据附件、填表部门/人员/时间；结算会计、财务负责人、董事长审核意见
OA-06 项目进度款支付	公司、申请人/部门/时间、涉诉纠纷、项目编号/名称、合同金额、收款/支付累计、可用资金、合同预计/累计支付、可支付余额、材料/机械/专业分包/人工/其他计划占比与实际占比、是否分包付款、发票附件是否已入账、回款预测附件	支付资料：成本合同编号、标的物、总价、累计应付/已付、已开发票、累计欠付、本次申请/大写金额、供应商、合同类型/子类、附件矩阵；收款账户户名/开户行/账号、其他支付事由/对象/类型/附件；支付明细：日期、方式、公司付款账号、金额；账套、借贷科目、往来单位；审批检查和意见
OA-07 银行账户开户	公司、申请人/部门/时间、开户事由、对账周期、户名、开户行、账号、账户类别、项目编号/名称、开户时间	开户资料是否齐全：总公司营业执照正/副本、法人身份证原件、基本户开户许可证、公司公章/法人私章、股东身份证复印件；预留印鉴附件；审批意见。公司附件按原表要求打码后上传；本表只管理内部账户资料，不连接网银或 U 盾
OA-08 发票开具申请	公司、申请人/日期、项目名称/编号/地址、总承包合同金额、已开票金额、设计费总额/已开票金额、是否设计费、本次开票所属结算方式、客户全称、预计到账时间、联系电话	开票抬头、纳税识别号、注册地址/电话、开户行/账号、开票金额、税率、开票内容、进度表/施工合同关键页附件、发票类型；普通/专票条件必填和审批意见
OA-09 农民工实名入场	填报人/部门/时间、项目编号/名称、班组名称/负责人/联系方式	人员明细：姓名、身份证号、联系方式、合同薪酬标准（月度）、工种、进场时间、紧急联系方式、工资卡开户行、工资卡账号、劳动合同、身份证；审批意见
OA-10 履约进度	公司、填报人/部门/时间、项目编号/名称、施工单位、业主单位、合同额/增量、预算总成本、人工/材料/机械/安全文明/间接/其他成本、合同工期/日历天数、实际开竣工日、交底完成情况	报告年/季度、本期及累计完成产值、本期及累计投入成本、本期应确认增值税收入、完成进度、剩余工期、进度概述、业主审批附件；累计成本分类；4 张项目形象照片；任务明细：名称、开始/完成日、进度、文件、负责人；审批意见
OA-11 成本合同结算	公司、填制人/部门/时间、项目编号/名称、成本合同编号/名称、供应商、合同金额、结算金额、累计已开票、累计已付款	合同结算单/结算单/合同扫描件/发票扫描件/现场照片；质安、成本、财务、工程负责人和盖章情况
OA-12 项目验收	公司、填制人/部门/时间、项目编号/名称	验收明细：阶段、时间、结论、附件、备注；资料室、工程负责人、董事长助理、档案室意见
OA-13 押证费用	公司、申请人/部门/时间、项目名称/编号、收费时间	费用明细按建造师、技术负责人、施工员、质量员、安全员、资料员、标准员记录姓名、人员归属、证件开始时间、收费标准、本月收费金额；公司/办事处每月应收费用；审批意见
OA-14 中标人员	公司、项目名称、是否办理施工许可证、经营负责人姓名/电话、项目负责人姓名/电话、中标金额、合同工期、中标公示日、合同竣工日、实际验收日	证件人员新增：岗位、姓名、类别、电话、地址、证件类型、备注、是否上网/上岗；人员变更：岗位、姓名、电话、原因、日期、备注、是否上网/上岗；驻派人员：姓名、电话、任命/调离时间、工资、备注；资料、工程、结算会计和结算出纳意见

9.3.1 字段元数据冻结规则

每个字段在本文件冻结记录中必须具备：稳定字段代码、中文名称、所属表单/分组、数据类型、最大长度、是否多行、必填条件 requiredWhen、默认值、枚举代码和值、金额/比例精度、单位、导入列名、重复行规则、跨字段校验、敏感等级、脱敏方式、附件关系、下游对象映射和错误文案。源图没有明确给出的内容不得由开发人员猜测；统一进入 D-02，由甲方在原型和样本上确认。

公共字段由系统统一提供，不要求 14 个模板重复配置：documentNo、formType、templateVersion、sourceSystem、sourceNo、sourceVersion、companyId、projectId、status、version、创建/修改人和时间。人员、账户、合同、供应商和项目必须优先引用生效主数据；确需保留来源原文时，同时保存主数据 ID 和只读来源快照。

字段代码一经正式模板发布不得改义或复用。更名只修改显示名称；类型、精度、必填条件或下游含义变化必须发布新模板版本。导入模板的列头、在线表单字段和 OpenAPI 字段都映射到同一字段代码，错误必须定位到表单、分组、行号、列名和字段代码。

9.3.2 OA-04/OA-06 条件附件矩阵基线

现有需求整理稿显示，同一附件可能在不同成本类型下重复出现，系统必须做成“成本类型 → 附件类型 → 必填条件”的版本化矩阵，不能照截图硬编码一张超长表。以下是整理稿中的首版附件集合，待原图重新归档后复核；D-02/D-09 还需要确认哪些必需、哪些允许“不涉及”：

成本类型	首版条件附件集合
材料	材料发票、送货单、结算单、入库单、出库单、领料单、现场验收照片、材料检验检测报告/合格证；进口/经销场景增加贸易商进货证明、个人经营所得完税证明、资源税完税或免税/完税证明
建筑/机械租赁或服务	建筑服务/机械租赁发票、机械设备进出场验收表、机械结算表、机械费用结算单、机械设备权属证明或租赁服务进项证明、机械设备现场照片、个人经营所得完税证明
劳务	劳务发票、考勤表、工资表（签字加按手印）、个人所得税申报表及完税证明、人工成本确认单、工资发放记录、质安审批核签表
业务服务	业务发票、结算单、业务报告
运输	运输服务发票、运输结算单、运输车辆权属证明、运输资质、运输现场照片
临时用工	临时用工花名册、临时用工协议（签字加按手印）、项目日报表、考勤表、个人所得税申报表、质安审批核签表
专业分包	工程服务发票、专业分包工程量清单、专业分包进度款审批单、专业分包结算单/验收单、专业分包验收报告、专业分包结算报告
设备采购	设备采购发票、发货单、送货单、结算单、现场验收设备照片、设备检验检测报告/合格证、设备安装照片；经销场景增加特许经销证明

附件矩阵每次发布保存版本号和生效日期，单据保存提交时使用的矩阵快照。选择“不涉及”必须填写原因并由财务复核；已通过单据更换正式附件时生成新版本并重新进入受影响节点。

9.4 来源表单状态

以下状态码只属于“来源表单”状态域，不与付款、凭证、档案或项目管理 ToDo 状态混用：

DRAFT 草稿
SUBMITTED 已提交
PROJECT_REVIEW 项目审核中
FINANCE_REVIEW 财务审核中
RETURNED 退回补件
REJECTED 驳回
APPROVED 已通过
RESULT_PENDING 待登记结果
ARCHIVE_PENDING 待归档
ARCHIVED 已归档
VOID 已作废

只有当前节点的角色可以执行动作；“通过”不等于“已付款”或“已记账”。

9.5 关键业务对象状态和允许动作

表单、付款、发票、凭证和档案分别保存自己的状态，不能用一个字段表示全部进度。比如 OA-06 已通过，只能说明付款申请审核完成，不能直接把付款结果改成“已支付”。

业务对象	状态主线	关键动作和规则
主数据	DRAFT → REVIEWING → ACTIVE → DISABLED；退回为 RETURNED	新增/变更由另一名授权人员复核；停用后只影响新业务
来源表单	DRAFT → SUBMITTED → PROJECT_REVIEW → FINANCE_REVIEW → APPROVED → RESULT_PENDING → ARCHIVE_PENDING → ARCHIVED；分支为 RETURNED/REJECTED/VOID	可退回后重提；驳回、作废为终止状态；审批通过后生成下游对象
财务事件	PENDING_CONFIRM → CONFIRMED → ACCOUNTING_PENDING → COMPLETED；终止为 VOID	只能从已批准来源生成；错误通过作废/更正事件处理
收款记录	PENDING_CONFIRM → CONFIRMED → PARTIALLY_ALLOCATED → ALLOCATED；终止为 VOID	暂收款允许待分配；核销不得超过确认收款金额
开票申请	新命令主线为 DRAFT/RETURNED → REVIEWING → RESULT_PENDING → ISSUED；分支为 RETURNED/REJECTED/VOID/RED_LETTERED；APPROVED 仅保留为既有数据兼容状态	复核通过直接进入待登记人工结果；作废/红冲记录原因，红字票必须关联原发票
付款申请	DRAFT → REVIEWING → APPROVED → OFFLINE_PENDING → RESULT_RECORDED → RESULT_VERIFIED → PAID；分支为 RETURNED/REJECTED/FAILED/REFUNDED/VOID	失败或退汇进入对应分支，重付必须创建并关联新记录
凭证草稿	DRAFT → REVIEWING → APPROVED → EXPORTED → RESULT_RECORDED → COMPLETED；分支为 RETURNED/VOID	制单与复核分离；作废后可按规则重新生成一张有效草稿
项目财务状态	PENDING/IN_PROGRESS/BLOCKED → COMPLETED	仅财务管理人员在授权范围内执行确认；项目状态须为 DRAFT/ACTIVE/SUSPENDED/CLOSED；成功后作为生成档案包前置条件
档案包	PREPARING → CHECKED → REVIEWING → ARCHIVED；分支为 RETURNED/FROZEN	退回后补件形成新版本；已归档只允许借阅、版本查看和受控下载；冻结时禁止到期处置

所有状态迁移都通过后端命令完成，并校验当前状态、角色、数据范围和版本号。前端只展示允许的按钮，不允许提交任意目标状态。一次动作必须同时写入业务状态、流程任务和审计记录；任一步失败时整笔事务回滚。

状态码按对象分域保存；同名状态只表示相近语义，不表示可以跨对象直接复制迁移规则。第 12.8 节 BACKLOG/READY/IN_PROGRESS/REVIEW/TESTING/ACCEPTED/BLOCKED 是项目任务状态，不得写入业务表。每个对象的全部合法状态、中文显示、允许来源状态、目标状态、命令、权限码和错误码必须在 TODO-S0-023 中冻结并生成状态机测试。

9.6 关键状态、按钮和处理人矩阵

对象/当前状态	有权处理人	页面按钮和前置条件	成功结果
来源表单 DRAFT	创建人或明确代录人	保存、删除草稿、校验、预览、提交；提交前完整校验并二次确认	SUBMITTED，创建流程实例和首个任务
来源表单审核中	当前任务处理人	通过、退回补件、驳回；三者都要意见，退回必须选字段/附件；不提供批量审批金额单据	关闭当前任务并进入下一节点、RETURNED 或 REJECTED
来源表单 RETURNED	原创建人/代录人	编辑被退回项、补附件、重新校验、重提或作废	新版本重提并保留旧版本和退回意见，或进入 VOID
来源表单已提交但首节点未处理	发起人	撤回，二次确认并填写原因	回到可编辑草稿/新版本，原任务关闭并留痕
主数据 DRAFT/REVIEWING	提交人/另一名复核人	提交复核；复核人通过或退回，同人按钮禁用并解释岗位冲突	新版本 ACTIVE 或退回草稿
收款 PENDING_CONFIRM/CONFIRMED	收款经办/财务复核	确认收款、建立分配；金额和证据齐全，分配总额不超确认金额	PARTIALLY_ALLOCATED 或 ALLOCATED，生成财务事件
开票 REVIEWING/RESULT_PENDING/ISSUED	财务审核/开票结果登记人	审核、退回；批准后登记人工开票结果；作废/红冲从当前原票发起并填写原因，可关联已通过检查的结果文件	ISSUED、VOID，或原票 RED_LETTERED 并生成关联红字票
付款 REVIEWING/APPROVED	当前审批人/线下付款经办	审核或退回；批准后只能进入待线下处理，额度、账户、附件、重复和 SOD 全部通过	OFFLINE_PENDING，冻结金额但不发银行指令
付款 OFFLINE_PENDING/RESULT_RECORDED	结果登记人/另一名复核人	登记成功、失败或退汇及回单；复核人不得与登记人相同	PAID、FAILED 或 REFUNDED，释放/结转冻结并生成对应事件
凭证 DRAFT/REVIEWING	记账会计/另一名复核人	编辑分录并填修改原因、提交复核、批准；借贷不平或维度缺失时禁用批准	APPROVED，允许生成一个导出批次
凭证 EXPORTED/RESULT_RECORDED	结果登记人/另一名复核人	登记外部凭证号和结果、复核；关联导出批次和哈希	COMPLETED，项目详情和档案可下钻查看
项目财务 PENDING/IN_PROGRESS/BLOCKED	授权财务管理人员	PAGE-08 显示“确认财务完整”；服务端校验权限、范围、项目/财务状态和版本	COMPLETED，写审计并允许进入 PAGE-17 生成档案包
档案 PREPARING/CHECKED/REVIEWING	已完成财务确认的项目范围内，财务提交人/资料审核人	生成前要求 financeStatus=COMPLETED；检查后无缺件才提交；资料人员异人退回或归档，退回必须列缺件	新版本 RETURNED 或 ARCHIVED
借阅申请待审	借阅申请人/资料批准人	申请填写用途和归还日；批准/拒绝；归还登记需确认文件状态	借阅、拒绝或已归还记录，全部写审计

无功能权限的按钮隐藏；有功能权限但当前状态、资料、金额或岗位互斥不满足时按钮禁用并显示原因。只有低风险、同类且不含金额判断的动作才允许批量处理；R1 的审批、付款结果、凭证复核、敏感下载和归档确认默认逐笔处理。

9.7 岗位职责资料如何进入 R1

岗位职责资料已经对原始压缩包中的 12 份 Excel 完成名称和文本复核，用于识别真实分工、风险点和后续扩展；这不代表 12 份岗位材料中的全部日常工作都必须在第一轮实现。会议原文明确“先做最基础的数据来源、审批、记账准备、存档和查询”，因此按下表取舍；未列为“R1 实现”的职责不得自行扩入第一轮。

岗位资料中的职责	R1 处理级别	第一轮系统行为	明确不做
项目经办、财务审核、资料归档三类分工	R1 实现	以三类身份工作台进入，再用岗位模板、数据范围、金额阈值和流程节点细分权限	不为每份岗位职责另建一套首页或平行系统
成本/应付审核、收款/开票经办、付款结果登记与复核、制单与凭证复核	R1 实现	按 4.4、9.6 节落实同人禁止和服务端权限；财务身份内部仍按岗位模板授权	不把“财务管理人员”做成万能角色
项目可用资金、合同可付额、附件、重复、涉诉/罚款风险	R1 实现	涉诉和未结罚款作为项目人工风险标记，由授权人员录入证据和有效期；付款检查命中有效阻断标记时返回稳定错误码	不连接法院、银行或其他外部平台自动查询风险
主办出纳准备资料、结算出纳线下处理、另一人复核	R1 只实现内部留痕	系统保存付款资料准备人、线下结果登记人和结果复核人；后两者不得相同，实际付款发生在系统外	不设置 payment:execute，不在系统内下发、确认或重放银行指令
公司/供应商账户、专户和账户责任范围	R1 实现基础主数据	保存账户类别、所属公司/项目、用途、脱敏账号和生效版本；历史单据保留使用时快照	不保存 U 盾、UK、网银密码、PIN、印鉴领取密码或银行登录材料，不做 U 盾清点台账
OA-09 工资卡、薪酬标准等来源字段	R1 仅作为受限来源资料	按模板保存、加密、脱敏、审批和归档，只有独立权限可查看	不开发工资计算、工资发放、社保、公积金、个税或自然人税务子系统
税金、报税、银企对账、发票验真	后续单独立项	R1 只允许上传已经取得的人工结果/依据，并关联原单据	不登录税务/银行平台，不自动申报、缴税、对账或验真
借支计息、滚动预算、预算偏差、三流一致、月结调账和账实核对	后续评审	只保留来源附件、备注和扩展位；若未来纳入，单独补页面、状态、权限、公式和 UAT	不在 R1 中暗含利息计提、预算管理或完整总账结账功能
到期催收、季度提醒、自动清点和无人值守处理	本期不自动执行	页面按当前日期计算并展示已有记录的到期/超期状态，用户进入页面后人工处理	不使用 Scheduler、Quartz、消息消费者或 RPA 自动执行业务

R1 可以吸收岗位资料中的“内部控制”，但不能吸收已排除的“外部执行”。任何新增岗位规则先判断是否能落在现有 21 页、14 表单和 F-01～F-14；需要新子系统、第三方权限、自动任务或新增法定财务处理的，统一走后续变更，不改变第一轮完整交付边界。

原始岗位包中的《收集到财务岗位需求》含 OA、T+、网银、U 盾和 RPA 设想，以及不应进入需求文档、源码、样本或日志的外部系统访问信息。R1 只吸收其中“项目余额不足阻断付款、核对收款方和账户、保存回单、制单与复核分离”等内部业务规则；任何账号、密码、地址、证书、U 盾控制和自动登录/点击方案一律不复制、不实现，并由资料负责人限制原件访问。

10. 关键业务规则

10.1 数据不能重复

来源表单唯一键：表单类型 + 来源系统 + 规范化来源单号 + 规范化来源版本。

同一份资料重复上传时，系统要提示已有记录并给出链接，不能重复生成项目、应付、付款或凭证草稿。

10.2 正式数据不能直接覆盖

• 草稿可以编辑和删除。
• 已提交数据修改后要增加版本。
• 已通过数据修改关键字段时重新审核。
• 已付款、已记账或已归档数据不能直接改金额或附件，只能作废、冲销、退回或创建新版本。

10.3 项目资金口径

第一版建议公式：

项目账面余额 = 已确认收款 - 已支付金额 - 已确认扣费 ± 已批准调整
项目可用余额 = 项目账面余额 - 已冻结金额 - 已审批未支付金额

通俗理解：已经批了但还没付的钱，也不能再拿去批第二次。

资金与付款模块验收前，财务负责人需要签字确认：哪些收款算“已确认”、哪些状态进入冻结、哪些业务允许负余额、例外由谁审批。

10.4 合同付款上限

• 结算前累计付款不能超过原合同额加已批准变更。
• 结算后累计付款不能超过生效结算金额。
• 本次可付金额不能超过项目可用余额、合同可付余额和应付余额中的最小值。
• 无合同付款要用独立业务类型、附件清单和审批路线。

10.5 供应商账户

• 付款不能自由手填收款账号，只能选择已复核生效的账户版本。
• 账户新增/变更提交人与复核人不能是同一人。
• 历史付款继续显示当时使用的账户版本。

10.6 发票和附件

• 发票号、税号、金额、日期用于发现疑似重复，不自动判断真伪。
• 材料、机械、劳务、运输、设备等成本类型对应不同附件清单。
• 选择“不涉及”时必须填写原因，并由财务人员复核。
• 已通过后替换附件会生成新版本并重新进入资料/财务审核。

10.7 付款岗位分离

同一笔付款至少要分开：申请、财务审核、线下结果登记、结果复核。结果登记人与复核人必须不同。

系统只记录线下付款结果，不发起银行操作。

10.8 记账准备

• 一个财务事件只能有一张有效凭证草稿，明确拆分的情况除外。
• 借方合计必须等于贷方合计。
• 修改系统建议的科目、金额或项目维度要填写原因。
• 导出后保存导出批次、文件哈希和凭证范围。
• 外部记账完成后由用户登记凭证号和结果，另一名财务人员复核。

10.9 附件和档案

每个文件保存文件名、类型、大小、SHA-256、上传人、上传时间、业务关系和版本。文件替换不覆盖旧文件；正式档案不能由普通页面物理删除。

10.10 敏感信息

身份证、手机号、工资和银行账号按字段加密和脱敏。只有在对应业务节点有权限的人能查看完整值；查看和导出都留审计记录。

10.11 例外审批不是通用绕过

余额暂时不足、无合同业务、非硬性附件缺失或超金额阈值等业务情况，可以按甲方确认的规则发起独立例外申请。例外记录必须包含：例外编号、触发规则、原单据、公司/项目、金额、原因、证据附件、申请人、审批人、决定、有效期和使用结果。

以下控制不允许通过例外放行：未授权访问、供应商账户未生效、同一人登记并复核付款、重复的有效来源/财务事件、借贷不平、恶意文件或审计记录写入失败。

例外被批准后只放行指定单据上的指定规则，并且只能使用一次；其他校验继续执行。例外被退回或驳回时，原业务保持阻断。系统管理员不提供“跳过全部检查”的按钮。

11. Java 技术实现方案

11.1 技术选型

层次	技术	通俗解释
前端	官方 Tencent/tdesign-vue-next-starter	直接使用 TDesign Vue Next 中后台 Starter，再按财务业务裁剪和改造
前端运行环境	Node.js >=22.12.0、npm、package-lock.json	与 Starter 当前要求一致，使用 npm ci 保证依赖可重复安装
后端语言/构建	Eclipse Temurin/兼容发行版 Java 17 LTS、Maven Wrapper 3.9.16	发布字节码和生产运行时固定 Java 17；CI 使用 Java 17 与仓库内 Maven Wrapper
Web 框架	Spring Boot 3.5.16、Spring MVC	负责页面请求、接口、登录和业务逻辑；补丁版本变更必须跑全量回归
权限	Spring Security、Spring Session JDBC	负责本地账号、服务端会话、CSRF 和接口权限，不引入外部身份平台
数据访问	MyBatis Spring Boot Starter 3.0.5	SQL 写清楚，财务查询更方便审查；不同时引入 JPA 形成两套持久化方式
数据库	MySQL 8.4.x LTS、Connector/J 由 Spring Boot BOM 锁定	保存结构化业务数据、状态和审计记录，staging 与 production 使用同一大版本
数据库升级	Flyway Core + Flyway MySQL	每次改表都有版本；正式建表前必须锁定一个明确支持 MySQL 8.4 的版本，启动出现“数据库版本未测试”警告即不通过基线评审
文件解析	Apache POI、Commons CSV	读取 Excel 和 CSV 模板
测试	JUnit 5、MockMvc、Testcontainers、Vitest、Playwright	自动验证业务规则、接口、真实数据库和浏览器主流程
架构检查	ArchUnit、JaCoCo	防止模块互相乱调，检查测试覆盖率

11.2 TDesign Starter 前端实施规范

前端硬性结论已经冻结：第一轮不再重新选 UI 框架、不另画一套后台、不另建前端工程。前端开发的工作方式只有一种：在现有 frontend/ TDesign Vue Next Starter 中增加或修改菜单和路由，在 pages/ 增加财务页面，用 tdesign-vue-next 与 tdesign-icons-vue-next 组合业务组件，接通本文件定义的 Java API，再按页面合同自行联调、测试和修复到验收通过。“做成腾讯这个样子”在本项目中的准确含义是遵守 TDesign 的布局、组件、Design Token 和交互习惯，不是复制腾讯商标、产品名称或演示数据。

生效时点：本节是当前 R1 开发的唯一正式前端实现方式。PAGE-14 已按该技术方向完成模块级实现；后续任何路由、API、Store、权限或业务组件改动都必须继续接受本节合同和证据门禁，不得因开发已启动而降级。

前端硬规范一页判定表

普通使用者不需要理解全部工程细节，只要按下表即可判断前端是否符合要求；任一“硬性结果”不满足，页面不得合并、不得演示为完成功能，也不得计入 R1 完成率。

判定项	硬性结果	一眼可见或可自动检查的证据
唯一工程	只在现有 frontend/ 内开发，不新增第二个前端、第二入口、第二套后台或 iframe 拼装	仓库只有一个生产 package.json、vite.config.ts、src/main.ts 和根挂载
唯一视觉体系	页面使用当前 TDesign Vue Next Starter 的 side 布局、间距、Token、信息密度和交互规则	PAGE-03～21 共用同一侧栏、顶部栏、面包屑、页签和内容区
唯一控件体系	通用控件只用 tdesign-vue-next；图标使用 Starter 的 t-icon 或 tdesign-icons-vue-next 导出组件，两者都属于 TDesign 图标体系	依赖和源码扫描无第二 UI 库、自绘同类图标或复制私改的 TDesign 源码
业务组合组件	只有跨页面业务语义才建立 components/business，且内部仍只组合 TDesign 组件	每个新增组合组件有 COMP-###、用途、测试、可访问性和批准记录
菜单与页面	菜单、顺序、路由和 PAGE-01～21 只按 7.3、8.24～8.26 节实现	本地路由、菜单、pageId、权限码和 routes.json 一致，无演示菜单或死入口
真实功能	所有正式页面和按钮连接 Java 真实 API、MySQL、权限、状态和审计	production Network 无 Mock/静态 JSON；刷新、重登后数据仍在；失败和越权被服务端拒绝
腾讯样式边界	“腾讯样式”只指 TDesign 规范，不使用腾讯 Logo、名称、产品文案或远程素材	D-11 前使用临时文字和 TDesign 默认主色；production 无腾讯商标和 Starter 演示品牌
财务后台形态	页面安静、紧凑、便于扫描和重复录入，不做营销首页	无 Hero、渐变背景、装饰插画、嵌套卡片、大标题宣传文案或无业务意义动效
状态与异常	每页完整处理加载、空态、无权、冲突、校验失败、网络失败和写入结果	401/403/404/409/422/500、重复点击、会话失效均有自动化用例和可理解反馈
交付质量	开发团队自行完成实现、联调、修复和回归，不把基础问题留给甲方 UAT	Vitest、Playwright、axe、production 构建、三档分辨率和 FE-GATE 全部通过

前端强制组件规则（不可变）

以下规则是“使用 TDesign”在代码评审中的可执行定义，适用于 PAGE-01～PAGE-21 的正式页面：

1. 业务页面不得直接替代 TDesign 控件：不得用原生 <button>、<input>、<select>、<table> 或自写弹窗/分页/下拉组件替代 TDesign 同类组件。语义性布局标签（例如 <main>、<section>、<dl>）可以使用，但不得承担控件交互。
2. 图标只能走批准来源：操作图标使用 Starter 已有的 t-icon 命名图标或 tdesign-icons-vue-next 导出组件；禁止手绘同类 SVG、复制 Starter/TDesign 图标源码或从运行时公网地址加载图标。甲方 Logo 只能使用 D-11 批准的本地资源。
3. 组件选择必须可追溯：每个页面和可见操作在 routes.json、components.json、operations.json 中记录实际组件名；新增组合组件必须有 COMP-###，项目专用控件还需产品负责人批准。
4. 样式只能通过统一 Token 调整：颜色、字号、间距、圆角、阴影和控件高度来自 TDesign Token 或集中项目变量；禁止在页面里复制一套“腾讯风格”CSS、使用渐变/Hero/装饰插画或用 !important 强行改写组件行为。
5. 组件不等于功能完成：TDesign 组件只是界面实现，按钮必须同时绑定权限码、状态前置条件、OpenAPI operationId、审计事件、错误码、真实 MySQL 数据和自动化测试；只有摆出按钮或接 Mock 的页面一律不计完成。
6. 例外必须先批准：TDesign 确实没有对应能力时，前端负责人提交替代方案、可访问性、测试和维护人，经批准后才可新增项目专用控件；没有书面 COMP-### 记录不得合并。

因此，代码评审可以用一句话判断：页面里看到的每个控件，都能在 TDesign 组件或批准的 TDesign 组合组件中找到来源；页面里看到的每个动作，都能在操作合同和真实 API 中找到去处。

前端直接采用官方 GitHub 仓库 Tencent/tdesign-vue-next-starter。本方案核对基线为：默认分支 develop、提交 1f183fa089d07183235dc69dbd76b8b2c4a6d8bb、Starter 版本 0.14.0、MIT 许可证。当前已经把该提交作为一次性源代码底本导入本仓库 frontend/；正式业务开发开始后只在这一工程内原位增加财务菜单、页面、组件和功能，不使用会持续漂移的 latest 初始化结果，也不把上游仓库作为运行时依赖或 Git 子模块。

当前 package-lock.json 锁定的核心版本如下；开发前底座核验已经执行 npm ci、类型检查和完整构建，2026-08-11 又对当前业务代码执行 Vue 类型检查和 production 构建。两类结果分别证明底座和当前构建可用，不自动证明全部 S1 任务完成。升级 Starter 或任一核心依赖都要单独建任务，通过漏洞扫描、类型检查、Vitest 和 Playwright 回归后才能合并。

基线项	Starter 锁定版本
Node.js	>=22.12.0
Vue	3.5.39
Vite	8.1.5
TypeScript	6.0.3
TDesign Vue Next	1.20.2
TDesign Icons Vue Next	0.4.4
Pinia	3.0.4
Vue Router	5.1.0
decimal.js	10.6.0，只用于前端十进制金额解析、比较和格式化

Starter 固定视觉和交互基线

“做成腾讯这个样子”必须落实为当前 Starter 和 TDesign Token 的可核验基线，不允许靠每个页面自行模仿。R1 固定值如下；甲方品牌只替换名称、Logo 和经 D-11 批准的品牌主色，不改变页面结构和控件体系。

基线项	R1 固定规则	禁止偏离
布局模式	沿用 Starter side + light：固定侧栏、固定顶部栏、面包屑、路由页签和内容区；PAGE-01～02 使用 BlankLayout	不开放顶部/混合导航、深色模式、布局设置或第二套后台壳
侧栏尺寸	沿用当前 Starter 展开占位 232px、收起控件 64px/占位 72px 的机制；只允许用户展开或收起，不允许业务页覆盖宽度	不在页面写侧栏定位、宽度或额外左边距，不建立第二导航栏
顶部与内容区	顶部高度使用 --td-comp-size-xxxl（当前基线默认 64px）；内容区使用 Starter 的 --td-comp-paddingTB-xl、--td-comp-paddingLR-xl	不按页面硬编码另一套头部高度、页面外边距或滚动容器
颜色与主题	确认 D-11 前使用 TDesign 默认品牌色 #0052D9；背景、文字、边框、状态和交互色使用 TDesign Token	不散落自定义十六进制颜色，不使用渐变、光斑、装饰背景或腾讯商标色拼贴
字体与层级	使用 TDesign 字体 Token；页面标题、分区标题、正文、辅助文字按中后台层级显示；字体不随视口缩放，字间距为 0	不在业务卡片中使用 Hero 级大字，不用负字距或装饰字体制造“品牌感”
圆角与容器	使用 TDesign 默认圆角；项目新增卡片圆角不超过 8px。页面分区默认无外框，卡片只用于单个重复对象、指标组、弹窗或确需边界的工具	不把整页做成浮动卡片，不嵌套卡片，不用大圆角胶囊承载普通文字命令
密度与稳定性	财务页面以扫描、比较和重复录入为优先；查询栏、工具栏、表格、分页使用稳定尺寸，Loading、Tag、按钮和错误文字不得引起布局跳动	不做营销型首屏、装饰动效、超大留白或动态内容撑开工具栏
操作表现	一个页面只设一个主要实心按钮；熟悉工具动作优先 TDesign Icon 并提供中文 Tooltip；行内直接动作最多 3 个	不用文字胶囊替代已有图标，不自画图标，不让危险动作和普通动作同级
目标终端	R1 只验收桌面 Chrome/Edge 的 1366×768、1440×900、1920×1080；复杂宽表在表格内部滚动	不为小屏强行压缩文字或控件，也不得在目标桌面分辨率出现页面整体横向滚动

若升级 TDesign 导致 Token 默认值变化，必须建立依赖升级任务、输出升级前后截图和回归结果，再决定是否更新本表；页面开发不得先行硬编码旧值或新值。

导入时保留上游 MIT LICENSE，并在 THIRD_PARTY_NOTICES.md 记录仓库地址、基线提交、导入日期和本项目修改说明。后续上游更新采用人工对比和选择性合并，禁止生产构建自动跟随 develop 分支。

Starter 保留和改造边界

Starter 内容	处理方式	财务系统落地要求
Vite、Vue、TypeScript、ESLint、Stylelint、Husky、npm 锁文件	保留	统一开发、检查和构建命令；只使用 npm，不混用 Yarn 锁文件
src/layouts、菜单、面包屑、页签、结果页	保留并精简	改成三类身份导航；删除无关布局选项和演示入口
Pinia、Vue Router、动态路由框架	保留并重写权限数据	当前角色和菜单由 Spring Boot 返回；前端路由只改善体验，后端仍做最终鉴权
Axios 请求封装	保留结构并重写拦截器	使用 /api/v1、Spring Session Cookie、CSRF、ProblemDetail、请求编号、幂等键和版本号
登录页	保留视觉结构并重写逻辑	删除注册入口和示例 Token 登录，接入 PAGE-01 登录及 PAGE-02 身份选择
Mock 数据	只允许在 S0 原型模式隔离保留	S1 正式业务开发开始后，正式页面和 production 都禁止启用 Mock；自动化测试 fixture 放入独立测试目录，不得进入正式数据或生产包
Dashboard、列表、表单、详情示例	作为组件参考后删除	按 PAGE-01～PAGE-21 重建真实财务页面，不把产品/电商演示文案带入系统
Logo、登录背景、外部链接和远程 API 地址	全部盘点并替换	使用甲方本地品牌资源；删除 Starter 默认公网 API 和外部资源依赖
深色模式、主题设置、语言切换	MVP 精简	首期固定中文和审核通过的浅色财务主题，减少无业务价值的测试组合

当前 .env* 已把 VITE_API_URL 留空并把前缀固定为 /api/v1，正式配置必须保持同源；开发代理目标只能由本机/受控环境变量提供，不能进入 production 产物。Starter 遗留源码中仍存在演示公网地址和远程素材，须按文件级清单全部删除。Starter 示例通过 Pinia 保存 Token，本项目改为 Spring Security 服务端 Session；浏览器只保存安全的 HttpOnly 会话 Cookie，不在 Pinia、localStorage 或 sessionStorage 持久化 Token、权限明细和敏感业务数据。Axios 开启同源凭据和 CSRF 头处理；GET 查询可按规则重试，提交、审批、付款结果、凭证生成等写命令禁止自动重试。

Starter 自带 test 脚本目前只是占位文本，本项目必须补充真实的 Vitest 和 Playwright 配置，并把 npm run test、npm run test:e2e、npm run build 接入 CI。TDesign 的 JavaScript、CSS、图标、字体和品牌资源全部随前端产物部署，不使用公网 CDN。

页面能力	TDesign 组件基线	实施规则
系统框架	Layout、Aside、Header、Menu、Breadcrumb	三类身份共用框架，菜单按当前角色生成；不能只靠隐藏菜单控制权限
列表和台账	Table、Pagination、Input、Select、DateRangePicker	后端分页、筛选、排序；金额列右对齐并显示千分位和两位小数
表单和明细	Form、FormItem、Input、InputNumber、DatePicker、Select、Upload	金额使用基于 Input 的 MoneyInput 业务组合组件；InputNumber 只用于安全整数；动态字段映射到受控组件，后端校验决定是否受理
审批和状态	Steps、Timeline、Tag、Alert、Dialog、Drawer	状态颜色和术语统一；高风险动作必须二次确认并填写原因
操作反馈	MessagePlugin、NotificationPlugin、Loading、Empty	明确显示成功、失败、字段错误和请求编号，不只提示“操作失败”
图标	Starter t-icon / tdesign-icons-vue-next	按钮优先使用熟悉的 TDesign 图标并提供文字或提示，不自画同类 SVG 图标

前端统一封装 AppTable、AppForm、MoneyInput、SecureField、FileUploader、ApprovalTimeline、StatusTag 和 ResultPage 等业务组件。主题只通过 TDesign Design Token/CSS 变量和项目级样式层调整，不逐页复制颜色、间距和按钮样式。界面采用安静、紧凑、便于重复操作的财务后台布局，不套用营销页结构，不堆叠卡片。

中文为首期唯一界面语言，日期按北京时间展示。目标办公分辨率为 1366×768、1440×900 和 1920×1080；表格明细允许区域内滚动，页面主体不整体横向溢出。R1 支持发布时最新两个稳定大版本的桌面 Chrome 和 Edge；IE、移动端和小于 1280px 宽度的复杂录入不作为本期验收范围，其他现代浏览器显示不兼容结果页。字号、间距、圆角和控件高度使用 TDesign Token，不使用 vw 缩放字体或因动态内容改变固定工具栏尺寸。可见性、禁用状态和路由守卫只负责交互提示，所有权限、状态和金额规则仍由 Java 后端执行。

Starter 提供的是前端工程和交互骨架，不等于本系统的业务功能已经实现。登录、三类身份、金额权限、审批状态、文件权限和岗位互斥均以本方案和 Java 后端为准。

Starter 原位开发是唯一前端实施方式

frontend/ 是第一轮唯一前端工程。开发人员必须在已经拉取并锁定的 Starter 内增加财务菜单、路由、页面和业务组合组件，复用它的布局、主题、路由、Pinia、国际化和构建链路；不得另建第二个 Vue 工程、复制一份 Starter、引入另一套后台模板，或先做独立页面再用 iframe 拼回系统。

Starter 位置	第一轮处理	硬性结果
src/main.ts、App.vue	保留唯一入口和 TDesign/Pinia/Router 挂载	不增加平行入口，不重复注册 UI 库
src/layouts/index.vue、layouts/components/*	在现有 Layout、侧栏、顶部栏、面包屑和内容区上改造	固定 side 布局；菜单、页签、身份切换和内容区保持一套框架
src/layouts/setting.vue、store/modules/setting.ts	移除业务用户可见的布局/主题试验项，固定批准 Token	不允许用户切成顶部/混合导航或改变核心导航行为
src/router/index.ts、router/modules/*	删除演示路由，按 7.3 节建立本地组件映射和隐藏详情路由	根跳转、403/404、面包屑、页面 ID 和权限码一致；后端不下发组件文件路径
src/permission.ts	接真实 Session、当前身份和权限摘要	未登录、会话失效、切换身份、无权路由均有确定行为
store/modules/user.ts	删除 main_token、Mock 登录和固定 roles:['all']	只保存非敏感会话摘要，不在浏览器持久化 Token
store/modules/permission.ts	从本地路由表结合后端权限码生成当前菜单	前端过滤只改善体验，手输 URL 和接口仍由后端拒绝
store/modules/tabs-router.ts	将默认首页改为当前身份工作台，切换身份清空旧页签	不残留 /dashboard/base 或上一身份详情页
utils/request/index.ts	重写为同源 Cookie Session、CSRF、统一成功响应和 ProblemDetail	不发送 Starter 示例 Authorization Token；写请求不自动重试
pages/login/*	保留 TDesign 视觉结构，删除注册、扫码、手机号和示例账号	只提供本地账号密码登录、改密/重置说明和真实错误反馈
pages/dashboard、pages/list、pages/form 等演示域	只在设计阶段参考组件用法，正式开发时删除	产品、电商、腾讯云等示例文案、数据、路由和接口为零
pages/workbench、projects、forms、finance、archives、reports、governance	按 8.24 节在 Starter 中新增真实业务页面	PAGE-01～PAGE-21 共用统一模板、组件、权限、状态和错误规则
api/generated、api/client	由 OpenAPI 生成类型和基础客户端，只增加薄封装	不在页面手写重复 DTO，不让接口类型靠人工猜测
mock/、vite.config.ts、.env*	原型 Mock 明确隔离；业务开发和 production 禁用，代理同源 /api/v1	production 无 Mock、默认公网 API、远程静态资源和演示数据
assets/、style/	使用本地甲方素材和集中 Token 覆盖	不复制腾讯商标，不散落颜色/圆角/间距，不形成第二套视觉体系
package.json、package-lock.json	保持 npm 锁定，补真实测试命令；新增依赖经过评审	不混用包管理器，不加入第二 UI 库，依赖漏洞达到发布门槛

V2.9 Starter 文件级执行清单

下表以锁定的 Starter 上游路径和当前未评审实验代码为审计对象，是 S1 前端改造的固定代码评审清单。“当前基线/实验风险”只描述开工前看到的代码，不代表已验收；文件改名或拆分时，Pull Request 必须记录旧路径、新路径和本表对应项，不得以“已经试过”或“目录调整”为由跳过正式合同和测试。

当前文件/目录	当前基线/实验风险	S1 固定动作	完成证据
src/main.ts、src/App.vue	唯一 Vue/TDesign/Pinia/Router/i18n 启动链	保留并只接入全局错误、会话和样式初始化	生产包只有一个挂载入口，TDesign 只注册一次
src/router/index.ts	已有 PAGE-01～21 实验路由和根入口，但尚未通过路由合同、管理员入口、query 白名单和异常验收	按 7.3 节保留唯一聚合、滚动和异常路由；根入口按会话状态进入登录、PAGE-02 或当前身份入口	刷新、直达、401、403、404、管理员入口和身份切换路由测试通过
src/router/modules/*	已有 finance.ts 实验菜单，管理员已改为 SYSTEM_ADMIN，项目查看权限已部分按 4.6 节改名；工作流、档案、审计和系统治理等试验权限码仍未统一，旧 homepage.ts/user.ts 已移除	按 7.3 节重建本地菜单映射，统一 pageId、完整权限码、SYSTEM_ADMIN、顺序、隐藏路由、面包屑和安全返回路径	菜单、routes.json、OpenAPI 权限码和 UAT-029/035 逐项一致
src/router/modules/result.ts	已有 403/404/500/网络等结果页，但部分按钮仍返回已删除的 /dashboard/base	改为本系统中文文案、请求编号和基于当前身份的安全返回动作	8.24 节异常状态有页面和自动化测试，不存在死路由
src/layouts/index.vue、src/layouts/blank.vue、src/layouts/components/*	支持 side/mix、页签和多种布局	固定 side，保留侧栏、顶部、面包屑和页签；替换品牌，删除业务用户布局实验入口	PAGE-03～21 始终同一 Layout，PAGE-01～02 使用 BlankLayout
src/layouts/setting.vue、src/store/modules/setting.ts	可切换布局、主题等演示设置	移除业务用户入口，只保留代码内批准的浅色 Token	页面不存在顶部/混合导航、深色和任意主题切换
src/permission.ts	已有 Session、PAGE-02 和路由守卫试验，尚未覆盖权限版本变更、纯管理员入口和全部会话失效场景	按认证合同完成 Session、PAGE-02、权限版本、会话失效和服务端 403；保留进度条/异常跳转	手输 URL、权限变更与切换身份不泄露上一身份数据
src/store/modules/user.ts	已移除持久化示例 Token并接入会话试验，但身份代码、权限摘要和管理员隔离尚未正式冻结验收	只保存非持久化会话摘要、可用身份、当前身份和显示所需权限，不保存 Token 或业务事实数据	Storage/Pinia 扫描无 Token、密码、敏感数据；三类业务身份与 SYSTEM_ADMIN 合同通过
src/store/modules/permission.ts	已使用本地路由和服务端权限列表做实验过滤，但路由权限码尚未与 4.6 节统一	使用本地路由白名单 + 服务端权限码过滤菜单，并以 routes.json/operations.json 做 CI 校验	后端不返回组件路径；前后端无权访问均被拒绝
src/store/modules/permission-fe.ts	纯前端角色过滤备选方案	删除或移出生产引用，不作为授权事实来源	production bundle 与路由链不引用该方案
src/store/modules/tabs-router.ts	已开始把默认入口改为 PAGE-02，仍须核验所有旧 Dashboard 常量和缓存路径	首页随当前身份变化；切换身份清空页签和缓存	上一身份页签、详情和查询缓存全部消失，源码无 /dashboard/base
src/utils/request/index.ts、Axios.ts	已有 Cookie/CSRF 试验，仍保留 Starter 通用封装、注释和可配置重试路径	收口为同源 Cookie/CSRF、统一成功体、ProblemDetail、请求编号、幂等键、版本和下载处理	所有写请求不自动重试；401/403/409/422/500 行为符合 11.2 节
根 vite.config.ts、.env*	已移除 Mock 插件并使用本地 Java 代理试验，但开发目标和 production 同源/禁外连仍未形成 CI 证据	原型 Mock 显式隔离；正式开发和 production 禁用；production 只使用同源 /api/v1	production 构建扫描无 Mock、默认本机目标、公网地址和远程资源
根 mock/*	Starter 演示 Mock 目录仍在源码仓库，虽未接入当前 Vite 插件	正式业务开发时删除；测试 fixture 移入独立测试目录并禁止打包	production 产物、Network 和源码引用扫描为零
src/pages/login/index.vue、src/pages/login/components/*	已移除注册、手机号、二维码和示例账号并接入登录试验	按 PAGE-01 复核账号密码、改密提示、锁定/停用/会话失效和 PAGE-02 去向	真实 CSRF/Session 正常及失败流程、键盘和三档截图通过
src/api/list.ts、detail.ts、permission.ts 等演示 API	调用 /get-list、采购、演示菜单接口	删除，替换为 OpenAPI 生成客户端和 api/client 薄封装	页面不手写重复 DTO，不调用演示接口
src/pages/dashboard/*、list/*、form/*、detail/*	Starter 演示业务页	参考组件用法后删除；不得改名冒充财务页面	演示文案、路由、数据和接口扫描为零
src/config/global.ts	品牌前缀仍为 tdesign-starter	改为甲方确认的本地系统前缀	DOM/CSS/存储键不再使用 Starter 产品名
src/config/style.ts、src/config/color.ts	side/light 和多主题配置	保留 TDesign Token 机制，锁定批准的 side/light 与 D-11 品牌值	不出现散落颜色、第二主题或用户任意改色
src/pages/workbench、projects、forms、tasks、finance、archives、reports、governance	PAGE-01～21 均已有合同指向的独立非占位组件；PAGE-13/14 已通过模块级验收，PAGE-15 核心付款链已定向验证，PAGE-18/19 为本地阶段实现完成	保持 PAGE-13/14 回归稳定；按 7.3、8.24～8.26 节逐页评审其余范围；对每页分别补齐查询、详情、命令、下钻、导出、权限范围和异常交互；清理 Starter 演示内容和未使用组件	PAGE-13 证据见 13.1.2，PAGE-14 证据见 13.1.1，PAGE-15 证据见 13.1.3，PAGE-18/19 阶段证据见 13.1.4；其余每页真实 API、DTO、权限/范围、状态、命令、异常和截图证据齐全；production 无演示或占位内容冒充完成
src/components/business	MoneyInput.vue 已在 PAGE-14 使用十进制字符串并通过页面级回归；components.json 已建立 PAGE-01～21 基础组件需求清单，但还不是完整 COMP-* 批准登记	保持 PAGE-14 使用方式；只用 TDesign 基础组件建立正式业务组合组件，为其他金额、敏感字段、文件、审批和错误状态补合同与测试	PAGE-14 定向检查持续通过；完整 COMP-* 元数据、组件测试、axe 和 PAGE-10/12/15/16 金额回归仍归全局任务
src/api/generated、src/api/client	当前不存在正式合同客户端	从冻结 OpenAPI 生成类型/基础客户端，手写层仅处理会话、错误和文件	CI 重新生成无差异，页面无重复 DTO/Axios 直连

文件级清单的“删除”指从正式 R1 源码、路由和生产依赖中移除；设计阶段保留参考副本时必须放在不会被 Vite 扫描和打包的位置，且不能由业务路由访问。清单每一行都必须在 TODO-S1-028 的评审记录中给出提交、测试或扫描证据。

禁止直接修改 node_modules、复制 TDesign 组件源码后私改、手画已有 TDesign 图标，或用全局 CSS 大面积覆盖组件内部结构。确实缺少的财务交互先由 TDesign 基础组件组合成 components/business 业务组件；只有经过技术负责人登记用途、可访问性、测试和维护责任后，才允许开发项目专用的无同类控件。

前端执行优先级和禁止事项

前端发生冲突时按以下顺序执行：本文件已冻结的业务和页面规则 → 当前锁定版本的 TDesign Vue Next 组件 API → Starter 既有布局与代码规范 → 开发人员个人偏好。任何人不得以“实现更快”或“看起来更好”为由绕开前三项。

以下规则是第一轮硬性规范：

1. 所有通用可视控件使用 tdesign-vue-next，所有通用图标使用 Starter t-icon 或 tdesign-icons-vue-next；不引入 Element Plus、Ant Design Vue、Naive UI、Vuetify 或其他第二套组件库。
2. 允许自建业务组件，但必须由 TDesign 基础组件组合，不能复制一套按钮、表单、弹窗、表格、提示或状态标签。
3. ECharts 只用于 PAGE-04～06、PAGE-19 的必要图表，不承担按钮、筛选器或其他界面控件。
4. 不复制腾讯商标、腾讯 Logo 或 Starter 演示产品名称。这里的“腾讯样式”指 TDesign 的布局、组件、Token 和交互规范；系统名称、Logo 和品牌归属按 D-11 使用甲方素材。
5. 不使用公网 CDN、远程字体、远程图片和外链脚本，不在生产包保留 Starter 的产品、电商、注册、主题试验或开发演示内容。
6. 不通过大量自定义 CSS 把 TDesign 改成另一套视觉体系；业务页面不出现渐变背景、营销大标题、装饰图形、嵌套卡片或与财务工作无关的动效。
7. 不允许 Mock、静态 JSON、浏览器本地数据或硬编码统计值冒充已完成功能。S1 之后，正式页面只能通过 OpenAPI 对应的真实接口读写数据。
8. 不允许用一个通用占位组件承载多个正式路由，也不在正式页面显示“页面已接入”“功能建设中”“后续开放”等开发过程文案；未完成页面不进入 production 菜单，完成页面必须具备本页真实字段、操作、异常状态和接口。

t-card 只用于一组同类指标、单个重复业务对象或确实需要边界的工具区域，不把整个页面和每个页面分区都套成卡片，也不在卡片内继续嵌套卡片。操作型页面保持紧凑、安静、适合长期扫描和重复录入。

前端唯一性、依赖和图表白名单门禁

“只在 Starter 中开发”和“只使用 TDesign”必须由自动检查证明。CI 对受版本控制的 frontend/ 源码执行以下门禁，扫描时排除 node_modules/、dist/ 和测试制品：

1. 只允许一个 package.json、一个根 vite.config.ts、一个 src/main.ts 和一处生产 createApp；只允许一个 Vue 根挂载、一个 Router、一个 Pinia 和一条 TDesign 注册链。
2. 生产 UI 直接依赖白名单只有 tdesign-vue-next 和 tdesign-icons-vue-next。禁止第二套 UI/后台模板；测试、构建和纯数据处理依赖不因此自动获得界面控件资格。
3. echarts 是唯一图表引擎例外，只允许 PAGE-04～06、PAGE-19 按需加载并绘制业务图表；筛选、按钮、菜单、表单、提示、分页和弹窗仍必须使用 TDesign。没有必要图表时优先使用数字和表格。
4. production 源码和产物不得包含 iframe 页面拼装、Starter 外部链接、运行时 HTTP(S) 静态资源、公网 CDN、第二前端入口、演示路由或 Mock 引用。Starter 当前 FrameContent.vue、GitHub 跳转和演示品牌必须在 S1 生产链路中删除。
5. 每次 production 构建输出 FE-GATE-{gitCommit}.json，记录入口数量、直接依赖、路由/pageId、外链、iframe、Mock、第二 UI 库、包体和扫描结论，并保存制品 SHA-256；任一硬规则失败即阻止合并和发布。
6. Playwright 页面测试接入 axe 自动检查，关键页面的 critical/serious 可访问性问题为零；登录、查询、录入、审批和弹窗主路径另做键盘 Tab、焦点可见、中文可访问名称和非纯颜色表达的人工/自动化断言。

本门禁验证的是工程结构和运行结果，不替代后端权限、业务状态和金额规则测试。开发人员不得通过把依赖改名、复制组件源码、动态加载远程代码或把第二套控件放进业务组件目录来规避扫描。

菜单、组件和功能的逐项落地合同

第一轮前端工作的准确含义是：在唯一的 frontend/ Starter 中，按 7.3 节增加或修改菜单和本地路由，按 8.24～8.26 节增加页面与操作，优先直接使用 TDesign 组件，确有跨页面业务语义时再用 TDesign 组件组合业务组件，并接通 Java 真实接口。 不接受先做一套独立页面、再讨论如何接入 Starter，也不接受先把按钮摆出来、以后再补权限和接口。

每个菜单、页面主操作、表格行操作、弹窗确认、导入、导出、上传、下载和状态动作都必须在开发任务或 Pull Request 中逐项登记以下合同：

合同项	必须写清楚什么	不通过的典型情况
页面和入口	pageId、菜单层级、路由、是否隐藏路由、来源页和安全返回路径	新增了页面但没有正式入口；详情刷新后丢失上下文
TDesign 实现	直接使用的 TDesign 组件/图标，或批准的 components/business 组合组件	自造按钮、表格、弹窗、图标或引入第二组件库
用户和权限	可见身份、权限码、公司/项目范围、金额阈值和岗位互斥	只在前端隐藏按钮，没有服务端拒绝规则
对象和状态	目标业务对象、允许当前状态、按钮隐藏/禁用条件和禁用原因	前端任意提交目标状态；状态不允许时仍可点击
接口合同	OpenAPI operationId、请求/响应 DTO、版本号、幂等键和稳定错误码	页面直接拼 Axios、手写重复 DTO、写请求自动重试
操作结果	成功后的新状态、重新读取对象、列表/工作台刷新范围和下一步去向	只弹“成功”但页面仍显示旧数据；前端乐观伪造结果
异常和恢复	Loading、空态、401/403/404/409/422/500、网络失败、未保存离开和重试边界	报错后输入丢失、无请求编号、冲突时覆盖他人数据
审计和敏感数据	审计事件、请求编号、脱敏、下载/查看理由以及浏览器存储限制	敏感值进入 URL、日志、Pinia 或 Storage
验证证据	Vitest/Playwright 用例、三档分辨率截图、真实 Network 请求和 production 扫描	只有开发截图、使用 Mock、没有失败/越权测试

组件选择顺序固定为：TDesign 现成组件 → 本项目已批准的 TDesign 业务组合组件 → 经评审后新增的 TDesign 业务组合组件。只有 TDesign 确实不存在同类能力时，技术负责人才能批准一个项目专用控件；审批记录必须写明用途、替代方案、可访问性、测试和维护人。不得以设计稿像素差异为由复制 TDesign 源码或改写其基础交互。

新增业务组合组件或项目专用控件必须在所属任务/PR 建立唯一 COMP-### 记录，至少包含：componentId、使用页面/动作、TDesign 组件检索证据、已比较的替代方案、不直接复用的原因、组合结构、可访问性结果、测试链接、维护人、前端负责人和产品负责人批准、批准日期及复核版本。普通业务组合组件由前端负责人批准；项目专用控件还必须由产品负责人共同批准。没有记录、只有口头批准或 TDesign 已有同类组件时不得合并。

每个可见操作另建立唯一 OPS-{pageId}-{序号} 记录，并冻结 visibilityPermission、allowedStatuses、enabledWhen、disabledReasonCode、operationId、后端拒绝错误码、成功目标状态和 fixture ID。统一规则是：没有功能权限时隐藏；有功能权限但状态、资料、金额或 SOD 不满足时禁用并显示稳定原因；服务端最终拒绝必须与矩阵中的错误码一致。该矩阵同时生成前端组件测试、后端授权/状态测试和 Playwright 断言，避免同一按钮在页面、接口和测试中使用不同规则。

S1 在唯一 frontend/ 工程内建立以下机器合同，固定由代码评审和 CI 校验，不由开发人员各自保存表格。截至 2026-08-13，三个 JSON 初版已入库并由 Vitest 校验；下表同时写明当前已有字段和未完成的目标字段，不得把初版误当成全量合同门禁已通过：

机器合同	固定路径	保存内容	维护规则
页面/路由合同	frontend/contracts/routes.json	初版已有 pageId/path/component/pageType/pageTemplate/requiresAuth/description/breadcrumb/roles/permission；目标补齐菜单层级、默认入口、query 白名单和首个读取 operationId	与 7.3、8.24～8.26 节一致；路由变更必须同时更新并通过扫描
组件合同	frontend/contracts/components.json	初版已有组件库政策和 PAGE-01～22 必需基础组件；目标补齐全部 COMP-###、TDesign 检索证据、组合结构、使用页面、可访问性、测试、维护人和批准记录	无记录的新增业务组件或项目专用控件不得合并
操作合同	frontend/contracts/operations.json	初版已有 operationId/method/path/pages/api wrapper 及少量变体；目标补齐全部 OPS-* 的可见权限、允许状态、启用条件、禁用原因、错误码、成功状态和 fixture	最终生成前端、后端和 Playwright 的共同断言；目标字段缺项时不得把全量操作合同标为完成

这些 JSON 是本文件在代码阶段的机器可校验实现合同，不是新的需求文档。业务含义和范围仍只以本文件为准；机器合同与本文件不一致时停止开发，先按变更流程更新本文件，再同步生成或修改机器合同。

Pull Request 只有同时满足以下条件才能合并：页面/操作合同完整；本地路由和 7.3 节一致；OpenAPI 生成代码无未提交差异；production 不引用 Mock、演示页、公网资源或第二 UI 库；权限和状态的正向/越权用例通过；Chrome/Edge 三档截图无重叠或溢出；Console、Network 和 Storage 检查通过。对应证据统一归入 TODO-S1-023、TODO-S1-028 和所属业务任务，缺任一证据时任务保持 REVIEW，不能标成“前端已完成”。

前端新增菜单、页面、组件和功能的固定步骤

当前及后续所有前端改动都按下面顺序完成。步骤可以由不同开发人员承担，但同一个页面必须有一名闭环负责人；不得把“加菜单”“画页面”“接接口”拆成互不负责的完成项。

1. 先定位现有页面合同：确定所属 PAGE-*、一级菜单、页面模板、默认身份、权限和业务对象。R1 当前固定 22 页，新增 PAGE 编号或一级菜单必须先走需求变更。
2. 在 Starter 原位加入口：在现有本地路由模块增加或修改路由和 meta，同步菜单顺序、隐藏路由、面包屑、页签、返回路径和 routes.json；后端只返回权限摘要，不返回组件路径。
3. 用 TDesign 组装页面：先选择 11.2 节八类模板和现成 TDesign 组件；跨页面业务语义才建立 components/business 组合组件并登记 COMP-*，不得先自造控件。
4. 逐个绑定可见操作：每个主按钮、行操作、弹窗确认、上传、下载、导入和导出建立 OPS-*，写清可见权限、允许状态、启用条件、禁用原因、金额/SOD、成功状态和错误码。
5. 先有合同再接真实接口：从已冻结 OpenAPI 生成类型和客户端，绑定 operationId、版本、幂等键、CSRF、请求编号和审计事件；页面不得直接拼接 Axios、DTO 或目标状态。
6. 补齐所有运行状态：同时实现首次加载、刷新、空态、字段错误、401、403、404、409、422、500、网络失败、重复点击、未保存离开和服务端成功后重读。
7. 验证后才进入菜单：通过组件测试、服务端授权/状态测试、Playwright 正向/越权/失败测试、三档截图、Console/Network/Storage 和 FE-GATE 后，才允许出现在 production 菜单并计入 R1。

改动类型	必须同步的内容	明确禁止	完成证据
加菜单/路由	7.3 节映射、路由 meta、当前身份权限、面包屑/页签/安全返回、routes.json	只写一个可点击菜单；复制第二套路由配置；后端下发任意组件路径	四类账号菜单截图、直达/刷新/403/切换身份测试
加页面	PAGE 合同、页面模板、默认查询、真实 DTO/API、Loading/Empty/错误、页面测试	通用占位页、静态 JSON、Mock、空按钮、“建设中”文案	页面主流程和失败流程、三档截图、真实 Network 请求
加业务组件	TDesign 检索结果、COMP-*、组合结构、使用页面、可访问性、维护人和测试	复制 TDesign 源码、直接改 node_modules、引入第二 UI、自画同类控件	components.json、组件测试、axe 和批准记录
加按钮/状态动作	OPS-*、权限、状态、allowedActions、operationId、幂等/版本、审计、成功后重读	只靠前端隐藏；前端直接改状态；乐观显示财务成功	operations.json、前后端正向/拒绝测试、请求编号和审计证据
加筛选/列/导出	8.26 节白名单、OpenAPI 参数/列枚举、URL 非敏感 query、后端同口径导出	前端任意字段透传、当前页数据冒充全量、导出越权/未脱敏数据	列表/导出同 filter hash、总数和权限断言
加样式/主题	TDesign Token 或集中项目变量、目标分辨率和前后截图	页面散落颜色/字号/圆角、!important 改写组件、渐变/Hero/装饰图	Stylelint、Token 扫描、三档视觉回归
加图表	仅 PAGE-04～06/PAGE-19、业务问题、同口径数字、下钻和按需加载	图表作装饰、替代筛选控件、引入第二图表引擎	数据口径测试、下钻测试、包体报告

一个需求如果同时涉及菜单、页面、组件和操作，必须按上表形成一个纵向任务并同时验收，不得拆成四个相互独立的“已完成”任务。单独完成其中任意一行都只是过程进度。

固定布局和导航

第一轮只交付一套确定的桌面后台布局，不把 Starter 的布局试验功能暴露给业务用户。

区域	固定规则
登录/身份选择	PAGE-01、PAGE-02 使用 Starter BlankLayout；保留 TDesign 登录视觉结构，使用甲方本地品牌素材，不显示业务侧栏
登录后框架	PAGE-03～PAGE-22 固定使用 Starter side 布局：左侧菜单、顶部栏、页签栏和内容区；不渲染面包屑
左侧菜单	使用 7.3 节固定层级和顺序；支持 Starter 默认展开/收起；一级菜单图标来自 TDesign Icons，名称不得由开发人员自行缩写
顶部栏	显示当前身份、身份切换、系统通知和用户菜单；删除代码仓库、外部帮助、语言切换、主题切换和布局设置入口
面包屑	首期删除可见面包屑；菜单和页签承担层级识别，隐藏详情路由通过显式返回按钮或安全返回路径返回来源列表
页签栏	保留 Starter 路由页签；工作台固定不可关闭，详情页签显示“页面名 + 业务编号”；切换身份时清空旧身份页签和缓存
内容头	静态列表、工作台、台账和配置页直接进入紧凑操作栏、查询区或指标区，不显示面包屑，也不重复堆叠模块名、页面名和功能说明；保留读屏可识别的隐藏 h1，刷新、新建、导入、导出等动作进入右侧紧凑工具栏。项目详情、表单详情等动态页面显示业务编号、对象名称和状态，并提供明确返回路径
页面滚动	页面主体纵向滚动；宽表格只在表格区域横向滚动；弹窗、抽屉和固定操作栏不得覆盖页面标题或分页

主题固定为 TDesign 浅色模式和已确认的品牌主色；首期不交付深色模式、多语言、顶部导航、混合导航或用户自定义主题。允许本地保存的只有菜单收起、非敏感表格列显示等界面偏好；身份、权限、业务记录、查询结果和敏感字段不得持久化到浏览器。

页面模板

PAGE-01～PAGE-22 必须从以下模板组合，不允许每个开发人员各做一套页面结构。

模板	适用页面	固定结构	主要 TDesign 组件
公共入口	PAGE-01～02	本地品牌区 + 登录表单或三张身份卡 + 明确错误反馈	Form、Input、Button、Alert、Loading
工作台	PAGE-04～06	紧凑指标行 + 待办/异常主列表 + 常用入口 + 最近动态；下一屏内容在首屏可见	Statistic、Table、Tabs、Tag、Timeline、必要的 Card
列表/台账	PAGE-07、09、13～16、18～20	紧凑操作栏 + 查询栏 + 数据表格 + 分页；不额外渲染面包屑或重复静态页名，详情通过路由或抽屉进入	Form、Input、Select、DateRangePicker、Table、Pagination、Dropdown
业务详情	PAGE-08	项目摘要 + 状态/主操作 + 页签 + 描述信息/明细表/时间线；跨对象都有返回路径	Descriptions、Tabs、Table、Timeline、Tag、Drawer
录入/导入	PAGE-10、PAGE-12 的编辑状态	分组表单 + 动态明细 + 附件 + 校验结果 + 底部固定操作栏	Form、Row、Col、Input/MoneyInput、仅整数 InputNumber、Select、DatePicker、Upload、Alert
审批处理	PAGE-11、PAGE-17	待办列表 + 业务摘要 + 附件/校验 + 审批时间线 + 当前节点动作	Table、Descriptions、Steps、Timeline、Dialog、Textarea
配置管理	PAGE-21	配置分类 + 版本化列表/详情 + 新增编辑弹窗；生效操作和业务操作分离	Tabs、Tree、Table、Form、Dialog、Popconfirm
系统更新	PAGE-22	版本摘要 + 独立检查 + 下载进度/完成确认 + 安装重启 + 审计历史	Steps、Table、Alert、Tag、Button
结果/异常	全部页面	明确状态、可理解原因、请求编号和下一步动作	Result、Empty、Alert、Button、Skeleton

工作台不是营销首页，不使用大幅 Hero、插画横幅或仅作装饰的图表。图表必须回答一个业务问题，并提供同口径数字和可下钻明细；无有效业务含义时使用表格。

控件和操作规则

场景	必须使用	统一规则
明确命令	Button + TDesign Icon	每个页面只设一个最主要的实心主按钮；常见工具动作优先图标并有 Tooltip；危险动作使用错误色和二次确认
二元设置	Switch 或 Checkbox	不用两个文字按钮模拟开/关；开关旁显示当前含义
少量互斥选项	RadioGroup/RadioButton	选项不超过 5 个；身份选择属于业务入口卡片，不用下拉框隐藏
多个工作视图	Tabs	只切换同一对象/同一页面内的视图，不用标签页代替左侧主导航
状态	Tag + 文本	颜色、文字和必要图标同时表达，不能只靠颜色区分
更多行操作	Dropdown	表格行内直接动作最多 3 个，其余收进“更多”；主动作顺序全系统一致
简单确认	Popconfirm	用于影响小、可立即说明的动作；涉及原因、金额或附件时使用 Dialog
辅助详情	Drawer	只展示快速查看或轻量编辑；长表单、复杂审批和可分享详情使用独立路由
进度和历史	Steps/Timeline	Steps 表示当前流程节点，Timeline 表示已发生事实，不混用
颜色/枚举配置	ColorPicker/Select	颜色必须显示色样；有限选项不让用户手输自由文本

无功能权限的操作不显示；有权限但因当前状态、数据不齐或岗位互斥暂不可执行的操作显示为禁用，并用 Tooltip 或邻近提示说明原因。前端不能自行推断最终可执行性，点击写操作后仍以服务端返回为准。

列表、表格和查询

• 查询栏默认展示 3～6 个高频条件，低频条件放进“更多筛选”抽屉；查询、重置和导出位置在所有台账保持一致。
• 列表查询条件、页码、排序写入 URL query，刷新和返回时恢复；不得把敏感查询值写入 URL。
• 默认每页 20 条，可选 20/50/100；分页、排序和筛选全部由后端执行，排序字段使用接口白名单。
• 表头和操作列按需要固定；金额右对齐，日期/状态保持稳定宽度，长名称省略并可悬停查看；不能因加载、Tag 或按钮出现造成列宽跳动。
• 宽表格在自身容器滚动，左侧业务编号/名称和右侧操作列固定；页面主体不得出现整体横向滚动条。
• 批量操作先显示已选数量和影响范围，提交后按服务端结果逐条反馈；涉及正式金额和审批的动作默认不提供未经确认的批量修改。
• 导出前显示当前筛选范围、预计条数和脱敏说明；导出由后端按当前身份重新查询，前端不得导出已缓存但当前无权的数据。
• 表格首次加载显示骨架或加载态，后续刷新保留原表结构并显示区域 Loading，避免页面闪烁和布局跳动。

表单、金额、日期和敏感字段

• 常规表单在 1440px 及以上优先两列，长文本、附件、动态明细和审批意见独占整行；1366×768 下不得遮挡标签、错误提示或底部按钮。
• 必填标记、字段说明、单位和错误位置统一。提交失败时页面顶部显示错误摘要并自动聚焦第一个错误字段；后端 422 字段错误必须映射到具体字段、明细行或附件。
• 草稿允许保存未完整数据；“提交审批”前执行完整校验并二次确认。离开有未保存修改的页面时必须提示，提交成功后以服务端返回对象重新渲染。
• 金额接口统一传十进制字符串，前端新增并锁定 decimal.js@10.6.0；MoneyInput 使用 TDesign Input 的视觉和交互并以字符串保存值，金额字段不得直接绑定只返回 JavaScript number 的 InputNumber。数量/次数等安全整数仍可使用 InputNumber。禁止用 Number、parseFloat 或二进制浮点数计算、比较、合计财务金额，最终金额规则始终由 Java BigDecimal 复算。
• 金额显示为 1,234.56，负数显示明确负号，零显示 0.00，空值显示 --；币种不是人民币时同时显示币种代码，不能只靠货币符号判断。
• 纯日期使用 yyyy-MM-dd；时间由后端以 UTC 时间点返回，前端按北京时间显示为 yyyy-MM-dd HH:mm:ss，导出文件注明时区。
• 身份证、手机号、工资和银行账号默认只接收服务端脱敏值。SecureField 的查看完整值动作单独鉴权、填写原因、由后端返回短时结果并写审计；切换页面、身份或会话失效后立即清除，不进入日志、URL、Pinia 或浏览器存储。
• 状态词只使用第 9.4～9.5 节定义的中文和状态码。草稿用中性状态、处理中用品牌色、待关注/退回用警告色、成功用成功色、驳回/作废/失败用错误色，但文字始终保留。

文件上传和预览

• 统一使用 FileUploader 组合 TDesign Upload，展示允许格式、单文件大小、数量、上传进度、失败原因和重试入口。
• 客户端只做快速格式和大小提示；文件是否接收由服务端重新检查 MIME、扩展名、大小、病毒和权限，服务端未确认前不得显示“上传成功”。
• 同名文件不静默覆盖，替换正式附件必须生成新版本并说明原因；删除按钮只对未提交临时文件出现。
• 预览、下载和完整敏感文件访问都调用受控接口，不拼接服务器文件路径，不打开公网预览服务；预览失败时仍可按权限下载原文件。
• 上传、预览和下载组件必须覆盖空文件、超限、格式不符、病毒命中、网络中断、会话过期和无权限状态。

Loading、空态、错误和并发状态

状态	页面必须怎么做
首次加载	使用 Skeleton 或内容区 Loading，保留稳定尺寸；超过合理时间后显示可重试状态
无数据	使用 Empty，说明是“暂无数据”还是“当前筛选无结果”；有创建权限时才显示创建入口
401 会话失效	清除会话内业务状态并回到登录页；重新登录后只恢复安全路由，不恢复敏感表单内容
403 无权限	使用 Starter 403 结果页，显示请求编号和返回授权入口；不得短暂闪现无权数据
404 不存在	区分业务对象不存在和路由不存在，提供返回来源列表入口
409 版本/重复冲突	停止覆盖，使用对话框说明“数据已被他人更新/记录已存在”，提供重新加载或打开已有记录，不自动重放写请求
422 业务校验失败	字段错误就近显示，跨字段规则使用页面 Alert；保留用户尚未提交成功的输入
500/网络失败	使用统一错误结果或通知，显示请求编号、重试和返回入口；不展示堆栈、SQL 或内部路径
写操作处理中	主按钮进入 Loading 并防止重复点击，携带 Idempotency-Key；审批、金额、结果登记和凭证生成不做乐观成功
写操作成功	显示明确对象和结果，从服务端重新读取状态、金额和可执行动作，不只弹出“成功”后停留在旧数据

弹窗关闭后焦点回到触发控件；键盘 Tab 顺序、表单标签、按钮名称和焦点样式必须可见。所有图标按钮有中文 Tooltip 或无障碍名称，不能只靠图形让普通用户猜测功能。

前端目录、命名和代码边界

S1 裁剪 Starter 后，前端目录固定为：

frontend/src/
├── api/
│   ├── generated/             # OpenAPI 自动生成类型和基础客户端，禁止手改
│   └── client/                # CSRF、请求编号、错误映射、下载等薄封装
├── assets/                    # 甲方本地品牌和静态资源
├── components/
│   └── business/              # MoneyInput、SecureField、ApprovalTimeline 等跨页面业务组件
├── constants/                 # 状态、权限码、展示映射
├── hooks/                     # 沿用 Starter 命名的可复用组合逻辑，不保存全局业务数据
├── layouts/                   # 从 Starter 保留并裁剪的框架组件
├── pages/
│   ├── workbench/
│   ├── projects/
│   ├── forms/
│   ├── finance/
│   ├── archives/
│   ├── reports/
│   └── governance/
├── router/modules/            # 按一级菜单分路由；组件路径由本地映射决定
├── store/modules/             # 会话、当前身份、菜单和非敏感 UI 偏好
├── style/                     # 沿用 Starter 的 TDesign Token 覆盖和少量全局布局
└── utils/                     # 无业务状态的纯函数

页面目录以业务域命名，每个复杂页面使用 index.vue + components/ + hooks/ + __tests__/。Vue 组件用 PascalCase，组合函数用 useXxx，Pinia Store 用 useXxxStore，路由名使用稳定英文 PascalCase，权限码统一为 模块:资源:动作，例如 payment:request:approve。

Pinia 只保存登录会话摘要、当前身份、菜单权限和非敏感界面偏好，不缓存可作为事实来源的付款、凭证、账户或审批对象。服务端数据以接口响应为事实来源；跨页面传递对象使用业务 ID 并重新鉴权读取，不把完整对象塞进路由或浏览器存储。

全局样式只放字体、Token、布局和公共可访问性规则；页面样式默认 <style scoped lang="less">。除集中定义的品牌/状态 Token 外禁止散落十六进制颜色；禁止用 !important 覆盖组件行为，确因上游兼容需要时必须写明原因和清理任务。业务组件不得直接调用未封装 Axios，页面不得手写与 OpenAPI 重复的 DTO 类型。

11.3 为什么采用模块化单体

首期系统使用一个 Java 应用、一个数据库和一个受保护文件目录，不拆微服务。

通俗理解：先做成一个结构清楚的完整系统，部署和排查都简单；内部仍按模块分开，后续确有需要再拆。

11.4 运行结构

flowchart LR
    U["浏览器"] -->|"HTTPS"| APP["Java 财务项目系统"]
    APP --> DB["MySQL 数据库"]
    APP --> FS["受保护附件目录"]
    APP --> LOG["审计与运行日志"]
    FILE["人工导出的 OA/Excel/记账资料"] --> U
    U --> OUT["人工下载/登记外部结果"]

运行时默认不访问互联网，也不连接 OA、网银、T+、税务或 HR。

11.5 后端模块

Java 模块	负责内容	对应页面
iam	用户、角色、数据范围、身份选择、互斥权限	PAGE-01～03、21
project	项目、进度、人员、验收和项目总览	PAGE-04、07、08
masterdata	公司、供应商、账户、合同、字典和版本	PAGE-12
source	14 类模板、导入、来源单据和审批快照	PAGE-09、10
workflow	待办、审批、退回、驳回和操作记录	PAGE-11
contractcost	合同额度、成本分类、应付和结算	PAGE-13
receivable	收款、应收核销和发票申请	PAGE-14
payment	付款申请、额度检查、结果、退汇和回单	PAGE-15
accounting	财务事件、凭证草稿、导出和人工结果	PAGE-16
archive	文件、版本、档案包、检索和借阅	PAGE-17、18
reporting	查询、报表、下钻和导出	PAGE-19
audit	审计日志和敏感操作记录	PAGE-20

模块之间不能直接修改别人的数据库表；跨模块业务通过明确的服务方法完成。

11.6 数据库表组

表组	主要表	保存什么
用户权限	iam_user、iam_role、iam_user_role、iam_permission、iam_role_permission、iam_scope、iam_sod_rule	用户、角色、权限、公司/项目范围和互斥规则
主数据	md_company、md_project、project_risk_flag、md_counterparty、md_contract、md_bank_account_version	公司、项目、人工风险标记、供应商、合同和账户版本
来源表单	src_template、src_template_field、src_import_batch、src_source_document、src_document_version、src_field_value、src_approval_snapshot	模板/字段版本、导入批次、来源单据、字段值和审批快照
审批	wf_definition、wf_definition_version、wf_instance、wf_task、wf_action	流程版本、当前节点、待办和每次审批动作
合同成本	contract_change、payable、cost_ledger	合同变更、应付和项目成本
收款发票	receivable、receipt、allocation、invoice	应收、收款、核销和发票
付款	payment_request、payment_result、payment_refund	付款申请、人工结果、退汇和重付
资金与例外	project_fund_control、fund_ledger、exception_request	项目余额、冻结/已批未付和一次性例外审批
记账	finance_event、voucher_draft、voucher_line、export_batch、accounting_result	财务事件、凭证草稿、导出和人工结果
档案	file_object、file_link、archive_package、archive_borrow	文件元数据、业务关联、档案包和借阅
审计	audit_log、export_log	操作前后值、导出范围和责任人
系统控制	sys_idempotency_record、sys_parameter_version	幂等请求结果和参数版本

所有核心业务表包含内部 ID、业务编号、状态、版本、创建/修改人和时间；公司、项目只在业务适用时必填，IAM、全局模板、文件本体、审计和系统控制表不得为了形式完整写入虚假公司/项目。金额使用 DECIMAL(20,2)，税率/比例使用 DECIMAL(9,6)，Java 统一使用 BigDecimal，禁止浮点数误差。来源表单使用规范化来源键，财务事件使用来源事件唯一约束；状态字段只允许定义过的枚举值，所有外键、金额范围和版本约束必须由数据库迁移脚本建立。

11.6.1 核心关系和数据库不变量

对象	必须存在的关系/唯一性	修改和删除规则
用户授权	用户 → 身份/岗位模板 → 逐条权限 → 公司/项目范围/金额阈值；同一管理员账号不得拥有财务业务身份	授权版本化；变更后失效旧会话；历史审计保留当时身份快照
项目	必须属于一个公司；(company_id, business_no) 唯一	生效后编号不变；关闭/归档不物理删除
往来单位/账户	证照号规范化后唯一；账户必须属于往来单位或公司并保存版本	新增/变更由另一人复核；停用只阻止新业务，历史单据保留账户快照
合同	必须关联公司、项目和往来单位；同公司合同编号唯一	原额、批准变更和结算额分开保存；生效后只做版本、变更或作废
来源单据	(form_type, source_system, normalized_source_no, normalized_source_version) 唯一；每个版本关联模板版本、字段值、附件和审批快照	已提交版本不可覆盖；新版本关联前一版本；正式版本不物理删除
流程	一个来源版本最多一个有效流程实例；一个任务只能产生一次终结动作	流程定义版本发布后不改义；动作与业务状态同事务写入
财务业务	应付、收款、开票、付款必须关联来源单据和项目；来源事件键唯一	更正通过新记录、作废、红冲、退汇或重付关系表达，不改写历史结果
资金控制	每个项目/币种一条当前控制记录；资金台账为追加式分录	余额由台账校验重算；禁止直接更新余额绕过业务命令
财务事件/凭证	来源事件键唯一；一个事件最多一张有效凭证草稿；凭证行借贷合计相等	作废旧草稿后才可重新生成；导出批次和人工结果不可覆盖
文件/档案	文件对象以 SHA-256 标识内容，业务关系和版本单独保存；档案包保存文件清单快照	同内容可复用文件对象但每个业务关系独立审计；已归档版本不物理删除
审计	request_id + event_sequence 唯一，关联用户、身份、对象和动作	只追加、不更新、不删除；业务人员无写接口

外键默认使用 RESTRICT，不使用级联删除清理正式财务数据。可删除的临时上传和未提交导入批次必须与正式表隔离并由用户显式操作；R1 不设置自动清理定时任务。MySQL 数据字典在开工前必须把本节每个不变量展开为列、类型、默认值、检查约束、唯一键、外键和索引，评审通过后才允许创建首个正式 Flyway 迁移。

11.6.2 V2.9 数据库合同

本节给出 R1 首个正式 Flyway 迁移必须遵守的最小列级合同。字段长度、枚举和动态表单字段仍要用 D-02 的已确认值填充，但开发人员不得另行改变表意、金额类型、唯一键和历史保留规则。

通用列规则

• 实体表统一使用 id BIGINT UNSIGNED AUTO_INCREMENT 内部主键和 public_id CHAR(26) 唯一 ULID；API 只暴露 public_id。
• 需要人工识别的对象增加 business_no VARCHAR(64)；同一业务域内的唯一范围见下表，不用数据库 ID 充当业务编号。
• 可变实体统一包含 status VARCHAR(32)、version INT UNSIGNED NOT NULL DEFAULT 0、created_at/updated_at DATETIME(3)、created_by/updated_by BIGINT UNSIGNED。关联表、追加式台账和日志表按下表使用自己的序号/时间，不强塞无意义状态。
• 字符集固定 utf8mb4，列名使用 snake_case；时间按 UTC 保存。金额使用 DECIMAL(20,2)，币种使用 ISO 4217 CHAR(3)，比例/税率使用 DECIMAL(9,6) 并按 0～1 保存。
• 普通金额列必须 >= 0；只有资金台账差额、冲销和批准调整列允许负数。凭证行 debit_amount/credit_amount 均非负且每行只能一侧大于零。
• 正式状态使用本文件冻结的 VARCHAR 代码和 CHECK；业务表不使用通用 deleted。JSON 列必须有 schema_version 或关联规则版本，不能成为绕开字段字典的任意数据袋。
• 所有外键默认 ON DELETE RESTRICT。条件唯一使用生成列或等价唯一索引，不能只依赖 Java 查询后再插入。

表/表组	最小必需列	唯一键与关键约束	必建查询索引
iam_user	login_name VARCHAR(64)、display_name VARCHAR(128)、department_name VARCHAR(128) NULL、password_hash VARCHAR(255)、must_change_password BOOLEAN DEFAULT TRUE、failed_count INT DEFAULT 0、locked_until DATETIME(3) NULL、通用状态/版本/审计列	public_id、规范化 login_name 唯一；失败次数非负	(status)、(locked_until)
iam_role、iam_permission	code VARCHAR(64)、name VARCHAR(128)、identity_code VARCHAR(32) NULL、状态/版本列	各自 code 唯一；权限表不保存通配符	(identity_code,status)、(status)
iam_user_role、iam_role_permission	用户角色含 user_id/role_id/valid_from/valid_to/status/version；角色权限含 role_id/permission_id	(user_id,role_id,valid_from)；(role_id,permission_id)	(role_id,status)、(permission_id)
iam_scope	user_role_id、permission_id、scope_type VARCHAR(16)、company_id/project_id NULL、amount_limit DECIMAL(20,2) NULL、valid_from/valid_to、状态/版本列	(user_role_id,permission_id,scope_type,company_id,project_id,valid_from)；金额阈值非负	(company_id,project_id,status)、(user_role_id,status)
iam_sod_rule	rule_code VARCHAR(64)、left_permission_id/right_permission_id、object_type VARCHAR(32)、hard_block BOOLEAN、状态/版本列	(rule_code)；左右权限不能相同	(object_type,status)
Spring Session 表	使用当前锁定 Spring Session JDBC 官方 MySQL schema，并由独立迁移纳管	Session 主键、过期索引按官方 schema；不得自行删减以保存“当前身份”	官方过期时间和 principal 索引
md_company	business_no、name VARCHAR(200)、normalized_tax_no VARCHAR(64) NULL、状态/版本/审计列	business_no 唯一；非空规范化税号唯一	(status)、(name)
md_project	company_id、business_no、name VARCHAR(200)、customer_id NULL、owner_user_id、start_date/end_date NULL、currency CHAR(3) DEFAULT 'CNY'、状态/版本/审计列	(company_id,business_no)；结束日不得早于开始日	(company_id,status)、(owner_user_id,status)
project_risk_flag	project_id、risk_type VARCHAR(32)、reason VARCHAR(1000)、evidence_file_link_id NULL、effective_from/effective_until NULL、blocking BOOLEAN、状态/版本/审计列	同项目同类型同生效期不得有重叠有效阻断记录	(project_id,status,effective_from,effective_until)
md_counterparty	counterparty_type VARCHAR(32)、name VARCHAR(200)、normalized_tax_no VARCHAR(64) NULL、状态/版本/审计列	非空规范化税号唯一；类型为冻结枚举	(name,status)、(counterparty_type,status)
md_contract	company_id/project_id/counterparty_id、business_no、name、original_amount、approved_change_amount DEFAULT 0、settlement_amount NULL、currency、状态/版本/审计列	(company_id,business_no)；各金额非负	(project_id,status)、(counterparty_id,status)
md_bank_account_version	owner_type、company_id NULL、counterparty_id NULL、account_category、account_name、bank_name、account_no_ciphertext VARBINARY、account_no_hash CHAR(64)、masked_account_no、version_no、valid_from/valid_to、状态/审计列	CHECK 要求公司/往来单位恰有一个非空；按生成的 owner key + version_no 唯一；同范围生效账号哈希唯一；不允许 U 盾/密码/PIN 列	(company_id,status)、(counterparty_id,status)、(account_no_hash)
src_template	form_type VARCHAR(16)、template_version INT、name、schema_version、published_at NULL、状态/版本/审计列	(form_type,template_version)	(form_type,status)
src_template_field	template_id、field_code VARCHAR(64)、label、data_type、max_length/precision/scale NULL、required_when_json、enum_code NULL、sensitivity、mapping_code NULL、sort_order	(template_id,field_code)；定义发布后不可改义	(template_id,sort_order)
src_import_batch	batch_no、form_type、source_system、source_file_id、file_sha256、total_rows/valid_rows/error_rows、状态/版本/审计列	batch_no；同用户/类型/文件哈希的未取消有效批次唯一	(status,created_at)、(file_sha256)
src_source_document	form_type、source_system、source_no、source_version、template_id、company_id、project_id NULL、current_version_id NULL、状态/版本/审计列	(form_type,source_system,normalized_source_no,normalized_source_version)	(company_id,project_id,status)、(form_type,status)
src_document_version	source_document_id、version_no、previous_version_id NULL、template_id、submitted_at NULL、snapshot_sha256、审计列	(source_document_id,version_no)	(source_document_id,version_no)
src_field_value	document_version_id、field_code、row_no DEFAULT 0、类型化值列或 typed_value_json、schema_version	(document_version_id,field_code,row_no)；值必须匹配模板数据类型	(document_version_id)、(field_code)
src_approval_snapshot	document_version_id、node_code、actor_name/actor_id NULL、action、opinion、acted_at、source_snapshot_json	(document_version_id,node_code,action,acted_at)	(document_version_id,acted_at)
wf_definition、wf_definition_version	定义含 code/name/status/version；版本含 definition_id/version_no/definition_json/schema_version/status/published_at	wf_definition.code；(definition_id,version_no)	(status)、(definition_id,status)
wf_instance	definition_version_id、source_type/source_public_id、current_node_code、状态/版本/审计列	每个来源版本最多一个非终态实例，使用条件唯一索引	(source_type,source_public_id)、(status)
wf_task、wf_action	任务含 instance_id/node_code/sequence_no/assignee_id/due_at/status/version；动作含 task_id/sequence_no/action/opinion/return_points_json/actor_id/acted_at/request_id	(instance_id,node_code,sequence_no)；(task_id,sequence_no)；任务仅一次终结动作	(assignee_id,status,due_at)、(instance_id,status)
contract_change	contract_id、change_no、change_amount、effective_date、source_version_id、状态/版本/审计列	(contract_id,change_no)；批准后才计入额度	(contract_id,status)
payable、receivable	business_no、source_version_id、company_id/project_id、contract_id NULL、counterparty_id、amount/outstanding_amount、currency、状态/版本/审计列	各自来源事件键唯一；余额在 0～原额之间	(project_id,status)、(counterparty_id,status)
cost_ledger	project_id、contract_id NULL、source_event_key、cost_category_id、amount、business_date、finance_event_id NULL、追加审计列	source_event_key 唯一；只追加，更正用反向/更正记录	(project_id,business_date)、(cost_category_id)
receipt、allocation	收款含来源版本、公司、项目可空、客户、金额、未分配额、日期、证据文件、状态/版本；核销含 receipt_id/receivable_id/sequence_no/amount	收款来源事件键唯一；(receipt_id,receivable_id,sequence_no)；核销合计不得超收款/应收	(project_id,status)、(customer_id,status)
invoice	来源版本、公司、项目可空、客户、申请/发票编号、含税额、税额、税率、开票日、original_invoice_id NULL、状态/版本/审计列	公司范围非空发票号唯一；红冲/作废必须关联原票	(project_id,status)、(customer_id,status)
payment_request	来源版本、公司/项目、合同、应付可空、账户版本、申请金额、冻结金额、check_snapshot_json/check_rule_version、状态/版本/审计列	来源事件键和业务编号唯一；冻结额不超申请额	(project_id,status)、(account_version_id,status)
payment_result、payment_refund	结果含 payment_request_id/result_no/result_type/result_amount/result_at/receipt_file_link_id/recorded_by/verified_by NULL/status/version；退汇含 payment_result_id/sequence_no/amount/reason/status	结果号唯一；登记人与复核人不同；(payment_result_id,sequence_no)	(payment_request_id,status)、(verified_by,status)
project_fund_control	project_id、currency、confirmed_receipt、confirmed_deduction、approved_adjustment、frozen_amount、approved_unpaid、paid_amount、version	(project_id,currency)；各非负列及公式不变量由命令和测试保证	(project_id,currency)
fund_ledger	project_id、currency、source_event_key、entry_type、delta_amount、balance_after、occurred_at、追加审计列	source_event_key 唯一；允许冲销负数，只追加	(project_id,currency,occurred_at)
exception_request	business_no、source_type/source_public_id、rule_code、reason、amount NULL、evidence_json、valid_until、used_at NULL、申请/审批人、状态/版本	(source_type,source_public_id,rule_code) 同时最多一个有效批准例外；硬控制代码禁止插入批准态	(status,valid_until)、(source_type,source_public_id)
finance_event	source_event_key、source_type/source_public_id、event_type、公司/项目、金额、币种、状态/版本/审计列	source_event_key 唯一	(project_id,event_type,status)
voucher_draft、voucher_line	草稿含事件、期间、摘要、借/贷合计、状态/版本；分录含 voucher_id/line_no/account_code/debit_amount/credit_amount/project_id/counterparty_id	每事件最多一个非作废草稿；(voucher_id,line_no)；借贷合计相等	(status,period)、(voucher_id)
export_batch、accounting_result	导出含批次号、范围、文件、哈希、行数、状态/审计；结果含凭证、外部凭证号、结果日期、登记/复核人、状态/版本	批次号唯一；外部凭证号按账套/期间唯一；每凭证最多一个有效结果	(status,created_at)、(voucher_id,status)
file_object	sha256 CHAR(64)、size_bytes BIGINT、mime_type、storage_key、scan_status、encryption_key_id NULL、上传人/时间	内容哈希唯一；storage_key 唯一；只允许 11.9 节状态	(scan_status,created_at)、(sha256)
file_link	file_id、owner_type/owner_public_id、file_type、version_no、required_flag、not_applicable_reason NULL、supersedes_link_id NULL、状态/审计列	(owner_type,owner_public_id,file_type,version_no)；多态 owner 由领域服务校验并测试	(owner_type,owner_public_id)、(file_id)
archive_package、archive_borrow	包含项目、版本号、规则版本、清单 JSON/哈希、状态/审计；借阅含包/文件、申请人、用途、批准人、到期/归还时间、状态/版本	(project_id,version_no)；借阅业务号唯一	(project_id,status)、(borrower_id,status,due_at)
audit_log	request_id CHAR(26)、event_sequence INT、actor_id、identity_code、scope_snapshot_json、object_type/object_public_id、action、before_json/after_json、reason、occurred_at	(request_id,event_sequence)；只追加，不提供 UPDATE/DELETE 权限	(object_type,object_public_id,occurred_at)、(actor_id,occurred_at)
export_log	request_id、actor_id、resource_type、filter_json/columns_json、row_count、file_id、sha256、occurred_at	request_id 唯一	(actor_id,occurred_at)、(resource_type,occurred_at)
sys_idempotency_record	actor_id/identity_code/http_method/normalized_path/idempotency_key、request_hash、execution_status、response_status/response_json NULL、expires_at	作用域复合唯一；同键不同请求哈希拒绝	(expires_at)、(execution_status,created_at)
sys_parameter_version	parameter_code、version_no、value_json、schema_version、effective_at、状态/审计列	(parameter_code,version_no)；每代码同一时刻最多一个生效版本	(parameter_code,status,effective_at)

来源键的规范化固定为：去除首尾空白、Unicode NFKC、英文按大写比较；source_no 和 source_version 在正式来源中都不得为空。唯一键必须包含 source_system，即 (form_type, source_system, normalized_source_no, normalized_source_version)。历史资料确实没有来源版本时，导入预览要求用户明确填写 LEGACY-001 等版本，不由数据库静默补空值。

finance_event.source_event_key 固定由“来源对象类型 + 来源公开 ID + 来源版本 + 事件类型 + 事件序号”组成并保存 SHA-256 规范化键；付款申请、付款结果、退汇和重付使用不同事件类型，重付记录必须显式关联原付款，不复用旧键。

下列内容保持版本化规则 JSON，不拆成一批随意列：动态字段布局与 requiredWhen、OA-04/OA-06 附件矩阵、审批路线条件、金额阈值、凭证分录规则、报表公式和保管策略。每次提交保存所用规则版本和关键快照；规则改变只能发布新版本，不能改写历史 JSON。其 JSON Schema、示例和迁移策略属于 TODO-S0-021 的冻结内容。

11.6.3 PAGE-14 已落库数据基线（2026-08-11）

PAGE-14 使用 V010、V011 和 V017 的前向迁移共同形成本模块数据结构；V017 是 PAGE-14 的关键增量，V050/V051 又补充了来源版本和审批投影关联；全库截至 2026-08-16 已迁移到 V067。下表是已经运行和测试的真实表名，不再使用 11.6 节概念表名 receipt/allocation/invoice 代替实现名。

实际表	作用和关键列	已落库的不变量
fin_receipt	收款主记录；公司、可选项目/客户、收款日、金额、已分配额、币种、付款方、银行流水号、确认人/时间、作废原因、状态和版本	金额大于 0；已分配额在 0～收款额；状态限 DRAFT/CONFIRMED/PARTIALLY_ALLOCATED/ALLOCATED/VOID；业务号唯一；同公司非空流水号唯一；正式外键 RESTRICT
fin_receipt_allocation	收款到正式应收的核销关系；receipt_id、receivable_id、核销序号、项目、合同、金额、备注和登记人	金额大于 0；(receipt_id, receivable_id, sequence_no) 唯一；一笔收款可分配多条应收，同一应收可由多笔收款结清
fin_receivable	人工开票结果生成的正式应收；来源发票、公司、项目、合同、客户、业务日、原额、未收额、币种、状态和版本	一张发票最多一条应收；原额大于 0；未收额在 0～原额；状态限 OPEN/PARTIALLY_SETTLED/SETTLED/VOID；项目/客户状态索引和全部业务外键已建立
fin_invoice	开票申请和人工结果；申请/发票编号、类型、金额、税率、日期、结果文件、原发票、提交/复核/结果人员与时间、意见、终止原因、状态和版本	金额大于 0、税率 0～1；类型限 SPECIAL/NORMAL/RECEIPT/RED_LETTER；同公司非空发票号唯一；红字票通过 original_invoice_id 关联原票；状态限已冻结发票域
acc_event	收款确认和人工开票结果生成的记账准备事件	来源业务 ID 幂等；已确认业务作废/红冲时，仅 PENDING 事件可同步作废，已进入后续记账处理则阻断直接终止

V017__receivable_ledger_and_invoice_controls.sql 新建 fin_receivable，为收款增加作废原因和流水唯一键，为核销增加正式应收关系/序号，为发票增加提交、复核、结果和终止元数据及公司发票号唯一键，并补充 receivable:receipt:void 权限及既有范围继承。本段原记录的“10 个 Testcontainers 集成测试类、全量 Maven 47/47、迁移到 V017”是 2026-08-11 PAGE-14 历史验收快照，仅证明当时基线；当前仓库测试与迁移数量已变化，不用该数字表达当前全仓状态。

11.7 接口设计

内部接口统一使用 /api/v1：

/api/v1/auth/*                    登录、身份和会话
/api/v1/workbenches/*             三类工作台汇总
/api/v1/projects/*                项目
/api/v1/source/forms/*            14 类表单
/api/v1/workflow/tasks/*          待办和审批
/api/v1/masterdata/*              主数据
/api/v1/contracts/*               合同
/api/v1/costs/*                   成本台账
/api/v1/payables/*                应付
/api/v1/receipts/*                收款
/api/v1/invoices/*                发票
/api/v1/payments/*                付款
/api/v1/accounting/*              记账准备
/api/v1/archive/*                 文件和归档
/api/v1/reports/*                 查询报表
/api/v1/audit/*                   审计
/api/v1/admin/*                   用户、权限、模板和参数治理

状态只能通过命令接口改变，例如 submit、approve、return、void、confirm，不提供任意修改状态的接口。

11.7.1 登录、会话和身份接口

方法和路径	登录要求	请求/响应要点	主要错误
GET /api/v1/auth/csrf	匿名可用	返回 CSRF token 摘要并设置同源 XSRF-TOKEN Cookie；不创建业务身份	429 请求过快
POST /api/v1/auth/login	匿名 + CSRF	请求 username/password；成功轮换 Session ID，返回本人摘要和 mustChangePassword，不返回 Token	AUTH_BAD_CREDENTIALS、AUTH_LOCKED、AUTH_DISABLED
GET /api/v1/auth/session	已登录	返回本人摘要、当前身份、可用身份、会话到期时间和权限版本，不返回敏感授权明细	401
GET /api/v1/auth/profile	已登录	返回本人姓名、部门、当前身份、授权范围摘要和最近登录记录；不返回他人信息	401
GET /api/v1/auth/roles	已登录	业务账号返回被授权的三类业务身份卡；纯管理员只返回 SYSTEM_ADMIN 系统管理卡；单入口也返回一项；业务与管理员同时授权时返回配置冲突	401、409 AUTH_ROLE_CONFLICT
POST /api/v1/auth/select-role	已登录 + CSRF	请求 roleCode；校验仍被授权且满足账号互斥后轮换 CSRF 和权限版本，返回对应工作台或 PAGE-21 路由	AUTH_ROLE_NOT_GRANTED、409 AUTH_ROLE_CONFLICT、409 权限已变化
PATCH /api/v1/auth/password	已登录 + CSRF	请求当前密码、新密码、确认值；成功失效除当前会话外的旧会话	AUTH_CURRENT_PASSWORD_INVALID、AUTH_PASSWORD_POLICY
GET /api/v1/auth/sessions	已登录	返回本人会话的设备摘要、创建/最近活动时间和当前标记	401
DELETE /api/v1/auth/sessions/{sessionId}	已登录 + CSRF	退出本人的指定会话；不能操作其他用户	404、403
DELETE /api/v1/auth/sessions	已登录 + CSRF	退出本人全部会话，当前请求完成后回登录页	401
POST /api/v1/auth/logout	已登录 + CSRF	注销当前会话、清除身份和 CSRF Cookie	重复注销按幂等成功处理

登录流程固定为：打开 PAGE-01 → 获取 CSRF → 登录 → PAGE-02 → 读取入口卡 → 用户选择身份 → 业务身份进入对应工作台，SYSTEM_ADMIN 进入 PAGE-21。前端不保存登录 Token；Session Cookie 由浏览器同源携带。角色切换不是前端改 Store，而是调用 select-role 让服务端改变身份上下文，再清理前端旧身份状态。

11.7.2 查询、命令和文件接口合同

• 列表查询使用 GET，参数统一为 page、size、可重复 sort=field,asc|desc 和页面冻结的筛选字段；未知筛选/排序字段返回 400，不静默忽略。
• 创建草稿使用 POST /resources；读取详情使用 GET /resources/{publicId}；更新草稿使用 PATCH 并携带 version。正式状态只通过明确命令子路径改变。
• 每个写接口的 OpenAPI 必须声明权限码、数据范围、允许状态、请求体、Idempotency-Key、请求体 version、成功状态、审计事件和全部稳定业务错误码；R1 不同时支持 If-Match 与请求体版本两种并发协议。
• 文件上传使用 multipart/form-data，固定包含 metadata JSON part 和一个或多个 file part；下载返回准确 Content-Type、RFC 5987 编码的 Content-Disposition、Content-Length、ETag/SHA-256 和 X-Request-Id，JSON 中不返回服务器路径。
• 导入固定为“创建批次并上传 → 查询校验结果 → 用户确认入库”三个接口步骤；确认前不写正式业务表，确认命令必须幂等。
• 导出固定为“提交导出请求 → 生成受控文件 → 下载”或在 50,000 行以内同步生成；无论哪种方式都重新按当前身份查询，保存筛选、列、行数、哈希和审计记录。

11.7.3 R1 最小接口目录

下表是 R1 不得缺少的接口集合。路径中的 {id} 一律是 26 位公开 ULID，不是数据库自增主键；命令路径只接收执行动作所需字段，不接收任意目标状态。为压缩表格，{approve,return} 表示两个独立的固定路径 /approve 和 /return，OpenAPI 中不得把它实现成可传任意值的路径变量。

业务域/页面	查询接口	创建、修改和命令接口
三类工作台 PAGE-04～06	GET /workbenches/project、/finance、/archive	工作台本身无写接口，所有卡片跳到对应业务资源
项目 PAGE-07～08	GET /projects、GET /projects/{id}、GET /projects/{id}/{forms,contracts,receipts,payments,progress,people,accounting,archives,timeline,risk-flags}	POST /projects、PATCH /projects/{id}、POST /projects/{id}/finance-complete、POST /projects/{id}/risk-flags、POST /projects/{id}/risk-flags/{riskId}/resolve、POST /projects/imports、POST /projects/exports
模板/表单 PAGE-09～10	GET /source/templates、GET /source/templates/{formType}/versions/{version}、GET /source/forms、GET /source/forms/{id}	POST /source/forms、PATCH /source/forms/{id}、POST /source/forms/{id}/validate、/submit、/withdraw、/void；POST /source/imports、GET /source/imports/{id}、POST /source/imports/{id}/confirm
待办 PAGE-11	GET /workflow/tasks、GET /workflow/tasks/{id}	POST /workflow/tasks/{id}/{approve,return,reject}、POST /workflow/instances/{id}/{withdraw,void}；退回请求必须含字段/附件定位
主数据 PAGE-12	对 companies、departments、projects、counterparties、bank-accounts、contracts、cost-categories、accounts、tax-rates 提供 GET /masterdata/{resource} 和 GET /masterdata/{resource}/{id}；当前八类可维护资源另提供 GET /masterdata/{resource}/{id}/versions 分页版本记录	对同一资源提供 POST、PATCH /{id}、POST /{id}/{submit,review,activate,disable}；账户和关键主数据复核必须另一人执行；版本接口先复用资源详情完成权限/范围校验，再返回去除 allowedActions 的前后快照
合同成本 PAGE-13	GET /contract-costs/contracts、GET /contract-costs/contracts/{id}、`GET /source/forms?formType=OA-04	OA-11&status=APPROVED`
收款 PAGE-14	GET /receivables/references、GET /receivables、GET /receipts、GET /receipts/{id}	POST /receipts、PATCH /receipts/{id}、POST /receipts/{id}/confirm、POST /receipts/{id}/allocations、POST /receipts/{id}/void、GET /receipts/export
发票 PAGE-14	GET /invoices、GET /invoices/{id}	POST /invoices、PATCH /invoices/{id}、POST /invoices/{id}/submit、POST /invoices/{id}/review、POST /invoices/{id}/record-result、POST /invoices/{id}/void、POST /invoices/{id}/red-letter、GET /invoices/export
付款 PAGE-15	GET /payments、GET /payments/{id}、GET /payments/{id}/checks	POST /payments、PATCH /payments/{id}、POST /payments/{id}/{submit,approve,return,confirm-offline-result,verify-result,record-failure,record-refund,create-repayment}、POST /payments/exports
记账 PAGE-16	GET /accounting/events、GET /accounting/vouchers、GET /accounting/vouchers/{id}、GET /accounting/vouchers/{id}/result-files/{fileId}/content	POST /accounting/events/{id}/generate-draft、PATCH /accounting/vouchers/{id}、POST /accounting/vouchers/{id}/{submit,approve,export,record-result,verify-result,reverse-result,reopen-result,void}
档案 PAGE-17～18	GET /archive/packages、GET /archive/packages/{id}、GET /archive/files、GET /archive/files/{id}、GET /archive/borrows	POST /archive/packages（前置 financeStatus=COMPLETED）、POST /archive/packages/{id}/{check,submit,return,revise,archive,freeze,unfreeze}、清单项不涉及申请/复核；POST /archive/files、GET /archive/files/{id}/content；POST /archive/borrows、POST /archive/borrows/{id}/{approve,reject,return}
报表 PAGE-19	GET /reports/{project-ledger,contract-execution,receipt-invoice,payment-progress,workflow-duration,archive-completeness} 及对应 /{rowId}/drilldown	POST /reports/{reportCode}/exports/prepare 预检冻结；POST /reports/{reportCode}/exports/confirm 重新鉴权、校验快照并生成文件
审计 PAGE-20	GET /audit/logs、GET /audit/logs/{id}	POST /audit/exports；没有修改或删除接口
系统治理 PAGE-21	对 users、roles、scopes、templates、parameters 提供 GET /admin/{resource} 和详情；GET /admin/system-update 返回版本、状态和 allowedActions	POST /admin/{resource}、PATCH /admin/{resource}/{id}、POST /admin/{resource}/{id}/{enable,disable,publish}；POST /admin/system-update/check、POST /admin/system-update/install，具体动作按资源白名单开放

详情响应统一包含 publicId、businessNo、status、version、创建/修改摘要和服务端计算的 allowedActions；列表项只返回页面列需要的数据。所有金额在 JSON 中使用十进制字符串，日期/时间遵守 11.12 节，枚举同时返回稳定代码和前端可映射的显示含义。OpenAPI 评审时要把本表每一项拆成明确 operationId、DTO、权限码、错误码和示例；未列出的新接口先走需求变更，不能为绕过领域规则新增“万能保存”接口。

11.7.3.1 PAGE-14 实际接口合同（2026-08-11）

接口组	输入要点	输出和控制
引用与列表查询	companyId/projectId/counterpartyId/keyword/status/dateFrom/dateTo/sort/page/size；页码从 1 开始，size 仅 20/50/100	ReferenceOptionsView、ReceivableView[]、ReceiptView[]、InvoiceView[]；服务端分页、排序白名单、数据范围过滤和十进制字符串金额
收款草稿	新建：公司、可选项目/客户、日期、金额、币种、付款方、可选流水号；编辑另带 version	返回 ReceiptView 和 allowedActions；重复公司+流水号返回 409 DUPLICATE_RESOURCE，非草稿编辑或范围/金额不满足由后端拒绝
收款确认/核销/作废	确认只带 version；核销带 receivableId/amount/note/version；作废带 version/reason	确认生成财务事件；核销返回 ReceiptDetailView 并事务内更新收款与应收；作废同步终止尚未进入后续记账的事件；SOD、超额、状态和版本冲突分别返回稳定错误码
开票草稿与提交	新建/编辑带公司、项目、可选合同、开票对象、类型、金额、税率和申请日期；编辑/提交带 version	返回 InvoiceView；项目、合同和对象关系、权限范围、金额阈值和状态均由服务端复算
开票审核	version/decision/opinion，其中 decision 只允许 APPROVE/RETURN/REJECT	APPROVE 直接进入 RESULT_PENDING，提交人与复核人相同返回 SOD_VIOLATION，合同额度不足返回 CONTRACT_LIMIT_EXCEEDED
人工开票结果	version/invoiceNo/issuedDate/resultFileId?	原申请进入 ISSUED，同事务生成唯一 fin_receivable 和 acc_event；结果文件存在时必须通过本地文件检查
发票作废/红冲	作废带 version/reason；红冲带 version/invoiceNo/issuedDate/resultFileId?/reason	已核销应收或已进入后续记账的业务被阻断；红冲把原票标为 RED_LETTERED，新增关联原票的 RED_LETTER 记录，并保证合同/报表按净额统计
导出	使用与列表相同的筛选和排序，不接收前端缓存行	返回 UTF-8 BOM CSV，按当前身份重新查询，收款和发票导出分别写审计事件

当前 Controller 使用分离命令路径，不存在可提交任意目标状态的万能接口。前端调用层位于 frontend/src/api/receivable.ts，页面位于 frontend/src/pages/finance/ReceiptsInvoicesPage.vue；写操作成功后重新读取服务端对象和 allowedActions。

代表性命令接口固定为：

POST /api/v1/source/forms/{id}/submit
POST /api/v1/workflow/tasks/{taskId}/approve
POST /api/v1/workflow/tasks/{taskId}/return
POST /api/v1/payments/{id}/confirm-offline-result
POST /api/v1/payments/{id}/verify-result
POST /api/v1/accounting/events/{id}/generate-draft
POST /api/v1/accounting/vouchers/{id}/export
POST /api/v1/archive/packages/{id}/submit
POST /api/v1/archive/packages/{id}/archive

创建、更新和业务命令携带 Idempotency-Key，更新和命令请求体携带当前 version，每个请求携带/返回 X-Request-Id。错误响应采用 Spring ProblemDetail，包含稳定业务错误码、可读提示、字段/附件定位和请求编号；OpenAPI 文件是前后端联调的唯一机器合同。

11.7.4 V2.9 通用 DTO、分页和错误合同

本文件仍是唯一人工阅读的 PRD/SPEC；仓库中的 openapi.yaml 是由本节和 11.7.3 生成、供 Java/TypeScript/CI 使用的机器制品，不是第二份可自行修改的需求文档。OpenAPI 与本文件不一致时停止联调，先通过变更记录修改本文件，再重新生成机器制品。

协议固定值

项目	R1 固定合同
API 前缀	/api/v1；只提供 JSON、multipart 上传和受控二进制下载
ID	URL 和 JSON 中公开 ID 均为 26 位大写 ULID；数据库 BIGINT 不出接口
分页	page 从 1 开始，默认 1；size 默认 20，只允许 20/50/100；响应回显 page/size/totalElements/totalPages
排序	可重复 `sort=field,asc
文本查询	搜索词去首尾空白，最大 100 字；精确编号和模糊名称使用不同参数，未知参数返回 400 QUERY_PARAMETER_UNKNOWN
金额	JSON 字符串，正金额格式 ^\\d{1,18}(\\.\\d{1,2})?$；允许调整为负时由具体 DTO 使用带负号格式；禁止 JSON number
比例/税率	JSON 字符串，0～1，最多 6 位小数；页面可显示百分比但提交前转换为小数字符串
日期时间	日期 yyyy-MM-dd；时间为 UTC ISO-8601，例如 2026-08-07T08:30:00.123Z
枚举	请求只传稳定英文代码；响应返回代码，中文由前端集中映射；未知代码返回 422 ENUM_VALUE_INVALID
版本	可变资源详情返回非负整数 version；每个 PATCH/业务命令请求体必须回传该值，冲突返回 409 VERSION_CONFLICT
幂等	创建、PATCH 和命令使用 Idempotency-Key Header，16～64 位可打印 ASCII；同键不同请求体返回 409 IDEMPOTENCY_KEY_REUSED
请求编号	客户端可发送 26 位 X-Request-Id；缺少或非法时服务端生成，所有响应、运行日志和审计都返回同一编号
会话/CSRF	Cookie Session 同源携带；除安全 GET/HEAD/OPTIONS 外必须发送 X-XSRF-TOKEN，不接受 Bearer 示例 Token

统一成功体

{
  "data": {},
  "meta": {
    "page": 1,
    "size": 20,
    "totalElements": 0,
    "totalPages": 0
  },
  "requestId": "01J4Q2M4T0Y7B5P8A3N6C9D2EF"
}

单对象响应省略 meta；204 响应没有 body，但仍返回 X-Request-Id。详情 DTO 统一包含：publicId、适用时的 businessNo/company/project 摘要、status、version、createdAt/createdBy、updatedAt/updatedBy 和服务端计算的 allowedActions。allowedActions 只用于前端展示，不替代后端鉴权。

认证 DTO

DTO	字段	规则
LoginRequest	username、password	用户名 1～64 字符并规范化；密码 12～64 字符且不 trim、不写日志
LoginResponse	user、mustChangePassword、sessionExpiresAt	不返回 Token、密码策略细节或权限全集；成功后前端只跳 PAGE-02
RoleSummary	code、name、description、workbenchRoute	业务身份代码固定 PROJECT_MANAGER/FINANCE_MANAGER/ARCHIVE_MANAGER；纯超级管理员使用 SYSTEM_ADMIN，只返回超级管理员卡且默认 workbenchRoute=/governance/settings，不得和业务身份同时返回；该默认入口不限制其全部页面权限
SelectRoleRequest	roleCode	只能提交 GET /auth/roles 当前返回的代码；服务端重新校验授权
SessionResponse	user、availableRoles、currentRole、permissionVersion、sessionExpiresAt	不返回组件路径、数据库 ID、完整权限范围或敏感字段
ChangePasswordRequest	currentPassword、newPassword、confirmPassword	新密码由后端执行 11.10.1；三项均不进入日志和审计前后值

通用业务命令 DTO

命令类型	必填字段	特殊规则
新建草稿	业务字段 + clientRequestNo	Header 带幂等键；服务端生成 publicId/businessNo/version=0
更新草稿	version + 允许修改的业务字段	不接受 status/createdBy/approvedBy；空字段的清除语义在 OpenAPI 逐字段声明
提交/撤回/作废	version、reason；提交可省略 reason	撤回/作废 reason 2～500 字；服务端完整复算校验
通过/驳回	version、opinion	意见 2～1000 字；当前任务处理人和 SOD 由后端判断
退回补件	version、opinion、returnPoints[]	每个退回点含 type=FIELD/ATTACHMENT、fieldCode/attachmentType、可选 rowNo；至少一项
登记线下付款成功结果	version、resultAt、amount、receiptFileIds[]、remark	只用于 /confirm-offline-result 并进入待复核；不接收银行指令、网银流水抓取或 U 盾数据
登记失败/退汇	version、occurredAt、amount、reason、evidenceFileIds[]	分别使用 /record-failure、/record-refund，不能通过任意 resultType 直接指定目标状态
复核付款结果	version、opinion	复核人与登记人不同；服务端按结果类型进入 PAID/FAILED/REFUNDED
生成凭证草稿	version、ruleVersion	来源财务事件键 + 规则版本幂等；前端不得提交借贷目标状态
凭证结果登记/复核	version、externalVoucherNo、resultAt、evidenceFileIds[]、opinion	登记与复核分离；外部凭证号按账套/期间唯一
归档提交/确认	version、opinion	确认前重算缺件和文件状态；清单哈希由后端生成

导入、文件和导出 DTO

• ImportCreateRequest.metadata 至少包含 formType/sourceSystem/templateVersion/companyId/projectId/clientRequestNo；文件使用独立 file part。响应只创建 batchId/status=VALIDATING，不创建正式单据。
• ImportValidationResponse 包含 totalRows/validRows/errorRows/warnings[]/errors[]。每个错误固定返回 sheet/row/column/fieldCode/code/message；确认请求为 batchId + version + acceptedWarningCodes[]。
• FileUploadMetadata 包含 ownerType/ownerId/fileType/version/replacementReason/notApplicableReason 的适用字段；上传响应返回 fileId/displayName/size/mimeType/sha256/status，不返回 storageKey 或服务器路径。
• 报表导出使用两阶段合同。prepare 请求包含筛选条件、列代码、排序、expectedFilterHash 和 expectedDefinitionVersion；服务端冻结导出人、当前身份、权限范围指纹、报表/口径、筛选、列、排序、预计行数和过期时间，返回 exportId/status=PREPARED/estimatedRows/columns/sort/expiresAt/maskingNotice。confirm 只接收 exportId + maskingConfirmed=true，生成文件前重新校验人员、身份、权限范围、口径、筛选、列、排序和预计行数；成功返回 status=COMPLETED/rowCount/fileName/content/sha256并记录导出审计。同一 exportId 不得再次确认，快照失效或已消费返回 409 VERSION_CONFLICT。

统一失败体

{
  "type": "urn:kaidi:problem:version-conflict",
  "title": "数据已被其他人更新",
  "status": 409,
  "detail": "请重新加载后再操作",
  "instance": "/api/v1/payments/01J4Q2M4T0Y7B5P8A3N6C9D2EF/approve",
  "code": "VERSION_CONFLICT",
  "requestId": "01J4Q2Q7H5S4M8P2K9V6R3C1AB",
  "objectId": "01J4Q2M4T0Y7B5P8A3N6C9D2EF",
  "fieldErrors": []
}

HTTP	稳定错误码基线	页面行为
400	QUERY_PARAMETER_UNKNOWN、SORT_FIELD_NOT_ALLOWED、REQUEST_MALFORMED	保留安全输入，提示修正请求；不显示 Java/SQL 信息
401	AUTH_REQUIRED、AUTH_SESSION_EXPIRED	清理会话业务状态并回登录页
403	PERMISSION_DENIED、DATA_SCOPE_DENIED、AMOUNT_LIMIT_EXCEEDED、SENSITIVE_ACCESS_DENIED	进入 403 或禁用动作；显示请求编号，不泄露无权对象内容
404	RESOURCE_NOT_FOUND、FILE_NOT_FOUND	显示业务对象不存在或已不可用，提供来源列表返回路径
409	VERSION_CONFLICT、DUPLICATE_SOURCE、IDEMPOTENCY_KEY_REUSED、COMMAND_IN_PROGRESS、CONCURRENT_MODIFICATION、AUTH_ROLE_CONFLICT	停止覆盖，允许重新加载或打开已有对象；身份配置冲突时阻断进入并联系管理员，不自动重放写请求
422	FIELD_VALIDATION_FAILED、ENUM_VALUE_INVALID、INVALID_STATE_TRANSITION、ATTACHMENT_REQUIRED、FUNDS_INSUFFICIENT、CONTRACT_LIMIT_EXCEEDED、PAYABLE_LIMIT_EXCEEDED、ACCOUNT_NOT_ACTIVE、PROJECT_RISK_BLOCKED、SOD_VIOLATION、VOUCHER_UNBALANCED、FILE_REJECTED	字段错误就近显示；跨字段/业务阻断在页面 Alert 展示原因和下一步
429	AUTH_RATE_LIMITED、REQUEST_RATE_LIMITED	显示等待时间，登录按钮在倒计时后恢复，不循环自动请求
500/503	INTERNAL_ERROR、AUDIT_WRITE_FAILED、FILE_SCANNER_UNAVAILABLE、SERVICE_UNAVAILABLE	显示统一错误和请求编号；正式动作未知时先查询对象状态再允许重试

每个 operationId 在 S0 OpenAPI 快照中必须补齐：页面 ID、权限码、数据范围、请求/响应 schema、字段长度和示例、允许状态、版本/幂等、审计事件、全部错误码以及成功后的页面去向。缺任一项，该接口状态保持 DRAFT，对应开发任务不得进入 IN_PROGRESS。

11.8 事务、并发和幂等

• “提交表单、审核、确认付款、生成凭证”等每个动作在一个数据库事务内完成。
• 更新时检查版本号，两个用户同时编辑时，后提交的人得到冲突提示而不是覆盖别人。
• 检查项目余额和合同额度时锁定对应控制记录，防止两笔付款同时超额。
• 导入确认和凭证生成使用幂等键；重复点击只返回原结果，不重复建数据。

R1 固定使用 MySQL READ COMMITTED。涉及资金的锁顺序固定为：项目资金控制 → 合同控制 → 应付/收款对象 → 当前业务单据；所有命令遵循同一顺序，避免不同模块反向加锁。锁等待超时或检测到版本变化返回 409 CONCURRENT_MODIFICATION，前端提示重新加载；不得自动覆盖。

Idempotency-Key 的服务端作用域为“当前用户 + 当前身份 + HTTP 方法 + 规范化路径 + Key”，并保存请求体 SHA-256、执行状态、HTTP 结果和对象编号 24 小时。相同 Key、相同请求体重复提交返回第一次成功结果；相同 Key、不同请求体返回 409 IDEMPOTENCY_KEY_REUSED；首次仍在执行时返回 409 COMMAND_IN_PROGRESS 和 Retry-After。确定性 4xx 和未知 5xx 不缓存为成功结果。只对已经声明幂等且尚未产生外部副作用的数据库死锁命令内部重试，最多 2 次；前端写请求一律不自动重试。

11.9 文件存储

文件本体保存在受保护目录，数据库只保存元数据和 SHA-256。上传流程为：临时目录 → 类型/大小/病毒检查 → 计算哈希 → 建立业务关系 → 原子移动到正式目录。病毒检查使用甲方环境内本地部署的扫描服务，不调用公网云扫描接口。

允许格式首期建议：PDF、OFD、DOCX、XLSX、CSV、JPG、PNG。压缩包、可执行文件和带宏文件默认拒绝。

R1 文件限制固定为：单文件不超过 100MB，单次最多 20 个文件且合计不超过 500MB；Excel/CSV 导入文件不超过 50MB、10,000 行。文件名按 UTF-8 保存显示名，同时生成独立存储名；拒绝路径分隔符、控制字符、双扩展伪装和公式注入风险名称。

文件状态固定为 TEMPORARY → SCANNING → AVAILABLE，失败进入 REJECTED 或 QUARANTINED，正式附件被替换后旧关系进入 SUPERSEDED 但文件仍可审计查看。病毒扫描超时或服务不可用时保持 QUARANTINED，不得预览、下载或关联正式单据；只有 AVAILABLE 才显示上传成功。临时文件清理由管理员显式执行并记录审计，本期不使用定时任务。

11.10 安全要求

• 本地账号使用 Argon2id 密码哈希，Session Cookie 设置安全属性。
• 使用 Spring Session JDBC 把会话保存在 MySQL，不引入 Redis；当前身份保存在服务端会话。Cookie 设置 HttpOnly、Secure、SameSite=Lax，切换身份、停用账号和退出全部会话时服务端立即失效旧会话。
• 页面隐藏按钮不能代替后端权限判断。
• 银行账号、身份证和工资字段加密；列表和导出执行相同脱敏。
• 防止 SQL 注入、文件路径穿越、Excel 公式注入和恶意文件上传。
• 应用代码和配置中不得出现第三方账号、Token、证书、网银/税务凭据。
• 不使用 @Scheduled、Quartz、XXL-JOB、消息消费者或 RPA SDK。

11.10.1 R1 安全参数基线

控制项	固定基线
密码哈希	Argon2id：内存 64MiB、迭代 3、并行度 1、随机盐 16 字节、输出 32 字节；参数随哈希保存以便升级
密码规则	12～64 个字符，至少满足大写、小写、数字、符号四类中的三类；禁止包含账号、常见弱口令和最近 5 次密码；管理员重置后首次登录强制修改
登录防护	同账号 15 分钟内连续失败 5 次锁定 15 分钟；同 IP 每分钟最多 10 次登录尝试；成功登录清空失败计数，锁定/解锁留审计
Session	登录后轮换 Session ID；空闲 30 分钟失效，绝对时长 8 小时；每账号最多 3 个会话，超出时注销最旧会话并通知；停用、改权和退出全部会话立即失效
Cookie/CSRF	production 的 Session Cookie 使用 HttpOnly; Secure; SameSite=Lax; Path=/；CSRF 使用同源 XSRF-TOKEN Cookie + X-XSRF-TOKEN Header，登录和切换身份后轮换
浏览器边界	production 只同源访问，CORS 默认关闭；禁止把 Session、CSRF、密码、权限明细或敏感业务对象写入日志、URL、Pinia 持久化和 Web Storage
字段加密	身份证、银行账号和工资使用 AES-256-GCM，逐值随机 96 位 nonce，保存密钥 ID；密钥由环境密钥文件注入，不与数据库备份存放在一起，支持双密钥轮换
传输/响应头	production 仅 TLS 1.2/1.3；启用 HSTS、X-Content-Type-Options: nosniff、合适的 CSP、Referrer-Policy 和防 iframe 策略
敏感访问	默认脱敏；查看完整值必须有独立权限、填写原因、短时返回并记审计；导出和下载执行相同规则
管理端点	Actuator 仅在管理网络开放 health/readiness/metrics，不开放环境、Bean、堆转储和写端点

密码到期不做无依据的周期强制更换；发现泄露、管理员重置或策略升级时强制修改。production 启动时若使用默认密码、缺少字段加密密钥、Cookie 未启用 Secure、CORS 宽松或调试端点开放，应用必须直接拒绝启动。

11.11 性能基线

最终规模由甲方确认。在规模未确认前，开发按以下基线验证：100 个并发会话、100 万业务记录；常用列表和详情 P95 小于 2 秒；10,000 行模板校验在 60 秒内完成；一次导出不超过 50,000 行。

临时性能环境固定为：应用 4 vCPU/8GB 内存、MySQL 4 vCPU/16GB 内存及 SSD、应用与数据库同一内网；数据集至少包含 10 家公司、1,000 个项目、100 万核心业务/审计记录和 100GB 文件元数据/样本文件。正式 D-10 若低于该配置，必须重新评估指标，不能沿用未验证数字。

压测先预热 10 分钟，再持续测量 30 分钟；100 个并发会话的请求比例为查询 80%、草稿写入 15%、已隔离的业务命令 5%。常用接口除 P95 小于 2 秒外，P99 小于 5 秒、非预期错误率小于 0.1%，且不得出现重复事件、余额错误、越权或审计缺失。报告记录代码版本、Flyway 版本、硬件、数据量、脚本、吞吐、P50/P95/P99、错误和慢 SQL；只报平均值不算通过。

前端页面路由全部使用动态导入，ECharts 和 PAGE-19 报表能力只在进入相关页面时加载。production 构建的首屏必需 JS+CSS gzip 合计不超过 700KB，普通单个 JS chunk 压缩前不超过 500KB；图表 vendor 必须独立分块并按需加载。以 20Mbps、50ms 延迟和已预热后端为基线，登录页及工作台首次可操作时间不超过 3 秒，路由切换不得因为一次性加载全部页面而冻结界面。包体报告进入 CI，超过预算视为构建失败，不通过简单调高 Vite warning 阈值掩盖。

11.12 接口和错误规则

• JSON 字段统一使用 camelCase，日期使用 yyyy-MM-dd，时间统一保存 UTC、页面按北京时间显示。
• 列表统一使用 page、size、sort，单页最多 100 条。
• 写操作带请求编号、幂等键和版本号。
• 401 表示未登录，403 表示无权限，404 表示对象不存在，409 表示版本/重复冲突，422 表示业务规则不满足。
• 错误信息必须给出稳定错误码，例如余额不足、账户未生效、附件缺失、岗位冲突；不能只显示“系统错误”。

11.13 CI 和代码质量

每次代码合并必须自动执行：npm ci、Starter 前端类型/格式/样式检查、Vitest、生产构建、Java 编译、MySQL 集成测试、Playwright 核心流程测试、模块边界检查、覆盖率检查、数据库迁移验证、OpenAPI 差异、依赖漏洞扫描、凭据扫描、构建制品生成，以及本文件 PAGE/OA/TODO/UAT 编号的唯一性、连续性和交叉引用检查。

质量门槛：后端与前端分别统计行覆盖率和分支覆盖率，二者都不低于 80%；金额、权限、状态机、岗位互斥、幂等和凭证规则的行/分支覆盖率都不低于 90%；严重/高危漏洞和明文密钥为零。只允许排除自动生成的 OpenAPI 客户端、纯 DTO、框架配置和数据库迁移文件，排除清单集中配置并经评审，不能逐文件临时加忽略。失败测试不得通过无限重跑、注释断言或降低门槛进入主分支。

11.14 部署、备份和监控

环境分为 local、test、staging、production。生产推荐：HTTPS 反向代理 + 单个 Java 应用 + 独立 MySQL + 独立文件卷；首期不拆微服务、不引入 Redis、消息队列或搜索集群。

staging/production 使用 Linux 容器或等价受控服务：反向代理仅对外开放 443，Java 应用和 MySQL 只在内部网络开放；应用使用非 root 用户，数据库账号只拥有本库运行所需权限，文件卷目录不由 Web 服务器直接暴露。镜像、JDK、反向代理和 MySQL 均以不可变版本或 digest 发布；密码、Session 密钥和字段加密密钥通过挂载密钥文件注入，不写进 Compose、镜像、环境样例或启动日志。

在甲方确认前使用临时目标：数据库每日全量备份并开启 binlog，文件卷每日增量备份；RPO ≤ 24 小时、RTO ≤ 4 小时；每季度完成一次数据库和附件联合恢复演练。

监控至少包括：请求延迟和错误率、JVM、数据库连接池、慢 SQL、导入失败、待办积压、磁盘空间、文件哈希异常、备份结果和审计写入失败。告警不触发自动业务处理。

运行日志在线保留 180 天；审计、导出和敏感访问日志首期按 10 年保留且不自动删除，最终保管期限由 D-09 确认。归档或到期处理必须由授权管理员显式执行、先导出校验并记录审批和哈希；处于项目档案、争议或审计冻结的记录不得处理。

第一版 Preview 的固定交付路径为私有 Gitea ERP-Team/kaidi 的 Git tag → Gitea Actions 全量门禁 → RSA 签名 Release → Linux 安装器。CI 先创建 draft，上传并核对恰好 9 个资产后再发布，生产服务器只读 Release API/资产，不执行 git pull 或现场编译。64 位 Linux 可由安装器创建 MySQL 8.4 容器；i386/i486/i586/i686 必须先准备外部 MySQL 8.4.x、数据库和具备本库 DDL/DML 权限的账号。两类主机均只运行一组经安装器 SHA-256、固定公钥指纹和只读 Gitea Token 保护的 curl 命令，具体可复制命令、占位符、建库、健康检查、停用和排障命令以仓库根 README.md 为准。

在线更新是部署运维能力，不是 OA、银行、税务或财务业务第三方集成。它只允许访问 root 配置中固定的 HTTPS Gitea Release API 和同源资产，页面不能改变地址；生产可按网络策略禁用。下载缓存、请求领取、运维备份和事务阶段保存在 /var/lib/kaidi-update，主机重启后先恢复未提交事务；安装前必须确认 mysqldump 成功并生成 root-only 压缩备份。签名包内的应用、updater、systemd 单元和 Nginx 配置以临时文件加原子移动切换；配置、新版本直连、Nginx 健康、更新 path unit 和静态首页任一失败时恢复旧应用和旧运维文件，并再次验证旧版本健康。数据库迁移继续遵守至少一个版本向后兼容，数据库恢复须按备份恢复演练单独执行。

11.15 全栈工程硬规范

仓库和构建结构

R1 使用一个仓库、一个 Java 部署单元、一个前端构建产物、一个 MySQL 数据库和一个受保护文件卷。目标目录固定为：

/
├── frontend/                  # 已导入的 TDesign Vue Next Starter 及业务前端
├── backend/
│   ├── mvnw
│   ├── mvnw.cmd
│   ├── pom.xml
│   └── src/
│       ├── main/java/
│       ├── main/resources/
│       │   ├── db/migration/ # Flyway 脚本
│       │   └── application.yml
│       └── test/
├── deploy/                    # 本地/staging/production 配置样例、容器和部署脚本
├── docs/
│   └── 财务系统开发交付总方案.md  # 唯一总方案
├── samples/                   # 脱敏导入、导出和验收样本
└── README.md                  # 本地构建、启动、Preview 安装、运维和文档入口

Java 使用 Maven Wrapper，前端使用 npm 和已提交的 package-lock.json。开发、CI 和交付不得依赖某台电脑全局安装的 Maven 包、未锁定 npm 版本或手工复制的私有 Jar。根目录提供一条全量校验命令，顺序完成前端检查/测试/构建、后端测试/打包、数据库迁移验证和端到端测试。

Java 分层和模块边界

基础包名固定为 com.kaidi.finance。第 11.5 节每个业务模块在同一 Spring Boot 应用内按以下四层组织：

com.kaidi.finance.<module>/
├── api/              # Controller、请求/响应 DTO、接口鉴权声明
├── application/      # 用例、事务边界、跨模块编排
├── domain/           # 实体、值对象、状态机、金额和业务规则
└── infrastructure/   # MyBatis Mapper、数据库/文件实现、外部技术适配

硬性边界如下：

• Controller 只做协议转换、输入校验和调用用例，不写金额公式、状态迁移或 SQL。
• Application 层定义一个用户动作的事务边界；Domain 层决定业务是否允许；Infrastructure 层不绕过 Domain 规则修改正式状态。
• MyBatis Mapper 和表模型属于各自模块，其他模块不能直接引用；跨模块写操作只通过公开 Application Service。reporting 可读取批准的只读投影/视图，但不能反向修改业务表。
• API DTO、领域对象和数据库对象分开，不把数据库行直接返回浏览器，也不接受浏览器提交任意 status、createdBy、approvedBy 等受控字段。
• shared 只允许放金额、ID、时间、分页、错误、安全上下文等真正跨模块的稳定能力，不建立无边界的 common 工具仓库。
• 当前用户、当前角色和数据范围从 Spring Security 上下文取得；接口传入的用户 ID、公司 ID 或项目 ID 仍要重新校验，不能相信隐藏字段。
• ArchUnit 固化层级和模块依赖，任何新增例外必须在本文件登记原因和清理时间，不允许用循环依赖或关闭检查临时通过。

数据库和 Flyway

• 数据库、表和列使用 utf8mb4 与 snake_case；业务表内部主键使用 BIGINT，URL/API 使用 CHAR(26) ULID public_id，给人阅读的项目号、合同号等另设 business_no。不把自增主键暴露给浏览器，也不把“编号难猜”当成权限控制。
• 金额、比例、日期时间和版本遵守 11.6 节；时间统一以 UTC 保存，审计时间精确到毫秒，页面按北京时间转换。
• 正式状态用可读 VARCHAR 状态码并加检查约束；所有唯一键、外键、非空、金额范围和版本约束在数据库中再次建立。
• 每个业务表至少包含 id、public_id、业务编号、company_id/project_id（适用时）、status、version、创建/修改人和时间。是否作废由业务状态表达，不使用一个全局 deleted 字段掩盖所有业务语义。
• Flyway 文件按 V001__iam_baseline.sql、V002__masterdata_baseline.sql 顺序递增；已进入共享环境的版本禁止修改，只能新增迁移。R__ 脚本仅用于可重复生成的只读视图，不用于不可追踪的数据修复。
• 一次迁移只解决一个明确变化，包含索引、约束和必要的数据转换；生产禁止 flyway clean、Hibernate/JPA 自动建表或人工直接改表。
• 破坏性改表使用“先扩展、迁移数据、切换代码、后收缩”的兼容步骤。部署前先备份，迁移失败立即停止发布，不让应用带着半完成结构启动。
• 初始化管理员、字典和模板使用可审查的版本化数据脚本；生产初始密码通过部署密钥注入并强制首次修改，不能写进迁移文件。

OpenAPI 和前后端合同

每个页面开始联调前，先冻结相关 OpenAPI：路径、方法、权限码、请求/响应字段、金额字符串、枚举、分页、错误码、幂等和示例。Spring Boot 生成的 OpenAPI 文件提交到仓库，CI 检测未评审的破坏性变更；前端类型和基础客户端由该文件生成，禁止前后端各自手写一份“差不多”的类型。

成功响应统一为：

{
  "data": {},
  "meta": {},
  "requestId": "01..."
}

单对象可省略空的 meta；分页 meta 固定包含 page、size、totalElements、totalPages。失败响应使用 Spring ProblemDetail，并扩展稳定的 code、requestId、fieldErrors 和可选 objectId。HTTP 状态与 11.12 节一致，不能全部返回 200 再把失败藏在业务字段里。

命令接口必须说明：允许的当前状态、需要的权限、数据范围、岗位互斥、幂等键、版本号、成功后的新状态、可能错误和审计动作。上传/下载接口单独声明文件大小、内容类型、哈希和 Content-Disposition，禁止在 JSON 中暴露服务器绝对路径。

配置、日志和审计

• application.yml 只放非敏感默认值；数据库密码、Session 密钥、字段加密密钥和初始管理员密码从环境变量或挂载密钥文件读取。仓库提供 .example，不提交真实凭据。
• local/test/staging/production 的差异由显式 profile 和部署配置表达；生产启动时发现默认密码、调试模式、Mock、宽松 CORS 或缺失密钥必须直接失败。
• staging/production 运行日志使用结构化 JSON，至少包含时间、级别、服务版本、环境、requestId、用户内部 ID、当前角色、模块、动作、对象编号、结果和耗时。
• 运行日志不记录密码、Session、CSRF、Token、身份证全文、完整银行账号、工资、文件内容、SQL 参数全文或上传文件原文。需要排查时使用业务编号和请求编号关联。
• 审计日志是业务证据，不等同于普通运行日志；审批、状态、金额、权限、敏感查看和导出必须与业务事务一致写入。审计写入失败时对应正式业务动作回滚。
• 日志级别和保留期由环境配置，普通用户不能通过页面更改；生产不开放 Actuator 写端点，健康和指标端点只在管理网络访问。

测试和样本

层级	必须覆盖	工具/规则
Java 单元测试	金额公式、状态机、权限决策、岗位互斥、凭证平衡、附件矩阵	JUnit 5；不依赖 Spring 上下文，边界值和失败路径都要覆盖
Java 集成测试	Controller 鉴权、MyBatis SQL、事务回滚、唯一约束、并发锁、Flyway	MockMvc + Testcontainers MySQL 8.4；不使用 H2 假装 MySQL
前端组件测试	金额/日期、字段错误、权限按钮、状态标签、上传和 409 处理	Vitest + Vue Test Utils；不以快照代替关键断言
合同测试	OpenAPI 生成、前端类型、错误码和破坏性差异	CI 固定 OpenAPI 制品并校验生成代码无未提交差异
浏览器测试	三类身份、PAGE-01～21、14 类表单、主业务闭环和异常状态	Playwright 使用 staging 真实 API 和可重置样本数据库
恢复/性能测试	备份恢复、100 并发、百万记录、10,000 行导入和 50,000 行导出	输出可复查报告、数据校验值和测试版本

测试样本全部脱敏且可重复初始化，每个 OA 类型固定成功、必填失败、重复和越权样本。测试不得依赖执行顺序、开发者个人账号或公网服务；测试完成后能从脚本还原干净环境。

样本编号固定为 FIX-{对象}-{场景}-{序号}，例如 FIX-OA01-SUCCESS-001、FIX-OA01-REQUIRED-001、FIX-OA01-DUPLICATE-001、FIX-OA01-FORBIDDEN-001。每个样本在本文件的冻结记录中写明前置主数据、输入文件/请求、执行身份、预期 HTTP 状态、业务状态、金额、下游对象、审计事件和证据位置。测试和 staging 通过显式重置脚本初始化独立数据库；重置能力不得打包进 production。Playwright 只调用同源真实 API，不拦截核心业务请求、不用 Mock 响应代替后端。

依赖、质量和发布

新增依赖必须说明用途、许可证、维护状态、替代方案和影响范围，经评审后锁定版本。Java 版本由 Spring Boot BOM/Maven 管理，npm 版本由 lockfile 管理；禁止动态版本、未备案私服包和复制来源不明代码。

2026-08-07 对刚导入的 Starter 基线执行 npm 官方安全审计：运行依赖为 2 个高危、2 个中危，全依赖树为 9 个高危、3 个中危、1 个低危；主要包含 tvision-color 链路及 Starter Mock/构建依赖。该结果说明底座可以用于设计和本地启动，但尚未达到 R1 发布条件。S1 必须删除生产不需要的 mockjs/vite-plugin-mock，升级或替换有漏洞的直接/传递依赖并完成回归；staging 和 production 的严重/高危漏洞均为零，未修复中低危必须有影响分析、负责人和到期日。

版本统一为 1.0.0-rc.N 候选版和 1.0.0 首次正式版。每个制品记录 Git 提交、构建时间、前后端版本、Flyway 最高版本、依赖清单和 SHA-256。发布顺序固定为：备份 → 迁移验证 → Flyway → Java 应用 → 前端静态资源 → 冒烟测试 → UAT 证据归档。前端和 /api/v1 同源部署；生产不依赖开发服务器。

发布失败时先停止流量并回滚兼容的应用/前端制品；数据库依靠备份和前向修复脚本处理，不临时手改生产数据。每次发布必须有变更清单、数据库影响、回滚步骤、验证人和结果；未通过第 12.9 节 Definition of Done 的构建不能标记为 R1。

12. 开发步骤和 ToDoList

12.1 开发顺序总览

S0 需求冻结和原型
→ S1 工程底座和权限
→ S2 项目、主数据、14类表单和审批
→ S3 收款、发票、合同成本和付款
→ S4 记账准备、档案和查询
→ S5 测试、迁移、试点和交付

不建议同时把所有模块一起开工。前一阶段的页面、字段和状态没有确认，后一阶段不能写死业务规则。

12.1.1 每个功能固定开发顺序

开发开始后，每个页面、接口和业务动作都按下面七步纵向完成，不采用“先把 21 个页面都画完，再统一补后端”的分离方式：

1. 冻结功能合同：确认 pageId、入口、TDesign 组件、OPS-*、用户、权限、状态、输入、输出、异常、fixture 和验收人。
2. 建立数据合同：确认表、字段、关系、状态、版本、唯一键、金额约束、索引、迁移和回滚/恢复验证；正式 Flyway 只在开工后创建。
3. 冻结接口合同：先评审 OpenAPI operationId、DTO、权限、状态、幂等、版本、错误码、审计和示例，再生成 Java/TypeScript 合同代码。
4. 实现 Java 业务：按 api/application/domain/infrastructure 四层完成领域规则、事务、权限、数据范围、SOD、审计、文件和 MySQL 持久化。
5. 实现 Starter 页面：只在现有 frontend/ 中加菜单、路由、TDesign 页面和批准的业务组合组件，接真实 Java API，不建立平行前端或正式业务 Mock。
6. 完成联调和测试：依次通过 Java 单元/集成、数据库约束、前端组件、OpenAPI 合同、Playwright 正常/失败/重复/越权/并发测试。
7. 形成证据并验收：保存请求编号、截图/录像、日志、导出文件、版本和哈希；验收人核对成功结果及失败阻断后，任务才进入 ACCEPTED。

前一步输出未经评审，后一步不得开始；同一功能的前端、后端、数据库和测试可以由不同人员实现，但必须指定一名闭环负责人，负责跟到真实数据、真实权限和验收证据全部通过。任何“页面已完成”“接口已完成”都只是过程状态，不是功能完成。

12.1.2 第一轮阶段交付边界

阶段	本阶段必须产出	本阶段明确不代表什么
S0	本文件 V2.9、《R1 基线包》、21 页低保真/已实现页面走查、14 类字段/附件字典、四类 fixture、逐表合同、状态矩阵和 OpenAPI 快照；全部通过后签发《R1 基线确认》	当前与开发并行收口；Starter 能启动、局部接口返回或单页完成仍不代表系统开发完成
S1	可重复构建的 Java/Vue/MySQL 底座，PAGE-01～03 真实会话，PAGE-04～06 授权工作台框架，权限/审计/文件/OpenAPI/CI 基础能力	工作台有框架不代表项目、财务、档案业务数据已完成
S2	PAGE-07～12、项目/主数据、14 类表单、导入、附件和审批的真实闭环	单个表单或单条成功样例不代表 S2 完成
S3	PAGE-13～15、合同成本、收款、发票、应付、付款检查及线下结果复核	只做台账页面或只通过正常付款路线不代表 S3 完成；系统始终不执行银行付款
S4	PAGE-16～21、记账准备、档案、文件借阅、六类报表、审计和系统配置闭环	生成一张凭证或一个档案包不代表 S4 完成；系统始终不自动过账或报税
S5	全量回归、迁移、性能、安全、恢复、staging/production、培训、UAT 和完整证据	演示通过、试用中或局部签字都不代表 R1 正式交付

S1～S4 可以分阶段评审和演示，但不能拆成若干残缺产品向甲方宣称“第一轮已完成”。第一轮唯一完成点是 S5 及第 12.9 节全部通过。

12.2 S0：需求冻结和可视化原型

目标：甲方先看到页面和数据流，确认“做的是不是这个东西”。

• PRE-S0-001 完成开发前底座核验：官方 TDesign Vue Next Starter 指定提交已导入 frontend/，保留许可证和锁文件，并完成一次依赖安装、类型检查、构建和本地启动。该项只证明底座可用，不表示 S1 已启动或任何财务业务功能已完成。

• PRE-S0-002 完成本文件 V2.8 规范收口：明确现有 Starter 是唯一前端，冻结新增菜单/页面/组件/功能的执行规则、固定视觉基线、完整 R1 口径、《R1 基线包》和开发团队缺陷闭环责任。该历史项只表示 V2.8 开发前文档已补齐，不替代 D-01～D-11、原型、样本和技术合同签字。

• TODO-S0-001 确认首期试点公司、项目和实际使用人员名单。负责人：甲方业务/财务。

• TODO-S0-002 确认三类业务身份的实际人员、公司/项目范围，以及独立系统管理员账号名单。负责人：甲方负责人。

• TODO-S0-003 走查并确认三类业务身份卡及隔离“系统管理”卡的名称、说明、人员归属和进入页面；所有账号登录后均先进入 PAGE-02 的交互已经按 4.1 节冻结。负责人：产品/甲方。

• TODO-S0-004 按 9.3～9.3.1 节把 OA-01～OA-14 源字段展开为正式字段字典：字段代码、类型、必填条件、枚举、长度、精度、敏感等级、导入列和下游映射。负责人：产品/业务。

• TODO-S0-005 为 OA-01～OA-14 各收集至少一份脱敏成功原始样本和一份失败原始样本，用于字段及错误场景走查；正式成功/必填失败/重复/越权 fixture 仍须由 TODO-S0-027 补齐。负责人：甲方/测试。

• TODO-S0-006 确认每类成本对应的附件矩阵和“不涉及”规则。负责人：财务/资料。

• TODO-S0-007 确认项目余额公式、冻结时点、负余额例外和审批人。负责人：财务负责人。

• TODO-S0-008 确认合同、付款、收款和发票关键状态及允许动作。负责人：产品/财务。

• TODO-S0-009 确认供应商账户新增/变更复核流程。负责人：财务。

• TODO-S0-010 确认现有记账系统需要的导出模板和人工结果字段。负责人：记账会计。

• TODO-S0-011 确认首期报表样式和金额统计口径。负责人：财务负责人。

• TODO-S0-012 确认文件格式、大小、保管期限和纸质原件位置规则。负责人：资料管理。

• TODO-S0-013 确认用户数、数据量、服务器、备份恢复目标。负责人：甲方 IT/技术。

• TODO-S0-014 基于官方 TDesign Vue Next Starter 布局和组件画出 PAGE-01～PAGE-21 低保真原型。负责人：产品/UI。

• TODO-S0-015 用“一家公司、一个项目”串联原型演示。负责人：产品。

• TODO-S0-016 形成需求确认记录：确认项、修改项、暂缓项和签字人。负责人：项目经理。

• TODO-S0-017 按 7.3、8.24～8.26 和 11.2 节冻结 21 个页面的页面分类、菜单、路由、TDesign 组件、读取/写入 operationId、权限码、状态、OPS-* 逐项操作合同和页面完成条件。负责人：产品/前端/后端/测试。

• TODO-S0-018 逐文件确认 11.2 节 Starter 原位改造清单，标明保留、重写、删除和新增内容；同时冻结唯一入口、依赖/ECharts 白名单、外链/iframe/Mock 扫描和 FE-GATE 输出规则。负责人：前端负责人。

• TODO-S0-019 对 PAGE-01～PAGE-21 原型逐页走查正常、空态、失败、无权、三档分辨率和键盘/焦点状态；需要新增业务组合组件时同步建立 COMP-* 记录。负责人：产品/UI/测试。

• TODO-S0-020 形成第一轮页面/API/数据/测试追溯表，为每个页面、操作和 UAT 分配负责人、验收人及证据 ID；任何页面不得缺后端负责人和验收人。负责人：项目经理。

• TODO-S0-021 按 11.6.2 节冻结逐表列、类型、默认值、状态、唯一键、检查约束、外键、索引、JSON Schema 和 ER 关系；评审人包含后端、DBA、财务和测试。负责人：后端负责人/DBA。

• TODO-S0-022 用评审后的数据合同形成首批 Flyway 设计稿和数据库验收用例，覆盖空库、重复键、非法状态、金额范围、外键拒绝、版本冲突和恢复校验；本任务只评审设计稿，不在开工前创建正式业务迁移。负责人：后端/测试/运维。

• TODO-S0-023 按 9.4～9.6 节冻结来源表单、主数据、项目风险标记、财务事件、收款、发票、付款、凭证、档案和借阅的完整状态字典、迁移矩阵、权限码、按钮、错误码和审计事件。负责人：产品/财务/后端/测试。

• TODO-S0-024 按 11.7.3～11.7.4 节冻结全部 R1 operationId、方法路径、请求/响应 DTO、字段约束、权限/范围、版本/幂等、错误码、示例和审计事件，生成首份 OpenAPI 快照并完成前后端评审。负责人：后端/前端/测试。

• TODO-S0-025 按 8.26 节冻结每个列表的筛选、排序、列、导出和工作台快捷入口映射，并在低保真原型逐项标注主按钮、行操作、禁用原因和结果去向。负责人：产品/前端/测试。

• TODO-S0-026 把岗位职责按 9.7 节映射到三类身份、岗位模板、权限码、数据范围、金额阈值和 SOD；确认项目涉诉/罚款人工风险标记的录入人、证据、有效期和解除人。负责人：甲方财务/产品/安全。

• TODO-S0-027 为 OA-01～OA-14 每类补齐成功、必填失败、重复、越权四种脱敏 fixture，并为付款、凭证、档案各准备成功、阻断、并发和 SOD 样本；逐项写明精确预期。负责人：甲方/测试。

完成标准：甲方能根据原型或已实现页面说清三类人分别进入哪里、做什么；P0 字段、状态、流程、权限和金额没有口头未落文档的规则；《R1 基线包》A～F、21 页页面基线、14 类字段/样本、逐表数据合同、OpenAPI 快照、状态矩阵和测试 fixture 均通过评审且不存在 TBD。满足后签发《R1 基线确认》，作为整套 R1 发布前置条件。

12.3 S1：Java/Vue 工程底座和权限

目标：先把系统外壳、安全和基础规范做好，后续业务模块在同一标准上开发。

执行限制：以下任务已有不同程度实现，但只有通过所属页面、接口、数据库、安全和验收证据后才能勾选完成。第 3.6 节基线缺项阻断受影响任务验收；既有技术代码不能仅因存在于仓库就直接把复选框改成完成。

• TODO-S1-001 创建 Git 仓库、分支保护和代码评审规则。
• TODO-S1-002 创建 Java 17、Spring Boot 3.5.16、MyBatis 3.0.5、Maven Wrapper 3.9.16 工程。
• TODO-S1-003 建立 local/test/staging/production 配置分离。
• TODO-S1-004 配置 MySQL 8.4、连接池和 UTC 时区。
• TODO-S1-005 建立 Flyway 基线和数据库命名规范。
• TODO-S1-006 建立统一返回、分页、错误码、请求 ID 和日志格式。
• TODO-S1-007 建立登录、密码哈希、Session、CSRF 和账号锁定。
• TODO-S1-008 建立用户、角色、权限、公司/项目范围数据库表。
• TODO-S1-009 实现登录页、身份选择页和个人中心 API。
• TODO-S1-010 实现三类业务工作台和纯系统管理员 PAGE-21 入口的导航骨架。
• TODO-S1-011 实现角色+数据范围+金额阈值+流程节点授权服务。
• TODO-S1-012 实现岗位互斥规则和授权冲突检查。
• TODO-S1-013 建立审计日志基础组件，记录操作人和前后值。
• TODO-S1-014 建立文件上传、哈希、类型检查、隔离目录和业务关联组件。
• TODO-S1-015 配置 OpenAPI、ArchUnit、JUnit、Testcontainers 和 JaCoCo。
• TODO-S1-016 配置格式检查、漏洞扫描、凭据扫描和禁止 Scheduler/Connector 检查。
• TODO-S1-017 在干净 S1 环境复核已经导入的官方 Tencent/tdesign-vue-next-starter 提交 1f183fa089d07183235dc69dbd76b8b2c4a6d8bb：核对许可证和锁文件，使用 Node.js >=22.12.0 重跑 npm ci、类型检查、生产构建和本地启动，并把结果作为正式工程基线证据。开发前证据见 PRE-S0-001，不得直接沿用为本任务完成。
• TODO-S1-018 盘点并裁剪 Starter：删除注册入口、产品演示页、默认公网 API、远程品牌资源和生产 Mock，保留布局、结果页、Pinia、路由和 Axios 骨架。
• TODO-S1-019 建立 OpenAPI 类型生成/API 客户端，统一处理请求编号、幂等键、版本冲突和 ProblemDetail 错误。
• TODO-S1-020 基于 TDesign 建立列表、动态表单、金额输入、附件上传、导入错误、状态标签、审批时间线和敏感字段等公共组件。
• TODO-S1-021 建立 TDesign 主题 Token、页面密度、状态颜色、中文文案、图标和三档办公分辨率规范，禁止混入第二套业务组件库或公网 CDN 资源。
• TODO-S1-022 把 Starter Token 登录改成 Spring Session + CSRF，接入身份选择、后端菜单权限、会话失效和服务端越权处理；前端存储禁止持久化 Token 和敏感数据。
• TODO-S1-023 为 Starter 补充真实 Vitest、Playwright、axe 和覆盖率脚本，并在生产构建中检查 Mock、示例路由、默认公网地址、外链资源、iframe、第二入口和第二 UI 库为零，生成带 SHA-256 的 FE-GATE-{gitCommit}.json。
• TODO-S1-024 按 11.15 节建立仓库、Java 四层包、Flyway、OpenAPI 快照、结构化日志和根目录全量校验命令，并用 ArchUnit 固化模块边界。
• TODO-S1-025 清理 Starter 当前依赖审计问题：删除正式工程不需要的 Mock 依赖，升级/替换运行和构建依赖，使严重/高危漏洞为零并生成 SBOM。
• TODO-S1-026 按 11.2 节重组前端目录，建立固定 side 布局、八类页面模板（公共入口、工作台、列表/台账、业务详情、录入/导入、审批处理、配置管理、结果/异常）、路由 meta、业务组件和 Loading/Empty/403/404/409/422/500 统一状态。
• TODO-S1-027 对页面、ECharts 和报表做动态导入/按需加载，清理 npm 不支持的 Starter 配置，接入包体报告并达到 11.11 节前端性能预算。
• TODO-S1-028 完成 11.2 节 Starter 文件级改造清单、frontend/contracts/routes.json、components.json、operations.json、COMP-* 组件批准记录和 OPS-* 菜单/组件/功能逐项合同的代码评审，证明只有一个前端入口、一个布局体系、一个 UI 组件库和一套菜单/权限链路；每个可见操作都具备路由、组件、权限、状态、operationId、结果、审计和测试证据。
• TODO-S1-029 锁定明确支持 MySQL 8.4 的 Flyway Core/MySQL 版本，完成空库迁移、重复启动、升级和失败停止测试；任何“数据库版本未测试”警告必须清零。
• TODO-S1-030 按 11.10.1 节实现并自动验证密码、锁定、Session、Cookie/CSRF、字段加密、安全响应头和 production 启动失败条件。

完成标准：S1 全部 TODO 和对应页面/API/数据库/安全追溯项完成；前后端都能从空环境构建；生产前端不含 Starter 演示业务、注册入口、默认公网 API、生产 Mock 或敏感 Token 持久化；项目、财务、资料三类普通业务账号只能进入各自授权范围，隔离超级管理员可进入全部页面并查看全局数据；审批处理人和 SOD 不因超级权限失效；越权页面和接口被拒绝并留痕；数据库能从空库迁移成功。单个账号或单条登录样例通过不构成 S1 完成。

12.4 S2：项目、主数据、14 类表单和审批

目标：先打通“资料进入系统并完成审核”。

• TODO-S2-001 开发公司、部门、项目主数据、人工涉诉/罚款风险标记及对应接口；风险只由授权人员录入，不连接外部查询。2026-08-15 子状态：部门已完成真实表、API、字典权限范围、异人复核、审计、TDesign 页签及三档行为回归；八类可维护主数据已补分页版本记录、双版本字段差异和权限负向断言；本任务还包含公司/项目正式验收、旧编号映射和人工风险标记完整矩阵，因此保持未勾选。
• TODO-S2-002 开发供应商/客户主数据、证照去重和状态管理。
• TODO-S2-003 开发供应商银行账户版本和双人复核。
• TODO-S2-004 开发合同、合同变更、结算金额和状态管理。
• TODO-S2-005 开发成本类别、科目、税率和附件矩阵字典。
• TODO-S2-006 开发 PAGE-07 项目列表和 PAGE-08 项目详情骨架。
• TODO-S2-007 开发表单模板版本、字段字典和模板发布机制。
• TODO-S2-008 开发两阶段导入：上传校验、错误清单、确认入库。
• TODO-S2-009 实现来源唯一键和重复导入幂等保护。
• TODO-S2-010 开发来源单据、审批快照和附件版本。
• TODO-S2-011 开发内部审批定义、实例、任务、动作和意见。
• TODO-S2-012 实现提交、通过、退回、驳回、撤回、作废状态机。
• TODO-S2-013 开发 PAGE-09 表单中心、PAGE-10 填写/导入页、PAGE-11 待办页。
• TODO-S2-014 配置 OA-01 项目立项字段、校验和输出。
• TODO-S2-015 配置 OA-02 供应商准入字段、附件和账户待审输出。
• TODO-S2-016 配置 OA-03 成本合同会签字段、附件和合同输出。
• TODO-S2-017 配置 OA-04 人材机应付字段和动态附件矩阵。2026-08-14 子状态：模板 v2、合同/供应商/成本分类引用、发票含税汇总和终审应付投影已实现；正式附件矩阵发布和全量表单验收仍待完成。
• TODO-S2-018 配置 OA-05 收款确认字段和收款输出。2026-08-14 子状态：模板 v2、终审 CONFIRMED 收款、资金台账和会计事件已实现并通过 SourceWorkflowIntegrationTest；正式页面 UAT 和证据包仍待完成。
• TODO-S2-019 配置 OA-06 进度款支付字段和付款申请输出。2026-08-16 子状态：V070 已发布 OA-06 v2，补齐合同、供应商、已确认应付稳定引用；财务终审在来源审批事务内生成 OFFLINE_PENDING 付款，同步执行付款检查、全额冻结和资金流水，余额不足时来源审批、付款、冻结和流水整体回滚。后端全量 211/211、来源审批专项 37/37 及真实 HTTP 成功/失败链均通过；正式附件矩阵确认、三档浏览器 UAT 和甲方证据包仍待完成，因此本项保持未勾选。
• TODO-S2-020 配置 OA-07 银行账户字段和账户版本输出。
• TODO-S2-021 配置 OA-08 发票申请字段和开票申请输出。2026-08-14 子状态：模板 v2、客户/合同引用、合同快照、在途候选额度预占和终审 DRAFT 开票候选已实现并通过来源专项回归；来源候选退回更正闭环和正式 UAT 仍待完成。
• TODO-S2-022 配置 OA-09 实名入场字段、加密和脱敏。
• TODO-S2-023 配置 OA-10 履约进度、明细、照片和进度输出。
• TODO-S2-024 配置 OA-11 合同结算字段和结算版本输出。
• TODO-S2-025 配置 OA-12 验收字段和归档触发输出。
• TODO-S2-026 配置 OA-13 押证费用字段和费用候选输出。
• TODO-S2-027 配置 OA-14 人员新增/变更/驻派字段和名册版本。
• TODO-S2-028 为 14 类表单逐一编写成功、失败、重复和越权测试。

完成标准：S2 全部 TODO、PAGE-07～12、对应接口/数据表/状态矩阵和追溯项完成；14 类表单都能创建/导入、校验、审批、退回和归档，每类成功、必填失败、重复和越权 fixture 全部通过。每类一条成功和一条失败只是最低演示样例，不能替代其余动作、状态、权限和异常测试。

12.5 S3：合同成本、收款、发票和付款

目标：把财务最急需的收支数据从表单变成可用台账。

• TODO-S3-001 开发合同执行和项目成本台账。
• TODO-S3-002 实现合同额、变更额、结算额、已开票、已应付、已付计算。
• TODO-S3-003 开发应收、收款、暂收和应收核销。2026-08-11 模块验收：人工开票结果生成正式应收；收款允许暂不匹配项目/客户；确认后可按应收核销；作废与记账事件联动。2026-08-14 OA-05 终审投影直接生成已确认收款并进入项目资金台账，后续仍走既有核销链。
• TODO-S3-004 实现一收多应收和一应收多次收款。2026-08-11 模块验收：ReceivableIntegrationTest.receiptAllocationsSupportManyToManySettlement 通过，两条收款与两条应收交叉核销后均结清。
• TODO-S3-005 开发销项开票申请、人工开票结果、红冲/作废关系。2026-08-11 模块验收：提交、异人复核、人工结果、应收生成、作废、红冲和原票关系通过自动化与浏览器实操。2026-08-14 OA-08 终审投影生成带来源版本的 DRAFT 候选，仍需 PAGE-14 人工提交/复核/登记结果。
• TODO-S3-006 实现开票额度、重复风险和附件检查。2026-08-11 模块验收：合同可开票额在审核及结果登记时复算；同公司发票号/收款流水号重复拒绝；关联结果文件必须处于允许的本地检查状态。
• TODO-S3-007 开发应付记录和应付可用余额。2026-08-13 模块验收：应付登记/确认 SOD、OA-04 已批准来源、待确认/已应付分列、合同额度预占、重复来源和乐观锁通过自动化与真实页面验收。
• TODO-S3-008 开发付款申请和项目资金、合同、应付、账户、附件、重复、涉诉/罚款人工风险标记检查。2026-08-15 复核：申请主链及项目资金、合同、应付、生效账户、通用/按成本类型附件、精确/近似重复、OA-06 当前批准版本和项目阻断风险检查均已实现；DUPLICATE/PROJECT_RISK 可例外项通过异人审批、有效期、指纹复算和批准时原子消费，硬控制清单始终阻断。
• TODO-S3-009 实现项目资金控制行、资金台账和并发锁。2026-08-15 复核：V037 建立追加式 fund_ledger，付款冻结/支付、收款变动和 OA-05 投影均写入来源事件唯一的逐笔分录；FundLedgerApplicationService 在锁定控制行后幂等追加并记录审计，PAGE-15 TDesign 资金流水抽屉提供范围内查询；PaymentIntegrationTest 已覆盖冻结/支付、重放、重复来源、查询和范围阻断，独立真实 HTTP 查询已验证。本项完成，但 PAGE-15 仍受矩阵和例外规则阻断。
• TODO-S3-010 实现供应商生效账户版本检查。2026-08-13 定向验收：创建/编辑只返回当前生效版本，批准及重付时重新锁定账户并检查状态、有效期和供应商归属；账户失效阻断测试包含在 PaymentIntegrationTest。
• TODO-S3-011 实现按成本类型的付款附件检查。2026-08-13 子状态：V036、严格矩阵解析/治理校验、应付分类规则读取、TDesign 逐项状态、结构化资料类型、付款规则快照以及缺件/文件状态/历史兼容检查已实现并通过 PaymentIntegrationTest；完整业务矩阵因 D-02/D-09 未确认保持 DRAFT，例外机制已由 TODO-S3-017 完成，但正式规则仍未发布，故本业务任务暂不勾选。
• TODO-S3-012 实现疑似重复付款检查和例外审批。2026-08-15 复核：精确重复返回阻断，强/中度近似按日期、金额和事由分级；中度仅记录警告，强/精确可发起一次性例外；申请、异人审批、有效期、发现指纹复算、原子消费、重复提交和过期换版均由 PaymentIntegrationTest 覆盖。
• TODO-S3-013 开发线下付款结果登记和另一人复核。2026-08-13 定向验收：线下结果必须附回单，登记人不得复核或退回本人结果；结果退回后可再次登记且不重复改变资金和会计事件。
• TODO-S3-014 开发部分支付、失败、退汇和重付关系。2026-08-13 定向验收：部分支付保留剩余冻结额，失败只释放未支付额，退汇逆转资金/应付/会计事件，重付关联原付款并限制金额和序号。
• TODO-S3-015 开发 PAGE-13、PAGE-14、PAGE-15。子状态：PAGE-13/14=MODULE_ACCEPTED；PAGE-15 核心付款链、逐笔资金台账、例外机制及来源页面证据已完成，但正式附件矩阵确认、三档浏览器/异常状态证据和甲方验收尚未完成，本聚合任务保持未完成。
• TODO-S3-016 编写余额不足、合同超额、账户失效、附件缺失、重复和 SOD 测试。2026-08-13 定向验收：上述单请求阻断和 SOD 均由 PaymentIntegrationTest 覆盖；同项目两笔付款并发竞争余额时仅一笔成功，另一笔返回 FUNDS_INSUFFICIENT，最终冻结额与成功付款一致。
• TODO-S3-017 开发一次性例外申请、审批、使用和审计，并固化永不允许例外的硬控制清单。2026-08-15 复核：付款控制例外和附件“不涉及”均记录原因、发现快照/指纹、申请/复核人、有效期、版本和消费时间；批准时按当前发现重新校验并在同一事务内消费，账户、SOD、额度、附件硬要求、来源和资金控制等永不允许例外。正式附件矩阵是否允许“不涉及”仍受 D-02/D-09 业务确认约束。

当前阶段结论：PAGE-13/14 和 TODO-S3-003～TODO-S3-010、TODO-S3-012、TODO-S3-013、TODO-S3-014、TODO-S3-016、TODO-S3-017 已完成实现或定向验收；TODO-S3-011 的技术能力已验证但正式业务矩阵未发布，TODO-S3-015 仍等待 PAGE-15 模块级验收，S3 整体继续为 IN_PROGRESS。

完成标准：S3 全部 TODO、PAGE-13～15、对应接口/数据表/金额规则/状态矩阵和追溯项完成；收款、发票、应付、进度款及付款的正常、阻断、并发、重复、例外和 SOD 路线全部通过。一笔收款、一张发票申请、一笔应付和一笔进度款是最低端到端样例，不构成范围完成；系统不得产生任何银行付款指令。

12.6 S4：记账准备、档案和查询

目标：完成“业务结果 → 记账准备 → 归档 → 查询”的闭环。

• TODO-S4-001 建立财务事件类型和来源事件唯一约束。
• TODO-S4-002 建立凭证规则版本和借贷分录模板。
• TODO-S4-003 开发凭证草稿生成和重复生成保护。
• TODO-S4-004 实现借贷平衡、辅助维度和期间检查。
• TODO-S4-005 实现制单与复核分离。
• TODO-S4-006 开发记账标准文件导出、批次和文件哈希。
• TODO-S4-007 开发外部人工记账结果登记和复核。2026-08-15 子状态：结果登记、异人复核、已完成结果冲销、异人重开、分轮证据、历史外部凭证号唯一、授权额度/数据范围、SOD、版本、幂等和审计已实现，AccountingIntegrationTest 18/18 通过；正式外部导入样例和甲方 UAT 未完成，本项保持未勾选。
• TODO-S4-008 开发 PAGE-16 记账准备中心。2026-08-15 子状态：真实 TDesign 页面/API、凭证主链、导出、人工结果、已冲销页签、冲销/重开弹窗、当前轮次、历史动作和历史证据下载已贯通；PAGE-16 三档专项 12/12、完整 Playwright 111/111 通过。正式 Chrome/Edge 真实数据证据和甲方签字未完成，本项保持未勾选。
• TODO-S4-009 开发项目档案包生成、缺件清单和版本快照。2026-08-15 子状态：档案包生成、预期缺件清单、文件/对象快照、manifest 与 SHA-256 已实现；生成已受项目 financeStatus=COMPLETED 服务端门禁约束，本项等待正式浏览器和甲方验收后勾选。
• TODO-S4-010 开发资料审核、退回补件和确认归档。2026-08-15 子状态：检查、无缺件提交、资料异人退回、补件新版本、归档、冻结/解冻及缺件阻断已实现；完整权限/失败路线和正式证据包仍未完成，本项保持未勾选。
• TODO-S4-011 开发文件检索、预览、下载水印、借阅和归还。2026-08-15 子状态：本地检索、版本详情、水印预览、范围外直链下载回归、可恢复重扫及“资料申请 → 财务批准 → 资料归还”闭环已通过；正式多浏览器负向矩阵和证据包未完成，本项保持未勾选。
• TODO-S4-012 开发 PAGE-17、PAGE-18。2026-08-15 子状态：PAGE-17 已有真实页面/API、财务确认按钮与合同、档案状态机和保管到期显示，财务确认/归档门禁后端专项 1/1 通过；PAGE-18 的隔离文件来源、范围链接、幂等重放、崩溃恢复、异人借阅/归还已完成本地 HTTP、浏览器和数据库定向验证。Chrome/Edge 三档完整业务流、正式异常 fixture、权限失败路线和甲方证据包未完成，本项保持未勾选。
• TODO-S4-013 开发项目综合、合同执行、收款开票、付款进度、流程时效和资料完整性报表。2026-08-16 子状态：六类报表、汇总、状态/金额展示和 MySQL 8.4 全量集成回归已完成；D-08、日期口径、流程时长真实样本和正式 UAT 未完成，本项保持未勾选。
• TODO-S4-014 实现报表下钻和同权限导出。2026-08-16 子状态：下钻已复用父行身份/权限/完整筛选；两阶段导出已实现服务端预检、冻结筛选/列/排序/预计行数、页面确认和确认时人员/身份/权限范围/口径/快照重新校验，并完成 MySQL 8.4 全量集成回归。本项仍缺全分支权限证据和正式证据包，保持未勾选。
• TODO-S4-015 开发 PAGE-19、PAGE-20、PAGE-21、PAGE-22。2026-08-17 子状态：四页真实 TDesign 页面和接口已实现；PAGE-20 完成稳定排序、URL 筛选、脱敏详情和同序导出，PAGE-21 专注权限与业务配置，PAGE-22 独立承载签名在线更新和历史记录。四页均为 IMPLEMENTED_PENDING_ACCEPTANCE，正式业务口径、异常权限矩阵和甲方签字未完成，本项保持未勾选。
• TODO-S4-016 完成项目详情从来源到记账和档案的双向穿透。

完成标准：S4 全部 TODO、PAGE-16～22、对应接口/数据表/状态矩阵和追溯项完成；财务事件、凭证、导出、人工结果、档案、文件借阅、六类报表、审计、配置和更新的正常及失败路线全部通过。一笔财务记录只能形成一张有效凭证草稿只是最低端到端样例；人工结果、档案版本、报表下钻和权限证据必须按全范围验收。

12.7 S5：测试、迁移、试点和交付

目标：证明系统真实可用，而不只是页面能打开。

• TODO-S5-001 完成所有 P0 单元、数据库、接口、权限和端到端测试。2026-08-16 子状态：最近完整后端 MySQL 8.4/Testcontainers 基线 211/211，Failures/Errors/Skipped 均为 0，70 个迁移从空库执行到 V070；Vitest 53/53、Chromium 三档 Playwright 183/183、在线更新专项 15/15、四种身份真实 Edge 登录 PAGE-01～21 冒烟 21/21、安装器/在线更新/Gitea 发布 fixture 通过；正式 Edge 全操作矩阵、性能、安全和甲方 UAT 未完成，本项保持未勾选。
• TODO-S5-002 完成三类业务身份和纯系统管理员的正向、越权及账号互斥测试矩阵。
• TODO-S5-003 完成重复导入、重复点击、并发付款和并发凭证测试。
• TODO-S5-004 完成文件类型、大小、恶意内容和下载权限测试。
• TODO-S5-005 完成代码漏洞、依赖漏洞、凭据和禁止外连扫描。2026-08-16 子状态：npm 完整依赖树为 0 vulnerabilities，production hygiene、私钥排除、RSA/SHA-256 制品校验通过；完整 SAST、凭据和出站网络证据仍待归档，本项保持未勾选。
• TODO-S5-006 完成性能测试并输出 P95/P99 报告。
• TODO-S5-007 盘点并清洗试点公司、项目、供应商、合同和附件。
• TODO-S5-008 建立旧编号和新系统 ID 映射。
• TODO-S5-009 完成期初试导、错误修复、金额对账和三方确认。
• TODO-S5-010 部署 staging，组织甲方按验收场景操作。
• TODO-S5-011 修复 P0/P1 缺陷并完成回归。2026-08-16 Preview 代码复审 P0 为零，已修复更新请求丢失、备份管道误判、回滚未复核、重装配置丢失和 OpenAPI 错误响应缺口；正式服务器、Edge 和甲方 UAT 缺陷仍未收口，本项保持未勾选。
• TODO-S5-012 配置生产 HTTPS、数据库、文件卷、日志和监控。
• TODO-S5-013 完成数据库+文件备份及恢复演练，核对 SHA-256。
• TODO-S5-014 部署生产并完成冒烟测试。
• TODO-S5-015 培训项目、财务、资料和管理员四类使用人员。
• TODO-S5-016 交付源代码、数据库、部署包、模板、测试报告和操作手册。2026-08-16 子状态：签名 Preview 应用包、可靠更新器、单命令安装器、manifest、SHA-256 清单、前后端 SBOM 和 README 部署/重装教程已生成并验签；实际 Git 仓库/Release 上传、甲方资料包和签字仍未完成，本项保持未勾选。
• TODO-S5-017 完成甲方验收签字和遗留问题清单。
• TODO-S5-018 使用 Playwright + axe 完成 PAGE-01～PAGE-21 关键浏览器流程、三类业务身份及系统管理员截图、键盘焦点和可访问性核验。2026-08-17 子状态：合同驱动的 21 页 Chromium 三档和完整 Playwright 套件 192/192 通过，新增超级管理员在权限摘要滞后时逐页打开全部业务页面的回归；四种身份真实 Edge 登录 PAGE-01～21 冒烟 21/21 继续有效；PAGE-07/08/10/13/14/15/18 关键业务流程、PAGE-20 审计和 PAGE-21 更新启用/禁用/恢复失败状态已纳入回归；键盘路径、正式截图矩阵和 Edge 全操作矩阵未完成，本项保持未勾选。
• TODO-S5-019 在 1366×768、1440×900、1920×1080 三档分辨率逐页核验布局、文字、表格、弹窗和固定操作栏，无重叠、截断或页面整体横向溢出。2026-08-15 子状态：21 页三档 document overflow 自动断言已通过；真实数据长文本、表格、弹窗、抽屉、固定操作栏和 Chrome/Edge 人工截图未全部完成，本项保持未勾选。
• TODO-S5-020 核验空态、慢加载、网络失败、401、403、404、409、422、500、重复点击、会话失效和未保存离开，保留截图/录像与请求编号证据。
• TODO-S5-021 对生产构建执行无 Mock、无演示数据、无外部请求、无 iframe 拼装、无第二 UI/入口、无控制台错误、无未处理 Promise、无持久化敏感数据扫描，核验 FE-GATE 报告，并逐项确认页面按钮均连接真实 API。

完成标准：S5 全部 TODO、UAT-001～035 和第 12.9 节 R1 DoD 全部通过；试点项目端到端通过；P0/P1 缺陷清零；数据差异清零或有批准说明；备份可恢复；甲方人员能独立完成核心操作。未满足第 12.9 节时，S5 不得以“已演示”或“甲方正在使用”为由标记完成。

12.8 ToDoList 状态使用方法

每个 TODO-* 在项目管理工具中至少包含：负责人、计划开始/完成日期、前置任务、关联页面/需求、验收人、当前状态和验收证据链接。

状态统一为：BACKLOG → READY → IN_PROGRESS → REVIEW → TESTING → ACCEPTED；阻塞时标记 BLOCKED 并写清缺少哪个甲方决策或样本。

验收证据包规则

每次自动化测试、页面验收和 UAT 生成不可混写的证据包。命名固定为 UAT-{编号}-{pageId或DOMAIN}-{fixtureId}-{gitCommit}.zip，内部至少包含 manifest.json、操作步骤、输入 fixture 版本、页面截图/录像、HTTP 请求与响应摘要、请求编号、业务/审计断言、浏览器版本、OpenAPI 版本、Flyway 版本和各文件 SHA-256。敏感值只保留脱敏摘要，不进入录像、Network 导出或日志。

证据包存放在甲方批准的 CI 制品库或内部对象存储，路径按 r1/{releaseVersion}/{gitCommit}/{uatId}/{fixtureId}/ 固定；开启不可覆盖版本和访问控制，不使用开发人员本机路径、聊天临时链接或会过期的公共网盘。任务链接失效时任务自动退回 REVIEW。证据保留期限和到期处置纳入 D-09；在期限未确认前不得删除任何 R1 验收证据。

12.9 第一轮 Definition of Done

一个开发任务只有同时具备以下证据，才能从 TESTING 进入 ACCEPTED：代码已评审；OpenAPI/数据库/权限同步更新；正常、失败、重复和越权测试通过；前端包含规定的加载、空态和错误状态；没有 Mock 或待接按钮；验收人能从任务链接打开自动化报告、接口证据或截图。只完成前端、只完成后端、只在开发者电脑运行或口头说“已经好了”都不算完成。

R1 只有下表全部满足，才能标记为第一轮完整交付：

完成维度	R1 必须具备的客观证据
范围	PAGE-01～PAGE-21、OA-01～OA-14、F-01～F-14 全部完成；F-15～F-16 和第三方自动化仍明确排除
前端	固定使用 TDesign Starter side 布局和组件；三类身份菜单正确；11.2 节八类页面模板、全部按钮、弹窗、表格、表单和异常状态连接真实 API
一致性	1366×768、1440×900、1920×1080 全页面无重叠/截断/整体横向溢出；状态、金额、日期、图标、文案和操作顺序一致
后端	Java 模块边界、鉴权、状态机、金额、幂等、并发、审计、文件和导出规则实现；不存在依赖前端隐藏按钮的安全控制
数据	空 MySQL 8.4 可用 Flyway 一次建立；试点数据可重复导入；刷新、重启和重新登录后数据及关系完整；无人工改库步骤
业务闭环	一家公司/一个项目从三种来源进入，完成审批、财务记录、记账准备、档案和下钻查询；成功和被阻断路线都有证据
权限	项目、财务、资料、管理员四类账号完成菜单、按钮、API、数据范围、金额阈值、流程节点、敏感字段和岗位互斥测试
文件/审计	上传、版本、哈希、预览、下载、水印、借阅、归档和恢复通过；关键动作能按请求编号还原操作人、身份、前后值和时间
前端运行质量	production 构建无 Mock、演示路由、默认公网地址、远程资源、控制台错误、未处理 Promise、重复请求副作用或敏感浏览器持久化；路由按需加载并满足包体预算
自动化测试	Java/Vitest/合同/Playwright/迁移/并发/性能/恢复测试全部通过；总体覆盖率 ≥80%，金额、权限、状态机和凭证规则 ≥90%
安全和依赖	明文密钥、严重/高危漏洞、默认生产密码、开放调试、越权和恶意文件放行均为零；中低危有书面处置
部署运维	staging 和 production 可按文档从零部署；HTTPS、日志、监控、备份和联合恢复演练通过；制品版本、SBOM、哈希可追溯
缺陷	P0、P1 缺陷清零；剩余 P2 不影响业务、权限、金额和数据，已记录负责人、处理版本；甲方对影响和延期知情确认，缺陷定级、根因定位、修复和回归仍由开发团队负责
交付使用	源代码、制品、迁移、样本、报告和操作材料齐全；四类用户完成培训并能独立通过对应核心 UAT
签字	产品、前端、后端、测试、运维、甲方业务、财务和资料负责人共同确认，项目经理汇总形成唯一 R1 验收结论

S1～S4 的阶段演示用于尽早发现问题，不触发“部分交付完成”。只有 S5 完成并满足本节全部条件，R1 才算完整系统。

12.10 第一轮开发与缺陷责任

“自己去改、自己去修”在本项目中转化为闭环交付责任：第一轮进入开发后，由开发团队对完整 R1 的可运行性负责，主动完成实现、自测、联调、定位、修复、回归、部署和证据整理，不把联调、基础测试和明显缺陷转交给甲方承担：

发现问题
  → 固定 fixture 和版本复现
  → 关联请求编号、日志、页面、接口、数据库和权限
  → 判断根因及影响范围
  → 修改代码/迁移/合同/测试
  → 扫描同类页面和同类规则
  → 自动化回归 + 真实环境冒烟
  → 重新部署并留存证据
  → 由验收人复核后关闭

这条链由开发团队主动推进。甲方反馈“某个按钮不能用、金额不对、看不到项目、附件缺失”等业务现象即可，开发团队必须自行完成技术定位和修复；不能要求甲方执行 SQL、修改浏览器缓存、手动补数据或在多个环境重复猜测问题。若根因是本文件已经冻结但实现遗漏，按缺陷修复处理，不得借“需求未说清”推迟；若确实超出冻结范围，才按第 2.3 节变更流程提交决策。

1. 每个任务由实现人完成前端、后端或数据职责内的自测；跨端任务由指定主责人跟到真实闭环通过，不能以“我这边接口/页面已经写完”为结束。
2. 已在本文件冻结的页面、按钮、状态、权限、错误处理、响应式和测试缺失属于未完成或缺陷，修正这些内容不作为新增需求重新排期。
3. 开发过程中发现字段、金额公式或审批规则无法确定时，立即关联 D-01～D-11 决策项；不得自行猜测后写死，也不得用 Mock 绕过。
4. 缺陷由对应模块负责人修复并补回归测试；同类问题在其他页面同步排查，不能只修验收时被点到的一处。
5. 甲方 UAT 前必须先通过开发自测、代码评审、自动化测试和测试团队验收；甲方 UAT 用于确认业务结果，不用于替代开发团队找基础功能问题。
6. 每次修复同时检查 OpenAPI、数据库迁移、权限、审计、文档、测试和已有数据兼容性，禁止通过手改生产数据或临时隐藏按钮“修复”。
7. R1 验收前 P0/P1 持续修复到清零；所有遗留 P2 写明影响、负责人和目标版本，由甲方对影响和延期作知情确认。缺陷定级、根因定位、修复和回归仍由开发团队负责，不能以等待甲方确认代替开发验收，也不能由开发团队单方面宣布交付完成。
8. 甲方只需提供业务现象、操作时间和可见请求编号；开发团队自行完成日志关联、复现、根因定位、代码/迁移修正、同类问题扫描、自动化回归、重新部署和结果说明，不要求甲方查看源码、执行 SQL 或替开发人员联调。

13. 验收标准

13.1 端到端验收场景

验收编号	操作场景	必须看到的结果
UAT-001	分别用单业务身份、多业务身份和纯超级管理员账号登录	三者都先进入 PAGE-02；单身份只显示一张卡且需点击进入，多业务身份只显示已授权业务卡；纯超级管理员只显示一张隔离卡并默认进入 PAGE-21，随后可从侧栏访问 PAGE-04～21、查看全局数据；项目身份仍只看到项目工作台和授权项目
UAT-001A	超级管理员查看三类业务工作台、跨人员草稿、导入批次和全部付款，再尝试处理不属于自己的审批任务或同人复核	项目、资金、档案和全部待办在工作台可见，跨人员查询和管理成功；管理员专用“全部付款”可用；非实际节点处理人的审批返回 403，同人登记/复核返回 422 SOD_VIOLATION，状态、余额、附件和审计规则不被绕过
UAT-002	同一账号从项目身份切换到财务身份	重新进入 PAGE-02；导航和待办变化、数据范围不扩大，旧身份页签、缓存和无权详情全部清除
UAT-003	未授权用户直接访问财务 URL/API	服务端拒绝并产生审计记录
UAT-004	OA-01 创建项目立项并通过审核	项目生效，可反查原表单、审批和附件
UAT-005	OA-02 新增供应商账户	未复核前不能用于付款，复核人不能是提交人
UAT-006	OA-03 创建成本合同	合同原额、变更和结算额分开保存
UAT-007	OA-01～OA-14 每类导入成功样本	字段、附件、审批快照和下游对象正确
UAT-008	OA-01～OA-14 每类导入失败样本	错误定位到表/行/列/字段，正式数据不增加
UAT-009	重复导入同一表单类型+来源系统+规范化单号+版本	只保留一个有效来源和财务事件
UAT-010	退回表单并补件后重提	保留退回意见、旧版本和新版本差异
UAT-011	OA-05 收款确认	收款进入项目台账，证据和审核记录齐全
UAT-012	OA-08 开票申请并登记人工结果	不连接发票平台，人工结果和附件可查
UAT-013	OA-06 付款资料齐全且额度足够	进入待线下付款，不产生银行指令
UAT-014	分别制造余额不足、合同超额、有效涉诉/罚款人工风险标记和允许例外的非硬性附件缺失	前三类及无批准例外的附件缺失均阻断；批准后只放行指定单据的指定非硬性规则一次，风险硬阻断须先由授权人员解除
UAT-015	同一人登记并复核付款结果	系统按岗位分离规则拒绝
UAT-016	登记付款失败/退汇并重新支付	原付款、失败/退汇和新付款关系完整
UAT-017	对同一财务事件连续点击生成凭证	只有一张有效凭证草稿
UAT-018	凭证借贷不平或缺项目维度	不允许复核和导出
UAT-019	导出记账文件并登记人工凭证号	导出批次、哈希、登记人和复核人可查
UAT-020	未完成财务确认时尝试生成档案包；财务在授权范围确认后再次生成	未确认返回 422；无权限、越范围和旧版本分别被拒绝；确认成功后形成规定资料清单、对象快照和不可覆盖版本
UAT-021	资料人员退回档案后补件归档，并检查保管到期与冻结	退回、补件、异人复核和最终版本完整；到期仅提示、不自动删除；FROZEN 时禁止处置
UAT-022	无权用户预览或下载敏感文件	被拒绝；有权下载带水印并记审计
UAT-023	从项目报表点击金额	可下钻到合同、表单、财务记录和附件
UAT-024	停用用户后使用原会话	会话立即失效，历史操作仍显示原身份
UAT-025	断开公网后完成核心流程	人工文件导入、审核、记账准备和归档仍可完成
UAT-026	分别用在线填写、OA 已审批导入和历史批次导入创建数据	三条路线按 5.2 节分流，审批快照、确认人和批次证据正确
UAT-027	尝试对未生效账户、同人登记/复核、重复有效事件、借贷不平和恶意文件发起例外	不显示例外入口，后端始终阻断并留审计记录
UAT-028	检查 Starter 改造后的生产构建并断网运行	不含注册/演示路由、默认公网 API、生产 Mock、远程资源和持久化 Token；登录、身份选择及核心页面正常
UAT-029	用项目、财务、资料和管理员账号逐项检查菜单、页签、隐藏详情路由和按钮	菜单顺序符合 7.3；只显示当前身份可见入口；切换身份清空旧页签/缓存；手输无权 URL 和调用 API 都被拒绝
UAT-030	逐页检查 PAGE-01～PAGE-21 的组件、图标、颜色、间距、状态和操作顺序，并执行组件批准记录与可访问性检查	所有界面控件只使用 TDesign/TDesign Icons 及有 COMP-### 记录的业务组合组件；ECharts 只在 PAGE-04～06、PAGE-19 绘制必要图表且不承担控件职责；无第二套 UI、腾讯商标、演示文案、渐变/Hero/插画横幅、嵌套卡片或大面积改写 TDesign 的 CSS；axe critical/serious 为零
UAT-031	在 Chrome、Edge 的 1366×768、1440×900、1920×1080 完成三类身份核心操作、键盘路径并截图	页面、表格、弹窗、抽屉、分页和固定操作栏无重叠、截断、异常跳动或页面整体横向溢出；焦点可见、图标按钮有中文名称、状态不只靠颜色表达
UAT-032	对关键页面制造首次加载、空结果、慢请求、网络失败、401、403、404、409、422 和 500	每种状态按 11.2 节正确反馈，普通用户看得懂下一步；字段错误、请求编号、重试/返回入口完整且不泄露内部信息
UAT-033	在表单、审批、付款结果和凭证生成中连续点击、并发编辑、后退和关闭页签	写按钮防重复且幂等；409 不覆盖他人修改；未保存内容有提示；服务端结果返回前不显示虚假成功
UAT-034	使用 production 构建打开 PAGE-01～PAGE-21，并检查包体报告、浏览器 Console、Network、Storage	满足 11.11 包体预算；无控制台错误/未处理 Promise/外部请求/Mock；除允许的非敏感 UI 偏好外无业务或敏感持久化；所有业务按钮命中同源真实 API
UAT-035	检查 frontend/ 源码、依赖、OPS-* 逐项操作合同、FE-GATE-{gitCommit}.json 和 production 构建	只有一个 Vue 入口、一个 Starter 布局体系、一套本地路由/菜单权限链路和 TDesign UI 组件库；ECharts 例外符合白名单；每个可见操作可追到 operationId、权限/状态、审计和测试证据；未新增平行前端工程、第二套后台模板、第二 UI 库、iframe 拼装或直接修改 node_modules

每条 UAT 在执行前必须补齐并冻结：fixtureId、前置主数据和版本、执行账号/身份/数据范围、操作步骤、预期页面/HTTP/业务状态、关键字段和金额断言、下游对象断言、审计事件、截图/录像/日志/导出文件证据及验收人。执行结果记录代码版本、数据库迁移版本、浏览器版本、时间和请求编号；只写“通过”而没有可复查断言和证据不算验收记录。

13.1.1 PAGE-14 模块验收记录（2026-08-11）

本记录是 PAGE-14 的本地模块级验收，不替代 OA-05/OA-08 来源表单、三档桌面 Chrome/Edge、正式证据包和整套 R1 的最终 UAT。

时间口径：本节的 6/6、4/4、47/47、“10 个 Testcontainers 集成测试类”和 Flyway V017 均是 2026-08-11 PAGE-14 历史验收快照，不是当前全仓测试数量或最高迁移版本。当前全库最高迁移为 V067，当前验证状态见 13.1.2～13.1.8。

自动化与构建结果

检查项	结果	主要覆盖
ReceivableIntegrationTest	2026-08-11 快照：6/6 通过	收款/发票状态与财务事件、登记/确认 SOD、核销上限和版本冲突、多收多应收、开票复核 SOD、重复红冲、合同超额、重复发票号/流水号、项目身份越权
FinanceOperationsIntegrationTest	2026-08-11 快照：4/4 通过	合同台账和合同执行报表按红冲净额统计：原票 RED_LETTERED 计正数，关联 RED_LETTER 计负数
全量后端	2026-08-11 快照：./mvnw test 47/47，Failures=0、Errors=0、Skipped=0，BUILD SUCCESS	当时 10 个 Testcontainers 集成测试类均从空 MySQL 迁移到 V017，同时回归 IAM、项目、来源审批、主数据、文件、付款、记账和工作台
前端	npm run build、npm run build:type、PAGE-14 定向 ESLint、npm run stylelint 通过	Vue 类型、production 构建、PAGE-14 脚本规范和全仓样式规则
当前全局质量状态	Starter/旧演示源码已清理，全仓 npm run lint、Vitest、release build、source/dist hygiene 及合同驱动 Chromium 三档 Playwright + axe 基线通过	真实 API 关键动作、Edge、键盘路径、异常状态矩阵及正式 FE-GATE 证据仍归 TODO-S1-023/028、TODO-S5-018～021 收口

真实浏览器业务链

步骤	操作与人员分离	页面/数据库结果
1	finance 财务身份创建开票草稿并提交	开票业务号 INV-01KZPZCP928XRVSFVNZS3VRT7C 进入 REVIEWING
2	demo 财务身份复核通过；随后登记人工开票结果	发票号 VAT-R1-UAT-20260811-001，申请进入 ISSUED，保留复核意见和结果人员
3	系统处理开票结果	自动生成应收 AR-01KZPZKQ7BMFRS783K5QZSX711 和对应财务事件，合同台账已开票显示 1,000.00
4	一名财务人员登记收款，另一名财务人员确认并核销到具体应收	收款 RCPT-01KZPZ0YWZ1SWE71BCXGT3TK4C，流水号 BANK-R1-UAT-20260811-0708；已核销 1,000.00，未分配 234.56，状态 PARTIALLY_ALLOCATED
5	刷新列表、详情抽屉和合同台账	列表、详情、应收余额、允许动作和合同金额均从服务端重读并保持一致，无手工改库步骤

视觉和交互检查

• 桌面 1440×900：列表、筛选、分页、详情抽屉和操作按钮无页面整体横向溢出，关闭按钮可用。
• 补充移动视口 390×844：工具栏和抽屉操作按钮自动换行，无页面整体横向溢出；移动端不因此纳入 R1 正式支持范围。
• 审核意见、发票号码、开票日期、作废原因和红冲原因均有前端必填校验；发票详情中的编辑/提交可正确分发；写操作后已打开抽屉不再保留旧状态。
• 该次（2026-08-11）本地验收数据库为 MySQL 8.4、Flyway V017；后端和前端均通过真实 HTTP/Session/CSRF 交互，不使用 PAGE-14 Mock。

模块结论：PAGE-14 标记为 MODULE_ACCEPTED；UAT-011/UAT-012 的页面内财务处理部分已有证据，OA-05/OA-08 来源表单自动生成、正式附件上传操作、三档桌面 Chrome/Edge 和标准证据包仍由对应 S2/S5 任务补齐，不把这些全局事项误报为已完成。

13.1.2 PAGE-13 模块验收记录（2026-08-13）

本记录固定 PAGE-13 合同与成本台账的模块级结论，不替代 PAGE-15、S3 聚合任务、三档 Chrome/Edge 证据包或整套 R1 的最终 UAT。

自动化与数据库结果

检查项	结果	主要覆盖
后端定向与全量测试	FinanceOperationsIntegrationTest、ReportingIntegrationTest 及后端全量 97/97 通过	同人登记/确认拒绝、异人确认、权限范围、金额分列、额度预占、OA 类型/状态/版本/公司/项目约束、重复来源和报表回归
前端门禁	TypeScript、ESLint、Stylelint、Vitest 10/10、production build 全部通过	TDesign 页面类型、样式、机器合同和生产构建
Flyway/MySQL	MySQL 8.4 空库顺序执行 V001～V035 成功，本地库 V034→V035 升级成功	新权限/SOD 种子、历史空来源兼容、非空来源唯一索引

真实页面与运行环境

• 前端 http://127.0.0.1:3002、后端 http://127.0.0.1:18082，后端健康状态为 UP，数据库为 MySQL 8.4/Flyway V035。
• 在已展开的合同详情中，“登记应付”显示 OA-04 来源审批单，TDesign 下拉只显示当前项目已批准 OA-04；“登记结算”同理只显示 OA-11。
• 在其他必填项齐全时不选来源，前端分别显示“请选择已批准的 OA-04 来源审批单”和“请选择已批准的 OA-11 来源审批单”；本次验收未提交业务单据。
• 默认桌面视口和 1440×900 无页面整体横向溢出、按钮重叠或 Console error/exception；768×900 台账宽表格会产生横向滚动，该尺寸不是 R1 正式支持视口，不影响模块结论。
• 两张临时 OA 验收来源及其版本/审批实例已按外键顺序全部删除，应付和结算引用计数均为 0。

模块结论：PAGE-13 标记为 MODULE_ACCEPTED，TODO-S3-007 标记完成；TODO-S3-015 因 PAGE-15 未完成仍保持未勾选，S3 仍为 IN_PROGRESS。

13.1.3 PAGE-15 核心付款链阶段验收记录（2026-08-13）

本记录证明 PAGE-15 核心付款链、OA-06 来源约束、成本类型附件技术能力、并发余额控制、独立逐笔资金台账和例外申请/复核/消费机制已经可执行；正式矩阵尚未确认发布，本记录也不替代正式三档浏览器证据包或整套 R1 UAT，因此 PAGE-15 仍为 IN_PROGRESS。

自动化、构建与数据库结果

检查项	本轮结果	主要覆盖
付款集成测试	MySQL 8.4/Testcontainers 下 PaymentIntegrationTest 18/18，Failures=0、Errors=0、Skipped=0	付款主链、部分支付/失败/退汇/重付、附件范围、幂等、权限范围/金额、余额/合同/应付/账户/重复/风险阻断、结果 SOD、OA-06 约束、同项目并发余额竞争，以及成本类型附件缺件/文件状态/V1→V2 快照/历史兼容/旧请求早失败/矩阵外类型/发布保护
并发余额证据	项目可用余额 1,000 元，两笔 600 元付款由两个财务会话同时批准；结果恰好一笔 200、一笔 422 FUNDS_INSUFFICIENT，最终冻结额 600 元	修复重复资金控制行上的锁升级死锁；资金行在余额检查前按统一顺序取得排他锁，不超支且不返回非预期 500
例外机制证据	PaymentIntegrationTest 覆盖精确/近似重复分级、DUPLICATE 与 PROJECT_RISK 申请、异人审批、7 天有效期、过期换版、发现指纹变化阻断、批准时一次性消费、附件“不涉及”复核消费和硬控制拒绝	正式附件矩阵仍需 D-02/D-09 确认；未确认规则不会因测试例外而自动发布
共享资金回归	MySQL 8.4/Testcontainers 下 ReceivableIntegrationTest 7/7，Failures=0、Errors=0、Skipped=0	收款模块复用的资金控制行创建/更新路径保持可用，收款确认、核销与相关金额控制未因锁顺序调整回归
测试夹具修复	多版本 OA 来源清理前先解除待删版本间的 previous_version_id，再按外键顺序删除	避免第二个及后续测试在 BeforeEach 因自外键失败；修复后同一测试类全量通过
Flyway/MySQL	测试容器从空库顺序执行 V001～V036 成功，本地库从 V035 升到 V036 成功	V036 三列规则快照可空，历史付款无回填阻断；完整矩阵种子保持 DRAFT
前端门禁	PAGE-15 定向 ESLint、Stylelint、TypeScript 和 production build 通过	TDesign 页面脚本、样式、类型和生产构建；主 chunk 约 1.38 MB 的全局预算问题仍未解决
运行健康	后端 http://127.0.0.1:18082/actuator/health 为 UP，前端 http://127.0.0.1:3002/finance/payments 返回 200	真实 Java/MySQL 与 TDesign 页面可访问
独立资金台账	PaymentIntegrationTest.fundLedgerTracksReservedAndPaidAmountsAndEnforcesProjectScope 覆盖冻结、支付、幂等重放、重复来源、查询和数据范围；2026-08-15 在独立 18087 + MySQL 8.4 查询 P-DEMO-001，返回控制余额 500.00、流水总数 1，且 OpenAPI listFundLedger 门禁通过	证明逐笔记录和查询链路可用，不替代 PAGE-15 正式三档浏览器和甲方证据包

OA-06 规则与真实页面证据

场景	已验证结果
错误表单类型	选择 OA-04 创建付款草稿返回 422 VALIDATION_FAILED
未审批来源	选择 DRAFT OA-06 返回 422 VALIDATION_FAILED
合法来源	同公司、同项目、当前版本已批准的 OA-06 可保存草稿
批准前版本变化	草稿选中合法来源后，把来源切换到未批准的新当前版本，付款批准返回 422 INVALID_STATE_TRANSITION，付款保持 REVIEWING，检查项 SOURCE_APPROVED=BLOCK
TDesign 选择器	财务身份打开“新建付款申请”，选择 C-DEMO-001/P-DEMO-001 后，OA-06 下拉只显示临时已批准来源 OA06-PAGE15-UAT；选择后正确回显，未保存草稿
视觉与控制台	当前桌面视口内弹窗字段、下拉和操作区无重叠；Console 无 warning/error
数据清理	临时付款及其检查/附件、OA-06/OA-04 来源、文档版本和审批实例已按外键顺序删除，复查计数均为 0

成本类型附件技术证据

场景	已验证结果
规则发布保护	V036 完整矩阵含 allowNotApplicable=true，治理 API 返回 422 VALIDATION_FAILED；更新为不含例外的测试矩阵后可正常发布
页面与输入	生效规则随应付成本分类返回；TDesign 弹窗逐项显示齐全/缺失/文件检查中，每个附件选择矩阵内资料类型；同一文件不能充当多个资料
缺件与文件状态	缺少送货单返回 ATTACHMENT_REQUIRED；送货单仍在扫描返回 FILE_REJECTED；检查记录保存具体缺失/未通过资料名称
规则快照	V1 保存草稿后发布 V2，再提交和批准仍按付款自身 V1 快照通过；V2 新付款缺少新增资料时被阻断
历史兼容	矩阵发布前创建且无快照的旧付款继续按通用附件规则批准；矩阵生效后的新请求若仍使用 attachmentFileIds，在保存时明确返回 VALIDATION_FAILED，不会拖到批准阶段
真实运行	本地库最高版本 V036，完整矩阵仍为 DRAFT；财务身份真实登录、进入付款页和打开新建弹窗正常，1331×632 视口无整体横向溢出，Console 无 warning/error

剩余模块阻断

1. TODO-S3-011：代码、迁移、页面和测试已具备按成本类型检查附件的能力，但 D-02/D-09 未确认正式必需项，完整矩阵保持 DRAFT，因此尚未形成可签字的业务规则验收。
2. 正式业务矩阵仍未由 D-02/D-09 确认；含可不涉及项的正式矩阵继续在发布入口硬阻断，已实现的例外机制只对经确认并发布的规则生效。

阶段结论：TODO-S3-008/009/010/012/013/014/016/017 标记完成；TODO-S3-011 记录为技术能力已验证、正式业务矩阵待确认发布；TODO-S3-015 继续等待 PAGE-15 模块级验收。PAGE-15 不标记 MODULE_ACCEPTED，S3 和整套 R1 均继续为 IN_PROGRESS。

13.1.4 PAGE-18/19 本地阶段验收记录（2026-08-13）

本记录用于固化本轮已完成的实现和定向验证，不是甲方签字的正式 UAT。表中 DEV-FIXTURE-* 是本地可重建场景编号，不是第 13.1 节要求的已冻结正式 fixture；因临时数据和独立验证实例未作为交付物保留，本记录只保留稳定断言，不编造对象 ID、请求编号或截图路径。

验证环境与构建

检查项	本轮结果	证据边界
后端编译	Java 21 下 Maven compile、test-compile 通过	证明主代码和测试代码可编译，不代替集成测试执行
前端门禁	TypeScript、ESLint、Stylelint、Vitest 10/10 和 production build 通过	Vitest 当前主要覆盖机器合同和工作台 URL 白名单；主 chunk 约 1.38 MB，仍超过 11.11 节预算
数据库/服务	MySQL 8.4，Flyway 已成功迁移到 V032；当前后端 http://127.0.0.1:18081 健康检查为 UP，前端 http://127.0.0.1:3002 可访问	PAGE-18 扫描器不可用路线使用独立非 local 验证实例；临时数据未保留在当前主库
2026-08-13 历史 Testcontainers 环境	FileIntegrationTest、ArchiveIntegrationTest、ReportingIntegrationTest 当时未进入断言	当时本机无 /var/run/docker.sock；该历史环境结论不代表 2026-08-15 本轮专项状态
2026-08-15 增量环境	MySQL 8.4，Flyway V065；PAGE-16 收口包后端 http://127.0.0.1:18092 健康为 UP，配套前端为 http://127.0.0.1:3009	保留既有联调服务不动；本轮 3009 → 18092，OpenAPI 从 18092 重导并通过合同门禁，页面与 CSRF 代理请求成功，不替代甲方正式签字

PAGE-18 隔离文件来源闭环：DEV-FIXTURE-PAGE18-SCANNER-UNAVAILABLE-20260813

步骤	操作	已验证结果
1	以有 archive:file:upload/view 权限和公司/项目数据范围的资料身份上传文件，使扫描器返回 UNAVAILABLE	HTTP 返回 503 FILE_SCANNER_UNAVAILABLE；系统保留唯一 QUARANTINED file_object
2	查询隔离文件的范围链接、PAGE-18 列表和资料工作台	只存在一条带当前公司/项目范围的 file_link；GET /api/v1/archive/files?scanStatus=QUARANTINED 可查到唯一文件，allowedActions=[]；工作台隔离数量为 1
3	以相同 Idempotency-Key、相同 metadata 和相同字节重放	仍返回同一 503，不再执行上传，file_object/file_link 均仍只有一条；幂等记录为 COMPLETED 且 response_status=503
4	以相同幂等键改变文件内容	HTTP 返回 409 IDEMPOTENCY_KEY_REUSED，不新增文件
5	在“替换旧版本”或“关联档案项”语义下上传隔离候选	隔离候选不 supersede 旧的可用版本，不把档案项状态更新为 PRESENT

PAGE-18 重扫与借阅归还闭环：DEV-FIXTURE-PAGE18-RESCAN-BORROW-20260815

步骤	操作	已验证结果
1	对 file_object=01M020G47BNE5N6X3EN3VH0S7J 在扫描器不可用时上传并建立范围链接	页面显示 QUARANTINED 和“重新扫描”；文件绑定公司/项目范围，不成为无范围孤立文件
2	扫描服务恢复后由资料身份在 PAGE-18 点击“重新扫描”	页面转为“可用”并恢复预览、下载、上传新版本和借阅；数据库为 scan_status=AVAILABLE、promotion_storage_key=NULL，正式文件存在、隔离源不存在
3	核验失败恢复、幂等和审计	FileIntegrationTest 7/7 通过，覆盖 503/200/422 重放、扫描不重复及移动后数据库提交失败恢复；ARCHIVE_FILE_RESCAN/SUCCESS 恰好一条
4	archive / ARCHIVE_MANAGER 对该文件提交借阅申请	生成 BOR-20260815-RRD4H4GB，状态 APPLIED，审计 ARCHIVE_BORROW_APPLY/SUCCESS
5	finance / FINANCE_MANAGER 批准申请	申请人与审批人不同，状态进入 BORROWED，审计 ARCHIVE_BORROW_APPROVE/SUCCESS，符合职责分离
6	archive / ARCHIVE_MANAGER 登记文件完好归还	最终状态 RETURNED、版本 2，记录审批人、归还人和归还说明；审计 ARCHIVE_BORROW_RETURN/SUCCESS
7	检查页面和证据	浏览器 Console 无 warning/error；重扫、批准和归还截图分别为 docs/evidence/r1/archive-rescan-1366x612.jpg、archive-borrow-approved-1366x768.jpg、archive-borrow-returned-1366x768.jpg

PAGE-19 两阶段导出：DEV-FIXTURE-PAGE19-TWO-PHASE-EXPORT-20260813

步骤	操作	已验证结果
1	查询具有两行结果的报表，向 POST /api/v1/reports/{reportCode}/exports/prepare 提交当前筛选、列、排序、filter hash 和口径版本	返回 PREPARED、estimatedRows=2、冻结列/排序/筛选 hash/过期时间/脱敏说明；此时 export_log 未新增
2	在 Chrome 打开 TDesign 导出确认框	页面显示预计行数、冻结排序、筛选快照和脱敏说明，用户确认前不生成导出记录
3	向 POST /api/v1/reports/{reportCode}/exports/confirm 提交 exportId 和 maskingConfirmed=true	服务端重新校验用户、身份、权限范围指纹、口径、筛选、列、排序和预计行数；返回 COMPLETED，仅新增一条 export_log
4	校验返回 CSV 和记录的文件哈希	CSV 内容的 SHA-256 与响应及 export_log.sha256 一致，记录行数为 2
5	对同一 exportId 再次确认	HTTP 返回 409 VERSION_CONFLICT，不重复生成文件或导出记录

尚未满足的正式验收条件

1. PAGE-18 的本地重扫、借阅批准和归还正向链已补齐；仍需固化可重放的正式 fixture，在 Docker/Testcontainers 中补拒绝、逾期、重复操作、无权预览/下载、水印与范围变化后的全分支证据。
2. PAGE-19 还需甲方冻结 D-08，统一六类报表日期口径，导入可计算流程时长的真实样本，并在 Testcontainers 中覆盖范围缩小/撤销、筛选变化、预计行数变化、过期、重复确认和附件跨范围拒绝。
3. PAGE-18/19 均还需按 13.1 节保留正式 fixture ID、账号/身份/数据范围、完整请求编号、Chrome/Edge 三档桌面截图或录像、Network/Console/数据库/审计日志和导出文件。Chrome 本轮未捕获到 Blob download 事件，只能证明确认页面无错和后端确认成功，不作为正式下载证据。

阶段结论：PAGE-18 的“扫描器不可用产生无范围孤立隔离文件”、可恢复重扫和异人借阅/归还正向链已闭环；PAGE-19 的正式两阶段导出已实现并通过 MySQL 8.4 全量集成回归。两页状态均维持 IMPLEMENTED_PENDING_ACCEPTANCE，TODO-S4-011～TODO-S4-015 全部保持未勾选；PAGE-18 在正式负向 fixture、Playwright/axe、Chrome/Edge 三档证据和甲方签字完成前，PAGE-19 在 D-08、日期口径、真实时长样本和正式桌面证据包完成前，均不得升级为 MODULE_ACCEPTED。

13.1.5 OA-04/05/08 来源审批投影专项记录（2026-08-14）

本记录固化本轮 Java/MySQL 实现和运行态证据，不替代三档桌面浏览器 UAT、正式业务矩阵签字或整套 R1 交付。

范围和输出

来源表单	财务终审事务输出	后续人工动作	明确不做
OA-04 人材机应付	fin_payable.status=CONFIRMED；锁定合同额度、写入含税发票汇总、建立唯一 PAYABLE 会计事件	PAGE-13 查询和付款链继续消费已确认应付	不接网银/U 盾、自动付款或第三方接口
OA-05 项目收款	fin_receipt.status=CONFIRMED；更新项目资金控制、追加 fund_ledger、建立唯一 RECEIPT 会计事件	PAGE-14 继续做暂收分配和应收核销	不接银行流水、网银或自动对账
OA-08 发票申请	带 source_document_id/source_version_id 的 DRAFT 开票候选	PAGE-14 提交、异人复核、人工登记发票结果，再生成应收和 INVOICE 会计事件	不接电子发票平台、自动开票或税务系统

运行态验证

• SourceWorkflowIntegrationTest：MySQL 8.4/Testcontainers 从空库顺序迁移到 V052，25/25 通过，Failures=0、Errors=0、Skipped=0。
• 后端全量：154/154 通过，Failures=0、Errors=0、Skipped=0；V051MigrationIntegrationTest 显式迁移到 target("51") 后通过。
• 覆盖：模板 v2、来源版本一致性、公司/项目/客户/供应商/合同归属、OA-04 合同额度和附件金额、OA-05 客户失效回滚、OA-08 客户快照失败回滚及多个在途候选累计额度预占、同幂等键重放不重复、审批任务/来源状态/下游对象/台账/会计事件的原子回滚。
• Java compile、test-compile，前端 TypeScript、定向 ESLint、Vitest 36/36 和 production build 均在本轮重新执行并通过。

迁移和发布门禁

• 当前最高 Flyway 版本为 V067。本节来源投影专项仍以 V052 为当时历史快照；V051 对历史发票重复来源、缺少当前版本或多版本来源执行阻断式预检，V051MigrationIntegrationTest 已固定以 target("51") 验证被测迁移，不受后续迁移影响。
• V050 的历史收款来源在升级前仍须执行同等重复/版本预检；存在历史来源记录时，先完成逐笔版本映射和业务清数，再运行 Flyway，禁止通过删除唯一约束或强行取当前版本绕过门禁。

未清零事项

1. OA-08 已审批候选退回后的“来源更正→新版本→重新终审”闭环尚未完成；当前实现禁止直接编辑或作废来源候选，正式 UAT 前必须补齐更正路径，或在业务决策中明确退回只回到来源表单。
2. OA-04/05/08 的三档 Chrome/Edge 页面证据、正式 fixture、截图和甲方签字仍未完成，因此本专项状态为 IMPLEMENTED_PENDING_ACCEPTANCE，不升级 PAGE-14 或整套 R1 的交付结论。

13.1.6 PAGE-01～21 Chromium 三档可访问性与溢出门禁（2026-08-15）

本记录是合同驱动的开发门禁，不替代真实 Java/MySQL 业务动作、正式 Chrome/Edge 人工截图、键盘全路径或甲方签字。测试从 frontend/contracts/routes.json 读取 PAGE-01～21，按每页首个授权身份和权限构造稳定会话，并以空态或最小详情 fixture 隔离后端数据波动。

检查项	结果	固定断言
Playwright 项目	chromium-1366、chromium-1440、chromium-1920	视口分别为 1366×768、1440×900、1920×1080
页面矩阵	21 pages × 3 viewports = 63/63 通过	每页合同标题或业务对象标题可见，document.scrollWidth <= clientWidth
axe	63/63 通过	WCAG 2A/2AA 中 impact 为 critical/serious 的违规为零
浏览器日志	63/63 通过	console.error 和未捕获 pageerror 均为零
既有前端门禁	Vitest 9 files / 50 tests、全仓 ESLint、TypeScript、Stylelint、release build 通过	production hygiene 扫描 114 个 source、94 个 dist 文件通过

本轮由门禁发现并修复：侧栏图标按钮缺少名称、菜单 ul/li 被无语义 div 打断、分页跳页输入缺少名称、登录/版本/面包屑/空态/状态标签对比度不足、个人中心缺少页面一级标题和身份列表语义错误、PAGE-10 使用不存在的 t-date-time-picker、报表阻断提示色对比度不足。对应实现位于 frontend/src/layouts/components/SideNav.vue、MenuContent.vue、src/composables/useTDesignAccessibility.ts、src/style/、个人中心、动态表单和报表页面；自动门禁位于 frontend/playwright.config.ts 与 frontend/e2e/accessibility.e2e.ts。

剩余边界：本轮 fixture 不提交业务命令，不覆盖弹窗/抽屉的所有长数据状态，也不证明 Edge、键盘焦点、Network/Storage、401/403/404/409/422/500 和逐按钮真实 API。以上继续由 TODO-S5-018～021 和 UAT-030～035 收口，不因 63/63 通过把整套 R1 标记完成。

13.1.7 PAGE-11/12/16/17 专项与完整浏览器回归记录（2026-08-15）

本记录覆盖当前完整 Playwright 开发回归和 PAGE-11/12/16/17 后端专项，不替代真实 Chrome/Edge 正式 UAT、键盘全路径、异常状态矩阵、正式 fixture、外部样例或甲方签字。

检查项	本轮结果	证据边界
完整 Playwright	npx playwright test 111/111 通过，耗时约 6.4 分钟	覆盖 PAGE-01～21 三档路由/axe/溢出门禁及 PAGE-09/10/11/12/16/17 定向行为；PAGE-11 增加筛选和列表最新详情退回，PAGE-12 覆盖部门创建、提交、复核、停用和版本差异，PAGE-16 覆盖结果冲销/重开及历史证据；不据此把整套 R1 标记完成
PAGE-11 查询合同专项	SourceWorkflowIntegrationTest#workflowTaskListSupportsProjectArrivalOverdueStatusSortAndKeyAmount 1/1 通过	覆盖项目、到达日期、逾期、状态、排序、关键金额和范围合同；正式业务 UAT 继续按既有任务收口
PAGE-12 部门主数据专项	MasterDataIntegrationTest 8/8、FinanceOperationsIntegrationTest 10/10、PAGE-12 三档行为测试 3/3 通过	覆盖部门重复编码、列表/详情、编辑、提交、同人复核拒绝、异人复核、版本冲突、停用、5 条版本快照、分页、项目身份 403、快照动作清洗和双版本字段差异；V064 已完成旧编号映射，完整异常矩阵和正式 UAT 仍待完成
PAGE-16 人工记账结果专项	AccountingIntegrationTest#completedResultCanBeReversedAndReopenedWithoutLosingHistory 1/1 通过；完整 AccountingIntegrationTest 18/18 通过；PAGE-16 三档专项 12/12 通过	覆盖 COMPLETED → RESULT_REVERSED → EXPORTED、冲销/重开独立权限与金额/数据范围、登记人/冲销人/重开人 SOD、空白理由拒绝、版本、幂等重放与同键异载荷、分轮证据、历史外部凭证号唯一和审计；正式外部导入样例与甲方证据包仍待完成
PAGE-17 财务确认/归档门禁专项	ProjectIntegrationTest#financeConfirmationIsRequiredBeforeArchiveGenerationAndUsesScopeVersionAndAudit 1/1 通过	覆盖未确认阻断、权限/范围/版本/审计和确认后生成；正式 Chrome/Edge 全流程和异常 fixture 仍待完成
Testcontainers/Flyway	后端全量 208/208 连接 Colima MySQL 8.4；另以定向集成测试从空库成功执行 69 个迁移至 V069	证明当前完整迁移链和各模块业务断言；不替代 staging 升级预检、备份恢复或正式性能测试

PAGE-16 全类回归曾暴露测试证据文件路径硬编码与应用 finance.storage.root 不一致；夹具已改为注入并使用同一 FileStorageProperties。冲销/重开收口又补齐当前轮次响应、去空格后有效理由校验、重开金额上限及两命令同键异载荷断言，最终 18/18 通过。上述调整没有放宽生产下载接口的文件存在性、路径边界或权限检查。

阶段结论：工程实现估算更新为约 95%。PAGE-11、PAGE-12、PAGE-16、PAGE-17 的本轮新增主合同已形成自动化证据，但相关页面仍未完成所有正式 UAT 和甲方签字，状态不得升级为整套 R1 已交付。剩余开发/内部验证与甲方协同验收的时间口径以 0.5 节为准。

13.1.8 第一版 Preview 发布工程验收记录（2026-08-16）

本记录证明当前提交可形成第一版 Preview 候选包和可回归的安装/更新框架，不替代甲方业务规则确认、真实服务器首次安装、正式域名/HTTPS、Chrome/Edge UAT、备份恢复演练或最终签字。

检查项	本轮结果	证据边界
后端全量	最近完整 Maven/Testcontainers 基线 208/208 通过，Failures=0、Errors=0、Skipped=0；本轮项目生命周期改动已通过 test-compile、新 JAR 启动和真实 MySQL 8.4 API 查询	当前机器无可用 Docker/Colima，新增断言的 Testcontainers 复跑停在容器启动前；当前空库迁移链共 69 个版本并到达 V069
前端工程	ESLint、Stylelint、TypeScript、production build/hygiene 通过；Vitest 9 files / 53 tests	前端固定为现有 TDesign Vue Next Starter，不引入第二 UI 框架
浏览器回归	Chromium 三档完整 Playwright 183/183、四种身份真实 Edge 登录 PAGE-01～21 冒烟 21/21 通过	含 PAGE-07 筛选/导入/导出、PAGE-08 已完成记账生命周期与反向返回、PAGE-10 动态附件并发与保存校验、PAGE-13 应付登记/确认、PAGE-14 发票退回更正、PAGE-15 付款结果附件、PAGE-18 借阅审批/归还、PAGE-20 审计和 PAGE-21 更新恢复状态；不替代正式 Edge 全操作矩阵及甲方 UAT
合同与供应链	OpenAPI、Actionlint、ShellCheck 通过；npm 完整依赖树 0 vulnerabilities	CI 仍在 tag 发布时从干净环境重新执行全部门禁
更新可靠性	成功切换、健康失败回滚、Release 下载失败、mysqldump 失败和不安全请求拒绝五类夹具通过	覆盖持久 processing/transaction、普通文件门禁、有效失败状态、0600 备份、应用、updater、systemd、Nginx、新旧健康验证和失败 Release 清理；真实 Linux systemd 主机仍须冒烟
Release 制品	1.0.0-preview.1 应用 tar、RSA 3072 签名 manifest、公钥、SHA-256 清单、安装器、前后端 CycloneDX SBOM 统一生成并互相绑定；签名清单同时绑定应用、SBOM、安装器、公钥、bootstrap 摘要和源码修订，Maven、npm、JAR、SBOM 与 manifest 严格同版本，tag CI 强制干净来源	应用包 SHA-256=45c44070b4b0857f202ea5767441f684bdda28095276e0ea1c75cd31dcddf39b，安装器 SHA-256=bf50b8ca0fcd1aebf2c05f0d80fa362a482f46ecf6e07f7cf5aa5d05d6370c21，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9；当前本地候选清单明确为 source.ref=local、source.dirty=true，实际 Git Release 仍待目标仓库
Linux 32 位	安装器 fixture 验证 i386/i486/i586/i686 均选择 Java 17 i686 JRE；外部 MySQL 8.4.x 先做连接、版本、DDL/DML 预检	属于“外部数据库已预置后的单命令安装”，不是 32 位主机内置 MySQL；正式 i686 systemd 主机仍须实装

Preview 放行结论：代码和本地签名制品满足第一版 Preview 候选条件，P0 代码阻断为零。实际对外 Release 只剩目标 GitHub 仓库、Release URL、CI 签名 Secret、公钥指纹 Variable 和服务器地址等部署输入；这些输入未配置前，不把本地候选包描述成已经公网部署。

13.1.9 OA-06 付款投影验收记录（2026-08-16）

本记录补充 13.1.3 的付款主链证据，证明 OA-06 财务终审能够原子形成待线下付款及资金占用；它不代表银行付款、第三方执行或 PAGE-15 正式业务矩阵已经验收。

检查项	本轮结果	验收结论
模板与引用	V070 发布 OA-06 v2，增加生效合同、供应商和已确认应付引用，并建立来源文档/版本成对约束	付款不再依赖合同号、供应商名等易变文本关联
成功链	真实 HTTP 来源单 01M04RDPY0V03B6VV53PE9X12B 财务终审后生成付款 01M04RFRWM14NMJAMDA9YPR1M1；状态为 OFFLINE_PENDING，申请/批准/冻结金额均为 100.00，项目可用余额从 500.00 降至 400.00	来源审批、付款记录、资金冻结和 PAYMENT_FUNDS_RESERVED 流水在同一事务内完成
失败回滚	真实 HTTP 来源单 01M04RH7HM00SGSJQEE3EY46P3 因余额不足返回 422 FUNDS_INSUFFICIENT；表单保持 FINANCE_REVIEW、任务保持 PENDING，新增付款数为 0，冻结和流水均未增加	投影失败不会留下已批准来源、孤立付款或错误资金占用
自动化回归	后端全量 209/209，Failures=0、Errors=0、Skipped=0；PaymentIntegrationTest 29/29，来源审批专项 37/37；MySQL 8.4 Testcontainers 从空库执行 70 个迁移到 V070	OA-06 正常链、资金不足回滚、付款并发余额控制和迁移约束均纳入当前回归基线
接口合同	最新 OpenAPI 为 205 个 paths、286 个 schemas，check-openapi.sh 通过	OA-06 继续使用元数据驱动表单与既有审批/付款接口，不新增第三方接口
范围边界	系统仅生成待线下付款记录，后续由人员登记结果并异人复核	不接网银、U 盾、税务系统、第三方权限/API、RPA 或自动执行

阶段结论：OA-06 自动付款投影达到第一版 Preview 技术放行条件；PAGE-15 仍因正式附件矩阵、三档浏览器证据和甲方业务确认保持 IN_PROGRESS。

13.1.10 第一版 Preview V070 候选包重建记录（2026-08-16）

本记录在 13.1.8 历史候选之后，以包含 V070/OA-06 付款投影的最新工作区重新生成本地签名候选包；13.1.8 中的旧摘要继续作为当时快照保留。

检查项	本轮结果	证据边界
构建	Maven 以 revision=1.0.0-preview.1 生成 JAR 和后端 SBOM，前端 npm ci 后完成 TypeScript、Vite release build 与 production hygiene	工作区仍为未提交本地候选，manifest 明确记录 source.ref=local、source.dirty=true
独立验签	verify-release.sh 对应用包、两份 SBOM、manifest、RSA 签名、公钥、安装器和 bootstrap 清单全部返回 OK，RSA 签名验证为 Verified OK	可信公钥指纹由部署方固定，不从待验 Release 动态信任
最新摘要	应用包 SHA-256=e8ba2a7b1f9badbadfdaf5ee786fd981b86a2cacd41def250a9fe2bfd9d163d2；安装器 SHA-256=bf50b8ca0fcd1aebf2c05f0d80fa362a482f46ecf6e07f7cf5aa5d05d6370c21；公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9	README 的当前候选摘要同步为本记录；正式 tag Release 仍须在干净 checkout 中由 CI 重建并发布
本地 Preview 切换	后端 http://127.0.0.1:18095 运行 JAR 1.0.0-preview.1 并返回 UP；日志确认 MySQL 8.4、70 个迁移校验通过、schema 为 V070；前端 http://127.0.0.1:3014 代理 /api/v1 到 18095	这是本机预览入口，不等同于公网 GitHub Release 或生产部署
最终真实浏览器冒烟	Edge 完成财务登录、财务工作台、OA-06 待线下付款详情及 8 项付款检查、记账列表、项目归档、管理员登录和系统更新状态检查；系统配置页显示当前版本 1.0.0-preview.1，页面 Console warning/error 为 0	在线更新因未配置正式 Release 地址显示“未启用”，符合当前部署边界
部署脚本回归	i386/i486/i586/i686 Java 17 选择与外部 MySQL 8.4 预检夹具通过；在线更新成功、健康失败回滚、下载失败、数据库备份失败和不安全请求拒绝夹具通过；ShellCheck、Actionlint 均通过	正式 Linux i686/systemd 主机实装仍属于正式版部署验收，不阻断本机第一版 Preview

候选结论：包含 V070 的本地签名制品已经通过独立验签并完成本机第一版 Preview 切换；当前 Preview Goal 完成。正式 GitHub Release 留待仓库地址、CI Secret、Variable 和服务器输入到位后执行。

13.1.11 私有 Gitea 两阶段在线更新与 Preview.2 验收记录（2026-08-16）

本记录以当前实现取代 13.1.8～13.1.10 中关于“后续再确定 GitHub 更新源”的旧方案；旧小节仅保留为当时历史快照。生产更新源固定为私有 Gitea Release，不在服务器执行 git pull、切换源码分支或现场编译。

检查项	本轮结果	证据边界
固定更新源	Git remote 已绑定 https://git.awaioi.com/ERP-Team/kaidi.git；生产读取 https://git.awaioi.com/api/v1/repos/ERP-Team/kaidi/releases/latest，资产 URL 必须与 API 的 scheme、host、port 完全同源	页面不能修改更新地址、Token、脚本或命令；生产只读 Token 与 Gitea Actions 发布权限分离
分阶段交互	管理员点击“获取版本”只检查发布信息；发现新版本后点击“立即更新”才下载。下载、RSA 验签、SHA-256 和压缩包检查完成后进入 READY/下载完成，业务服务在下载阶段不停机；只有 READY 状态才能显示“立即更新并重启”并提交安装	检查、下载、安装的忙碌状态互斥，防止重复排队；未经“立即更新并重启”确认不切换版本
安装与页面恢复	安装阶段重新验签、备份、原子切换并执行后端直连、Nginx、更新 path unit 和静态首页健康检查；成功后页面倒计时 10 秒自动刷新，安装中刷新或短暂断线会恢复 3 秒轮询；失败自动恢复并复验上一版本	10 秒是页面刷新等待，不延迟服务端安装；真实 Linux systemd 主机仍须执行发布后冒烟和备份恢复演练
凭据保护	Token 只从权限 0600 的 root 配置/Token 文件读取，curl 通过临时 Header 文件使用；认证请求不跟随重定向，Token 不进入进程参数、页面、状态 JSON、审计参数或日志	Token 轮换时必须同步更新 /etc/kaidi/kaidi.env 和 /etc/kaidi/update.env
接口与自动化	OpenAPI 为 206 paths / 287 schemas；后端全量 211/211，Vitest 53/53、完整 Playwright 183/183、更新专项 Playwright 15/15 通过；ShellCheck、Actionlint、安装、更新和 Gitea draft/恰好 9 资产/发布 fixture 通过	更新专项覆盖下载确认、安装弹窗、10 秒刷新、安装中刷新恢复、禁用状态和失败可见性
Gitea 发布原子性	tag 工作流先创建 draft=true, prerelease=false 的 Release，显式上传并核对恰好 9 个签名资产的名称、数量和大小，全部一致后才发布；失败或资产不齐时 /latest 不可见	还需在 Gitea 配置 RELEASE_SIGNING_KEY_B64、KAIDI_RELEASE_PUBLIC_KEY_SHA256 和可用的 ubuntu-24.04 act_runner
Preview.2 制品	1.0.0-preview.2 已完成构建及独立验签；应用包 SHA-256=180168d4481044d3803eef81a88b301642a55cb5519e50401915e1cc131e10c7，安装器 SHA-256=6a881dcfd5476e795a6e181f8a8b234184523478f20312a669c6748889be1288，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9	当前清单绑定 revision 47403fd337cfd4544e45d6c851984e4a40bcd8f3、source.ref=local、source.dirty=true；正式 tag Release 必须从干净提交重新构建，摘要将以 CI 输出为准
本地 Preview.2	签名包内 JAR 在 http://127.0.0.1:18095 返回 UP，前端 http://127.0.0.1:3014 代理真实 API；系统管理员登录后，系统配置页显示当前版本 1.0.0-preview.2 和完整四步更新面板，页面无横向溢出，Console warning/error 为 0	本地未注入生产只读 Token，因此页面显示“在线更新未配置”；这证明禁用态，不替代真实 Gitea 下载和 Linux 安装冒烟

阶段结论：后台更新页面、Java 更新接口、root 执行器、签名制品和私有 Gitea 发布链已形成完整 Preview 框架。代码侧 P0 阻断为零；正式对外 Release 仍以“干净源码提交、Gitea Actions 配置完成、tag 工作流成功、真实 Linux 首装/更新冒烟”作为放行条件。

13.1.12 V071 超级管理员全权限与 Preview.3 验收记录（2026-08-17）

本节是当前有效基线；13.1.8～13.1.11 继续保留为当时的历史快照。SYSTEM_ADMIN 仍是独立、隔离的管理员身份，但不再局限于系统治理：它拥有系统内全部真实功能权限、全部业务页面和全局数据范围，不需要兼任项目、财务或档案角色。

检查项	本轮结果	继续强制的边界
权限与范围	V071 逐条授予全部 iam_permission，并为管理员账号建立无金额上限、无失效时间的 GLOBAL scope；启动同步会补齐后续新增权限。运行库实测总权限 173、管理员角色权限 173、管理员有效全局范围 173	不在数据库、API 或前端使用 * 通配符；禁用账号、禁用角色和会话失效继续生效
页面与菜单	超级管理员可进入 PAGE-04～21，展开后可见工作台、项目管理、表单审批、财务管理、资料档案、查询分析和系统治理全部菜单；页面直链和按钮不再被旧的治理角色判断隐藏	页面权限放行不替代后端业务校验；所有正式写操作仍由 Java 服务重新检查对象状态、版本和业务约束
跨人员业务管理	管理员可查看和管理跨人员表单、导入批次、付款草稿、收款/发票草稿、项目、财务对象和档案对象；PAGE-15 默认提供“全部付款”视图	通用未关联文件继续执行上传人隔离；已关联业务文件按对象权限和范围受控下载
全局工作台	项目工作台显示全部进行中项目和全部待处理；财务工作台显示全部待处理及全局资金概览；资料工作台显示全部档案包、缺件和借阅数据。运行态真实 Edge 已看到跨人员项目、1 条他人待办、全局资金和跨人员档案	“可查看待办”不等于“可冒充处理人”；审批动作仍要求当前节点角色和实际 assignee
职责分离	管理员可查看全部审批任务，但对分配给其他人的审批动作返回 403；凭证、付款结果、主数据、收款、开票、应付和档案的异人复核继续执行	不提供跳过 SOD、节点处理人、状态机、幂等、乐观锁、合同/应付/资金余额、附件安全或审计的超级按钮
自动化回归	后端 MySQL 8.4/Testcontainers 213/213，Failures/Errors/Skipped 均为 0，71 个迁移从空库到 V071；Vitest 10 files / 56 tests，完整 Playwright 192/192；TypeScript、ESLint、Stylelint、production build/hygiene 均通过	Preview 自动化通过不替代第 12.9 节正式 UAT、恢复、性能、培训和甲方签字
Preview.3 制品	1.0.0-preview.3 已独立构建并验签恰好 9 个资产；应用包 SHA-256=18178889ff905e1f6741e23b7e6fc2738dd34c7ca930d1015541adf379641239，安装器 SHA-256=6a881dcfd5476e795a6e181f8a8b234184523478f20312a669c6748889be1288，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9	当前本地清单绑定 revision 47403fd337cfd4544e45d6c851984e4a40bcd8f3、source.ref=local、source.dirty=true；正式 tag Release 必须从干净提交重新构建
本地 Preview.3	前端 http://127.0.0.1:3014、后端 http://127.0.0.1:18095；管理员 admin / LocalOnly@123。JAR 显示版本 1.0.0-preview.3，健康端点为 UP，Flyway 为 V071；真实 Edge 核验系统配置、三类工作台、全部付款和审计页面，Console warning/error 为 0	本地固定密码只用于当前开发机；生产首次安装生成随机密码。当前未注入生产只读 Token，因此在线更新面板显示“未启用”

本轮结论：原先“系统管理员只有系统治理权限”的角色模型已废止。当前模型是“独立超级管理员 + 全部功能权限 + 全局数据范围 + 不可绕过的业务控制”，既解决管理员看不到业务模块的问题，也避免管理员冒充审批人或绕过资金与职责分离规则。

13.1.13 统一页面面包屑与 Preview.4 验收记录（2026-08-17）

检查项	本轮结果	固定边界
面包屑来源	Breadcrumb.vue 直接读取 routes.json 注入的页面合同层级；PAGE-03～21 统一显示从一级模块到当前页面的中文面包屑，不再按 URL 临时猜测标题	菜单、路由、页签和面包屑继续共用同一页面合同，不新增第二份页面名称配置
静态页面内容头	工作台、列表、台账、财务、档案、报表、审计和系统配置页删除内容区重复的模块名、页面名及介绍说明；保留读屏可识别的隐藏 h1，刷新、新建、导入、导出等动作保留在右侧紧凑工具栏	项目详情和表单详情继续显示业务编号、动态对象名称与状态；这些信息不与静态面包屑重复，不能删除
页面回归	TypeScript、ESLint、Stylelint、Vitest 10 files / 56 tests、production build/hygiene 通过；页面层级专项 Playwright 66/66、完整 Playwright 192/192 通过，覆盖三档桌面分辨率、全部 PAGE-01～21、超级管理员逐页访问、无整体横向溢出及无 serious/critical WCAG 违规	后续新增静态页面必须同时满足“合同面包屑可见、仅一个读屏 h1、无可见重复静态标题”的自动门禁
真实浏览器	Edge 中项目工作台只显示“工作台 > 项目管理工作台”后直接进入指标区；付款页只显示“财务管理 > 进度款与付款”及操作栏；按钮、页签、筛选和表格无重叠，Console warning/error 为 0	路由页签继续承担多页面切换，不在内容区再次复制页签标题
Preview.4 制品	1.0.0-preview.4 已独立构建并验签恰好 9 个资产；应用包 SHA-256=9d6b5d62838eee1c40dd40235e5159876b3c9a410ef40dc7a3d8e42619164f84，安装器 SHA-256=6a881dcfd5476e795a6e181f8a8b234184523478f20312a669c6748889be1288，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9	当前本地清单绑定 revision 47403fd337cfd4544e45d6c851984e4a40bcd8f3、source.ref=local、source.dirty=true；正式 tag Release 仍必须从干净提交重新构建
本地 Preview.4	前端 http://127.0.0.1:3014、后端 http://127.0.0.1:18095，管理员 admin / LocalOnly@123；JAR 为 1.0.0-preview.4，健康端点为 UP，Flyway 为 V071	固定密码只用于本机 Preview；生产首次安装生成随机管理员密码

13.1.14 Preview.5 响应式布局与独立更新页验收记录（2026-08-17）

项目	结果	说明
Preview.5 制品	1.0.0-preview.5 已独立构建并验签恰好 9 个资产；应用包 SHA-256=5291975cfee7f42f13ed331ee8ba2eb42a8b83fbee488d2d59d21cc5ac0a7848，安装器 SHA-256=6a881dcfd5476e795a6e181f8a8b234184523478f20312a669c6748889be1288，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9	清单绑定 revision 47403fd337cfd4544e45d6c851984e4a40bcd8f3、source.ref=local、source.dirty=true；正式 tag Release 仍必须从干净提交重新构建
本地 Preview.5	前端 http://127.0.0.1:3014、后端 http://127.0.0.1:18095，管理员 admin / LocalOnly@123；JAR 为 1.0.0-preview.5，健康端点为 UP，Flyway 为 V071	PAGE-21 为权限与配置，PAGE-22 为系统更新；更新页显示当前版本、获取更新、立即重启和历史更新记录
布局专项	工作台异常项自适应高度；窄屏取消强制横排；记账事件编号/类型列单行省略；更新步骤在 640px 及以下切换纵向；左上角和页脚品牌统一为“财务系统”	1440px、390px 实测无整体横向溢出或文本重叠

本轮结论：页面名称现在只在顶部合同面包屑中可见一次，业务内容区直接进入指标、页签、筛选和数据；动态详情仍保留识别当前业务对象所必需的信息。

13.1.15 Preview.6 移动端固定列与顶部栏验收记录（2026-08-17）

项目	结果	说明
窄屏固定列	已修复	390px 权限与配置表曾出现左侧编号列与右侧操作列相互覆盖；统一在 640px 及以下取消 sticky 定位和阴影，保留 TDesign 表格横向滚动，新增几何回归断言覆盖同一行矩形交叠
顶部栏长文本	已修复	账号显示增加 min-width: 0、最大宽度和省略号，窄屏压缩操作区，不再因长姓名挤压页面或操作按钮
真实浏览器	通过	Edge 390px 复测权限与配置、系统更新、财务管理工作台和记账准备；文档 scrollWidth == clientWidth，事件编号/类型保持分列，更新步骤和操作栏无重叠；1440px 复测仍保留桌面 sticky 列
自动化	通过	Vitest 10 files / 56 tests、完整 Playwright 198/198、TypeScript、ESLint、Stylelint、production build/hygiene 均通过；新增测试为 mobile settings table fixed columns do not overlap
Preview.6 制品	已验签	1.0.0-preview.6 应用包 SHA-256=b59268fc3e8e9ffa44bf1be293fa7c61385d05f0e9ca640b5fa037eb79598a7c，安装器 SHA-256=6a881dcfd5476e795a6e181f8a8b234184523478f20312a669c6748889be1288，公钥 SHA-256=807c6aec1dc3f7ce494db16aa9d763c66f292033c38f328afd0390d2715a8cd9

本轮结论：Preview.6 修复了可复现的手机端固定列覆盖问题，同时保持桌面端表格体验和现有在线更新签名信任根不变。远程 Gitea 尚未创建对应 Release 前，安装器和更新页仍按“暂无可用版本”运行；发布 v1.0.0-preview.6 后即可由同一公钥链承接更新。

13.1.16 Preview.8 首次安装向导与 32 位部署验收记录（2026-08-17）

项目	结果	说明
首次访问	已实现	KAIDI_SETUP_WIZARD=true 时正式业务 DataSource、Flyway、JDBC Session 和业务路由不启动；GET /api/v1/setup/status 在无业务数据库时返回 required=true，前端 /setup 为未登录公共页
数据库配置	已实现	首版只开放 MySQL 8.4.x；向导先执行版本和临时表 CREATE/INSERT/UPDATE/DROP 权限验证，再执行 72 个 Flyway 迁移；非空且无 Flyway 历史的数据库被拒绝
管理员初始化	已实现	操作者填写账号、显示名称和密码；创建 SYSTEM_ADMIN、逐项全局权限范围，并用 kaidi_setup_installation 单例状态支持提交后重试，避免重复创建超级管理员
锁定与恢复	已实现	一次性安装码只保存 SHA-256；完成后原子写运行时环境和锁定标记，systemd 重启进入正式模式；向导未完成时可用 REINSTALL=true + KAIDI_SETUP_WIZARD=true 恢复并重新生成安装码，已锁定/正式模式拒绝该路径
32 位 curl	已实现	i386/i486/i586/i686 只下载 i686 Java 17 JRE，不传数据库密码；管理员预建 MySQL 8.4 数据库后在 /setup 输入连接信息
自动化证据	通过	Java compile、SetupContextSmokeTest、安装器/ Git 包装器 fixture、TypeScript、PAGE-23 Playwright（390px）均通过；Testcontainers 完整迁移回归在无 Docker 主机上标记为 skipped，发布 runner 必须提供 Docker

本轮结论：Preview.8 具备可部署的首次安装和 32 位向导框架；生产录入安装码、数据库密码和管理员密码前必须先配置 HTTPS 反向代理或可信内网隧道，HTTP 仅用于隔离 Preview 验证。

13.1.17 Preview.27 安装跳转与内容区导航收敛记录（2026-08-18）

项目	结果	说明
安装完成跳转	已修复	完成安装后以 required=false 且 locked/ready 状态确认服务已切换，再通过 Vue Router 进入 /login；不再等待永远为 false 的 setup ready 标志，也不再复用安装前缓存的 required=true 状态
面包屑	已删除可见渲染	菜单和路由页签已经表达层级，业务内容区不再显示“表单审批 → 表单中心”等重复导航；历史 breadcrumb 合同字段仅保留作元数据，不生成 DOM
内容区留白	已收紧	移除面包屑占位和底部间距，页签下内容区顶部间距固定为 16px；列表、工作台和配置页直接进入操作栏/指标/查询区
自动化证据	通过	TypeScript、ESLint、Stylelint、Vitest 12 files / 60 tests、安装向导 Playwright 6/6、全量页面可访问性与布局 Playwright 78/78、production build/hygiene 均通过

本轮结论：业务页面不再把菜单层级重复显示为面包屑；安装完成后会稳定进入登录页，异常重启场景也通过状态确认后自动跳转。

13.2 第三方权限和自动化负向验收

当前状态：PENDING_EVIDENCE。以下五项是发布前必须执行并归档的负向验收，不代表当前已经完成；证据包须记录代码/依赖/配置扫描、断网运行、人工登记审计断言、执行时间、版本和可复查结果。

必须提供以下证据：

1. 代码和配置中没有 OA/T+/网银/税务/HR 业务连接器、账号、Token、私钥或证书。
2. 工程中没有定时业务任务、RPA、自动付款、自动申报、自动缴税或自动过账入口。
3. 运行环境默认拒绝财务业务公网出口，核心流程不依赖外部接口；唯一可选例外是系统管理员启用的固定 HTTPS Release 更新通道，该通道不传输业务数据且不能由页面改址。
4. T+、银行、发票和税务外部结果均由用户人工登记并留痕。
5. Starter 默认公网 API、远程 Logo/图片、注册入口、演示路由和生产 Mock 已清除，生产前端不依赖任何外部静态资源。

13.3 非功能验收

类别	验收要求
安全	密码哈希、HTTPS、CSRF、最小权限、字段脱敏和安全文件下载通过测试
完整性	唯一键、版本、外键、状态机和金额规则在后端及数据库同时控制
审计	正式数据、审批、导入导出、敏感查看和结果登记可还原前后值
性能	常用列表/详情 P95 小于 2 秒；无超付、重复事件或重复凭证
文件	类型/大小/病毒/哈希检查通过；数据库和文件关系一致
备份	MySQL 和文件卷可恢复，业务链和 SHA-256 校验一致
易用性	三类用户不培训也能从各自工作台找到待办、项目和常用入口
前端一致性	PAGE-01～21 使用锁定的 TDesign Starter 布局、组件、Token、图标和页面模板；不存在第二套视觉体系
前端稳定性	三档办公分辨率无重叠/截断/整体横向溢出；Loading、空态和 HTTP/业务错误均有确定状态；Console 无错误
浏览器兼容	发布时最新两个稳定大版本的桌面 Chrome、Edge 通过主流程；不支持环境进入明确的不兼容结果页
可访问性	Playwright + axe 的 critical/serious 问题为零；键盘可完成登录、查询、录入和审批主操作；焦点可见；图标按钮有中文名称；状态不只靠颜色表达
运行边界	production 前端无 Mock、演示数据、外部静态资源和公网请求，核心流程在断网环境仍可使用

13.4 缺陷放行标准

• P0 缺陷：影响核心流程、金额、权限、数据丢失或安全，必须清零。
• P1 缺陷：影响常用操作或明显降低可用性，R1 正式验收前必须清零。
• P2 缺陷：显示、文案或低频体验问题，可进入后续版本。

13.5 需求到开发和验收的追溯

需求范围	页面	Java 模块	主要开发阶段	主要验收
F-01～F-04 身份与三类工作台	PAGE-01～06	iam、project、archive	S1	UAT-001～003、024
F-05～F-07 主数据、14 表单和审批	PAGE-07～12	project、masterdata、source、workflow	S2	UAT-004～010、026
F-08 合同与成本	PAGE-08、12、13	masterdata、contractcost	S2～S3	UAT-006、013～014
F-09 收款与发票	PAGE-14	receivable	S3	UAT-011～012
F-10 进度款与付款	PAGE-15	payment	S3	UAT-013～016、027
F-11 记账准备	PAGE-16	accounting	S4	UAT-017～019、027
F-12 资料归档	PAGE-17～18	archive	S4	UAT-020～022
F-13 查询和导出	PAGE-08、19	reporting	S4	UAT-023
F-14 审计与配置	PAGE-20～21	audit、iam	S1、S4	UAT-003、022、024、027
F-15～F-16 银行对账和税务准备	无 MVP 页面	本期不开发	后续单独立项	负向验收 13.2
全页面 TDesign 与前端运行规范	PAGE-01～21	frontend、全部接口模块	S1～S5	UAT-028～035

14. 最终交付清单

14.1 软件交付物

• Java 17/Spring Boot 完整源代码和构建脚本。
• 前端源代码和静态构建产物。
• TDesign Starter 上游仓库、基线提交、MIT 许可证和 THIRD_PARTY_NOTICES.md。
• MySQL Flyway 全量迁移脚本和初始化字典。
• 可部署 Jar、签名 Release、Linux 一键安装/在线更新脚本、版本号、SHA-256 清单和前后端 SBOM。
• OA-01～OA-14 模板、字段字典，以及成功、必填失败、重复、越权四类脱敏 fixture。
• 记账导出模板和人工结果登记模板。
• 演示数据和试点迁移脚本。

14.2 文档交付物

本文件是唯一的需求、开发和交付总文档；其他材料作为证据附件保存，不再要求甲方阅读多份相互跳转的 PRD/SPEC。

此外随软件交付：

• 安装部署说明。
• 数据库和文件备份/恢复操作说明。
• 用户操作手册：项目、财务、资料、管理员四个版本。
• API/OpenAPI 文档。
• 数据字典和错误码清单。
• 测试报告、性能报告、安全扫描报告和 UAT 记录。
• 发布记录、已知问题和后续版本清单。

14.3 培训和交接

培训对象	培训内容	要求
项目管理人员	新建项目、填写表单、补件、看进度	能独立完成一条立项和付款申请
财务管理人员	财务审核、额度/附件检查、结果登记、记账准备	能独立完成一笔收付款和记账准备
资料管理人员	档案包、缺件、归档、检索和借阅	能独立完成一个项目归档
超级管理员	全部业务页面、用户、角色、模板、字典、备份、日志和在线更新	能查看全局数据、管理跨人员草稿/导入、配置系统并完成恢复演练；理解审批处理人和 SOD 仍不可绕过

15. 开发前必须由甲方确认的事项

这些不是让甲方重新描述整个需求，而是开发团队拿着样例和选项请甲方签字。D-01～D-11 仍须形成书面结论；开发已启动不表示可以边开发边猜规则。未确认事项阻断其影响到的模块验收，并统一阻断整套 R1 发布和最终验收。

决策编号	要确认的具体内容	负责人	最晚确认节点	未确认时的处理
D-01	首期公司、项目、用户、三类业务身份和独立系统管理员账号名单	甲方负责人	相关账号/范围模块验收前	阻塞受影响模块验收和整套 R1 发布
D-02	按 9.3.1 展开的 14 类表单最终字段、必填条件、枚举、附件矩阵和下游映射	甲方业务/财务	OA 模板验收前	阻塞受影响模块验收和整套 R1 发布
D-03	三种来源下各表单的项目/财务/资料节点、处理人、退回点和时限	甲方业务/财务	流程模块验收前	阻塞受影响模块验收和整套 R1 发布
D-04	项目余额、冻结金额、负余额和一次性例外规则	财务负责人	资金/付款模块验收前	阻塞受影响模块验收和整套 R1 发布
D-05	合同、付款、收款、发票金额阈值及等于/超过阈值时的审批路线	财务负责人	财务金额模块验收前	阻塞受影响模块验收和整套 R1 发布
D-06	供应商、合同、项目和来源单据唯一编码/去重规则	甲方业务/财务	主数据/来源模块验收前	阻塞受影响模块验收和整套 R1 发布
D-07	记账导出文件样例、列/编码/金额规则和人工结果字段	记账会计	PAGE-16 验收前	阻塞 PAGE-16 验收和整套 R1 发布
D-08	六类报表样式、公式、日期口径、权限和下钻路径	财务负责人	PAGE-19 验收前	阻塞 PAGE-19 验收和整套 R1 发布
D-09	文件类型、大小、病毒处理、业务文件/验收证据包保管期、纸质位置、“不涉及”规则和到期处置	资料负责人	文件/档案模块验收前	阻塞受影响模块验收和整套 R1 发布
D-10	用户量、数据量、服务器规格、备份位置及 RPO/RTO	甲方 IT	性能/部署验收前	阻塞 S5 和整套 R1 发布
D-11	系统正式名称、甲方 Logo/版权文字、品牌主色及可使用范围；确认 TDesign 风格不等于使用腾讯商标	甲方负责人/品牌负责人	品牌/production 验收前	阻塞 production 发布；确认前只使用临时文字和 TDesign 默认主色，不使用腾讯 Logo

16. 风险和处理方式

风险	表现	处理方式
用户看不懂	一次展示太多模块和专业词	三类工作台、角色化导航、先用一个项目演示
需求方说不清规则	口头回答前后不一致	用表单样本、页面原型和可选项签字，不问空泛问题
14 表单字段变化	OA 表单后续改列	模板版本化，旧数据保留原版本
金额口径争议	项目余额、已批未付不一致	公式和状态时点由财务签字，报表可下钻
账号权限混乱	一人兼任多个岗位	登录后选身份，后端仍做数据范围和 SOD 检查
资料不完整	付款或归档时缺附件	附件矩阵、退回补件和“不涉及”复核
外部系统阻塞	没有 OA/T+/银行/税务权限	固定采用人工导入、导出和结果登记
数据迁移质量差	编号重复、金额不一致、附件缺失	分批试导、错误清单、三方核对和冻结期初
Starter 风格漂移	开发人员混用其他组件库、复制新主题或每页自行设计	以 11.2 节为代码评审清单，UAT-029～034 逐页核验，偏离项不得合并
Starter 依赖漏洞	底座可构建但当前依赖审计仍有高危项	S1 删除 Mock 依赖并升级/替换问题链路；严重/高危清零后才可进入 staging
Starter 上游变化	后续 develop 更新造成组件、路由或构建不兼容	固定提交和 lockfile；按任务选择性合并并跑完整回归，不自动追随上游
Starter 初始包体偏大	当前原始构建入口 chunk 触发 Vite 大分块警告	S1 删除演示页，路由和 ECharts 按需加载；CI 执行 11.11 包体预算，不调高警告阈值绕过
品牌理解偏差	把“腾讯样式”误做成使用腾讯 Logo、名称或完全照搬演示页	只采用 TDesign 规范，甲方品牌按 D-11 确认，本地资源替换全部演示品牌

17. 名词解释

专业词	一般人可以这样理解
主数据	大家反复使用的基础资料，例如项目、供应商、合同和账户
财务事件	一笔需要进入财务处理的事实，例如确认收款、确认应付或付款完成
凭证草稿	系统根据业务先准备好的记账建议，仍要会计检查
幂等	同一个按钮点两次，也只产生一条有效数据
乐观锁/版本冲突	两人同时修改时，不让后保存的人把前一个人的结果覆盖掉
SOD/岗位分离	同一件事不能一个人从申请做到付款、复核和记账
数据范围	某个人能看哪家公司、哪些项目
SHA-256	文件指纹，用来判断文件是否被替换或改变
下钻	从汇总金额点进去查看每一笔明细和原始依据
P95	100 次请求里至少 95 次要在目标时间内完成
RPO/RTO	最多能接受丢多少数据、系统出故障后多久恢复

18. 资料依据

本方案基于以下已复核资料和现有需求整理稿：

1. 腾讯会议_20260805_153007(4).docx 会议转写与 AI 总结，SHA-256：3d499330d9246634c65de7a21871511ee6840c7afdb3a8f3d10759805740ec8d（已复核）。
2. OA审批表单及数据采集(1).zip 中 14 张 OA 表单图，SHA-256：4da7896acd4b7c6620532f455c2a640b25af6b53657848e241f38d62541e98f6（已从微信正式文件目录找回并逐张复核）。
3. 财务各岗位职责(1).zip 中 12 份 Excel 岗位资料，SHA-256：60f171126cf2c76c6ba2a90572eeea8c9192df992da309ff7e56980d775dbce4（已从微信正式文件目录找回并完成文件名及关键职责复核；原件含敏感访问信息，须受限保管）。
4. 33b3fa6087e4c7840474112218845097.jpg 项目管理流程图（本次冻结核验时原始路径不可读取；流程节点以会议转写和现有整理稿为临时基线，D-03 前需补可视化原图或书面确认）。
5. 前期财务需求规划、PRD 和 Java 技术规格中的有效规则。
6. Tencent/tdesign-vue-next-starter 官方 GitHub 仓库，基线提交 1f183fa089d07183235dc69dbd76b8b2c4a6d8bb（2026-08-07 核对）。
7. 2026-08-10 后续项目决策：现有 TDesign Vue Next Starter 为唯一前端实现基线；第一轮交付第 12.9 节定义的完整 R1；该日项目仍处于开发文档和规范冻结阶段。
8. 2026-08-11 最新执行决策与仓库事实：R1 已进入开发；PAGE-14 按 8.15.1、11.6.3、11.7.3.1 和 13.1.1 完成模块级验收；该事实不改变第三方/自动化排除项，也不降低整套 R1 DoD。

资料可复核性规则：会议 DOCX、OA 压缩包和岗位压缩包已经按上述哈希建立本轮复核基线；后续替换原件必须重新计算哈希并记录差异。项目管理流程图仍缺失，在补图或 D-03 书面确认前，不得把具体跨部门节点和处理人推定为已确认。原图/岗位表未明确的必填条件、枚举、金额公式、审批人、时限、附件是否必需和下游映射仍须通过 D-01～D-09 与脱敏样本签字；否则受影响模块不得验收，整套 R1 不得发布。含账号、密码、证书、银行介质和身份证/银行卡全文的原件只在受限资料区保存，不进入仓库、字段样本、截图、日志或验收证据包。

19. 最终产品定义

首期最终产品不是“完整 ERP”，而是：

一套面向项目管理、财务管理和资料管理三类人员的项目财务基础系统。它把 14 类业务表单、内部审批、收款、发票、成本、付款、记账准备和项目档案串成一条可追溯数据流，在不接入第三方权限、不执行网银/税务/记账自动化的前提下，先解决甲方最急迫的基础财务管理和资料查询问题，并为后续功能扩展保留清晰边界。