@yss123/cage-cli 0.0.0-stage → 0.2.0

package/templates/app/docs/errors/CAGE-APPR-005.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-005：流程名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+route 的流程标识不是小写字母开头的小写短横线格式。
+
+## 修复步骤
+
+1. 使用稳定的小写短横线标识；需要中文显示时修改 step 标题或图谱 label，不翻译标识。
+
+## 正例
+
+```text
+route('po-approval', nodes)
+```
+
+## 反例
+
+```text
+route('采购审批', nodes)
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:96`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function route(process: string, nodes: RouteNode[]): Route {
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+```

package/templates/app/docs/errors/CAGE-APPR-006.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-006：流程没有步骤
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+route 接收了空步骤数组。
+
+## 修复步骤
+
+1. 声明至少一个实际审批步骤，并检查条件后能否形成预期流程。
+
+## 正例
+
+```text
+route('po-approval', [step('经理审批', approver.deptLeader('deptId'))])
+```
+
+## 反例
+
+```text
+route('po-approval', [])
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:97`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+    const steps = n.kind === 'step' ? [n] : n.steps;
+```

package/templates/app/docs/errors/CAGE-APPR-007.md

@@ -0,0 +1,50 @@
+# CAGE-APPR-007：找不到审批人
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+worker 启动或推进审批步骤时，选人器没有找到人。
+
+## 修复步骤
+
+1. 先看本项目 approvals.ts：deptLeader 读取单据部门的负责人；role 使用角色 code；user 使用实际用户 UUID。
+2. 在 /admin 设置单据所属部门的负责人，或创建对应 code 的角色并分配实际用户。给用户经理角色，并不等于设置了部门负责人。
+3. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
+4. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
+
+## 正例
+
+```text
+deptLeader('deptId')：给该部门设置负责人；role('finance')：给实际用户分配 code=finance 的角色
+```
+
+## 反例
+
+```text
+只建中文名为“财务”的角色却没有配置 code/用户，或配置后重复提交已是 pending_approval 的单据
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/engine.ts:64`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (who.length === 0) {
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${s.title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
+    }
+    for (const assignee of new Set(who)) {
+      await tx.insertInto('flow.approval_task').values({ instance_id: instanceId, tenant_id: tenantId, step: index, title: s.title, assignee }).execute();
+```

package/templates/app/docs/errors/CAGE-APPR-010.md

@@ -0,0 +1,48 @@
+# CAGE-APPR-010：流程专用命令没有调用者
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+命令只允许 process 调用，但图中没有审批结论、反应或任务调用它。
+
+## 修复步骤
+
+1. 补实际 approval/reaction/job 引用并从入口导出；如果本来是用户操作，按需求纠正 invokedBy。不要增加空引用骗过检查。
+
+## 正例
+
+```text
+approve 被 poApproval.onApproved 引用，或 acquireLock 被 lockOnApprove 引用
+```
+
+## 反例
+
+```text
+定义 process 命令但没有任何流程或反应调用
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:140`
+- `packages/cli/src/rules.ts:149`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-APPR-010：invokedBy 为 process 的命令必须有审批绑定或反应调用它，否则没有人能调用 */
+export function checkProcessCommands(g: Ontology): Finding[] {
+  const { into } = index(g);
+  const findings: Finding[] = [];
+```

package/templates/app/docs/errors/CAGE-AUTH-001.md

@@ -0,0 +1,47 @@
+# CAGE-AUTH-001：OIDC 发现文档获取失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：HTTP 登录。
+
+HTTP 无法取得 OIDC issuer 的发现文档，或远端返回非成功状态。
+
+## 修复步骤
+
+1. 检查部署环境 OIDC issuer、发现地址、网络与证书配置；不要关闭认证或把 issuer 校验删掉。
+
+## 正例
+
+```text
+配置可访问的 OIDC_ISSUER、正确客户端和回调地址
+```
+
+## 反例
+
+```text
+将不可访问的 issuer 当作已成功登录并继续建立会话
+```
+
+## 修复后验证
+
+重新走真实 OIDC 登录和回调，确认会话中的用户与授权；不要仅验证发现文档能打开。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/oidc.ts:20`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    (disco ??= fetch(new URL('.well-known/openid-configuration', o.issuer.endsWith('/') ? o.issuer : `${o.issuer}/`)).then(async (r) => {
+      if (!r.ok) throw new Error(`[CAGE-AUTH-001] OIDC 发现文档获取失败：${r.status}`);
+      return (await r.json()) as Discovery;
+    }));
+  const secure = opts.cookieSecure ?? process.env.NODE_ENV === 'production';
+```

package/templates/app/docs/errors/CAGE-BUDGET-001.md

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-001：内核超出体积预算
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+框架源码检查发现内核有效代码行数超过当前 5000 行预算。
+
+## 修复步骤
+
+1. 框架维护者将非内核职责拆为扩展，必要的预算调整需架构评审。独立业务项目不应复制内核源码来修此错误。
+
+## 正例
+
+```text
+第三方业务放到 connectors/业务声明，内核保持通用
+```
+
+## 反例
+
+```text
+直接调大阈值或删除检查
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:45`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-001',
+      reason: `内核 ${lines} 行，超过 5000 行预算`,
+      fix: '拆出扩展职责，或提交架构评审调整预算',
+    });
+```

package/templates/app/docs/errors/CAGE-BUDGET-002.md

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-002：公共原语超过词汇预算
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+框架公共词汇计数超过当前 16 个预算。
+
+## 修复步骤
+
+1. 优先组合现有原语；确需增加公共概念时由框架维护者评审，不由业务项目随意扩展品牌。
+
+## 正例
+
+```text
+用 command/event/reaction 组合新业务
+```
+
+## 反例
+
+```text
+每个业务动作新增一个框架原语
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:51`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-002',
+      reason: `品牌原语 ${primitives} 个，超过 16 个预算`,
+      fix: '优先使用组合子，避免新增原语',
+    });
+```

package/templates/app/docs/errors/CAGE-BUDGET-003.md

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-003：新增未经基线认可的 unsafe
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+本次图中的 unsafe 数超过给定基线；没有基线时允许值为零。
+
+## 修复步骤
+
+1. 优先移除逃生口；确需使用时写明 reason/owner，评审后更新受审基线。不要用刚改后的图冒充旧基线。
+
+## 正例
+
+```text
+unsafe({ reason: '受审的历史修复', owner: '负责人' }, action) 并使用受审基线
+```
+
+## 反例
+
+```text
+随手调用 unsafe，再覆盖基线隐藏增长
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-003',
+      reason: `unsafe 从 ${allowance} 增加到 ${graph.unsafeCount}`,
+      fix: '移除新增逃生口，或在评审完成后更新受审基线',
+    });
+```

package/templates/app/docs/errors/CAGE-CMD-002.md

@@ -0,0 +1,47 @@
+# CAGE-CMD-002：已有记录命令缺少 id
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+非新建命令的对象输入 schema 没有 id，无法确定要加载哪条记录。
+
+## 修复步骤
+
+1. 在 input 添加 UUID id；没有其他输入时可省略 input 使用默认 idOnly。
+
+## 正例
+
+```text
+input: z.object({ id: z.string().uuid(), title: z.string() })
+```
+
+## 反例
+
+```text
+input: z.object({ title: z.string() }) // from 不是 new
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和相关命令测试，检查生成输入/方法签名。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:142`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from !== 'new' && input instanceof z.ZodObject && !('id' in input.shape)) {
+    throw declError('CAGE-CMD-002', `${agg.name} 的非新建命令输入必须包含 id`);
+  }
+  if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
+    throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
+```

package/templates/app/docs/errors/CAGE-CMD-003.md

@@ -0,0 +1,47 @@
+# CAGE-CMD-003：新建命令没有目标状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+from 为 new 时使用 to: null，新记录没有可保留的当前状态。
+
+## 修复步骤
+
+1. 新建必须指向已声明状态；to: null 只用于已有记录的字段更新，仍检查 from、身份、版本并写审计。
+
+## 正例
+
+```text
+from: 'new', to: 'draft' // 或已有记录 from: 'approved', to: null
+```
+
+## 反例
+
+```text
+from: 'new', to: null
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和相关命令测试，检查生成输入/方法签名。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:135`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from === 'new' && def.to === null) {
+    throw declError('CAGE-CMD-003', `${agg.name} 的新建命令必须指定目标状态，不能使用 to: null`);
+  }
+  if (def.to !== null && !hasStates(agg, def.to as string)) {
+    throw declError('CAGE-STATE-001', `${agg.name} 的命令 to 是未声明的状态：${String(def.to)}`);
+```

package/templates/app/docs/errors/CAGE-CONN-001.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-001：连接器名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+connector 的名称不是小写字母开头的小写短横线格式。
+
+## 修复步骤
+
+1. 采用稳定的英文连接器标识，中文名称写 description 或图谱 label。
+
+## 正例
+
+```text
+connector('finance-erp', definition)
+```
+
+## 反例
+
+```text
+connector('FinanceERP', definition)
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:56`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function connector<Ops extends Record<string, OpDef<any, any>>>(name: string, def: ConnectorDef<Ops>): Connector<Ops> {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw declError('CAGE-CONN-001', `连接器名 ${name} 必须是小写短横线`);
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+```

package/templates/app/docs/errors/CAGE-CONN-002.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-002：外部操作路径格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+op.path 没有以斜线开头。
+
+## 修复步骤
+
+1. host 在连接器白名单中配置，操作 path 只写从 / 开始的相对接口路径。
+
+## 正例
+
+```text
+path: '/api/purchase-orders'
+```
+
+## 反例
+
+```text
+path: 'https://erp.example.com/api/orders'
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:29`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function op<Req extends z.ZodObject<any>, Res extends z.ZodType>(def: OpDef<Req, Res>): OpDef<Req, Res> {
+  if (!def.path.startsWith('/')) throw declError('CAGE-CONN-002', `操作路径 ${def.path} 必须以 / 开头`);
+  return def;
+}
+
+```

package/templates/app/docs/errors/CAGE-CONN-003.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-003：地址白名单包含协议或路径
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+connector.hosts 中包含协议、路径或空白，而不是主机名（可带端口）。
+
+## 修复步骤
+
+1. 将协议和路径从 host 移除；实际路径写 op.path，环境 host 按声明配置。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com:8443', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+hosts: { prod: 'https://erp.example.com/api' }
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+  const c: any = {
+    [CONNECTOR]: true,
+```

package/templates/app/docs/errors/CAGE-CONN-004.md

@@ -0,0 +1,47 @@
+# CAGE-CONN-004：只读操作被用作出站写映射
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+outbound 绑定了 effect 为 read 的操作。
+
+## 修复步骤
+
+1. 按真实副作用给操作声明 write/retryableWrite；有可重试写入时设计远端幂等协议，不能只改标签。
+
+## 正例
+
+```text
+effect: 'retryableWrite' // 第三方实际支持幂等写入
+```
+
+## 反例
+
+```text
+effect: 'read' // 却在业务事件后创建远端订单
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:99`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Outbound<E, O> {
+  if (operation.effect === 'read') throw declError('CAGE-CONN-004', '只读操作不能用于出站映射');
+  const o: any = {
+    [OUTBOUND]: true,
+    event: ev,
+```