From 620c5a009eee16a744279c05c059c4e451822d32 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 17:21:12 +0200 Subject: [PATCH] docs: track PikaOA invoice and test runtime --- .../R1.3.8_Task_Report.md | 40 +++++++++++++++++++ docs/MDTODO/pikaoa-enterprise-platform.md | 7 +++- 2 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md 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 new file mode 100644 index 00000000..8ffd9393 --- /dev/null +++ b/docs/MDTODO/details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md @@ -0,0 +1,40 @@ +# R1.3.8 发票管理任务报告 + +## 交付结果 + +- 产品仓分支：`feat/r138-invoices`。 +- 产品提交：`60c903e feat: add invoice lifecycle and CLI`。 +- 产品 PR：[pikainc/pikaoa#9](https://github.com/pikainc/pikaoa/pull/9)。 +- 执行记录：[pikasTech/unidesk#1993](https://github.com/pikasTech/unidesk/issues/1993)。 + +## 业务能力 + +- 发票是服务端生成 UUIDv7 的平级 REST 资源，伙伴、合同、合同版本和附件只保存 typed ID。 +- `00007_invoices.sql` 使用 `numeric(20,2)` 保存金额、税额和价税合计，并由服务和数据库共同校验定点金额与合计关系。 +- 附件使用独立 `invoice_attachments` 关联记录，不形成嵌套资源或附件载荷副本。 +- 发票支持创建、读取、允许字段部分更新、分页列表、按币种汇总和不可删除废弃；废弃保留操作者、时间与非空原因，默认有效列表和汇总排除废弃记录。 +- `partnerCategoryId` 在 PostgreSQL List/Summary 中通过 `business_partner_categories` 的 `EXISTS` 条件真实过滤，不清空条件或返回未过滤全量结果。 + +## 平台契约 + +- 模块与 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，失败返回非零退出码。 + +## 验证证据 + +- `go test ./...`：通过。 +- `go vet ./...`：通过。 +- `make build`：`pikaoa-api`、`pikaoa-worker`、`pikaoa` 三入口通过。 +- host `httptest` 真实 HTTP/CLI 验证：管理员创建、读取、汇总、废弃和默认排除通过；普通员工读取通过，写入被 `authorization_denied` 拒绝。 +- 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，不能改变安全业务成功终态。 diff --git a/docs/MDTODO/pikaoa-enterprise-platform.md b/docs/MDTODO/pikaoa-enterprise-platform.md index 3dd28570..b573f334 100644 --- a/docs/MDTODO/pikaoa-enterprise-platform.md +++ b/docs/MDTODO/pikaoa-enterprise-platform.md @@ -48,7 +48,7 @@ #### R1.3.7 [in_progress] 实现合同与合同版本平级 UUIDv7 REST 资源，通过 contractId、previousVersionId、currentVersionId 建立 ID 关系，保证版本不可变、并发序号唯一、附件关联和全量 CLI，执行记录见 [pikasTech/unidesk#1992](https://github.com/pikasTech/unidesk/issues/1992)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.7_Task_Report.md)。 -#### R1.3.8 [in_progress] +#### R1.3.8 [completed] 实现平级 UUIDv7 发票资源，通过 partnerId、contractId、contractVersionId 和 attachmentId 建立关联，支持定点金额、typed 一致性校验、不可删除废弃事实、筛选汇总和全量 CLI，执行记录见 [pikasTech/unidesk#1993](https://github.com/pikasTech/unidesk/issues/1993)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3.8_Task_Report.md)。 #### R1.3.9 [in_progress] @@ -58,7 +58,7 @@ 在 R1.3 CLI 后端验收通过后实现 HWLAB v0.3 同族 Vue 工作台、响应式页面与同路径业务流，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.4_Task_Report.md)。 -### R1.5 [completed] +### R1.5 [in_progress] 在 UniDesk 中声明 PK01 PostgreSQL、Secret、NC01 独立 namespace、Gitea/PaC、GitOps、OTel/Prometheus 和 PK01 公网暴露，并改进可复用 bootstrap 工具，依赖 R1.1-R1.2，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5_Task_Report.md)。 @@ -80,6 +80,9 @@ #### R1.5.6 [completed] 修复 GitHub repository override 对 owner/repo 大小写敏感，确保 pikaInc/pikaoa 与 canonical 名称选择同一受控 token，执行记录见 [pikasTech/unidesk#1980](https://github.com/pikasTech/unidesk/issues/1980)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.6_Task_Report.md)。 +#### R1.5.7 [in_progress] + +增加 YAML-first PikaOA 专用测试集群临时 k8s 运行面和 pikaoa test-target plan/status/start/stop 受控入口，不经过 CI/CD、不触碰正式 namespace，未声明测试 target 时返回 configured=false，执行记录见 [pikasTech/unidesk#2046](https://github.com/pikasTech/unidesk/issues/2046)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5.7_Task_Report.md)。 ### R1.6 审核并合并双仓 PR，执行首次受控 PaC bootstrap，由正常 source PR merge 自动发布，依赖 R1.3-R1.5，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6_Task_Report.md)。