From 3d807062ed724d192b78a8fd93e5315fe6da43cb Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Mon, 13 Jul 2026 20:18:13 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=20PikaOA=20=E4=BC=81?=
 =?UTF-8?q?=E4=B8=9A=E5=8A=9E=E5=85=AC=E5=B9=B3=E5=8F=B0=E8=A7=84=E6=A0=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/MDTODO/pikaoa-enterprise-platform.md     |  45 ++
 .../PJ2026-03/specs/PJ2026-03-pikaoa.md       | 479 ++++++++++++++++++
 2 files changed, 524 insertions(+)
 create mode 100644 docs/MDTODO/pikaoa-enterprise-platform.md
 create mode 100644 project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md

diff --git a/docs/MDTODO/pikaoa-enterprise-platform.md b/docs/MDTODO/pikaoa-enterprise-platform.md
new file mode 100644
index 00000000..0189dd72
--- /dev/null
+++ b/docs/MDTODO/pikaoa-enterprise-platform.md
@@ -0,0 +1,45 @@
+# PikaOA 企业办公平台
+
+- 规格真相：`project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md`。
+- 产品仓库：`pikaInc/pikaoa`，固定主工作区为 `/root/pikaoa`。
+- 目标运行面：owning YAML 选中的 NC01 Kubernetes 独立 namespace。
+- 公网原入口：`https://oa.pikapython.com`。
+- 数据真相：PK01 host PostgreSQL 中的独立数据库与角色。
+- 执行证据：GitHub issue/PR、任务报告、PaC/PipelineRun/GitOps/Argo 和 Web 原入口验证。
+
+
+## R1 [in_progress]
+
+依据 PJ2026-03 建设企业级可扩展 PikaOA：在 /root/pikaoa 建立 pikaInc 仓库，采用 HWLAB v0.3 同族 Vue 技术栈和 Go 后端；CLI-first 完成员工/RBAC、甲方分类、合同多版本、发票关联与废弃、审计、OTel/Prometheus，再开发 Web；通过独立 K8s namespace、PK01 host PostgreSQL、YAML-first、PaC bootstrap、自动 CI/CD 和 https://oa.pikapython.com 原入口交付，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1_Task_Report.md)。
+
+### R1.1
+
+调研成熟开源 OA、ERP、合同、发票、Go 微服务与 Vue 组件方案，形成采用/复用/不采用结论，依赖 R1 规格，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.1_Task_Report.md)。
+
+### R1.2
+
+建立 pikaInc/pikaoa 私有仓库、/root/pikaoa 固定 master 和独立任务 worktree，依赖 R1.1 的技术选型，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.2_Task_Report.md)。
+
+### R1.3
+
+实现企业模块内核、Go API/Worker、PostgreSQL 迁移、员工/RBAC、伙伴分类、合同版本、发票废弃、审计、OTel/Prometheus 与 CLI，并通过 CLI 后端验收，依赖 R1.1-R1.2，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.3_Task_Report.md)。
+
+### R1.4
+
+在 R1.3 CLI 后端验收通过后实现 HWLAB v0.3 同族 Vue 工作台、响应式页面与同路径业务流，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.4_Task_Report.md)。
+
+### R1.5
+
+在 UniDesk 中声明 PK01 PostgreSQL、Secret、NC01 独立 namespace、Gitea/PaC、GitOps、OTel/Prometheus 和 PK01 公网暴露，并改进可复用 bootstrap 工具，依赖 R1.1-R1.2，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.5_Task_Report.md)。
+
+### R1.6
+
+审核并合并双仓 PR，执行首次受控 PaC bootstrap，由正常 source PR merge 自动发布，依赖 R1.3-R1.5，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.6_Task_Report.md)。
+
+### R1.7
+
+通过 CLI、OTel、Prometheus 和 https://oa.pikapython.com 桌面/移动原入口验证完整主路径，依赖 R1.6，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.7_Task_Report.md)。
+
+### R1.8
+
+完成 issue、MDTODO、阶段报告、post-task、已吸收 worktree 与分支清理，依赖 R1.7，完成任务后将详细报告写入[任务报告](./details/pikaoa-enterprise-platform/R1.8_Task_Report.md)。
diff --git a/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md
new file mode 100644
index 00000000..acda64e5
--- /dev/null
+++ b/project-management/PJ2026-03/specs/PJ2026-03-pikaoa.md
@@ -0,0 +1,479 @@
+# PJ2026-03 PikaOA 企业办公平台总规格
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+| v0.1 | 待本版本提交 | 2026-07-13 | 创建企业办公平台预期终态、模块架构和首批合同与发票能力规格。 |
+
+修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
+
+## 正文
+
+## PJ2026-03 PikaOA 企业办公平台总项目需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-03 |
+| 短名 | PikaOA |
+| 层级 | L0 总项目 |
+| 规格状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 规格治理索引 | 本文第 9 章 |
+| 实现引用版本 | v0.1 |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。
+
+本文只定义：
+
+- 企业办公平台的预期终态；
+- 稳定业务边界；
+- 可扩展模块架构；
+- 首批合同与发票能力；
+- 可重复执行的验收契约。
+
+当前实现状态、阶段差距、提交、PR、作业、日志和截图进入阶段报告、任务报告或 GitHub issue，不进入本规格正文。
+
+## 2. 目的和范围
+
+### 2.1 项目使命
+
+PikaOA 的使命是为公司提供长期演进的企业办公平台：
+
+- 统一承载员工、组织、业务伙伴、文档、流程、审计和业务模块；
+- 让合同、发票等首批模块形成可追溯、可检索、可关联的业务事实；
+- 让后续审批、采购、报销、项目、人事、资产和知识管理模块复用同一平台能力；
+- 通过稳定模块边界避免每增加一个功能就复制账号、权限、审计、附件和部署逻辑；
+- 在 Kubernetes 中以可审计、可重复、自动交付的方式运行。
+
+### 2.2 预期终态
+
+PikaOA 终态必须同时具备：
+
+- 企业平台内核：
+  - 统一员工身份、组织成员、角色、权限和会话；
+  - 统一业务伙伴、分类、标签、联系人和归档状态；
+  - 统一附件、审计、模块注册、搜索和分页契约；
+  - 统一 API 错误、字段校验和幂等写入语义。
+- CLI-first 交付：
+  - 每个后端业务用例先提供稳定 CLI 入口；
+  - CLI 与 Web 复用同一 HTTP API、身份、权限和业务语义；
+  - 后端、数据库、审计和可观测性通过 CLI 原入口验收后，才实现对应前端工作流；
+  - 自动化和人工排障不依赖浏览器才能完成核心业务闭环。
+- 可扩展业务模块：
+  - 每个模块拥有独立领域模型、应用服务、持久化迁移、权限声明、HTTP API 和前端路由；
+  - 模块通过稳定端口、领域事件和对象引用协作；
+  - 新模块不得复制用户、组织、业务伙伴、审计或附件真相；
+  - 成熟模块可以沿既有端口从业务 API 中提取为独立微服务。
+- 首批可用能力：
+  - 合同管理支持多版本、当前版本、版本历史和关联业务伙伴；
+  - 发票管理支持合同关联、合同版本关联、正常与废弃状态以及废弃原因；
+  - 员工管理支持管理员和普通员工两类初始角色；
+  - 按不同甲方及其分类筛选合同、发票和统计摘要。
+- 企业交付能力：
+  - Web、业务 API 和异步 Worker 是可独立扩缩和发布的工作负载；
+  - PostgreSQL 是业务数据真相；
+  - 文件内容通过可替换存储端口管理，元数据与哈希进入业务数据；
+  - 配置、Secret、数据库绑定、运行目标和公网暴露均由 owning YAML 管理；
+  - GitHub 合并触发自动 CI/CD、GitOps 和运行面收敛。
+- 首版可观测能力：
+  - Web、CLI、API、Worker 和 CI/CD 统一传播 W3C trace context；
+  - Go 服务从第一版接入 OpenTelemetry traces、metrics 和结构化日志关联；
+  - Prometheus 从第一版采集服务、HTTP、数据库、领域用例、outbox 和运行时指标；
+  - trace、metric 和日志均携带稳定 service、module、operation 和结果属性；
+  - 可观测后端不可用时形成显式非阻塞 warning，不阻塞已经成功的用户业务。
+
+### 2.3 范围内
+
+- 员工账户、启停、角色、权限和登录会话。
+- 业务伙伴、甲方分类、联系人、标签和归档。
+- 合同主记录、多版本、附件、状态、检索和关联。
+- 发票主记录、合同/版本关联、附件、废弃标记和检索。
+- 审计记录、领域事件、模块注册和模块级导航。
+- CLI、Web 工作台、HTTP API、健康接口和异步任务入口。
+- OpenTelemetry Collector 接入、Prometheus 指标、结构化日志和 trace/metric 关联。
+- PostgreSQL、Kubernetes namespace、Secret、CI/CD、GitOps 和公网 HTTPS。
+
+### 2.4 范围外
+
+- 首期自动签章、电子税务局直连、OCR 自动识别、付款和银行流水对账。
+- 首期通用 BPMN 设计器、复杂会签、组织同步和单点登录。
+- 用合同版本覆盖历史版本或物理删除已废弃发票。
+- 为每个业务模块部署独立身份系统、独立业务伙伴表或独立审计实现。
+- 把运行面 Secret、Pod 环境变量或数据库现状反向保存为配置真相。
+- 未经后续规格确认的租约、选主、分布式事务协调器或第二权限体系。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 员工 | 可以登录 PikaOA 并按角色执行操作的公司成员。 |
+| 管理员 | 可以管理员工、角色、业务伙伴分类和全部首批业务模块的员工角色。 |
+| 普通员工 | 可以使用被授予模块能力但不能管理系统身份与权限的员工角色。 |
+| 业务伙伴 | 与公司发生业务关系的外部组织或个人；甲方是业务伙伴的一种业务角色。 |
+| 甲方分类 | 用于组织、筛选和汇总甲方的可维护分类。 |
+| 合同主记录 | 表示一份合同长期身份、甲方、编号、状态和当前版本指针的聚合根。 |
+| 合同版本 | 合同在某一时点的不可变业务内容快照，具有合同内单调递增的版本号。 |
+| 当前版本 | 合同主记录明确指向、供默认查询和新关联使用的合同版本。 |
+| 发票废弃 | 保留发票记录并记录废弃人、时间和原因，使其不再计入有效业务结果。 |
+| 模块 | 具有独立领域边界、权限、迁移、API、事件和前端入口的可插拔业务能力。 |
+| 领域事件 | 模块完成业务事务后写入的结构化事实，用于同进程订阅或异步扩展。 |
+
+## 4. 系统边界和内部模块
+
+### 4.1 外部边界
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 管理员、普通员工和经批准的自动化调用方。 |
+| 外部输入 | 登录凭据、员工信息、业务伙伴信息、合同版本、发票信息、附件和筛选条件。 |
+| 受控资源 | 员工身份、业务伙伴、合同、发票、附件、审计记录、数据库和运行配置。 |
+| 外部输出 | 工作台、列表、详情、版本历史、关联结果、状态、审计和健康摘要。 |
+| 用户接口 | CLI、响应式 Web 与版本化 HTTP API。 |
+| 系统边界 | PikaOA 管理内部办公业务事实；不替代税务、签章、银行和外部身份平台。 |
+
+### 4.2 L1 能力域
+
+| 编号 | 短名 | 主责边界 | 下游支撑 |
+| --- | --- | --- | --- |
+| PJ2026-0301 | 组织权限 | 员工、角色、权限、会话和模块授权。 | 全部业务模块。 |
+| PJ2026-0302 | 伙伴主数据 | 业务伙伴、甲方角色、分类、联系人和标签。 | 合同、发票及后续业务模块。 |
+| PJ2026-0303 | 合同管理 | 合同身份、多版本、当前版本、状态、附件和历史。 | 发票、审批、项目和归档。 |
+| PJ2026-0304 | 发票管理 | 发票、合同关联、合同版本关联、废弃和附件。 | 财务、报销、对账和统计。 |
+| PJ2026-0305 | 平台内核 | 模块注册、审计、领域事件、附件端口、搜索和 API 规范。 | 全部业务模块和自动化。 |
+| PJ2026-0306 | 平台交付 | Web/API/Worker 运行、数据库、Secret、CI/CD、GitOps 和公网入口。 | 全部产品能力。 |
+
+### 4.3 模块接入合同
+
+每个业务模块必须声明：
+
+- 唯一模块标识、显示名称和生命周期状态；
+- 领域实体、应用用例、数据库迁移和对象引用类型；
+- 权限集合及其管理员、普通员工默认授权映射；
+- 版本化 HTTP 路由、OpenAPI 描述和稳定错误码；
+- 领域事件名称、版本和最小载荷；
+- 前端路由、导航项、权限要求和列表/详情入口；
+- 审计动作、资源类型和可安全披露的变更摘要；
+- 健康、迁移和部署后验证入口。
+
+新增模块不得通过修改其他模块私有表完成集成。跨模块读取使用应用端口或稳定对象引用；异步扩展使用事务内写入的领域事件/outbox，不新增第二业务真相。
+
+## 5. 目标架构和数据流
+
+### 5.1 目标架构图
+
+```mermaid
+flowchart LR
+  U[管理员与员工] --> W[Vue Web 工作台]
+  U --> CLI[PikaOA CLI]
+  W --> A[Go 业务 API]
+  CLI --> A
+  A --> I[组织权限模块]
+  A --> P[伙伴主数据模块]
+  A --> C[合同模块]
+  A --> F[发票模块]
+  A --> K[平台内核]
+  I --> DB[(PostgreSQL)]
+  P --> DB
+  C --> DB
+  F --> DB
+  K --> DB
+  A --> S[文件存储端口]
+  A --> O[(事务 Outbox)]
+  O --> J[Go Worker]
+  J --> X[后续通知、索引与集成适配器]
+  W --> OT[OpenTelemetry Collector]
+  CLI --> OT
+  A --> OT
+  J --> OT
+  A --> PM[Prometheus metrics]
+  J --> PM
+  PM --> PR[Prometheus]
+  OT --> TB[Trace backend]
+```
+
+部署单元采用三类独立工作负载：
+
+- Web：使用与 HWLAB v0.3 同族的 Vue 3、Vite、TypeScript、Vue Router、Pinia 和 Tailwind 技术栈；
+- API：使用成熟 Go HTTP/服务框架、PostgreSQL 驱动、迁移工具、RBAC 库和 OpenAPI 工具；
+- Worker：复用 Go 领域与应用层，消费 PostgreSQL outbox，承载非请求内任务。
+
+CLI 是后端业务的第一用户入口：
+
+- 使用与 Web 相同的公开 HTTP API，不通过数据库直连或内部 manager 绕过业务语义；
+- 默认输出适合人工扫描的紧凑文本，机器调用显式请求 JSON；
+- 长任务使用提交与短轮询，不保持无界阻塞连接；
+- 输出包含请求标识和 traceId，但不显示密码、token、完整数据库连接串或附件正文；
+- 前端开发必须以对应 CLI 用例已经通过为前置。
+
+业务 API 在首期采用模块化单体内核：
+
+- 保持单事务、单数据库和低运维复杂度；
+- 模块边界与端口从第一版生效；
+- Web、API 和 Worker 已是独立工作负载；
+- 当容量、团队或故障域需要时，单个模块可以沿既有 API、事件和数据所有权边界提取为独立微服务。
+
+### 5.2 业务数据流
+
+```mermaid
+flowchart TD
+  R[用户请求] --> G[认证、授权与输入校验]
+  G --> M[目标模块应用用例]
+  M --> T[领域规则与事务]
+  T --> D[(模块拥有的数据表)]
+  T --> A[(统一审计记录)]
+  T --> O[(事务 Outbox)]
+  D --> Q[查询投影与分页]
+  Q --> V[Web/API 响应]
+  O --> W[异步 Worker]
+  W --> E[扩展适配器]
+```
+
+### 5.3 合同多版本时序
+
+```mermaid
+sequenceDiagram
+  participant U as 员工
+  participant W as Web
+  participant A as 合同应用服务
+  participant D as PostgreSQL
+  U->>W: 新建合同或创建新版本
+  W->>A: 提交合同身份、甲方和版本内容
+  A->>D: 校验权限、甲方和合同内版本号
+  A->>D: 事务写入不可变版本、更新当前版本指针和审计/outbox
+  D-->>A: 返回合同与新版本
+  A-->>W: 返回当前版本和完整版本摘要
+  W-->>U: 展示详情与版本历史
+```
+
+### 5.4 发票废弃与合同关联时序
+
+```mermaid
+sequenceDiagram
+  participant U as 员工
+  participant W as Web
+  participant A as 发票应用服务
+  participant D as PostgreSQL
+  U->>W: 登记发票并选择合同/版本
+  W->>A: 提交发票与关联标识
+  A->>D: 校验合同、版本、甲方一致性并写入发票
+  D-->>A: 返回有效发票
+  U->>W: 标记发票废弃并填写原因
+  W->>A: 提交废弃动作
+  A->>D: 原子写入废弃人、时间、原因和审计/outbox
+  D-->>A: 返回保留的废弃发票
+  A-->>W: 展示废弃标识且默认排除有效统计
+```
+
+## 6. 全局原子需求
+
+### 6.1 PIKAOA-L0-REQ-001 模块化平台内核
+
+PikaOA 必须以第 4.3 节的模块接入合同组织业务能力。模块必须拥有清晰数据所有权，复用统一身份、伙伴、附件、审计和事件能力，并能在不改写既有模块私有实现的情况下增加导航、权限、API、迁移和事件订阅。
+
+接受标准包括：
+
+- 模块注册表可以枚举已启用模块及其权限和前端入口；
+- 一个示例新增模块可以只通过自身声明与公共端口接入；
+- 禁止跨模块直接更新私有表；
+- API 与领域事件具有显式版本。
+
+### 6.2 PIKAOA-L0-REQ-002 员工与权限
+
+系统必须支持员工的创建、编辑、启用、停用、角色分配和登录。管理员与普通员工的初始账号由 owning YAML 的 Secret `sourceRef`/`targetKey` 注入，不在 Git、镜像、日志或前端代码中保存密码。
+
+接受标准包括：
+
+- 管理员可以管理员工和角色；
+- 普通员工不能管理员工、角色或 Secret；
+- 停用员工不能建立新会话；
+- 所有业务写入记录实际员工身份。
+
+### 6.3 PIKAOA-L0-REQ-003 业务伙伴和甲方分类
+
+系统必须维护业务伙伴的唯一身份、名称、统一社会信用代码或其他外部标识、角色、分类、标签、联系人、备注和归档状态。合同与发票通过稳定标识关联甲方，不复制甲方名称作为关系真相。
+
+接受标准包括：
+
+- 管理员可以维护甲方分类；
+- 员工可以按甲方、分类、标签和归档状态筛选；
+- 同一甲方的合同与发票可以从伙伴详情统一查看；
+- 甲方改名不破坏历史关联。
+
+### 6.4 PIKAOA-L0-REQ-004 合同多版本
+
+每份合同必须有稳定主记录和一个或多个不可变版本。合同内版本号单调递增；创建新版本必须保留旧版本、更新当前版本指针并记录变更说明、操作者和时间。
+
+每个版本至少包含：
+
+- 版本号和版本说明；
+- 合同标题、合同编号和甲方引用；
+- 签署日期、生效日期、到期日期和币种；
+- 金额、摘要、状态和附件引用；
+- 创建人、创建时间和内容哈希。
+
+接受标准包括：
+
+- 详情默认显示当前版本并可查看全部历史版本；
+- 历史版本不可被当前编辑覆盖；
+- 并发创建相同下一版本时只能有一个事务成功；
+- 合同可以按甲方、分类、编号、状态和日期筛选。
+
+### 6.5 PIKAOA-L0-REQ-005 发票管理和废弃
+
+发票必须支持号码、类型、开票日期、金额、税额、价税合计、币种、甲方、合同和可选合同版本关联。发票不得物理删除；废弃动作必须保留原记录，并记录废弃人、废弃时间和非空原因。
+
+接受标准包括：
+
+- 发票可以关联合同主记录与具体合同版本；
+- 关联版本必须属于所选合同；
+- 发票甲方与合同甲方不一致时返回明确校验错误；
+- 默认有效列表和汇总排除废弃发票；
+- 用户可以显式筛选全部、有效或废弃发票。
+
+### 6.6 PIKAOA-L0-REQ-006 附件完整性
+
+合同版本和发票可以关联附件。附件元数据必须记录原文件名、媒体类型、字节数、内容哈希、存储键、上传人和上传时间。存储实现通过端口替换，业务表不保存宿主绝对路径。
+
+接受标准包括：
+
+- 上传、下载和详情读取均执行权限检查；
+- 相同对象的附件可独立增删，不改写历史合同版本内容；
+- 内容哈希与下载内容一致；
+- 文件存储不可用时不生成成功业务引用。
+
+### 6.7 PIKAOA-L0-REQ-007 审计和领域事件
+
+所有身份、伙伴、合同、版本、发票和模块配置写入必须生成不可变审计记录。需要异步扩展的业务事实必须在同一数据库事务中写入 outbox；Worker 只消费已提交事件，不反向成为业务真相。
+
+接受标准包括：
+
+- 审计记录包含员工、动作、资源类型、资源标识、时间和安全摘要；
+- Secret、密码、会话和附件正文不进入审计；
+- 事务回滚时审计和 outbox 同时回滚；
+- Worker 重试不重复改变业务主记录。
+
+### 6.8 PIKAOA-L0-REQ-008 企业工作台
+
+Web 必须是高密度、可持续使用的办公工作台。首屏直接显示导航、筛选、列表、状态和主要动作，不使用营销式落地页。合同、发票、伙伴和员工页面必须具备分页、空态、加载态、错误态、权限态、创建/编辑表单和详情深链。
+
+接受标准包括：
+
+- 桌面与移动视口无控件重叠或不可达操作；
+- 列表筛选和详情选择进入 URL 并可刷新恢复；
+- 版本历史、废弃标识和甲方分类可直接扫描；
+- 图标按钮有可访问名称和工具提示。
+
+### 6.9 PIKAOA-L0-REQ-009 自动交付和配置真相
+
+PikaOA 必须运行在独立 Kubernetes namespace。目标、namespace、镜像、数据库引用、Secret、资源、探针、持久卷、公网域名和 CI/CD 参数均由 owning YAML 声明；代码只校验和渲染。
+
+GitHub 目标分支合并必须自动驱动 Gitea 受控镜像、不可变快照、Pipelines-as-Code、Tekton、GitOps、Argo 和运行面收敛。首次 bootstrap 只初始化空镜像仓库和控制面，不得同步业务分支或人工创建 PipelineRun。
+
+接受标准包括：
+
+- Web、API 和 Worker 在同一独立 namespace 内运行；
+- API 直接连接 YAML 声明的 host PostgreSQL；
+- 运行面 Secret 只显示对象、key、presence 和 fingerprint；
+- 健康接口证明进程、数据库和迁移状态；
+- 公网 HTTPS 入口通过 YAML 声明的 PK01 edge 暴露。
+
+### 6.10 PIKAOA-L0-REQ-010 OpenTelemetry 与 Prometheus
+
+PikaOA 必须从首版提供 OpenTelemetry 与 Prometheus 可观测性，而不是在业务上线后补接。
+
+OpenTelemetry 必须覆盖：
+
+- Web 和 CLI 发起请求时生成或传播 W3C `traceparent`/`baggage`；
+- API HTTP server/client、认证、授权、领域用例、PostgreSQL、附件存储和 outbox 写入；
+- Worker 消费、重试、处理结果和下游适配器；
+- CI/CD 从 source、build、artifact、GitOps 到 runtime health 的同一 trace 上下文；
+- 结构化日志中的 traceId、spanId、service、module、operation、result 和稳定错误码。
+
+Prometheus 必须覆盖：
+
+- HTTP 请求量、延迟、状态族和在途请求；
+- 登录成功/失败、授权拒绝和会话状态摘要；
+- 合同创建、版本创建、发票创建、发票废弃等领域动作计数与延迟；
+- PostgreSQL连接池、查询延迟和迁移状态；
+- outbox pending、oldest age、processed、retry 和 failed；
+- Worker 队列、处理耗时和错误；
+- Go runtime、进程和健康状态。
+
+可观测属性不得包含密码、token、完整合同正文、附件正文、个人敏感字段或无界业务载荷。甲方、合同、发票和员工只在明确需要下钻时使用不可逆或受权限保护的稳定标识，禁止把高基数自由文本作为 metric label。
+
+接受标准包括：
+
+- 一次 CLI 合同版本操作可以从 CLI requestId/traceId 查询到 API、授权、数据库和审计/outbox span；
+- 一次 Worker 处理可以通过同一业务 correlation 与来源事件关联；
+- Prometheus 可以抓取 API 与 Worker 的 `/metrics` 并显示上述核心指标；
+- 健康状态区分应用 ready、数据库 ready、迁移 ready、OTel exporter warning 和 metrics scrape 状态；
+- OTel export 超时或 trace backend 暂时不可用只输出 `warning=true`、`blocking=false`，不改变成功业务事务终态。
+
+### 6.11 PIKAOA-L0-REQ-011 CLI-first 业务验收
+
+每个后端业务能力必须先通过 `pikaoa` CLI 验收，再实现对应 Web 页面。CLI 必须调用同一公开 HTTP API、使用同一用户身份与权限，并覆盖员工、伙伴、合同版本、发票废弃、审计和模块枚举。
+
+接受标准包括：
+
+- CLI 支持登录、当前身份、员工管理、伙伴/分类管理、合同 CRUD/版本历史、发票 CRUD/废弃、审计查询和健康/metrics 摘要；
+- 默认文本输出有界且非空，显式 JSON 输出为单一合法 JSON；
+- 业务失败返回稳定非零退出码和 typed error，不以 traceback 或空输出代替；
+- CLI 业务成功同时返回资源标识、requestId 和 traceId；
+- 后端 CLI 验收未通过时，对应前端任务保持未开始。
+
+### 6.12 PIKAOA-L0-REQ-012 非阻塞版本告警
+
+Web、API、Worker 和 CI/CD 必须输出结构化日志、健康状态和 trace 上下文。源码版本、镜像版本和 API 版本漂移只能形成非阻塞 warning，不得阻塞可安全解释的用户业务。
+
+## 7. API、数据与兼容边界
+
+- 外部 HTTP API 使用 `/api/v1` 版本前缀。
+- 模块路由使用稳定复数资源名和标准分页参数。
+- 写请求返回稳定业务错误码、字段路径和可读消息。
+- ID 使用不可枚举、全局唯一的稳定标识。
+- 时间以 UTC 保存并在用户界面按配置时区显示。
+- 金额使用定点十进制语义，不使用二进制浮点保存。
+- 数据库迁移单向、版本化、可审计；应用启动不静默修改未知结构。
+- 跨模块对象引用包含资源类型和稳定 ID，不复制私有载荷。
+- 兼容归一化只处理可安全解释的旧字段；不可解释业务数据返回字段级错误。
+
+## 8. 全局验收契约
+
+### 8.1 功能验收
+
+- 先使用 CLI 管理员账号登录，创建普通员工、甲方分类和甲方。
+- 通过 CLI 创建合同 v1，再创建 v2，确认 v1 保留且 v2 成为当前版本。
+- 通过 CLI 在甲方维度查看合同，并按甲方分类筛选合同。
+- 通过 CLI 创建关联合同 v2 的发票，确认合同、版本和甲方关系正确。
+- 通过 CLI 标记发票废弃，确认原因和审计存在，默认有效汇总不包含该发票。
+- 使用 CLI 普通员工账号确认允许的业务操作可用、管理员操作不可用。
+- 确认 CLI 后端验收通过后，再用 Web 重复同一业务主路径并比对结果。
+
+### 8.2 扩展性验收
+
+- 注册一个不修改首批模块私有实现的示例模块；
+- 模块声明权限、路由、导航、迁移、审计动作和事件订阅；
+- 示例模块可通过公共伙伴引用和领域事件完成集成；
+- 禁用模块后，其导航和新请求入口关闭，但历史业务数据不被删除。
+
+### 8.3 运行验收
+
+- CI/CD 绑定 source commit、PipelineRun、镜像 digest、GitOps revision、Argo 状态和运行面 ready；
+- Web、API 和 Worker 运行在 owning YAML 声明的 namespace；
+- PostgreSQL 连接、迁移、附件存储和健康检查通过；
+- OTel Collector 接收 Web/CLI/API/Worker trace，Prometheus 抓取 API/Worker 指标；
+- CLI 主路径均返回可查询的 requestId/traceId，并能关联业务审计；
+- `https://oa.pikapython.com` 返回登录页和可用业务工作台；
+- 桌面与移动浏览器完成登录、合同版本和发票废弃主路径；
+- 运行和验证输出不披露密码、数据库连接串、token 或附件正文。
+
+## 9. 规格治理
+
+- 本规格是 PikaOA L0 长期真相。
+- 稳定需求、模块边界、数据流、接口和验收口径变化先更新本规格或对应 L1 规格。
+- 实现进度、当前阻塞、提交、PR、PipelineRun、截图和一次性验证进入 GitHub issue、MDTODO 报告和阶段报告。
+- 本项目新增或修改的源码文件必须在文件头部或包级文档中标注 `SPEC: PJ2026-03 PikaOA v0.1`；自动生成文件、第三方代码、纯配置、锁文件和二进制产物例外，但其生成器或 owning 配置必须可追溯。
+- L1 规格按第 4.2 节编号建立；优先拆分具有独立生命周期、数据所有权或验收入口的能力域。