diff --git a/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.10_Task_Report.md b/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.10_Task_Report.md new file mode 100644 index 00000000..12afe744 --- /dev/null +++ b/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.10_Task_Report.md @@ -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`。 + - 合并冲突时必须保留动态枚举逻辑。 + - 不得恢复最新版本号或迁移数量硬编码。 diff --git a/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md b/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md index 8ffd9393..2dbff56f 100644 --- a/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md +++ b/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md @@ -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。 + - 不得改变安全业务成功终态。 diff --git a/docs/MDTODO/pikaoa-enterprise-platform.md b/docs/MDTODO/pikaoa-enterprise-platform.md index b7eb9b03..a630705a 100644 --- a/docs/MDTODO/pikaoa-enterprise-platform.md +++ b/docs/MDTODO/pikaoa-enterprise-platform.md @@ -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]