@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,357 @@
+# 错误码册
+
+这是本业务项目自带的离线诊断手册。先使用错误码、声明位置、reason/fix 定位；不需要克隆框架仓库。
+
+- [HTTP 运行时错误与业务码](runtime.md)：401/403/404、状态冲突、约束拒绝、DOMAIN_ERROR 等。
+- [业务排错顺序](../ai/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
+- CAGE-* 是声明、工具链或内部运行诊断；HTTP code 与业务 domainCode 是另一层，不要混为一谈。
+
+每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
+
+## 智能运行时
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AI-001](CAGE-AI-001.md) | 智能运行时声明无效 |
+
+## 文件字段与上传
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-FILE-001](CAGE-FILE-001.md) | 文件字段或上传配置无效 |
+
+## 可靠读取审计
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AUDIT-001](CAGE-AUDIT-001.md) | 可靠读取审计失败 |
+
+## 运行状态诊断
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DIAG-001](CAGE-DIAG-001.md) | 运行诊断输入或连接失败 |
+
+## 后台执行与就绪
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-WORKER-001](CAGE-WORKER-001.md) | 缺少必要后台引擎 |
+| [CAGE-WORKER-002](CAGE-WORKER-002.md) | 事件与消费者清单不匹配 |
+| [CAGE-WORKER-003](CAGE-WORKER-003.md) | 后台任务未在停机时限内结束 |
+
+## 审批
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [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-BIZ-001](CAGE-BIZ-001.md) | 业务流程声明无效 |
+| [CAGE-BIZ-002](CAGE-BIZ-002.md) | 业务流程与真实声明不一致 |
+
+## 体积与逃生口预算
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [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-CONN-013](CAGE-CONN-013.md) | 出站幂等键无效或请求冲突 |
+| [CAGE-CONN-014](CAGE-CONN-014.md) | 不可重试外部写入结果未知 |
+| [CAGE-CONN-015](CAGE-CONN-015.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-ENV-002](CAGE-ENV-002.md) | 运行配置不满足安全边界 |
+| [CAGE-ENV-003](CAGE-ENV-003.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-GEN-003](CAGE-GEN-003.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-IMPACT-002](CAGE-IMPACT-002.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-INIT-005](CAGE-INIT-005.md) | 显式组织初始化或凭据交付失败 |
+
+## 定时任务
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [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-REACT-003](CAGE-REACT-003.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-TEST-002](CAGE-TEST-002.md) | 派生测试准备或初始夹具失败 |
+| [CAGE-TEST-003](CAGE-TEST-003.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/app/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/app/package.json

@@ -5,18 +5,15 @@
   "packageManager": "pnpm@10.14.0",
   "scripts": {
     "dev": "cage dev",
-    "db:setup": "cage db setup",
-    "db:up": "cage db up",
-    "db:down": "cage db down",
-    "db:status": "cage db status",
+    "migrate": "cage migrate",
     "verify": "cage verify",
     "gen": "cage gen",
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.1.0",
-    "@yss123/cage-testkit": "0.1.0",
-    "@yss123/cage-lint": "0.1.0",
+    "@yss123/cage-cli": "0.3.0",
+    "@yss123/cage-testkit": "0.3.0",
+    "@yss123/cage-lint": "0.3.0",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/app/packages/contracts/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.1.0",
+    "@yss123/cage-client": "0.3.0",
     "zod": "^4.1.5"
   }
 }

package/templates/app/packages/contracts/src/{dept.ts → aggregates/dept/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** 部门：读侧快照（敏感字段是按权限掩码后的值） */
 export const DeptSchema = z.object({
@@ -23,9 +23,9 @@ export const DeptStates = ['active', 'archived'] as const;
 
 /** 命令输入：和后端命令的输入校验完全一致 */
 export const DeptInputs = {
-  archive: z.object({ id: z.string().uuid() }),
-  create: z.object({ name: z.string().min(1).max(100), code: z.string().max(64).optional(), parentId: z.string().uuid().nullable().optional(), leaderId: z.string().uuid().nullable().optional() }),
-  update: z.object({ id: z.string().uuid(), name: z.string().min(1).max(100).optional(), code: z.string().max(64).nullable().optional(), leaderId: z.string().uuid().nullable().optional() }),
+  archive: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+  create: z.object({ name: z.string().min(1).max(100), code: z.string().max(64).optional(), parentId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
+  update: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), name: z.string().min(1).max(100).optional(), code: z.string().max(64).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
 };
 
 /** Dept.archive 可能返回的错误码 */
@@ -55,15 +55,15 @@ export interface DeptListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const dept = {
   /** 停用部门（没有在职用户和下级部门时） */
-  archive: (id: string, expectedVersion?: number) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }),
+  archive: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }, options),
   /** 新建部门 */
-  create: (input: z.input<typeof DeptInputs.create>) => client.post<Dept, DeptCreateError>('/api/dept/create', input),
+  create: (input: z.input<typeof DeptInputs.create>, options: RequestOptions = {}) => client.post<Dept, DeptCreateError>('/api/dept/create', input, options),
   /** 修改部门名称、编码、负责人 */
-  update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
-  /** 导出 CSV：需要 Dept.export 能力 */
-  export: (params: DeptListParams = {}) => client.post<string, never>('/api/dept/export', params),
-  get: (id: string) => client.get<Dept>(`/api/dept/${encodeURIComponent(id)}`),
-  list: (params: DeptListParams = {}) => client.get<{ items: Dept[]; total: number; page: number; pageSize: number }>('/api/dept', params as Record<string, unknown>),
+  update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Dept.export 能力。 */
+  export: (params: DeptListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/dept/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Dept>(`/api/dept/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: DeptListParams = {}, options: RequestOptions = {}) => client.get<{ items: Dept[]; total: number; page: number; pageSize: number }>('/api/dept', params as Record<string, unknown>, options),
 };
 
 /** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */

package/templates/app/packages/contracts/src/{inventory.ts → aggregates/inventory/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** Inventory：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventorySchema = z.object({
@@ -42,11 +42,11 @@ export interface InventoryListParams {
 
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventory = {
-  create: (input: z.input<typeof InventoryInputs.create>) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input),
-  /** 导出 CSV：需要 Inventory.export 能力 */
-  export: (params: InventoryListParams = {}) => client.post<string, never>('/api/inventory/export', params),
-  get: (id: string) => client.get<Inventory>(`/api/inventory/${encodeURIComponent(id)}`),
-  list: (params: InventoryListParams = {}) => client.get<{ items: Inventory[]; total: number; page: number; pageSize: number }>('/api/inventory', params as Record<string, unknown>),
+  create: (input: z.input<typeof InventoryInputs.create>, options: RequestOptions = {}) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Inventory.export 能力。 */
+  export: (params: InventoryListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Inventory>(`/api/inventory/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: InventoryListParams = {}, options: RequestOptions = {}) => client.get<{ items: Inventory[]; total: number; page: number; pageSize: number }>('/api/inventory', params as Record<string, unknown>, options),
 };
 
 /** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */

package/templates/app/packages/contracts/src/{inventory-lock.ts → aggregates/inventory-lock/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** InventoryLock：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventoryLockSchema = z.object({
@@ -38,10 +38,10 @@ export interface InventoryLockListParams {
 
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventoryLock = {
-  /** 导出 CSV：需要 InventoryLock.export 能力 */
-  export: (params: InventoryLockListParams = {}) => client.post<string, never>('/api/inventory-lock/export', params),
-  get: (id: string) => client.get<InventoryLock>(`/api/inventory-lock/${encodeURIComponent(id)}`),
-  list: (params: InventoryLockListParams = {}) => client.get<{ items: InventoryLock[]; total: number; page: number; pageSize: number }>('/api/inventory-lock', params as Record<string, unknown>),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 InventoryLock.export 能力。 */
+  export: (params: InventoryLockListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory-lock/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<InventoryLock>(`/api/inventory-lock/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: InventoryLockListParams = {}, options: RequestOptions = {}) => client.get<{ items: InventoryLock[]; total: number; page: number; pageSize: number }>('/api/inventory-lock', params as Record<string, unknown>, options),
 };
 
 /** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */

package/templates/app/packages/contracts/src/aggregates/purchase-order/index.ts

@@ -0,0 +1,86 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
+
+/** PurchaseOrder：读侧快照（敏感字段是按权限掩码后的值） */
+export const PurchaseOrderSchema = z.object({
+  id: z.string().uuid(),
+  deptId: z.string().uuid(),
+  createdBy: z.string().uuid(),
+  supplierPhone: z.string().nullable().optional(),
+  amount: z.string(),
+  reason: z.string().nullable().optional(),
+  items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+  erpNo: z.string().nullable().optional(),
+  attachments: z.array(z.string().uuid()).max(10),
+  status: z.enum(["draft", "pending_approval", "approved", "received", "rejected", "cancelled"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type PurchaseOrder = z.infer<typeof PurchaseOrderSchema>;
+export type PurchaseOrderStatus = PurchaseOrder['status'];
+export const PurchaseOrderStates = ['draft', 'pending_approval', 'approved', 'received', 'rejected', 'cancelled'] as const;
+/** 文件字段限制；服务端仍执行权威校验。 */
+export const PurchaseOrderFileFields = {"attachments":{"maxBytes":2147483648,"accept":["application/pdf","image/jpeg","image/png","text/plain"],"maxCount":10,"multiple":true}} as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const PurchaseOrderInputs = {
+  cancel: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+  create: z.object({ amount: z.string(), items: z.array(z.object({ sku: z.string(), qty: z.number().int().max(9007199254740991).gt(0) })).min(1), supplierPhone: z.string().optional(), reason: z.string().max(2000).optional(), deptId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).optional(), attachments: z.array(z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"))).max(10).optional() }),
+  explainPurpose: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), reason: z.unknown() }),
+  setAttachments: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), attachments: z.array(z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"))).max(10) }),
+  submit: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+};
+
+/** PurchaseOrder.cancel 可能返回的错误码 */
+export type PurchaseOrderCancelError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.create 可能返回的错误码 */
+export type PurchaseOrderCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.explainPurpose 可能返回的错误码 */
+export type PurchaseOrderExplainPurposeError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.setAttachments 可能返回的错误码 */
+export type PurchaseOrderSetAttachmentsError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.submit 可能返回的错误码；业务码（domainCode）：NO_ITEMS */
+export type PurchaseOrderSubmitError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+export type PurchaseOrderSubmitDomainCode = 'NO_ITEMS';
+
+export type PurchaseOrderSortKey = 'createdAt' | 'updatedAt' | 'deptId' | 'createdBy' | 'supplierPhone' | 'amount' | 'reason' | 'erpNo';
+export interface PurchaseOrderListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: PurchaseOrderSortKey | `-${PurchaseOrderSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  deptId?: string | number | boolean;
+  createdBy?: string | number | boolean;
+  amount?: string | number | boolean;
+  reason?: string | number | boolean;
+  erpNo?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const purchaseOrder = {
+  cancel: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderCancelError>(`/api/purchase-order/${encodeURIComponent(id)}/cancel`, { expectedVersion }, options),
+  create: (input: z.input<typeof PurchaseOrderInputs.create>, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderCreateError>('/api/purchase-order/create', input, options),
+  /** 补充采购用途与必要性，保存后可以重新提交审核 */
+  explainPurpose: (id: string, input: Omit<z.input<typeof PurchaseOrderInputs.explainPurpose>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderExplainPurposeError>(`/api/purchase-order/${encodeURIComponent(id)}/explain-purpose`, { ...input, expectedVersion }, options),
+  setAttachments: (id: string, input: Omit<z.input<typeof PurchaseOrderInputs.setAttachments>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderSetAttachmentsError>(`/api/purchase-order/${encodeURIComponent(id)}/set-attachments`, { ...input, expectedVersion }, options),
+  submit: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderSubmitError>(`/api/purchase-order/${encodeURIComponent(id)}/submit`, { expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 PurchaseOrder.export 能力。 */
+  export: (params: PurchaseOrderListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<PurchaseOrder>(`/api/purchase-order/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: PurchaseOrderListParams = {}, options: RequestOptions = {}) => client.get<{ items: PurchaseOrder[]; total: number; page: number; pageSize: number }>('/api/purchase-order', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const usePurchaseOrder = (id: string) => useCageQuery(['purchase-order', id], `/api/purchase-order/${encodeURIComponent(id)}`, PurchaseOrderSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const usePurchaseOrderList = (params: PurchaseOrderListParams = {}) => useCageList(['purchase-order'], '/api/purchase-order', params as Record<string, unknown>, PurchaseOrderSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const purchaseOrderKeys = { all: ['purchase-order'] as const, one: (id: string) => ['purchase-order', id] as const };