docs: specify project management hwpod auth

2026-06-26 07:49:55 +00:00
parent db136bd261
commit 695dc48aff
1 changed files with 5 additions and 2 deletions
@@ -85,7 +85,7 @@
 | 配置类别 | 示例 | 归属 | 输出边界 |
 | --- | --- | --- | --- |
 | 非 Secret 目标事实 | nodeId、laneId、namespace、hwpodId、workspaceRootRef、projectRoot、Keil project、target、probe UID、UART、board-comm endpoint、ioProbe id、ConfigMap 和 mount path | UniDesk/HWLAB owning YAML | 可输出 YAML path、presence、摘要 hash、fingerprint、目标 id 和缺失字段；不得在代码中硬编码为 fallback。 |
-| Secret 或敏感运行凭据 | API key、maintenance token、JWT/encryption key、gateway auth token、database URL、provider credential | YAML sourceRef/targetKey 或外部 Secret source | 只输出对象名、key 名、sourceRef、presence、字节数和 fingerprint；不得打印完整值、base64 payload、DSN 或可复制 token。 |
+| Secret 或敏感运行凭据 | API key、maintenance token、JWT/encryption key、gateway auth token、project-management HWPOD node-ops bearer、database URL、provider credential | YAML sourceRef/targetKey 或外部 Secret source | 只输出对象名、key 名、sourceRef、presence、字节数和 fingerprint；不得打印完整值、base64 payload、DSN 或可复制 token。 |
 | 迁移输入 | 旧 `.device-pod` profile、旧 v0.2 direct-url、D601 Windows 本地 profile | 一次性调查/迁移证据 | 不作为 runtime registry authority；只允许转换为 YAML 声明后进入运行面。 |

 ## 5. 内部分工与规格索引
@@ -132,6 +132,7 @@ flowchart LR
  Lane --> PM[hwlab-project-management/constart-71freq-mdtodo.yaml]
  PM --> Source[sourceId constart-71freq<br/>sourceKind hwpod-workspace]
  PM --> Ops[HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_URL]
+  PM --> OpsAuth[HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_API_KEY secretRef]
  Lane --> GW[hwlab-gateway/constart-71freq-d601-v03.yaml]
  GW --> SecretRefs[gateway/API Secret sourceRefs]
 ```
@@ -211,7 +212,7 @@ CaseRun smoke 只要求证明 71-FREQ 最小硬件链路能通过 HWPOD 服务 r

 71-FREQ 预装配置必须由 UniDesk YAML 承载，并通过 configRef 串联 node/lane、HWPOD spec、metadata、project-management source、gateway profile、public/API origin 和 Secret sourceRef。代码只负责解析、校验和渲染，不得内置 `D601`、`v03`、`constart-71freq-c`、`F:\Work\ConStart`、Keil 路径、COM 口、probe UID、board-comm IP、ioProbe id、旧 cloud URL 或 gateway/session id 作为 fallback。

-HWPOD preinstall owning YAML 至少应声明 hwpodId、sourceRef、metadataRef、targetDevice、nodeBinding、workspaceRootRef、projectRoot、toolchain、debugProbe、uart、boardComm endpoints、ioProbe、ConfigMap 名称、mount path、environment key 和 rollout target。71-FREQ 的 boardComm endpoints 必须显式包含 `freq71` 和 `main41`，ioProbe 必须显式包含 `main41.ai0.current`，这些字段必须进入最终挂载给 cloud-api 的 `specDocument`，不能只停留在运维 YAML 的旁路摘要字段。MDTODO source owning YAML 至少应声明 sourceId、sourceKind、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef、focus files 和 hwpod node ops URL configRef。Gateway profile owning YAML 至少应声明 cloudUrl、nodeOps websocketUrl、gatewayId、sessionId、resourceId、capabilityId、secretRefs、runtimeRoot、bunPath、taskName、periodicTaskName、runKeyName、start/status command、processPattern 和重连参数；代码不得为这些运行面事实提供隐藏默认。
+HWPOD preinstall owning YAML 至少应声明 hwpodId、sourceRef、metadataRef、targetDevice、nodeBinding、workspaceRootRef、projectRoot、toolchain、debugProbe、uart、boardComm endpoints、ioProbe、ConfigMap 名称、mount path、environment key 和 rollout target。71-FREQ 的 boardComm endpoints 必须显式包含 `freq71` 和 `main41`，ioProbe 必须显式包含 `main41.ai0.current`，这些字段必须进入最终挂载给 cloud-api 的 `specDocument`，不能只停留在运维 YAML 的旁路摘要字段。MDTODO source owning YAML 至少应声明 sourceId、sourceKind、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef、focus files、hwpod node ops URL configRef 和 HWPOD node-ops API key sourceRef；project-management Deployment 只能通过显式 env/SecretRef 注入该 bearer，不得匿名调用 cloud-api 管理 HWPOD route。Gateway profile owning YAML 至少应声明 cloudUrl、nodeOps websocketUrl、gatewayId、sessionId、resourceId、capabilityId、secretRefs、runtimeRoot、bunPath、taskName、periodicTaskName、runKeyName、start/status command、processPattern 和重连参数；代码不得为这些运行面事实提供隐藏默认。

 ### 6.2 HWPOD-PRE-REQ-002 Runtime discovery 与 HWPOD工具验证

@@ -243,6 +244,8 @@ v0.2 不再是兼容目标。受控 `apply` 必须从 YAML 生成 v0.3+ runner/e

 Project-management MDTODO source 必须使用 `sourceKind=hwpod-workspace` 和公共 HWPOD workspace ops 读取 71-FREQ 工作区内的 Markdown todo 文件。MDTODO 页面、sources/files/tasks API 和后续 web-probe 验收只通过 sourceId、projectId、hwpodId、nodeId 与 HWPOD 关联；不得把 Workbench 组件嵌入 MDTODO，也不得让 MDTODO 服务直接读取 D601 文件系统、SSH、Windows share、旧 submodule 路径或第二套文件 reader。

+当 project-management service 需要调用 cloud-api `/v1/hwpod-node-ops` 执行 workspace ops 时，必须使用 YAML 声明的 `HWLAB_PROJECT_MANAGEMENT_HWPOD_NODE_OPS_API_KEY` SecretRef 作为 bearer 认证，并继续在下游请求中保留服务来源标识。缺少该 SecretRef 或认证失败应作为 project-management source blocker 暴露，不能降级为匿名内部 route、旧 direct-url、SSH 读取或本地文件 fallback。
+
 71-FREQ MDTODO 的实际 authority 是 `F:\Work\ConStart\docs\MDTODO`。source config 应能选择 focus files，例如 `20260419_频率判断.md`、`20260609_频率判断_用户反馈.md` 和 `details/`，并在 reindex 后通过 public API 返回 source、file 和 task 摘要。Markdown 正文默认不进入 issue evidence 或 CLI 普通输出。

 ### 6.5 HWPOD-PRE-REQ-005 顶层 web-probe 与 readMdtodo 验收