docs: 固化 PikaOA 稳定开发运行面规格

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 节编号建立；优先拆分具有独立生命周期、数据所有权或验收入口的能力域。