From 22b42a280d759451acca1df37d91dce2774d2dba Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 16 Jul 2026 07:01:53 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20PikaOA=20=E7=A8=B3?= =?UTF-8?q?=E5=AE=9A=E5=BC=80=E5=8F=91=E8=BF=90=E8=A1=8C=E9=9D=A2=E8=A7=84?= =?UTF-8?q?=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../PJ2026-03/specs/PJ2026-03-pikaoa.md | 87 ++++++++++--------- 1 file changed, 45 insertions(+), 42 deletions(-) diff --git a/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md index 200d0f98..bfcd9fe1 100644 --- a/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md +++ b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md @@ -11,6 +11,7 @@ | v0.5 | 待本版本提交 | 2026-07-14 | 增加不经过 CI/CD 的 YAML-first 专用测试集群临时运行面，并与正式自动交付严格隔离。 | | v0.6 | 待本版本提交 | 2026-07-15 | 将测试运行面收敛到现有 NC01 k3s 的独立 namespace，复用 PK01 host PostgreSQL 的独立测试库和角色，并增加 hostIP 暴露与测试自动交付契约。 | | v0.7 | 待本版本提交 | 2026-07-16 | 增加合同与发票 PDF 导入预览、自动字段提取、人工校对、typed ID 附件关联和 YAML 分发的 CLI 管理 token，并将数据库与公网入口收敛到 NC01。 | +| v0.8 | 待本版本提交 | 2026-07-16 | 退役临时测试运行面，将产品 `master` 收敛为 NC01 稳定开发 namespace 的自动交付，并保留 `release` 独立生产交付。 | 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 @@ -28,7 +29,7 @@ | 规格状态 | 已生效 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 规格治理索引 | 本文第 9 章 | -| 实现引用版本 | v0.7 | +| 实现引用版本 | v0.8 | 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 @@ -87,10 +88,10 @@ PikaOA 终态必须同时具备： - PostgreSQL 是业务数据真相； - 文件内容通过可替换存储端口管理，元数据与哈希进入业务数据； - 配置、Secret、数据库绑定、运行目标和公网暴露均由 owning YAML 管理； - - 正式发布由 GitHub 合并触发自动 CI/CD、GitOps 和运行面收敛； - - 后端测试和调试可以先不经过 CI/CD，由 owning YAML 在现有测试节点的独立 Kubernetes namespace 创建可单步控制的运行面； - - 单步调通后，独立测试交付 consumer 跟随产品 `master`，且不改变正式发布 consumer 和正式运行面； - - 测试 Web 通过 owning YAML 声明的 hostIP 端口暴露，不进入正式公网域名。 + - 产品 `master` 合并自动交付到 NC01 稳定开发 namespace； + - 产品 `release` 合并自动交付到独立生产 namespace； + - development 与 production 分别拥有独立 PostgreSQL database/role、Secret、附件存储、GitOps branch、Argo Application 和公网 HTTPS 入口； + - 临时测试 namespace、单步测试部署入口和 test 命名控制面不作为长期交付路径。 - 首版可观测能力： - Web、CLI、API、Worker 和 CI/CD 统一传播 W3C trace context； - Go 服务从第一版接入 OpenTelemetry traces、metrics 和结构化日志关联； @@ -109,7 +110,7 @@ PikaOA 终态必须同时具备： - CLI、Web 工作台、HTTP API、健康接口和异步任务入口。 - OpenTelemetry Collector 接入、Prometheus 指标、结构化日志和 trace/metric 关联。 - PostgreSQL、Kubernetes namespace、Secret、CI/CD、GitOps 和公网 HTTPS。 -- 现有 NC01 k3s 独立 namespace 内的 YAML-first 后端运行面、NC01 host PostgreSQL 独立测试库、hostIP 暴露、可观测性和清理入口。 +- 现有 NC01 k3s 中相互隔离的 development 与 production namespace、NC01 host PostgreSQL 独立数据库、YAML-first 自动交付、公网 HTTPS 和可观测性入口。 ### 2.4 范围外 @@ -137,7 +138,7 @@ PikaOA 终态必须同时具备： | Typed ID 关联 | 资源只保存关联对象的资源类型和全局唯一 ID，不复制关联对象私有载荷，也不以嵌套路径或表级从属关系定义资源身份。 | | 模块 | 具有独立领域边界、权限、迁移、API、事件和前端入口的可插拔业务能力。 | | 领域事件 | 模块完成业务事务后写入的结构化事实，用于同进程订阅或异步扩展。 | -| 测试运行面 | 与正式 namespace 隔离，由 YAML 在现有测试节点上声明并可通过受控 CLI 单步部署、查询和停止的 API、Worker、Web 与测试依赖集合。 | +| 开发运行面 | 与 production namespace 隔离，由产品 `master` 合并自动驱动 PaC、Tekton、GitOps 和 Argo 收敛的长期 API、Worker、Web、附件与数据运行面。 | | 导入预览 | 对上传 PDF 执行有界文本提取和字段解析后返回的非持久化、可编辑草稿；预览不是合同、合同版本、发票或附件业务事实。 | | 提取器 | 通过稳定端口读取 PDF 并返回文本、页数、方法和置信度的可替换实现；首选原生文本，OCR 作为可选 provider。 | @@ -324,24 +325,25 @@ sequenceDiagram 导入预览不得持久化 PDF、提取文本或业务字段。只有用户校对确认后，客户端才调用现有业务创建 API；业务对象创建成功后，原 PDF 通过附件 API 生成独立附件资源，并通过 `contract-version` 或 `invoice` typed ID 关联。数字原生 PDF 由原生文本提取器处理；扫描 PDF 在 OCR provider 可用时尝试 OCR，否则返回 `manual_review_required`、`blocking=false`，同时保留空白或部分预填草稿供用户完成校对。 -### 5.6 正式发布与临时测试数据流 +### 5.6 Development 与 production 自动交付数据流 ```mermaid flowchart LR - G[GitHub 目标分支合并] --> C[PaC 与 Tekton] - C --> A[GitOps 与 Argo] - A --> P[正式 PikaOA namespace] - Y[config/pikaoa.yaml testRuntime] --> T[pikaoa test-target] - T --> K[NC01 独立测试 namespace] - K --> D[(NC01 host PostgreSQL 独立测试库)] - K --> O[OTel 与 Prometheus] - K --> H[NC01 hostIP YAML 端口] - M[产品 master 合并] --> Q[独立测试交付 consumer] - Q --> K - T --> X[受控停止测试工作负载] + M[产品 master 合并] --> DC[Development PaC 与 Tekton] + DC --> DG[Development GitOps 与 Argo] + DG --> DN[NC01 PikaOA development namespace] + DN --> DD[(NC01 host PostgreSQL development database)] + DN --> DE[oa-dev.hwpod.com] + R[产品 release 合并] --> PC[Production PaC 与 Tekton] + PC --> PG[Production GitOps 与 Argo] + PG --> PN[NC01 PikaOA production namespace] + PN --> PD[(NC01 host PostgreSQL production database)] + PN --> PE[oa.hwpod.com] + DN --> O[OTel 与 Prometheus] + PN --> O ``` -正式发布与测试运行面是职责隔离的两条路径。正式发布的 source authority、镜像、数据库、Secret、公网入口和运行 namespace 只由正式交付配置管理。测试运行面只消费 owning YAML 明确声明的现有测试 target、独立 namespace、commit-pinned 镜像、NC01 独立测试数据库与角色、测试 Secret 和 hostIP 端口；它不得读取、修改或清理正式交付对象。测试运行面先允许通过受控 CLI 单步调通，随后由独立测试 consumer 跟随产品 `master` 自动更新；两种方式必须共享同一 owning YAML，不得形成第二份运行配置真相。 +Development 与 production 是职责隔离的两条长期自动交付路径。`master` 只能更新 development consumer、GitOps branch、Argo Application、namespace、数据库、Secret、附件存储和 `oa-dev.hwpod.com`；`release` 只能更新对应 production 对象和 `oa.hwpod.com`。两条路径共享模块架构与通用 renderer，但不共享可变数据或运行对象。临时 test target、手工 PipelineRun、人工 Argo sync 和第二 source authority 不属于目标数据流。 ## 6. 全局原子需求 @@ -480,6 +482,7 @@ GitHub 目标分支合并必须自动驱动 Gitea 受控镜像、不可变快照 接受标准包括： - Web、API 和 Worker 在同一独立 namespace 内运行； +- `master` 与 `release` 分别只更新 development 与 production namespace； - API 直接连接 YAML 声明的 host PostgreSQL； - 运行面 Secret 只显示对象、key、presence 和 fingerprint； - 健康接口证明进程、数据库和迁移状态； @@ -536,29 +539,28 @@ Prometheus 必须覆盖： Web、API、Worker 和 CI/CD 必须输出结构化日志、健康状态和 trace 上下文。源码版本、镜像版本和 API 版本漂移只能形成非阻塞 warning，不得阻塞可安全解释的用户业务。 -### 6.13 PIKAOA-L0-REQ-013 YAML-first 独立测试运行面 +### 6.13 PIKAOA-L0-REQ-013 YAML-first 稳定开发运行面 -PikaOA 后端测试和调试必须支持在接入自动交付前，通过受控 CLI 单步部署 Kubernetes 测试运行面。该运行面只能部署到 owning YAML 明确声明的测试 target 和独立 namespace；未声明、零匹配或多匹配时，受控入口必须在连接远端前返回 `configured=false` 或 typed blocker，并保持 `mutation=false`。测试 target 可以复用现有 k3s 节点，但不得复用正式 namespace、正式数据库角色、正式 Secret 或正式公网暴露。 +PikaOA 必须在 NC01 k3s 中维护与 production 隔离的稳定 development 运行面。Development 只由产品 `master` 合并驱动自动 CI/CD、GitOps 和 Argo 收敛，不保留临时 test target、单步直写部署或第二 source authority。 -测试 target 必须由 owning YAML 声明： +Development target 必须由 owning YAML 声明： -- 节点、route、固定测试 namespace、停止与清理策略； -- 源码仓库、源码提交和 commit-pinned API、Worker、迁移镜像； -- NC01 host PostgreSQL 中独立测试 database、role、Secret export 和受控连接来源； -- namespace-local 附件存储、健康探针、OTel endpoint、Prometheus 抓取和 Web 工作负载； -- hostIP、空闲端口和 Kubernetes Service 暴露方式； -- 跟随产品 `master` 的独立测试交付 consumer 与 source authority； -- 正式 namespace 保护集合和对象所有权标签。 +- 节点、route、固定 development namespace 和独立附件存储； +- 源码仓库、`master` branch、不可变 source snapshot 和 commit-pinned API、Worker、Web、迁移镜像； +- NC01 host PostgreSQL 中独立 development database、role、Secret export 和受控连接来源； +- 健康探针、OTel endpoint、Prometheus 抓取和 Web 工作负载； +- 独立 GitOps branch、Argo Application、PaC consumer、ServiceAccount 和 Secret； +- `oa-dev.hwpod.com` 公网 HTTPS exposure 及共享 public-edge 引用； +- production namespace、数据库、Secret、GitOps branch、Argo Application 和公网入口保护边界。 接受标准包括： -- `plan` 只读渲染目标、测试 namespace、镜像提交、数据库/Secret presence、hostIP 端口、可观测性和保护集合； -- `start` 只在显式确认后创建或更新固定测试 namespace，并在 API、Worker 和 Web ready 前完成数据库迁移； -- `status` 返回迁移、API、Worker、Web、外部测试 PostgreSQL、hostIP 入口、OTel 和 Prometheus 的有界状态； -- `stop` 只停止或删除 target、namespace 和 managed-by 标签同时匹配的测试对象，不触碰其他 namespace； -- 测试运行面连接 NC01 host PostgreSQL 中独立测试 database/role，不复用正式数据库凭据、正式 Secret 或正式公网入口，也不改变正式发布 source authority； -- 单步验收通过后，测试 consumer 的正常触发只来自产品 `master` 合并，且只更新同一测试 namespace； -- 配置一致性、版本漂移和 OTel exporter 失败只产生 `blocking=false` warning，Secret 缺失或 namespace 所有权不安全仍在 mutation 前失败。 +- 产品 `master` 合并产生唯一正常 webhook、PaC、Tekton、GitOps 和 Argo 自动事件； +- initializer 在 API、Worker 和 Web rollout 前初始化 development database； +- API、Worker、Web、附件 PVC、外部 development PostgreSQL、OTel、Prometheus 和 `oa-dev.hwpod.com` 均可通过受控状态或原入口验收； +- development 运行面不读取或修改 production 数据库凭据、Secret、附件、namespace、GitOps branch、Argo Application或公网入口； +- 旧 test namespace 和控制面对象只在 development 自动链健康后受控退役，旧数据直接丢弃且不迁移； +- 配置一致性、版本漂移和 OTel exporter 失败只产生 `blocking=false` warning，Secret 缺失或 mutation target 不安全仍在写入前失败。 ### 6.14 PIKAOA-L0-REQ-014 合同与发票 PDF 导入预览 @@ -604,7 +606,7 @@ PikaOA 后端测试和调试必须支持在接入自动交付前，通过受控 ### 8.1 功能验收 - 先使用 CLI 管理员账号登录，创建普通员工、甲方分类和甲方。 -- 在测试与正式运行面通过 YAML 分发 `OA_ADMIN_TOKEN`，使用不含 session 文件的 CLI `whoami` 和管理查询证明管理员身份映射与 capability 生效。 +- 在 development 与 production 运行面通过 YAML 分发 `OA_ADMIN_TOKEN`，使用不含 session 文件的 CLI `whoami` 和管理查询证明管理员身份映射与 capability 生效。 - 通过 CLI 创建合同 v1，再创建 v2，确认 v1 保留且 v2 成为当前版本。 - 通过 CLI 在甲方维度查看合同，并按甲方分类筛选合同。 - 通过 CLI 创建关联合同 v2 的发票，确认合同、版本和甲方关系正确。 @@ -624,14 +626,15 @@ PikaOA 后端测试和调试必须支持在接入自动交付前，通过受控 ### 8.3 运行验收 - CI/CD 绑定 source commit、PipelineRun、镜像 digest、GitOps revision、Argo 状态和运行面 ready； -- 测试运行面通过 YAML 声明的现有测试 target 完成 `plan`、`start`、`status`、CLI 后端业务验证、OTel/Prometheus/Web 验证和 `stop`，不触发正式 CI/CD； -- 单步验证通过后，产品 `master` 的正常合并事件可以通过独立测试 consumer 自动更新测试 namespace； -- 测试停止后受控对象已停止或删除，正式 namespace、正式数据库、正式 Secret 和公网入口保持不变； +- 产品 `master` 的正常合并事件只通过 development consumer 自动更新 development namespace； +- 产品 `release` 的正常合并事件只通过 production consumer 自动更新 production namespace； +- development 与 production 的数据库、Secret、附件 PVC、GitOps branch、Argo Application 和公网入口相互隔离； - Web、API 和 Worker 运行在 owning YAML 声明的 namespace； - PostgreSQL 连接、迁移、附件存储和健康检查通过； - OTel Collector 接收 Web/CLI/API/Worker trace，Prometheus 抓取 API/Worker 指标； - CLI 主路径均返回可查询的 requestId/traceId，并能关联业务审计； - `https://oa.hwpod.com` 返回登录页和可用业务工作台； +- `https://oa-dev.hwpod.com` 返回当前 `master` 对应的开发工作台； - 桌面与移动浏览器完成登录、合同 PDF 导入校对、发票 PDF 导入校对、合同版本和发票废弃主路径； - 运行和验证输出不披露密码、数据库连接串、token 或附件正文。 @@ -640,5 +643,5 @@ PikaOA 后端测试和调试必须支持在接入自动交付前，通过受控 - 本规格是 PikaOA L0 长期真相。 - 稳定需求、模块边界、数据流、接口和验收口径变化先更新本规格或对应 L1 规格。 - 实现进度、当前阻塞、提交、PR、PipelineRun、截图和一次性验证进入 GitHub issue、MDTODO 报告和阶段报告。 -- 本项目新增或修改的源码文件必须在文件头部或包级文档中标注 `SPEC: PJ2026-03 PikaOA v0.7`；自动生成文件、第三方代码、纯配置、锁文件和二进制产物例外，但其生成器或 owning 配置必须可追溯。 +- 本项目新增或修改的源码文件必须在文件头部或包级文档中标注 `SPEC: PJ2026-03 PikaOA v0.8`；自动生成文件、第三方代码、纯配置、锁文件和二进制产物例外，但其生成器或 owning 配置必须可追溯。 - L1 规格按第 4.2 节编号建立；优先拆分具有独立生命周期、数据所有权或验收入口的能力域。