pikasTech-unidesk/docs/reference/pikaoa.md

PikaOA

配置真相

• PikaOA 平台配置唯一真相是 config/pikaoa.yaml。
• 测试运行面固定使用：
  • Target：NC01；
  • route：NC01:k3s；
  • namespace：pikaoa-test；
  • NodePort：32080。
• 测试 namespace 不根据 commit、instance 或任务动态生成。
• pikaoa 与 pikaoa-ci 是正式交付保护 namespace。
• 测试入口不得渲染、覆盖或删除保护 namespace 中的对象。

数据库边界

• 测试数据库固定使用 PK01 host PostgreSQL。
• config/platform-db/postgres-pk01.yaml 声明独立的：
  • role：pikaoa_test；
  • database：pikaoa_test；
  • schema：pikaoa；
  • DATABASE_URL export：platform-infra/pikaoa-test.env。
• pikaoa-test namespace 不创建 PostgreSQL StatefulSet、Service 或临时数据库。
• 数据库生命周期独立于 namespace 和业务 workload。
• 测试数据清理由 PK01 PostgreSQL 受控入口负责，不依赖删除 namespace。

Secret 初始化

• config/secrets-distribution.yaml 声明：
  • source：platform-infra/pikaoa-test.env；
  • target：pikaoa-test-nc01；
  • scope：pikaoa-test；
  • Kubernetes Secret：pikaoa-test-runtime。
• platform-infra/pikaoa-test.env 必须包含：
  • DATABASE_URL；
  • PIKAOA_SESSION_SECRET。
• DATABASE_URL 由 platform-db postgres export-secrets 写入并保留。
• createIfMissing 只为 PIKAOA_SESSION_SECRET 生成值，不覆盖已有 DATABASE_URL。
• 管理员和员工密码继续使用既有 external raw sources：
  • ~/.unidesk/.env/pikaoa-admin-password.txt；
  • ~/.unidesk/.env/pikaoa-employee-password.txt。
• Secret 输出只披露对象、key、presence、fingerprint 和摘要，不读取或打印值。

Test Target CLI

• 受控入口是 bun scripts/cli.ts pikaoa test-target。
• config/pikaoa.yaml#testRuntime 声明固定 namespace、镜像、PVC、Secret 引用、迁移、工作负载、探针和暴露端口。
• 所有创建对象都带以下所有权标签：
  • app.kubernetes.io/managed-by=unidesk-pikaoa-test-target；
  • pikaoa.unidesk.io/test-runtime=true；
  • pikaoa.unidesk.io/target=<target-id>；
  • pikaoa.unidesk.io/instance=<instance-id>。
• stop 只允许删除同时匹配固定 namespace 和全部所有权标签的运行面。
• CLI 使用异步任务状态目录记录有界状态和事件，不建立第二数据库、控制器、租约或锁服务。

初始化顺序

1. 使用 platform-db postgres 受控入口准备 PK01 pikaoa_test role/database，并 export DATABASE_URL。

2. 执行 foundation：

   bun scripts/cli.ts pikaoa test-target start \
     --target NC01 \
     --instance default \
     --step foundation \
     --confirm
   

3. foundation 只创建带所有权标签的固定 pikaoa-test Namespace 和附件 PVC，不要求业务 Secret 已存在。

4. 执行 Secret 下发：

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

5. secrets sync 按 YAML 声明补齐允许生成的本地来源，并下发 pikaoa-test-runtime。

6. 使用同一 commit 依次执行：

   • --step init，仅初始化全新数据库；
   • --step api；
   • --step worker；
   • --step web。

7. Web 固定通过 152.53.229.148:32080 的 NodePort 入口验收。

单步运行

• foundation 不需要 --commit，也不检查业务 Secret。
• init、api、worker、web 和 all 必须显式提供 --commit。
• 每个 start 立即返回任务 ID；使用同一 target、instance 和 step 的 status 查询终态。
• request identity 包含：
  • target；
  • instance；
  • 产品 commit；
  • step；
  • 当前 step 的稳定 structural manifest fingerprint。
• request fingerprint 对 Secret stringData 只保留 key 结构和脱敏占位，不包含 Secret 原值。
• request fingerprint 排除 pikaoa.unidesk.io/expires-at 等每次渲染变化的易变字段。
• 完全相同 request 重复提交只返回已有任务状态，不并行创建第二任务。
• 不同 request 遇旧任务处于 queued/running 且 worker 存活时返回 start-instance-conflict。
• 不同 request 遇旧任务已 succeeded/failed/canceled，或 queued/running 但 worker 明确缺失时：
  • 原子退役该 step 的旧有界状态目录；
  • 继续使用同一 target/instance/step 状态路径提交新任务；
  • status 只读取该 step 的最新任务。
• foundation 也遵循相同规则。
• foundation 需要显式形成新 request 时，可以：
  • 提供新的 --commit 修订标识；
  • 修改 foundation 的稳定 manifest 结构。
• 不为重跑引入第二状态库、控制器、租约或长期历史存储。
• initializer、rollout 或运行面查询失败返回具名失败码，不静默进入下一阶段。
• OTel exporter、配置版本和 commit 对齐漂移只产生 blocking=false warning，不恢复 dedicated 门禁。

交付阶段

• pikaoa-test-nc01 独立 test CI/CD 复用同一 owning YAML：
  • 产品 master 只生成 .tekton/pikaoa-test-nc01-pac.yaml；
  • API、Worker、Web 并行构建并以 digest 发布 GitOps；
  • initializer 通过 Argo PreSync 在 API、Worker、Web 前初始化全新数据库；
  • 不创建专用测试集群；
  • 不生成动态 namespace；
  • 不创建 namespace-local PostgreSQL；
  • 不把测试 CI/CD 变成生产交付或用户业务的阻塞门禁。
• GitOps 接管后，手动 test-target start|stop mutation 仅用于暂停 Argo 自动同步后的有界调试；禁止 CLI direct-apply 与 Argo 同时写入。
• 生产 pikaoa-nc01 保留 release source authority，但当前不 bootstrap、不生成 .tekton、不创建 PipelineRun。
• PR、构建或单测不能替代固定 NodePort 原入口验收。

本地验证

• config/fixtures/pikaoa-test-target.yaml 只用于 renderer 和 CLI 测试。
• fixture target 固定为 validationOnly=true，不得连接真实 route。
• 最小验证包括：
  • bun --check scripts/src/pikaoa-test-target.ts；
  • bun test scripts/src/pikaoa-test-target-async.test.ts；
  • bun scripts/cli.ts check --syntax-only；
  • pikaoa test-target plan --step foundation；
  • git diff --check。