docs: 规定 HWPOD runtime spec 使用 host PostgreSQL
This commit is contained in:
pikastech
@@ -98,15 +98,23 @@ HWPOD工具应提供 spec 新建、读取、列表、修改、删除、validate
|
||||
|
||||
Spec 工具必须以 HWPOD 标准为准输出校验结果。服务端 registry 可以提供 authority 摘要，但工具不得用服务端缺省值静默补齐未声明的危险写操作能力。
|
||||
|
||||
Spec CRUD 必须在 L0 与 L1 使用同一 repository 合同：
|
||||
Spec CRUD 必须在 L0-L3 使用同一 PostgreSQL repository 合同：
|
||||
|
||||
- L0 由 `hwpod spec list|get|create|update|delete --local` 直接调用 native function；
|
||||
- L1 由同一命令加 `--over-api` 调用 owning YAML 固定端口上的 HWPOD API；
|
||||
- L0 由 `hwpod spec list|get|create|update|delete --local` 直接调用 native function，
|
||||
并从 owning YAML 的 Secret sourceRef 连接 development host PostgreSQL；
|
||||
- L1 由同一命令加 `--over-api` 调用 owning YAML 固定端口上的 HWPOD API，
|
||||
API 与 L0 连接同一个 development database；
|
||||
- L2 的 development API 与 L0/L1 使用同一个 development database，
|
||||
L3 使用 production owning YAML 声明的 production database；
|
||||
- database、role、endpoint、Secret sourceRef、连接 key 和 schema/table identity
|
||||
必须来自 owning YAML，不得由命令行参数、进程目录或代码默认值补齐；
|
||||
- create 和 update 接收完整 spec document，并在写入前执行与 validate 相同的校验；
|
||||
- list 默认返回有界摘要，get 返回单个完整 document；
|
||||
- create、update 和 delete 必须输出 authority、mutable、frozen、hwpodId 和 mutation；
|
||||
- YAML-first 内置 spec 的 update 和 delete 必须返回 `hwpod_spec_frozen`，不得复制为 runtime spec、写入覆盖层或修改 owning YAML；
|
||||
- runtime spec 与内置 spec 同名时，create 必须返回 `hwpod_spec_frozen`，不得形成遮蔽或优先级覆盖。
|
||||
- filesystem JSON registry、`--runtime-spec-dir` 和 runtime directory env 属于
|
||||
`legacy-retire`，不得作为 fallback、双写、迁移后 overlay 或第二 authority 保留。
|
||||
|
||||
### 6.2 HWPOD-TOOL-REQ-002 执行动作入口
|
||||
|
||||
|
||||
@@ -132,17 +132,35 @@ Registry 必须以 HWPOD 标准解释资源事实。缺失 HWPOD spec 的真实
|
||||
Registry 必须区分两种 authority：
|
||||
|
||||
- `yaml-first-builtin` 来自 owning YAML 解析后注入的内置 spec，`mutable=false`、`frozen=true`；
|
||||
- `runtime` 来自 HWPOD 服务状态目录，`mutable=true`、`frozen=false`，重启后继续可读。
|
||||
- `runtime` 来自 owning YAML 声明的 host PostgreSQL，`mutable=true`、
|
||||
`frozen=false`，API、Worker、Pod 和 host 进程重启后继续可读。
|
||||
|
||||
Runtime repository 必须使用唯一 PostgreSQL authority：
|
||||
|
||||
- development 的 L0、L1 和 L2 共用同一个 host PostgreSQL database；
|
||||
- production 的 L3 使用 production owning YAML 声明的 host PostgreSQL database；
|
||||
- database、role、endpoint、TLS、Secret sourceRef、sourceKey 和 schema/table identity
|
||||
只能来自 owning YAML；
|
||||
- runtime 表以 `hwpod_id` 为唯一键，保存规范化后的完整 `document JSONB`、
|
||||
固定 authority `runtime`、`created_at` 和 `updated_at`；
|
||||
- repository 初始化只执行幂等 schema/table/index migration，不创建隐藏 database、
|
||||
role、凭据或 filesystem fallback；
|
||||
- YAML-first 内置 spec 只在读取时与 PostgreSQL runtime 记录合并，
|
||||
不写入 runtime 表。
|
||||
|
||||
Runtime CRUD 只能修改 `runtime` authority：
|
||||
|
||||
- create 在 hwpodId 不存在时原子写入 runtime state；
|
||||
- create 在 hwpodId 不存在时以唯一键约束和单条事务原子写入；
|
||||
- get 和 list 合并返回内置与 runtime spec，并保留 authority、mutable 和 frozen；
|
||||
- update 只能完整替换已有 runtime spec；
|
||||
- delete 只能删除已有 runtime spec；
|
||||
- update 只能在单条事务中完整替换已有 runtime spec，并保留 `created_at`；
|
||||
- delete 只能在单条事务中删除已有 runtime spec；
|
||||
- 内置 spec 的同名 create、update 和 delete 均返回 `hwpod_spec_frozen`；
|
||||
- runtime spec 不得遮蔽、覆盖、复制或回写 YAML-first 内置 spec。
|
||||
|
||||
filesystem JSON registry、runtime spec directory 参数和目录环境变量属于
|
||||
`legacy-retire`。实现不得保留 filesystem fallback、双写、启动导入、overlay
|
||||
或第二 authority；历史 JSON 只允许通过显式一次性迁移工具处理，不参与正常 CRUD。
|
||||
|
||||
### 6.2 HWPOD-SVC-REQ-002 租约与占用
|
||||
|
||||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||||
@@ -240,8 +258,17 @@ flowchart LR
|
||||
|
||||
### 7.4 验收契约
|
||||
|
||||
- L0：spec、topology、workflow contract 和 typed error 测试通过；runtime CRUD 只修改 disposable state，内置 spec mutation 返回 `hwpod_spec_frozen`。
|
||||
- L1：通过 native API 完成 runtime spec create、list、get、update、delete，并证明 API 重启后 create/update 结果仍可读取。
|
||||
- L0：spec、topology、workflow contract 和 typed error 测试通过；runtime CRUD
|
||||
直接修改 owning YAML 选择的 development host PostgreSQL，内置 spec mutation
|
||||
返回 `hwpod_spec_frozen`。
|
||||
- L0/L1：对同一 runtime spec 做 `--local` 与 `--over-api` 对比复测，
|
||||
两条路径返回一致的 document、authority 和 fingerprint。
|
||||
- L1：通过 native API 完成 runtime spec create、list、get、update、delete，
|
||||
并证明 API 重启后 create/update 结果仍可读取。
|
||||
- L2：development API 完成同一 CRUD，并证明 Deployment/Pod 重启后记录仍可读取；
|
||||
该验证不得使用 Pod filesystem 作为持久化证据。
|
||||
- L3：完成 L2 回归并取得本次生产操作明确授权后，production API 完成有界 CRUD
|
||||
和 Pod 重启持久化验证；测试对象必须清理，内置对象指纹保持不变。
|
||||
- L1：对 YAML-first 内置 spec 的同名 create、update 和 delete 均返回 `hwpod_spec_frozen`，内置 document 指纹保持不变。
|
||||
- L1：API、worker、Web 可分别重启；worker 重启后未完成 workflow 可继续；Web 通过固定入口完成首屏、资源列表和 operation 状态交互。
|
||||
- L1：D601 节点注册后，HWPOD topology 同时显示 node online、spec available 和 capability match；节点断开后显示 node offline，不得伪造硬件成功。
|
||||
|
||||
@@ -154,7 +154,10 @@ flowchart TD
|
||||
Tool --> Evidence[operator validation summary]
|
||||
```
|
||||
|
||||
运行发现要求 `constart-71freq-c` 的 runtime authority 来自挂载目录和 discovery 结果。cloud-api 代码不得把 71-FREQ 路径、COM 口、probe UID、board-comm IP、HWPOD id 或旧 node id 写成隐藏默认值。
|
||||
运行发现要求 `constart-71freq-c` 的 `yaml-first-builtin` authority 来自挂载目录和
|
||||
discovery 结果。该内置对象不写入 runtime PostgreSQL 表。cloud-api 代码不得把
|
||||
71-FREQ 路径、COM 口、probe UID、board-comm IP、HWPOD id 或旧 node id 写成
|
||||
隐藏默认值。
|
||||
|
||||
### 5.4 Windows outbound HWPOD node/gateway 时序图
|
||||
|
||||
@@ -229,6 +232,11 @@ YAML-first 预装 spec 在所有运行等级都必须标记为 `yaml-first-built
|
||||
回写该对象；同名 create、update 和 delete 必须返回 `hwpod_spec_frozen`，并保留
|
||||
owning configRef 与变更前 document 指纹。
|
||||
|
||||
L0-L3 的 runtime spec 必须持久化到对应 owning YAML 声明的 host PostgreSQL。
|
||||
L0/L1/L2 共用 development database，L3 使用 production database；API、Worker、
|
||||
Pod 或 host 进程重启不得丢失 runtime spec。挂载目录只承载只读 YAML-first 内置
|
||||
spec，不得承载 runtime JSON、fallback、双写或覆盖层。
|
||||
|
||||
### 6.3 HWPOD-PRE-REQ-003 D601 Windows v0.3+ 出站托管
|
||||
|
||||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||||
|
||||
Reference in New Issue
Block a user