@yss123/cage-cli 0.0.0-stage → 0.1.0

package/managed/errors/CAGE-NAME-002.md

@@ -0,0 +1,32 @@
+# CAGE-NAME-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/aggregate.ts:87](../../packages/kernel/src/primitives/aggregate.ts)
+
+```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;
+
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```

package/managed/errors/CAGE-NAME-003.md

@@ -0,0 +1,32 @@
+# CAGE-NAME-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/event.ts:19](../../packages/kernel/src/primitives/event.ts)
+
+```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} 必须是大驼峰`);
+  return Object.freeze({
+    [EVENT]: true as const,
+    name,
+    fields: Object.freeze({ ...fields }),
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```

package/managed/errors/CAGE-NAME-004.md

@@ -0,0 +1,32 @@
+# CAGE-NAME-004
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/command.ts:145](../../packages/kernel/src/primitives/command.ts)
+
+```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,
+    agg,
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```

package/managed/errors/CAGE-NAME-005.md

@@ -0,0 +1,32 @@
+# CAGE-NAME-005
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:88](../../packages/kernel/src/primitives/flow.ts)
+
+```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.* 安全视图`);
+  }
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```

package/managed/errors/CAGE-NAME-006.md

@@ -0,0 +1,32 @@
+# CAGE-NAME-006
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:189](../../packages/kernel/src/primitives/flow.ts)
+
+```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,
+    name,
+```
+
+## 怎么修
+
+聚合、事件使用大驼峰；命令、任务和查询使用小驼峰，且同类名称唯一。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', definition);
+```
+
+## 反例
+
+```text
+aggregate('purchase-order', definition);
+```

package/managed/errors/CAGE-ORG-001.md

@@ -0,0 +1,32 @@
+# CAGE-ORG-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:211](../../packages/cli/src/rules.ts)
+
+```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')
+    ? []
+```
+
+## 怎么修
+
+从 domain 入口导出框架组织模型。
+
+## 正例
+
+```text
+export * from '@yss123/cage-admin/domain';
+```
+
+## 反例
+
+```text
+// domain 入口只导出业务聚合，遗漏组织模型
+```

package/managed/errors/CAGE-PAIR-002.md

@@ -0,0 +1,33 @@
+# CAGE-PAIR-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:43](../../packages/cli/src/rules.ts)
+
+```ts
+
+/** CAGE-PAIR-002：进入某状态时获得了资源，从该状态出发的每一条迁移都必须释放它，或进入一个同样持有它的状态 */
+export function checkPairing(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+  const held = statesHoldingResources(g);
+```
+
+## 怎么修
+
+离开持有资源的状态时，发出事件并声明释放该资源的反应；检查每一条离开路径。
+
+## 正例
+
+```text
+reaction(OrderCancelled, { command: releaseLock, releases: 'inventory.lock', map: e => ({ id: e.orderId }) });
+```
+
+## 反例
+
+```text
+// approved 持有 inventory.lock，取消却没有 releases 反应
+command(PurchaseOrder, { from: 'approved', to: 'cancelled', handler: o => o });
+```

package/managed/errors/CAGE-QUERY-001.md

@@ -0,0 +1,32 @@
+# CAGE-QUERY-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:89](../../packages/kernel/src/primitives/flow.ts)
+
+```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.* 安全视图`);
+  }
+  return Object.freeze({
+```
+
+## 怎么修
+
+SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
+
+## 正例
+
+```text
+reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+sql: 'select * from core.purchase_order'
+```

package/managed/errors/CAGE-QUERY-002.md

@@ -0,0 +1,32 @@
+# CAGE-QUERY-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:91](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+  }
+  return Object.freeze({
+    [QUERY]: true as const,
+    name,
+```
+
+## 怎么修
+
+SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
+
+## 正例
+
+```text
+reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+sql: 'select * from core.purchase_order'
+```

package/managed/errors/CAGE-QUERY-003.md

@@ -0,0 +1,32 @@
+# CAGE-QUERY-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/cli/src/rules.ts:168](../../packages/cli/src/rules.ts)
+
+```ts
+
+/** CAGE-QUERY-003：手写 SQL 只能引用 reads 里聚合的安全视图 */
+export function checkQueries(g: Ontology): Finding[] {
+  const { get } = index(g);
+  const findings: Finding[] = [];
+  for (const q of g.nodes.filter((n) => n.kind === 'query')) {
+```
+
+## 怎么修
+
+SQL 引用 reads 对应的 safe 视图，用命名参数绑定输入。
+
+## 正例
+
+```text
+reads: [PurchaseOrder], sql: 'select amount from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+sql: 'select * from core.purchase_order'
+```

package/managed/errors/CAGE-REACT-001.md

@@ -0,0 +1,32 @@
+# CAGE-REACT-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/flow.ts:46](../../packages/kernel/src/primitives/flow.ts)
+
+```ts
+  if (def.target && def.target !== def.command.agg) {
+    throw declError('CAGE-REACT-001', `反应的 target 与 command 所属聚合不一致`);
+  }
+  return Object.freeze({
+    [REACTION]: true as const,
+    event: ev,
+```
+
+## 怎么修
+
+反应的目标聚合必须与 command 一致，目标命令需从统一入口导出。
+
+## 正例
+
+```text
+reaction(Approved, { command: acquireLock, map: e => ({ id: e.orderId }) })
+```
+
+## 反例
+
+```text
+reaction(Approved, { target: Order, command: acquireLock, map })
+```

package/managed/errors/CAGE-REACT-002.md

@@ -0,0 +1,32 @@
+# CAGE-REACT-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/kernel.ts:193](../../packages/kernel/src/kernel.ts)
+
+```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');
+
+```
+
+## 怎么修
+
+反应的目标聚合必须与 command 一致，目标命令需从统一入口导出。
+
+## 正例
+
+```text
+reaction(Approved, { command: acquireLock, map: e => ({ id: e.orderId }) })
+```
+
+## 反例
+
+```text
+reaction(Approved, { target: Order, command: acquireLock, map })
+```

package/managed/errors/CAGE-READS-001.md

@@ -0,0 +1,32 @@
+# CAGE-READS-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/pipeline/load.ts:83](../../packages/kernel/src/pipeline/load.ts)
+
+```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];
+    },
+  });
+```
+
+## 怎么修
+
+在 reads 中声明所有读依赖，并确认目标聚合也从入口导出。
+
+## 正例
+
+```text
+reads: { stock: Inventory }
+```
+
+## 反例
+
+```text
+reads: {} // handler 却读取 deps.stock
+```

package/managed/errors/CAGE-REG-001.md

@@ -0,0 +1,32 @@
+# CAGE-REG-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/kernel.ts:109](../../packages/kernel/src/kernel.ts)
+
+```ts
+    if (!rc) {
+      throw new Error(`[CAGE-REG-001] 找不到命令 ${typeof ref === 'string' ? ref : ref.agg.name + '.?'}，它是否从 domain 导出了？`);
+    }
+    return rc;
+  }
+
+```
+
+## 怎么修
+
+检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
+
+## 正例
+
+```text
+export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+// 命令引用了没有从入口导出的聚合
+```

package/managed/errors/CAGE-REG-002.md

@@ -0,0 +1,32 @@
+# CAGE-REG-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/registry.ts:86](../../packages/kernel/src/registry.ts)
+
+```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;
+        case 'COMMAND': {
+```
+
+## 怎么修
+
+检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
+
+## 正例
+
+```text
+export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+// 命令引用了没有从入口导出的聚合
+```

package/managed/errors/CAGE-REG-003.md

@@ -0,0 +1,32 @@
+# CAGE-REG-003
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/registry.ts:133](../../packages/kernel/src/registry.ts)
+
+```ts
+    if (!aggSet.has(c.cmd.agg)) throw declError('CAGE-REG-001', `命令 ${c.capability} 所属的聚合 ${c.cmd.agg.name} 没有从 domain 导出`);
+    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} 引用的聚合没有导出`);
+    }
+```
+
+## 怎么修
+
+检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
+
+## 正例
+
+```text
+export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+// 命令引用了没有从入口导出的聚合
+```

package/managed/errors/CAGE-ROUTE-001.md

@@ -0,0 +1,32 @@
+# CAGE-ROUTE-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/lint/src/rules/no-manual-routes.ts:11](../../packages/lint/src/rules/no-manual-routes.ts)
+
+```ts
+    docs: { description: '禁止在业务项目里手写 HTTP 路由' },
+    messages: { route: '[CAGE-ROUTE-001] 不要手写路由 {{call}}：在 domain 里声明命令或查询，路由由框架生成' },
+    schema: [],
+  },
+  create(context) {
+    return {
+```
+
+## 怎么修
+
+在 domain 声明 command/query，让框架生成 HTTP 路由。
+
+## 正例
+
+```text
+export const submit = command(Order, definition);
+```
+
+## 反例
+
+```text
+app.post('/api/order/submit', handler);
+```

package/managed/errors/CAGE-SCOPE-001.md

@@ -0,0 +1,32 @@
+# CAGE-SCOPE-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/scope/index.ts:66](../../packages/kernel/src/scope/index.ts)
+
+```ts
+    default:
+      throw new Error('[CAGE-SCOPE-001] 未知的范围组合子');
+  }
+}
+
+/** 多个授权取并集：用 OR 连接；外层始终加租户条件。 */
+```
+
+## 怎么修
+
+选择内置范围组合子，引用聚合中真实存在的部门/创建人字段。
+
+## 正例
+
+```text
+scope: scope.deptSubtree('deptId')
+```
+
+## 反例
+
+```text
+scope: scope.deptSubtree('missingField')
+```

package/managed/errors/CAGE-SCOPE-002.md

@@ -0,0 +1,32 @@
+# CAGE-SCOPE-002
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/kernel/src/primitives/aggregate.ts:96](../../packages/kernel/src/primitives/aggregate.ts)
+
+```ts
+  for (const f of [sc.deptField, ownerField]) {
+    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+  }
+  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
+
+  return Object.freeze({
+```
+
+## 怎么修
+
+选择内置范围组合子，引用聚合中真实存在的部门/创建人字段。
+
+## 正例
+
+```text
+scope: scope.deptSubtree('deptId')
+```
+
+## 反例
+
+```text
+scope: scope.deptSubtree('missingField')
+```

package/managed/errors/CAGE-SECRET-001.md

@@ -0,0 +1,32 @@
+# CAGE-SECRET-001
+
+## 什么时候出现
+
+命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
+
+来源：[packages/connectors/src/runtime.ts:22](../../packages/connectors/src/runtime.ts)
+
+```ts
+    const v = process.env[name];
+    if (!v) throw new Error(`[CAGE-SECRET-001] 缺少密钥 ${name}（由密钥管理服务或环境变量注入）`);
+    return v;
+  },
+};
+
+```
+
+## 怎么修
+
+配置中只写密钥名；密钥值通过运行环境注入，移除源码中的字面量。
+
+## 正例
+
+```text
+secret: 'ERP_API_TOKEN'
+```
+
+## 反例
+
+```text
+secret: 'a-real-token-in-source'
+```