docs(devlevel): 固化 L1 native 独立执行边界
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user