pikasTech-unidesk/docs/reference/pikaoa.md

PikaOA 运行与交付

配置真相

• PikaOA 运维配置的唯一真相是 config/pikaoa.yaml。
• 稳定开发运行面由 config/pikaoa.yaml#developmentRuntime.targets.NC01 声明：
  • source branch：master；
  • consumer：pikaoa-dev-nc01；
  • runtime namespace：pikaoa-dev；
  • CI namespace：pikaoa-ci；
  • GitOps branch：nc01-pikaoa-dev-gitops；
  • Argo Application：pikaoa-dev-nc01；
  • 公网入口：https://oa-dev.hwpod.com；
  • NodePort：32080。
• 生产运行面由 config/pikaoa.yaml#releaseRuntime.targets.NC01 声明：
  • source branch：release；
  • consumer：pikaoa-nc01；
  • runtime namespace：pikaoa；
  • CI namespace：pikaoa-ci；
  • GitOps branch：nc01-pikaoa-gitops；
  • Argo Application：pikaoa-nc01；
  • 公网入口：https://oa.hwpod.com；
  • NodePort：32096。
• development 与 production 必须保持独立：
  • PostgreSQL role/database；
  • Kubernetes Secret；
  • 附件 PVC；
  • GitOps branch；
  • Argo Application；
  • namespace 与公网入口。
• 已退役路径不得恢复：
  • testRuntime；
  • pikaoa-test namespace；
  • pikaoa-test-nc01 consumer/Repository；
  • pikaoa test-target CLI；
  • 动态测试 namespace；
  • namespace-local PostgreSQL。

对象与模块边界

• PikaOA 是可扩展企业办公平台：
  • 模块通过 descriptor 注册；
  • 模块拥有自己的 schema 初始化、HTTP route、outbox event 和 worker；
  • 新模块复用 identity、附件、审计、可观测性和 API 错误合同。
• 业务对象均为平级 REST 资源：
  • 伙伴、伙伴分类、合同、合同版本、发票和附件都使用服务端生成的 UUIDv7；
  • 对象之间只保存 typed ID 关联；
  • 不把伙伴、合同或发票建模为另一个对象的从属资源。
• 合同版本关系：
  • 每个合同版本拥有独立全局 ID；
  • contractId、previousVersionId 和当前版本投影建立版本链；
  • 发票可分别关联合同 ID 与合同版本 ID。
• 首版审计与一致性：
  • 跨模块关联未完成一致性核验时只返回 blocking=false warning；
  • 完整身份/RBAC、严格审计门禁和强一致性校验不作为 MVP 上线前置。

数据库与 Secret

• development 与 production 都使用 NC01 host PostgreSQL：
  • owning YAML：config/platform-db/postgres-nc01.yaml；
  • development role/database：pikaoa_dev；
  • production role/database：pikaoa；
  • 业务 schema：pikaoa；
  • development export：platform-infra/pikaoa-dev.env；
  • production export：platform-infra/pikaoa.env。
• 不迁移旧 test 数据：
  • development 使用全新 role/database；
  • 旧 test 数据、namespace 和运行对象可直接丢弃；
  • 不增加兼容、回填或双写路径。
• Secret 分发的唯一真相是 config/secrets-distribution.yaml：
  • development scope：pikaoa-dev；
  • development Secret：pikaoa-dev-runtime；
  • production scope：pikaoa；
  • production Secret：pikaoa-runtime。
• runtime Secret 只包含敏感键：
  • DATABASE_URL；
  • PIKAOA_SESSION_SECRET；
  • OA_ADMIN_TOKEN；
  • PIKAOA_BOOTSTRAP_ADMIN_PASSWORD；
  • PIKAOA_BOOTSTRAP_EMPLOYEE_PASSWORD。
• 非敏感 pikaoa.yaml 由 pikaoa-runtime-config ConfigMap 提供：
  • API、Worker 和 initializer 从 ConfigMap 挂载配置；
  • DATABASE_URL 在应用校验前由环境变量覆盖空配置值；
  • 禁止把 pikaoa.yaml 写入 runtime Secret。
• Secret 来源和运行面输出必须脱敏：
  • 只披露 sourceRef、key、presence、fingerprint 和摘要；
  • 禁止从 Kubernetes Secret、Pod 环境、日志或数据库反解值；
  • 禁止在命令参数、issue、截图或报告中写入 token、密码或完整 DSN。

首次引导

• 首次创建 development 数据库与导出：

  bun scripts/cli.ts platform-db postgres plan \
    --config config/platform-db/postgres-nc01.yaml
  bun scripts/cli.ts platform-db postgres apply \
    --config config/platform-db/postgres-nc01.yaml \
    --confirm --wait
  bun scripts/cli.ts platform-db postgres export-secrets \
    --config config/platform-db/postgres-nc01.yaml \
    --confirm
  

• 首次同步 development Secret：

  bun scripts/cli.ts secrets plan \
    --config config/secrets-distribution.yaml \
    --scope pikaoa-dev
  bun scripts/cli.ts secrets sync \
    --config config/secrets-distribution.yaml \
    --scope pikaoa-dev \
    --confirm
  

• PaC consumer 只在首次引导时执行 bootstrap：

  bun scripts/cli.ts platform-infra pipelines-as-code bootstrap \
    --target NC01 \
    --consumer pikaoa-dev-nc01 \
    --dry-run
  bun scripts/cli.ts platform-infra pipelines-as-code bootstrap \
    --target NC01 \
    --consumer pikaoa-dev-nc01 \
    --confirm
  

• bootstrap 完成后不得再次用于 source delivery、恢复或补跑。

• 旧 Repository CR 与新声明使用同一 URL 时：

  • 先精确确认旧对象属于已退役 PikaOA test consumer；
  • 只退役该旧对象；
  • 立即由已合并 owning YAML 的 bootstrap 创建新对象；
  • 禁止修改共享 PaC controller、admission 或其他 consumer。

自动交付

• development 和 production 都使用 PaC 自动交付：

  • GitHub source PR merge；
  • GitHub webhook；
  • Gitea controlled mirror 与 immutable snapshot；
  • PaC/Tekton；
  • GitOps branch；
  • Argo 自动同步；
  • runtime readiness 与 /healthz。

• 正常交付的唯一触发：

  • development：合并 pikainc/pikaoa@master PR；
  • production：合并 pikainc/pikaoa@release PR。

• .tekton 制品必须由 UniDesk source-artifact renderer 生成：

  bun scripts/cli.ts platform-infra pipelines-as-code source-artifact write \
    --target NC01 \
    --consumer pikaoa-dev-nc01 \
    --source-worktree <clean-pikaoa-worktree> \
    --confirm --json
  bun scripts/cli.ts platform-infra pipelines-as-code source-artifact check \
    --target NC01 \
    --consumer pikaoa-dev-nc01 \
    --source-worktree <clean-pikaoa-worktree> \
    --json
  

• 自动链禁止人工补齐：

  • 不人工创建 PipelineRun；
  • 不人工 mirror sync；
  • 不人工 Argo sync/refresh；
  • 不在 source PR merge 后再次 bootstrap/apply。

• 自动链失败时：

  • 使用 platform-infra pipelines-as-code status|history|debug-step 只读归因；
  • consumer 私有缺陷回到 owning YAML、renderer 或 source artifact 修复；
  • 共享 PaC/controller/admission 故障只报告，不在 PikaOA 任务中修改公共 CI/CD 基础设施。

公网入口

• 公网入口的聚合真相是 config/platform-infra/public-edge.yaml#targets.NC01。

• 产品 hostname、NodePort 和 health path 只从 config/pikaoa.yaml 的 configRef/path 解析。

• 受控入口：

  bun scripts/cli.ts platform-infra public-edge plan --target NC01
  bun scripts/cli.ts platform-infra public-edge apply --target NC01 --dry-run
  bun scripts/cli.ts platform-infra public-edge status --target NC01
  

• 公网入口 mutation 只由 master merge 触发的唯一 PaC authority执行；PikaOA任务和 L1 会话不得执行 apply --confirm、内部 reconcile 或直接改写 Caddy。

• NC01 共享 edge 约束：

  • 复用唯一 Caddy 80/443 listener；
  • 不访问 PK01；
  • 保留 UDP 443；
  • 单站探针失败只输出 blocking=false warning；
  • 禁止为 PikaOA 启动第二个独立 80/443 proxy。

CLI-first 验收

• 所有业务功能先使用 PikaOA CLI 验收：
  • CLI 只调用与 Web 相同的公开 HTTP API；
  • development endpoint 使用 https://oa-dev.hwpod.com；
  • production endpoint 使用 https://oa.hwpod.com；
  • OA_ADMIN_TOKEN 只通过进程环境注入，不创建 session 文件；
  • CLI 输出不得打印 token。
• 最小顺序：
  • health；
  • health --ready；
  • metrics；
  • modules；
  • whoami；
  • 员工与角色；
  • 伙伴分类与伙伴；
  • 合同 v1；
  • 合同 v2 版本链；
  • 发票关联与废弃；
  • 附件与审计；
  • 合同和发票 PDF import-preview。
• PDF import-preview 约束：
  • 原 PDF 作为附件保留；
  • 自动提取结果包含置信度与 manualReviewRequired；
  • 用户可人工校对后再创建或更新业务对象；
  • 提取 warning 不阻塞手工校对流程。
• CLI 通过后才进入 Web 验收：
  • 只使用 $unidesk-webdev 的 web-probe；
  • 禁止裸 Playwright；
  • 验证管理员登录、合同/发票/PDF 校对主路径和移动视口。

可观测性

• OTel 从第一版启用：
  • API、Worker 与 CLI 使用 OpenTelemetry；
  • runtime endpoint 由 config/pikaoa.yaml 声明；
  • exporter 失败只记录 blocking=false warning；
  • trace 不记录 Secret、完整 DSN、PDF 内容或业务敏感字段。
• Prometheus 从第一版启用：
  • API 与 Worker 使用 owning YAML 的 label selector 和 scrape annotation；
  • API 与 Worker 都提供 /metrics；
  • 重点核验数据库、迁移、HTTP、pgx pool、Worker 周期和业务模块指标。
• 受控验收入口：
  • OTel/Tempo 使用 $unidesk-otel；
  • Prometheus 与 Web 哨兵使用 $unidesk-monitor；
  • 指标、trace 或版本一致性漂移不得改变业务 ready 终态。

退役与推广

• development 验收通过后退役旧 test 对象：
  • pikaoa-test namespace；
  • 旧 test Repository/Argo/GitOps 资源；
  • 旧 test Secret source 与数据库 role/database；
  • 旧 test CLI 状态目录。
• 退役必须精确限定旧 test 对象：
  • 禁止删除 pikaoa production namespace；
  • 禁止删除 pikaoa-ci；
  • 禁止删除 pikaoa-dev；
  • 禁止触碰其他 PaC consumer。
• production 推广：
  • 先完成 development CLI/Web/OTel/Prometheus 验收；
  • 再通过正常 master -> release PR 推广；
  • release PR merge 是生产自动交付的唯一触发；
  • 生产推广不复制 development 数据。