# 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：

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

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

   ```bash
   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`。