From 28ee7e62ae0160372f4f5a4fb54d034c77415508 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 10:41:03 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A3=81=E5=86=B3=20HWLAB=20=E5=8F=8C?= =?UTF-8?q?=E7=8E=AF=E5=A2=83=E4=B8=8E=E7=BA=AF=20Kafka=20=E6=9D=83?= =?UTF-8?q?=E5=A8=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-subagent/SKILL.md | 4 + ...60714-pure-kafka-architecture-deviation.md | 84 ++++++++ ...-0104010803-workbench-unique-projection.md | 2 + ...0401080313-workbench-realtime-authority.md | 23 ++- .../specs/PJ2026-010601-controlled-release.md | 1 + ...026-01060106-hwlab-dev-production-lanes.md | 182 ++++++++++++++++++ 6 files changed, 289 insertions(+), 7 deletions(-) create mode 100644 project-management/PJ2026-01/deviations/PJ2026-010401080313-20260714-pure-kafka-architecture-deviation.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md diff --git a/.agents/skills/unidesk-subagent/SKILL.md b/.agents/skills/unidesk-subagent/SKILL.md index 6f60eae5..d3703917 100644 --- a/.agents/skills/unidesk-subagent/SKILL.md +++ b/.agents/skills/unidesk-subagent/SKILL.md @@ -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； diff --git a/project-management/PJ2026-01/deviations/PJ2026-010401080313-20260714-pure-kafka-architecture-deviation.md b/project-management/PJ2026-01/deviations/PJ2026-010401080313-20260714-pure-kafka-architecture-deviation.md new file mode 100644 index 00000000..b0a123a8 --- /dev/null +++ b/project-management/PJ2026-01/deviations/PJ2026-010401080313-20260714-pure-kafka-architecture-deviation.md @@ -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、迁移与回退方案，并取得用户明确授权；新增测试只能验证已授权架构，不能反向把未经授权的实现合法化。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md index 0f4f853a..b1797897 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md +++ b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md @@ -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唯一投影需求规格 diff --git a/project-management/PJ2026-01/specs/PJ2026-010401080313-workbench-realtime-authority.md b/project-management/PJ2026-01/specs/PJ2026-010401080313-workbench-realtime-authority.md index 97ee400e..d8b63013 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401080313-workbench-realtime-authority.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401080313-workbench-realtime-authority.md @@ -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. 过程控制 diff --git a/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md b/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md index 7e7a8c8f..6a0d9e6b 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md +++ b/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md @@ -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. 原子需求 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md b/project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md new file mode 100644 index 00000000..78095709 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01060106-hwlab-dev-production-lanes.md @@ -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:`；实施任务应探测空闲端口并把最终值固化到 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 验证完成。