@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,50 @@
+# CAGE-EVENT-002：事件变更不向后兼容
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：写事务 / 基线比较。
+
+与基线相比，删除旧载荷字段、改变字段 kind，或新增必填字段。
+
+## 修复步骤
+
+1. 保留旧字段和类型，新字段 optional；不兼容含义新建事件，并考虑旧 outbox 消息和消费者升级顺序。
+
+## 正例
+
+```text
+note: text().optional() // 新增字段
+```
+
+## 反例
+
+```text
+给线上已有事件新增必填 note，旧消息没有该值
+```
+
+## 修复后验证
+
+运行相关命令与消费者测试；兼容性使用修改前基线检查，考虑尚未消费的旧事件。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:225`
+- `packages/cli/src/rules.ts:237`
+- `packages/cli/src/rules.ts:244`
+- `packages/cli/src/rules.ts:254`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-EVENT-002：事件载荷只允许向后兼容的变更（只能新增可选字段） */
+export function checkEventCompat(base: Ontology, head: Ontology): Finding[] {
+  const findings: Finding[] = [];
+  const b = new Map(base.nodes.filter((n) => n.kind === 'event').map((n) => [n.id, n]));
+```

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

@@ -0,0 +1,47 @@
+# CAGE-FIELD-001：敏感字段种类不存在
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+sensitive 使用了 SENSITIVE_KINDS 之外的值。
+
+## 修复步骤
+
+1. 选用当前包导出的敏感种类；确需新掩码规则时评估框架扩展，不以 any 绕过声明。
+
+## 正例
+
+```text
+supplierPhone: text(32).sensitive('phone')
+```
+
+## 反例
+
+```text
+text().sensitive('自定义随意字符串')
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/fields.ts:100`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (isRelation(this)) throw declError('CAGE-REL-001', '关系字段不支持 sensitive；目标字段按目标聚合权限掩码');
+    if (!SENSITIVE_KINDS.includes(kind)) throw declError('CAGE-FIELD-001', `未知的敏感种类 ${kind}`);
+    return this.with({ sensitiveKind: kind });
+  }
+  /** 唯一约束（租户内） */
+```

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

@@ -0,0 +1,47 @@
+# CAGE-FIELD-002：引用目标为空
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+ref 收到空目标，常见原因是循环导入。
+
+## 修复步骤
+
+1. 使用 ref("聚合名") 避免循环求值，确保对应聚合从入口导出且名称正确。
+
+## 正例
+
+```text
+deptId: ref('Dept')
+```
+
+## 反例
+
+```text
+deptId: ref(undefined)
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/fields.ts:160`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const target = typeof to === 'string' ? to : to?.name;
+  if (!target) throw declError('CAGE-FIELD-002', 'ref() 的目标为空，可能是循环导入；可改为 ref("聚合名")');
+  return mk(z.string().uuid(), { kind: 'ref', sql: 'uuid', ref: target });
+}
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-FIELD-003：字段不是字段原语
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+aggregate.fields 中存在不是 field/states 描述对象的值。
+
+## 修复步骤
+
+1. 使用 text/int/money/ref/list 等公开字段工厂；Zod 用在命令输入或 json schema，不能直接代替 fields 的字段描述。
+
+## 正例
+
+```text
+fields: { amount: money() }
+```
+
+## 反例
+
+```text
+fields: { amount: z.string() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:83`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    }
+    if (!isField(v)) throw declError('CAGE-FIELD-003', `${name}.${k} 不是字段原语`);
+    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
+      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
+    }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-FIELD-004：覆盖系统保留列
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+业务 fields 定义了 id/version/status/createdAt/updatedAt/tenantId 等保留字段。
+
+## 修复步骤
+
+1. 移除重复系统字段；状态使用 aggregate.states 或唯一 fields.status 状态声明；业务另取有意义名称。
+
+## 正例
+
+```text
+fields: { externalId: text() }, states: POStatus
+```
+
+## 反例
+
+```text
+fields: { version: text() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:85`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
+      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
+    }
+    if (!/^[a-z][A-Za-z0-9]*$/.test(k)) throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
+    fields[k] = v;
+```

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

@@ -0,0 +1,48 @@
+# CAGE-GEN-001：契约等生成结果过期
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+gen --check/verify 比较发现需提交的生成文件缺失或与声明不一致。
+
+## 修复步骤
+
+1. 改源声明后运行 pnpm gen，审查并提交结果；手改生成物会被覆盖，不靠更新预期掩盖错误。
+
+## 正例
+
+```text
+修改 domain → pnpm gen → pnpm exec cage gen --check
+```
+
+## 反例
+
+```text
+直接编辑 packages/contracts/src/aggregates/purchase-order/index.ts
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:48`
+- `packages/cli/src/gen/index.ts:90`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  findings: Finding[],
+  code = 'CAGE-GEN-001',
+) {
+  const cur = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  if (cur === content) return;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-GEN-002：声明结构没有对应迁移
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+声明的期望结构与最后一个迁移内嵌的结构快照不一致。
+
+## 修复步骤
+
+1. 运行 pnpm gen 生成新迁移草稿，审查回填、非空与破坏性变更后提交；实际落库还需 pnpm migrate。
+
+## 正例
+
+```text
+新增字段 → gen → 审查新迁移 → migrate
+```
+
+## 反例
+
+```text
+修改已执行 0001_init.sql，或把 gen 当作已更新数据库
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:162`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      findings.push({
+        code: 'CAGE-GEN-002',
+        at: cfg.migrations,
+        reason: `声明的表结构与迁移不一致（${stmts.length} 处变化）`,
+        fix: '运行 cage gen 生成迁移草稿，人审后提交',
+```

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

@@ -0,0 +1,49 @@
+# CAGE-GRANT-001：授予超出自己的能力或额度
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+管理员授予自己没有的能力/更高参数，或分配含越权能力的角色。
+
+## 修复步骤
+
+1. 由具备足够能力和参数的管理员操作；降低授予范围到自身权限内，不禁用防提权约束。
+
+## 正例
+
+```text
+有 approve=100000 额度的管理员授予不超过自身的额度
+```
+
+## 反例
+
+```text
+自己没有采购审批能力，却给别人分配该能力或包含它的角色
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:21`
+- `packages/admin/src/domain/constraints.ts:24`
+- `packages/admin/src/domain/constraints.ts:51`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const mine = ctx.capabilities.get(input.capability);
+    if (!mine) return violation('[CAGE-GRANT-001] 不能授出自己没有的能力点');
+    for (const [k, v] of Object.entries(input.params ?? {})) {
+      if (typeof v === 'number' && typeof mine[k] === 'number' && v > (mine[k] as number)) {
+        return violation(`[CAGE-GRANT-001] 参数 ${k}=${v} 超过了你自己的 ${mine[k]}`);
+```

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

@@ -0,0 +1,48 @@
+# CAGE-GRANT-002：授予超出自己的数据范围
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+设置范围或分配角色时，目标范围比操作人自身范围更宽。
+
+## 修复步骤
+
+1. 核对操作人在该聚合的范围，由具有足够范围的管理员配置；部门限定还需对应范围字段。
+
+## 正例
+
+```text
+自己有 all 范围时，按业务需求授予部门范围
+```
+
+## 反例
+
+```text
+仅有本人范围的管理员给角色授予全部部门
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:37`
+- `packages/admin/src/domain/constraints.ts:55`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const want = COMBINATOR_WIDTH[input.combinator as Combinator] ?? 99;
+    return want <= ownWidth(ctx, input.aggregate) ? ok() : violation('[CAGE-GRANT-002] 不能授出比自己更宽的数据范围');
+  },
+});
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-GRANT-003：能力不在代码目录中
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：组织命令。
+
+授权请求引用了注册表没有声明的能力点。
+
+## 修复步骤
+
+1. 先在 domain 声明并导出相应命令/聚合，再查看能力目录；不要在管理页面凭空发明能力名称。
+
+## 正例
+
+```text
+PurchaseOrder.submit // 由已导出的命令形成
+```
+
+## 反例
+
+```text
+PurchaseOrder.anything // 没有对应声明
+```
+
+## 修复后验证
+
+用真实操作人验证允许与拒绝场景，检查目标角色最终能力、参数和范围。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/admin/src/domain/constraints.ts:13`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  check: (_role, _ctx, input, meta) =>
+    meta.catalog().includes(input.capability) ? ok() : violation(`[CAGE-GRANT-003] 能力点 ${input.capability} 不在能力目录里`),
+});
+
+/** 防提权：不能授出自己没有的能力点；数值参数（额度）不能超过自己的 */
+```

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

@@ -0,0 +1,48 @@
+# CAGE-IMPACT-001：影响分析没有可用基线
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：impact / 基线加载。
+
+impact 未指定基线，或 Git 基线无法加载/抽取。
+
+## 修复步骤
+
+1. 使用真实存在且能加载的提交，或修改前保存的完整 ontology.json。基线失败不能当作没有变化。
+
+## 正例
+
+```text
+pnpm exec cage impact --base-file .cage/before-change.json
+```
+
+## 反例
+
+```text
+修改后才保存旧图，或指定不存在的提交并忽略失败
+```
+
+## 修复后验证
+
+使用可靠基线重新 impact，确认报告中的变化与本次需求相符。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/baseline.ts:45`
+- `packages/cli/src/main.ts:212`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    );
+    if (code !== 0) throw new Error('[CAGE-IMPACT-001] 基线抽取失败，请修复基线声明或使用保存的 --base-file');
+    return readOntology(join(project, '.cage/ontology.json'));
+  } finally {
+    // 先断开本次建立的 junction，避免清理工作树时遍历共享依赖目录。
+```

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

@@ -0,0 +1,47 @@
+# CAGE-INIT-001：管理员 URL 没有数据库名
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+init 的管理员连接没有指定一个明确的已有数据库。
+
+## 修复步骤
+
+1. 在 URL 路径填写实际数据库名，确认该库已经存在；init 不负责创建数据库。
+
+## 正例
+
+```text
+postgresql://postgres:已编码密码@主机:端口/business_db
+```
+
+## 反例
+
+```text
+postgresql://postgres:密码@主机:端口/
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:80`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!target.pathname || target.pathname === '/') {
+    throw new Error('[CAGE-INIT-001] 管理员连接必须指定已经存在的数据库名，例如 postgresql://postgres:密码@localhost:5432/business_db');
+  }
+  const admin = new pg.Client({ connectionString: adminUrl, connectionTimeoutMillis: 5000, application_name: 'cage-init' });
+  let staged: string | undefined;
+```

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

@@ -0,0 +1,49 @@
+# CAGE-INIT-002：集群已有账号但缺少原凭证
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+PostgreSQL 集群已经存在 Cage 登录角色，而本项目没有保存可复用的三种连接。
+
+## 修复步骤
+
+1. 从已有项目或管理员安全取得对应角色的原连接，填入本项目 .env，再运行 init 验证。
+2. 角色名在集群共享；不要为新项目随机重置 cage_app/read/migrate 的密码，影响其他项目。
+3. 如需完全隔离的账号策略，先规划集群/角色隔离方案；不删除共享角色绕过检查。
+
+## 正例
+
+```text
+复用原 APP/READ/MIGRATE 凭证，指向本项目实际同一库
+```
+
+## 反例
+
+```text
+ALTER ROLE 重置共享账号密码，导致已有应用断连
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:94`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (existing.rowCount !== 4 || !hasSaved) {
+        throw new Error('[CAGE-INIT-002] PostgreSQL 集群已有 Cage 账号；请在 .env 提供已有的 APP / READ / MIGRATE 连接后重试。初始化不会重置这些账号的密码');
+      }
+      if (new URL(saved.APP).host !== target.host || new URL(saved.APP).pathname !== target.pathname) {
+        throw new Error('[CAGE-INIT-003] 已有账号连接与管理员连接必须指向同一个数据库；请检查 .env');
+```

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

@@ -0,0 +1,48 @@
+# CAGE-INIT-003：三种连接身份或目标不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+APP/READ/MIGRATE 账号不是各自 Cage 账号，或三者及管理员连接不指向同一目标数据库。
+
+## 修复步骤
+
+1. 核对 URL 的用户名、主机、端口、数据库名；各自使用正确账号，并连接同一个库，不输出密码。
+
+## 正例
+
+```text
+cage_app/cage_read/cage_migrate 均连接同一 host:port/business_db
+```
+
+## 反例
+
+```text
+app 连接 business_db，而 read/migrate 指向另一个库
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/init.ts:22`
+- `packages/cli/src/init.ts:97`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (url.username !== accounts[key] || url.host !== target.host || url.pathname !== target.pathname) {
+      throw new Error('[CAGE-INIT-003] APP / READ / MIGRATE 需使用各自的 cage 账号，指向同一个数据库；请检查 .env');
+    }
+    const client = new pg.Client({ connectionString: urls[key], connectionTimeoutMillis: 5000 });
+    try {
+```