@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/blank/docs/errors/CAGE-MIG-004.md

@@ -0,0 +1,5 @@
+# CAGE-MIG-004
+
+此错误码属于 npm 0.1.0 的旧数据库初始化流程，当前源码已移除该流程，保留本页供历史错误查询。
+
+当前项目首次在根目录 `.env` 填写 `CAGE_ADMIN_DATABASE_URL`，运行 `pnpm exec cage init` 自动准备账号与连接，再执行 `pnpm migrate` 更新表结构。已有集群角色需复用原凭证，不能覆盖其他项目正在使用的密码。

package/templates/blank/docs/errors/CAGE-MIG-005.md

@@ -0,0 +1,47 @@
+# CAGE-MIG-005：已执行迁移内容被修改
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：migrate。
+
+迁移文件校验和与 sys.schema_migrations 中记录不符。
+
+## 修复步骤
+
+1. 恢复执行时的原文件；结构更新新增迁移。换行引起差异时恢复原始字节并遵守仓库 LF 约定，不改数据库 checksum。
+
+## 正例
+
+```text
+保留 0001_init.sql，新增 0002_add_field.sql
+```
+
+## 反例
+
+```text
+重写 0001，或手工修改迁移历史 checksum
+```
+
+## 修复后验证
+
+在合适数据库上重新 migrate，确认迁移历史及 safe 读写权限，已执行文件保持原样。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/db/migrate.ts:71`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (done.has(migration.name) && done.get(migration.name) !== checksum(migration.sql)) {
+        throw new Error(`[CAGE-MIG-005] 已执行迁移 ${migration.name} 的内容被修改，请恢复原文件并新增迁移`);
+      }
+    }
+    for (const m of all) {
+```

package/templates/blank/docs/errors/CAGE-NAME-001.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-001：聚合名必须大驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+aggregate 名称不是大写字母开头的字母数字标识。
+
+## 修复步骤
+
+1. 聚合使用稳定英文大驼峰，中文显示名写 description/graph.labels。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition)
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:72`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+    throw declError('CAGE-NAME-001', `聚合名 ${name} 必须是大驼峰`);
+  }
+  let st: StatesDef<any> | undefined = def.states;
+  const fields: Record<string, AnyField> = {};
+```

package/templates/blank/docs/errors/CAGE-NAME-002.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-002：字段名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+聚合字段名不是小写字母开头的字母数字标识。
+
+## 修复步骤
+
+1. 业务字段使用小驼峰；数据库 snake_case 由框架转换，中文列名写在页面或图谱显示配置。
+
+## 正例
+
+```text
+fields: { supplierPhone: text() }
+```
+
+## 反例
+
+```text
+fields: { supplier_phone: text() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:87`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    }
+    if (!/^[a-z][A-Za-z0-9]*$/.test(k)) throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
+    fields[k] = v;
+  }
+  const states = st ?? DEFAULT_STATES;
+```

package/templates/blank/docs/errors/CAGE-NAME-003.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-003：事件名必须大驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+event 名称格式不满足大驼峰。
+
+## 修复步骤
+
+1. 使用表示已发生事实的稳定大驼峰事件名，避免中文或短横线标识。
+
+## 正例
+
+```text
+event('OrderSubmitted', fields)
+```
+
+## 反例
+
+```text
+event('order-submitted', fields)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/event.ts:19`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function event<const N extends string, F extends Fields>(name: N, fields: F, opts?: { description?: string }): Event<N, F> {
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-003', `事件名 ${name} 必须是大驼峰`);
+  if (Object.values(fields).some(isRelation)) throw declError('CAGE-REL-001', '事件载荷不声明持久化关系；传递 ID 数组请使用 list(id())');
+  return Object.freeze({
+    [EVENT]: true as const,
+```

package/templates/blank/docs/errors/CAGE-NAME-004.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-004：命令名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+command 显式 name 不是小驼峰。
+
+## 修复步骤
+
+1. name 使用小驼峰；中文按钮与图谱展示名另配，导出变量可用唯一业务前缀。
+
+## 正例
+
+```text
+name: 'submit'
+```
+
+## 反例
+
+```text
+name: '提交审批'
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:145`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
+    throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
+  }
+  return Object.freeze({
+    [COMMAND]: true as const,
+```

package/templates/blank/docs/errors/CAGE-NAME-005.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-005：查询名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+query 名称格式不满足小驼峰。
+
+## 修复步骤
+
+1. 使用小驼峰查询名，保持生成契约与路由的稳定标识。
+
+## 正例
+
+```text
+query('poByStatus', definition)
+```
+
+## 反例
+
+```text
+query('PO_BY_STATUS', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:88`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Query<I> {
+  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/blank/docs/errors/CAGE-NAME-006.md

@@ -0,0 +1,47 @@
+# CAGE-NAME-006：任务名必须小驼峰
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+job 名称格式不满足小驼峰。
+
+## 修复步骤
+
+1. 任务使用稳定的小驼峰名，中文意图放 description。
+
+## 正例
+
+```text
+job('expireStaleOrders', definition)
+```
+
+## 反例
+
+```text
+job('Expire-Stale-Orders', definition)
+```
+
+## 修复后验证
+
+重跑 cage check/gen；改动线上标识时还要审查能力、路由、迁移及旧消费者影响。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:189`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Job {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-006', `任务名 ${name} 必须是小驼峰`);
+  if (def.cron.trim().split(/\s+/).length < 5) throw declError('CAGE-JOB-001', `任务 ${name} 的 cron 表达式不合法`);
+  return Object.freeze({
+    [JOB]: true as const,
+```

package/templates/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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');
+```