feat: 建立 NC01 共享公网边缘

docs/reference/platform-infra.md

@@ -10,6 +10,32 @@
 - UniDesk 拥有的 image version、namespace、endpoint、FRP port 与 profile 列表不得隐藏在 helper 常量里；外部工具要求的 TOML、JSON 和 env 仅是边缘渲染格式。
 - 新节点出网 bootstrap 遵循 `docs/reference/yaml-first-ops.md` 的零依赖 host proxy 边界，不得依赖尚未安装的 Docker、k3s、containerd 或包管理器网络能力。
 
+## NC01 共享公网边缘
+
+- `config/platform-infra/nc01-public-edge.yaml` 是 NC01 TCP `80/443` listener、
+  Caddy runtime、workDir、Compose、TLS data/config 和站点聚合顺序的唯一真相。
+- 每个站点只声明 `configRef` 与 `path`：
+  - hostname、upstream、DNS expectation 和 probe path 从产品 owning YAML 解析；
+  - 共享 YAML、renderer 和产品 YAML 不得重复声明同一 hostname 或 upstream；
+  - 路径缺失、对象形状不兼容、hostname 重复或 `expectedA` 不匹配时，
+    `plan/status` 必须精确披露，`apply` 不得补隐藏默认值。
+- 共享边缘复用 `pikaoa-edge` 的 Caddy workDir、data、config、容器名和证书状态；
+  禁止创建第二 Caddy、FRP 或 fallback listener。
+- `platform-infra public-edge apply --confirm` 每次重新读取 YAML 与运行面：
+  - 先生成临时候选 Caddyfile；
+  - 先执行 Caddy adapt 与 validate；
+  - 校验成功后才安装并 reload；
+  - reload 失败时恢复上一份有效 Caddyfile 与 Compose；
+  - 不得基于旧 `status` 结果直接 mutation。
+- 受控入口：
+
+  ```bash
+  bun scripts/cli.ts platform-infra public-edge plan --target NC01
+  bun scripts/cli.ts platform-infra public-edge apply --target NC01 --dry-run
+  bun scripts/cli.ts platform-infra public-edge apply --target NC01 --confirm
+  bun scripts/cli.ts platform-infra public-edge status --target NC01
+  ```
+
 ## Gitea 与 Pipelines-as-Code 边界
 
 - Gitea mirror 与 Pipelines-as-Code 是 UniDesk 运维的 CI source/trigger 服务。`config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml` 分别拥有 mirror/webhook 与 PaC Repository/consumer 配置；repo URL、snapshot、webhook、public exposure、FRP/Caddy port、token sourceRef 和 PaC params 不得隐藏在代码特例中。