docs(devlevel): 固化 L1 native 独立执行边界

2026-07-21 01:36:26 +02:00
parent 46183cf44b
commit 10e93f17f9
3 changed files with 64 additions and 40 deletions
@@ -43,12 +43,23 @@ description: >-
 ## L1 Native

 - 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。
+- L1 的执行面在任何情况下都固定为本机 native 进程，不依赖 CI/CD、GitOps、
+  Kubernetes、集群 rollout 或运行时镜像：
+  - API、Worker 和 Web 必须由 owning YAML 选中的 host workspace 与项目受控
+    lifecycle CLI 拉起；
+  - CLI `--over-api` 回归可以直接访问 owning YAML 固定端口上的 native API；
+  - 本机调用可使用 YAML 解析出的 probe host，跨主机或用户入口使用 YAML
+    声明的固定 native 地址；
+  - 正常启动、首次拉起、配置变更、合并后复测和故障处理都不得等待或调用
+    PipelineRun、Argo、Deployment、ConfigMap 或镜像交付；
+  - 需要上述集群对象才能复现或验收时，该部分已经属于 L2，不得继续标为 L1。
 - 每个 L1 服务必须使用 owning YAML 或项目规格声明的端口：
  - 同一服务的旧 L1 进程占用时，通过项目 CLI 停止或重启，再使用 YAML 当前端口；
  - 其他服务占用时，禁止停止、接管或复用其他服务；
  - 确认空闲端口后修改本服务 owning YAML，再由 parser/CLI 读取新端口继续；
  - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。
- 固定端口、bind/probe、首选 HTTPS origin、固定公网 HTTP 降级入口、状态目录和服务组成必须由 YAML-first 配置解析；代码和命令行不得补隐式默认值。
+- 固定端口、bind/probe、状态目录和服务组成必须由 YAML-first 配置解析；
+  代码和命令行不得补隐式默认值。
 - L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。
 - L1 开发、诊断或验收中发现受控 CLI 问题时，可以在当前任务内即时修改并完成最小验证：
  - 问题范围包括 parser、lifecycle、transport、输出、错误码、可见性和帮助；
@@ -61,37 +72,23 @@ description: >-
  - 一次性 disposable smoke 可以按自身隔离合同清理，但不能替代可持续访问的 L1 服务；
  - 任务结束前必须重新读取 lifecycle status，不能凭启动返回值推断服务仍在运行。
 - CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。
- Web 使用 `$unidesk-webdev` 的受控入口，从 owning YAML 当前选中的首选 HTTPS origin 或固定公网 HTTP 降级入口访问 native Web。
+- Web 使用 `$unidesk-webdev` 的受控入口访问 owning YAML 固定端口上的 native Web。
 - 微服务项目只启动当前微服务的前端、API、Worker及必要依赖。
 - 前端、API 和 Worker可以分别启动、查看日志、重启和停止。
- 所有 L1 API/Web 用户入口必须由 owning YAML 声明和选择：
-  - 固定 HTTPS origin 是首选入口；
-  - 共享 public-edge、TLS、DNS 或出网故障导致 HTTPS 不可用时，必须立即降级到 owning YAML 解析出的固定公网 HTTP IP 与 port，不能因公共面故障停止 L1 业务调试或验收；
+- L1 API/Web 入口必须由 owning YAML 声明和选择：
  - `0.0.0.0` 只表示进程 bind；
-  - `127.0.0.1` 只用于本机 probe 或进程间代理；
-  - 固定公网 HTTP 入口的 IP 与 port 必须由 owning YAML 显式声明或从其中的公网地址和服务固定端口确定，禁止随机端口、localhost、命令行拼接或代码默认值；
-  - HTTP 降级不得关闭或绕过业务认证，不得新增第二 Caddy、FRP、代理或业务路径；
-  - 降级后先验证公网 HTTP readiness，再通过同一 API、Worker、SSE 和页面业务路径继续原 L1 验收；仅探测到端口或 HTTP 200 不构成业务通过；
-  - 内部端口冲突时通过 owning YAML 退让到空闲端口，固定 HTTPS origin 保持不变。
- L1 使用共享 public-edge 时：
-  - 只允许修改本服务 owning YAML 的 `publicExposure` 与聚合 YAML 的 `configRef/path`；
-  - 只允许执行 `platform-infra public-edge plan|status` 或 `apply --dry-run`；
-  - 禁止执行、提示或恢复 `public-edge apply --confirm`、内部 `reconcile`、Caddyfile 写入或容器重建；
-  - 公网配置随正常 `master` merge 由唯一 PaC authority 自动收敛；
-  - 自动链未收敛时使用 `$unidesk-cicd` 只读归因并登记独立公共面 issue，不由 L1 会话补写；
-  - 公共面 issue 不得阻塞业务主线，确认固定公网 HTTP 降级入口可用后必须立即继续 L1；
-  - HTTPS 恢复后从正式 origin 复测并撤回 HTTP 降级状态。
- L1 验收命令必须实际从当前选中的公网 HTTPS 或固定 HTTP 入口打开页面和 API；本机 `127.0.0.1`/`localhost` 只可作为进程健康 probe，不构成 L1 证据。
- 涉及 L1 的任务在结束时必须报告公网入口：
-  - 报告 owning YAML 声明的固定 HTTP/HTTPS origin 和当前可用状态；
-  - 存在页面路径时同时报告可直接访问的完整 URL；
-  - HTTPS 未就绪但固定公网 HTTP 已通过时，明确报告 `degraded`、公共面 issue 和固定 HTTP URL，并继续交付；
-  - 两种公网入口都不可用时才报告 L1 公网 blocker，禁止用 localhost、bind 地址、随机 IP 或随机端口冒充公网入口。
- 执行任何 L1 流程时必须扫描当前项目已声明的 L1：
-  - 发现历史 L1 尚未配置固定 HTTPS exposure 时，立即建立可追踪记录；
-  - 发现一例就完成该实例的 YAML-first exposure、受控部署和原入口验收；
-  - HTTPS 未收敛但固定公网 HTTP 降级入口已通过时，公共面问题独立跟踪，当前 L1 流程继续；禁止把公共面问题变成核心业务门禁。
- HWLAB 的端口退让与公网验收细则以 `docs/reference/hwlab.md#workbench-浏览器回归专项` 为唯一权威，并由 `$unidesk-webdev` 执行。
+  - 同 host 的 CLI、服务间调用和浏览器回归可以使用 YAML probe host 与固定端口；
+  - 跨 host 调用使用 YAML 声明的固定 native host 与端口；
+  - 禁止随机端口、临时 URL、命令行覆盖和代码默认值。
+- L1 验收以 native 服务为准：
+  - lifecycle status 必须证明 API、Worker 和 Web 进程仍在运行且 health ready；
+  - CLI 必须通过 native `--over-api` 完成真实业务操作；
+  - Web 必须通过 native Web 完成受影响页面和交互；
+  - localhost 或 probe host 只要来自 owning YAML，就可以作为同 host L1 证据。
+- 公网域名、TLS、public-edge 和固定公网入口属于独立暴露检查：
+  - 不进入 L1 启动、执行、回归和完成条件；
+  - L1 任务不得调查、等待或操作其 CI/CD、GitOps、Argo 或 Kubernetes；
+  - 用户明确要求 L2 或独立公共面运维时，才进入对应专项流程。
 - 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。

 ## L2 Development
@@ -101,6 +101,23 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
  - 使用目标 provider、pod 或 Windows route 的最小闭环证明；
  - 只有证据显示 client 侧无法规避边界时，才进入 provider-gateway 变更流程。

+## L1 Native 执行边界
+
+- L1 只使用 host 上的 native API、Worker、Web 和必要基础依赖：
+  - 服务从 owning YAML 解析固定 workspace、端口、状态目录和依赖；
+  - 启动、停止、重启、状态和日志统一走项目受控 lifecycle CLI；
+  - `--over-api` 直接调用该 native API，不经过 Kubernetes Service 或集群 workload。
+- L1 在任何情况下都不依赖 CI/CD、GitOps、Argo、Kubernetes、镜像发布或
+  集群 rollout：
+  - 正常启动、首次拉起、配置变更、合并后复测和故障处理都不等待这些系统；
+  - 不用这些系统更新、修复或验收 L1 运行面；
+  - 必须依赖集群对象的验证属于 L2。
+- L1 始终使用本机小回环：
+  - 通过 owning YAML 固定 native 端口完成 API、Worker、Workflow 和 Web 回归；
+  - 同 host 可使用 YAML probe host，跨 host 使用 YAML 固定 native host；
+  - 公共入口状态独立记录，不能成为 L1 业务门禁；
+  - L1 任务不进入 CI/CD、Kubernetes 和 public-edge 调查或操作。
+
 ## L1 受控 CLI 即时修复

 - 执行 L1 开发、诊断或验收时，发现项目受控 CLI 存在问题即可在当前任务内即时修改：
@@ -102,9 +102,18 @@ HWLAB v0.2/v0.3 仓库内 `docs/reference/spec-*`，以及已收编的 `cloud-wo
  - development `NC01/v03` 前端/API 入口为 `https://lab-dev.hwpod.com`；
  - production release lane `NC01/production` 的正式入口为 `https://lab.hwpod.com`。
 - HWPOD L1 Native 是独立于 Cloud Web 的运行面：
-  - API、Temporal worker、Web、固定端口和公网入口必须从 `config/hwlab-node-lanes.yaml#lanes.<lane>.targets.<node>.nativeDevelopment.hwpod` 读取；
+  - API、Temporal worker、Web 和固定端口必须从 owning YAML 读取：
+    - `config/hwlab-node-lanes.yaml#lanes.<lane>.targets.<node>.nativeDevelopment.hwpod`；
  - 启停和状态统一使用 `hwlab nodes native-development hwpod api|worker|web`；
-  - 公网验收统一使用 `web-probe native-readiness --node <node> --lane <lane> --profile hwpod`；
+  - L1 API、worker 和 Web 是 NC01 host 上的 native 进程：
+    - 任何情况下都不依赖 CI/CD、GitOps、Argo、Kubernetes 或集群 rollout；
+    - 正常启动、首次拉起、配置变更、合并后复测和故障处理均适用；
+  - CLI `--over-api` 直接调用 owning YAML 固定端口上的 native API：
+    - 同 host 回归使用 YAML probe host；
+    - 禁止改走 Cloud API 或 Kubernetes Service；
+  - L1 只验收本机 API、worker、Web 小回环：
+    - 公网入口与 public-edge 是独立可选检查；
+    - 不得成为 L1 启动、执行或完成条件；
  - HWPOD Web 无业务登录页时，由 owning YAML profile 声明 `authentication: none`，不得改用临时 Playwright 脚本或弱化浏览器错误断言。
 - Windows HWPOD-NODE 的连接入口和制品入口属于不同合同：
  - WebSocket 注册入口来自节点 YAML 的桌面连接配置；
@@ -196,16 +205,17 @@ Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../..
  - 端口被同一 L1 服务的旧进程占用时，只能通过项目 CLI 停止或重启该服务；
  - 端口被其他服务占用时，禁止停止、接管或复用其他服务；
  - 必须先确认空闲端口，再修改 `config/hwlab-node-lanes.yaml#lanes.<lane>.targets.<node>.nativeDevelopment.workbench` 中本服务的端口；
-  - API、Worker、Web 的启动、状态和固定 HTTPS 入口继续由同一 YAML 与 `hwlab nodes native-development workbench` 解析；
+  - API、Worker、Web 的启动和状态继续由同一 YAML 与 `hwlab nodes native-development workbench` 解析；
  - 禁止用命令行参数、临时环境变量或代码 fallback 形成第二端口真相；
-  - 端口退让后固定 HTTPS 域名保持不变，并从该域名执行 `web-probe native-readiness`，确认页面、DOM、交互和浏览器错误均通过后再向用户披露入口。
- L1 Native 公网暴露与降级：
-  - `nativeDevelopment.<application>.publicExposure` 声明首选固定 HTTPS origin；
-  - HTTPS 因 public-edge、TLS、DNS 或出网故障不可用时，必须降级到同一 owning YAML 解析出的固定公网 HTTP IP:port，并继续 L1；
-  - 固定 HTTP 降级入口必须保持业务认证，禁止随机端口、localhost、临时 URL、第二代理或第二业务路径；
-  - 降级后先验证公网 readiness，再通过同一 Workbench API、Worker、Kafka SSE 与 Web 路径完成原验收；端口监听或 HTTP 200 不能替代业务验收；
-  - HTTPS 故障独立登记为非阻塞公共面 issue，不得等待回复或恢复后才继续业务；
-  - 公共面恢复后从固定 HTTPS origin 复测，并撤回 HTTP 降级状态。
+  - 端口退让后从 owning YAML 的 native probe host 和固定端口执行
+    `web-probe native-readiness`，确认页面、DOM、交互和浏览器错误均通过。
+- L1 Native 暴露边界：
+  - `nativeDevelopment.<application>.publicExposure` 只描述独立公共入口；
+  - 公网域名、TLS、public-edge 和固定公网入口不进入 L1 启动、执行、回归和
+    完成条件；
+  - L1 不调查、等待或操作公共面的 CI/CD、GitOps、Argo、Kubernetes、镜像或
+    rollout；
+  - 只有用户明确要求 L2 或独立公共面运维时，才进入对应专项流程。

 - Workbench L1 API 与 Kafka SSE 验收：
  - API 进程存活入口固定为 `/health/live`；