@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/blank/docs/errors/CAGE-STATE-001.md

@@ -34,9 +34,9 @@ to: 'finished'，状态集中只有 done
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/command.ts:130`
-- `packages/kernel/src/primitives/command.ts:138`
-- `packages/kernel/src/primitives/states.ts:29`
+- `packages/kernel/src/primitives/command.ts:228`
+- `packages/kernel/src/primitives/command.ts:236`
+- `packages/kernel/src/primitives/states.ts:59`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-STATE-002.md

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

package/templates/blank/docs/errors/CAGE-STATE-003.md

@@ -34,7 +34,7 @@ states('PendingApproval', '已完成')
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/states.ts:24`
+- `packages/kernel/src/primitives/states.ts:54`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-STATE-004.md

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

package/templates/blank/docs/errors/CAGE-STATE-005.md

@@ -34,8 +34,9 @@ fields: { stage: POStatus }，或 states 与 fields.status 同时提供
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/aggregate.ts:78`
-- `packages/kernel/src/primitives/aggregate.ts:79`
+- `packages/kernel/src/primitives/aggregate.ts:169`
+- `packages/kernel/src/primitives/aggregate.ts:170`
+- `packages/kernel/src/primitives/states.ts:62`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-STATE-010.md

@@ -34,15 +34,15 @@ states 包含 received，却没有任何命令迁移到它
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:67`
-- `packages/cli/src/rules.ts:93`
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:123`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
-export function checkStates(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
 ```

package/templates/blank/docs/errors/CAGE-STATE-011.md

@@ -34,15 +34,15 @@ states('draft', 'done', { terminal: ['done'] })，draft 有提交路径
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:67`
-- `packages/cli/src/rules.ts:102`
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:132`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
-export function checkStates(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
 ```

package/templates/blank/docs/errors/CAGE-STRUCT-001.md

@@ -38,7 +38,7 @@ packages/domain/src/expense.ts
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/project-structure.ts:58`
+- `packages/cli/src/project-structure.ts:74`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-STRUCT-002.md

@@ -38,7 +38,7 @@ import { ExpensePage } from '../../modules/expense/pages/expense-page';
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/project-structure.ts:108`
+- `packages/cli/src/project-structure.ts:124`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-SYNC-001.md

@@ -34,8 +34,9 @@ sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/sync.ts:97`
-- `packages/cli/src/sync.ts:110`
+- `packages/cli/src/sync.ts:149`
+- `packages/cli/src/sync.ts:156`
+- `packages/cli/src/sync.ts:167`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/docs/errors/CAGE-TEST-001.md

@@ -34,7 +34,7 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/verify.ts:36`
+- `packages/cli/src/verify.ts:48`
 
 实现片段（位置随框架版本更新）：
 

package/templates/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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/blank/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/blank/docs/errors/README.md

@@ -8,16 +8,48 @@
 
 每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
 
+## 智能运行时
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [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-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-006](CAGE-APPR-006.md) | 审批步骤配置无效 |
 | [CAGE-APPR-007](CAGE-APPR-007.md) | 找不到审批人 |
 | [CAGE-APPR-010](CAGE-APPR-010.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/blank/docs/examples/purchase-admin/apps/api/src/main.ts

@@ -1,9 +1,13 @@
 // 启动入口只装配框架：认证、业务路由和 /admin 都由 createServer 提供。
 // WEB_DIR 在部署镜像中指向 Vite 构建产物；本地由 Vite 独立提供前端。
+// 进程启动只建立服务，不迁移结构、不初始化账号；这些操作由受控 CLI 流程提前完成。
+// 声明中启用的 AI、审批与文件接口由框架挂载，后台事件消费仍需要独立 worker 进程。
 import { createServer } from '@yss123/cage-http';
 import * as domain from '@app/domain';
 
-const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台' });
+// 默认不接受转发头；部署在代理后时，仅在这里填写实际可信代理的地址或网段。
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台', trustProxy: false });
+// listen 先等待路由、扩展与授权通知初始化；失败直接拒绝顶层启动，不伪装为已就绪。
 await server.listen();
 // 退出时释放数据库池及 LISTEN 连接，部署滚动替换时不会留下旧连接。
 process.once('SIGINT', () => void server.close());

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

@@ -1,4 +1,5 @@
 // API 与 worker 使用相同声明。worker 专门处理审批启动、异步反应和 ERP 推送。
+// 两个进程部署同一版本，消费者依据声明发现工作；事件提交成功不等于这些后台动作已经完成。
 import { startWorker } from '@yss123/cage-http/worker';
 import { fakeConnector, stage } from '@yss123/cage-connectors';
 import * as domain from '@app/domain';
@@ -9,6 +10,8 @@ if (stage() === 'fake') {
     pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId.slice(0, 8)}` }),
   });
 }
+// 框架拥有轮询、重试、调度和连接生命周期；应用只注册本地 fake，不另建数据库池或业务重试循环。
 const worker = await startWorker({ domain });
+// 停止句柄等待框架在途工作收尾并释放连接，避免进程退出时留下仍在续租的消费者。
 process.once('SIGINT', () => void worker.stop());
 process.once('SIGTERM', () => void worker.stop());