@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,49 @@
+# CAGE-ORG-001：业务入口遗漏组织模型
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：图规则 / 测试环境。
+
+应用 domain 没有完整导出 User、Dept、Role。
+
+## 修复步骤
+
+1. 在统一入口保留框架组织模型导出；新业务引用组织模型，不复制第二套用户/角色实现。
+
+## 正例
+
+```text
+export * from '@yss123/cage-admin/domain';
+```
+
+## 反例
+
+```text
+替换采购业务时把组织模型导出也删除
+```
+
+## 修复后验证
+
+重跑 cage check/analyze，确认 User、Dept、Role 均已注册。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:211`
+- `packages/cli/src/rules.ts:218`
+- `packages/testkit/src/env.ts:107`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-ORG-001：domain 必须包含框架自带的组织模型 */
+export function checkOrg(g: Ontology): Finding[] {
+  const has = (id: string) => g.nodes.some((n) => n.kind === 'aggregate' && n.id === id);
+  return has('User') && has('Dept') && has('Role')
+```

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

@@ -0,0 +1,50 @@
+# CAGE-PAIR-002：离开持有资源状态却没有释放
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：图规则。
+
+图规则沿进入状态的 acquires 反应推断资源持有，发现离开该状态的迁移没有 releases 路径，也未进入同样持有的状态。
+
+## 修复步骤
+
+1. 沿报错命令 → emits → reaction → 释放命令检查，新增所需事件与真正释放行为。
+2. 释放反应标注与获取一致的资源名；检查取消、收货、撤回等每条离开路径及 map 的条件分支。
+3. 标签只参与静态分析，不会自动释放资源；重要路径需用业务数据验证。不要删除 acquires 或添加永不执行的 map 来骗过检查。
+
+## 正例
+
+```text
+reaction(OrderCancelled, { command: releaseLock, releases: 'inventory.lock', map: e => e.previousStatus === 'approved' ? { id: e.orderId } : null })
+```
+
+## 反例
+
+```text
+新增 approved → draft 的撤回命令，却没有事件及释放反应
+```
+
+## 修复后验证
+
+重跑 cage check，并用业务用例验证每条关键离开路径确实释放资源。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:43`
+- `packages/cli/src/rules.ts:56`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-PAIR-002：进入某状态时获得了资源，从该状态出发的每一条迁移都必须释放它，或进入一个同样持有它的状态 */
+export function checkPairing(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+```

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

@@ -0,0 +1,47 @@
+# CAGE-QUERY-001：查询必须选择一种实现
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+query 同时提供或同时未提供 sql/build。
+
+## 修复步骤
+
+1. 在参数化手写 SQL 与查询构建器之间选择一种，显式声明 reads 和 input。
+
+## 正例
+
+```text
+query('poByStatus', { reads: [PurchaseOrder], input, sql })
+```
+
+## 反例
+
+```text
+query('poByStatus', { reads: [PurchaseOrder], sql, build })
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:89`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-005', `查询名 ${name} 必须是小驼峰`);
+  if (!def.sql === !def.build) throw declError('CAGE-QUERY-001', `查询 ${name} 必须二选一：sql 或 build`);
+  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-QUERY-002：自定义查询直接访问基表
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+query.sql 引用了 core.* 或 sys.*。
+
+## 修复步骤
+
+1. 改成对应 safe 视图，让只读账号落实范围与掩码。需要系统管理数据时使用框架已有系统接口，不绕过安全层。
+
+## 正例
+
+```text
+'select amount from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+'select * from core.purchase_order'
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:91`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+  }
+  return Object.freeze({
+    [QUERY]: true as const,
+```

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

@@ -0,0 +1,49 @@
+# CAGE-QUERY-003：查询读取范围与声明不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+SQL 引用了 reads 未声明聚合的 safe 视图，或引用非 safe 的限定表。
+
+## 修复步骤
+
+1. 在 reads 列出每个实际读取的聚合，并只查询相应安全视图；join 同样要声明。
+
+## 正例
+
+```text
+reads: [PurchaseOrder]；SQL from safe.purchase_order
+```
+
+## 反例
+
+```text
+reads: []；SQL from safe.purchase_order
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:168`
+- `packages/cli/src/rules.ts:183`
+- `packages/cli/src/rules.ts:201`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-QUERY-003：手写 SQL 只能引用 reads 里聚合的安全视图 */
+export function checkQueries(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REACT-001：反应目标与命令聚合不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 写流水线。
+
+reaction 显式 target 与 command.agg 不同。
+
+## 修复步骤
+
+1. 省略 target 由框架从命令推导；确需写出时必须是命令所属聚合。
+
+## 正例
+
+```text
+reaction(OrderApproved, { command: acquireLock, map })
+```
+
+## 反例
+
+```text
+target: PurchaseOrder，command 却属于 InventoryLock
+```
+
+## 修复后验证
+
+重跑 cage check；同事务链验证共同提交/回滚，异步链检查 worker 和死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:46`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.target && def.target !== def.command.agg) {
+    throw declError('CAGE-REACT-001', `反应的 target 与 command 所属聚合不一致`);
+  }
+  return Object.freeze({
+    [REACTION]: true as const,
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REACT-002：同事务反应链嵌套过深
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 写流水线。
+
+同事务执行深度超出内核上限，常见原因是命令与事件互相触发形成循环。
+
+## 修复步骤
+
+1. 沿事件/反应图定位循环，减少同事务级联；仅在业务允许最终一致时改成 outbox，并避免异步循环。
+
+## 正例
+
+```text
+单向批准 → 建锁，释放不会再次触发批准
+```
+
+## 反例
+
+```text
+批准触发建锁，建锁又触发批准，或随意调高深度上限
+```
+
+## 修复后验证
+
+重跑 cage check；同事务链验证共同提交/回滚，异步链检查 worker 和死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:197`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const agg = cmd.agg;
+    if (depth > this.maxDepth) throw new Error(`[CAGE-REACT-002] 同事务反应嵌套超过 ${this.maxDepth} 层`);
+
+    // 第 1 关：认证
+    if (!ctx.actor || (ctx.actor.kind === 'anonymous' && !cmd.public)) throw cageError('UNAUTHENTICATED');
+```

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

@@ -0,0 +1,47 @@
+# CAGE-READS-001：handler 使用了未声明读依赖
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：handler 执行。
+
+handler 访问 deps 中不存在的别名。
+
+## 修复步骤
+
+1. 在命令 reads 添加真实聚合与正确别名，核对入口导出。不要通过 any 或自建仓储绕过依赖声明。
+
+## 正例
+
+```text
+reads: { stock: Inventory }；使用 deps.stock.findOne({ sku })
+```
+
+## 反例
+
+```text
+reads: {}；使用 deps.stock
+```
+
+## 修复后验证
+
+检查本体图 reads 边并运行该命令的业务用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/pipeline/load.ts:86`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (typeof prop === 'string' && !(prop in target) && prop !== 'then' && prop !== 'toJSON') {
+        throw new Error(`[CAGE-READS-001] handler 使用了未声明的读依赖 ${prop}（详见 docs/errors/CAGE-READS-001.md）`);
+      }
+      return (target as any)[prop];
+    },
+```

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

@@ -0,0 +1,53 @@
+# CAGE-REG-001：注册表缺少被引用声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+命令、读依赖、反应、审批或任务引用了没有从 domain 入口导出的聚合/命令，或执行时找不到命令。
+
+## 修复步骤
+
+1. 从统一入口导出依赖双方，确认引用是同一个声明对象且名字正确；修复后重新 check/gen。
+
+## 正例
+
+```text
+export * from './inventory.js'; export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+只导出反应，却没有导出它的目标命令
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:113`
+- `packages/kernel/src/registry.ts:153`
+- `packages/kernel/src/registry.ts:159`
+- `packages/kernel/src/registry.ts:164`
+- `packages/kernel/src/registry.ts:168`
+- `packages/kernel/src/registry.ts:172`
+- `packages/kernel/src/registry.ts:190`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!rc) {
+      throw new Error(`[CAGE-REG-001] 找不到命令 ${typeof ref === 'string' ? ref : ref.agg.name + '.?'}，它是否从 domain 导出了？`);
+    }
+    return rc;
+  }
+```

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

@@ -0,0 +1,48 @@
+# CAGE-REG-002：聚合或查询注册重名
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同类聚合/查询拥有相同逻辑名称。
+
+## 修复步骤
+
+1. 保留一个规范声明，或为真正不同对象选不同逻辑名；不能通过对象复制创建同名注册。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', ...)、aggregate('Inventory', ...)
+```
+
+## 反例
+
+```text
+不同文件都 aggregate('Order', ...) 并导出
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:88`
+- `packages/kernel/src/registry.ts:176`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          if (aggregates.some((a) => a.name === (v as AnyAggregate).name)) {
+            throw declError('CAGE-REG-002', `聚合名重复：${(v as AnyAggregate).name}`);
+          }
+          aggregates.push(v as AnyAggregate);
+          break;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REG-003：命令能力点重复
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同一聚合的多个命令解析成同一个 Aggregate.command 能力点。
+
+## 修复步骤
+
+1. 为不同操作指定不同 name，跨文件导出名也保持唯一；相同操作复用同一命令对象。
+
+## 正例
+
+```text
+name: 'submit' 与 name: 'cancel'
+```
+
+## 反例
+
+```text
+同一聚合两个命令都 name: 'update'
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:156`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      throw declError('CAGE-REL-001', `${c.cmd.agg.name}.related 是生成客户端的关联读取入口；请为业务命令使用其他 name`);
+    if (caps.has(c.capability)) throw declError('CAGE-REG-003', `能力点重复：${c.capability}，可用 command({ name }) 区分`);
+    caps.add(c.capability);
+    for (const [alias, a] of Object.entries(c.cmd.reads)) {
+      if (!aggSet.has(a)) throw declError('CAGE-REG-001', `命令 ${c.capability} 的 reads.${alias} 引用的聚合没有导出`);
+```

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

@@ -0,0 +1,64 @@
+# CAGE-REL-001：关系字段声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 生成。
+
+关系目标未导出、hasMany.mappedBy 不是指回当前聚合的公开 ref、关系表重名/过长，或集合关系用于不支持的位置与修饰。带关系聚合的用户命令名 related 也会占用生成客户端入口。
+
+## 修复步骤
+
+1. 把 ref/hasMany/manyToMany 的目标从 domain 入口导出；循环引用使用聚合名字符串。
+2. hasMany 的 mappedBy 写目标上的真实 ref 字段名，该字段不能 hidden 或 sensitive；修改归属调用子对象命令。
+3. 集合关系只写在聚合 fields 中，不放进 list、事件载荷或 scope 字段。不要对关系链式调用 optional/unique/hidden/sensitive；没有关联用空集合表示。
+4. 缩短或调整发生冲突的字段/表名；业务命令避开 related，运行 cage check/gen 后审查迁移。
+
+## 正例
+
+```text
+Note.fields.members = manyToMany('User', { description: '协作成员' }); // User 已导出
+Notebook.fields.notes = hasMany('Note', { mappedBy: 'notebookId' }); // Note.notebookId = ref('Notebook')
+```
+
+## 反例
+
+```text
+hasMany('Note', { mappedBy: 'title' }); // title 不是反向 ref
+list({ members: manyToMany('User') }); // JSON 明细中不能声明关系
+```
+
+## 修复后验证
+
+重跑 cage check/gen；迁移后用真实用户验证关系命令、关联分页读取和双侧范围。不要手写纯中间表聚合。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:97`
+- `packages/kernel/src/primitives/event.ts:20`
+- `packages/kernel/src/primitives/fields.ts:94`
+- `packages/kernel/src/primitives/fields.ts:99`
+- `packages/kernel/src/primitives/fields.ts:105`
+- `packages/kernel/src/primitives/fields.ts:110`
+- `packages/kernel/src/primitives/fields.ts:167`
+- `packages/kernel/src/primitives/fields.ts:174`
+- `packages/kernel/src/primitives/fields.ts:193`
+- `packages/kernel/src/registry.ts:137`
+- `packages/kernel/src/registry.ts:141`
+- `packages/kernel/src/registry.ts:147`
+- `packages/kernel/src/registry.ts:155`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    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}`);
+  }
+  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-ROUTE-001：业务项目手写 HTTP 路由
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / verify。
+
+业务代码调用 app.get/post 等手动注册接口，绕过声明生成路径。
+
+## 修复步骤
+
+1. 将普通业务写接口声明为 command、读接口声明为 query；API 入口只装配框架。协议扩展另按框架边界评估。
+
+## 正例
+
+```text
+领域 command → gen → 自动路由和前端契约
+```
+
+## 反例
+
+```text
+app.post('/api/order/submit', handler)
+```
+
+## 修复后验证
+
+重新生成，检查 generated/routes.json 和前端契约，再验证自动接口。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-manual-routes.ts:11`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    docs: { description: '禁止在业务项目里手写 HTTP 路由' },
+    messages: { route: '[CAGE-ROUTE-001] 不要手写路由 {{call}}：在 domain 里声明命令或查询，路由由框架生成' },
+    schema: [],
+  },
+  create(context) {
+```