docs: 定义 PikaOA Temporal native 架构

2026-07-17 03:20:19 +02:00
parent 5aa1c1e72b
commit b36b500810
3 changed files with 119 additions and 26 deletions
@@ -0,0 +1,22 @@
 # R6.1 任务报告
 ## 结果
 PJ2026-03 总规格升级到 v0.9，删除 CLI 必须只经 HTTP 的旧门禁，冻结以下终态契约：
 - 同步业务通过共享 application dispatcher；CLI 默认 local，显式 `--over-api` 只切换 REST transport。
 - PostgreSQL outbox 保留事务事实，后台、可重试和长时执行统一由 Temporal workflow/activity 编排。
 - API、Temporal Worker 和 Web HMR 独立启动、观测、停止和部署；Worker 不暴露公网业务入口。
 - Native smoke 顺序固定为 local CLI、真实 workflow/activity、独立 API + `--over-api`、Web HMR；通过后只由产品 master PR merge 触发正式 development 自动交付。
 - 数据库、Temporal serviceRef/namespace/task queue、端口、PID、日志、state、超时与重试全部归 owning YAML，不增加隐藏默认、第二 authority、租约或围栏。
 ## 证据
 - 治理 Issue：https://github.com/pikasTech/unidesk/issues/2417
 - 产品 Issue：https://github.com/pikainc/pikaoa/issues/78
 - `git diff --check` 通过。
 - 定点检索确认不存在“CLI 只调用公开 HTTP API”、旧 `CLI --> API` 或 PostgreSQL ticker 作为正式 Worker authority 的残留契约。
 ## 后续
 R6.2 与 R6.3 可在本规格基线上并行；native smoke、YAML/CICD 和部署态回归继续按 R6.4-R6.6 串行收敛。
@@ -269,7 +269,7 @@
 完成 [UniDesk #2417](https://github.com/pikasTech/unidesk/issues/2417) 与 [PikaOA #78](https://github.com/pikainc/pikaoa/issues/78)：把 PikaOA 后端改造为共享 application dispatcher + Temporal workflow/activity，API 与 worker 独立；CLI 默认 local、显式 `--over-api`；Workbench 可独立启动 native API/worker/Web HMR，先完成 native smoke，再由正常 master CI/CD 回归 development 运行面，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R6_Task_Report.md)。
-### R6.1 [in_progress]
+### R6.1 [completed]
 升级 PJ2026-03 SPEC：冻结 dispatcher、Temporal、CLI local/`--over-api`、API/worker 分离、Web HMR 与 native-first/CICD 验收契约，关联 [UniDesk #2417](https://github.com/pikasTech/unidesk/issues/2417)，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R6.1_Task_Report.md)。
@@ -12,6 +12,7 @@
 | 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` 独立生产交付。 |
 | v0.9 | 待本版本提交 | 2026-07-17 | 将后台执行权威收敛到 Temporal，增加共享 application dispatcher、CLI local/`--over-api` 双模式及 API、Worker、Web HMR 独立 native 开发闭环。 |
 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
@@ -29,7 +30,7 @@
 | 规格状态 | 已生效 |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 规格治理索引 | 本文第 9 章 |
-| 实现引用版本 | v0.8 |
+| 实现引用版本 | v0.9 |
 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。
@@ -67,9 +68,10 @@ PikaOA 终态必须同时具备：
  - 统一持久化 REST 资源的 UUIDv7 全局标识和 typed ID 关联语义。
 - CLI-first 交付：
  - 每个后端业务用例先提供稳定 CLI 入口；
-  - 所有已启用模块的管理与业务功能必须具有调用公开 HTTP API 的 CLI 等价入口；
+  - 所有已启用模块的管理与业务功能必须通过共享 application dispatcher 提供 CLI 等价入口；
  - CLI 默认在本地组装 dispatcher、repository 和 Temporal client，显式 `--over-api` 才通过公开 HTTP API 调用同一 dispatcher；
  - 受控管理 CLI 优先读取由 owning YAML 分发的 `OA_ADMIN_TOKEN`，不得把 token 写入命令参数、日志或会话文件；
-  - CLI 与 Web 复用同一 HTTP API、身份、权限和业务语义；
+  - CLI local、CLI `--over-api`、Web 与 API 复用同一身份、权限、应用用例和业务语义；
  - Web 与后端可以依据已冻结的资源和 API 契约并行开发；
  - 最终集成验收先以 CLI 证明后端业务语义，再由 Web 通过同一公开 HTTP API 重复等价业务流；
  - 自动化和人工排障不依赖浏览器才能完成核心业务闭环。
@@ -85,6 +87,7 @@ PikaOA 终态必须同时具备：
  - 按不同甲方及其分类筛选合同、发票和统计摘要。
 - 企业交付能力：
  - Web、业务 API 和异步 Worker 是可独立扩缩和发布的工作负载；
  - Temporal 是后台、可重试和长时执行的唯一编排权威，Worker 只注册 workflow/activity 并消费 owning task queue；
  - PostgreSQL 是业务数据真相；
  - 文件内容通过可替换存储端口管理，元数据与哈希进入业务数据；
  - 配置、Secret、数据库绑定、运行目标和公网暴露均由 owning YAML 管理；
@@ -108,6 +111,7 @@ PikaOA 终态必须同时具备：
 - 合同与发票 PDF 导入预览、可替换文本提取器、可编辑校对草稿和确认后附件关联。
 - 审计记录、领域事件、模块注册和模块级导航。
 - CLI、Web 工作台、HTTP API、健康接口和异步任务入口。
 - Temporal workflow/activity、native API/Worker/Web HMR 生命周期与 local/`--over-api` 等价验证入口。
 - OpenTelemetry Collector 接入、Prometheus 指标、结构化日志和 trace/metric 关联。
 - PostgreSQL、Kubernetes namespace、Secret、CI/CD、GitOps 和公网 HTTPS。
 - 现有 NC01 k3s 中相互隔离的 development 与 production namespace、NC01 host PostgreSQL 独立数据库、YAML-first 自动交付、公网 HTTPS 和可观测性入口。
@@ -197,13 +201,15 @@ flowchart LR
  U[管理员与员工] --> W[Vue Web 工作台]
  U --> CLI[PikaOA CLI]
  W --> A[Go 业务 API]
-  CLI --> A
+  CLI -->|local| D[Application Dispatcher]
-  A --> I[组织权限模块]
+  CLI -->|--over-api| A
-  A --> P[伙伴主数据模块]
+  A --> D
-  A --> C[合同模块]
+  D --> I[组织权限模块]
-  A --> F[发票模块]
+  D --> P[伙伴主数据模块]
-  A --> DI[文档导入预览]
+  D --> C[合同模块]
-  A --> K[平台内核]
+  D --> F[发票模块]
  D --> DI[文档导入预览]
  D --> K[平台内核]
  I --> DB[(PostgreSQL)]
  P --> DB
  C --> DB
@@ -212,9 +218,11 @@ flowchart LR
  EX --> NT[原生文本提取器]
  EX -. 可选 .-> OCR[OCR provider]
  K --> DB
-  A --> S[文件存储端口]
+  D --> S[文件存储端口]
-  A --> O[(事务 Outbox)]
+  D --> O[(事务 Outbox)]
-  O --> J[Go Worker]
+  D --> T[Temporal Frontend]
  T --> J[Go Temporal Worker]
  J --> O
  J --> X[后续通知、索引与集成适配器]
  W --> OT[OpenTelemetry Collector]
  CLI --> OT
@@ -230,11 +238,13 @@ flowchart LR
 - Web：使用与 HWLAB v0.3 同族的 Vue 3、Vite、TypeScript、Vue Router、Pinia 和 Tailwind 技术栈；
 - API：使用成熟 Go HTTP/服务框架、PostgreSQL 驱动、迁移工具、RBAC 库和 OpenAPI 工具；
- Worker：复用 Go 领域与应用层，消费 PostgreSQL outbox，承载非请求内任务。
+- Worker：复用 Go 领域与应用层，注册 Temporal workflow/activity，消费 owning task queue 并承载非请求内任务。
 CLI 是后端业务的第一用户入口：
- 使用与 Web 相同的公开 HTTP API，不通过数据库直连或内部 manager 绕过业务语义；
+- 默认本地模式通过共享 composition root 直接调用 application dispatcher，不依赖 API 进程；
 - 显式 `--over-api` 通过与 Web 相同的公开 HTTP API 调用同一 dispatcher；
 - local 与 `--over-api` 只能切换 transport，不得复制 repository、领域规则、权限或输出格式；
 - 默认输出适合人工扫描的紧凑文本，机器调用显式请求 JSON；
 - 长任务使用提交与短轮询，不保持无界阻塞连接；
 - 输出包含请求标识和 traceId，但不显示密码、token、完整数据库连接串或附件正文；
@@ -253,15 +263,18 @@ CLI 是后端业务的第一用户入口：
 ```mermaid
 flowchart TD
  R[用户请求] --> G[认证、授权与输入校验]
-  G --> M[目标模块应用用例]
+  G --> AD[Application Dispatcher]
  AD --> M[目标模块应用用例]
  M --> T[领域规则与事务]
-  T --> D[(模块拥有的数据表)]
+  T --> DB[(模块拥有的数据表)]
  T --> A[(统一审计记录)]
  T --> O[(事务 Outbox)]
-  D --> Q[查询投影与分页]
+  DB --> Q[查询投影与分页]
  Q --> V[Web/API 响应]
-  O --> W[异步 Worker]
+  O --> C[Temporal Client]
-  W --> E[扩展适配器]
+  C --> W[Temporal Workflow]
  W --> A2[Activity]
  A2 --> E[扩展适配器]
 ```
 ### 5.3 合同多版本时序
@@ -345,6 +358,32 @@ flowchart LR
 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 不属于目标数据流。
 ### 5.7 Native-first 开发数据流
 ```mermaid
 flowchart LR
  C[PikaOA CLI] -->|默认 local| D[Application Dispatcher]
  C -->|--over-api| A[Native API]
  A --> D
  D --> P[(NC01 host PostgreSQL)]
  D --> T[Temporal Frontend]
  T --> WK[Native Temporal Worker]
  WK --> P
  V[Vite HMR Web] --> A
  S[Native Smoke] --> C
  S --> V
  M[产品 master PR merge] --> CI[PaC/Tekton/GitOps/Argo]
 ```
 Native 开发必须先于正式交付完成短反馈闭环：
 - API、Temporal worker 和 Vite HMR Web 使用独立进程、PID、日志、端口、健康状态和停止入口；
 - CLI local 不依赖 API 进程，但使用与 API 相同的 composition root、dispatcher、repository 和授权语义；
 - `--over-api` 只替换 transport，不改变命令、输入、输出、错误或业务事务语义；
 - native worker 和 API 只连接 owning YAML 选择的真实 PostgreSQL、Temporal 和可观测基础设施，不建立临时数据库或第二编排服务；
 - native smoke 依次验证 local CLI、Temporal workflow/activity、独立 API + `--over-api` 和 Web HMR；
 - native 验收完成后只合并一次产品 PR，由正常 `master` 自动链完成 development 交付，不用反复 rollout 代替本地迭代。
 ## 6. 全局原子需求
 ### 6.1 PIKAOA-L0-REQ-001 模块化平台内核
@@ -482,8 +521,10 @@ GitHub 目标分支合并必须自动驱动 Gitea 受控镜像、不可变快照
 接受标准包括：
 - Web、API 和 Worker 在同一独立 namespace 内运行；
 - API 与 Worker 使用独立 Deployment、Service/健康端点、资源和 rollout；Worker 不提供公网业务入口；
 - `master` 与 `release` 分别只更新 development 与 production namespace；
 - API 直接连接 YAML 声明的 host PostgreSQL；
 - API 与 Worker 通过 YAML 声明的 Temporal serviceRef、logical namespace 和 task queue 协作；
 - 运行面 Secret 只显示对象、key、presence 和 fingerprint；
 - 健康接口证明进程、数据库和迁移状态；
 - 公网 HTTPS 入口通过 YAML 声明的 NC01 edge 暴露。
@@ -497,6 +538,7 @@ OpenTelemetry 必须覆盖：
 - Web 和 CLI 发起请求时生成或传播 W3C `traceparent`/`baggage`；
 - API HTTP server/client、认证、授权、领域用例、PDF 提取、PostgreSQL、附件存储和 outbox 写入；
 - Worker 消费、重试、处理结果和下游适配器；
 - Temporal client、workflow、activity、task queue、workflow/run ID、重试和终态；
 - CI/CD 从 source、build、artifact、GitOps 到 runtime health 的同一 trace 上下文；
 - 结构化日志中的 traceId、spanId、service、module、operation、result 和稳定错误码。
@@ -507,7 +549,7 @@ Prometheus 必须覆盖：
 - 合同创建、版本创建、发票创建、发票废弃、导入预览和提取结果等领域动作计数与延迟；
 - PostgreSQL连接池、查询延迟和迁移状态；
 - outbox pending、oldest age、processed、retry 和 failed；
- Worker 队列、处理耗时和错误；
+- Temporal workflow/activity started、completed、failed、retry、task queue backlog 和处理耗时；
 - Go runtime、进程和健康状态。
 可观测属性不得包含密码、token、完整合同正文、附件正文、个人敏感字段或无界业务载荷。甲方、合同、发票和员工只在明确需要下钻时使用不可逆或受权限保护的稳定标识，禁止把高基数自由文本作为 metric label。
@@ -522,18 +564,20 @@ Prometheus 必须覆盖：
 ### 6.11 PIKAOA-L0-REQ-011 CLI-first 集成验收
-每个后端业务能力必须通过 `pikaoa` CLI 验收。所有启用模块的管理动作、业务写入和查询必须有 CLI 等价入口；CLI 通过 owning YAML 分发的 `OA_ADMIN_TOKEN` 调用公开 HTTP API。Web 可以依据已冻结的资源与 API 契约并行开发，但最终必须与 CLI 调用同一公开 HTTP API、使用同一身份与权限语义，并覆盖员工、伙伴、合同版本、发票废弃、审计和模块枚举的等价业务语义。
+每个后端业务能力必须通过 `pikaoa` CLI 验收。所有启用模块的管理动作、业务写入和查询必须由共享 application dispatcher 提供 CLI 等价入口。CLI 默认使用 local transport，显式 `--over-api` 使用公开 HTTP API；两者必须复用同一身份、权限、用例、repository 和错误语义。Web 可以依据冻结的资源与 API 契约并行开发，但最终必须通过同一 HTTP adapter 重复等价业务流。
 接受标准包括：
 - CLI 支持登录、当前身份、员工管理、伙伴/分类管理、合同 CRUD/版本历史、合同与发票 PDF `import-preview`、发票 CRUD/废弃、附件上传、审计查询和健康/metrics 摘要；
 - 默认文本输出有界且非空，显式 JSON 输出为单一合法 JSON；
 - local 是默认模式且不要求 API 进程；`--over-api` 只能切换 transport，不能启用另一套业务实现；
 - 同一命令在 local 与 `--over-api` 下返回同构资源、warning、requestId/traceId 和 typed error；
 - `OA_ADMIN_TOKEN` 存在时 CLI 不要求 session 文件并优先使用该环境凭据；不存在时继续使用显式登录建立的短期 session；
 - CLI 帮助、错误、JSON、trace、日志和进程参数不得披露 `OA_ADMIN_TOKEN` 值；
 - 业务失败返回稳定非零退出码和 typed error，不以 traceback 或空输出代替；
 - CLI 业务成功同时返回资源标识、requestId 和 traceId；
 - 前后端开发不互设启动门禁；后端 CLI 尚未通过或 API 尚未收敛时，集成差异只能形成非阻塞 warning，不能宣称对应业务能力已经完成最终验收；
- 最终验收必须先证明 CLI 后端业务语义，再由 Web 通过同一公开 HTTP API 重复等价业务流并比对结果。
+- 最终验收必须依次证明 local CLI、Temporal worker、CLI `--over-api` 和 Web HTTP 业务流，并比对结果。
 ### 6.12 PIKAOA-L0-REQ-012 非阻塞版本告警
@@ -549,6 +593,7 @@ Development target 必须由 owning YAML 声明：
 - 源码仓库、`master` branch、不可变 source snapshot 和 commit-pinned API、Worker、Web、迁移镜像；
 - NC01 host PostgreSQL 中独立 development database、role、Secret export 和受控连接来源；
 - 健康探针、OTel endpoint、Prometheus 抓取和 Web 工作负载；
 - Temporal serviceRef、logical namespace、task queue、workflow/activity 超时与重试，以及 API/Worker 独立健康探针；
 - 独立 GitOps branch、Argo Application、PaC consumer、ServiceAccount 和 Secret；
 - `oa-dev.hwpod.com` 公网 HTTPS exposure 及共享 public-edge 引用；
 - production namespace、数据库、Secret、GitOps branch、Argo Application 和公网入口保护边界。
@@ -586,9 +631,33 @@ Development target 必须由 owning YAML 声明：
 - 合同 PDF 关联新建合同的 `contract-version` ID，发票 PDF 关联 `invoice` ID，任何一方都不成为另一方的隶属对象；
 - 导入预览 span 和 metric 只使用低基数文档类型、提取方法、结果和 manual-review 属性，不记录 PDF 正文、企业名称、税号或业务号码。
 ### 6.15 PIKAOA-L0-REQ-015 Temporal 与 native 敏捷开发
 PikaOA 的后台、可重试和长时执行必须由 Temporal workflow/activity 承担。PostgreSQL outbox 保留为事务内领域事件事实，但 ticker、定时轮询器或 API 内 goroutine 不得成为正式执行 authority。Worker 必须独立注册 workflow/activity 并消费 owning YAML 声明的 task queue。
 Native 开发必须由仓库正式 CLI 提供非阻塞生命周期入口：
 - `native start` 分别启动 API、Worker 或 Web HMR，并立即返回稳定 process ID、PID、端口、日志和 status 命令；
 - `native status`、`native logs` 和 `native stop` 对每个组件独立工作，不用一个进程的失败覆盖其他组件事实；
 - 端口占用、配置缺失、进程退出和依赖不可用必须返回 typed error 与非空有界输出；
 - PID、日志和状态只写入 owning YAML 声明的 state 目录，不扫描或终止不属于当前 PikaOA native 实例的进程；
 - Vite HMR 通过 native 配置代理 API，不要求先构建 Web 镜像或部署 Kubernetes；
 - native 依赖地址、数据库 configRef、Temporal serviceRef、task queue、端口、日志和 state 目录均来自 owning YAML，不使用隐藏默认或环境 fallback。
 接受标准包括：
 - native worker 消费一个调用至少一个 activity 的真实 workflow，client 校验精确结果并确认 worker 可停止；
 - 默认 CLI 在 API 未启动时完成数据库 CRUD 和 workflow smoke；
 - 独立 native API 启动后，同一组 CLI 命令增加 `--over-api` 即可通过；
 - 独立 Web HMR 启动后，受控 web-probe custom/local smoke 验证真实 DOM、交互和 API 请求；
 - native smoke 通过后，正常产品 PR merge 自动交付独立 API/Worker/Web 工作负载，部署态再次通过同一 CLI 与 Web 验收；
 - 任务报告记录 native 迭代次数、native 墙钟时间、正式流水线次数、流水线总耗时、交付墙钟时间和 rollout 次数；缺失资源计量时不得虚构成本或提速比例。
 ## 7. API、数据与兼容边界
 - 外部 HTTP API 使用 `/api/v1` 版本前缀。
 - REST adapter 只负责 HTTP envelope、鉴权、状态码和 correlation；业务判断全部委派给共享 application dispatcher。
 - Temporal workflow/activity 使用稳定版本名和显式 task queue；workflow 参数只传递有界 typed ID、命令和 correlation，不复制无界附件或 Secret。
 - 模块路由使用稳定复数资源名和标准分页参数。
 - 写请求返回稳定业务错误码、字段路径和可读消息。
 - 所有持久化 REST 资源 ID 使用服务端生成、不可枚举、不可变的 UUIDv7。
@@ -614,7 +683,7 @@ Development target 必须由 owning YAML 声明：
 - 通过 CLI 对扫描合同 PDF 执行 `import-preview`，确认无有效原生文本时返回非阻塞人工校对 warning，手工补齐后创建合同并把原 PDF 关联到合同版本 ID。
 - 通过 CLI 标记发票废弃，确认原因和审计存在，默认有效汇总不包含该发票。
 - 使用 CLI 普通员工账号确认允许的业务操作可用、管理员操作不可用。
- Web 与后端可以并行实现；每项功能必须先使用 `OA_ADMIN_TOKEN` 完成 CLI 后端验收，再用 Web 通过同一公开 HTTP API 重复业务主路径并比对结果。
+- Web 与后端可以并行实现；每项功能必须先使用 `OA_ADMIN_TOKEN` 完成 local CLI 和 Temporal worker 验收，再用 `--over-api` 与 Web 重复业务主路径并比对结果。
 ### 8.2 扩展性验收
@@ -630,7 +699,9 @@ Development target 必须由 owning YAML 声明：
 - 产品 `release` 的正常合并事件只通过 production consumer 自动更新 production namespace；
 - development 与 production 的数据库、Secret、附件 PVC、GitOps branch、Argo Application 和公网入口相互隔离；
 - Web、API 和 Worker 运行在 owning YAML 声明的 namespace；
 - API 与 Temporal Worker 独立 ready，Worker 不提供公网业务 Service；
 - PostgreSQL 连接、迁移、附件存储和健康检查通过；
 - Temporal logical namespace、task queue、workflow/activity 与 worker readiness 通过；
 - OTel Collector 接收 Web/CLI/API/Worker trace，Prometheus 抓取 API/Worker 指标；
 - CLI 主路径均返回可查询的 requestId/traceId，并能关联业务审计；
 - `https://oa.hwpod.com` 返回登录页和可用业务工作台；
@@ -643,5 +714,5 @@ Development target 必须由 owning YAML 声明：
 - 本规格是 PikaOA L0 长期真相。
 - 稳定需求、模块边界、数据流、接口和验收口径变化先更新本规格或对应 L1 规格。
 - 实现进度、当前阻塞、提交、PR、PipelineRun、截图和一次性验证进入 GitHub issue、MDTODO 报告和阶段报告。
- 本项目新增或修改的源码文件必须在文件头部或包级文档中标注 `SPEC: PJ2026-03 PikaOA v0.8`；自动生成文件、第三方代码、纯配置、锁文件和二进制产物例外，但其生成器或 owning 配置必须可追溯。
+- 本项目新增或修改的源码文件必须在文件头部或包级文档中标注 `SPEC: PJ2026-03 PikaOA v0.9`；自动生成文件、第三方代码、纯配置、锁文件和二进制产物例外，但其生成器或 owning 配置必须可追溯。
 - L1 规格按第 4.2 节编号建立；优先拆分具有独立生命周期、数据所有权或验收入口的能力域。