@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/app/packages/domain/src/modules/purchase/purchase-order.test.ts

@@ -12,7 +12,7 @@ let buyer: TestUser;
 let manager: TestUser;
 /**
  * 夹具通过真实命令建立部门负责人和库存，不绕过领域规则直接造业务行。
- * 申请人和经理能力分开，经理额度限定为 50000，确保后续断言真的经过职责分离与额度分支。
+ * 申请人和经理能力分开，以验证职责分离、业务批准和库存联动。
  */
 beforeAll(async () => {
   env = await createTestEnv({
@@ -24,19 +24,18 @@ beforeAll(async () => {
   });
   manager = await env.user({
     caps: ['PurchaseOrder.approve'],
-    params: { 'PurchaseOrder.approve': { ceiling: 50000 } },
   });
   await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: manager.id }, env.system());
   await env.kernel.execute('Inventory.create', { sku: 'A-01', available: 100 }, env.system());
 });
 afterAll(() => env?.close());
 
-/** 创建并提交一张 1200 元、两件 A-01 的采购单；只推进领域状态，不在此助手中消费 outbox。 */
-async function submitted() {
+/** 创建并提交两件 A-01 的采购单；金额默认 1200 元，不在此助手中消费 outbox。 */
+async function submitted(amount = '1200.00') {
   const ctx = await buyer.ctx();
   const order = await env.kernel.execute(
     'PurchaseOrder.create',
-    { amount: '1200.00', items: [{ sku: 'A-01', qty: 2 }] },
+    { amount, items: [{ sku: 'A-01', qty: 2 }] },
     ctx,
   );
   return env.kernel.execute('PurchaseOrder.submit', { id: order.id }, ctx);
@@ -126,21 +125,15 @@ it.each(['cancelled', 'received'] as const)(
   },
 );
 
-/** 低额度反例检查硬约束阻止批准，且同事务反应没有留下半成功的占用记录。 */
-it('审批额度不够时保留待审批状态，不创建库存锁', async () => {
-  const order = await submitted();
-  const lowLimit = await env.user({
-    caps: ['PurchaseOrder.approve'],
-    params: { 'PurchaseOrder.approve': { ceiling: 500 } },
-  });
+/** 领域命令不按角色金额限制批准；更大金额的额外步骤由采购流程声明负责。 */
+it('有批准能力的经理不需要额度参数即可执行大额采购结论', async () => {
+  const order = await submitted('60000.00');
   const process = env.kernel.processCtx({
     process: 'po-approval',
     tenantId: env.tenantId,
-    onBehalfOf: lowLimit.id,
+    onBehalfOf: manager.id,
     capabilities: ['PurchaseOrder.approve'],
   });
-  expect((await env.callAs(process, 'PurchaseOrder.approve', { id: order.id })).code).toBe(
-    'CONSTRAINT_VIOLATED',
-  );
-  expect(await env.query('select id from core.inventory_lock where id = $1', [order.id])).toHaveLength(0);
+  await env.kernel.execute('PurchaseOrder.approve', { id: order.id }, process);
+  expect((await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status).toBe('held');
 });

package/templates/app/packages/domain/src/modules/purchase/purchase-order.ts

@@ -1,12 +1,11 @@
 /**
  * 采购单声明集中列出申请材料、专业复核名单、状态、范围、命令和事件，由 API、worker 和生成器统一消费。
  * 草稿可编辑专业复核名单，提交重新核对协作名录；handler 仅读取声明依赖，数据库写入、版本与审计由内核完成。
- * 审批结论仍以 process 命令执行职责分离、额度和库存检查；选入名录或路由不授予权限。
+ * 审批结论仍以 process 命令执行职责分离和库存检查；选入名录或路由不授予权限。
  */
 import {
   aggregate,
   bool,
-  ceiling,
   command,
   emit,
   event,
@@ -127,7 +126,7 @@ export const create = command(PurchaseOrder, {
 /**
  * 在 draft 中调整本单专业复核需求和名单；需要 PurchaseOrder.setReviewers，不能直接修改待审批快照。
  * 输入保存前核对 1–5 位不同且非提单人的 active 名录成员；关闭时用 false/[]，失败整次回滚。
- * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取、批准能力或额度。
+ * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取或批准能力。
  */
 export const setReviewers = command(PurchaseOrder, {
   name: 'setReviewers', description: '设置采购单专业复核需求和人员', from: 'draft', to: null,
@@ -179,7 +178,7 @@ export const submit = command(PurchaseOrder, {
 });
 
 /**
- * 审批终结命令必须同时满足创建人与审批人分离、当前角色额度，以及声明的库存只读检查。
+ * 审批终结命令必须同时满足创建人与审批人分离，以及声明的库存只读检查。
  * stock 是 reads 绑定的受范围约束仓储；找不到 SKU 或登记数量不足时返回 STOCK_SHORT 并回滚。
  * 该检查不扣减 available；真正占用由 OrderApproved 的同事务反应创建 InventoryLock。
  * 范例展示资源配对，不实现多订单累计扣减、仓库出入库或价格核算。
@@ -188,7 +187,7 @@ export const approve = command(PurchaseOrder, {
   from: 'pending_approval',
   to: 'approved',
   invokedBy: 'process',
-  constraints: [sod.notSameAs('createdBy'), ceiling('amount')],
+  constraints: [sod.notSameAs('createdBy')],
   reads: { stock: Inventory },
   emits: [OrderApproved],
   handler: async (o, _input, { stock }) => {

package/templates/app/packages/domain/src/workflows/purchase-process.ts

@@ -18,7 +18,7 @@ export const purchaseLifecycle = businessProcess('purchase-lifecycle', {
     approval: { title: '采购审批', description: 'AI 先核查材料；通过后部门经理审批，金额超过五万元时增加财务审批。疑难材料由本步骤转人工。', actor: 'AI、部门经理、财务', kind: 'decision', action: poApproval },
     returned: { title: '退回修改', description: '材料不足退回草稿，保留本轮审核理由。', actor: '审批流程', action: returnForChanges },
     revise: { title: '补充采购用途', description: '依据建议补充用途，再次提交后从 AI 预审开始。', actor: '申请人', action: explainPurpose },
-    approved: { title: '批准并锁定库存', description: '审批结论通过权限、额度和库存校验后，同事务锁定所需库存。', actor: '审批流程与系统', action: approve,
+    approved: { title: '批准并锁定库存', description: '审批结论通过权限和库存校验后，同事务锁定所需库存。', actor: '审批流程与系统', action: approve,
       related: [{ object: InventoryLock, label: '同事务锁库存', via: acquireLock }] },
     received: { title: '确认收货', description: '接收外部收货通知并更新采购单，异步释放库存锁。', actor: '外部系统与系统', kind: 'end', action: markReceived,
       related: [{ object: InventoryLock, label: '收货后释放占用', via: releaseLock }] },

package/templates/blank/.agents/skills/cage-development/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: cage-development
+description: 使用 Cage 框架开发、修改和排查业务应用。适用于依赖 @yss123/cage-*、具有 cage.config.json 的项目，与用户澄清需求、比较方案，再完成业务建模、框架接入与验收；维护框架内部实现时先遵守框架仓库的 AGENTS.md。
+---
+
+<!-- 由 scripts/sync-agent-skill.ts 生成；教学正文只在 docs/development 维护。 -->
+
+加载本技能后，先阅读[完整框架开发方法](../../../docs/development/skills/cage-development/SKILL.md)，再根据其中的任务选择表读取相关专题。
+正文规定先理解需求、提出疑问与建议、查证框架，再说明实现映射、编码和验收；不要只凭本入口的摘要开始编写业务。
+当前项目的业务要求与 AGENTS.md 仍适用，框架维护任务遵守仓库的包边界。

package/templates/blank/AGENTS.md

@@ -2,7 +2,7 @@
 
 这是 create-cage-app 的空白业务项目。真实运行的 domain 仅包含用户、部门和角色组织模型；从 packages/domain/src 新建客户自己的业务，再从 index.ts 导出。框架通过 @yss123/cage-* 依赖提供。
 
-先读 [业务开发指南](docs/ai/README.md)、[任务配方](docs/ai/recipes.md) 和 [错误码册](docs/errors/README.md)。[采购范例参考源码](docs/examples/purchase-admin/README.md) 只用于学习，未注册到应用；导读中的采购路径在 docs/examples/purchase-admin 下查找。普通业务路径仍相对项目根目录。
+先读 [业务开发指南](docs/development/README.md)、[任务配方](docs/development/guides/recipes.md) 和 [错误码册](docs/errors/README.md)。[采购范例参考源码](docs/examples/purchase-admin/README.md) 只用于学习，未注册到应用；导读中的采购路径在 docs/examples/purchase-admin 下查找。普通业务路径仍相对项目根目录。
 
 ## 项目自己的业务约定
 
@@ -10,127 +10,47 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.3.1 -->
+<!-- cage:begin v0.4.0 -->
 ## Cage 业务开发约定（框架托管）
 
-### 先读，再按需求改业务
-
-本项目由 create-cage-app 创建。框架来自 `@yss123/cage-*` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
-
-先读项目说明指定的学习资料，默认入口为 `docs/ai/README.md`。第一次读 `architecture.md`、`project-structure.md` 和 `primitives.md`；具体任务读 `recipes.md`，采购全链路读 `purchase-example.md`，错误查 `docs/errors/README.md` 和 `docs/ai/troubleshooting.md`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
-
-### 详细中文注释（每次开发必须遵守）
-
-所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 `commenting.md`（独立项目为 `docs/ai/commenting.md`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
-
-- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
-- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
-- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
-- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
-- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
-- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
-- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
-
-### 原生 AI 能力入口
-
-遇到以下需求，先读 `docs/ai/intelligence.md`，用 `pnpm exec cage capabilities "关键词" --format json` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
-
-| 需求 | 框架入口与应用职责 |
-| --- | --- |
-| AI审批 / 智能审批 | 现有 `step` 使用 `kind: 'ai'`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
-| 业务助理 / 本体助理 | 导出 `ai({ models, assistant })`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
-| 页面上下文 / 随页助理 | `useAssistant(client.ai, page)` 配合 `useAiPageContext` / `AiPageContext`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
-| 模型管理 / Responses | `managedModel` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
-| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
-| 上下文预算 | `ai({ context: ... })` 的配置形状见 `AiContextOptions`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
-
-前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
-
-### 业务代码放在哪里
-
-| 位置 | 职责 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
-| `packages/domain/src/workflows`、`integrations` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
-| `packages/domain/src/index.ts` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
-| `packages/contracts/src/aggregates/<聚合>`、`queries` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
-| `apps/api/src` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
-| `apps/web/src/app` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
-| `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
-| `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
-| `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
-| `cage.config.json` | 项目路径、检查配置、graph.labels 中文图谱名称 |
-| `.env` | 本机真实连接和密钥；不提交、不输出完整内容 |
-
-新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 `docs/ai/project-structure.md`。新模板启用 `structure: modular`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
-
-### 实现一项需求的顺序
-
-1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前用 `pnpm exec cage snapshot save before-change` 保存不可覆盖的命名基线；或使用真实 Git 提交/独立本体图文件。
-3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 `export const`，从 domain 入口导出，跨文件导出名保持唯一。
-4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --snapshot before-change`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
-6. 按 `commenting.md` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
-
-### 必守边界
-
-- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
-- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
-- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；`to: null` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
-- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
-- 自定义查询声明 reads，二选一使用 sql/build，只读 `safe.*`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
-- scope 描述范围字段，角色数据决定实际范围；`scope.none()` 不代表所有人可访问。`can/useCan` 只控制按钮，后端负责授权。
-- 前端从 `@app/contracts` 导入生成 API/类型，按需使用 `@yss123/cage-client`；不导入 domain、内核或数据库包。
-- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
-- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
-- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。parallel(title, ...branch(...)) 声明结构化 AND：分支同时开始，内部顺序独立，全部活动分支完成后汇合；when 支持嵌套并仍按提交快照求值，声明有深度/数量边界，不支持任意跳转。currentSteps 表示当前活动节点集合，兼容字段 currentStep 只是最小活动索引，不能据此隐藏其他分支。人工节点 assignment: 'candidate' 开放候选领取/释放，approver.field 从 routable 字段选人；actions 开放转办、委派归还和前后/并行必签。任务操作与决定携带 revision，waiting 任务只能查看。approvalOperations() 为框架通用时效运行时：step.sla 配置自然分钟节点总时限，route.reminders 配置申请人催办；迁移并运行 worker 后提供持久站内提醒、已读与 Admin 通用页面，不自动批准或授予权限。政策、SDK 和边界见 docs/ai/approvals.md。第三方 IO 通过连接器，回调验签后调用 external 命令。
-- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
-- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
-- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
-- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
-
-### 最小命令形状
-
-```ts
-// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
-/**
- * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
- * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
- * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
- * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
- */
-export const submitOrder = command(Order, {
-  name: 'submit',
-  from: 'draft',
-  to: 'pending_approval',
-  emits: [OrderSubmitted],
-  handler: (draft) => draft,
-});
-```
-
-完整可添加的普通管理对象见 `docs/ai/primitives.md` 的 Note；采购模板的审批、资源、第三方示例在 `packages/domain/src`，空白模板的参考源码在 `docs/examples/purchase-admin`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
-
-### 启动、验证与排错
-
-在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`；用 `pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织，最后 `pnpm dev`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
-
-init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
-
-API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。`/healthz` 只表示存活，`/readyz` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
-
-- `pnpm exec cage graph`：浏览器图谱，默认端口 15418，以终端为准。
-- `pnpm exec cage context command:对象.命令 --format json --out .cage/context.json`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
-- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
-- `pnpm exec cage capabilities 关键词 --format json`：查当前安装版本公开签名；`cage doctor`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。`cage timeline/explain` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
-- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
-- `pnpm exec cage gen --check`：生成一致性；`pnpm exec cage sync --check`：本托管区一致性。
-- `pnpm exec cage test --only project`：业务测试；`pnpm verify`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
-- `pnpm exec cage verify --skip-tests` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
-- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
-- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
-- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
-
-框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+### 学习与任务入口
+
+本项目使用 `@yss123/cage-*`，业务写在本项目。先读项目说明指定的教材；独立项目默认入口是 `docs/development/README.md`。
+
+开始 Cage 业务开发或排错时，加载 `docs/development/skills/cage-development/SKILL.md`，统一按“理解需求 → 澄清 → 查证能力 → 说明实现映射 → 编码 → 验收”工作。首次学习配合 `docs/development/getting-started/first-feature.md`；已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
+
+支持 Agent Skills 的工具可发现 `.agents/skills/cage-development`；其他工具直接读取上述 Markdown，使用相同流程。教材随框架版本分发，均为本地文件，不需要额外服务、模型或索引。框架仓库范例使用项目说明指定的规范教材位置。
+
+### 框架执行什么
+
+- 业务声明从 domain 总入口导出，框架据此构建注册表、能力、HTTP 接口、本体图、契约与迁移草稿；只有文件而未导出不会生效。
+- 命令是业务写入口；handler 描述变化与显式 reads，内核处理授权、状态、范围、版本、事务、审计及 outbox。读侧通过生成契约或 query 的安全视图，外部 IO 通过连接器。
+- 角色、能力、数据范围、调用身份与业务约束分别建模。前端 can() 只影响显示，新增能力不自动授给生产角色；审批选人不授予能力。
+- 页面依赖生成契约及客户端。表单、弹窗等临时状态留在前端；正式业务数据和流程结果通过服务端读写。实际记录不能用模拟仓储或固定统计替代。
+
+### 编码前的依据
+
+业务疑点按 `docs/development/guides/business-collaboration.md` 提出选项、影响和推荐，让用户选择；沿用已明确的规则与授权。API 和当前行为由 agent 查证，普通技术方案自行决定；等待业务答案时推进独立部分。
+
+写代码前按 Skill 简述“已确认规则 → 已查证的 Cage 能力 → 修改位置 → 验收结果”，具体设计见 `docs/development/guides/recipes.md`。能力与签名查 `cage capabilities`，现有业务查 `cage context` 并阅读源码。未知规则和能力缺口不能靠猜测、编造 API 或复制示例填补；已明确的部分直接实施，不另设技术方案批准。
+
+涉及领域建模先读 `docs/development/guides/ontology-modeling.md`：说明对象含义、关系方向/基数、状态及动作前后结果，再写真实声明。聚合/字段/命令等填写结构化描述，每个状态填写 labels；中文注释和前端文案不会自动成为本体名称。处理本次声明的 CAGE-ONTOLOGY-001，并按业务例子核对关系和触发链；名称完整不能证明业务正确。自然语言、文档、表格和原型都是输入，不能由模板或页面布局代替业务判断。
+
+遇到原生 AI、AI 审批或随页助理，先读 `docs/development/guides/intelligence.md`，核对已有能力及应用启用状态。审批、文件、关系、数据传输等专题由 Skill 按需引导，不重建框架已有运行时。
+
+### 代码与环境边界
+
+- 所有手写代码遵守 `docs/development/reference/commenting.md`：文件职责与调用链、导出 API/字段、复杂分支的中文说明，写清做什么、为什么、怎样完成及实际边界；随代码更新。生成物注释从生成器维护。
+- domain 按 modules/workflows/integrations/shared 组织，Web 按 app/modules/shared 组织。模块通过 index.ts 公开入口组合，前端不导入 domain、数据库或内核运行时；不关闭 modular 目录门禁。
+- 领域含义修改前保留本体或真实 Git 基线；修改声明后运行 check/gen，审查契约和迁移草稿。生成物不手改，已执行迁移不可改写；具体命令见 `docs/development/getting-started/workflow.md`。
+- 页面处理业务失败、版本冲突、会话与缓存；多页面使用独立 URL，筛选/分页进入查询参数，按 `docs/development/guides/routing.md` 实际验收。
+- 新项目启动步骤见 `docs/development/getting-started/workflow.md`。使用已有 PostgreSQL 和项目 .env；init 准备账号，migrate 更新结构，bootstrap 显式初始化组织，dev 启动进程。普通业务不新增连接池或管理 Docker。
+- 不输出或提交 .env、数据库密码、Cookie 密钥及初始化凭据。API 与 worker 使用一致的 domain，修改配置后按实际需要重启。
+- 出错保留 code/at/reason/fix，查 `docs/errors/README.md` 与 `docs/development/tools/troubleshooting.md`；不得放宽权限、删约束或关闭门禁来掩盖问题。
+
+### 完成依据
+
+对照编码前的业务规则逐项验收，验证与改动匹配。check/gen/typecheck/build 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
+
+`pnpm verify` 汇总门禁；`verify --skip-tests` 不代表完整通过。诊断用 `cage doctor`、`timeline`、`explain`，具体前提见 `docs/development/tools/diagnostics.md`。交付分别说明通过、跳过、未执行及剩余配置；文档和可逆小改动不反复执行全量数据库回归。
 <!-- cage:end -->

package/templates/blank/CLAUDE.md

@@ -0,0 +1,6 @@
+<!-- 由 scripts/sync-agent-skill.ts 生成；共享同一套框架教材。 -->
+# Cage 开发入口
+
+先读本目录 [AGENTS.md](AGENTS.md) 的项目说明和约定。
+进行 Cage 业务开发或排错时，阅读[框架开发 Skill](docs/development/skills/cage-development/SKILL.md)，按任务选择章节并完成对应验证。
+这是框架维护的通用教学流程；具体业务以用户需求和项目约定为准。

package/templates/blank/README.md

@@ -2,7 +2,7 @@
 
 这是可直接开发业务的 TypeScript + React 项目，框架由 `@yss123/cage-*` npm 包提供。当前仅注册用户、部门、角色基础模型，保留登录、权限、系统管理、审计和异步任务；没有采购、库存、审批演示声明或演示业务表。
 
-先读 [AGENTS.md](AGENTS.md) 和 [业务开发指南](docs/ai/README.md)。给 Codex 等工具描述自己的业务需求，按 [任务配方](docs/ai/recipes.md) 开发即可。[采购范例导读](docs/ai/purchase-example.md) 对应 `docs/examples/purchase-admin` 中的参考源码；这些文件不参与编译、领域注册或迁移。
+先读 [AGENTS.md](AGENTS.md) 和 [业务开发指南](docs/development/README.md)。给 Codex 等工具描述自己的业务需求，按 [任务配方](docs/development/guides/recipes.md) 开发即可。[采购范例导读](docs/development/examples/purchase-example.md) 对应 `docs/examples/purchase-admin` 中的参考源码；这些文件不参与编译、领域注册或迁移。
 
 ## 首次启动
 
@@ -17,11 +17,11 @@
 
 登录后可从“系统管理”配置用户、部门、角色与权限，再按业务需求添加模块。页面不会显示虚构业务数据。`.env` 中三个账号连接同一个数据库；日常运行不需要管理员账号。首次迁移应在为本项目准备的库中执行，接管历史业务表需要额外映射和迁移审查。
 
-前端已配置 React Router：`/login` 登录、`/workspace` 工作台、`/directory/users` 成员列表、`/directory/users/:id` 成员详情，以及应用 404。成员页面只读取已有组织模型，需要 User.read，未增加演示业务或数据。详情可直达、刷新，登录后返回原地址。新增业务与生产 SPA 回退按[路由和浏览器验收指南](docs/ai/routing.md)执行；反向代理示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+前端已配置 React Router：`/login` 登录、`/workspace` 工作台、`/directory/users` 成员列表、`/directory/users/:id` 成员详情，以及应用 404。成员页面只读取已有组织模型，需要 User.read，未增加演示业务或数据。详情可直达、刷新，登录后返回原地址。新增业务与生产 SPA 回退按[路由和浏览器验收指南](docs/development/guides/routing.md)执行；反向代理示例见 [deploy/nginx.conf](deploy/nginx.conf)。
 
 ## 添加第一个业务模块
 
-先读[工程目录与代码组织](docs/ai/project-structure.md)。在 `packages/domain/src/modules/<业务>` 新建声明，通过模块 index.ts 从领域总入口导出；运行 `pnpm exec cage check`、`pnpm gen`，审查生成契约和迁移。在 `apps/web/src/modules/<业务>` 使用 `@app/contracts` 实现页面和表单，通过模块公开入口接入 `app` 导航；共享 UI/工具放 `shared`。最后按需迁移，并由管理员分配新增能力。完整的 Note 对象示例见 [原语与最小业务](docs/ai/primitives.md)。
+先读[工程目录与代码组织](docs/development/reference/project-structure.md)。在 `packages/domain/src/modules/<业务>` 新建声明，通过模块 index.ts 从领域总入口导出；运行 `pnpm exec cage check`、`pnpm gen`，审查生成契约和迁移。在 `apps/web/src/modules/<业务>` 使用 `@app/contracts` 实现页面和表单，通过模块公开入口接入 `app` 导航；共享 UI/工具放 `shared`。最后按需迁移，并由管理员分配新增能力。完整的 Note 对象示例见 [原语与最小业务](docs/development/reference/primitives.md)。
 
 `src/main.tsx` 只挂载 React 和全局 Provider，业务不平铺到 src 根目录。`cage.config.json` 已启用 `structure: modular`，check/verify 会检查目录和依赖边界；不要关闭检查或将所有业务移入 shared 来消除提示。
 

package/templates/blank/apps/api/package.json

@@ -10,6 +10,6 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.3.1"
+    "@yss123/cage-http": "0.4.0"
   }
 }

package/templates/blank/apps/web/package.json

@@ -8,9 +8,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@ant-design/icons": "^6.3.4",
     "@app/contracts": "workspace:*",
     "@tanstack/react-query": "^5.87.1",
-    "@yss123/cage-client": "0.3.1",
+    "@yss123/cage-client": "0.4.0",
+    "antd": "^6.7.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-markdown": "^10.1.0",

package/templates/blank/apps/web/src/app/styles/global.css

@@ -23,11 +23,11 @@ body {
   margin: 0;
   min-width: 1024px;
 }
-button,
+button:not(.ant-btn),
 input {
   font: inherit;
 }
-button,
+button:not(.ant-btn),
 a {
   -webkit-tap-highlight-color: transparent;
 }
@@ -39,16 +39,17 @@ button,
 .primary {
   cursor: pointer;
 }
-button:disabled {
+button:not(.ant-btn):disabled {
   cursor: wait;
   opacity: 0.65;
 }
-button:focus-visible,
+button:not(.ant-btn):focus-visible,
 a:focus-visible {
   outline: 3px solid #91bca2;
   outline-offset: 4px;
 }
-button {
+/* 原生按钮规则服务于模板现有的 DOM 控件，不覆盖新增的 Ant Design Button。 */
+button:not(.ant-btn) {
   transition:
     background 0.18s ease,
     border-color 0.18s ease;

package/templates/blank/apps/web/src/main.tsx

@@ -1,18 +1,29 @@
 /**
- * 空白业务应用的浏览器启动入口，创建共享 QueryClient 并挂载 app 路由。
- * 新增业务页面使用同一 Provider 内的生成查询 hooks；此处只装配前端，不注册领域或连接数据库。
- * 全局样式由入口加载，会话失效与账号切换时的查询清理由 useSession 负责。
+ * 空白业务应用的浏览器启动入口，装配 Ant Design 中文主题、共享 QueryClient 并挂载 app 路由。
+ * 新增页面使用同一组 Provider 内的 UI 上下文和生成查询 hooks；入口不注册领域或连接数据库。
+ * AntD reset 与全局样式由入口加载，会话失效和账号切换时的查询清理由 useSession 负责。
  */
-// 浏览器入口只负责挂载和全局 Provider。QueryClient 让新增模块可直接使用生成查询 hooks。
+// 浏览器入口只负责挂载 React、Ant Design 与查询 Provider，让新增模块使用统一 UI 和缓存上下文。
 import { createRoot } from 'react-dom/client';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { App as AntdApp, ConfigProvider } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
 import { App } from './app/app';
+import 'antd/dist/reset.css';
 import './app/styles/global.css';
 
 const queryClient = new QueryClient();
 
+/**
+ * ConfigProvider 为组件提供简体中文文案和共享主题；AntdApp 提供上下文反馈方法。
+ * QueryClientProvider 承载生成查询 hooks 的缓存；三个 Provider 覆盖应用的全部路由。
+ */
 createRoot(document.getElementById('root')!).render(
-  <QueryClientProvider client={queryClient}>
-    <App />
-  </QueryClientProvider>,
+  <ConfigProvider locale={zhCN} theme={{ token: { colorPrimary: '#173e35', borderRadius: 4 } }}>
+    <AntdApp>
+      <QueryClientProvider client={queryClient}>
+        <App />
+      </QueryClientProvider>
+    </AntdApp>
+  </ConfigProvider>,
 );

package/templates/blank/cage.config.json

@@ -5,6 +5,7 @@
   "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
   "graph": {
     "title": "业务应用图谱",
+    "naming": "required",
     "labels": {
       "aggregate:Dept": "部门",
       "aggregate:User": "用户",

package/templates/blank/docs/README.md

@@ -0,0 +1,13 @@
+# 本地框架文档
+
+编程 agent 先读项目 [AGENTS.md](../AGENTS.md)，按 [Cage 开发 Skill](development/skills/cage-development/SKILL.md) 理解需求、澄清、查证能力、说明实现映射，再编码与验收。
+
+[任务导航](development/README.md) 说明各类文档的分工，按本次需要选择资料：
+
+- `development/getting-started`：运行模型、完整业务链和操作命令。
+- `development/guides`：[业务澄清](development/guides/business-collaboration.md)、[能力选择与实现映射](development/guides/recipes.md)、各专题接入。
+- `development/reference`：原语与工程规范。
+- `development/tools`：诊断、本体查询和排错。
+- `development/examples`：教学源码与采购导读。
+- `development/skills`：唯一的 agent 工作流程。
+- [错误码册](errors/README.md)：按实际错误定位原因。

package/templates/blank/docs/development/README.md

@@ -0,0 +1,80 @@
+# Cage 框架学习入口
+
+本目录面向使用 Cage 编写业务的 agent，帮助 agent 理解需求、查证框架并完成真实实现。先读项目 AGENTS.md，再按 [cage-development Skill](skills/cage-development/SKILL.md) 工作；本页只负责按任务定位资料。教材由框架维护，随脚手架分发，读取无需额外服务、模型或向量索引。
+
+工作主线：**理解需求 → 提出疑问与建议 → 核对现有业务和框架能力 → 说明实现映射 → 编码 → 按规则验收**。明确的规则直接采用，技术事实自行查证，需要用户决定的业务取舍再交给用户选择。
+
+模型接入、智能助理和 AI 审批属于框架的原生 AI 能力，具体接入见[原生 AI 专题](guides/intelligence.md)。
+
+## 按当前阶段阅读
+
+| 你现在需要什么 | 从哪里开始 | 应得到什么 |
+| --- | --- | --- |
+| 第一次使用 Cage | [Skill 的运行模型](skills/cage-development/SKILL.md#先建立正确的运行模型) → [第一条完整业务链](getting-started/first-feature.md) | 理解声明、导出、生成、授权、契约与持久读写如何连接 |
+| 用户描述或文档不清楚 | [业务澄清与共同设计](guides/business-collaboration.md) | 主动提出疑问、可行选项与建议，与用户选择业务规则，再落实到实现和验收 |
+| 把需求转成设计 | [业务设计与能力选择](guides/recipes.md) → [编码前的映射](skills/cage-development/SKILL.md#4-写代码前说明实现映射) | 业务规则、查证过的能力、修改位置和验收例子一一对应 |
+| 表达对象、状态和关系的业务含义 | [本体建模](guides/ontology-modeling.md) → [对象关系](guides/relations.md) | 名称写入真实声明，关系有正确方向、基数及执行依据，图谱能用业务用语阅读 |
+| AI 生成 React 页面与选择组件 | [前端组件指南](guides/frontend-ui.md) → [路由](guides/routing.md) | 生成可维护的真实 TSX 页面，使用 Ant Design 组合 UI，并按 Cage 契约读写 |
+| 实现或修改功能 | [Skill 的实施流程](skills/cage-development/SKILL.md#5-沿一条真实链路实施再扩展) → [开发步骤](getting-started/workflow.md) | 沿实际调用链完成受影响的功能，并取得验证证据 |
+| 已有功能不正常 | [排错方法](tools/troubleshooting.md) → [诊断工具](tools/diagnostics.md) / [错误码册](../errors/README.md) | 找到第一个失败边界，修复原因并复验 |
+| 查询一个能力的用法 | 下方专题表，必要时本地搜索术语 | 找到当前任务的 API、接入前提与限制 |
+
+已经熟悉框架时不必每次重读课程。不要将所有专题一次加载，也不要把参考业务注册到客户应用。
+
+## 各类文件的责任
+
+| 文件 | 负责什么 |
+| --- | --- |
+| 项目 AGENTS.md | 项目入口、代码与环境约束；项目业务约定保留在框架托管区外 |
+| [Skill](skills/cage-development/SKILL.md) | agent 的工作顺序、判断依据及何时与用户互动 |
+| [业务澄清](guides/business-collaboration.md) | 如何发现疑点、比较方案、保留并落实用户选择 |
+| [能力选择](guides/recipes.md) | 业务规则如何映射到 Cage，包含编码前的映射示例 |
+| [本体建模](guides/ontology-modeling.md) | 业务含义、结构化名称、对象关系和触发链写在哪里，以及怎样检查和验收 |
+| [开发步骤](getting-started/workflow.md) | 已确定设计的修改、生成、迁移和验证命令 |
+| 其他专题、参考与源码 | 当前能力用法、前提与边界，按需阅读；示例业务不成为当前需求 |
+
+## 按资料用途查找
+
+| 目录 | 内容与入口 |
+| --- | --- |
+| `getting-started/` 入门 | [运行模型](getting-started/architecture.md)、[完整入门课](getting-started/first-feature.md)、[开发步骤](getting-started/workflow.md) |
+| `guides/` 专题指南 | [业务澄清](guides/business-collaboration.md)、[能力选择](guides/recipes.md)、[本体建模](guides/ontology-modeling.md)、[前端组件](guides/frontend-ui.md)、[审批](guides/approvals.md)、[文件](guides/files.md)、[关系](guides/relations.md)、[路由](guides/routing.md)、[数据传输](guides/transfers.md)、[原生 AI](guides/intelligence.md) |
+| `reference/` 参考规范 | [原语](reference/primitives.md)、[目录组织](reference/project-structure.md)、[中文注释](reference/commenting.md) |
+| `tools/` 工具与排错 | [诊断](tools/diagnostics.md)、[本体上下文](tools/ontology-context.md)、[排错方法](tools/troubleshooting.md) |
+| `examples/` 教学示例 | [便笺源码](examples/note/note.ts)、[采购导读](examples/purchase-example.md)；按入门课与导读阅读，源码不自动注册 |
+| `skills/` agent 开发流程 | [cage-development](skills/cage-development/SKILL.md)，按任务加载上述教材 |
+
+查明确符号可用 `rg -n "术语或符号" docs/development docs/errors`，没有 rg 时使用 agent 的本地文件搜索。用 `pnpm exec cage capabilities 符号 --format json` 核对已安装版本公开签名，用 `pnpm exec cage context "业务关键词" --format json` 定位当前应用。候选命中不能代替阅读上下文，未命中也不能证明框架不支持。
+
+## 确认代码与资料的位置
+
+本指南的业务路径和命令默认相对应用根目录。应用的 `packages/domain/src` 定义业务，`packages/contracts/src` 是生成契约，`apps/web/src` 是界面，`apps/api/src` 是薄启动入口，`db/migrations` 保存审查过的迁移。
+
+空白模板只启用组织基础；`docs/examples/purchase-admin` 是离线采购参考源码，不参与注册、编译或迁移。采购模板直接在业务目录包含该范例。框架仓库的应用根目录是 `examples/purchase-admin`，规范教材位于仓库 `docs/development`，以应用 AGENTS.md 的说明为准。
+
+`docs/development` 是框架教学内容的唯一手写来源；Skills 发现入口和模板副本由同步脚本生成。用户的业务约定保留在项目已有业务文档或 AGENTS.md 的托管区外。教材分发检查只能证明资料存在且一致，模型是否学会需要框架维护者另做任务评估。
+
+## 当前实现边界
+
+以下区分可避免 agent 把方案中的愿景写成不存在的功能。
+
+| 已有能力 | 使用边界 |
+| --- | --- |
+| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
+| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
+| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
+| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
+| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
+| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
+| 代码审批路由与任务流转 | 顺序/条件、`parallel/branch` 结构化 AND 分支与汇合、any/all、字段选人、候选领取/释放、转办、单层委派归还、前后/并行必签和动作历史；候选池仅支持 any，追加票全部必签。条件和依赖随提交冻结，currentStep 仅为最小活动索引；尚无任意连线/循环/OR 网关、岗位/代理规则、通用恢复、任意 JS 选人或在途迁移，见[任务流转](guides/approvals.md) |
+| 审批时限、站内提醒与催办 | 人工节点按实际开启时间计算自然分钟 SLA，worker 持久投递临期/超时提醒；申请人可按完整活动集合催办，同实例共享冷却，接收人可标已读。旧快照不自动获得政策；尚无工作日历、自动升级、抄送或邮件/短信通知 |
+| 审批界面与 SDK | Admin/采购待办可领取、释放、归还受托任务并查看等待加签；采购另有协作名录选人器、转办/委派/三种加签及分页人工历史，view 查询参数保留视图。启用运营后通用 Admin 提供我的申请、催办和流程提醒；页面仍需应用启用、真实授权与浏览器验收。AI 助理目前只查询本人待办及提交决定，无人员管理写工具 |
+| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
+| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
+| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
+| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
+| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
+| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
+| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
+
+文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。