# PJ2026-01060106 HWLAB双环境

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-01060106 HWLAB双环境需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060106 |
| 短名 | HWLAB双环境 |
| 层级 | L3 子课题 |
| 状态 | 草稿 |
| 实现引用版本 | draft-2026-07-14-p0-hwlab-dev-production-lanes |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) |
| 关联规格 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md)、[PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文定义 HWLAB 在 NC01 上的 development/production 双环境。所有可调事实由 owning YAML 控制，L2/L3 发布只允许通过受控 `plan` 和手动 `trigger` 执行；PR merge/branch update 不得创建 PipelineRun。禁止裸补跑 PipelineRun、手工 Argo sync、运行时 patch 或从集群反解配置。

## 2. 目的和范围

### 2.1 目的

把当前 `v0.3` 固定为开发环境，并建立跟随 `release` 分支的生产环境。两套环境在发布身份、运行资源、公开入口、数据库数据域和 Kafka consumer identity 上隔离，使开发变更可以持续滚动，同时只有经过开发原入口验证的 commit 才能晋升为生产基线。

### 2.2 范围内

- `v0.3` development 与 `release` production 的 source、PaC consumer、Tekton Pipeline、GitOps branch/path、Argo Application、namespace 和 artifact provenance。
- development 的 NC01 公网 IP HTTP 入口与 production 的 `https://hwlab.pikapython.com` 入口。
- 共用 NC01 host PostgreSQL 服务时，两套独立 database、role、Secret consumer 和 migration ledger。
- 两套独立 Kafka consumer group identity，以及纯 Kafka实时/回放权威不被数据库迁移阻塞的边界。
- `v0.3` 到 `release` 的受控晋升、手动计划发布和原入口验证。

### 2.3 范围外

- Web 页面能力和组件重写归客户端规格。
- AgentRun 自身的发布 lane 和数据库归 AgentRun 专项规格。
- DNS、Caddy、FRP 和证书服务的通用实现归 YAML运维与公开入口平台；本规格只定义 HWLAB 两个 consumer 的所有权。
- 从 development 向 production 复制业务数据、Secret value 或用户会话不在本任务范围内。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| development lane | source 为 `v0.3`、保留当前开发 namespace、通过 NC01 公网 IP 空闲 HTTP 端口访问的 HWLAB 环境。 |
| production lane | source 为 `release`、使用独立 production namespace、通过 `https://hwlab.pikapython.com` 访问的 HWLAB 环境。 |
| 晋升 | 把已在 development 完成原入口验证的精确 commit 纳入 `release`；分支推进不发布，仍需对 production 单独 plan 和手动 trigger。 |
| 数据域隔离 | 两个环境不共享 PostgreSQL database、role、Secret consumer 或 migration ledger，任何 schema/data mutation 只作用于选中 lane。 |
| 入口所有权 | owning YAML 中唯一声明某 public origin 的 consumer；同一 host/origin 不得同时归 development 和 production。 |

## 4. 架构与数据流

### 4.1 系统架构

```mermaid
flowchart LR
  V03[HWLAB v0.3] --> DEVPA[development PaC/Pipeline]
  DEVPA --> DEVGIT[development GitOps]
  DEVGIT --> DEVNS[development namespace]
  DEVNS --> DEVHTTP[152.53.229.148:YAML端口]
  DEVNS --> DEVDB[(host PostgreSQL: development database)]

  REL[HWLAB release] --> PRODPA[production PaC/Pipeline]
  PRODPA --> PRODGIT[production GitOps]
  PRODGIT --> PRODNS[production namespace]
  PRODNS --> PRODHTTPS[https://hwlab.pikapython.com]
  PRODNS --> PRODDB[(host PostgreSQL: production database)]

  KAFKA[(Kafka)] -->|development consumer group| DEVNS
  KAFKA -->|production consumer group| PRODNS
```

### 4.2 运行数据流

```mermaid
flowchart LR
  AR[agentrun.event.v1] --> MAP[HWLAB mapper]
  MAP --> HE[hwlab.event.v1]
  HE -->|development group| DEVSSE[development live/replay SSE]
  HE -->|production group| PRODSSE[production live/replay SSE]
  DEVSSE --> DEVWEB[development Web]
  PRODSSE --> PRODWEB[production Web]
  DEVWEB -.显式查询.-> DEVDB[(development read model)]
  PRODWEB -.显式查询.-> PRODDB[(production read model)]
```

Kafka event 是实时与回放 authority。数据库只保存各 lane 的业务数据和派生读模型；任一数据库 schema 缺失不得改变 Kafka direct publish/live/replay 路径，也不得成为 Cloud API 启动或自动滚动前置。

### 4.3 晋升与手动发布时序

```mermaid
sequenceDiagram
  participant D as v0.3
  participant DC as development CI/CD
  participant DV as development 原入口验证
  participant R as release
  participant PC as production CI/CD
  participant PV as production 原入口验证
  D->>DC: merge/update commit C，不触发发布
  DC->>DC: plan C，审阅 env reuse 与构建范围
  DC->>DV: 手动 trigger C，构建、GitOps、rollout
  DV-->>D: C 验证通过
  D->>R: 受控晋升精确 commit C
  R->>PC: branch update，不触发发布
  PC->>PC: plan C，审阅 env reuse 与构建范围
  PC->>PV: 获得当次授权后手动 trigger C
  PV-->>R: digest/source/runtime/入口证据
```

初始 `release` 分支只能从完成 P0 纯 Kafka纠偏并在 development 原入口验证通过的 `v0.3` commit 创建。不得从已知强制 PostgreSQL transactional projector 的事故 commit 创建，也不得绕过 plan 和受控 trigger，用裸 PipelineRun 或 runtime patch 填补发布链。

## 5. 配置与隔离

### 5.1 YAML-first 配置

owning YAML 至少声明：

- lane id、source repository/branch、PaC consumer、Pipeline、GitOps branch/path、Argo Application 和 namespace。
- public exposure 的 scheme、host、port、target service、health path、Caddy/FRP managed block 引用。
- PostgreSQL host service reference、database、role、Secret sourceRef/targetKey、migration ledger identity。
- Kafka bootstrap SecretRef、topic contract、consumer group identity 和 replay retention/cursor 配置。
- artifact repository、image name、digest provenance 和 source commit label。

代码只校验和渲染 YAML，不内置 development/production 特例，不从现有 Deployment、Secret、Ingress、Caddy 或数据库反解事实。Secret 输出只允许 presence、object/key、fingerprint 和脱敏摘要。

### 5.2 公开入口

- development 正式入口是 `http://152.53.229.148:<development.publicExposure.port>`；实施任务应探测空闲端口并把最终值固化到 owning YAML。
- production 正式入口固定为 `https://hwlab.pikapython.com`，由 production publicExposure 独占。
- development 必须删除 `hwlab.pikapython.com` 的 route、probe、CORS/origin 和 managed block 所有权；Web/API/health 使用同源 development 入口。
- production 证书、Caddy/FRP route 和 health probe 由 YAML 渲染，禁止手改共享配置文件。

### 5.3 PostgreSQL 与 Kafka 隔离

- 两个 lane 可以复用同一 NC01 host PostgreSQL 服务进程，但必须使用不同 database、role、Secret consumer 和 migration ledger。
- migration 命令必须显式选中 lane，只能迁移其 database；禁止用共享 DSN、共享 schema 或默认 database 回退。
- migration 执行边界：
  - lane 自有 schema migration 可以作为 owning workload 的 init 阶段执行；
  - 禁止使用会在 migration 失败时停止整个 Argo Application 资源应用的 Sync hook；
  - migration 失败只能使依赖该 schema 的组件保持未就绪；
  - 失败状态必须保留具名组件、lane 和失败阶段，不能阻止同一 lane 的无关服务滚动。
- production 初始化不复制 development 会话、用户业务数据或 migration history；需要数据导入时必须另立受控任务。
- development 与 production 使用不同 Kafka consumer group identity。运行状态和 lag 必须带 lane 标签，禁止同名 group 导致 offset 互相推进。
- 数据库、Kafka 或 schema warning 不得触发功能关闭、authority 切换、HTTP fallback 或阻塞其他 lane 滚动上线。

## 6. 原子需求

### 6.1 HWLAB-LANE-REQ-001 Development迁移

`v0.3` 的受控手动发布链必须部署到 development namespace，并迁移到 YAML 声明的 NC01 公网 IP HTTP 入口。迁移完成后 `https://hwlab.pikapython.com` 只指向 production，不再路由到 development。

### 6.2 HWLAB-LANE-REQ-002 Production手动发布链

`release` 必须拥有独立 PaC consumer、Tekton Pipeline/ServiceAccount、GitOps branch/path、Argo Application、namespace、image provenance 和 release status。`release` update 不得触发完整链；获得当次 L3 授权后，发布人员必须先审阅精确 commit 的 plan，再用受控 trigger 发布，禁止裸补跑。

### 6.3 HWLAB-LANE-REQ-003 Source与制品对齐

每个 lane 的 PipelineRun、GitOps desired state、runtime image digest 和 workload label 必须能关联同一 source commit。缺失或不一致必须可见，但微服务契约、版本或 schema 检查只输出 warning，不得阻塞业务和滚动上线。

### 6.4 HWLAB-LANE-REQ-004 数据边界

任一 lane 的应用、migration、Secret 和管理命令不得连接另一 lane 的 database/role。验收必须证明两个环境写入的 canary 数据、migration ledger 和 consumer group offset 互不出现于对方数据域。

### 6.5 HWLAB-LANE-REQ-005 原入口验收

原入口验收要求如下：

- development 从新的公网 IP HTTP 入口完成 Web、API、health 和至少一次实时/回放 SSE 验收。
- production 从 `https://hwlab.pikapython.com` 完成同样验收。
- production 同时核对 source commit、image digest、namespace、database identity 和 Kafka consumer group。
- 源码测试、PipelineRun 成功或 Argo Synced 不能单独替代原入口通过。

## 7. 过程控制

- 父任务由 pikasTech/unidesk#2008 跟踪。
- development 入口迁移由 pikasTech/unidesk#2009 和 MDTODO `R7.1` 跟踪。
- production release lane 由 pikasTech/unidesk#2010 和 MDTODO `R7.2` 跟踪。
- 两个实施任务可以在独立 worktree 并行；共享 YAML/publicExposure 基线的合并和上线顺序由主代理审核。
- production 实现可以先准备，但 `release` 分支创建、生产部署和公网切换必须等待 P0 纯 Kafka纠偏在 development 验证完成。