@yss123/cage-cli 0.1.0 → 0.3.0

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/routing.md

@@ -0,0 +1,86 @@
+# 业务前端路由与浏览器验收
+
+[返回学习入口](README.md) · [工程目录](project-structure.md) · [开发步骤](workflow.md)
+
+多页面业务默认使用 React Router 的 BrowserRouter。列表、详情、报表等可独立访问的页面必须有 URL；在 app 中统一组合路由和工作台布局，页面从模块 index.ts 导出。useState 用于弹窗、未提交表单和按钮忙碌状态。筛选、分页和需要分享的选项使用 useSearchParams。
+
+本页对应后续开发版本的模板改进；已发布的 0.2.0 项目需要按本页迁入路由实现，不能只升级依赖就认为旧页面已完成改造。框架包无需维护客户的页面地址。
+
+## 模板中的可运行示例
+
+| 页面 | 空白模板 | 采购模板 |
+| --- | --- | --- |
+| 登录 | `/login` | `/login` |
+| 工作台 | `/workspace` | `/workspace` |
+| 列表 | `/directory/users?page=2` | `/procurement/orders?status=draft&page=2` |
+| 详情 | `/directory/users/:id` | `/procurement/orders/:id` |
+| 其他业务 | 按实际需求新增 | `/inventory`、`/approvals` |
+| 404 | 未匹配页面显示“页面不存在” | 同左 |
+
+`:id` 替换成真实记录 ID。空白模板的成员目录读取已有 User 组织模型，不注册额外业务、演示表或虚假数据；列表与详情均需要 User.read，数据范围由安全接口落实。采购待办的 businessKey 由 app 映射成采购详情链接，审批模块不直接导入采购模块。
+
+在应用根目录运行 pnpm dev 后访问终端打印的 Web 地址。先在系统管理配置真实账号与权限，再从列表复制某条记录的详情 URL，用于刷新和新标签页测试。
+
+## 新增一项业务页面
+
+1. 在 `apps/web/src/modules/<业务>/pages` 编写列表、详情和表单，从模块 index.ts 导出。详情用 useParams 读取 ID，再用生成的 use对象(id) 获取记录；不要求先打开列表，也不从组件状态或上一页传来的对象直接认定记录存在。
+2. 在 `apps/web/src/app/app.tsx` 注册列表与详情 Route。放在已有会话守卫和 WorkspaceLayout 之下，使页面通过 Outlet 渲染。新增实际页面时扩展路由表；不要再添加 tab/page useState 来选择整页。
+3. 导航使用 Link / NavLink；完整页面地址可收藏、复制或新标签页打开。列表筛选和分页通过 useSearchParams 更新，刷新和前进后退恢复相应查询。
+4. 需要 read 能力的页面用共享 RequireCapability 提供直接访问时的提示；服务端返回 FORBIDDEN 时显示权限提示，NOT_FOUND 显示“记录不存在，或不在当前可访问范围”。401 由会话回调进入登录。不要把 403 当成登录失效，也不要通过放宽读权限解决页面导航问题。
+5. 用下面的浏览器配方验收，并报告通过、跳过与未执行。构建和 cage verify 通过，只证明其各自检查范围，不能据此宣称路由体验正确。
+
+```tsx
+// app 中的组合片段：页面通过所属模块的 index.ts 导出。
+<Route element={<WorkspaceLayout onLogout={onLogout} />}>
+  <Route path="procurement/orders" element={<PurchaseOrdersPage />} />
+  <Route path="procurement/orders/:id" element={<PurchaseOrderDetailPage />} />
+</Route>
+```
+
+片段只展示路由与布局关系。实际代码参考本模板 app.tsx，保留会话守卫、页面 props 和能力提示。`cage/no-manual-routes` 限制手写后端业务 HTTP 路由，不禁止 React Router；前端导航不会生成能力或授予数据访问权。
+
+## 登录后返回原地址
+
+应用启动先 loadMe 恢复会话。未登录访问详情时，守卫使用 replace 导航到 `/login?returnTo=编码后的原路径`，包含 query 和 hash。登录完成再次 replace 回原页面，避免浏览器后退反复落入登录页。
+
+`shared/lib/navigation.ts` 的 loginReturnTo 只接受应用内页面，排除外站、登录循环及 API/admin 等服务端入口；不要直接把用户提供的任意 returnTo 交给 location.href。网络错误显示重试界面并保留地址，只有 UNAUTHENTICATED 才要求重新登录。运行中会话过期同样保存当前 URL，并清除上一账号的查询缓存。
+
+前端路由守卫只改善导航与提示。请求仍由 Cage HTTP 和内核检查会话、能力、租户、数据范围与掩码；直接请求接口必须得到相同约束。
+
+## 与系统管理及部署共存
+
+| 路径 | 所有者 |
+| --- | --- |
+| `/login`、`/workspace`、客户业务页面 | React Router |
+| `/admin`、`/admin/` 及其脚本/样式 | Cage 系统管理 |
+| `/api/`、`/auth/`、`/hooks/` | Cage HTTP 接口 |
+| `/assets/` | Vite 构建资源 |
+
+进入 `/admin/` 使用普通 `<a href="/admin/">`，让浏览器请求独立管理入口；应用内部页面使用 Link。不要在 React 中注册覆盖 /admin 或 /auth 的页面。Vite 配置已代理 API、认证与管理请求，开发环境支持业务深链接刷新。
+
+生产可选两种部署方式：
+
+- **Cage 托管 Web**：API 启动时提供 webDir，标准入口读取 WEB_DIR；将其设置为 apps/web/dist 的绝对路径。模板 Dockerfile 已复制构建产物并设置 WEB_DIR=/app/web。浏览器 GET/HEAD 页面请求可回退到 index.html，React 决定详情或 404；API、管理和丢失资源返回各自错误，不应变成业务首页。
+- **Nginx 托管 Web**：参考项目 `deploy/nginx.conf`，将 root 指向真实 dist，将 API/admin/auth/hooks 代理到 Cage；业务页面使用 try_files 回退到 index.html，/assets/ 缺失时直接 404。示例按 Nginx 与 API 在同一主机、API 端口 3000 编写；按部署拓扑修改上游。仅复制 dist 到没有 SPA 回退的静态服务器会导致详情刷新 404。
+
+上线前用实际反向代理地址验收深链接。Vite 开发环境成功，不代表 Nginx、CDN 或生产容器已配置正确。
+
+## 浏览器验收配方
+
+准备一条有权读取的真实记录和两个测试账号：有 read 能力及范围的账号、没有该能力的账号。测试账号和记录在独立验收环境准备，不修改生产角色。
+
+| 操作 | 预期结果 |
+| --- | --- |
+| 复制列表中某条详情 URL，在新标签页粘贴 | 直接加载对应记录，无需先访问列表 |
+| 在详情页刷新 | URL 和记录保持一致 |
+| 列表 → 详情 → 另一页面，再点浏览器后退、前进 | 地址、页面内容与导航高亮同步变化 |
+| 改变列表筛选/分页，复制地址或刷新 | 条件与列表恢复，不返回工作台或第一页 |
+| 未登录打开带 query/hash 的详情 URL | 进入登录；成功后回到原 URL，保留 query/hash |
+| 在业务页使测试会话过期，再触发读取 | 进入登录；重新登录后回到原页面，旧账号缓存不残留 |
+| 无 read 能力账号直接访问有效详情地址 | 显示权限提示，直接请求 API 仍为 403 |
+| 有 read 能力但记录位于范围外 | 显示记录不可用，直接请求 API 为 404，不泄露记录是否存在 |
+| 访问不存在的业务路径 | 显示应用 404，并有返回工作台入口 |
+| 访问 /admin/，以及缺失的 API/JS/CSS | 管理入口独立可用；缺失接口或资源不返回业务 index.html |
+| 在实际部署地址重复深链接和刷新步骤 | 正常加载，浏览器控制台无脚本 MIME 错误 |
+
+验收记录写明模板、地址、操作和结果。模拟 API 的浏览器检查可以证明导航行为；真实权限、范围和数据库链路需要相应集成验收，二者分别报告。

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,65 @@
+# 排错方法
+
+[返回学习入口](README.md) · [错误码册](../errors/README.md) · [HTTP 运行时错误](../errors/runtime.md)
+
+先保留完整诊断的 code、源码位置、reason/fix、requestId 或 outboxId。检查所在阶段，再修复原因；不要通过改业务状态、给全局权限、注释约束或禁用 lint 消除现象。
+
+先执行 `pnpm exec cage doctor` 查看各阶段证据；异步动作按 requestId/outboxId/业务对象用 `cage timeline` 关联实际执行记录。能力、范围、调用身份或额度不清楚时，有权诊断的管理员可使用 `cage explain`，不会执行目标命令。完整参数与权限见[诊断指南](diagnostics.md)。
+
+## 按现象定位
+
+| 现象 | 先查什么 | 常见原因 |
+| --- | --- | --- |
+| 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 能力 | 默认掩码是正常安全行为 |
+| 有明文能力但读取报 CAGE-AUDIT-001 | requestId、审计库可用性与权限 | 可靠审计未成功，框架拒绝交付结果 |
+| 生产服务拒绝启动 | CAGE-ENV-002/003、Cookie 密钥与 bootstrap 参数 | 关键配置不合格，或试图在日常启动时隐式初始化 |
+| 任务时间线有 CAGE-WORKER-002 | API/worker 版本、注册指纹和消费者清单 | 旧进程或必要消费者缺失，不能把 done 当作已执行 |
+| 提交成功但无待办 | 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 为准。错误来自内部源码时，手册给出路径和位置；独立项目无需把内部源码复制进来修补，应先修自己的声明/配置或明确报告框架缺口。

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

@@ -0,0 +1,152 @@
+# 开发步骤与交付要求
+
+[返回学习入口](README.md) · [范例导读](purchase-example.md) · [详细中文注释](commenting.md)
+
+本页命令在**应用根目录**执行，除非注明“框架根目录”。使用项目安装的 CLI：`pnpm exec cage ...`。项目脚本可简写为 `pnpm gen / pnpm migrate / pnpm dev / pnpm verify`；不要假定机器已全局安装 cage。
+
+## 第一次启动应用
+
+前提是 PostgreSQL 数据库已经存在。框架负责连接与表结构，不负责数据库服务的安装、建库或 Docker 生命周期。
+
+```powershell
+pnpm install
+# 仅首次复制；已有 .env 时编辑原文件，不覆盖配置。
+Copy-Item .env.example .env
+# 在 .env 填写 CAGE_ADMIN_DATABASE_URL，指向已有数据库。
+pnpm exec cage init
+pnpm build:app
+pnpm gen
+# 审查 db/migrations 中的迁移草稿，再执行：
+pnpm migrate
+# 迁移后显式初始化组织，目标是新的受限凭据文件；父目录需存在。
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
+pnpm dev
+```
+
+`init` 自动创建独立账号与随机密码，填写 APP/READ/MIGRATE 连接和 Cookie 密钥，成功后删除文件中的管理员连接。三个连接使用同一数据库。已有 Cage 集群账号时复用原连接，不能重置其他应用的账号密码。生产环境可由平台直接提供账号连接，不必执行本地 init。
+
+`bootstrap` 独立初始化组织，不自动授予业务能力。管理员凭据只进入新的受限文件，不进入服务控制台；已有用户时不重置。交付后移除凭据文件。日常 API 启动不初始化组织；生产缺少合格 Cookie 密钥会拒绝启动。具体文件权限与诊断用法见[能力发现与状态诊断](diagnostics.md)。
+
+`.env.example` 是配置说明，`.env` 是本机私密配置，二者不混用。CLI 自动加载应用 `.env`，部署环境同名变量优先。API 和 worker 启动需重启后读取变更；不要输出整个 `.env` 排障。
+
+框架仓库首次先在根目录 `pnpm install`、`pnpm build`，再进入 `examples/purchase-admin` 配置。`dev` 不自动执行迁移；生成新迁移后要审查并显式运行 migrate。
+
+## 做一项业务修改
+
+1. 读 AGENTS.md、[目录规范](project-structure.md)和[详细中文注释规范](commenting.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
+2. 涉及已存在业务含义变化时，**修改前**运行 `pnpm exec cage snapshot save before-change` 保存命名基线；也可使用真实 Git 提交或独立本体图文件。
+3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。同步编写详细中文注释：文件职责与调用链、导出声明及输入字段、权限/状态/reads/事件/事务、关键步骤和失败边界；涉及已有行为时补齐受影响的上下游说明。
+4. `pnpm exec cage check` 检查声明和图规则；`pnpm gen` 更新契约与迁移草稿。聚合和命令填写中文 `description`，需要覆盖时补 `cage.config.json` 的 `graph.labels`（如 `aggregate:Note`、`command:Note.archive`、`capability:Note.export`）。这些名称同时用于图谱和 `/admin` 授权界面；修改后重启 API。不重命名实际能力点来实现翻译。在图谱确认连接与资源生命周期。
+5. 审查数据库变更，特别是非空字段、数据回填、删列和索引。已执行的迁移不可改写。需要落库时显式 `pnpm migrate`。
+6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 的 URL 路由；依赖生成 contracts，处理失败结果。列表、详情等多页面使用 React Router，筛选和分页进入 URL；组件状态只管理页面内临时交互。新增能力由管理员授权，页面按钮可用 `useCan` 控制。按[路由与浏览器验收](routing.md)检查直达、刷新、前进后退和登录回跳。
+7. 补足重要业务反例并运行相关验证；测试解释夹具目的、所保护的规则和覆盖边界。按注释规范审查本次 diff，核对页面、组件/hooks、类型字段、脚本副作用和恢复流程的说明是否完整准确。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
+
+### 如何保存和比较基线
+
+```powershell
+# 修改前执行；同名快照不会覆盖。
+pnpm exec cage snapshot save before-change
+# 修改 domain 后执行：
+pnpm exec cage impact --snapshot before-change
+# 或与真实可用的 Git 提交比较；下面的 main 应按仓库实际情况替换。
+pnpm exec cage impact --base main
+```
+
+基线文件要保留到验收结束。影响分析用于找到相关命令、约束、审批、查询和候选测试，不能当作不需验证的证明。没有 Git 提交时不要为了让命令成功而擅自创建/推送远端。
+
+`context` 和图谱查询只返回查询结果，不更新当前图文件或命名基线；`analyze/gen` 更新当前图。快照来源时间、版本与图指纹随报告保存。
+
+## 常见需求的具体改法
+
+| 需求 | 做法 | 必查项 |
+| --- | --- | --- |
+| 增加字段 | 修改 aggregate；按命令更新 input/handler；重新生成 | 是否敏感、是否可选、旧数据如何回填、查询/事件/页面受影响吗 |
+| 增加状态或撤回 | 修改 states 和 command；声明事件及资源处理 | 可达性、非终态出边、审批 cancelOn、CAGE-PAIR-002 |
+| 修改审批 | 修改 route/approval；按需要增加 routable | 负责人/role code、步骤 mode、结论命令、额度和职责分离 |
+| 增加报表 | 声明 query 的 reads、input 和 sql/build | 安全视图、参数化、调用人 read 权限、生成 queries 契约 |
+| 接入第三方 | 声明 connector/op/outbound/inbound；配置运行环境密钥 | 请求响应白名单、幂等、超时、验签、永久/可重试错误和补偿 |
+| 改后台管理配置 | 通过组织模型与系统接口修改 | 防提权、实际授权范围、角色缓存刷新、操作人权限 |
+| 改脚手架 | 先修改标准范例，再同步模板并构建 CLI | 新目录实际创建结果、资料分发、凭证不入包 |
+
+## 前端如何消费框架
+
+```ts
+import { purchaseOrder } from '@app/contracts';
+
+// 普通业务接口使用生成的方法；第二个参数可传当前记录的 version。
+const result = await purchaseOrder.submit(order.id, order.version);
+if (!result.ok) {
+  // 按 code 展示通用原因；DOMAIN_ERROR 还可以按 domainCode 展示业务文案。
+  showError(result.domainCode ?? result.code);
+} else {
+  refreshOrder(result.data);
+}
+```
+
+这是页面事件处理片段，`order/showError/refreshOrder` 由业务页面提供。不要导入 domain 命令在浏览器执行，也不要复制后端权限逻辑。生成契约只包含允许 user 调用的写操作；审批通过通过待办接口进行，而不是自己增加 `purchaseOrder.approve()`。
+
+对自定义 HTTP 协议能力使用 `@yss123/cage-client`；它负责会话、CSRF 和类型化结果。需让多个提交共享幂等键时，按当前客户端接口显式传递同一次业务操作的 key，并在页面阻止重复进行中的提交。生成契约的方法签名以 `packages/contracts/src` 为准，不假设每个命令方法都支持自定义 options。
+
+生成方法最后的请求选项支持 `signal/timeoutMs/idempotencyKey`。底层返回 `CageResult`；`useCageCommand` 成功返回业务数据、失败抛出 `CageCommandError`，因此 mutation 的 `isSuccess` 表示业务成功。退出、401、切换账号时订阅 `client.subscribe` 取消用户查询并清除应用缓存，范例 `apps/web/src/app/use-session.ts` 展示了接法。
+
+### 导入和导出属于业务页面
+
+框架提供通用异步接口与任务查询，页面放在哪里由具体业务决定。
+
+- 导出调用生成的 `purchaseOrder.export(params, options?)` 等方法，得到任务；使用 `client.transfer(id)` 或 `useTransfer(id)` 查看进度，完成后通过 `client.transferDownloadUrl(id)` 下载。
+- 导入调用 `client.importCsv('PurchaseOrder.create', csv, { atomic: false })` 等，目标是已声明且支持用户调用的命令；每行执行命令，复用权限和业务校验。该例中的 `items` 等复杂字段需遵守实际 CSV 编码规则，不是任意 Excel 文件自动识别。
+- `atomic: true` 请求整批原子处理，普通逐行导入需展示成功/失败计数及报告。HTTP 202 仅代表接受任务，不能立即提示处理完成。
+- worker 必须运行；任务可能 queued/retrying/failed/expired。下载会再次校验当前权限。导出的系统列和掩码值不能原样回导。
+
+CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入导出](transfers.md)。给新业务做入口时按实际生成的签名调用，不硬编码采购单专属逻辑进框架。
+
+## 工具做什么，结果在哪里
+
+| 命令 | 用途 | 主要输出 |
+| --- | --- | --- |
+| `pnpm exec cage analyze` | 抽取显式声明与源码位置 | `.cage/ontology.json` |
+| `pnpm exec cage capabilities 关键词 --format json` | 查询当前安装版本的公开能力 | 公开签名、声明位置和学习入口 |
+| `pnpm exec cage doctor` | 统一核对注册、生成、构建及可用运行证据 | pass / fail / unknown 与下一步；见[诊断指南](diagnostics.md) |
+| `pnpm exec cage snapshot save 名称` | 保存不可覆盖的命名基线 | `.cage/snapshots`；配合 `impact --snapshot 名称` |
+| `pnpm exec cage check` | 静态检查、注册表与图规则 | 终端 `code/at/reason/fix` |
+| `pnpm exec cage graph` | 启动中文本体图谱 | 默认 `http://127.0.0.1:15418`，按终端地址访问 |
+| `pnpm exec cage context "需求或节点"` | 开发前取得相关子图、原因、源码与候选验证 | 默认终端 Markdown；`--format json --out .cage/context.json` 保存结构化报告 |
+| `pnpm exec cage graph search/inspect/path ...` | 检索候选 / 精确节点 / 关系路径 | 同源中文与证据；每次重新抽取，见[用法](ontology-context.md) |
+| `pnpm gen` | 更新契约、结构说明、迁移草稿 | `packages/contracts/src`、`db/migrations`、`generated`、`.cage/ontology.json` |
+| `pnpm exec cage gen --check` | 只比较需提交的生成物 | 不一致时报 CAGE-GEN；不是实际数据库漂移扫描 |
+| `pnpm exec cage test --only project` | 项目测试 | `.cage/test-results.json` 与终端 |
+| `pnpm exec cage test --only derived` | 声明派生的框架性质测试 | `generated/tests`、同一测试报告 |
+| `pnpm verify` | 汇总门禁 | `.cage/verify.json` |
+| `pnpm exec cage verify --skip-tests` | 执行测试以外的门禁 | 报告标明 `complete: false`，不可称全量通过 |
+| `pnpm exec cage sync` / `sync --check` | 同步/比较 AGENTS 托管区 | 保留标记外的项目自有规则；不自动改写业务代码或学习资料 |
+| `pnpm exec cage budget` | 体积、公共词汇和 unsafe 预算 | 终端 metrics/findings |
+| `pnpm exec cage upgrade --dry-run` | 查看当前目标 CLI 所带升级改动 | 文件修改预览；应先安装正确目标版本 CLI |
+
+`generated/` 和 `.cage/` 是可再生资料；contracts 和迁移是需要审查、提交的生成结果。生成迁移通过最后一个迁移内嵌的结构快照比较，不是创建临时数据库，也不能证明真实库从未被手工改动。
+
+## 验证要与改动匹配
+
+- 文档、文案、可逆的小改动：检查链接、格式、资料分发；不需要重复运行全套数据库测试。
+- 所有源码变更：按[注释交付清单](commenting.md#交付前逐项核对)人工核对中文职责、接口与关键流程说明；静态检查不能替代注释准确性检查。仅补注释时不新增复述实现的测试、不改写已执行迁移。
+- 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、额度边界、资源释放、同事务回滚。不要写只复述实现的测试。
+- 领域结构变化：check、gen、生成一致性、类型检查；有数据库影响时在独立测试库验证迁移和读写。
+- 页面或导航变化：构建后按[浏览器配方](routing.md)实际操作，包含深链接、新标签页、刷新、前进后退、登录回跳、无权限和 404。check/verify 不自动执行浏览器验收；未操作时明确报告未执行，不能写“页面功能完整”。
+- 发布前：按项目要求执行完整 verify/build/test，核对分发包。没有执行的项目明确写出原因。
+
+测试使用真实 PostgreSQL。`CAGE_TEST_DATABASE_URL` 供独立测试集群使用，测试工具会准备角色和临时数据库；不要指向业务/生产集群。没有设置时 testkit 可使用内嵌的真实 PostgreSQL，这与 dev 的固定已有库流程不同。
+
+派生测试无法凭空推断所有业务合法输入，会报告跳过。它们证明的是通用性质，不能代替采购 happy path、审批配置和第三方真实联调。
+
+## 可以交给 AI 的任务描述
+
+```text
+先读 AGENTS.md 和它指定的 docs/ai/README.md，再参考对应标准范例。
+需求：为某业务增加……
+先用 cage context 查询现有业务，必要时 graph inspect/path，确认候选与关系后阅读实现。
+说明字段、状态、能力与范围、事件/资源的影响，再修改 domain、生成契约和迁移草稿、接入业务页面。
+使用真实公开 API；不要手写业务路由、直接写表或新增本地数据库生命周期命令。
+按 docs/ai/commenting.md 给新建和修改代码写详细中文注释，覆盖职责、API/字段、步骤、原因和边界，同步修正相关上下游说明。
+按改动运行必要检查，报告通过/跳过/未执行项和需要的管理员配置。
+```
+
+交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、详细中文注释覆盖的主要职责与边界、验证结果，以及尚未做的真实外部联调。注释未覆盖项如实说明，不能用聊天中的解释代替源码注释。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。

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

@@ -0,0 +1,61 @@
+# CAGE-AI-001：智能运行时声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：领域声明 / 模型与运行预算配置。
+
+模型引用未配置、重复启用 AI 运行时，或上下文预算、重试、并发、超时、队列参数非法。
+
+## 修复步骤
+
+1. 在 domain 顶层导出一个 ai({ models, assistant }) 声明，审批 step 的 model 引用同名模型。
+2. 预算与并发为正整数；maxModelRetries 为 0 至 8，context.maxTools 最多 128（包含通用工具）。并发最多 32，单次运行 timeoutMs 最多 300000。API 与 worker 使用相同声明和模型配置。
+
+## 正例
+
+```text
+ai({ models: { main: provider }, assistant: { model: 'main', limits: { maxSteps: 8 } } })
+```
+
+## 反例
+
+```text
+ai({ models: {}, assistant: { model: 'missing', limits: { maxSteps: 0 } } })
+```
+
+## 修复后验证
+
+重跑 cage check、迁移与相关测试，再以真实角色验证助理和审批；fake 成功不代表真实模型联调完成。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/ai/src/index.ts:54`
+- `packages/ai/src/index.ts:61`
+- `packages/ai/src/index.ts:74`
+- `packages/ai/src/index.ts:82`
+- `packages/ai/src/index.ts:86`
+- `packages/ai/src/index.ts:88`
+- `packages/ai/src/index.ts:89`
+- `packages/ai/src/index.ts:90`
+- `packages/ai/src/index.ts:92`
+- `packages/ai/src/index.ts:94`
+- `packages/ai/src/index.ts:96`
+- `packages/ai/src/index.ts:126`
+- `packages/ai/src/index.ts:130`
+- `packages/ai/src/index.ts:132`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  /**
+   * 校验扩展唯一性与审批模型引用，无效配置以 CAGE-AI-001 拒绝。
+   */
+  validate(registry: Registry): void;
+}
+```