@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,47 @@
+# CAGE-SCOPE-001：范围组合子未知
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 范围编译。
+
+角色范围数据或内部调用传入了无法编译的 combinator。
+
+## 修复步骤
+
+1. 使用框架内置 self/dept/deptSubtree/deptSet/all，核对授权数据；别把显示中文当成存储标识。
+
+## 正例
+
+```text
+combinator: 'deptSubtree'
+```
+
+## 反例
+
+```text
+combinator: '部门及下级'
+```
+
+## 修复后验证
+
+重跑 cage check；分别使用本人/部门等实际授权用户验证范围内外结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/scope/index.ts:67`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    default:
+      throw new Error('[CAGE-SCOPE-001] 未知的范围组合子');
+  }
+}
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SCOPE-002：范围字段没有声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 范围编译。
+
+aggregate.scope 指向的部门或创建人字段不存在。
+
+## 修复步骤
+
+1. 在聚合声明真实字段，或改用正确字段名。scope.none 表示无此类字段，不代表不限权限。
+
+## 正例
+
+```text
+fields: { deptId: ref('Dept') }, scope: scope.deptSubtree('deptId')
+```
+
+## 反例
+
+```text
+scope.deptSubtree('departmentId')，fields 只有 deptId
+```
+
+## 修复后验证
+
+重跑 cage check；分别使用本人/部门等实际授权用户验证范围内外结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:187`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const f of [sc.deptField, ownerField]) {
+    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+    if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+    if (f && f !== 'id' && isFile(fields[f])) throw declError('CAGE-FILE-001', `${name} 的范围字段不能使用文件 ${f}`);
+  }
+```

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

@@ -0,0 +1,48 @@
+# CAGE-SECRET-001：运行环境缺少密钥
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / 外呼或回调。
+
+连接器或回调验签使用的密钥名在环境/密钥提供器中没有值。
+
+## 修复步骤
+
+1. 按声明的 secret/验签密钥名在 .env 或部署密钥系统注入，重启对应进程；不把值写进 domain 或日志。
+
+## 正例
+
+```text
+secret: 'ERP_API_TOKEN'，运行环境提供该变量
+```
+
+## 反例
+
+```text
+把实际 token 填进 secret 字段，或打印所有环境变量找值
+```
+
+## 修复后验证
+
+确认源码/日志不含值，重启后验证相应外呼或签名回调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:25`
+- `packages/http/src/routes.ts:88`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const v = process.env[name];
+    if (!v) throw new Error(`[CAGE-SECRET-001] 缺少密钥 ${name}（由密钥管理服务或环境变量注入）`);
+    return v;
+  },
+};
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SECRET-002：源码疑似包含密钥字面量
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / 外呼或回调。
+
+lint 在配置或代码中发现疑似密钥值。
+
+## 修复步骤
+
+1. 删除源码密钥，改为密钥名/环境注入；真实凭证若已暴露要轮换，不仅删掉文案。
+
+## 正例
+
+```text
+verify: hmacSha256('ERP_WEBHOOK_SECRET')
+```
+
+## 反例
+
+```text
+在源码里填真实 API token 或私钥
+```
+
+## 修复后验证
+
+确认源码/日志不含值，重启后验证相应外呼或签名回调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-secret-literal.ts:34`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    docs: { description: '禁止密钥字面量' },
+    messages: { secret: '[CAGE-SECRET-002] 疑似{{what}}写在了代码里：密钥只写名字，值由密钥管理服务注入' },
+    schema: [],
+  },
+  create(context) {
+```

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

@@ -0,0 +1,48 @@
+# CAGE-SENS-001：敏感字段未标注就进入事件
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：图规则。
+
+命令事件载荷包含与聚合同名的敏感字段，却没有对应 sensitive 标记。
+
+## 修复步骤
+
+1. 移除非必要敏感数据，或在事件保持一致 sensitive 标记以便掩码；自定义映射也要审查，字段改名不会自动证明安全。
+
+## 正例
+
+```text
+event('OrderChanged', { phone: text().sensitive('phone') })
+```
+
+## 反例
+
+```text
+聚合 phone 为 sensitive，事件 phone 却是普通 text()
+```
+
+## 修复后验证
+
+重跑 cage check，检查实际 outbox 载荷及普通读结果没有泄漏明文。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:144`
+- `packages/cli/src/rules.ts:163`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-SENS-001：敏感字段不得原样进入事件载荷 */
+/**
+ * 检查事件同名载荷字段是否保留聚合敏感标记。
+ * @param g 当前图。
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SQL-001：SQL 拼接用户值
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint。
+
+lint 发现 SQL 字符串拼接或插值存在注入风险。
+
+## 修复步骤
+
+1. query.sql 使用 :name 命名参数；受支持的 Kysely 构建器绑定值。不要用替换引号等手工转义替代参数化。
+
+## 正例
+
+```text
+sql: 'select id from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+'select id from safe.purchase_order where status = ' + input.status
+```
+
+## 修复后验证
+
+重跑相关 lint/verify，并用正常及特殊字符输入验证参数语义。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-sql-concat.ts:32`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    messages: {
+      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
+      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
+    },
+    schema: [],
+```

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

@@ -0,0 +1,47 @@
+# CAGE-SQL-002：sql.raw 接收动态表达式
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint。
+
+sql.raw 不是固定字面量，可能把输入当作 SQL 结构。
+
+## 修复步骤
+
+1. raw 仅使用固定 SQL 片段，动态值参数化，动态列/排序按声明白名单选择；不把完整用户输入塞到 raw。
+
+## 正例
+
+```text
+sql.raw('count(*)') // 固定片段
+```
+
+## 反例
+
+```text
+sql.raw(input.orderBy)
+```
+
+## 修复后验证
+
+重跑相关 lint/verify，并用正常及特殊字符输入验证参数语义。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-sql-concat.ts:33`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
+      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
+    },
+    schema: [],
+  },
+```

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

@@ -0,0 +1,49 @@
+# CAGE-STATE-001：引用了未声明状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+command.from/to 或 states.initial/terminal 包含状态集合中不存在的值。
+
+## 修复步骤
+
+1. 检查拼写并在同一状态集中声明；new 是创建命令来源，不是需要放进 states 的普通状态。
+
+## 正例
+
+```text
+states('draft', 'done', { terminal: ['done'] })；to: 'done'
+```
+
+## 反例
+
+```text
+to: 'finished'，状态集中只有 done
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:228`
+- `packages/kernel/src/primitives/command.ts:236`
+- `packages/kernel/src/primitives/states.ts:59`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from !== 'new' && !hasStates(agg, from)) {
+    throw declError('CAGE-STATE-001', `${agg.name} 的命令 from 里有未声明的状态：${[from].flat().join(', ')}`);
+  }
+  // 回执等异步元数据可能在单据取消/完成后到达。允许显式保留当前状态，
+  // 避免业务 handler 通过篡改 status 绕过状态机；新建命令必须有实际目标状态。
+```

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

@@ -0,0 +1,47 @@
+# CAGE-STATE-002：状态集合为空
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+states 没有任何字符串状态。
+
+## 修复步骤
+
+1. 声明实际业务状态；无需自定义生命周期时可使用聚合默认状态，但写命令仍需声明。
+
+## 正例
+
+```text
+states('active', 'archived', { terminal: ['archived'] })
+```
+
+## 反例
+
+```text
+states()
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:52`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const values = all.filter((a): a is S => typeof a === 'string');
+  if (values.length === 0) throw declError('CAGE-STATE-002', 'states() 至少需要一个状态');
+  for (const v of values) {
+    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-STATE-003：状态名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+状态名称不是小写字母开头的小写下划线格式。
+
+## 修复步骤
+
+1. 状态标识使用 pending_approval 等，中文名称通过页面/graph.labels 显示。
+
+## 正例
+
+```text
+states('draft', 'pending_approval', 'done')
+```
+
+## 反例
+
+```text
+states('PendingApproval', '已完成')
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:54`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const v of values) {
+    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
+  }
+  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
+  const terminal = opts.terminal ?? [];
+```

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

@@ -0,0 +1,47 @@
+# CAGE-STATE-004：状态名称重复
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+同一 states 集合内出现相同标识。
+
+## 修复步骤
+
+1. 保留唯一标识，需要不同含义的阶段使用不同状态名。
+
+## 正例
+
+```text
+states('draft', 'approved')
+```
+
+## 反例
+
+```text
+states('draft', 'draft')
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/states.ts:56`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  }
+  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
+  const terminal = opts.terminal ?? [];
+  for (const t of [...terminal, ...(opts.initial ? [opts.initial] : [])]) {
+    if (!values.includes(t)) throw declError('CAGE-STATE-001', `状态 ${t} 未在 states 中声明`);
+```

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

@@ -0,0 +1,49 @@
+# CAGE-STATE-005：状态声明位置冲突
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+状态集放在 fields 非 status 键，或同时通过 aggregate.states 与 fields.status 定义。
+
+## 修复步骤
+
+1. 只选择一种位置：推荐 aggregate.states，fields 中不再重复。
+
+## 正例
+
+```text
+fields: { amount: money() }, states: POStatus
+```
+
+## 反例
+
+```text
+fields: { stage: POStatus }，或 states 与 fields.status 同时提供
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:169`
+- `packages/kernel/src/primitives/aggregate.ts:170`
+- `packages/kernel/src/primitives/states.ts:62`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (isStates(v)) {
+      if (k !== 'status') throw declError('CAGE-STATE-005', `状态集只能放在 status 字段上（发现 ${name}.${k}）`);
+      if (st) throw declError('CAGE-STATE-005', `${name} 同时在 states 和 fields.status 里声明了状态`);
+      st = v;
+      continue;
+```

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

@@ -0,0 +1,48 @@
+# CAGE-STATE-010：状态不可达
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+图规则从创建/初始状态沿声明的迁移无法到达某状态。
+
+## 修复步骤
+
+1. 补真实进入路径或移除无用状态，确保命令从入口导出；不要用不可调用的假命令连线。
+
+## 正例
+
+```text
+draft 经 submit 到 pending_approval，再经 approve 到 approved
+```
+
+## 反例
+
+```text
+states 包含 received，却没有任何命令迁移到它
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:123`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
+```

package/templates/app/docs/errors/CAGE-STATE-011.md

@@ -0,0 +1,48 @@
+# CAGE-STATE-011：非终态没有后续操作
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+自定义非终态在图中没有出边，单据可能永久停住。
+
+## 修复步骤
+
+1. 若业务结束则列入 terminal；否则补真实可执行的后续命令。默认生命周期有框架特别处理，不能据此忽略自定义状态。
+
+## 正例
+
+```text
+states('draft', 'done', { terminal: ['done'] })，draft 有提交路径
+```
+
+## 反例
+
+```text
+声明 pending_approval 非终态，却没有批准/驳回/取消
+```
+
+## 修复后验证
+
+重跑 cage check、gen，审查状态图和相关状态迁移用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:132`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
+```