@yss123/cage-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,50 @@
+# CAGE-TEST-002：派生测试准备或初始夹具失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+派生测试在业务命令执行前无法构造合法夹具，或初始记录已经违反不变量。
+
+## 修复步骤
+
+1. 按 trace 的阶段、种子、fixture 和前置不变量修复准备数据；必要时提供业务 fixture。
+2. 使用相同随机种子重放；区分准备失败与合法初始状态下的真实业务反例，不放宽不变量。
+
+## 正例
+
+```text
+derived(domain, { seed: 20261103, /* 按公开类型提供合法 fixture */ })
+```
+
+## 反例
+
+```text
+初始预算已经不守恒，却报告命令破坏预算守恒
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/derived-diagnostics.ts:73`
+- `packages/testkit/src/derived-diagnostics.ts:77`
+- `packages/testkit/src/derived-diagnostics.ts:82`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+/**
+ * 携带结构化失败轨迹的测试异常，统一标识为 CAGE-TEST-002。
+ * 构造前由调用方脱敏 detail，消息序列化同一轨迹，phase/aggregate/seed 提供快速定位字段。
+ */
+export class DerivedTestError extends Error {
+```

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

@@ -0,0 +1,52 @@
+# CAGE-TEST-003：测试数据库目录归属不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+临时 PostgreSQL 的目录、归属标记、实际 data_directory 或端口与本次启动实例不符。
+
+## 修复步骤
+
+1. 保留诊断并核对本次测试自己的实例；修复路径或生命周期后重新运行。
+2. 已有目录明确使用 persistent: true；不删除未知目录、不按进程名批量终止 PostgreSQL。
+
+## 正例
+
+```text
+测试工具停止自己创建且验证归属的临时实例
+```
+
+## 反例
+
+```text
+将已有业务目录作为自动清理目录，或为了退出测试结束所有 postgres 进程
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/pg.ts:63`
+- `packages/testkit/src/pg.ts:65`
+- `packages/testkit/src/pg.ts:90`
+- `packages/testkit/src/pg.ts:96`
+- `packages/testkit/src/pg.ts:107`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const dir = resolve(opts.dir ?? mkdtempSync(join(tmpdir(), 'cage-pg-')));
+  if (dir === parse(dir).root) throw new Error('[CAGE-TEST-003] 内嵌 PostgreSQL 目录不能是文件系统根目录');
+  const fresh = !existsSync(join(dir, 'PG_VERSION'));
+  if (!persistent && !fresh) throw new Error('[CAGE-TEST-003] 不允许将已有 PostgreSQL 目录作为自动删除的临时实例；使用 persistent: true');
+  if (persistent) mkdirSync(dir, { recursive: true });
+```

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

@@ -34,8 +34,9 @@ unsafe({ reason: '', owner: '' }, action)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:219`
-- `packages/lint/src/rules/unsafe-needs-reason.ts:8`
+- `packages/kernel/src/primitives/flow.ts:383`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:10`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:17`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,8 +34,8 @@ command(A, { caller: 'user', invokedBy: 'process', ... })
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/upgrade.ts:45`
-- `packages/cli/src/upgrade.ts:58`
+- `packages/cli/src/upgrade.ts:60`
+- `packages/cli/src/upgrade.ts:79`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -0,0 +1,48 @@
+# CAGE-WORKER-001：缺少必要后台引擎
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+声明存在审批等必要消费者，但启动 worker 时没有提供相应引擎。
+
+## 修复步骤
+
+1. 按 domain 声明装配真实审批引擎和连接器运行环境，检查 worker manifest。
+2. 不要删除审批声明或把必需引擎缺失降级为警告。
+
+## 正例
+
+```text
+使用标准 createWorker 入口装配声明要求的审批引擎
+```
+
+## 反例
+
+```text
+带审批绑定的注册表启动时跳过审批引擎
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/consumers.ts:66`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!engine) {
+      throw new Error(`[CAGE-WORKER-001] 审批绑定 ${name} 缺少流程 ${a.process} 的审批引擎；补齐路由或装配引擎后再启动 worker`);
+    }
+    out.push({
+      name: `approval:${name}:start`,
+```

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

@@ -0,0 +1,50 @@
+# CAGE-WORKER-002：事件与消费者清单不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+worker 收到未知事件或缺少声明要求的消费者，消息不能静默完成。
+
+## 修复步骤
+
+1. 通过 doctor/timeline 核对 API 与 worker 的版本、注册指纹、消费者清单和心跳。
+2. 首阶段停止旧进程后同版本升级 API 与 worker，再检查死信并按允许方式恢复；不要直接修改 done 状态。
+
+## 正例
+
+```text
+更新匹配版本后重放死信，确认消费者处理证据
+```
+
+## 反例
+
+```text
+旧 worker 对新关键事件找不到消费者仍标记 done
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:289`
+- `packages/kernel/src/worker/outbox.ts:40`
+- `packages/kernel/src/worker/outbox.ts:106`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    async handle(row, tx, _kernel, prepared) {
+      if (!prepared) throw new Error('[CAGE-WORKER-002] 出站消费者必须经 worker prepare 阶段执行');
+      const result = prepared as OutboundPrepared;
+      if (result.skipped) return;
+      if (ob.onSuccess) {
+```

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

@@ -0,0 +1,48 @@
+# CAGE-WORKER-003：后台任务未在停机时限内结束
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+停止接收新任务并取消外部 IO 后，在途任务仍超过退出时限。
+
+## 修复步骤
+
+1. 检查任务、网络超时和阻塞阶段；等待在途任务结束后再释放锁与连接。
+2. 核对恢复记录和远端幂等结果；不要在任务还执行时强行释放互斥锁。
+
+## 正例
+
+```text
+先停止领取，再等待并核对运行任务的退出结果
+```
+
+## 反例
+
+```text
+停机时直接关锁连接，允许第二个实例和旧任务同时执行
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/index.ts:269`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        const timeout = setTimeout(() => {
+          state.lastError = `[CAGE-WORKER-003] 停机等待超时，在途任务：${snapshot().inFlight.join(', ')}`;
+          log.error({ err: state.lastError }, 'worker 停机超时；任务结束前保留锁和连接');
+          reject(new Error(state.lastError));
+        }, opts.shutdownTimeoutMs ?? 30_000);
+```

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

@@ -8,6 +8,38 @@
 
 每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
 
+## 智能运行时
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [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) | 后台任务未在停机时限内结束 |
+
 ## 审批
 
 | 诊断码 | 含义 |
@@ -27,6 +59,13 @@
 | --- | --- |
 | [CAGE-AUTH-001](CAGE-AUTH-001.md) | OIDC 发现文档获取失败 |
 
+## 业务流程阅读规格
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-BIZ-001](CAGE-BIZ-001.md) | 业务流程声明无效 |
+| [CAGE-BIZ-002](CAGE-BIZ-002.md) | 业务流程与真实声明不一致 |
+
 ## 体积与逃生口预算
 
 | 诊断码 | 含义 |
@@ -58,6 +97,9 @@
 | [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) | 连接器超时或限流参数无效 |
 
 ## 创建应用
 
@@ -102,6 +144,8 @@
 | 诊断码 | 含义 |
 | --- | --- |
 | [CAGE-ENV-001](CAGE-ENV-001.md) | 缺少数据库连接配置 |
+| [CAGE-ENV-002](CAGE-ENV-002.md) | 运行配置不满足安全边界 |
+| [CAGE-ENV-003](CAGE-ENV-003.md) | 服务启动不能隐式初始化组织 |
 
 ## 事件载荷与兼容性
 
@@ -131,6 +175,7 @@
 | --- | --- |
 | [CAGE-GEN-001](CAGE-GEN-001.md) | 契约等生成结果过期 |
 | [CAGE-GEN-002](CAGE-GEN-002.md) | 声明结构没有对应迁移 |
+| [CAGE-GEN-003](CAGE-GEN-003.md) | 输入校验需要服务端执行 |
 
 ## 角色授权与防提权
 
@@ -145,6 +190,7 @@
 | 诊断码 | 含义 |
 | --- | --- |
 | [CAGE-IMPACT-001](CAGE-IMPACT-001.md) | 影响分析没有可用基线 |
+| [CAGE-IMPACT-002](CAGE-IMPACT-002.md) | 命名本体快照无效 |
 
 ## 账号初始化
 
@@ -154,6 +200,7 @@
 | [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) | 显式组织初始化或凭据交付失败 |
 
 ## 定时任务
 
@@ -214,6 +261,7 @@
 | --- | --- |
 | [CAGE-REACT-001](CAGE-REACT-001.md) | 反应目标与命令聚合不一致 |
 | [CAGE-REACT-002](CAGE-REACT-002.md) | 同事务反应链嵌套过深 |
+| [CAGE-REACT-003](CAGE-REACT-003.md) | 集合或步骤顺序声明无效 |
 
 ## 显式读依赖
 
@@ -285,6 +333,8 @@
 | 诊断码 | 含义 |
 | --- | --- |
 | [CAGE-TEST-001](CAGE-TEST-001.md) | 测试进程没有生成结果报告 |
+| [CAGE-TEST-002](CAGE-TEST-002.md) | 派生测试准备或初始夹具失败 |
+| [CAGE-TEST-003](CAGE-TEST-003.md) | 测试数据库目录归属不匹配 |
 
 ## 逃生口
 

package/templates/app/package.json

@@ -11,9 +11,9 @@
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.2.0",
-    "@yss123/cage-testkit": "0.2.0",
-    "@yss123/cage-lint": "0.2.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.2.0",
+    "@yss123/cage-client": "0.3.0",
     "zod": "^4.1.5"
   }
 }

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

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } 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 }),
+  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: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/dept/export', params, options),
-  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>),
+  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/aggregates/inventory/index.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } 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),
+  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: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory/export', params, options),
-  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>),
+  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/aggregates/inventory-lock/index.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** InventoryLock：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventoryLockSchema = z.object({
@@ -39,9 +39,9 @@ export interface InventoryLockListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventoryLock = {
   /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 InventoryLock.export 能力。 */
-  export: (params: InventoryLockListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory-lock/export', params, options),
-  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>),
+  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

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** PurchaseOrder：读侧快照（敏感字段是按权限掩码后的值） */
 export const PurchaseOrderSchema = z.object({
@@ -11,8 +11,10 @@ export const PurchaseOrderSchema = z.object({
   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(),
@@ -21,23 +23,31 @@ export const PurchaseOrderSchema = z.object({
 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() }),
-  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(), deptId: z.string().uuid().optional() }),
-  submit: z.object({ id: z.string().uuid() }),
+  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';
+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' | 'erpNo';
+export type PurchaseOrderSortKey = 'createdAt' | 'updatedAt' | 'deptId' | 'createdBy' | 'supplierPhone' | 'amount' | 'reason' | 'erpNo';
 export interface PurchaseOrderListParams {
   page?: number;
   pageSize?: number;
@@ -50,18 +60,22 @@ export interface PurchaseOrderListParams {
   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) => client.post<PurchaseOrder, PurchaseOrderCancelError>(`/api/purchase-order/${encodeURIComponent(id)}/cancel`, { expectedVersion }),
-  create: (input: z.input<typeof PurchaseOrderInputs.create>) => client.post<PurchaseOrder, PurchaseOrderCreateError>('/api/purchase-order/create', input),
-  submit: (id: string, expectedVersion?: number) => client.post<PurchaseOrder, PurchaseOrderSubmitError>(`/api/purchase-order/${encodeURIComponent(id)}/submit`, { expectedVersion }),
+  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: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),
-  get: (id: string) => client.get<PurchaseOrder>(`/api/purchase-order/${encodeURIComponent(id)}`),
-  list: (params: PurchaseOrderListParams = {}) => client.get<{ items: PurchaseOrder[]; total: number; page: number; pageSize: number }>('/api/purchase-order', params as Record<string, unknown>),
+  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 */