Merge pull request #2161 from pikasTech/docs/pikaoa-live-reference

docs(pikaoa): 固化生产最短验收路径

docs/reference/pikaoa.md

@@ -11,6 +11,16 @@
 - 测试 namespace 不根据 commit、instance 或任务动态生成。
 - `pikaoa` 与 `pikaoa-ci` 是正式交付保护 namespace。
 - 测试入口不得渲染、覆盖或删除保护 namespace 中的对象。
+- 生产运行面固定使用：
+  - source branch：`release`；
+  - consumer：`pikaoa-nc01`；
+  - runtime namespace：`pikaoa`；
+  - CI namespace：`pikaoa-ci`；
+  - Argo Application：`pikaoa-nc01`；
+  - 公网入口：`https://oa.pikapython.com`。
+- 生产交付与公网配置分别以以下 selector 为真相：
+  - `config/pikaoa.yaml#releaseRuntime.targets.NC01`；
+  - `config/pikaoa.yaml#delivery.targets.NC01`。
 
 ## 数据库边界
 
@@ -122,9 +132,49 @@
   - 不创建 namespace-local PostgreSQL；
   - 不把测试 CI/CD 变成生产交付或用户业务的阻塞门禁。
 - GitOps 接管后，手动 `test-target start|stop` mutation 仅用于暂停 Argo 自动同步后的有界调试；禁止 CLI direct-apply 与 Argo 同时写入。
-- 生产 `pikaoa-nc01` 保留 `release` source authority，但当前不 bootstrap、不生成 `.tekton`、不创建 PipelineRun。
+- 生产 `pikaoa-nc01` 已完成 bootstrap：
+  - 产品 `release` 只生成 `.tekton/pikaoa-nc01-pac.yaml`；
+  - 正常 `release` PR merge 是生产 PipelineRun 的唯一触发入口；
+  - API、Worker、Web 并行构建并以 digest 发布到生产 GitOps branch；
+  - Argo Application `pikaoa-nc01` 自动同步 `pikaoa` namespace；
+  - 禁止人工补建 PipelineRun 代替 source merge。
+- 生产使用 PK01 host PostgreSQL 独立 `pikaoa` database/role，不使用 namespace-local PostgreSQL。
+- 生产初始化模式是 `fresh-database-only`，不实现旧数据迁移、兼容或回滚。
+- 版本、审计和配置一致性异常只产生 `blocking=false` warning，不作为 MVP 业务门禁。
 - PR、构建或单测不能替代固定 NodePort 原入口验收。
 
+## 生产最短只读验收
+
+- 先执行运行面与 Argo 对账：
+
+  ```bash
+  trans NC01:k3s kubectl get deploy,pod,svc,pvc -n pikaoa -o wide
+  trans NC01:k3s kubectl get application -n argocd pikaoa-nc01
+  ```
+
+- 运行面通过判定：
+  - API、Web、Worker、FRPC Deployment 全部 Ready；
+  - Pod 全部 Running 且没有新增重启；
+  - 附件 PVC 为 Bound；
+  - Argo 为 `Synced` 和 `Healthy`。
+- 再验证公网和共享可观测性：
+
+  ```bash
+  curl -fsSI https://oa.pikapython.com/
+  bun scripts/cli.ts platform-infra observability metrics-query \
+    --target NC01 \
+    --query 'pikaoa_database_ready' \
+    --full
+  ```
+
+- 公网与可观测性通过判定：
+  - 公网 HTTPS 返回 200；
+  - 生产 API 和 Worker 的 `pikaoa_database_ready` 均为 1；
+  - 使用 `$unidesk-webdev` 完成管理员桌面与移动视口登录；
+  - 使用 `$unidesk-otel` 查询登录 `traceId`，span error 数为 0。
+- 密码只从 owning YAML 声明的 `sourceRef` 读取，禁止出现在 CLI 参数、日志、截图或任务报告中。
+- 完整身份/RBAC、严格一致性审计和附件备份增强属于独立后续任务，不阻塞上述 MVP 验收。
+
 ## 本地验证
 
 - `config/fixtures/pikaoa-test-target.yaml` 只用于 renderer 和 CLI 测试。