mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 裁决 HWLAB 双环境与纯 Kafka 权威

Browse Source
This commit is contained in:
Codex
2026-07-14 10:41:03 +02:00
parent 500a176b5d
commit 28ee7e62ae
6 changed files with 289 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/unidesk-subagent/SKILL.md
+4
View File
@@ -14,6 +14,10 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
- 既有权限、Secret 脱敏、不可逆操作和损害预防边界继续生效，本规则不授权绕过既有安全底线；
- 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
- 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
- bug fix 不得擅自改变 event authority、transport、persistence、replay 或 source of truth；发现现有架构可能是根因时，也必须先完成证据和规格裁决。
- 涉及事件、投影、实时、回放或持久化的派单，主代理必须在子 issue 中先写出 current data flow 和 desired data flow；两者存在架构变化时，先更新长期 SPEC 并取得用户明确授权，再允许实施。
- 新增测试只能验证已经授权的合同，不能用测试通过把未经授权的架构变化、迁移依赖或新 authority 合法化。
- 主代理审核顺序固定为：先比较用户最新目标、适用 SPEC 和 current/desired data flow，再审核代码内部一致性、测试和实现质量；后者通过不能覆盖前者偏离。
- 执行型和调研型委派默认优先使用 AgentRun `Artificer`：
- Artificer 的 `create task`、`apply` 和 `dispatch` 必须以下文“子 issue + MDTODO”登记为 fail-closed 前置；禁止先创建 task 或派单再补登记；
- 原生子代理和 Artificer 每次派单前都必须已有对应 MDTODO ITEM 或 SUBITEM；派单 prompt 与最终报告必须写明同一个 MDTODO ID；
project-management/PJ2026-01/deviations/PJ2026-010401080313-20260714-pure-kafka-architecture-deviation.md
+84
View File
@@ -0,0 +1,84 @@
# PJ2026-010401080313 纯Kafka权威架构偏离复盘
## 1. 事件摘要
| 字段 | 内容 |
| --- | --- |
| 严重度 | P0 开发事故 |
| 日期 | 2026-07-14 |
| 影响规格 | [PJ2026-010401080313 Workbench实时权威](../specs/PJ2026-010401080313-workbench-realtime-authority.md) |
| 关联执行 | pikasTech/HWLAB#2538、PR #2540 |
| 事故类型 | 未经授权改变 event authority、persistence 和 replay 架构，并引入数据库 schema 启动硬前置 |
| 当前状态 | 已停止继续扩展，正在通过新 PR 精确纠偏；禁止粗暴 reset 或覆盖无关修改 |
事故边界如下：
- 原始目标是修复 Workbench timing/duration 与一次 17 分钟投影异常。
- 原始架构要求坚持 `agentrun.event.v1 -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`。
- 实际实现把链路替换为 PostgreSQL transactional projector、facts/outbox 和数据库 replay。
- 实际实现删除 direct publish、live Kafka SSE 与 Kafka refresh replay，构成对用户目标和实时权威的根本偏离。
## 2. 时间线
| 阶段 | 事实 |
| --- | --- |
| 事故前 | 运行配置启用 direct publish、live Kafka SSE、Kafka refresh replay；transactional projector 与 projection outbox relay 关闭。 |
| 任务定义 | #2538 和 MDTODO 被错误写成“删除 direct/live/refresh，固定 transactional projector”，没有先证明 duration 故障需要改变 authority。 |
| 实现 | `3e03e94e` 固定 transactional 投影并修改 timing；`fc87a7e5` 删除 direct/live/refresh；`bef23280` 删除 HTTP 自动补链；`2603b00c` 继续清理旧投影残余。 |
| 合并 | PR #2540 通过 merge commit `6ae0d1b5a48118b6a65a521919de0bc5801e969d` 进入 `v0.3`。 |
| 部署 | PipelineRun/GitOps 成功，但新 Cloud API Pod 因 `workbench_transactional_realtime_schema_blocked` CrashLoop；Argo 为 `Synced/Degraded`，旧 Pod 继续服务。 |
| 判定 | 数据库迁移被误认为新架构的必要条件，随后确认它不是原纯 Kafka实时/回放能力的依赖。 |
| 止损 | 主代理纠正 #2538 与 MDTODO，要求从最新 `v0.3` 建新分支和新 PR，逐文件恢复纯 Kafka路径并保留无关修复。 |
## 3. 影响
- 新 Cloud API Pod 无法启动，滚动发布退化；旧 Pod 暂时维持服务，因此未发生完整业务中断。
- CI/CD 显示成功而运行面 `Degraded`，扩大了“流水线成功等于发布成功”的可见性误差。
- 原本无需数据库迁移的实时/回放链被增加 v8 schema 前置，导致修复路径被错误引向数据库迁移。
- direct publish、live/replay Kafka 代码被删除，回退成本从配置切换扩大为代码纠偏。
- 子代理和主代理的多轮 review 围绕新架构内部一致性优化，消耗时间并偏离原始 Web 增强主线。
## 4. 直接原因
1. 任务合同直接把未经用户授权的 PostgreSQL transactional projector 写成目标架构。
2. PR 删除原 authority 路径，并用启动断言强制新 schema 就绪。
3. review 把“Kafka 仍在链路中”误判为“纯 Kafka”，没有检查 Kafka 是否仍是实时和回放 authority。
4. canonical duration 修复与 authority 替换被耦合在同一 PR，未保持问题与架构变更的因果边界。
## 5. 系统性原因
- 派单前没有写出 current data flow、desired data flow 和两者差异，也没有要求用户授权 authority/persistence/replay 变化。
- 主代理以测试和内部一致性替代对用户目标、最新 SPEC、线上运行配置和数据流的优先审查。
- 较旧“Workbench唯一投影”规格包含数据库 outbox 设计，较新的纯 Kafka要求尚未形成明确优先级裁决；冲突未先解决就进入实现。
- 新测试验证了 transactional 架构，却没有证明该架构是被授权目标；测试把偏移固化成了代码门禁。
- rollout 验证只看到 PipelineRun/GitOps 成功，没有把新 Pod readiness、Argo health 和启动 blocker 作为同一发布判定。
## 6. 主代理责任
主代理对事故负最终责任：主代理创建和接受了错误任务合同，未在派单前完成架构裁决；review 时继续要求删除旧路径；在看到 schema blocker 后仍一度沿数据库迁移方向调查。子代理按错误合同实现不能替代主代理的架构审查责任。
## 7. 检测与恢复
本次事故由新 Pod CrashLoop、Argo `Synced/Degraded` 和 `workbench_transactional_realtime_schema_blocked` 暴露。恢复不执行数据库迁移来承认新架构，而是从最新 `v0.3` 创建精确纠偏提交：
- 恢复 direct publish、live Kafka SSE 和 Kafka retention replay。
- 删除 v8 schema 作为 Cloud API 启动前置。
- 保留 canonical duration、feature config schema、HTTP fallback 禁令和无关修复。
- 通过新的 PR、自动 PaC/GitOps/Argo 上线，并在原入口校对 live/replay SSE、terminal/final 和 canonical duration。
禁止 reset、force push、整提交粗暴反转或人工 runtime patch，以免覆盖 PR #2540 中与架构偏移无关的正确修改。
## 8. 纠正与防复发措施
| 措施 | Owner | 完成判定 |
| --- | --- | --- |
| 更新实时权威 SPEC | 主代理 | 明确纯 Kafka data flow、数据库非阻塞边界和新旧规格优先级。 |
| 精确纠偏 PR #2540 | HWLAB 实施代理 | 新 PR 恢复 live/replay 路径，Cloud API 不再依赖 v8 schema 启动。 |
| 原入口验证 | 主代理审核 | 自动上线后以同一 session/trace 校对实时、刷新回放、terminal/final 与 duration。 |
| 固化派单规则 | 主代理 | `unidesk-subagent` 要求 current/desired data flow 和架构变化授权。 |
| 固化 review 顺序 | 主代理 | 先比较用户目标、SPEC、运行 data flow，再看代码内部一致性和测试。 |
| CI/CD 可见性 | 独立任务 | PipelineRun 成功但 Argo/Pod degraded 时明确报告发布未完成，不以 schema warning 阻塞滚动。 |
## 9. 长期判定
修复 timing、duration、丢事件或 UI 收敛问题时，不得默认改变 event authority、transport、persistence、replay 或 source of truth。若证据表明确需架构变化，必须先更新长期 SPEC，写清 current/desired data flow、迁移与回退方案，并取得用户明确授权；新增测试只能验证已授权架构，不能反向把未经授权的实现合法化。
project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md
+2
View File
@@ -7,6 +7,8 @@
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
> 裁决优先级：本规格中以 PostgreSQL aggregate event stream、transactional projector、durable outbox 或 `/v1/workbench/sync` 作为实时/回放 authority 的条款，已被 2026-07-14 的 [PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) `draft-2026-07-14-p0-pure-kafka-authority` 取代。当前权威链固定为 `agentrun.event.v1 -> mapper -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`；PostgreSQL 只可作为非阻塞派生读模型，不能成为 Cloud API 启动、Kafka 实时或回放的前置。未完成正文重整前，冲突条款一律以最新专项裁决为准。
## 正文
## PJ2026-0104010803 Workbench唯一投影需求规格
project-management/PJ2026-01/specs/PJ2026-010401080313-workbench-realtime-authority.md
+16 -7
View File
@@ -19,7 +19,7 @@
| 短名 | Workbench实时权威 |
| 层级 | L4 专项规格切片 |
| 状态 | 草稿 |
| 实现引用版本 | draft-2026-07-08-p0-workbench-realtime-authority-v2; draft-2026-07-09-p1-single-step-debug |
| 实现引用版本 | draft-2026-07-08-p0-workbench-realtime-authority-v2; draft-2026-07-09-p1-single-step-debug; draft-2026-07-14-p0-pure-kafka-authority |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
| 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-0106050514 Workbench实时运行面](PJ2026-0106050514-workbench-realtime-runtime.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) |
@@ -31,14 +31,21 @@
### 2.1 目的
Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card、Final Response、Trace detail 和 transport diagnostic 的实时输入收敛到同一 durable projection 语义。当前目标不是“永远不用 REST”，而是禁止前端多端点补洞成为 correctness path：SSE typed event 是 live 主路径，`/v1/workbench/sync` 只能作为与 SSE 同语义的统一 replay/delta，initial snapshot 只负责页面初始水位，detail/history 只服务用户显式查看。
Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card、Final Response、Trace detail 和 transport diagnostic 收敛到纯 Kafka 事件权威：
- 固定数据流为 `agentrun.event.v1 -> mapper -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`。
- 浏览器只消费同一 SSE 合同。
- 断线、刷新和 cursor 缺口由服务端按 Kafka retention 回放后继续 live tail。
- `/v1/workbench/sync` 或业务 REST 补链不得成为 correctness path。
PostgreSQL 可以保存查询优化所需的派生读模型，但不是 `agentrun.event.v1` 与 `hwlab.event.v1` 之间的 inline authority，也不是实时或回放 SSE 的启动前置。读模型 schema 缺失、迁移未执行或投影器退化必须形成 warning/diagnostic，不能关闭 direct publish、live SSE、Kafka replay，不能阻塞 Cloud API 启动或滚动上线。
本规格同时定义单步调试工作台。调试工作台必须能在不接触真实运行面、不触发 automatic recovery 和不污染生产 Workbench store 的前提下，用 fake SSE 数据逐条驱动同一 reducer，暴露每一步的 authority decision、entity version、state diff、DOM triad 和禁止请求。
### 2.2 范围内
- `/v1/workbench/events` typed event 的 authority metadata、cursor、entity family/id/version、projectionRevision 和 terminal seal 语义。
- `/v1/workbench/sync` replay/delta 的语义边界：它是 SSE replay 等价物，不是第二套 REST repair 事实源。
- Kafka retention 回放 SSE 的 cursor、去重、顺序和回放到 live tail 的切换语义。
- initial snapshot、explicit detail/history、trace-detail-only payload、session list/detail/messages read model 和主状态投影之间的合并边界。
- 前端 reducer/adapter 的 authority gate、sealed guard、detail-only rejection、late stale rejection 和 diagnostic 输出。
- 自动恢复、SSE error、cursor gap、cross-tab projection signal 和 refresh/reconnect 的允许动作与禁止动作。
@@ -56,9 +63,9 @@ Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card
| 术语 | 定义 |
| --- | --- |
| Realtime Authority v2 | Workbench 主状态只能由 initial snapshot、SSE typed event、统一 `/v1/workbench/sync` replay/delta 和显式 detail/history 中各自被授权的 projection 输入更新的规则集合。 |
| Realtime Authority v2 | Workbench 主状态只能由 initial snapshot、`hwlab.event.v1` 的 live/replay SSE typed event 和显式 detail/history 中各自被授权的输入更新的规则集合。 |
| 高纯度 SSE | Workbench live correctness 优先由 SSE typed event 驱动；断线、重复、乱序和缺口通过同一 durable cursor/replay 语义处理，不回退到多个业务 REST endpoint 自行补事实。 |
| sync replay | `/v1/workbench/sync` 或等价入口按 session/trace scope 与 cursor 返回的 typed delta。它必须能被转换为与 SSE 相同的 reducer event，并携带同一 authority metadata。 |
| Kafka replay SSE | SSE 服务按客户端 cursor 从 `hwlab.event.v1` retention 回放 typed event，追上水位后在同一连接继续 live tail；replay 与 live 使用同一事件 schema 和 reducer。 |
| 多源补洞 | 前端在 automatic recovery 中同时或顺序调用 `/turns`、`/sessions/:id/messages`、`/traces/:id/events`、旧 `/v1/agent/*` 等端点来推断 terminal/final/message/session 主状态。该模式禁止。 |
| detail-only | 只服务 Trace detail、历史页、诊断和审计的 payload。它可以展示过程，不能覆盖主 message/finalResponse/turn/session authority。 |
| terminal seal | 同一 durable projection revision 内写入的 message/part terminal status、turn terminal、Final Response、timing、session running=false 和 cursor checkpoint。 |
@@ -71,7 +78,7 @@ Workbench 主状态只接受以下输入：
- `initial snapshot`：页面初始加载或 explicit user refresh 的水位输入，只能写入其声明的 session/message/turn/trace bucket。
- `SSE typed event`：live delivery 主路径，必须携带 `contractVersion`、`realtimeAuthority`、`entity.family/id/version`、cursor 和 `projectionRevision`。
- `sync replay/delta`：与 SSE 同语义的 replay 输入，必须先转换为 typed event 或同等 reducer action，再进入主 reducer。
- `Kafka replay SSE`：服务端按 cursor 从 `hwlab.event.v1` retention 回放，与 live event 使用同一 schema、authority metadata 和 reducer action。
- `explicit detail/history`：用户显式打开的 trace detail、历史分页或详情读取，只能写 detail bucket 或 diagnostic bucket；声明 `detailProjection=true` 或 `authority=trace-detail-only` 时必须拒绝写主状态。
- `optimistic local echo`：submit admission 前后的本地临时投影，必须有 stable id，对账后由 durable event/sync 覆盖；不得成为跨页面或刷新后的事实源。
@@ -81,6 +88,7 @@ Workbench 主状态只接受以下输入：
- 用 trace tail、trace detail 末行、message text、session list preview、elapsed timeout、localStorage、DOM active card 或 analyzer fallback 推断 `running`、terminal、Final Response 或 session active。
- 让 late session list/detail/messages、detail-only trace payload、transport diagnostic、requestfailed 或 stale running snapshot 覆盖 sealed entity version。
- 用 reload、切换 session、自动 repair helper、测试后门或 probe analyzer suppress 把已经分裂的页面补成通过。
- 用 `/v1/workbench/sync`、数据库 outbox replay、HTTP polling 或读模型查询替代 Kafka retention replay，或在 Kafka replay 可用前要求 PostgreSQL schema 就绪。
## 5. 单步调试工作台
@@ -123,7 +131,7 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture
静态验收：
- 自动恢复路径只允许 `SSE typed event`、`/v1/workbench/sync` replay 或 diagnostic；不得出现旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
- 自动恢复路径只允许 live/replay `SSE typed event` 或 diagnostic；不得出现 `/v1/workbench/sync`、旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
- `traceHydration*` 命名和运行时口径必须收敛为 `traceDetail*` 或显式 detail read；旧配置字段如保留，只能作为 deprecated alias。
- `detailProjection=true`、`authority=trace-detail-only` 和缺 authority metadata 的输入必须被 reducer gate 拒绝写主状态，并产生可见 diagnostic。
@@ -133,6 +141,7 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture
- refresh/reconnect/cross-tab signal 后，control/observer/fresh page 不出现 persistent `cross-page-projection-divergence`。
- `workbench-automatic-recovery-fanout-authority`、旧 agent read-through 和旧 Workbench detail fan-out 不回归。
- fake SSE 单步调试可以在无真实 API、无 `/sync`、无补洞的模式下完成 terminal seal、late stale rejection、detail-only rejection 和两页收敛测试。
- Cloud API 在 Workbench 数据库 schema 缺失或读模型迁移未完成时仍能启动，并继续 direct publish、live SSE 与 Kafka retention replay；退化项只形成可见 warning/diagnostic。
## 7. 过程控制
project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md
+1
View File
@@ -84,6 +84,7 @@
| PJ2026-01060103 | 发布判定 | 本规格 6.3 | source/GitOps/runtime 一致性、health/readiness 和 migration/SecretRef presence | CI/CD、GitOps、YAML运维 | 平台管理员、业务模块 |
| PJ2026-01060104 | 验证分层 | 本规格 6.4 | 自测试、综合联调、CLI/API 交互和真实运行面通过口径 | 目标 runtime、业务模块测试需求 | 发布决策 |
| PJ2026-01060105 | AgentRun发布 | [PJ2026-01060105 AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | AgentRun `v0.1` 的发布 lane、Pipeline、runtime namespace 和真实联调细则 | 源码同步、YAML运维、Agent编排 | AgentRun runtime |
| PJ2026-01060106 | HWLAB双环境 | [PJ2026-01060106 HWLAB双环境](PJ2026-01060106-hwlab-dev-production-lanes.md) | HWLAB `v0.3` development 与 `release` production 的分支、流水线、公开入口和数据隔离 | 源码同步、YAML运维、Workbench实时权威 | HWLAB runtime |
## 6. 原子需求
project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md
+182
View File
@@ -0,0 +1,182 @@
# 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 控制，自动发布只由目标 source branch 的 PR merge/branch update 驱动，禁止人工补跑 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 自动链发布。 |
| 数据域隔离 | 两个环境不共享 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->>DV: 自动构建、GitOps、rollout
DV-->>D: C 验证通过
D->>R: 受控晋升精确 commit C
R->>PC: branch update 自动触发
PC->>PV: 自动构建、GitOps、rollout
PV-->>R: digest/source/runtime/入口证据
```
初始 `release` 分支只能从完成 P0 纯 Kafka纠偏并在 development 原入口验证通过的 `v0.3` commit 创建。不得从已知强制 PostgreSQL transactional projector 的事故 commit 创建，也不得把 production 自动链的缺失用人工 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 回退。
- 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 自动触发完整链，不依赖主代理或值班人员人工补跑。
### 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 验证完成。