From c0f6fed3fde53251bb8718101a6fae0ff3807f05 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Thu, 19 Mar 2026 16:22:38 +0800 Subject: [PATCH] docs: update spec verification and checklist --- .../checklists/scope-alignment.md | 64 +++++++++++++++++++ specs/002-rev005-invoice-flow/verification.md | 14 ++-- 2 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 specs/001-rev004-accounting/checklists/scope-alignment.md diff --git a/specs/001-rev004-accounting/checklists/scope-alignment.md b/specs/001-rev004-accounting/checklists/scope-alignment.md new file mode 100644 index 0000000..4b8f3d4 --- /dev/null +++ b/specs/001-rev004-accounting/checklists/scope-alignment.md @@ -0,0 +1,64 @@ +# Scope Alignment Checklist: REV-004 账务处理一期 + +**Purpose**: Validate whether the REV-004 scope and alignment requirements are complete, clear, consistent, and review-ready. +**Created**: 2026-03-18 +**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md) + +**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements. + +## Source & Scope + +- [ ] CHK001 Are the target documents and their distinct responsibilities explicitly defined without overlap or omission? [Completeness, Spec §FR-001] +- [ ] CHK002 Are the governing source-of-truth documents clearly distinguished from reference-only materials such as Archive content? [Consistency, Spec §FR-002] +- [ ] CHK003 Does the spec define REV-004 phase-one scope with a stable inclusion list and an equally explicit exclusion boundary? [Completeness, Spec §FR-003, Spec §FR-005] +- [ ] CHK004 Is the rule "共性能力先统一、场景能力再分批" specified with enough detail to constrain later planning order and not just describe intent? [Clarity, Spec §FR-004] + +## Requirement Completeness + +- [ ] CHK005 Are traceability requirements defined across detailed design, interface design, and database design for every in-scope accounting scenario? [Completeness, Spec §FR-006] +- [ ] CHK006 Are evidence retention, original-basis recording, and result write-back requirements all specified as mandatory scope elements rather than implied expectations? [Completeness, Spec §FR-007] +- [ ] CHK007 Does the spec define when execution playbook, project progress, and task checklist updates are required and when they are intentionally not required? [Completeness, Spec §FR-008] +- [ ] CHK008 Are the minimum validation actions required before clarify/plan/tasks complete, specific, and tied to concrete review artifacts? [Completeness, Spec §FR-011] + +## Requirement Clarity + +- [ ] CHK009 Is "一期" bounded by explicit scenario names and exclusion criteria, rather than by broad phrases that could expand during review? [Clarity, Spec §FR-003, Spec §FR-005] +- [ ] CHK010 Is "审批仅保留能力位和边界说明" precise enough to prevent readers from inferring workflow nodes, routing rules, or BPM scope? [Clarity, Spec §FR-010] +- [ ] CHK011 Is the phrase "文档一致性、计划可拆解性和台账可回写性" translated into objective review questions or evidence points? [Measurability, Spec §FR-009, Spec §SC-004] +- [ ] CHK012 Does the spec avoid implementation-oriented acceptance language and keep review criteria at the user/business-document level throughout? [Clarity, Spec §FR-012] + +## Requirement Consistency + +- [ ] CHK013 Are the in-scope scenarios consistent between the user stories, functional requirements, assumptions, and plan summary? [Consistency, Spec §User Story 1, Spec §FR-003, Plan §Summary] +- [ ] CHK014 Do the acceptance boundaries in the spec align with the plan's statement that this round excludes backend code modification? [Consistency, Spec §FR-009, Plan §Summary] +- [ ] CHK015 Are the named core scenarios consistent across the spec and plan, given that the plan summary includes five scenarios while FR-003 lists four examples? [Conflict, Spec §FR-003, Plan §Summary] +- [ ] CHK016 Are the requirements for traceability, validation, and ledger sync consistent between the spec and the task structure used for later execution? [Consistency, Spec §FR-008, Spec §FR-011, Tasks §Validation] + +## Acceptance Criteria Quality + +- [ ] CHK017 Can each success criterion be evaluated objectively from document content alone, without relying on reviewer intuition or external tribal knowledge? [Acceptance Criteria, Spec §SC-001, Spec §SC-002, Spec §SC-003, Spec §SC-004] +- [ ] CHK018 Is the "5 分钟内判断范围" criterion supported by explicit requirement structure that makes such a review realistically repeatable? [Measurability, Spec §SC-002] +- [ ] CHK019 Are acceptance scenarios mapped clearly enough to the functional requirements they are intended to validate? [Traceability, Spec §User Story 1, Spec §User Story 2, Spec §User Story 3] + +## Scenario Coverage + +- [ ] CHK020 Are primary, exclusion, exception, and governance-sync scenarios all covered in requirements, rather than only the happy-path planning narrative? [Coverage, Spec §Edge Cases, Spec §FR-008, Spec §FR-009] +- [ ] CHK021 Are requirements defined for terminology conflicts between detailed/interface/database documents, including how the formal wording is chosen? [Coverage, Spec §Edge Cases, Spec §FR-006] +- [ ] CHK022 Does the spec define what happens when historical materials contain finer-grained accounting scenarios than the current phase-one baseline? [Edge Case, Spec §Edge Cases] + +## Dependencies & Assumptions + +- [ ] CHK023 Are assumptions about the current main documents already covering the required accounting scenarios explicitly validated or marked for confirmation? [Assumption, Spec §Assumptions] +- [ ] CHK024 Are dependencies on the execution playbook, governance ledgers, and constitution documented as requirements constraints rather than hidden context? [Dependency, Spec §FR-002, Plan §Technical Context] + +## Ambiguities & Conflicts + +- [ ] CHK025 Is there any unresolved ambiguity between "账务处理一期" as a document-governance scope and "后续实施计划" as a scenario-delivery scope? [Ambiguity, Spec §FR-004, Spec §FR-009] +- [ ] CHK026 If scope is later narrowed to a single sub-scenario, do the requirements say which parts of the current baseline remain mandatory and which may be deferred? [Gap, Spec §Assumptions] + +## Notes + +- Check items off as completed: `[x]` +- Add comments or findings inline +- Link to relevant resources or documentation +- Items are numbered sequentially for easy reference diff --git a/specs/002-rev005-invoice-flow/verification.md b/specs/002-rev005-invoice-flow/verification.md index 22d5cdf..ca2c349 100644 --- a/specs/002-rev005-invoice-flow/verification.md +++ b/specs/002-rev005-invoice-flow/verification.md @@ -27,32 +27,36 @@ ### SC-001 发票申请接口响应时间 < 500ms（不包含外部服务调用） -- **当前状态**：待补充专项验证 +- **当前状态**：待补充专项验证（实现态证据已补强） - **现有证据**：backend 最小编译通过，后台申请接口与校验链路已实现 +- **实现态补充证据**：`InvoiceController.applyInvoice` 已固定暴露 `/business/invoice/apply` 入口；`InvoiceApplyReqVO` 强制要求 `chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`；`InvoiceServiceImpl.applyInvoice` 当前同步执行的仅包括账单去重排序、幂等单号生成、客户/客户开票信息/账单/税率校验、`InvoiceDO` 落库与操作日志写入，并未在该方法内直接同步调用外部 `SYS-008`，而是通过生成 `sysRequestNo`、写入 `PENDING` 状态后结束本地受理流程。 - **缺口说明**：尚未执行接口响应时延采样，也未沉淀固定样本、环境与统计结果 - **后续建议**：在可用测试环境中对 `/business/invoice/apply` 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径 - **建议统计口径**：仅统计 `SYS-002` 本地受理、账单/客户/税率/限额校验、申请记录落库等内部处理时延；明确剔除 `SYS-008` 外部接口等待时间；结果表至少记录样本时间、样本环境、请求体摘要、平均值、P95、最大值与异常样本说明 ### SC-002 发票申请校验通过率 > 95%（正常业务场景） -- **当前状态**：待补充样本统计 +- **当前状态**：待补充样本统计（实现态证据已补强） - **现有证据**：已实现账单收费状态、开票状态、客户开票信息、税率配置、开票限额、幂等控制等校验规则 +- **实现态补充证据**：`validateCustInvoice` 已明确拦截“客户未维护开票信息”“客户开票信息不存在”“发票抬头不一致”“税号不一致”“电子发票缺少邮箱/手机号”等场景；`validateCharges` 已明确拦截“账单不存在”“账单与客户不匹配”“仅已收费账单允许申请开票”“存在已开票账单”；`validateInvoiceTaxrate` 会拦截缺少可用税率配置；`applyInvoice` 对同一 `applicationNo` 或 `custId + chargeIds` 组合会直接返回既有申请，因此幂等命中样本应单列说明，不能混入正常成功率分母。 - **缺口说明**：尚未基于真实或模拟样本形成“正常场景通过率”统计 - **后续建议**：准备覆盖正常账单、已开票账单、未缴费账单、限额超限账单等样本集，按样本分组输出通过/拦截统计 - **建议统计口径**：将样本分为“正常业务场景”和“规则拦截场景”两组；SC-002 仅统计正常业务场景的申请成功率，结果表至少记录样本总数、成功数、失败数、失败原因分类，并单列幂等命中、原始单账单直接部分开票拦截等非正常场景说明 ### SC-003 开票结果回写成功率 > 99% -- **当前状态**：待补充样本统计 +- **当前状态**：待补充样本统计（实现态证据已补强） - **现有证据**：已实现结果回写、成功终态保护、账单状态联动、失败原因留痕 +- **实现态补充证据**：`writeBackInvoice` 已支持按 `applicationNo` / `sysRequestNo` 定位发票，统一回写 `invoiceStatus`、`invoiceCode`、`invoiceNumber`、`fileUrl`、`pushStatus`、`latestResult`、`latestError` 与 `failReason`，并调用 `syncChargeInvoiceState` 做账单联动；若当前记录已是 `SUCCESS` 且收到非成功回写，会命中“成功终态保护”分支，仅刷新查询上下文与日志，不覆盖既有成功结果；`queryInvoice` 与 `/query/compensate` 复用 `refreshQueryContext`，可为回写失败、超时与补偿查询样本提供统一追溯键。 - **缺口说明**：尚未基于批量样本统计回写成功率 - **后续建议**：在联调或测试环境中按申请单号、受理号建立样本集，统计回写请求总量、成功量、失败量与失败原因分类 - **建议统计口径**：按“回写请求总量”“业务成功落账量”“业务失败量”“因成功终态保护而不覆盖原状态量”四类指标统计；失败样本需区分外部返回失败、查询超时、账单联动异常、数据缺失等分类，并保留申请单号/受理号映射以便追溯 ### SC-004 电子发票下载成功率 > 99% -- **当前状态**：待补充样本统计 +- **当前状态**：待补充样本统计（实现态证据已补强） - **现有证据**：已实现仅 `SUCCESS + fileUrl` 可下载/推送的前置校验，客户归属校验与推送状态回写已落地 +- **实现态补充证据**：`getRequiredCustomerInvoice` 已要求 `custId` 必填，且 `invoiceId`、`applicationNo`、`sysRequestNo` 至少提供一个定位键，并会拦截“未找到当前客户可访问的电子发票”；`validateDownloadableInvoice` 已明确拦截“当前发票状态不可下载或推送”“电子发票文件地址不存在”；`pushInvoice` 仅支持 `EMAIL`、`SMS` 两类渠道，并分别校验邮箱/手机号是否可用，成功后会更新 `pushStatus`、`latestResult` 并记录渠道与目标。 - **缺口说明**：尚未形成客户侧下载成功率样本统计 - **后续建议**：在具备有效电子票文件地址的样本下，统计查询、下载、推送三类动作成功率，并区分“无权限”“无文件”“非成功终态”等拦截原因 - **建议统计口径**：以具备有效 `SUCCESS + fileUrl` 条件的样本作为成功率分母，同时单独记录被权限校验、文件缺失、非成功终态拦截的请求量；建议分别输出“客户查询成功率”“下载成功率”“推送成功率”三个子指标，避免把前置拦截与真实下载失败混为一类 @@ -76,6 +80,7 @@ | 后台红冲 | `redInkInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 | - **缺口说明**：尚未在测试或联调环境按上述矩阵逐项抽取实际日志样本，当前仍缺运行态日志记录证据 +- **DDL/迁移跟进结论**：已交叉核查 `backend/sql`、Archive 数据库设计、`sql/lhc_数据库设计.md` 与 `BACKEND_TABLE_MAPPING.md`；当前仍未定位到与 `InvoiceDO` 最新字段完全一致的 `biz_invoice` 物理 DDL / migration 脚本，现有同名历史对象更偏开票配置表，US4 的物理落库链路仍需继续结合实际数据库变更记录确认。 - **后续建议**：按矩阵至少抽取申请、补偿查询、结果回写、客户下载、客户推送、作废、红冲各 1 条日志样本，核对操作人、客户、状态与日志内容是否一致 ### 待补样本记录模板（不含实际结果） @@ -128,6 +133,7 @@ | 后台红冲 | 待补 | 待补 | 待补 | 待补 | 待补 | - **待补说明**：样本抽取时需能回扣到 `recordInvoiceOperatLog` / `OperatLogService.createOperatLog` 的实现态矩阵，并保留查询来源、渠道、原票代码/号码等关键上下文。 +- **DDL 跟进说明**：与日志样本同步收口时，还需补记本轮核查结论：当前仓库仍未定位到与 `InvoiceDO` 当前模型完全对齐的 `biz_invoice` 物理 DDL / migration 来源；若联调环境已完成数据库变更，应同时记录变更单号、脚本路径或 DBA 提供的物理表结构证明。 ### 待补样本执行入口清单