@yss123/cage-cli 0.3.1 → 0.4.0

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

@@ -1,6 +1,6 @@
 # CAGE-TEST-001：测试进程没有生成结果报告
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-TEST-002：派生测试准备或初始夹具失败
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-TEST-003：测试数据库目录归属不匹配
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-UNSAFE-001：逃生口缺少原因或负责人
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-UPGRADE-001：升级版本或 codemod 有歧义
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-WORKER-001：缺少必要后台引擎
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-WORKER-002：事件与消费者清单不匹配
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-WORKER-003：后台任务未在停机时限内结束
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -3,11 +3,17 @@
 这是本业务项目自带的离线诊断手册。先使用错误码、声明位置、reason/fix 定位；不需要克隆框架仓库。
 
 - [HTTP 运行时错误与业务码](runtime.md)：401/403/404、状态冲突、约束拒绝、DOMAIN_ERROR 等。
-- [业务排错顺序](../ai/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
+- [业务排错顺序](../development/tools/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
 - CAGE-* 是声明、工具链或内部运行诊断；HTTP code 与业务 domainCode 是另一层，不要混为一谈。
 
 每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
 
+## 本体业务名称
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ONTOLOGY-001](CAGE-ONTOLOGY-001.md) | 本体节点缺少结构化业务名称 |
+
 ## 智能运行时
 
 | 诊断码 | 含义 |
@@ -181,7 +187,7 @@
 
 | 诊断码 | 含义 |
 | --- | --- |
-| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或额度 |
+| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或参数 |
 | [CAGE-GRANT-002](CAGE-GRANT-002.md) | 授予超出自己的数据范围 |
 | [CAGE-GRANT-003](CAGE-GRANT-003.md) | 能力不在代码目录中 |
 

package/templates/blank/docs/errors/runtime.md

@@ -1,6 +1,6 @@
 # HTTP 运行时错误与业务码
 
-[返回错误码册](README.md) · [排错方法](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [排错方法](../development/tools/troubleshooting.md)
 
 框架诊断分三层：`CAGE-APPR-007` 等内部/工具码、HTTP 响应的通用 `code`、业务拒绝的 `domainCode`。同一次失败可以同时涉及几层；例如审批人配置问题出现在 worker 死信，前端提交此前可能已成功。
 
@@ -13,7 +13,7 @@
 | NOT_FOUND | 404 | 记录不存在或超出范围 | 用当前用户检查 id/租户/范围，不泄漏范围外数据 |
 | INVALID_INPUT | 400 | Zod/协议输入错误、外键或检查约束等 | 按输入 schema 修正字段和格式，不直接扩大 schema |
 | INVALID_TRANSITION | 409 | 当前状态不允许该命令 | 刷新记录，按真实生命周期显示允许操作 |
-| CONSTRAINT_VIOLATED | 403 | 职责分离、额度、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
+| CONSTRAINT_VIOLATED | 403 | 职责分离、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
 | INVARIANT_VIOLATED | 409 | 命令结果不满足聚合不变量 | 修正输入或 handler，保持合法结果 |
 | CONFLICT | 409 | 版本、唯一性、数据库串行化/死锁等冲突 | 看 detail、重新读取再决定是否重试；不要盲目重复创建 |
 | DOMAIN_ERROR | 422 | handler 返回 fail | 读取 domainCode，展示业务文案和必要 detail |

package/templates/blank/docs/examples/purchase-admin/README.md

@@ -2,4 +2,4 @@
 
 本目录只供阅读，不参与应用编译、注册、运行或迁移。当前应用的真实领域入口是项目根目录 packages/domain/src/index.ts。
 
-按 [采购范例导读](../../ai/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。
+按 [采购范例导读](../../development/examples/purchase-example.md) 阅读；导读中的范例路径在本目录下查找。需要可运行的完整采购项目时，重新使用 create-cage-app --template purchase 创建新目录，不要直接把整套业务导入空白项目。

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/styles/global.css

@@ -19,16 +19,17 @@
 body {
   margin: 0;
 }
-button,
+button:not(.ant-btn),
 input {
   font: inherit;
 }
-button,
+button:not(.ant-btn),
 a,
 input {
   outline-offset: 4px;
 }
-button {
+/* 原生按钮规则服务于范例中现有的手写 DOM 控件，不覆盖新增的 Ant Design Button。 */
+button:not(.ant-btn) {
   border: 1px solid var(--line);
   background: #fff;
   color: var(--green);
@@ -37,10 +38,10 @@ button {
   cursor: pointer;
   transition: background 0.15s;
 }
-button:hover {
+button:not(.ant-btn):hover {
   background: #edf2e8;
 }
-button:disabled {
+button:not(.ant-btn):disabled {
   opacity: 0.45;
   cursor: default;
 }
@@ -295,7 +296,7 @@ header {
   gap: 7px;
   flex-wrap: wrap;
 }
-.filters button {
+.filters button:not(.ant-btn) {
   border: 0;
   background: none;
   font-size: 12px;
@@ -305,7 +306,7 @@ header {
   background: #edf3e6;
   color: var(--green);
 }
-.toolbar > button {
+.toolbar > button:not(.ant-btn) {
   font-size: 11px;
 }
 /**
@@ -373,7 +374,7 @@ tr:last-child td {
   display: flex;
   gap: 7px;
 }
-.actions button {
+.actions button:not(.ant-btn) {
   font-size: 11px;
   padding: 6px 9px;
 }
@@ -386,7 +387,7 @@ tr:last-child td {
   font-size: 11px;
   color: var(--muted);
 }
-.pagination button {
+.pagination button:not(.ant-btn) {
   font-size: 11px;
   margin-left: 7px;
 }
@@ -442,7 +443,7 @@ tr:last-child td {
   font-size: 12px;
   margin-bottom: 20px;
 }
-.notice button {
+.notice button:not(.ant-btn) {
   background: transparent;
   border: 0;
 }
@@ -459,7 +460,7 @@ tr:last-child td {
   align-items: end;
   padding: 22px;
 }
-.stock-form button {
+.stock-form button:not(.ant-btn) {
   margin-bottom: 18px;
 }
 label {

package/templates/blank/docs/examples/purchase-admin/apps/web/src/main.tsx

@@ -1,18 +1,29 @@
 /**
- * 采购 Web 的浏览器启动入口：创建共享查询缓存，将应用路由挂到 root DOM 节点。
- * 契约客户端负责网络与会话协议，页面只在 Provider 内消费 hooks；这里不注册领域或启动后端。
- * 全局样式在此加载，账号切换时的缓存清理由 useSession 和应用壳负责。
+ * 采购 Web 的浏览器启动入口：装配 Ant Design 中文主题、共享查询缓存并挂载应用路由。
+ * 页面通过 Provider 消费 UI 上下文、生成契约客户端和查询 hooks；入口不注册领域或启动后端。
+ * AntD reset 与业务全局样式在此加载，账号切换时的缓存清理由 useSession 和应用壳负责。
  */
-// 唯一浏览器启动入口：挂载 React、全局 Provider 和样式；业务从 app 组合进入。
+// 唯一浏览器启动入口：挂载 React、Ant Design 与查询 Provider；业务从 app 组合进入。
 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 为 message、modal、notification 等反馈 API 提供上下文。
+ * 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/docs/examples/purchase-admin/apps/web/src/shared/lib/error-message.ts

@@ -16,7 +16,7 @@ export function errorMessage(r: Extract<CageResult<unknown, string>, { ok: false
     INVALID_INPUT: '请检查填写内容',
     CONFLICT: '数据或任务已更新，请刷新后重试',
     UNAUTHENTICATED: '登录已过期',
-    CONSTRAINT_VIOLATED: '未满足审批条件，请检查审批人或额度',
+    CONSTRAINT_VIOLATED: '未满足业务条件，请检查操作人及具体原因',
     STOCK_SHORT: '库存不足',
     REVIEWERS_REQUIRED: '请为专业会签选择 1–5 位协作人',
     REVIEWERS_NOT_REQUIRED: '取消专业会签时请清空复核人员',

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/approval-member-picker.tsx

@@ -46,6 +46,6 @@ export function ApprovalMemberPicker({ value, onChange, max = 5, exclude = [], d
     {query.data && entries.length === 0 && <p className="muted">当前页没有匹配人员，请调整筛选或联系名录维护人。</p>}
     {(query.data?.total ?? 0) > 200 && <div className="actions"><button type="button" disabled={page === 1} onClick={() => setPage(page - 1)}>上一页</button>
       <span>第 {page} 页</span><button type="button" disabled={page * 200 >= query.data!.total} onClick={() => setPage(page + 1)}>下一页</button></div>}
-    <small className="muted">名录只提供选人信息，处理权限、数据范围和最终额度仍以服务端校验为准。</small>
+    <small className="muted">名录只提供选人信息，处理权限和数据范围仍以服务端校验为准。</small>
   </fieldset>;
 }

package/templates/blank/docs/examples/purchase-admin/cage.config.json

@@ -5,6 +5,7 @@
   "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
   "graph": {
     "title": "采购业务图谱",
+    "naming": "required",
     "labels": {
       "module:purchase": "采购管理",
       "module:inventory": "库存管理",
@@ -125,7 +126,7 @@
       "state:Role.archived": "已停用",
       "field:Role.code": "角色编码",
       "field:Role.name": "角色名称",
-      "field:Role.capabilities": "能力点与额度",
+      "field:Role.capabilities": "能力点",
       "field:Role.scopes": "数据访问范围",
       "capability:Role.read": "查看角色",
       "capability:Role.export": "导出角色",

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/role/index.ts

@@ -31,7 +31,7 @@ export const RoleInputs = {
 };
 
 /** Role.archive 可能返回的错误码 */
-export type RoleArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleArchiveError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.create 可能返回的错误码 */
 export type RoleCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** Role.grantCapability 可能返回的错误码 */
@@ -39,7 +39,7 @@ export type RoleGrantCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOM
 /** Role.rename 可能返回的错误码 */
 export type RoleRenameError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.revokeCapability 可能返回的错误码 */
-export type RoleRevokeCapabilityError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleRevokeCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.setScope 可能返回的错误码 */
 export type RoleSetScopeError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/user/index.ts

@@ -38,11 +38,11 @@ export type UserAssignRolesError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_
 /** User.create 可能返回的错误码 */
 export type UserCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** User.disable 可能返回的错误码 */
-export type UserDisableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserDisableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.enable 可能返回的错误码 */
-export type UserEnableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserEnableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.setPassword 可能返回的错误码 */
-export type UserSetPasswordError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserSetPasswordError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.update 可能返回的错误码 */
 export type UserUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/blank/docs/examples/purchase-admin/packages/domain/src/modules/purchase/approval-members.ts

@@ -1,7 +1,7 @@
 /**
  * 采购协作名录：由业务管理员登记可参与采购复核的账号、公开业务姓名和专业领域，供草稿选人及任务操作使用。
  * 聚合通过标准命令维护，浏览器读取 safe.approval_member；名录与 sys.user 的私密资料、角色授权分离。
- * 名录在同租户内向具 ApprovalMember.read 且显式获 all 范围的采购参与者公开；加入名录不授予审批权限、范围或额度。
+ * 名录在同租户内向具 ApprovalMember.read 且显式获 all 范围的采购参与者公开；加入名录不授予审批权限或范围。
  */
 import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
 import { z } from 'zod';

package/templates/blank/docs/examples/purchase-admin/packages/domain/src/modules/purchase/approvals.ts

@@ -1,7 +1,7 @@
 /**
  * 采购实际审批路由：AI 预审、部门审核、可选专业会签和大额财务候选受理，共用一个采购流程实例。
  * 人工节点显式开放转办、委派和前后/并行加签；步骤/政策随提交保存，旧实例保持自己的快照。
- * 路由只决定任务分配与签序，最终结论仍执行领域命令的职责分离、额度与库存约束。
+ * 路由只决定任务分配与签序，最终结论仍执行领域命令的职责分离与库存约束。
  */
 import { approval } from '@yss123/cage-kernel';
 import { approver, eq, gt, route, step, when } from '@yss123/cage-approval';
@@ -28,7 +28,7 @@ export const poApproval = approval(PurchaseOrder, {
  * needsSpecialistReview=true 才增加专业会签，名单来自提交快照且全部人必须通过；金额严格大于 50000 元才增加财务节点。
  * AI 只读取 reason/amount/items，pass 仅推进到经理，return 回到草稿，manual 在当前节点交部门负责人。
  * 模型失败同样转人工，最多四轮/五次工具调用/120 秒；不以失败兜底为自动批准。
- * 财务共享一项未分配任务，finance 当前成员须先领取；所有人工动作仍需真实命令能力、范围、额度和职责分离。
+ * 财务共享一项未分配任务，finance 当前成员须先领取；所有人工动作仍需真实命令能力、范围和职责分离。
  * AI 人工接管保持原节点规则；经理、专业和财务才开放三项管理动作，新实例自动保存允许的加签位置。
  */
 export const poRoute = route('po-approval', [

package/templates/blank/docs/examples/purchase-admin/packages/domain/src/modules/purchase/intelligence.test.ts

@@ -25,7 +25,7 @@ beforeAll(async () => {
   env = await createTestEnv({ domain: { ...purchase, intelligence }, migrations: readMigrations(fileURLToPath(new URL('../../../../../db/migrations/', import.meta.url))) });
   buyer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.create', 'PurchaseOrder.explainPurpose', 'PurchaseOrder.submit', 'PurchaseOrder.setReviewers', 'ApprovalMember.read'],
     scopes: { ApprovalMember: 'all' } });
-  reviewer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.returnForChanges'], scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 50000 } } });
+  reviewer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.returnForChanges'], scopes: { PurchaseOrder: 'dept' } });
   await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: reviewer.id }, env.system());
   await env.kernel.execute('Inventory.create', { sku: 'AI-01', available: 100 }, env.system());
   const role = await env.kernel.execute('Role.create', { code: 'purchase_ai_reviewer', name: '材料预审角色' }, env.system());
@@ -39,12 +39,12 @@ beforeAll(async () => {
 afterAll(() => env?.close());
 
 /**
- * 通过组织和业务命令登记同部门协作人；10 万元额度只供本隔离库验证大额流程，名录本身不授予能力。
+ * 通过组织和业务命令登记同部门协作人；名录本身不授予能力。
  * 专业和财务共享这些真实审批能力，财务候选身份由额外的 finance 角色单独赋予。
  */
 async function collaborator(specialty: string) {
   const user = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.reject', 'PurchaseOrder.returnForChanges'],
-    scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 100000 } } });
+    scopes: { PurchaseOrder: 'dept' } });
   await env.kernel.execute('ApprovalMember.create', { userId: user.id, displayName: specialty, specialty }, env.system());
   return user;
 }
@@ -145,7 +145,7 @@ it('经理后开启所选专业人员 all 会签，全部通过才批准并锁
   expect((await env.query('select status from core.inventory_lock where id=$1', [order.id]))[0].status).toBe('held');
 });
 
-/** gt 阈值必须保持严格大于；恰好 5 万元时经理的同额 ceiling 足够，不创建财务候选任务。 */
+/** gt 阈值必须保持严格大于；恰好 5 万元时不创建财务候选任务。 */
 it('恰好 50000 元经理通过后直接批准，不产生财务候选待办', async () => {
   decision = 'pass'; const order = await submit({ amount: '50000.00' });
   await approveBy(reviewer, order.id);

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/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.3.1",
-    "@yss123/cage-testkit": "0.3.1",
-    "@yss123/cage-lint": "0.3.1",
+    "@yss123/cage-cli": "0.4.0",
+    "@yss123/cage-testkit": "0.4.0",
+    "@yss123/cage-lint": "0.4.0",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/blank/packages/contracts/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.3.1",
+    "@yss123/cage-client": "0.4.0",
     "zod": "^4.1.5"
   }
 }

package/templates/blank/packages/contracts/src/aggregates/role/index.ts

@@ -31,7 +31,7 @@ export const RoleInputs = {
 };
 
 /** Role.archive 可能返回的错误码 */
-export type RoleArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleArchiveError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.create 可能返回的错误码 */
 export type RoleCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** Role.grantCapability 可能返回的错误码 */
@@ -39,7 +39,7 @@ export type RoleGrantCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOM
 /** Role.rename 可能返回的错误码 */
 export type RoleRenameError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.revokeCapability 可能返回的错误码 */
-export type RoleRevokeCapabilityError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type RoleRevokeCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** Role.setScope 可能返回的错误码 */
 export type RoleSetScopeError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/blank/packages/contracts/src/aggregates/user/index.ts

@@ -38,11 +38,11 @@ export type UserAssignRolesError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_
 /** User.create 可能返回的错误码 */
 export type UserCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
 /** User.disable 可能返回的错误码 */
-export type UserDisableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserDisableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.enable 可能返回的错误码 */
-export type UserEnableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserEnableError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.setPassword 可能返回的错误码 */
-export type UserSetPasswordError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+export type UserSetPasswordError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 /** User.update 可能返回的错误码 */
 export type UserUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
 

package/templates/blank/packages/domain/package.json

@@ -14,11 +14,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-kernel": "0.3.1",
-    "@yss123/cage-admin": "0.3.1",
-    "@yss123/cage-approval": "0.3.1",
-    "@yss123/cage-connectors": "0.3.1",
-    "@yss123/cage-ai": "0.3.1",
+    "@yss123/cage-kernel": "0.4.0",
+    "@yss123/cage-admin": "0.4.0",
+    "@yss123/cage-approval": "0.4.0",
+    "@yss123/cage-connectors": "0.4.0",
+    "@yss123/cage-ai": "0.4.0",
     "zod": "^4.1.5"
   }
 }