@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,48 @@
+# CAGE-APPR-001：可路由字段不存在
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+approval.routable 引用了所属聚合没有声明的字段。
+
+## 修复步骤
+
+1. 先在聚合声明实际字段，再将需要给审批路由的字段放入 routable；不要把任意输入直接交给流程。
+
+## 正例
+
+```text
+routable: ['amount', 'deptId'] // 两字段均在 PurchaseOrder.fields 中
+```
+
+## 反例
+
+```text
+routable: ['managerName'] // 聚合没有该字段
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:159`
+- `packages/kernel/src/primitives/flow.ts:245`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        for (const field of s.context.fields) if (!binding.agg.fields[field] || binding.agg.fields[field].isHidden)
+          throw declError('CAGE-APPR-001', `AI 上下文字段 ${field} 不存在或不可公开`);
+        for (const query of s.context.queries ?? []) if (!registry.queries.some(q => q.name === query))
+          throw declError('CAGE-REG-001', `AI 步骤引用的查询 ${query} 未导出`);
+      }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-APPR-002：审批结论落到其他聚合
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+onApproved 或 onRejected 的命令不属于当前审批绑定的聚合。
+
+## 修复步骤
+
+1. 把结论绑定到当前单据的命令；后续跨对象动作通过该命令的事件和反应完成。
+
+## 正例
+
+```text
+PurchaseOrder 的审批绑定使用 approvePurchaseOrder 命令
+```
+
+## 反例
+
+```text
+采购审批 onApproved 直接绑定 InventoryLock.acquire
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:248`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const c of [def.onApproved, def.onRejected, ...(def.onReturned ? [def.onReturned] : [])]) {
+    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-APPR-003：审批结论未允许流程调用
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+审批结论命令的 invokedBy 不包含 process。
+
+## 修复步骤
+
+1. 将结论命令声明为 process；前端通过待办接口审批，不要为了显示按钮把结论改成用户可直调。
+
+## 正例
+
+```text
+invokedBy: 'process'
+```
+
+## 反例
+
+```text
+invokedBy: 'user' // 用作审批结论
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:250`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+  }
+  return Object.freeze({
+```

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

@@ -0,0 +1,47 @@
+# CAGE-APPR-004：路由没有对应审批绑定
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+运行审批桥接时，route 的 process 找不到同名 approval 绑定。
+
+## 修复步骤
+
+1. 检查 process 名完全相同，绑定和路由均从 domain 入口导出。
+
+## 正例
+
+```text
+approval(..., { process: 'po-approval', ... }) 与 route('po-approval', ...)
+```
+
+## 反例
+
+```text
+绑定叫 po-approval，路由叫 purchase-approval
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/bridge.ts:14`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const binding = k.registry.approvalByProcess(r.process);
+  if (!binding) throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
+```

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:126`
+
+实现片段（位置随框架版本更新）：
+
+```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,53 @@
+# 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/bridge.ts:16`
+- `packages/approval/src/engine.ts:70`
+- `packages/approval/src/route.ts:66`
+- `packages/approval/src/route.ts:68`
+- `packages/approval/src/route.ts:127`
+- `packages/approval/src/route.ts:154`
+- `packages/approval/src/route.ts:156`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
+  if (r.lastApprover) {
+    const user = await k.contextFor(r.lastApprover, r.tenantId);
+```

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:81`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (who.length === 0) {
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${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, 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:175`
+- `packages/cli/src/rules.ts:189`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-APPR-010：invokedBy 为 process 的命令必须有审批绑定或反应调用它，否则没有人能调用 */
+/**
+ * 检查仅流程/外部可调用的命令是否有声明调用入口。
+ * @param g 当前图。
+```

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

@@ -0,0 +1,53 @@
+# CAGE-AUDIT-001：可靠读取审计失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：安全读侧 / 查询。
+
+敏感明文读取，或声明 audit.purpose 的查询，无法完成交付前的审计写入。请求拒绝交付结果。
+
+## 修复步骤
+
+1. 凭 requestId 检查审计存储、写账号权限和数据库可用性；修复后重新读取。
+2. 不要吞掉审计异常、去除敏感声明或改用基表绕过审计。查询只声明目的，不把敏感输入放进目的文本。
+
+## 正例
+
+```text
+query('report', { reads: [Order], audit: { purpose: '月度核对' }, /* input/sql */ })
+```
+
+## 反例
+
+```text
+审计写入失败后继续返回敏感明文
+```
+
+## 修复后验证
+
+修复审计存储后重新读取，确认有权交付的数据与相应审计均完成。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/read.ts:136`
+- `packages/kernel/src/read.ts:137`
+- `packages/kernel/src/read.ts:284`
+- `packages/kernel/src/read.ts:285`
+- `packages/kernel/src/transfer/index.ts:176`
+- `packages/kernel/src/transfer/index.ts:177`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    }); } catch {
+      this.k.log.error({ code: 'CAGE-AUDIT-001', aggregate: agg.name, kind, requestId: ctx.requestId }, '读取审计失败，未交付数据');
+      throw cageError('INTERNAL', { diagnostic: 'CAGE-AUDIT-001', phase: 'audit', operation: kind, retryable: true });
+    }
+  }
+```

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:25`
+
+实现片段（位置随框架版本更新）：
+
+```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-BIZ-001.md

@@ -0,0 +1,51 @@
+# CAGE-BIZ-001：业务流程声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 图规则。
+
+流程或板块标识重复、名称说明缺失、入口/连线/结束阶段无效，或引用的真实声明未从 domain 导出。
+
+## 修复步骤
+
+1. 使用 businessProcess 声明阅读规格，填写流程、板块、阶段及连线说明；阶段引用已导出的真实业务声明。
+2. 主对象使用聚合引用；相同板块 ID 的名称和说明保持一致。流程不调度命令，也不授予权限。
+
+## 正例
+
+```text
+export const orderFlow = businessProcess('order-flow', { /* 完整阶段和转移，均引用真实声明 */ });
+```
+
+## 反例
+
+```text
+transitions: [{ from: 'draft', to: 'missing', mode: 'automatic', label: '继续' }] // missing 阶段不存在
+```
+
+## 修复后验证
+
+重跑 cage check，再在 cage graph 中检查主线、分支、关联和实现代码；运行行为仍需相应业务回归。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/business-process.ts:132`
+- `packages/kernel/src/registry.ts:253`
+- `packages/kernel/src/registry.ts:256`
+- `packages/kernel/src/registry.ts:259`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): BusinessProcess {
+  const invalid = (reason: string): never => { throw declError('CAGE-BIZ-001', `${name}：${reason}`); };
+  const identifier = (value: string) => /^[a-z][a-z0-9-]*$/.test(value);
+  const text = (value: string) => typeof value === 'string' && value.trim().length > 0;
+  if (!identifier(name) || !identifier(def.area.id)) invalid('流程与板块标识须使用小写短横线格式');
+```

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

@@ -0,0 +1,49 @@
+# CAGE-BIZ-002：业务流程与真实声明不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 图规则。
+
+阶段不可达或无法结束，自动连线缺少真实触发链，人工/等待方式与目标入口不符，同对象状态不相接，或关联对象缺少实现依据。
+
+## 修复步骤
+
+1. 自动连线必须有 emits、事件触发、反应目标、审批结论或外部成功回写支持；reads、字段关联和状态相接不能证明自动调用。
+2. 人工下一步使用用户可调用的命令，独立通知或调度使用 wait；核对前后命令的状态约束。
+3. 关联的 via 引用本阶段实际可触发的声明，且该声明确实读取、写入或引用目标对象。补齐入口到所有阶段，以及各阶段到结束结果的路径。
+
+## 正例
+
+```text
+{ from: 'draft', to: 'submit', mode: 'manual', label: '申请人提交' } // submit 允许 user 且状态相接
+```
+
+## 反例
+
+```text
+{ from: 'create', to: 'submit', mode: 'automatic', label: '自动提交' } // 只有状态相接，没有实际触发
+```
+
+## 修复后验证
+
+重跑 cage check，再在 cage graph 中检查主线、分支、关联和实现代码；运行行为仍需相应业务回归。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/process-rules.ts:50`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const fail = (node: ViewNode, reason: string, fix: string) => findings.push({
+    code: 'CAGE-BIZ-002', at: node.file ? `${node.file}:${node.line}` : node.id, reason, fix,
+  });
+  const actual = (start: string) => reachable(start, key => causalSuccessors(model, key));
+  const involving = (start: string, target: string) => {
+```

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:85`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-001',
+      reason: `内核 ${lines} 行，超过 5000 行预算`,
+      fix: '拆出扩展职责，或提交架构评审调整预算',
+    });
+```