tangweijie 3eccab2cf9 docs: 文档治理统一 — AGENTS.md 生命周期规则 + 模块归档 + DDL 修正

1. AGENTS.md 更新
   - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节
   - water-backend: 更新协作引用（建设期/建成后、evidence 模块化）

2. specs/ 重复合并
   - 006-reminder-event-design 合并入 003-rev006-reminder-event-design
   - 001-rev004-accounting 删除冗余 data-model.md + contracts/
   - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/

3. evidence 按模块归档
   - 35 个 REV-004 文件归入 evidence/rev004-accounting/
   - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/
   - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录

4. guides/ 清理
   - 14 个 REV004_*.md 移入 evidence/rev004-accounting/

5. 遗留文件处理
   - docs/research/ 归档到 Archive/06_Migration_Plans/
   - backend-check detached worktrees 清理

6. 交叉引用修复
   - 006-reminder-event-design → 003-rev006-reminder-event-design
   - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_

7. DB 设计文档修正（01_Database_Design.md）
   - biz_invoice 明确为开票配置表，非发票记录表
   - 新增 biz_invoice_record 为发票申请/结果主表
   - 新增 biz_charge_invoice_rel 账单-发票关联说明
   - REV-005 承接口径表名全部修正

8. 发票审计证据
   - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md

2026-06-16 11:47:16 +08:00

4.1 KiB

Raw Blame History

YW 业务流程 Expect 验收用例编制记录（2026-06-09）

背景

根据用户在 2026-06-09 提供的 5 条业务测试用例，前端仓新增 Expect 黑盒验收场景 suite：

yw-business-flows:yw-01：手工建档
yw-business-flows:yw-02：册本调整
yw-business-flows:yw-03：抄表录入
yw-business-flows:yw-04：复核开账
yw-business-flows:yw-05：柜台收费

前端实现位置：

../water-frontend/tests/expect/yw-business-flows/scenarios.json
../water-frontend/tests/expect/ywBusinessFlowsScenarios.test.mjs
../water-frontend/tools/expect/acceptance-scenarios.mjs
../water-frontend/tests/expect/README.md

执行入口

pnpm test:expect:acceptance -- yw-business-flows:all
pnpm test:expect:acceptance -- yw-business-flows:yw-01
pnpm test:expect:acceptance -- yw-05

测试数据要求

新增场景使用以下测试数据环境变量：

EXPECT_TEST_NEW_CUSTOMER_ARCHIVE
EXPECT_TEST_AVAILABLE_METER
EXPECT_TEST_INVOICE_PROFILE
EXPECT_TEST_ARCHIVED_CUSTOMER
EXPECT_TEST_TARGET_METER_BOOK
EXPECT_TEST_METER_READ_CUSTOMER
EXPECT_TEST_METER_READING_VALUE
EXPECT_TEST_REVIEWABLE_METER_READ_RECORD
EXPECT_TEST_BILLABLE_METER_READ_RECORD
EXPECT_TEST_CHARGED_CUSTOMER

并复用：

EXPECT_TEST_ADMIN_USERNAME
EXPECT_TEST_CASHIER_A_USERNAME

缺少上述数据时，runner 必须在启动浏览器前返回 BLOCKED，不得使用占位符或编造业务记录继续执行。

验证结果

已执行目录契约与 runner 数据门禁验证：

node --test tests/expect/ywBusinessFlowsScenarios.test.mjs

结果：pass 6 / fail 0。

pnpm test:expect:acceptance -- --list

结果：命令退出码 0，yw-business-flows:yw-01 至 yw-business-flows:yw-05 均已列出。

pnpm test:expect:acceptance -- yw-05 --no-dev-server

结果：命令退出码 2，按预期返回：

BLOCKED: missing required acceptance test data for yw-05.
缺少 EXPECT_TEST_CASHIER_A_USERNAME
缺少 EXPECT_TEST_CHARGED_CUSTOMER

pnpm test:expect:acceptance -- yw-business-flows:all --no-dev-server

结果：命令退出码 2，按预期返回 BLOCKED，缺少全部 5 条 YW 用例所需的账号、客户、册本、水表、抄表、复核开账与柜台收费测试数据。

node --test tests/expect/*.test.mjs

结果：pass 30 / fail 0。

真实浏览器验收尝试（2026-06-09 12:00 CST）

pnpm test:expect:acceptance -- yw-business-flows:all --no-dev-server --timeout 1800000

结果：命令退出码 1，未形成 PASS 业务验收结论。

已启动真实浏览器并进入 yw-business-flows:yw-01 手工建档场景。
浏览器侧可见记录显示已登录并访问 http://localhost:18080/custData/custCreate。
运行过程中产生的主要证据：
- /tmp/expect-artifacts/playwright/page@8c120c0eebb660ecda33437a218d685a.webm
- /tmp/expect-artifacts/playwright-results/result-*.json
- .expect/logs.md
ACP rollout 日志显示：用例在 yw-01 内部反复处理 Element Plus 下拉选择器，后续浏览器 transport 关闭。
Expect 最终报错：
- ACP stream inactivity timeout
- Streaming failed: Agent produced no output for 180s.
本次运行未进入 yw-02 至 yw-05 的业务执行阶段。
本次运行中测试数据环境变量虽然已设置，但部分值存在乱码；agent 曾使用自行构造的可读测试数据继续填写。按黑盒验收规则，这不能作为有效 PASS 证据。

本次真实浏览器验收结论：BLOCKED / FAIL-RUNNER。阻断原因为 Expect ACP/browser transport 超时，且测试数据可读性不足；业务功能本身尚不能据此判定通过或失败。

当前结论

测试用例已编制为可执行 Expect 黑盒验收场景，目录加载、提示词生成和数据缺失拦截均通过。

截至本记录，真实浏览器业务验收已尝试执行，但未形成有效业务通过结论；当前阻断点为测试数据可读性不足与 Expect ACP/browser transport 超时。真实业务场景结论当前仍为 BLOCKED，不是 PASS。

4.1 KiB Raw Blame History Unescape Escape