fix: 完善动态错误指引与发票日期校验（09-05-error-explainability-payment-readiness）
这个提交包含在：
@@ -18,6 +18,17 @@ QA script patterns over new abstractions.
|
||||
|
||||
## Common Checks
|
||||
|
||||
### Payment Account And Invoice Read Errors
|
||||
|
||||
- Payment-account maintenance and invoice-pool read validation use registered
|
||||
`payment_account.*` and `invoice_pool.*` reasons. Keep HTTP status, top-level
|
||||
error code and legacy detail fields; add `reasonCode` rather than changing
|
||||
permissions, queries or transaction order to make validation pass.
|
||||
- Invalid input and unavailable references must fail before successful writes,
|
||||
audit or notifications. Retain masked-account behavior and never echo input
|
||||
bank accounts in error messages. Reason registry, client mapping and exact
|
||||
message fixtures change together; remove only the migrated AST baseline entries.
|
||||
|
||||
### Receipt OCR Matching Service Boundary
|
||||
|
||||
- Failed evidence persistence is not OCR failure. In a separate bounded transaction,
|
||||
@@ -187,9 +198,30 @@ Wrong: treat a notice count or pending-batch aggregate as the complete finance w
|
||||
domain-scoped `details.reasonCode`; do not infer business identity from a
|
||||
details key alone. The builder rejects unregistered reasons.
|
||||
- **迁移一条遗留原因码 = 服务端注册 + 客户端映射 + 具体内容断言，三项缺一不可。**
|
||||
Dynamic guidance requires an additional payload test containing both reasonCode
|
||||
and its legacy details (missing fields, retry timestamps, failed policy rules).
|
||||
A reason-only fixture cannot prove preservation of actionable details. Project
|
||||
only allowlisted fields for that reason; malformed or cross-domain details must
|
||||
fall back safely instead of bypassing the registered message contract.
|
||||
Fixed expected text lives in `server/tests/unit/fixtures/error-reason-messages.json`
|
||||
and is asserted against both registry and client rendering; do not replace
|
||||
these assertions with broad message regexes or expectations derived at runtime.
|
||||
- Authentication explanations must retain the same `auth.code_invalid_or_expired`
|
||||
reason for missing, inactive, locked and wrong-code accounts; do not introduce
|
||||
account-enumerating recovery messages or include submitted secrets in errors.
|
||||
- Invoice verification availability is distinct from OCR availability. Explain a
|
||||
disabled verification gate without claiming OCR is disabled or enabling either
|
||||
provider. Invalid or duplicate requests must not enqueue work or write records.
|
||||
- Workflow input-error migration preserves parsers, permission order and transaction
|
||||
boundaries. Invalid comments, task identifiers and batch requests must fail before
|
||||
business transactions; changing error metadata does not authorize state-machine edits.
|
||||
- Invoice date-only input must survive UTC date round-trip unchanged. Reject invalid
|
||||
timestamps and calendar overflow (including non-leap February 29) before updates
|
||||
or audits; JavaScript Date construction alone is not calendar validation.
|
||||
- Preserve pre-existing actionable top-level API messages when migrating a reason.
|
||||
Use a fixed registered builder call, retaining legacy details/status and then the
|
||||
original message if necessary; do not bypass the AST gate with direct AppError
|
||||
literals or dynamic, unvalidated reason names.
|
||||
- Legacy entries are versioned AST-shape SHA-256 fingerprints plus relative file/operation,
|
||||
occurrence count, owner, explanation and expiry date (UTC). Whitespace, quotes,
|
||||
indentation, trailing commas and parenthesization must not change identity.
|
||||
|
||||
@@ -1,5 +1,67 @@
|
||||
# Implementation Plan：错误可解释性与付款就绪治理
|
||||
|
||||
## R1内容复核处置（R2修订，未提交/部署）
|
||||
|
||||
R2结果：`npm test -- tests/unit/scripts/error-reason-client.test.js tests/unit/routes/auth.login.test.js tests/unit/routes/workflow.transfer.test.js tests/unit/routes/invoicePool.patch.test.js`四文件311/311（244条客户端契约）；typecheck与vite build退出0。修订后visual-portal.spec.ts实际22/22零重试，含新增财务两段href和BX/PB均消失。日志/tmp/followup-r2-unit.log、typecheck/build/browser同前缀；不是R1的471项整批重跑。
|
||||
|
||||
`RUN_ISOLATED_DB_TEST=1 RUN_BROWSER_TEST=1 RUN_JOB_QUEUE=1 RUN_ERROR_GUIDANCE_TEST=1 node scripts/qa/test-invoice-first-http.cjs`通过PASS_ERROR_GUIDANCE_REAL_AUTH_DB_BROWSER：真实密码登录/JWT、实际发票PATCH携原因码与missingFields、页面显示发票代码/销售方缺失、失败保留ocr_failed，补齐后数据库和页面均变available。fixture是隔离库预置ocr_failed，不声称本次由OCR产生；mock provider无真实云调用。原invoice-ocr-flow全套seed用例本轮未原样运行，其对应修正子流程由此专项覆盖。隔离数据库/合成存储已清理，浏览器及临时preview均关闭，生产未接触。
|
||||
|
||||
外部新会话结论有条件通过，未执行测试；包完整性另已核，不能合并成独立运行验收。F1/F2按阻断修复：客户端仅对三个已注册原因投影其允许的动态字段，再复用原文案分支；无动态数据保留注册fallback，不将其他域details带入递归。OCR字段/密码策略使用已知清单，时间只接受有效UTC时间戳，不直接回显未知payload。补同时带reasonCode与真实legacy键的精确内容测试，以及未知/跨域details不泄露反例；invoice-ocr-flow原断言改为实际缺失两字段的完整文案。
|
||||
|
||||
F3登记未修债务：共享utils/date日期解析及报销/差旅/资产/付款消费者仍需逐模块审查严格日历校验；本次只修发票的局部函数，不能据此声称共享解析安全。归本任务后续日期输入批次，负责人shunli，09-25复审时给出消费者矩阵、拒绝溢出/闰日/月末/null/时区边界、无写入回归及历史异常只读盘点方案；不改历史记录、不混进本次R2的阻断修复，不延长错误豁免日期。
|
||||
|
||||
F4已修：转审输入原因文案同步注册/客户端/固定夹具为10至500字；转审实际守卫未变。F5补财务两段href断言和刷新后BX/PB均消失断言，旧R1表格超出当时实际断言的部分以复核结论为准，新增断言重跑后另记。F6批量逐条错误不携reasonCode登记后续投影债务，不破坏已有跳过键；F7密码登录的401/403/423为既有可区分设计，本次防枚举声明仅适用于邮箱验证码/重置链，不扩称全部登录路径。
|
||||
|
||||
R1包及其manifest不变；本轮代码已偏离R1，必须重冻R2后交增量复核。471/27/22是R1记录，不能冒称本次输入通过。
|
||||
|
||||
## 2026-09-15 第三阶段连续收口（本地实施与单元/构建验证通过，未提交/部署）
|
||||
|
||||
最终本地结果：19文件471/471通过（/tmp/followup-stage3-tests.log），其中包含发票上传/编辑/选票/文件/查验/差旅关联、七份workflow路由回归、门户、回单独立复核、auth/me/付款账户及237条客户端原因契约。命令为`cd server && npm test --`后逐个传入上述日志首行登记的19个测试文件；不是全仓测试，也未发送真实OCR。通知管理/IM路由/dispatcher另轮27/27，不能声称实际通知已发送。`cd client && npm run typecheck && ./node_modules/.bin/vite build`退出0；本轮修改后构建，不复用旧dist。AST229注册/612遗留/零finding、Trellis、process baseline及diff检查通过；docs registry零错误，仍有既有22项未登记告警。浏览器交接测试另记结果。
|
||||
|
||||
到期清单收口：paymentAccounts、auth/me、invoicePool主路由及read/verification/shared-schemas、workflow路由的本批VALID_001均已迁移，不为这些路径保留豁免。剩余591条entries/count612仍由原baseline逐条保留owner及2026-10-05到期；utils/workflow15条涉及路由推导，需独立按流程负例评审，workflowDefinitions11条属配置域，不与本次输入修复混交。其他模块保持原逐项责任与期限；09-25复审、09-30有理由的延期提案、10-02查漏均是计划而非已安排自动任务，不允许统一延期，也不把全部技术债宣称完成。
|
||||
|
||||
按“尽量一次完成、不重复询问”继续原范围：invoicePool主路由与查验查询schema、workflow路由剩余操作级原因迁移。不是全库612条遗留统一改名，不动workflowDefinitions配置域及utils/workflow审批路由算法。当前AST PASS registered229/migrated316/legacy612；本轮开始695，累计减少83次遗留命中。上述目标路由已无遗留命中，领域workflow仍有utils/workflow等15条，不能把路由清零写成全审批域清零。
|
||||
|
||||
发票覆盖上传文件/大小/类型/所属人、修改输入/金额/日期/必填OCR信息、归档、OCR重试和重复例外前置。原PDF专用顶层文案与兼容details保留，原因码走注册builder；不修改OCR默认值、不开启查验、不发送真实发票。审批剩余提示区分已处理、本人不能自审、目标人不可用/不合格、节点异常、业务类型不支持、催办冷却等，守卫条件/顺序/锁/状态不改。
|
||||
|
||||
新增日期负例发现真实缺陷：JS Date会把2月30日滚动为3月，且无效月份可能生成Invalid Date。沿本task发票字段输入校验补有限时间值与UTC日期回读一致性；增加非闰年2月29日、2月30日、4月31日、13月拒绝且无写入，以及真实闰日/月末正例。此项是实际输入验证修复，不冒充纯文案更改；不回填历史日期。
|
||||
|
||||
中途测试发现builder固定通用顶层message，直接替换PDF两处分支会改变旧API文案；已恢复专用文案且保留原因码。静态门禁不接受动态原因码或直接AppError伪迁移，因此分别使用固定注册builder，不修改门禁或增加豁免。最终联合测试、浏览器交接与构建结果完成后补记，不复用中途失败作为通过。
|
||||
|
||||
## 2026-09-15 后续三域实施（当前权威增量，未提交/未部署）
|
||||
|
||||
最终客户端`npm run typecheck && ./node_modules/.bin/vite build`退出0（/tmp/followup-final-typecheck.log、followup-final-build.log），构建包含本节所有34个新增原因映射。保留既有Browserslist/chunk提示，不新加依赖、不把构建成功称为已发布。
|
||||
|
||||
最终同输入回归：`cd server && npm test -- tests/unit/routes/auth.login.test.js tests/unit/routes/me.test.js tests/unit/routes/paymentAccounts.test.js tests/unit/routes/invoicePool.bindable.test.js tests/unit/routes/invoicePool.file.test.js tests/unit/routes/invoicePool.verification.test.js tests/unit/routes/workflow.batch.test.js tests/unit/routes/workflow.transfer.test.js tests/unit/routes/workflow.permissions.test.js tests/unit/routes/workflow.return-notifications.test.js tests/unit/routes/workflow.task-detail.test.js tests/unit/routes/portal.test.js tests/unit/services/paymentReceiptManualReview.test.js tests/unit/scripts/error-reason-client.test.js`，14文件367/367通过，日志/tmp/followup-final-tests.log。覆盖实际客户端错误解析、认证负例与原业务守卫的合成回归，不是公网/browser/真实JWT新验收。AST、node语法、Trellis治理、process baseline、diff检查通过；docs registry零错误，既有22项未登记告警未扩修。
|
||||
|
||||
在已批准D阶段继续完成auth/me、发票查验及审批输入，不另建task。auth/me新增10个原因：输入格式、设备上下文、密码策略、无效内部入口、统一无效验证码及通知设置。缺失/停用/锁定账户与验证码不正确仍返回相同原因，不新增账号枚举；登录、刷新、密码修改与会话事务顺序不变。三条旧测试精确details断言漏加原因码导致初跑失败，修正断言后auth/me连同首批六文件259/259通过，不改业务逻辑绕过测试。
|
||||
|
||||
发票查验新增disabled/already_pending/record_missing三个原因并复用invoice_pool.id_invalid；不是OCR开关变更，不启用查验、不新增云端调用。补不存在查验记录、重复排队与无效标识的无写入/无队列反例；两文件201/201通过（含当时191条客户端契约）。审批迁移七个输入parser：意见、转审输入、任务ID、批量同意/退回、催办与统计范围；权限门、状态机、事务与转审资格不变。七个HTTP输入反例均在事务前拒绝；六文件243/243通过（含当时198条客户端契约），包含既有转审、权限、退回通知及详情回归。
|
||||
|
||||
最终AST检查PASS：registered190、migrated271、legacy656、findings0；基线634条entries/count656，较本轮开始695减少39次AST遗留命中，日期仍全部2026-10-05。不是已经清完656条；保留invoicePool.js30、shared/schemas1、workflow.js13，workflowDefinitions11仍为未启用配置域，不扩改审批状态/资格。这些余项继续按操作与负例迁移，禁止整文件批量替换或统一延期。
|
||||
|
||||
验证日志：/tmp/followup-errors-combined.log、followup-verification-tests.log、followup-workflow-tests.log、followup-final-scan.json。最终同输入合并回归、typecheck/build另记录结果；以上不同轮测试含重叠，不累加宣称独立用例数。没有提交、推送、部署或生产写入；不是独立复核结论。
|
||||
|
||||
## 2026-09-15 第一批实施与验证（未提交/未部署）
|
||||
|
||||
按统一计划实际运行既有AST检查器，修复前PASS：registered156、migrated225、legacy695。第一批仅迁移paymentAccounts与invoicePool/read，不改auth/审批状态机或生产数据。
|
||||
|
||||
付款账户9个原因涵盖账号/银行输入、完整账号查看理由、无效标识、主体/银行不可用、重复银行编码、银行仍被使用、已有账户不能改公司。发票读取5个原因涵盖筛选分页、选票查询、状态批量查询、不可编辑报销、无效票据标识。保留HTTP status、VALID_001和legacy details；客户端真实resolveErrorMessage与固定中文夹具一起验。未修改解密/查看权限、文件授权、状态或付款逻辑。
|
||||
|
||||
移除实际已消除的8条AST豁免，当前665个entries/count687，日期仍全部2026-10-05；新增注册14项，检查PASS registered170/legacy687/findings0。不是只删豁免隐藏旧调用，不把公共helper的一条AST记录当作只有一条业务分支。
|
||||
|
||||
最终同轮四文件207/207通过：paymentAccounts13、invoicePool.bindable新增输入负例及既有行为、invoicePool.file文件授权/审计、error-reason-client178；付款账户反例确保未创建/更新/成功审计/通知且不泄漏合成账号。中途发票测试漏解构prisma导致一项测试代码失败，修正后完整四文件重跑207通过，未改业务逻辑绕过失败。客户端typecheck通过，构建另记结果。原auth/me、发票上传/识别核验主路由和workflow仍待后续批次，未声明本task完成。
|
||||
|
||||
证据安全日志本机/tmp/followup-error-scan.json、followup-error-after.json、followup-error-wave1-tests.log。未新增真实OCR、生产写入或部署，其他任务旧差异继续隔离；下一批仍沿本task操作级范围，不新建任务。
|
||||
|
||||
前端typecheck与vite生产构建最终均退出0，原有chunk体积/Browserslist提示不扩修。node语法、git diff、Trellis治理及process baseline通过；docs registry零错误，保留既有22项未登记文档告警。此轮提示映射由真实客户端resolveErrorMessage测试覆盖，不宣称重跑全部浏览器；权限/状态机未修改。测试/构建日志分别为/tmp/followup-typecheck.log、followup-build.log，产品补丁保持未提交状态。
|
||||
|
||||
## 2026-09-15 统一收口接续
|
||||
|
||||
用户采纳一次规划连续实施，协调入口为09-08-reimbursement-payment-closeout/implement.md“六项统一执行计划”。本task承接D，不新建豁免管理系统。已只读重统计：基线673个entries、count合计695、均2026-10-05到期，距09-15为20天；不是695个当前AST命中或产品缺陷。
|
||||
|
||||
先用既有检查器区分当前命中/已消除/变动指纹，再逐操作处理paymentAccounts、invoicePool已启用上传/读取/识别核验、auth/me、workflow审批动作；workflowDefinitions配置域不自动纳入。每次同时注册安全原因码、客户端映射、具体提示及禁止副作用断言。09-18首批验证、09-25复审、09-30逐模块延期建议、10-02查漏沿用原节点。延期需具体理由、负责人与验收，不在本轮规划中修改expiresOn。范围内本地实现/重验不逐项询问，最终提交/发布范围集中审批。
|
||||
|
||||
## 2026-09-11 到期治理接续（不统一续期）
|
||||
|
||||
本次只读复核现有 AST 基线为 673 条记录，到期仍为 2026-10-05，距 09-11 为 24 天；不是 673 个已证实产品故障。本轮主线修复不改到期日，不重复建立豁免台账。
|
||||
|
||||
在新工单中引用
屏蔽一个用户