@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/docs/ai/purchase-example.md

@@ -0,0 +1,97 @@
+# 标准采购范例：从声明到业务页面
+
+[返回学习入口](README.md) · [业务任务配方](recipes.md)
+
+选择 `--template purchase` 创建的是可运行的采购应用，下面的路径相对应用根目录；选择 `--template blank` 时，同一份范例仅作为参考源码保存在 `docs/examples/purchase-admin`，下面路径相对该参考目录，它不参与当前应用的编译、注册或迁移。框架能力来自 npm 依赖。先沿一条真实链路读代码，再把需要的模式应用到自己的业务。
+
+## 按这个顺序读文件
+
+| 文件（相对应用根目录） | 看懂的业务能力 | 改造时关注什么 |
+| --- | --- | --- |
+| `packages/domain/src/index.ts` | 哪些声明真正被注册 | 保留组织模型，导出新增业务，避免导出名冲突 |
+| `packages/domain/src/modules/inventory/inventory.ts` | 最简字段、创建命令、资源锁聚合 | scope.none 不等于无需授权；创建与释放都是命令 |
+| `packages/domain/src/modules/purchase/purchase-order.ts` | 单据生命周期、金额、明细、约束、事件 | 哪些字段由输入提供，哪些由内核维护；每个状态的允许操作 |
+| `packages/domain/src/workflows/purchase-inventory.ts` | 同事务建锁、异步释放 | acquires/releases 的配对及 map 返回 null 的原因 |
+| `packages/domain/src/modules/purchase/approvals.ts` | 启动/取消审批、条件步骤与选人 | routable、部门负责人、角色 code、结论命令 |
+| `packages/domain/src/integrations/erp.ts` | 出站推单、成功回写、入站回调 | 白名单、secret 名、schema、幂等与 HMAC |
+| `packages/domain/src/modules/purchase/queries.ts` | 按状态汇总 | reads、安全视图、命名参数 |
+| `packages/domain/src/modules/purchase/jobs.ts` | 过期草稿取消 | reads/calls 和 job 调用身份 |
+| `apps/api/src/main.ts`、`apps/api/src/worker.ts` | 如何启动框架与 worker | 保持薄装配，fake 只用于相应环境 |
+| `packages/contracts/src/aggregates/purchase-order/index.ts` | 生成的前端协议与类型 | 只读它，不手改；process/external 命令不生成浏览器写方法 |
+| `apps/web/src/main.tsx`、`app` | 挂载、全局 Provider、会话与导航组合 | 入口保持简洁，从模块公开入口组装页面 |
+| `apps/web/src/modules/purchase`、`inventory`、`approval` | 各业务页面与交互 | 调契约、处理错误、刷新列表、展示导出任务；不互相穿透 |
+| `packages/domain/src/modules/purchase/purchase-order.test.ts` | 有业务数据的成功/拒绝用例 | 越权、自审批、额度、库存锁、晚到 ERP 回执 |
+
+## 一次正常采购发生了什么
+
+```text
+采购员新建 → draft
+  → submit → pending_approval + OrderSubmitted（同事务提交）
+  → worker 消费事件 → 按 poRoute 创建经理待办
+  → 经理审批；金额 > 50000 时还有财务步骤
+  → 流程完成 → 调用 approve
+      → 职责分离、额度、库存检查
+      → approved + OrderApproved
+      → 同事务 lockOnApprove → InventoryLock.held
+  → worker 消费 OrderApproved → fake/真实 ERP 推单
+      → recordErpNo（external，保持当前状态）
+  → 收货回调 → markReceived → received + OrderReceived
+  → worker 释放锁 → InventoryLock.released
+```
+
+submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或其他异步工作已经完成。worker 未运行时，单据可以已经处于待审批，但没有待办。
+
+### 为什么分三个聚合
+
+- `PurchaseOrder` 管单据、审批结论和采购状态。
+- `Inventory` 是物料台账，提供库存检查的数据。
+- `InventoryLock` 记录某张订单的资源占用，使用订单 id 作为锁 id，让释放目标明确。
+
+审批通过和建锁放在同一事务，是为了避免“单据已批准却没拿到资源”。ERP 网络请求放到 outbox，是因为远端调用无法与本地 PostgreSQL 共同回滚。
+
+### 取消为什么要带 previousStatus
+
+草稿或待审批取消时还没有库存锁，不应释放不存在的锁；已批准取消才需要释放。因此 `OrderCancelled` 的显式 emit 映射携带旧状态，反应通过 `previousStatus === 'approved'` 决定是否调用释放命令。
+
+新增撤回、作废等动作时，每一条离开已批准状态的路径都要考虑资源。仅把命令 `to` 改成新状态，可能被 `CAGE-PAIR-002` 拦下；补了标签也仍要确保真正的释放命令会执行。
+
+### ERP 回执为什么用 to: null
+
+网络应答可能晚于取消或收货到达。`recordErpNo` 允许从 approved/received/cancelled 更新单号，用 `to: null` 保持加锁时的当前状态；不会把取消单重新变成已批准。它仍受调用身份、允许状态、版本和审计约束。
+
+本例没有真实 ERP 取消补偿。上线时需另外设计远端撤销、退货或人工补偿，不能把“本地取消成功”当成“远端订单已撤销”。
+
+## 首次体验所需业务配置
+
+以下体验需要采购模板；空白模板不会出现采购页面和审批配置。先按[开发步骤](workflow.md)准备已有数据库并启动 API、worker、Web。首次管理员凭证按 API 提示获取，不把凭证写到仓库。以下是业务配置，不是需要写进框架内核的逻辑。
+
+| 对象 | 配置要点 |
+| --- | --- |
+| 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围 |
+| 经理 | `PurchaseOrder.read/approve/reject`，适当数据范围，`approve` 的 `ceiling` 额度参数 |
+| 部门 | 将采购员所属部门的负责人设为经理；不能为空 |
+| 财务 | 角色 **code** 为 `finance`，给实际用户分配；配置审批所需权限、范围及额度 |
+| 库存台账 | 预先登记与采购明细相同的 sku，数量满足演示检查 |
+| 连接器环境 | fake 阶段使用 worker 注册的 fake；真实环境另配 host 对应密钥及回调签名密钥 |
+
+经理与提单人必须是不同用户。配置“负责人”决定选谁；配置角色能力与范围决定此人能否完成结论命令，两者都需要。金额 **大于** 50,000 才追加财务步骤，恰好 50,000 不满足 gt 条件。
+
+## 页面如何使用框架
+
+采购页和库存页通过 `@app/contracts` 获取方法、快照类型和查询 hooks。命令成功后刷新相应列表；失败时按 code/domainCode 展示原因。只有允许 user 调用的命令才生成页面方法，因此审批通过应使用待办接口。
+
+`apps/web` 中对字段和按钮的中文名称属于业务文案。图谱名称来自 `cage.config.json` 的 `graph.labels`，比如 `command:PurchaseOrder.submit` 对应“提交审批”。替换业务时别忘了更新这些名称，不要改英文能力标识来做翻译。
+
+导出按钮是调用通用异步接口的一个例子；框架不规定所有业务都要放相同的按钮。导入、导出、任务列表与错误报告应按客户页面需要接入，参考[开发步骤](workflow.md)中的客户端方法。
+
+## 把示例改成自己的业务
+
+先按[目录规范](project-structure.md)新增自己的领域模块和前端模块，完成一条完整链路，再逐步移除不需要的采购导出、路由、反应、连接器和页面引用。`@app/domain`、`@app/contracts` 是应用内包名，可以保留；npm 框架包也不需要重命名。
+
+若数据库尚未投入使用，可为新应用审查和规划初始结构；只要迁移已执行或已发布，就不能通过覆盖 `0001_init.sql` 来假装采购表从未存在。用新迁移表达后续变更，并明确已有数据处理方式。
+
+## 本例可以证明和不能证明的事
+
+它演示了真实 PG 上的命令与安全读侧、审批结论约束、同事务建锁、异步释放、连接器 fake 和签名回调。`Inventory.available` 是演示台账数量，尚未实现多订单并发扣减、实物出入库和退货核算；fake ERP 不证明第三方生产联调完成。
+
+扩展业务时把这些边界写进实现说明，补必要的业务规则与有意义的回归用例，而不是直接给范例换标题后声称生产需求已经全部覆盖。

package/templates/app/docs/ai/recipes.md

@@ -0,0 +1,81 @@
+# 业务任务配方
+
+[返回学习入口](README.md) · [原语示例](primitives.md) · [开发步骤](workflow.md)
+
+本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
+
+## 先把需求落到一张业务表
+
+开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
+
+| 业务问题 | 落到什么声明 | 例如 |
+| --- | --- | --- |
+| 管理什么对象？有哪些字段？ | aggregate、字段与 Zod 输入 | 报销单：金额、事由、部门、提单人、明细 |
+| 有哪些阶段？谁能做什么？ | states、command、invokedBy | 草稿可编辑、提交后审批、完成后不可撤回 |
+| 数据属于谁/哪个部门？ | 范围字段 + 角色数据范围 | 申请人看本人，经理看部门及下级 |
+| 每次操作有什么硬规则？ | constraints、invariants、fail | 提单人不可审批、额度上限、金额必须为正 |
+| 成功后还要发生什么？ | event、reaction、approval、outbound | 启动审批、登记额度占用、推送财务系统 |
+| 取消/失败要撤销什么？ | cancelOn、释放命令、补偿流程 | 取消待办、释放占用、远端撤销或人工补偿 |
+| 页面需要看什么？ | 生成的 list/get、query、业务页面 | 分页、详情、按状态汇总、导出与导入 |
+
+## 新增一个普通管理对象
+
+按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
+
+从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、表单和操作按钮，经模块公开入口接入 app。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
+
+完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
+
+## 增加一对多或多对多
+
+参考[对象关系](relations.md)，在聚合的同一个 fields 中添加 `hasMany/manyToMany`。纯关联交给框架生成中间表；关系本身有职位、状态等业务属性时再建立有意义的聚合。hasMany 反查目标上的 ref，修改归属执行子对象命令；manyToMany 用所属对象的命令返回 ID 数组。
+
+生成后前端通过 `对象.related.字段(id, params)` 或 `use对象Related字段` 分页读取，不从普通 get 响应猜测已加载关联。给角色配置两侧 read 能力与范围；添加成员时也检查目标可见性。修改关系执行版本检查，不能把当前一页当作完整集合替换。不要创建新的业务连接池、ORM 中间实体或手写关系路由。
+
+## 给业务单据加审批
+
+1. 为单据补草稿、待审批、通过、驳回等真实状态及命令；提交时发事件。
+2. 通过/驳回使用 process 命令，根据业务添加职责分离、额度等约束。
+3. 添加 approval 绑定和 route；只将需要的字段放进 routable，取消命令发事件并配置 cancelOn。
+4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
+5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
+
+完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。任意流程设计器、动态 JS 选人、转签/加签不属于当前现成能力，需要明确扩展范围。
+
+## 增加报表或复杂列表
+
+普通分页和详情先使用生成的 list/get；汇总、联表等需求再添加 query。写清 reads、输入 schema，选择参数化 SQL 或 build；只查对应 safe 视图，不为“报表方便”切到管理员连接。
+
+重新生成后使用 `queries.你的查询()` 或生成 hook。检查真实调用人的 read 能力和数据范围；管理员能看到结果不能证明普通用户的报表正确。
+
+## 接入外部系统
+
+沿 `packages/domain/src/integrations/erp.ts` 的结构声明 host、密钥名、操作 schema、outbound 和 inbound。远端成功后的字段回写也走 external 命令。先用 fake 完成本地链路，再在测试环境做真实联调。
+
+明确重复请求如何识别、哪些错误重试、回执晚到怎么办、取消后如何补偿。不要假设本地事务可以回滚已经提交给第三方的写入。
+
+## 增加导入或导出
+
+在客户实际需要的业务页调用客户端/生成契约，展示任务进行中、完成和失败。导入映射到用户可调用的命令，准备与该命令输入匹配的 CSV；不要生成直接写业务表的上传接口。
+
+明确逐行还是整批原子模式、失败报告如何呈现、任务过期如何处理。任务提交成功不能立即标成导入/导出完成，worker 与下载时授权也是链路的一部分。完整方法、CSV 例子与协议见[业务页导入导出](transfers.md)。
+
+## 由采购演示换成客户业务
+
+空白模板不需要清理采购业务，直接从 `packages/domain/src` 新增自己的声明和页面；参考源码在 `docs/examples/purchase-admin`，不在运行入口中。下面的替换步骤只适用于采购模板。
+
+建议先保留运行薄壳和一条可验证的演示链路，新增真实业务并接通页面，再移除不需要的演示引用。清理时沿领域导出、反应、审批、连接器、查询、任务、页面和 graph.labels 一起检查，避免残留仍在运行的自动任务。
+
+组织模型仍从 `@yss123/cage-admin/domain` 导出。已执行迁移作为历史保留，新表/删表通过新迁移表达；需要保存旧数据时先制定迁移方案，不能只把整个 migrations 文件夹删除。
+
+## 给编程工具的任务模板
+
+```text
+阅读当前项目 AGENTS.md，按 docs/ai/README.md 找到本次需求对应的原语和标准范例。
+遵守 docs/ai/project-structure.md：领域和前端按业务建 modules，app 组合页面，shared 只放通用代码，不平铺 src 或堆进 main.tsx。
+业务：……；角色与数据范围：……；状态与允许动作：……；审批/外部系统/资源占用：……。
+先列出需要修改的 domain、页面、契约、迁移和授权，再直接完成实现。
+使用当前公开 API；对无法表达的需求说明具体缺口，不编造方法。
+生成文件通过 cage gen 更新，数据库使用已有 .env 配置，按改动完成必要验证。
+交付时说明用户如何体验、管理员需配置什么，以及通过/跳过/未执行的检查。
+```

package/templates/app/docs/ai/relations.md

@@ -0,0 +1,160 @@
+# 业务对象之间的关系
+
+[返回学习入口](README.md) · [最小业务](primitives.md) · [开发步骤](workflow.md)
+
+关系和普通属性统一写在 `aggregate(...).fields` 中。业务不需要另写 `relations` 区块，也不用为单纯“便笺与用户的关联”创建 `NoteMember` 聚合。
+
+## 选择哪一种声明
+
+| 业务含义 | fields 中的写法 | 数据库如何保存 | 如何修改 |
+| --- | --- | --- | --- |
+| 多条便笺属于同一部门（多对一） | `deptId: ref('Dept')` | 本表 UUID 外键列 | 所属对象的命令 |
+| 一个目标在租户内最多被引用一次（至多一对一） | `reviewerId: ref('User').unique().optional()` | 外键列 + `(tenant_id, reviewer_id)` 唯一索引 | 所属对象的命令；重复引用返回 CONFLICT |
+| 一条便笺有多条评论（一对多） | `comments: hasMany('NoteComment', { mappedBy: 'noteId' })` | 外键在评论表的 `noteId: ref('Note')` 上；父表不增加列 | 评论自己的创建/归属命令；父字段只读 |
+| 便笺有多个协作人，一个人也能协作多条便笺（多对多） | `members: manyToMany('User', { description: '协作成员' })` | 框架生成中间表、同租户复合外键和组合主键 | 所属便笺的命令返回目标 ID 数组 |
+| 一张单据内的 JSON 明细 | `items: list({ sku: text(), qty: int() })` | 主表 JSONB 列 | 所属对象的命令；它不是对象关联 |
+
+`ref().unique()` 表达“至多一个”，不强制目标一定被引用，也不自动创建目标。多对一的每个来源只有一个外键，但多个来源可以填同一目标 ID。一对多需要目标本来就是有业务含义的对象，例如评论、订单行；这种业务对象有自己的字段和命令。
+
+`hasMany` 和 `manyToMany` 是集合关系，不支持 `.optional()`、`.unique()`、`.hidden()` 或 `.sensitive()`。没有关联使用空集合；目标对象的敏感属性由目标自身的权限掩码。可以使用 `.describe()`，也可以在工厂选项中写 `description`。关系不能嵌进 `list`、事件载荷或作为 scope 的部门/创建人字段；事件需要 ID 数组时使用 `list(id())`。
+
+## 完整领域例子
+
+下面可作为 `packages/domain/src/modules/note/note.ts`。它是[最小便笺](primitives.md)的关系版本，按需要替换原文件，避免重复声明 Note。
+
+```ts
+import {
+  aggregate, command, fail, hasMany, manyToMany, ref, scope, states, text,
+} from '@yss123/cage-kernel';
+import { z } from 'zod';
+
+export const Note = aggregate('Note', {
+  description: '部门便笺',
+  fields: {
+    title: text(120),
+    deptId: ref('Dept'),
+    createdBy: ref('User'),
+    // 这是 ID 集合。框架负责物理中间表、约束、关联写入和事务。
+    members: manyToMany('User', { description: '协作成员' }),
+    // 从评论上的 noteId 反查；这不是一份可写的评论 ID 数组。
+    comments: hasMany('NoteComment', { mappedBy: 'noteId', description: '便笺评论' }),
+  },
+  states: states('active', 'archived', { terminal: ['archived'] }),
+  scope: scope.deptSubtree('deptId'),
+  invariants: { titleNotBlank: (note) => note.title.trim().length > 0 },
+});
+
+export const NoteComment = aggregate('NoteComment', {
+  description: '便笺评论',
+  fields: {
+    noteId: ref('Note'),
+    body: text(2000),
+    deptId: ref('Dept'),
+    createdBy: ref('User'),
+  },
+  scope: scope.deptSubtree('deptId'),
+});
+
+export const createNote = command(Note, {
+  name: 'create', from: 'new', to: 'active',
+  input: z.object({
+    title: z.string().trim().min(1).max(120),
+    members: z.array(z.string().uuid()).optional(),
+  }),
+  // members 不传时由内核初始化为 []；部门与创建人仍按当前身份填入。
+  handler: (draft) => draft,
+});
+
+export const setNoteMembers = command(Note, {
+  name: 'setMembers', from: 'active', to: null,
+  input: z.object({ id: z.string().uuid(), members: z.array(z.string().uuid()) }),
+  // 完整替换集合；[] 表示全部解绑。只改关系也会递增便笺版本并写审计。
+  handler: (_draft, input) => ({ members: input.members }),
+});
+
+export const addNoteMembers = command(Note, {
+  name: 'addMembers', from: 'active', to: null,
+  input: z.object({ id: z.string().uuid(), memberIds: z.array(z.string().uuid()) }),
+  // 草稿包含完整的既有关联。增量追加可以保留当前操作者看不到的旧成员。
+  // 数组去重与排序由框架统一处理，业务不再维护第二套集合规范化。
+  handler: (draft, input) => ({ members: [...draft.members, ...input.memberIds] }),
+});
+
+export const createNoteComment = command(NoteComment, {
+  name: 'create', from: 'new', to: 'active', reads: { notes: Note },
+  input: z.object({ noteId: z.string().uuid(), body: z.string().trim().min(1).max(2000) }),
+  handler: async (_draft, input, { notes }) => {
+    const note = await notes.get(input.noteId);
+    if (!note) return fail('NOTE_NOT_AVAILABLE');
+    if (note.status !== 'active') return fail('NOTE_ARCHIVED');
+    // 这是“评论沿用便笺部门”的业务规则，必须显式表达，框架不猜测所属关系。
+    return { noteId: note.id, body: input.body, deptId: note.deptId };
+  },
+});
+```
+
+在 `modules/note/index.ts` 写 `export * from './note.js';`，再从 domain 的 `index.ts` 保留组织模型及已有模块，导出新模块：
+
+```ts
+export * from '@yss123/cage-admin/domain';
+export * from './modules/note/index.js';
+```
+
+不写双向对象导入时，可用目标聚合名字符串解决循环引用。`mappedBy` 填**目标字段的 TypeScript 名称**，例如 `noteId`；不能填 SQL 列名 `note_id`、目标表名或普通文本字段。目标 ref 需要公开且非敏感，关系接口才能通过目标安全视图反查。
+
+## 页面如何使用
+
+`pnpm gen` 后，生成契约会有以下方法。命令与列表方法的结果仍是 `CageResult`，页面按 `ok/code/domainCode` 处理：
+
+```ts
+import {
+  note, noteComment, useNoteRelatedMembers, useNoteRelatedComments,
+} from '@app/contracts';
+
+// 命令修改关系，第三个参数为详情上看到的版本号，过期版本返回 CONFLICT。
+const changed = await note.setMembers(noteId, { members: selectedUserIds }, version);
+// 目标是评论对象，不给 hasMany 赋值。
+const comment = await noteComment.create({ noteId, body: '已确认需求' });
+
+// 与普通列表一样支持目标字段筛选、分页、排序，单页最多 200 条。
+const members = await note.related.members(noteId, { page: 1, pageSize: 20 });
+const comments = await note.related.comments(noteId, { page: 1, sort: '-createdAt' });
+
+// React 组件内使用；没有选中 ID 时 hook 不发请求。
+const memberQuery = useNoteRelatedMembers(noteId, { page: 1 });
+const commentQuery = useNoteRelatedComments(noteId, { page: 1 });
+```
+
+上面的 `noteId/selectedUserIds/version` 来自页面的实际选择与详情数据；hook 在 React 组件或自定义 hook 内调用。保存成功后让相关缓存失效，例如 `queryClient.invalidateQueries({ queryKey: ['note', noteId] })`；新增评论还应更新评论列表。框架不自动推断所有跨对象缓存依赖。
+
+自动接口为：
+
+```text
+GET /api/note/:id/relations/members
+GET /api/note/:id/relations/comments
+```
+
+响应是 `{ items, total, page, pageSize }`，items 为**目标对象**的普通快照。`note.get/list` 和命令响应不自动展开成员、评论或完整 ID 集合，避免普通详情无限加载与绕过目标权限。生成的普通 Note 类型也不包含虚拟关系；不能从 `note.get()` 中直接读取 `members`。
+
+## 权限与事务
+
+- 修改成员需要 `Note.setMembers` 或对应增量命令能力，以及便笺范围。新增的用户还必须在调用人的 User 范围内，真人调用需要 `User.read`；范围外或其他租户目标返回 NOT_FOUND，缺能力返回 FORBIDDEN。
+- 读取成员需要 `Note.read` 和 `User.read`；读取评论需要 `Note.read` 和 `NoteComment.read`。所属对象不可见返回 NOT_FOUND；目标范围外的数据不计入 items/total。目标敏感字段按其 unmask 能力返回掩码或明文。
+- 角色需要分别配置 Note、NoteComment 和 User 的实际数据范围；`hasMany` 不会自动让父对象可见的人看到所有子对象，关系声明本身也不会授予能力。
+- 多对多是无序集合。框架统一 UUID 大小写、去重和排序；关联表不保存排列顺序。主表版本、关系增删、审计、outbox 和同事务反应共同提交或回滚。
+- 只校验本次新增的目标。某个旧成员后来变为不可见时，只修改标题仍保留其关联；公开分页只返回当前可见目标。页面不能把某一页或可见子集当作完整集合传给 setMembers，否则会解绑未列出的成员；需要保留时使用增量命令。
+- `hasMany` 不出现在可写草稿中。输入或 handler 给它赋值会返回 INVALID_INPUT。子对象跨范围或跨租户归属的业务规则要在子命令/约束中明确校验；普通 ref 的行为保持不变，不会继承 manyToMany 的新增目标可见性检查。
+
+## 迁移、图谱与边界
+
+第一次声明 `members` 后执行 `pnpm gen`，会生成 `core.note__members` 草稿。表只保存 `tenant_id/source_id/target_id`，以三列组合主键避免重复；两侧 `(tenant_id, id)` 唯一键与复合外键保证同租户。解绑只删链接，不删除 User；硬删除来源时数据库级联清链接，硬删除被引用目标时外键拒绝。
+
+关系表不注册为业务聚合，不增加独立 CRUD、状态机、审批或角色能力点。`hasMany` 本身不产生新表，只复用目标 ref 已有外键与索引。权限读取通过 `safe.note__members` 和两侧安全视图；业务项目不直接写这些表。
+
+按项目流程运行 `pnpm exec cage check`、`pnpm gen`，审查后 `pnpm migrate`；不要编辑已执行迁移，不会为关系另建一个数据库。删除关系声明后迁移只提示收缩，不自动删除已有链接数据。改变目标类型、把旧 JSON 数组改为关系等操作需要专门的数据迁移；框架不会猜测如何转换历史数据。
+
+`pnpm exec cage graph` 的对象卡片将它们标为“一对多 / 多对多”，集合关系不显示主表列的必填星号。点击连线可看 1:N、N:M、mappedBy 外键位置、中间表名称，以及为什么连接、读写方式。
+
+当前每个 `manyToMany` 字段拥有自己的关系。两边各写一次会生成**两份独立关联**，不会自动成为互为镜像的双向关系；本版没有 manyToMany 的 inverse/mappedBy 选项。需要反向统计时声明 query，列出双方 reads 并查询安全视图。自关联可写 `manyToMany('Note')`，仍是有方向的集合，A 关联 B 不会自动使 B 关联 A。
+
+如果链接本身有职位、参与时间、分摊比例、审批状态等业务属性，它已是有意义的业务对象，应建如“项目任职”的聚合并定义自己的命令，而不是把这些属性塞进自动中间表。关系字段的职责是表达单纯关联。

package/templates/app/docs/ai/transfers.md

@@ -0,0 +1,92 @@
+# 在客户业务页接入导入和导出
+
+[返回学习入口](README.md) · [开发步骤](workflow.md)
+
+框架提供持久化任务、CSV 处理、权限和下载接口。业务项目决定入口、列名、上传表单、任务状态与报告如何展示；不要求用户进入系统管理页，也不要求具备 Sys.ops 能力。路径中的 `/api/sys/transfers` 是通用任务接口。
+
+继续使用项目已有的 createServer 和 startWorker，不另写数据库连接、队列或文件服务。先审查并运行 `pnpm migrate`，同时部署 API 与 worker；只运行 API 会让任务一直等待。
+
+## 业务前端如何调用
+
+以下是业务事件处理函数，可按页面需要使用。目标导出对象与导入命令来自实际业务，不必固定为采购或库存。
+
+```ts
+import { client, purchaseOrder } from '@app/contracts';
+
+export async function exportApprovedOrders() {
+  // 同一次业务操作需要重试时，在页面保存并复用 key。
+  const key = crypto.randomUUID();
+  return purchaseOrder.export({ status: 'approved' }, { idempotencyKey: key });
+}
+
+export async function importCommandCsv(command: string, file: File, key: string) {
+  return client.importCsv(command, await file.text(), {
+    atomic: false,
+    idempotencyKey: key,
+  });
+}
+
+export async function inspectTransfer(id: string) {
+  const result = await client.transfer(id);
+  if (!result.ok) return result;
+  if (result.data.status !== 'completed') return result;
+  // 导入完成还可能有失败行，页面需展示报告中的 failed/succeeded。
+  if (result.data.kind === 'import') return client.importReport(id);
+  return client.transferDownloadUrl(id);
+}
+```
+
+所有提交先判断 `result.ok`，再保存返回任务的 id，HTTP 202 仅表示已接受。React 可从 `@app/contracts` 引入 `useTransfer(id)`：等待、处理中和重试中每两秒刷新，完成/失败/过期停止。没有 React 时自行调用 client.transfer。
+
+页面返回时可用 `client.transfers('实际聚合名')` 恢复本人该对象最近任务。任务状态包括 queued、processing、retrying、completed、failed、expired；completed 的导入也可能部分失败或整批回滚，不能只按状态显示“全部成功”。
+
+## 导入 CSV 怎么准备
+
+目标命令必须已经导出、允许 user 调用、使用 Zod object 输入，并且当前用户具有对应命令能力。比如业务输入 `{ sku: string, available: number }` 的 UTF-8 CSV：
+
+```csv
+sku,available
+SKU-001,100
+SKU-002,50
+```
+
+- 表头是**命令输入字段名**，使用小驼峰，不是数据库列名或中文标题。页面可自行做中文列名映射。
+- 可选列可省略；空的可选单元格表示不提供值。已有记录命令需要 id，还可提供 expectedVersion 控制乐观锁。
+- 数字按数字解析，布尔使用 true/false，数组与对象写 JSON，金额按字符串输入。
+- 复杂单元格仍要遵守 CSV 引号规则，例如 items 单元格可以是 `"[{""sku"":""A-01"",""qty"":1}]"`。
+- 支持 BOM、CRLF、引号中的逗号/换行及双引号转义。重复/未知表头、错列和未闭合引号等文件错误会在排队前拒绝。
+- 每行仍走原命令的权限、范围、状态、约束、不变量、审计、事件与同事务反应；导入不能绕过 process/external 限制。
+
+默认 `atomic: false`：成功行提交，失败行及其同事务反应回滚。`atomic: true`：任意行失败撤销整批业务写入，原成功行在报告中标为 ABORTED。
+
+报告只含记录号、ok/code/domainCode/fields，不返回原始值或命令快照。表头算第 1 条，第一条数据记录为第 2 条；带换行的引号单元格仍只算一条记录。页面用记录号帮助用户修复 CSV，不把失败文本直接拼成 HTML。
+
+**导出文件不是导入模板。** 读侧导出包含 id/status/version 等系统列及掩码值，不能原样回写；按所选命令整理输入。
+
+## 接口与授权
+
+| HTTP | 输入或结果 |
+| --- | --- |
+| POST `/api/{聚合短横线名}/export` | 列表筛选参数；返回 202 和任务，需要该聚合 export 能力 |
+| POST `/api/sys/transfers/import` | `{ command, csv, atomic? }`，command 是 `聚合.命令` 能力标识；返回 202 和任务 |
+| GET `/api/sys/transfers/options` | 本人可用的导出对象、导入命令、字段 name/required 与限制 |
+| GET `/api/sys/transfers?aggregate=聚合名` | 本人最近 100 个任务，按需筛选业务对象 |
+| GET `/api/sys/transfers/:id` | 本人单个任务的状态、计数及 errorCode |
+| GET `/api/sys/transfers/:id/download` | 已完成导出的 CSV，或已完成导入的 JSON 报告 |
+
+options 可用 `client.get('/api/sys/transfers/options')` 读取，没有额外假定的专用 helper。直接调用 HTTP 时，提交必须附会话、CSRF 以及 1–200 字符 Idempotency-Key；client 会处理这些协议。相同租户/用户的同键同内容返回同一任务，同键不同内容返回 CONFLICT。
+
+导出经过安全视图，按提交人的范围和明文权限读取。仅提交人能下载；账号停用、能力收回或范围/明文权限/部门树变化后，旧文件可能被拒绝下载，需要重新导出。系统运维权限不会自动授予他人的文件下载权。
+
+## 限制与排错
+
+| 项目 | 当前限制 |
+| --- | --- |
+| 导入 | UTF-8 CSV，1 MiB / 1000 条数据记录 |
+| 导出 | 100000 行 / 20 MiB；超限任务失败，不静默截断 |
+| 导出分页参数 | page/pageSize 不限制导出范围；使用业务筛选条件缩小数据 |
+| 有效期 | 提交起 24 小时，到期拒绝下载，由 worker 清理文件和结果 |
+| 存储 | PostgreSQL 持久化，API 与 worker 不需要共享磁盘 |
+| 暂未提供 | XLSX、对象存储、断点续传、逐行实时进度、超大文件流式导入 |
+
+任务一直 queued 先查 worker；failed 看 errorCode/导入报告；数据库故障耗尽重试时查原有死信链路。先修复根因再重放，别创建直接写业务表的“快速导入”接口。

package/templates/app/docs/ai/troubleshooting.md

@@ -0,0 +1,60 @@
+# 排错方法
+
+[返回学习入口](README.md) · [错误码册](../errors/README.md) · [HTTP 运行时错误](../errors/runtime.md)
+
+先保留完整诊断的 code、源码位置、reason/fix、requestId 或 outboxId。检查所在阶段，再修复原因；不要通过改业务状态、给全局权限、注释约束或禁用 lint 消除现象。
+
+## 按现象定位
+
+| 现象 | 先查什么 | 常见原因 |
+| --- | --- | --- |
+| dev 启不动 | `.env` 是否在项目根目录，数据库服务是否可连接 | 缺连接、密码/端口错误、没执行迁移、端口占用 |
+| init 提示账号已存在 | CAGE-INIT-002；找已有 APP/READ/MIGRATE 连接 | 角色在 PG 集群内共享；不应覆盖原密码 |
+| 新业务不出现在接口/图谱 | 顶层 export const 和 domain/index.ts | 漏导出、重名导出、放进函数/条件声明 |
+| API 403 | code/detail、角色能力、调用身份、硬约束 | 能力不足、CSRF、职责分离、额度缺失/超限 |
+| 详情 404 | 记录 id、租户和数据范围 | 不存在或在范围外；不能仅凭 404 断言被删除 |
+| 列表为空 | read 能力、范围与相应字段 | 默认本人范围、无 owner 字段或部门不匹配 |
+| 电话看不到明文 | sensitive 标注、unmask 能力 | 默认掩码是正常安全行为 |
+| 提交成功但无待办 | worker、outbox/死信、审批路由 | 未投递、缺审批人、没有匹配的绑定/路由 |
+| 已批准但 ERP 单号未回写 | worker、同步记录、死信、环境/fake | 密钥/白名单/响应错误，或异步还未完成 |
+| 已取消但锁未释放 | 释放事件、反应、死信 | 先前消息阻塞、map 条件不匹配或遗漏释放 |
+| 导入/导出一直 queued | worker 与任务详情 | 后台进程未启动或前序任务失败 |
+| gen --check 失败 | CAGE-GEN-001/002 | 声明修改未生成、手改契约、迁移快照不一致 |
+
+## CAGE-APPR-007：找不到审批人
+
+先读所属领域模块 `approvals.ts` 的实际步骤（采购范例为 `packages/domain/src/modules/purchase/approvals.ts`），按选人器处理：
+
+| 选人器 | 配置位置 | 常见误解 |
+| --- | --- | --- |
+| `approver.deptLeader('deptId')` | 单据 deptId 指向的部门，在 `/admin` 设置负责人 | 给用户经理角色不等于给部门设置负责人 |
+| `approver.role('finance')` | 创建 code 为 finance 的角色，并给实际用户分配 | 选人看角色 code，不是中文显示名称 |
+| `approver.user(id)` | 使用存在的用户 UUID，核对业务可用性 | 把用户名或角色名当成 UUID |
+
+选人成功后，再检查此人所需能力、数据范围、额度。示例中提单人不能审批自己，经理的 `PurchaseOrder.approve` 必须有 ceiling 参数。
+
+若事件已进入死信，在 `/admin` 查看对应 outboxId 的错误并修正配置，再点击重放。原 submit 通常已提交，单据处于 pending_approval；不要重复提交，更不要直接 SQL 改回 draft。重放后确认待办及后续事件，不把“点击重放成功”当成整条链路已经完成。
+
+## CAGE-PAIR-002：新增操作遗漏释放
+
+查看报错命令是否离开持有资源的状态，沿 `命令 → emits 事件 → reaction → releases 资源` 检查。补业务事件与真正的释放命令，声明相同资源标签，并确认 map 在这条路径能执行。
+
+不要只加一个不执行的反应骗过图规则，也不要删 acquires 标签。图规则检查结构，业务测试还要覆盖关键条件分支。
+
+## 数据库错误应提供什么信息
+
+提供发生于 init/migrate/API/worker 哪一步、主机/端口/库名、使用哪个角色、PostgreSQL 错误码、是否有待执行迁移。URL 中密码特殊字符需编码；修改环境变量后重启进程。
+
+- 连接拒绝：检查数据库服务、主机端口和容器端口映射。
+- 认证失败（如 28P01）：核对对应角色密码；不重置其他项目共享角色。
+- 无权限：核对当前账号职责；读账号不能用来执行迁移，业务进程不应改成管理员连接。
+- 表/视图不存在：审查后执行 migrate，确认连接的是同一个数据库。
+- 已执行迁移校验和不符：恢复原文件，新增迁移；不要改 sys.schema_migrations 的 checksum。
+
+不要贴出整个 `.env`、初始化凭证文件、Cookie 密钥或恢复文件内容。管理员连接只用于准备权限，日常业务继续使用独立账号。
+
+## 如何说明没有验证的部分
+
+报告构建/检查通过的命令，另列跳过和未执行的检查及原因。fake 成功、图规则通过、HTTP 202、无权限用户看不到按钮，都不能单独证明真实第三方、任务完成或后端权限正确。
+
+错误码册中的例子用于解释局部规则；完整业务代码以当前项目 domain 和生成 contracts 为准。错误来自内部源码时，手册给出路径和位置；独立项目无需把内部源码复制进来修补，应先修自己的声明/配置或明确报告框架缺口。