docs: 记录 PikaOA 发票与后端验证结果

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-14 18:43:20 +02:00
parent 38e9a66d1a
commit e58894a306
3 changed files with 108 additions and 10 deletions
@@ -0,0 +1,70 @@
+# R1.3.10 PostgreSQL 后端统一验证入口任务报告
+
+## 交付结果
+
+- 产品分支：`feat/r1310-test-postgres`。
+- 产品提交：
+  - `ebe829b feat: expose backend verification result`。
+  - `a806570 fix: serialize PostgreSQL verification tests`。
+- 产品 PR：[pikainc/pikaoa#12](https://github.com/pikainc/pikaoa/pull/12)。
+- 执行记录：[pikainc/pikaoa#10](https://github.com/pikainc/pikaoa/issues/10)。
+
+## 入口契约
+
+- `scripts/verify-backend.sh` 是单一非交互验证入口，`make verify-backend` 是默认 Make 包装。
+- 入口依次执行：
+  - `go test -p 1 -count=1 ./...`。
+  - `go vet ./...`。
+  - `make build`。
+- 全仓 integration package 共用专用测试 Job 注入的一个 PostgreSQL DSN，并且会各自执行 migrate。
+  - `-p 1` 固定 package 并发为 1，避免并发迁移和数据库状态竞争。
+  - `-count=1` 禁用 Go test cache，确保每次 Job 都真实执行。
+- 阶段开始、完成和失败写入 stderr，避免长任务无输出；stdout 最终只输出一个 JSON 文档。
+- PostgreSQL 只披露 `PIKAOA_TEST_DATABASE_URL` 是否为非空，不读取、打印、拼接或记录 DSN 内容。
+- 默认无 DSN 时，其他阶段继续运行，最终明确输出 `dsnPresent=false`、`integration=skipped`。
+- `--require-postgres` 模式缺少 DSN 时，在运行任何子命令前返回：
+  - exit 2。
+  - `postgres_test_database_required`。
+  - `integration=not_run`。
+- DSN 存在时通过环境继承给 Go 测试；全仓测试成功后输出 `integration=passed`。
+
+## 测试与迁移治理
+
+- fixture 通过 PATH 注入假的 `go` 和 `make`，验证：
+  - 默认 skipped。
+  - require-postgres 缺失 typed failure。
+  - DSN presence 传递和无泄露。
+  - Go 调用参数精确包含 `test -p 1 -count=1 ./...`。
+- 迁移测试使用嵌入文件系统动态枚举 `migrations/*.sql`，校验：
+  - 文件名符合五位编号和稳定名称；
+  - 文件按版本严格递增；
+  - 每个嵌入文件可读取；
+  - 每个迁移具有 Goose Up 和 Down 段；
+  - `LatestVersion()` 等于嵌入文件中的动态最高版本。
+- 测试不再包含 `latest == N` 或迁移数量硬编码，并行模块新增保留编号时不需要修改共享 latest 断言。
+
+## 验证证据
+
+- `env -u PIKAOA_TEST_DATABASE_URL go test -count=1 ./internal/verifybackend`：fixture 通过。
+- `env -u PIKAOA_TEST_DATABASE_URL ./scripts/verify-backend.sh`：
+  - exit 0。
+  - 全仓 Go package 按顺序重新执行。
+  - Go test、vet 和 build 均 passed。
+  - 最终 JSON 披露 `integration=skipped`。
+- `env -u PIKAOA_TEST_DATABASE_URL ./scripts/verify-backend.sh --require-postgres`：
+  - exit 2。
+  - typed code 为 `postgres_test_database_required`。
+- fixture 使用不可用伪 DSN，只验证环境传递；stdout、stderr 和调用记录均不包含伪 DSN。
+- `git diff --check`：通过。
+
+## 边界与风险
+
+- 本轮没有连接真实 PostgreSQL、数据库集群或 Kubernetes，没有启动 host server。
+- 本轮没有修改业务模块、迁移 SQL、身份/RBAC、CI/CD、Web 或运行配置。
+- `integration=passed` 的真实运行证据仍必须由 YAML-first 专用测试 Job 注入测试 DSN 后产生。
+  - 本任务只交付可供该 Job 调用的入口。
+  - PR 暂不合并。
+  - 后续吸收并行模块迁移后再在专用测试集群运行。
+- 并行伙伴、附件、合同和发票 PR 都可能修改 `internal/migrate/migrate_test.go`。
+  - 合并冲突时必须保留动态枚举逻辑。
+  - 不得恢复最新版本号或迁移数量硬编码。
@@ -3,7 +3,9 @@
 ## 交付结果

 - 产品仓分支：`feat/r138-invoices`。
- 产品提交：`60c903e feat: add invoice lifecycle and CLI`。
+- 产品提交：
+  - `60c903e feat: add invoice lifecycle and CLI`。
+  - `dc7e34b fix: reject empty invoice updates`。
 - 产品 PR：[pikainc/pikaoa#9](https://github.com/pikainc/pikaoa/pull/9)。
 - 执行记录：[pikasTech/unidesk#1993](https://github.com/pikasTech/unidesk/issues/1993)。

@@ -12,29 +14,55 @@
 - 发票是服务端生成 UUIDv7 的平级 REST 资源，伙伴、合同、合同版本和附件只保存 typed ID。
 - `00007_invoices.sql` 使用 `numeric(20,2)` 保存金额、税额和价税合计，并由服务和数据库共同校验定点金额与合计关系。
 - 附件使用独立 `invoice_attachments` 关联记录，不形成嵌套资源或附件载荷副本。
- 发票支持创建、读取、允许字段部分更新、分页列表、按币种汇总和不可删除废弃；废弃保留操作者、时间与非空原因，默认有效列表和汇总排除废弃记录。
+- 发票支持创建、读取、允许字段部分更新、分页列表、按币种汇总和不可删除废弃。
+  - 废弃保留操作者、时间与非空原因。
+  - 默认有效列表和汇总排除废弃记录。
+- 空 PATCH `{}` 返回 typed HTTP 400：
+  - `code=invalid_argument`。
+  - `field=body`。
+  - 发票实体、`updatedAt`、store、audit 和 outbox 均保持不变。
 - `partnerCategoryId` 在 PostgreSQL List/Summary 中通过 `business_partner_categories` 的 `EXISTS` 条件真实过滤，不清空条件或返回未过滤全量结果。

 ## 平台契约

- 模块与 capability 统一使用 `invoices`、`invoices.read/manage/void`；管理员拥有全部能力，普通员工系统角色只获得目录中的 `*.read`。
+- 模块与 capability 统一使用 `invoices`、`invoices.read/manage/void`。
+  - 管理员拥有全部能力。
+  - 普通员工系统角色获得目录中的全部 `*.read`。
 - HTTP 写入 actor 仅来自 identity session，不接受请求载荷伪造 actor。
 - 业务、审计和 `invoices.created/updated/voided` outbox 事件在同一 PostgreSQL 事务内写入。
 - OTel span、结构化日志和 Prometheus 指标统一使用 `invoices` 模块前缀；指标只包含有界 operation/result 标签。
- 跨模块引用存在性和一致性结果只投影为 `blocking=false` warning；发票自身 UUIDv7、金额、日期、状态和废弃事实继续返回字段级 typed error。
- CLI 覆盖 `invoices create|get|update|list|summary|void`，文本与 JSON 都返回 requestId/traceId，失败返回非零退出码。
+- 跨模块引用存在性和一致性结果只投影为 `blocking=false` warning。
+  - 发票自身 UUIDv7、金额、日期、状态和废弃事实继续返回字段级 typed error。
+- CLI 覆盖 `invoices create|get|update|list|summary|void`。
+  - 文本与 JSON 都返回 requestId/traceId。
+  - 失败返回非零退出码。

 ## 验证证据

 - `go test ./...`：通过。
 - `go vet ./...`：通过。
+- `git diff --check`：通过。
 - `make build`：`pikaoa-api`、`pikaoa-worker`、`pikaoa` 三入口通过。
- host `httptest` 真实 HTTP/CLI 验证：管理员创建、读取、汇总、废弃和默认排除通过；普通员工读取通过，写入被 `authorization_denied` 拒绝。
+- host `httptest` 真实 HTTP/CLI 验证：
+  - 管理员创建、读取、汇总、废弃和默认排除通过。
+  - 普通员工读取通过，写入被 `authorization_denied` 拒绝。
+  - 空 PATCH 返回 correlated typed error，重新读取的业务字段与 `updatedAt` 不变。
+- 服务层空 PATCH 回归验证：
+  - store 读取和写入次数均为零。
+  - 引用校验、audit 和 outbox 路径均未进入。
+  - 完整发票值与 `updatedAt` 保持不变。
 - PostgreSQL 集成测试代码覆盖大额定点金额、业务/audit/outbox 同事务回滚、伙伴分类 List/Summary 和废弃事实。

 ## 未执行与风险

 - 当前环境未声明 `PIKAOA_TEST_DATABASE_URL`，所以 PostgreSQL 集成测试在本轮按契约 skip，不能宣称真实 PostgreSQL 已通过。
- UniDesk owning YAML 只发现正式 `pikaoa`、`pikaoa-ci` 和 PK01 数据库目标，没有专用 PikaOA 测试集群 target；本轮没有猜测集群、没有部署 k8s、没有访问正式 namespace、公网或 PK01 数据。
- 分类查询依赖伙伴迁移 `00004_partners.sql` 提供 `business_partner_categories`；PR 合并前必须先吸收伙伴基线并在具有该迁移的测试数据库复跑 PostgreSQL 集成测试。
- 合同、合同版本和附件模块接入后应提供真实 `ReferenceValidator`；其一致性异常仍只能输出非阻塞 warning，不能改变安全业务成功终态。
+- UniDesk owning YAML 只发现正式 `pikaoa`、`pikaoa-ci` 和 PK01 数据库目标，没有专用 PikaOA 测试集群 target。
+  - 本轮没有猜测集群。
+  - 本轮没有部署 k8s。
+  - 本轮没有访问正式 namespace、公网或 PK01 数据。
+- 分类查询依赖伙伴迁移 `00004_partners.sql` 提供 `business_partner_categories`。
+  - PR 合并前必须先吸收伙伴基线。
+  - 必须在具有该迁移的专用测试数据库复跑 PostgreSQL 集成测试。
+- 合同、合同版本和附件模块接入后应提供真实 `ReferenceValidator`。
+  - 其一致性异常仍只能输出非阻塞 warning。
+  - 不得改变安全业务成功终态。
@@ -54,7 +54,7 @@
 #### R1.3.9 [in_progress]

 复用 append-only 审计唯一真相实现 UUIDv7 平级审计资源、RBAC 查询 API、actor/resource/action/time/requestId/traceId 筛选和 audit list/get CLI，执行记录见 [pikasTech/unidesk#1994](https://github.com/pikasTech/unidesk/issues/1994)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.9_Task_Report.md)。
-#### R1.3.10 [in_progress]
+#### R1.3.10 [completed]

 增加可由 YAML-first 专用测试集群临时 Job 调用的统一 PostgreSQL 后端验证入口，明确披露 DSN presence 和 integration passed/skipped，去掉迁移测试对最新编号的共享硬编码，执行记录见 [pikainc/pikaoa#10](https://github.com/pikainc/pikaoa/issues/10)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.10_Task_Report.md)。
 ### R1.4 [in_progress]