hyb-oa/.trellis/tasks/archive/2026-09/09-05-error-explainability-payment-readiness/prd.md

错误可解释性与付款就绪治理

B34 当前验收状态

用户批准接续后，损坏账号导入的限定修复已完成本地合成验证：已复现白名单格式返回固定400提示，未知解析故障继续500且不记录原解析内容；权限、文件限制、合法导入、日期文本与事务保持。最终68项导入加854项原因合同断言通过，前端typecheck/build及原因strict/self-test通过，详见implement最新回执。此结论不等于独立复核、真实导入或上线；下方“尚未实施”保留原时点，D15非阻塞、D16现合同及17 ERP排除不变。

2026-09-17 用户澄清：考勤由企业微信承办

用户明确“考勤功能在企微”。按现行产品规则，打卡、请假、补卡、外出、加班由企微承办；OA 保留月度摘要、异常解释、同步状态及审计，不恢复旧 OA 打卡。此前 D15 是 OA 摘要查询的极低年份技术观测，不是企微考勤故障，也不是新建 OA 考勤的需求。

D15 不列为本轮必须修复或阻塞收尾的项目；原 2000–2100 建议仅为未采纳的技术备选，不再作为等待用户决定的必办项。保留观测和现有代码，不把它记为已修复，也不由此认定所有企微摘要/同步代码均已废弃。B34 账号导入仍为下一本地修复优先项。

2026-09-17 剩余边界确认结果

W6三类余项已完成本地范围确认，产品源码未更改。损坏账号CSV/XLSX在两入口仍返回500且CSV异常可将合成单元格交给日志，列为B34优先修复方案；具体错误白名单、固定安全提示与未知内部异常分流见design。低年份D15将工资待精简路径排除，统一考勤保留入口只读偏移另待接受年份决策。AP反向ledger区间D16保持现有200及有界查询，不作为必须修复项；非法日期/其他区间原拒绝保持。

本轮验收为合成行为证据、在用/排除依据与限定实施方案，不把characterization通过记成缺陷已修复。旧17处ERP排除与原人工复审日期不变；不修改原AC勾选、不提交部署或访问真实数据。

G8按在用路径收口

按implement顶部B31–B33合同处理57处，17处ERP旧分支按用户最新指示跳过并保留源码/基线。其依据为产品设计规则61/89及企微路线图37；通用outbox有notification.im消费者不整文件跳过。当前权限/状态/编号/开关/认证业务规则保持，只本地合成。所有旧材料保护、独立PENDING，不读真实配置密钥/外联/提交部署或实施借款。

G7本地错误合同接续

查询考勤周报八源42处，按implement顶部B29/B30逐操作合同实施；三方固定提示、精确减基线、实际路由/服务负例和合法回归、页面安全消费及保护新候选。legacy考勤硬关闭保持，内部路由用合成门禁桩分层验证；周报项目开关失败前原update尝试保持。独立PENDING，不扩权限/状态规则，原真实数据/外联/提交部署边界不变。

G6验收补充

共享审批工具、流程定义、审批规则和委托仅迁移原错误合同，保留原status/details、角色/自审批/快照/主管链规则及事务副作用位置。明确不可达防御与本地mock边界，另限定修复委托列表有效期OR覆盖本人范围OR的组合缺陷：两者AND同时生效，恢复原有范围而不新增管理权；须有合成数据红绿路由证据。具体操作与验收以implement为准；独立只读复核PENDING。

G5验收补充

延续120处采购/资产/流转盘点/合同与共享预算错误合同治理，仅新增明确原因和固定安全提示，原状态/权限/冻结/附件安全及业务写入顺序保持。具体子批先行合同与进展以implement顶部为准；仅本地合成，不以扫描数代替分支或真实业务验收。

G4差旅验收补充

B19–B21覆盖申请、订单、授权、交易及共享预算和对账错误合同。保留原400/409/details、审批/付款/预算规则、锁/事务、按条导入跳过与幂等、ERP排队门禁及敏感文案固定映射。另修复申请关联项目误调用未定义parseUuid导致500，复用本文件已有id解析器，原可见/绑定规则不改。缺预算池前原ledger尝试、工作流拒绝前原风险处理继续明确记账，不虚报零写入或真实回滚。

G3基础资料验收补充

B15–B18覆盖公司/成本中心/单据分类/供应商、日历、费用标准/类型、假别、模板及项目逐操作错误合同。仅补稳定原因与固定安全提示，保持原400/409/details、权限、开关、状态、金额/日期schema、默认值/null和事务审计。项目收口项的原先行惰性初始化例外明确记录：拒绝后不修改目标项、不记成功审计，不承诺所有拒绝零写入。旧详情中的公司代码及无效费用类型列表不用于拼UI文案。仅合成测试，具体合同与验收状态见implement顶部。

B11–B14连续本地验收

覆盖预算范围/选池与控制规则、员工账号/部门、员工资料/生命周期/合同培训证书及头像/合同附件错误解释。保留旧HTTP、VALID_001、详情字段与权限/冻结/事务/业务规则，三方原因及可恢复提示同批。员工文件读取只捕获既有生产映射的FST_REQ_FILE_TOO_LARGE并补原因，原文件限额/格式/内容检查和下载阻断安全message/审计保持。原目录无调用helper清理与不可达日期防御分支单独记录，测试只用合成资料和离线桩，详细合同以implement顶部为准。

B10及剩余546处治理

按implement顶部8组总表连续处理同类本地错误合同。B10限定预算/绩效路由原拒绝条件，保留管理员权限、经理/本人冻结、预算范围/额度和事务状态；只补25个明确原因及安全恢复提示。覆盖原status/details、无后续写入/成功审计、正常与权限回归，三方文案和严格基线同批验证。共享预算服务仍单列未完成，不能称整个预算域清零。

B6/D13/D14/B7接续验收

连续完成账号导入文件7原因、月份后置守卫补证/具体提示、公告三日期字段合法性与公告操作原因/现有页面错误反馈，并收齐工资维护现有校验原因。共36原因，业务拒绝条件不变。原status/details、导入事务/预览审计、工资生成发放规则、公告时区/缺省/签收保护保持；非法上传或公告时间不进入业务写入。月份00/13已有校验不能重复宣称修复，低年份Date.UTC偏移另列决策。精确合同与状态以implement最新入口为准，不扩大到真实业务或借款实施。

本轮D12/B5验收补充

继续执行已批准的本地日期与错误治理：HR入职日期缺失保留默认，提供但非法必须整条跳过并保留安全审计，在部门/账号/角色/身份/主管写入之前拒绝；已有员工不新增入职日更新。员工目录、合同筛选（含对应导出外层输入）及在岗历史范围共7原因，兼容原status/details与默认范围。以本轮implement顶部为当前限定合同；旧“D12尚未实施”为历史时点，完成状态以本轮回执为准。仅合成数据与离线桩；独立/发布不由主会话本地验证抵扣。

2026-09-17 连续本地治理范围（当前合同）

用户已批准按后期规划连续推进。继D1–D4后，实施D5用户创建/修改/CSV/XLSX入职日、D6员工资料/生命周期/档案、D7 AP直接列表、D8余项盘点、D9仪表板直接读、D10薪资/预算/绩效、D11考勤修正/请假和同步请求日期。仅本地输入校验，保留原权限、开关、状态机、额度/区间/默认日期和nullable/optional；旧attendance_v1固定关闭不被解冻。CSV须保留合法日期及文本标识原值，非法apply整批无业务写入，dry-run原审计保留。

B3/B4限于dashboard/AP查询/开关及账号创建/修改/工号不可改/空修改/导入错误行9原因；旧VALID_001、status/details保持，客户端具体安全文本、固定夹具和真实路由负例同批。剩余豁免只删消失指纹，原owner/2026-10-05不变。

验收按D5–D9/B3/B4最终17文件520项及后续D10/D11的9文件61项分列，两组不冒称全仓/独立/真实DB或公网。前端typecheck/build通过；完整记录/初跑失败/精确命令归implement及新证据目录。D12外部HR多格式日期须先分清缺失默认与非法跳过，尚未实施；datetime/月份、AP反向区间改变、历史数据修订和借款实现不在本批。旧批次/冻结材料保留，提交发布另按门禁。

2026-09-17 D1–D4本地接续范围

用户在D1–D4规划落盘后要求继续推进，本轮仅落实待办dueDate、员工目录及导出的hireDate筛选、节假日批量日期、仪表板/AP导出date-only字段。无效日历日期须在写入/业务导出查询前拒绝，原nullable/optional、权限、重复/归档冲突及区间语义保持；CSV/XLSX共同验证。完整结果见implement顶部，未来09-25人工复审与剩余错误豁免仍开放。

不扩大共享parseDateOnlyString转换、员工资料写入/导入、审计datetime、工资月份或AP台账反向区间规则；不修改客户端/迁移/生产。B1/B2原候选保留，本次新输入另冻供独立审查，不将旧450项验证冒称覆盖新输入。

2026-09-17 后续治理范围（本地实施已批准，已发布批次不重做）

按09-08优先级表承接B1/B2。B1先覆盖contractsRegistry、purchaseRequests、travelOrders、travelReconciliation的外部日期，再覆盖weeklyReports/presence；只加输入日历守卫，不开放冻结模块、不改审批/付款规则、历史数据或旧parseDateOnlyString转换约定。内部派生日期逐调用点追上游资格，不因引用旧解析器就整文件替换。

B2先用现有AST门禁盘点当前豁免及用户可达操作，再处理确实未迁移的常用路径；已发布paymentAccounts/invoicePool/auth/workflow提示不重复实施。每项必须同时有服务端原因码、兼容details、客户端具体文案及动态字段/无副作用断言；保留逐条批处理失败原合同，不靠宽泛正则或删基线隐藏问题。

新增小批验收：非法日历输入在事务/写入前拒绝，闰日/月末/null/省略及原区间/周起点语义保持；新原因码三方文本一致，动态字段投影仍安全，主链路零新增例外；受影响真实路由/客户端定向测试通过并经相应只读审查。09-25复审、09-30必要单项延期提案、10-02查漏、10-05原到期门禁不变，责任人shunli；本轮未创建定时任务、不延期。

用户已于本日批准按梳理继续，本节既有B1/B2小批进入本地实施；新增schema/业务规则、整库历史修订、生产写入和发布不在范围。与08-23受保护操作等待解耦，不要求完整灾备全部通过才能做本地治理。

2026-09-09 追加阶段

用户已批准综合任务安排的本地实施。复用本 task 管理 10-05 到期豁免分流，不改变原功能验收。当前交付是 73 文件/673 指纹全量核对与分流台账（implement.md §13）；未迁移原因码、未修改基线日期，不把 file 级分类冒充逐调用业务裁决。新分支迁移沿原 status/code/details 兼容与精确测试合同；须先完成既有两笔隔离提交，不能在原脏树叠第三笔产品代码。延期、提交、推送、部署各守明确授权。

Goal

把“系统知道为什么不能继续、真人只看到参数校验失败”的缺陷从逐页补文案改成可持续的错误合同，并以付款批次为第一个完整样板：财务在点击前就知道付款资料是否齐全、缺什么、由谁补；点击后的服务端二次校验与页面提示必须来自同一份实时判断。

Background

• 2026-09-05，真实单据 0014 在生产付款页已能进入待处理队列，但财务选择银行转账并点击“创建并提交复核”后只看到“参数校验失败”。只读诊断确认请求未创建付款批次；报销人缺所属公司、开户银行和银行卡号，公司侧已有有效建行付款账户，经理/CEO 复核人存在。
• 服务端创建前已检查来源状态、公司归属、收款账户、公司付款账户、活动批次占用和复核人；客户端未覆盖付款原因，因此回退到通用技术文案。
• 这是十一天内第三次“参数校验失败”阻断真人主流程。此前 B2 已验证“一份判断同时驱动展示、点击拦截和 mutation 二次拦截”能防漂移；本任务把该模式推广到付款就绪。
• 当前文本基线：服务端同一通用校验文案 365 处，buildValidationError( 518 次，测试目录中该字符串 20 次。数量用于确定渐进迁移边界，不代表独立业务原因数量。
• details key 不能作为原因合同：同一个 legalEntity、status 或 review 在不同业务域含义不同。稳定合同必须是带业务域的原因码，例如 payment_batch.legal_entity_required。
• 生产资料补录和真实付款继续由授权人员操作；本任务不得读取、记录或修改真实银行卡号，不把伪填建行资料作为恢复办法。

Scope

本 task 包含三项互相支撑但可独立回滚的交付：稳定业务原因码及增量 parity 门禁、首批真人主链路错误迁移、付款批次实时 readiness 与就近反馈。它不建设统一待办，也不扩展银行付款能力。

Requirements

R1 稳定原因码与渐进 parity 门禁

1. 新增服务端业务错误原因注册表。每个原因至少记录稳定 reasonCode、业务域、普通用户是否可达、默认安全中文提示/恢复方向；原因码采用 <domain>.<reason>，不得复用任意 details key 冒充合同。
2. 原有 HTTP status、顶层 error.code 和兼容 details 保持；已迁移错误在 details.reasonCode 增加稳定原因码。旧客户端可继续依赖既有字段，新客户端优先消费原因码。
3. 新增 parity 检查：已注册用户原因必须有客户端安全映射；服务端使用的原因必须已注册；新增或修改通用校验不得绕过原因码；客户端不得有孤儿/拼写漂移；未知原因走安全兜底且不展示原始 details、内部路径或 UUID。
4. 存量通用错误使用版本化遗留基线渐进收敛。例外按业务域/文件组记录原因、负责人、到期日和行号无关的调用指纹；新增指纹默认失败。不得以整目录永久忽略、只比较数量或模糊正则代替指纹门禁。
5. 首批真人主链路不得进入例外：报销提交/编辑/票据关联，付款创建/复核/登记，请假提交和考勤修正提交。范围内每个用户可达校验分支必须有注册原因码、准确中文提示和测试。
6. 遗留例外是迁移债，不是管理页永久展示技术文案的许可。到期后门禁必须失败；续期需要新理由和明确期限。

R2 用户可行动的错误反馈

1. VALID_001 未映射时不得再把服务端的“参数校验失败”直接展示给普通用户。兜底必须说明操作未完成、建议核对页面提示或联系管理员，并附现有 request ID；没有 request ID 时不展示空编号。
2. 具体提示必须回答“哪里不满足、下一步怎么恢复”，并位于相关字段、条目或动作附近。页面顶部错误和 toast 只作补充。
3. 错误不得只靠红色表达；动态错误使用可访问告警语义。禁用动作的原因必须在按钮附近持续可见，并通过 aria-describedby 或等价语义关联。
4. 20 处现有测试字符串逐处处置，不用宽泛正则消除失败：客户端 4 处模拟响应改为原因码 fixture；首批主链路改断言 reasonCode、兼容 details 和 HTTP status；非本批路径明确对应遗留例外和到期日；持久化失败摘要/批处理 reason 单独判断兼容性。

R3 付款批次实时 readiness

1. 抽取唯一服务端付款就绪解析器，返回 { ready, blockers }。blocker 使用 payment_batch.* 原因码和最小安全定位信息，不返回完整银行卡、密文或原始员工对象。
2. readiness 至少覆盖：来源状态/已付款、付款能力部门门禁、活动批次占用、单一公司归属、收款人银行资料、公司付款账户及解密可用性、非制单人的合格经理/CEO复核人。
3. 候选列表对单条候选实时计算 readiness；缺资料的记录仍可被发现，但不可选择，并就近显示缺项与恢复责任。财务无员工维护权限时只提示联系管理员，不暴露无权入口。
4. 多选付款必须用同一解析器计算组合 readiness，覆盖跨公司、并发占用和复核人等组合条件；不能因为每条单独就绪就推断组合一定就绪。
5. 创建接口在事务、必要锁和最新数据下再次调用同一解析器并 fail closed。候选、组合预检和创建不得各写一套判断；并发变化返回同一原因码。
6. readiness 每次按当前事实派生，不新增数据库字段、不落库、不长期缓存。资料或账户变化后，下次查询自然反映最新结果。
7. 银行转账只按真实资料判断。开户行不是建行时不得建议伪填；是否支持跨行付款属于独立产品能力。

R4 付款页面反馈

1. 正常候选不增加解释性噪音；有 blocker 时在候选行展示精确缺项，复选框不可用且原因可被键盘和读屏取得。
2. 已选组合 readiness 位于主动作紧邻上方；阻断时主动作禁用，提示与服务端二次拦截来自同一组 reasonCode 投影。
3. 正常银行付款 fixture 保持可选择、可创建并提交复核；新增门禁不得误伤资料与复核人完整的单据。
4. PC 是批量付款主路径；移动端不新增复杂组批能力，但已有移动付款路径不得显示原始技术错误或回归。

Acceptance Criteria

• AC1：存在可机器读取的原因码注册表；同一 details key 在两个业务域使用不同 reasonCode，parity 分别验证，证明不是按 key 虚假覆盖。
• AC2：未注册原因、缺客户端映射、拼错 reasonCode、新增无原因码调用、遗留指纹变化、例外过期六类 self-test 均非零退出；正常注册与有效遗留通过。
• AC3：报销提交/编辑/票据、付款创建/复核/登记、请假提交、考勤修正提交的用户可达错误为零例外；报告按域输出注册、已迁移、遗留和过期数量。
• AC4：未知 VALID_001 在 PC/移动显示安全可行动兜底；有 request ID 时展示编号，无编号时无空占位；“参数校验失败”、原始 details、UUID、接口路径不出现在 UI。
• AC5：20 处既有测试字符串有逐项处置清单；主链路断言具体原因码/中文，非本批项对应有效例外，无宽泛正则掩盖差异。
• AC6：付款单条与组合 readiness 覆盖正常、状态异常、活动批次、缺公司、缺/非建行收款资料、缺/不可解密公司账户、跨公司、无复核人；准确返回原因码，正常 fixture ready=true。
• AC7：候选、组合预检和创建事务调用同一 readiness 实现；并发变化时创建再次阻断且不生成 batch、item、成功 audit 或通知。
• AC8：正常候选无 readiness 噪音；异常候选不可选择且缺项就近可读；组合原因紧贴禁用主动作，toast 非唯一反馈，键盘/读屏语义通过。
• AC9：员工资料或公司账户变化后下一次 readiness 立即变化；schema、migration 和持久化 readiness 字段为零。
• AC10：用受控 fixture 复现 0014 三类缺项，分别提示所属公司、开户银行/银行卡和渠道限制；不使用或修改真实银行卡资料。
• AC11：相关服务端、客户端单元/Playwright、typecheck/build、Prisma validate、UI strict/self-test、Trellis governance、敏感扫描和 git diff --check 全部通过。
• AC12（部署后）：/ready、bundle marker、公网文案扫描通过；合成 API/页面证明 readiness 与原因码解析生效。真实资料补录和 0014 重试由授权人员完成，未取得真实证据时不得冒充 PASS。2026-09-05 经用户追加授权，以公网受控管理员对 0014 的真实缺项负向核验确认候选禁用、就近原因和创建 409；未补录资料、未创建成功批次、未执行付款，详见 implement.md 第 11 节。

Test Plan

• 原因码合同：运行 parity strict 检查及 self-test，覆盖注册表唯一性、同一 details key 跨域、未注册原因、缺客户端映射、孤儿/拼写漂移、新增无原因码调用、遗留指纹变化、例外过期，以及首批主链路试图加入例外时 fail closed。
• 首批主链路：对报销提交/编辑/票据关联、付款创建/复核/登记、请假提交、考勤修正提交运行 focused 服务端测试；逐分支断言 HTTP status、稳定 reasonCode、兼容 details 和准确中文映射，并验证主链路遗留例外为零。
• 付款 readiness：用受控 fixture 覆盖正常、状态异常、活动批次占用、缺所属公司、缺开户银行/银行卡、非建行、缺或不可解密公司账户、跨公司、无合格复核人；分别验证单条和组合投影，并以正常 fixture 证明可选择、可创建和提交复核不被误伤。
• 事务与实时性：模拟候选读取后事实变化，确认创建事务重新校验、失败时不产生 batch/item/成功 audit/notification；修改受控员工资料或公司账户后重新查询，确认 readiness 即时变化且无持久化字段或缓存依赖。
• 客户端与可访问性：逐项处置现有 20 处“参数校验失败”测试命中；断言具体原因就近显示、禁用按钮关联 aria-describedby 或等价语义、toast 非唯一反馈、未知原因不泄露 details/UUID/路径，有 request ID 时显示排障编号、无编号时不留空占位；不得以宽泛正则替代精确断言。
• 工程门禁：运行相关 server/client 单元测试与 Playwright、npm run prisma:validate、前端 typecheck/build、UI strict/self-test、Trellis governance、敏感信息扫描和 git diff --check，并确认 schema/migration/seed/flag/routing 与生产数据修改均为零。
• 部署后验收：在另行批准部署后核对 /ready、bundle marker 和公网文案扫描；仅用合成 API/页面样本验证三类 0014 缺项、正常付款路径及 B2/maker-checker 回归。真实银行卡资料、0014 建批/复核/登记必须由授权人员操作；缺少真实链路证据的项目明确记为 BLOCKED 或待自然样本验证，不以合成测试冒充 PASS。

Out of Scope

• 统一首页待办、通知推导和角色行动项模型；等待真实付款链路记录后另行规划。
• 一次性迁移全部 365 处通用文案或 518 个调用文本；非首批路径只建立可到期遗留基线。
• 支持跨行付款、银行直连、自动付款，或改变 maker-checker、付款角色、复核规则。
• 自动补录或读取生产员工公司、开户银行、银行卡号和公司账户。
• 修改业务状态机，新增 schema/migration/seed/flag/routing。
• 把完整 details、payload、UUID、账号或内部路径写入日志、任务材料或普通页面。

Risks and Deferred Items

• 静态扫描只证明合同登记；focused 分支测试证明真实返回，二者缺一不可。
• 单条与组合 readiness 语义不同；只做前者仍留下跨公司等点击后失败路径，因此组合预检是必交项。
• request ID 可帮助定位，但当前 AppError details 不进服务端日志。是否增加脱敏 reasonCode 日志另行评估，本任务不记录原始 details。
• 0014 只证明资料未维护，不证明员工没有建行卡；真实开户行由本人和授权管理员确认。