@yss123/cage-cli 0.0.0-stage → 0.2.0

package/templates/blank/docs/errors/README.md

@@ -0,0 +1,307 @@
+# 错误码册
+
+这是本业务项目自带的离线诊断手册。先使用错误码、声明位置、reason/fix 定位；不需要克隆框架仓库。
+
+- [HTTP 运行时错误与业务码](runtime.md)：401/403/404、状态冲突、约束拒绝、DOMAIN_ERROR 等。
+- [业务排错顺序](../ai/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
+- CAGE-* 是声明、工具链或内部运行诊断；HTTP code 与业务 domainCode 是另一层，不要混为一谈。
+
+每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
+
+## 审批
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-APPR-001](CAGE-APPR-001.md) | 可路由字段不存在 |
+| [CAGE-APPR-002](CAGE-APPR-002.md) | 审批结论落到其他聚合 |
+| [CAGE-APPR-003](CAGE-APPR-003.md) | 审批结论未允许流程调用 |
+| [CAGE-APPR-004](CAGE-APPR-004.md) | 路由没有对应审批绑定 |
+| [CAGE-APPR-005](CAGE-APPR-005.md) | 流程名称格式错误 |
+| [CAGE-APPR-006](CAGE-APPR-006.md) | 流程没有步骤 |
+| [CAGE-APPR-007](CAGE-APPR-007.md) | 找不到审批人 |
+| [CAGE-APPR-010](CAGE-APPR-010.md) | 流程专用命令没有调用者 |
+
+## 登录认证
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AUTH-001](CAGE-AUTH-001.md) | OIDC 发现文档获取失败 |
+
+## 体积与逃生口预算
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-BUDGET-001](CAGE-BUDGET-001.md) | 内核超出体积预算 |
+| [CAGE-BUDGET-002](CAGE-BUDGET-002.md) | 公共原语超过词汇预算 |
+| [CAGE-BUDGET-003](CAGE-BUDGET-003.md) | 新增未经基线认可的 unsafe |
+
+## 命令
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CMD-002](CAGE-CMD-002.md) | 已有记录命令缺少 id |
+| [CAGE-CMD-003](CAGE-CMD-003.md) | 新建命令没有目标状态 |
+
+## 第三方连接器
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CONN-001](CAGE-CONN-001.md) | 连接器名称格式错误 |
+| [CAGE-CONN-002](CAGE-CONN-002.md) | 外部操作路径格式错误 |
+| [CAGE-CONN-003](CAGE-CONN-003.md) | 地址白名单包含协议或路径 |
+| [CAGE-CONN-004](CAGE-CONN-004.md) | 只读操作被用作出站写映射 |
+| [CAGE-CONN-005](CAGE-CONN-005.md) | 入站事件名称格式错误 |
+| [CAGE-CONN-006](CAGE-CONN-006.md) | 回调命令未允许 external |
+| [CAGE-CONN-007](CAGE-CONN-007.md) | 当前环境没有连接器地址 |
+| [CAGE-CONN-008](CAGE-CONN-008.md) | 外部请求发生网络错误或超时 |
+| [CAGE-CONN-009](CAGE-CONN-009.md) | 外部服务返回非成功状态 |
+| [CAGE-CONN-010](CAGE-CONN-010.md) | 外部响应不符合 schema |
+| [CAGE-CONN-011](CAGE-CONN-011.md) | 出站永久失败进入死信 |
+| [CAGE-CONN-012](CAGE-CONN-012.md) | 外部专用命令没有声明调用者 |
+
+## 创建应用
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CREATE-001](CAGE-CREATE-001.md) | 项目创建参数或模板资源有误 |
+
+## 可抽取声明
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DECL-001](CAGE-DECL-001.md) | 声明不在可抽取的顶层常量 |
+| [CAGE-DECL-002](CAGE-DECL-002.md) | 声明没有从 domain 入口导出 |
+| [CAGE-DECL-003](CAGE-DECL-003.md) | 声明不是 export const |
+| [CAGE-DECL-004](CAGE-DECL-004.md) | 跨文件导出名冲突 |
+
+## 依赖边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DEP-001](CAGE-DEP-001.md) | 领域声明直接依赖 IO |
+| [CAGE-DEP-002](CAGE-DEP-002.md) | 适配器绕过命令写库 |
+| [CAGE-DEP-003](CAGE-DEP-003.md) | 前端依赖服务端实现 |
+| [CAGE-DEP-004](CAGE-DEP-004.md) | 声明或 handler 直接发请求/动态导入 |
+| [CAGE-DEP-005](CAGE-DEP-005.md) | domain 反向依赖生成物 |
+
+## 工程目录与模块依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STRUCT-001](CAGE-STRUCT-001.md) | 业务源码目录不符合模块约定 |
+| [CAGE-STRUCT-002](CAGE-STRUCT-002.md) | 源码依赖越过模块边界 |
+
+## 死信操作
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DLQ-001](CAGE-DLQ-001.md) | 死信不存在或已经处理 |
+
+## 运行配置
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ENV-001](CAGE-ENV-001.md) | 缺少数据库连接配置 |
+
+## 事件载荷与兼容性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-EVENT-001](CAGE-EVENT-001.md) | 事件载荷不满足声明 |
+| [CAGE-EVENT-002](CAGE-EVENT-002.md) | 事件变更不向后兼容 |
+
+## 字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-FIELD-001](CAGE-FIELD-001.md) | 敏感字段种类不存在 |
+| [CAGE-FIELD-002](CAGE-FIELD-002.md) | 引用目标为空 |
+| [CAGE-FIELD-003](CAGE-FIELD-003.md) | 字段不是字段原语 |
+| [CAGE-FIELD-004](CAGE-FIELD-004.md) | 覆盖系统保留列 |
+
+## 关系字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REL-001](CAGE-REL-001.md) | 关系字段声明无效 |
+
+## 生成一致性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GEN-001](CAGE-GEN-001.md) | 契约等生成结果过期 |
+| [CAGE-GEN-002](CAGE-GEN-002.md) | 声明结构没有对应迁移 |
+
+## 角色授权与防提权
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或额度 |
+| [CAGE-GRANT-002](CAGE-GRANT-002.md) | 授予超出自己的数据范围 |
+| [CAGE-GRANT-003](CAGE-GRANT-003.md) | 能力不在代码目录中 |
+
+## 影响分析
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-IMPACT-001](CAGE-IMPACT-001.md) | 影响分析没有可用基线 |
+
+## 账号初始化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-INIT-001](CAGE-INIT-001.md) | 管理员 URL 没有数据库名 |
+| [CAGE-INIT-002](CAGE-INIT-002.md) | 集群已有账号但缺少原凭证 |
+| [CAGE-INIT-003](CAGE-INIT-003.md) | 三种连接身份或目标不一致 |
+| [CAGE-INIT-004](CAGE-INIT-004.md) | 账号已创建但 .env 替换失败 |
+
+## 定时任务
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-JOB-001](CAGE-JOB-001.md) | 定时表达式不合法 |
+| [CAGE-JOB-002](CAGE-JOB-002.md) | 任务调用了未声明的命令 |
+| [CAGE-JOB-003](CAGE-JOB-003.md) | 任务读取了未声明的聚合 |
+
+## 通用 lint
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-LINT-001](CAGE-LINT-001.md) | lint 语法或规则错误 |
+
+## 结构迁移与安全层
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-MIG-001](CAGE-MIG-001.md) | 迁移事务执行失败 |
+| [CAGE-MIG-002](CAGE-MIG-002.md) | 安全层重建失败 |
+| [CAGE-MIG-005](CAGE-MIG-005.md) | 已执行迁移内容被修改 |
+
+## 名称
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-NAME-001](CAGE-NAME-001.md) | 聚合名必须大驼峰 |
+| [CAGE-NAME-002](CAGE-NAME-002.md) | 字段名必须小驼峰 |
+| [CAGE-NAME-003](CAGE-NAME-003.md) | 事件名必须大驼峰 |
+| [CAGE-NAME-004](CAGE-NAME-004.md) | 命令名必须小驼峰 |
+| [CAGE-NAME-005](CAGE-NAME-005.md) | 查询名必须小驼峰 |
+| [CAGE-NAME-006](CAGE-NAME-006.md) | 任务名必须小驼峰 |
+
+## 组织模型
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ORG-001](CAGE-ORG-001.md) | 业务入口遗漏组织模型 |
+
+## 资源配对
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-PAIR-002](CAGE-PAIR-002.md) | 离开持有资源状态却没有释放 |
+
+## 安全查询
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-QUERY-001](CAGE-QUERY-001.md) | 查询必须选择一种实现 |
+| [CAGE-QUERY-002](CAGE-QUERY-002.md) | 自定义查询直接访问基表 |
+| [CAGE-QUERY-003](CAGE-QUERY-003.md) | 查询读取范围与声明不一致 |
+
+## 跨聚合反应
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REACT-001](CAGE-REACT-001.md) | 反应目标与命令聚合不一致 |
+| [CAGE-REACT-002](CAGE-REACT-002.md) | 同事务反应链嵌套过深 |
+
+## 显式读依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-READS-001](CAGE-READS-001.md) | handler 使用了未声明读依赖 |
+
+## 运行时注册表
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REG-001](CAGE-REG-001.md) | 注册表缺少被引用声明 |
+| [CAGE-REG-002](CAGE-REG-002.md) | 聚合或查询注册重名 |
+| [CAGE-REG-003](CAGE-REG-003.md) | 命令能力点重复 |
+
+## 自动路由
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ROUTE-001](CAGE-ROUTE-001.md) | 业务项目手写 HTTP 路由 |
+
+## 数据范围
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SCOPE-001](CAGE-SCOPE-001.md) | 范围组合子未知 |
+| [CAGE-SCOPE-002](CAGE-SCOPE-002.md) | 范围字段没有声明 |
+
+## 密钥边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SECRET-001](CAGE-SECRET-001.md) | 运行环境缺少密钥 |
+| [CAGE-SECRET-002](CAGE-SECRET-002.md) | 源码疑似包含密钥字面量 |
+
+## 敏感字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SENS-001](CAGE-SENS-001.md) | 敏感字段未标注就进入事件 |
+
+## SQL 参数化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SQL-001](CAGE-SQL-001.md) | SQL 拼接用户值 |
+| [CAGE-SQL-002](CAGE-SQL-002.md) | sql.raw 接收动态表达式 |
+
+## 状态与可达性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STATE-001](CAGE-STATE-001.md) | 引用了未声明状态 |
+| [CAGE-STATE-002](CAGE-STATE-002.md) | 状态集合为空 |
+| [CAGE-STATE-003](CAGE-STATE-003.md) | 状态名称格式错误 |
+| [CAGE-STATE-004](CAGE-STATE-004.md) | 状态名称重复 |
+| [CAGE-STATE-005](CAGE-STATE-005.md) | 状态声明位置冲突 |
+| [CAGE-STATE-010](CAGE-STATE-010.md) | 状态不可达 |
+| [CAGE-STATE-011](CAGE-STATE-011.md) | 非终态没有后续操作 |
+
+## AI 托管区
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SYNC-001](CAGE-SYNC-001.md) | AGENTS 托管区过期或标记损坏 |
+
+## 测试报告
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-TEST-001](CAGE-TEST-001.md) | 测试进程没有生成结果报告 |
+
+## 逃生口
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UNSAFE-001](CAGE-UNSAFE-001.md) | 逃生口缺少原因或负责人 |
+
+## 升级
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UPGRADE-001](CAGE-UPGRADE-001.md) | 升级版本或 codemod 有歧义 |
+
+## 历史流程
+
+[CAGE-MIG-003](CAGE-MIG-003.md)、[CAGE-MIG-004](CAGE-MIG-004.md) 属于旧版初始化流程，当前使用 init + migrate；保留页面供历史诊断。
+
+手册随创建项目时的 CLI 版本分发。cage sync 仅更新 AGENTS 托管区；升级后需要按该版本的资料核对差异。
+
+框架维护者：修改 scripts/error-catalog.ts 后运行 pnpm docs:errors；不要只手改生成的逐码页面。

package/templates/blank/docs/errors/runtime.md

@@ -0,0 +1,50 @@
+# HTTP 运行时错误与业务码
+
+[返回错误码册](README.md) · [排错方法](../ai/troubleshooting.md)
+
+框架诊断分三层：`CAGE-APPR-007` 等内部/工具码、HTTP 响应的通用 `code`、业务拒绝的 `domainCode`。同一次失败可以同时涉及几层；例如审批人配置问题出现在 worker 死信，前端提交此前可能已成功。
+
+## 接口错误
+
+| code | HTTP | 含义 | 业务前端/AI 应怎么做 |
+| --- | --- | --- | --- |
+| UNAUTHENTICATED | 401 | 会话不存在/失效或认证未通过 | 重新登录；回调先核对验签，不跳过认证 |
+| FORBIDDEN | 403 | 无能力、身份不允许，或 CSRF 拒绝等 | 看 detail 与当前授权；不能只因有按钮就认为有权。客户端会刷新过期 CSRF 令牌重试 |
+| NOT_FOUND | 404 | 记录不存在或超出范围 | 用当前用户检查 id/租户/范围，不泄漏范围外数据 |
+| INVALID_INPUT | 400 | Zod/协议输入错误、外键或检查约束等 | 按输入 schema 修正字段和格式，不直接扩大 schema |
+| INVALID_TRANSITION | 409 | 当前状态不允许该命令 | 刷新记录，按真实生命周期显示允许操作 |
+| CONSTRAINT_VIOLATED | 403 | 职责分离、额度、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
+| INVARIANT_VIOLATED | 409 | 命令结果不满足聚合不变量 | 修正输入或 handler，保持合法结果 |
+| CONFLICT | 409 | 版本、唯一性、数据库串行化/死锁等冲突 | 看 detail、重新读取再决定是否重试；不要盲目重复创建 |
+| DOMAIN_ERROR | 422 | handler 返回 fail | 读取 domainCode，展示业务文案和必要 detail |
+| RATE_LIMITED | 429 | 请求超过限流 | 按提示等待，避免页面无限重试 |
+| INTERNAL | 500 | 未分类内部错误 | 用 requestId 查服务端日志，向用户显示通用失败；不返回堆栈/密钥 |
+| NETWORK（仅客户端） | 0 | 请求未取得可用网络响应 | 检查连接与服务状态；保留同次操作幂等键，避免误认为服务端一定未执行 |
+
+网络失败和超时不证明服务端事务未提交。通用重试与人工重试都需考虑幂等与当前状态，不能先写 SQL 回滚业务再重发。
+
+## 业务码用法
+
+领域 handler 返回：
+
+```ts
+return fail('STOCK_SHORT', ['A-01']);
+```
+
+HTTP 响应形状为：
+
+```json
+{ "code": "DOMAIN_ERROR", "domainCode": "STOCK_SHORT", "detail": ["A-01"] }
+```
+
+客户端方法返回可区分结果，先判断 `result.ok`；失败时看 `result.code`，业务错误再看 `result.domainCode`。不要假设 code 直接等于 STOCK_SHORT，也不要把所有 403 当作“请重新登录”。
+
+业务码由项目定义并在页面翻译；字段 schema、不变量、硬约束和业务 fail 各有职责。正常业务拒绝不要伪装成普通异常导致 INTERNAL。
+
+## 异步任务与死信
+
+导入/导出 HTTP 202 只表示任务已接受，任务详情另有 queued/processing/retrying/completed/failed/expired。检查 task.errorCode/result 和导入报告，完成后才提供成功提示或下载。
+
+outbox 消费失败可能重试或进死信；修复内层错误后重放，查看同一聚合后续消息是否继续。使用管理接口处理，不直接更新 sys.outbox 或业务状态。
+
+当前实现定义位于框架源码 `packages/kernel/src/errors.ts` 与客户端包；实际 API 响应为准。生成契约会列出命令可能的通用错误与能抽取到的业务码，但不代表任何错误都已被实际测试覆盖。

package/templates/blank/docs/examples/purchase-admin/README.md

@@ -0,0 +1,5 @@
+# 采购范例参考源码
+
+本目录只供阅读，不参与应用编译、注册、运行或迁移。当前应用的真实领域入口是项目根目录 packages/domain/src/index.ts。
+
+按 [采购范例导读](../../ai/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。

package/templates/blank/docs/examples/purchase-admin/apps/api/src/main.ts

@@ -0,0 +1,10 @@
+// 启动入口只装配框架：认证、业务路由和 /admin 都由 createServer 提供。
+// WEB_DIR 在部署镜像中指向 Vite 构建产物；本地由 Vite 独立提供前端。
+import { createServer } from '@yss123/cage-http';
+import * as domain from '@app/domain';
+
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台' });
+await server.listen();
+// 退出时释放数据库池及 LISTEN 连接，部署滚动替换时不会留下旧连接。
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());

package/templates/blank/docs/examples/purchase-admin/apps/api/src/worker.ts

@@ -0,0 +1,14 @@
+// API 与 worker 使用相同声明。worker 专门处理审批启动、异步反应和 ERP 推送。
+import { startWorker } from '@yss123/cage-http/worker';
+import { fakeConnector, stage } from '@yss123/cage-connectors';
+import * as domain from '@app/domain';
+
+// 本地和测试的 ERP 返回确定的单号，便于查看同步记录；生产环境走真实出口。
+if (stage() === 'fake') {
+  fakeConnector(domain.erp, {
+    pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId.slice(0, 8)}` }),
+  });
+}
+const worker = await startWorker({ domain });
+process.once('SIGINT', () => void worker.stop());
+process.once('SIGTERM', () => void worker.stop());

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/app.tsx

@@ -0,0 +1,18 @@
+// 应用组合层只决定会话与页面的切换；具体业务交给 modules 下的页面。
+import { useEffect, useState } from 'react';
+import { loadMe } from '@app/contracts';
+import { LoginPage } from '../modules/auth';
+import { WorkspaceLayout } from './workspace-layout';
+
+export function App() {
+  const [session, setSession] = useState<'loading' | 'guest' | 'ready'>('loading');
+  useEffect(() => {
+    void loadMe().then((result) => setSession(result.ok ? 'ready' : 'guest'));
+  }, []);
+  if (session === 'loading') return <div className="loading">正在连接工作台…</div>;
+  return session === 'guest' ? (
+    <LoginPage onLogin={() => setSession('ready')} />
+  ) : (
+    <WorkspaceLayout onLogout={() => setSession('guest')} />
+  );
+}