@yss123/cage-approval 0.2.0 → 0.3.1

package/README.md

@@ -1,19 +1,87 @@
 # @yss123/cage-approval
 
-审批适配接口、桥接与代码内封闭路由（可选）
+Cage 的审批路由与执行包。用代码声明顺序步骤、条件分支、角色/部门负责人选人和会签，提供待办接口、审批历史与结论桥接，也支持 AI 审批步骤。通过、驳回和退回最终调用领域命令，审批引擎不直接修改业务表。
 
-Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
+## 安装
 
-## 使用
+需要 Node.js 24+、PostgreSQL，以及同版本 Cage 框架。在应用 domain 包中安装：
 
 ```powershell
-pnpm add @yss123/cage-approval
+pnpm add @yss123/cage-approval @yss123/cage-kernel
 ```
 
-首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
+标准 `@yss123/cage-http` 装配审批接口，worker 消费审批启动/取消事件。只启动 API 不会完成后台事件消费。
 
-- [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
-- [框架源码与范例](https://github.com/shunshunyue/cage)
-- [问题反馈](https://github.com/shunshunyue/cage/issues)
+## 将已有业务接到审批
 
-许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。
+以下是采购模板可用的组合片段。`PurchaseOrder`、事件和结论命令来自业务文件；结论命令须声明正确的状态迁移、process 调用身份及业务硬约束。
+
+```ts
+/** 将领域事件关联到审批生命周期；路由与绑定的 process 必须相同。 */
+import { approval } from '@yss123/cage-kernel';
+import { approver, gt, route, step, when } from '@yss123/cage-approval';
+import {
+  PurchaseOrder, OrderSubmitted, OrderCancelled, approve, reject,
+} from './purchase-order.js';
+
+/** 提交启动、取消撤回；只允许金额和部门字段用于流程路由。 */
+export const poApproval = approval(PurchaseOrder, {
+  process: 'po-approval',
+  start: OrderSubmitted,
+  cancelOn: [OrderCancelled],
+  routable: ['amount', 'deptId'],
+  onApproved: approve,
+  onRejected: reject,
+});
+
+/** 先部门负责人；金额严格大于 50000 元时，增加财务角色的一人审批。 */
+export const poRoute = route('po-approval', [
+  step('部门经理审批', approver.deptLeader('deptId')),
+  when(
+    gt('amount', 50000),
+    step('财务审批', approver.role('finance'), { mode: 'any' }),
+  ),
+]);
+```
+
+将这两个声明经模块入口从 domain 根入口导出，运行 `pnpm exec cage check` 和 `pnpm gen`，审查迁移后执行 `pnpm migrate`。启动 API/worker，在系统管理中配置真实部门负责人、角色与命令权限；通过提交命令触发业务事件后，从 `/admin/` 的审批待办处理。
+
+`routable` 是允许路由读取的字段清单，不是权限列表。被流程选为审批人也必须具备实际结论命令能力、数据范围及额度，并满足职责分离；路由选人不会自动授予这些权限。
+
+## 主要入口
+
+| 入口 | 用途 |
+| --- | --- |
+| `route`、`step`、`when` | 声明步骤和条件；顺序执行，条件只读取允许路由的字段 |
+| `approver` | 角色、部门负责人等选人规则 |
+| `gt/gte/lt/lte/eq/ne/isIn` | 可被分析的条件表达式 |
+| `InCodeEngine`、`TaskView` | 内置流程执行器及待办视图，通常由 HTTP/worker 装配 |
+| `bindApproval`、`applyOutcome` | 适配器把审批结论桥接回领域命令 |
+| `ApprovalAdapter` 等适配类型 | 对接外部审批实现时遵守的生命周期协议 |
+| `approvalRoutes` | 受认证保护的 HTTP 审批接口装配 |
+| `AiStepOptions`、`approvalRoleContext` | AI 节点配置与自动执行角色上下文 |
+| `TaskActionPolicy`、`TaskActionInput`、`InCodeEngine.act` | 人工节点显式开放转办、委派归还、当前节点并行必签；版本与操作记录共同提交 |
+| `InCodeEngine.taskHistory` | 当前单据授权读者按游标读取人工操作记录 |
+| `approvalOperations()` | 显式启用框架持久站内提醒、申请人催办与已读，复用现有 worker |
+
+领域绑定原语 `approval()` 从 `@yss123/cage-kernel` 导入；不要与本包的路由原语混淆。
+
+AI 审批使用同一个 `step` 的 `kind: 'ai'` 选项，配置模型、材料范围、策略、handoff 和预算；结果为 `pass/return/manual`。需要 domain 启用 `@yss123/cage-ai`，退回需声明 `onReturned`，自动结论需显式配置 `automatedBy` 对应角色权限。模型失败不会被当成自动批准。
+
+## 文档
+
+人工节点可设置 `actions: { transfer: true, delegate: true, addSign: true }`，默认关闭并随流程实例保存。
+委派未归还不能批准；前、后及并行加签在 any/all 模式下都必须全部通过。候选任务先领取再决定，任务操作及启用候选/流转节点的决定须携带 revision。
+不能把任务管理理解为授予角色能力。升级需执行追加系统迁移，旧实例保持原政策。
+
+通用时效通过 `export const approvalOps = approvalOperations()` 启用。人工 `step` 配置 `sla: { durationMinutes: 1440, remindBeforeMinutes: 60 }`，
+`route` 第三参配置 `reminders: { requesterField: 'createdBy', cooldownMinutes: 15 }`，申请人字段必须进入 `approval.routable`。
+框架负责持久提醒、去重、当前接收人授权、冷却和已读；Admin 提供“我的申请”和“流程提醒”，业务应用无需自行实现通知表或定时器。
+节点时限采用自然分钟，加签、转办和领取不重置；尚无工作日历、自动升级、外部通知、并行网关或流程设计器。
+
+- [人工审批任务流转、SDK 与边界](https://github.com/shunshunyue/cage/blob/main/docs/ai/approvals.md)
+- [标准采购审批链路](https://github.com/shunshunyue/cage/blob/main/docs/ai/purchase-example.md)
+- [AI 审批三态、转人工和授权](https://github.com/shunshunyue/cage/blob/main/docs/ai/intelligence.md)
+- [采购审批完整源码](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/modules/purchase/approvals.ts)
+
+源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。

package/dist/ai.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AI 审批的声明协议、受限角色上下文与前向迁移。模型循环在 cage-ai 中执行，
+ * 此模块不直接调用模型、不创建另一套流程；AI 结果仍进入 InCodeEngine 的当前步骤。
+ */
+import { type Ctx, type Kernel } from '@yss123/cage-kernel';
+import type { Approver } from './route.js';
+/** AI 是步骤执行类型，handoff 仅指定本步骤的接管人，不嵌入第二条流程。 */
+export interface AiStepOptions {
+    kind: 'ai';
+    /** 应用 AI 配置中的模型名，不在业务声明中保存供应商密钥。 */
+    model: string;
+    /** 节点审核政策；表达判定要求，不赋予超出自动角色的工具或数据权限。 */
+    instructions: string;
+    /** 允许取证的字段与已注册只读查询，字段须公开且实际访问仍受角色授权约束。 */
+    context: {
+        fields: readonly string[];
+        queries?: readonly string[];
+    };
+    /** 当前步骤转人工时的选人策略；不是另起一条无关审批流程。 */
+    handoff: Approver;
+    /** 单次执行预算：步骤数、工具调用数、token 数和毫秒超时，均应为正整数。 */
+    limits?: {
+        maxSteps?: number;
+        maxToolCalls?: number;
+        tokenBudget?: number;
+        timeoutMs?: number;
+    };
+    /** 模型/工具失败后的处理政策；故障不等同于正常通过。 */
+    onFailure?: 'manual' | 'failed';
+}
+export interface AiStep extends AiStepOptions {
+    title: string;
+}
+/** 三态审核结果；pass 只通过本节点，return 走领域退回命令，manual 生成本节点人工待办。 */
+export interface AiDecision {
+    decision: 'pass' | 'return' | 'manual';
+    reason: string;
+    suggestions: string[];
+    evidence: {
+        source: string;
+        detail: string;
+    }[];
+}
+/** 角色授权只赋予流程服务主体；不借用用户身份，也不继承 systemCtx 的全部范围。 */
+/**
+ * 每次从当前租户的 active 角色解析能力/范围/明文权限，不缓存旧授权、不借用真人身份。
+ * 角色缺失或未配置立即 FORBIDDEN；因为没有部门上下文，范围政策不能假定自动主体属于某个部门。
+ */
+export declare function approvalRoleContext(kernel: Kernel, process: string, tenantId: string): Promise<Ctx>;
+/** 追加迁移，保留原 FLOW_DDL 的已发布内容。 */
+/** 节点记录保存针对的提交版本、run 归属、判定及可见性证据；同实例/步骤唯一，防重复占位。 */
+export declare const APPROVAL_AI_MIGRATION: {
+    name: string;
+    sql: string;
+};

package/dist/ai.js

@@ -0,0 +1,51 @@
+/**
+ * AI 审批的声明协议、受限角色上下文与前向迁移。模型循环在 cage-ai 中执行，
+ * 此模块不直接调用模型、不创建另一套流程；AI 结果仍进入 InCodeEngine 的当前步骤。
+ */
+import { cageError, mergeCaps, mergeScopes, unmaskFrom } from '@yss123/cage-kernel';
+/** 角色授权只赋予流程服务主体；不借用用户身份，也不继承 systemCtx 的全部范围。 */
+/**
+ * 每次从当前租户的 active 角色解析能力/范围/明文权限，不缓存旧授权、不借用真人身份。
+ * 角色缺失或未配置立即 FORBIDDEN；因为没有部门上下文，范围政策不能假定自动主体属于某个部门。
+ */
+export async function approvalRoleContext(kernel, process, tenantId) {
+    const binding = kernel.registry.approvalByProcess(process)?.a;
+    if (!binding?.automatedBy)
+        throw cageError('FORBIDDEN', { reason: '审批未配置自动执行角色' });
+    const role = await kernel.app.selectFrom('sys.role').select(['capabilities', 'scopes']).where('tenant_id', '=', tenantId)
+        .where('code', '=', binding.automatedBy).where('status', '=', 'active').executeTakeFirst();
+    if (!role)
+        throw cageError('FORBIDDEN', { reason: '自动执行角色不存在或已禁用' });
+    const capabilities = mergeCaps([role]);
+    return { actor: { kind: 'process', id: `process:${process}:role:${binding.automatedBy}` }, userId: null, tenantId,
+        deptId: null, deptPath: null, capabilities, scopes: mergeScopes([role]), unmask: unmaskFrom(capabilities), source: 'process' };
+}
+/** 追加迁移，保留原 FLOW_DDL 的已发布内容。 */
+/** 节点记录保存针对的提交版本、run 归属、判定及可见性证据；同实例/步骤唯一，防重复占位。 */
+export const APPROVAL_AI_MIGRATION = {
+    name: 'cage:approval_ai_001',
+    sql: `
+ALTER TABLE flow.approval_instance ADD COLUMN subject_version integer;
+ALTER TABLE flow.approval_instance ADD COLUMN start_event_id bigint;
+ALTER TABLE flow.approval_instance ADD COLUMN last_actor jsonb;
+CREATE TABLE flow.approval_step (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL,
+  instance_id uuid NOT NULL REFERENCES flow.approval_instance(id),
+  step integer NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('human','ai')),
+  status text NOT NULL,
+  expected_version integer,
+  run_id uuid,
+  decision jsonb,
+  decision_visibility jsonb,
+  actor jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE(instance_id, step)
+);
+CREATE INDEX approval_step_queue_idx ON flow.approval_step(status, created_at) WHERE kind = 'ai';
+GRANT SELECT, INSERT, UPDATE ON flow.approval_step TO cage_app;
+`,
+};
+//# sourceMappingURL=ai.js.map

package/dist/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAyB,MAAM,qBAAqB,CAAC;AA4B3G,kDAAkD;AAClD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAAe,EAAE,QAAgB;IACzF,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,WAAW;QAAE,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IACnF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,QAAQ,CAAC;SACtH,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,gBAAgB,EAAE,CAAC;IAC7F,IAAI,CAAC,IAAI;QAAE,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IACrE,MAAM,YAAY,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,OAAO,SAAS,OAAO,CAAC,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ;QAC/G,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACnI,CAAC;AAED,gCAAgC;AAChC,oDAAoD;AACpD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,sBAAsB;IAC5B,GAAG,EAAE;;;;;;;;;;;;;;;;;;;;;;CAsBN;CACA,CAAC"}

package/dist/bridge.d.ts

@@ -1,6 +1,12 @@
-import type { Kernel } from '@yss123/cage-kernel';
+import { type Kernel } from '@yss123/cage-kernel';
 import type { Transaction } from 'kysely';
 import type { ApprovalAdapter, ApprovalOutcome } from './types.js';
+/**
+ * 从流程绑定选择通过/驳回/退回命令，再为结论构造可信 process 上下文。
+ * 人工结论实时核对最后审批人的命令能力与单据可见性；自动结论使用受限角色，不能继承系统全部范围。
+ * 传 tx 时与待办决定共同回滚，未传时命令自行开事务；expectedVersion 阻止迟到结论覆盖新版本。
+ */
 export declare function applyOutcome(k: Kernel, r: ApprovalOutcome, tx?: Transaction<any>): Promise<Record<string, any>>;
 /** 外部引擎（例如独立部署的 Warm-Flow、Flowable 服务）：它的结论通过回调进入这里 */
+/** 只登记结束回调，不创建外部流程或授予回调来源信任；适配器须自行完成其协议认证和投递可靠性。 */
 export declare function bindApproval(adapter: ApprovalAdapter, k: Kernel): void;

package/dist/bridge.js

@@ -1,17 +1,38 @@
+// 桥接：引擎的结论只能转成命令，以流程身份调用，走完整 12 关。引擎侧没有任何业务表的数据库权限。
+import { cageError, loadUserGrants, userCtx } from '@yss123/cage-kernel';
+import { approvalRoleContext } from './ai.js';
+/**
+ * 从流程绑定选择通过/驳回/退回命令，再为结论构造可信 process 上下文。
+ * 人工结论实时核对最后审批人的命令能力与单据可见性；自动结论使用受限角色，不能继承系统全部范围。
+ * 传 tx 时与待办决定共同回滚，未传时命令自行开事务；expectedVersion 阻止迟到结论覆盖新版本。
+ */
 export async function applyOutcome(k, r, tx) {
     const binding = k.registry.approvalByProcess(r.process);
     if (!binding)
         throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
-    const cmd = r.outcome === 'approved' ? binding.a.onApproved : binding.a.onRejected;
-    const ctx = k.processCtx({
-        process: r.process,
-        tenantId: r.tenantId,
-        onBehalfOf: r.lastApprover,
-        capabilities: [k.registry.capabilityOf(binding.a.onApproved), k.registry.capabilityOf(binding.a.onRejected)],
-    });
-    return tx ? k.executeIn(tx, cmd, { id: r.businessKey }, ctx, 0) : k.execute(cmd, { id: r.businessKey }, ctx);
+    const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+    if (!cmd)
+        throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+    let ctx;
+    if (r.lastApprover) {
+        // 待办决定已持有事务连接时复用它；同实例并发排队不能耗尽池后让锁持有者再等新连接。
+        const grants = await loadUserGrants(tx ?? k.app, r.lastApprover, r.tenantId);
+        const user = grants ? userCtx(grants) : null;
+        if (!user?.capabilities.has(k.registry.capabilityOf(cmd)) || !user.capabilities.has(`${binding.a.agg.name}.read`))
+            throw cageError('FORBIDDEN');
+        // 先核验真人对目标单据的权限；命令内声明的后台读依赖仍按已有流程身份完成业务校验。
+        const visible = await k.read.tx(user, read => read.selectFrom(`safe.${binding.a.agg.table.name}`).select('id').where('id', '=', r.businessKey).executeTakeFirst());
+        if (!visible)
+            throw cageError('NOT_FOUND');
+        ctx = k.processCtx({ process: r.process, tenantId: r.tenantId, onBehalfOf: r.lastApprover, capabilities: [k.registry.capabilityOf(cmd)] });
+    }
+    else
+        ctx = await approvalRoleContext(k, r.process, r.tenantId);
+    const input = { id: r.businessKey, expectedVersion: r.expectedVersion };
+    return tx ? k.executeIn(tx, cmd, input, ctx, 0) : k.execute(cmd, input, ctx);
 }
 /** 外部引擎（例如独立部署的 Warm-Flow、Flowable 服务）：它的结论通过回调进入这里 */
+/** 只登记结束回调，不创建外部流程或授予回调来源信任；适配器须自行完成其协议认证和投递可靠性。 */
 export function bindApproval(adapter, k) {
     adapter.onCompleted(async (r) => {
         await applyOutcome(k, r);

package/dist/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,CAAS,EAAE,CAAkB,EAAE,EAAqB;IACrF,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IACnF,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,UAAU,EAAE,CAAC,CAAC,YAAY;QAC1B,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;KAC7G,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;AAC/G,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,OAAwB,EAAE,CAAS;IAC9D,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/deadlines.d.ts

@@ -0,0 +1,29 @@
+import { type Transaction } from 'kysely';
+/** 自然分钟时限；允许小数，精度至少一毫秒，最长一年，不包含工作日历或暂停扣时。 */
+export interface ApprovalSla {
+    /** 从进入节点起计算的总办理分钟数，前后加签共用这一截止时间。 */
+    durationMinutes: number;
+    /** 在截止前多少分钟产生临期提醒；省略只提醒超时，必须小于总时限。 */
+    remindBeforeMinutes?: number;
+}
+/** 申请人催办政策随实例冻结；字段只标识申请人，不授予其审批结论能力。 */
+export interface ApprovalReminderPolicy {
+    /** routable 快照中的单个用户 UUID 字段，运行时还需当前用户有效且可见业务单据。 */
+    requesterField: string;
+    /** 两次成功催办间隔的自然分钟数，同实例各节点共用冷却；无收件人不占用冷却。 */
+    cooldownMinutes: number;
+}
+/** 校验并冻结节点政策；未知键和不合理提前量明确报声明错误，不把配置失误静默当作关闭提醒。 */
+export declare function approvalSla(value: ApprovalSla): Readonly<ApprovalSla>;
+/** 校验申请人字段名与正数冷却；真正的字段存在性、routable 和公开性在注册表装配后再检查。 */
+export declare function approvalReminderPolicy(value: ApprovalReminderPolicy): Readonly<ApprovalReminderPolicy>;
+/**
+ * 在进入人工节点的同一事务登记固定截止时间；使用数据库时间，服务重启不会丢失或重新计时。
+ * next_notice_scan_at 是有界扫描的持久轮转位置，后续收件人变化可补投，不让已提醒的旧步骤长期占满扫描批次。
+ */
+export declare function initializeDeadline(tx: Transaction<any>, instanceId: string, step: number, policy: ApprovalSla): Promise<void>;
+/** 前向迁移：时间只新增到节点，通知以来源/任务/接收人唯一；已读不删除历史，禁止修改已发布迁移。 */
+export declare const APPROVAL_DEADLINES_MIGRATION: {
+    name: string;
+    sql: string;
+};

package/dist/deadlines.js

@@ -0,0 +1,72 @@
+/**
+ * 人工节点的自然时间办理政策及持久存储，由 route 校验声明、engine 在进入节点时写入。
+ * 时限属于整个节点：领取、转办、委派和前后加签均不重置；这里只计时，不替代领域结论或自动批准。
+ * 迁移在已发布审批表之上追加，旧实例没有时限或催办政策，升级不会自动启用新行为。
+ */
+import { declError } from '@yss123/cage-kernel';
+import { sql } from 'kysely';
+import { z } from 'zod';
+const minutes = z.number().finite().min(1 / 60_000).max(525_600);
+const slaSchema = z.strictObject({ durationMinutes: minutes, remindBeforeMinutes: minutes.optional() })
+    .refine(value => value.remindBeforeMinutes === undefined || Math.round(value.remindBeforeMinutes * 60_000) < Math.round(value.durationMinutes * 60_000));
+const reminderSchema = z.strictObject({ requesterField: z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/), cooldownMinutes: minutes });
+/** 校验并冻结节点政策；未知键和不合理提前量明确报声明错误，不把配置失误静默当作关闭提醒。 */
+export function approvalSla(value) {
+    const parsed = slaSchema.safeParse(value);
+    if (!parsed.success)
+        throw declError('CAGE-APPR-006', 'sla 须为有效自然分钟时限（至少一毫秒，最长一年），提前提醒必须小于总时限');
+    return Object.freeze(parsed.data);
+}
+/** 校验申请人字段名与正数冷却；真正的字段存在性、routable 和公开性在注册表装配后再检查。 */
+export function approvalReminderPolicy(value) {
+    const parsed = reminderSchema.safeParse(value);
+    if (!parsed.success)
+        throw declError('CAGE-APPR-006', 'reminders 需要有效 requesterField 和自然分钟 cooldownMinutes（至少一毫秒，最长一年）');
+    return Object.freeze(parsed.data);
+}
+/**
+ * 在进入人工节点的同一事务登记固定截止时间；使用数据库时间，服务重启不会丢失或重新计时。
+ * next_notice_scan_at 是有界扫描的持久轮转位置，后续收件人变化可补投，不让已提醒的旧步骤长期占满扫描批次。
+ */
+export async function initializeDeadline(tx, instanceId, step, policy) {
+    const duration = Math.round(policy.durationMinutes * 60_000);
+    const before = policy.remindBeforeMinutes === undefined ? null : Math.round(policy.remindBeforeMinutes * 60_000);
+    await tx.updateTable('flow.approval_step').set({
+        due_at: sql `now() + ${duration} * interval '1 millisecond'`,
+        remind_at: before === null ? null : sql `now() + ${duration - before} * interval '1 millisecond'`,
+        next_notice_scan_at: sql `now() + ${duration - (before ?? 0)} * interval '1 millisecond'`,
+    }).where('instance_id', '=', instanceId).where('step', '=', step).execute();
+}
+/** 前向迁移：时间只新增到节点，通知以来源/任务/接收人唯一；已读不删除历史，禁止修改已发布迁移。 */
+export const APPROVAL_DEADLINES_MIGRATION = {
+    name: 'cage:approval_deadlines_003',
+    sql: `
+ALTER TABLE flow.approval_instance ADD COLUMN reminder_policy jsonb;
+ALTER TABLE flow.approval_instance ADD COLUMN next_urge_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN due_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN remind_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN next_notice_scan_at timestamptz;
+ALTER TABLE flow.approval_step ADD CONSTRAINT approval_step_deadline_order CHECK (remind_at IS NULL OR (due_at IS NOT NULL AND remind_at < due_at));
+CREATE INDEX approval_step_notice_scan_idx ON flow.approval_step(next_notice_scan_at, instance_id) WHERE next_notice_scan_at IS NOT NULL;
+CREATE TABLE flow.approval_notice (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  instance_id uuid NOT NULL REFERENCES flow.approval_instance(id),
+  task_id uuid NOT NULL REFERENCES flow.approval_task(id),
+  step integer NOT NULL,
+  recipient_id uuid NOT NULL,
+  source text NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('due_soon','overdue','urge')),
+  actor_id uuid,
+  reason text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  read_at timestamptz,
+  UNIQUE(instance_id, step, source, task_id, recipient_id)
+);
+CREATE INDEX approval_notice_recipient_idx ON flow.approval_notice(tenant_id, recipient_id, id);
+CREATE INDEX approval_notice_unread_idx ON flow.approval_notice(tenant_id, recipient_id, id) WHERE read_at IS NULL;
+GRANT SELECT, INSERT, UPDATE ON flow.approval_notice TO cage_app;
+GRANT USAGE, SELECT ON SEQUENCE flow.approval_notice_id_seq TO cage_app;
+`,
+};
+//# sourceMappingURL=deadlines.js.map

package/dist/deadlines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadlines.js","sourceRoot":"","sources":["../src/deadlines.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -1,7 +1,16 @@
-import { type Kernel } from '@yss123/cage-kernel';
+/**
+ * 原生结构化审批执行器：实例、AND 分支、候选/直派任务及签署阶段存在 flow 模式，结论经桥接调用领域命令。
+ * HTTP、worker 和 AI 运行时共用本入口；按实例锁串行决定，前后签激活与最后结论共同事务提交。
+ * waiting 不是完成；任务选人不授予能力，最后命令拒绝（如超额度）会回滚本次决定及附带变化。
+ */
+import { type Kernel, type Ctx } from '@yss123/cage-kernel';
 import { type ApprovalEngine } from '@yss123/cage-kernel/worker';
 import { type Transaction } from 'kysely';
 import { type Route } from './route.js';
+import { type BranchLocation } from './execution.js';
+import { type AiDecision } from './ai.js';
+import { type TaskActionInput, type TaskActionPolicy } from './task-actions.js';
+/** 对外待办摘要；step 为 0 基索引，vars 仅来自 routable 白名单，不包含整份领域对象。 */
 export interface TaskView {
     id: string;
     instanceId: string;
@@ -10,36 +19,161 @@ export interface TaskView {
     businessKey: string;
     step: number;
     title: string;
+    /** 所属并行组/分支路径；普通主线或旧顺序实例为空数组，不把索引大小当作实际执行先后。 */
+    branchPath: BranchLocation[];
     status: string;
     vars: Record<string, unknown>;
     createdAt: string;
+    /** 节点总办理截止 UTC 时间；无 SLA 为 null，waiting 或转办不重置，不代表自动批准时间。 */
+    dueAt: string | null;
+    /** 待办版本，启用任务流转的节点提交决定时也必须携带。 */
+    revision: number;
+    /** 当前持有人；候选池待领取时为空。 */
+    assigneeId: string | null;
+    /** direct 直接分配，candidate 允许当前候选领取/持有人释放。 */
+    assignment: 'direct' | 'candidate';
+    /** 加签来源任务；旧并行加签和原始任务可为空。 */
+    parentTaskId: string | null;
+    /** 相对父任务的签署顺序；null 表示原票或旧版未记录签序。 */
+    signPosition: 'parallel' | 'before' | 'after' | null;
+    /** 实例允许的新加签位置；未开放为 []，第一批旧快照仅 parallel，不表示本任务可以再次加签。 */
+    signPositions: readonly ('parallel' | 'before' | 'after')[];
+    /** 委派原负责人；未委派或已转办时为空。 */
+    ownerId: string | null;
+    /** pending 表示受托处理中，只能归还；resolved 表示已归还原负责人。 */
+    delegation: 'pending' | 'resolved' | null;
+    /** original 是路由选人，additional 是节点前后/并行追加必签。 */
+    taskKind: 'original' | 'additional';
+    /** 实例快照中的动作政策，仅供界面显示；服务端仍会实时授权。 */
+    actions: Readonly<TaskActionPolicy>;
 }
+/**
+ * 有限无环路由的持久执行器：实例冻结展开步骤与依赖，人工任务和 AI 节点共享同一推进/结束边界。
+ * 以实例行锁串行化决定，最后结论与领域命令共同事务提交；命令失败时本次审批也不能算完成。
+ */
 export declare class InCodeEngine implements ApprovalEngine {
     private readonly k;
     readonly route: Route;
     constructor(k: Kernel, route: Route);
-    private approversOf;
+    /**
+     * 执行候选领取/释放或本人待办转办/委派/归还/前后加签；必需任务版本与原因，失败不会部分更新。
+     * 分配或动作政策须显式启用，接收人须已有批准和读取权限；返回版本及新任务 ID，不推进领域状态。
+     */
+    act(taskId: string, userId: string, tenantId: string, input: TaskActionInput): Promise<import("./task-actions.js").TaskActionResult>;
+    /** 登记当前节点与提交版本；AI 节点排队等待运行时领取，人工节点立即解析候选并创建待办。 */
     private openStep;
+    /** direct 逐人建立票，candidate 只建一项未领取任务；空候选明确报错，不跳过或默认通过。 */
+    private openTasks;
+    /**
+     * 在消费事务中创建新轮次：先取消旧执行者，再保存展开步骤和触发事件/提交版本。
+     * 事件版本已落后于当前对象时标 superseded 而不创建新待办，防止迟到提交事件审核过期内容。
+     */
     start(input: {
         process: string;
         businessKey: string;
         tenantId: string;
         vars: Record<string, unknown>;
         tx: Transaction<any>;
+        subjectVersion?: number;
+        eventId?: number;
     }): Promise<{
         instanceId: string;
     }>;
+    /** 关闭同租户/流程/对象的 running 轮次、未决待办和可运行 AI 节点，已完成历史保持可追溯。 */
     cancel(input: {
         process: string;
         businessKey: string;
         tenantId: string;
         tx: Transaction<any>;
     }): Promise<void>;
-    /** 我的待办 */
+    /**
+     * 从本人最近 200 条任务候选中按当前单据 read/范围过滤，撤权或停用后不继续披露任务摘要。
+     * vars 是历史 routable 摘要，始终去隐藏字段并掩码；需要明文时另经带审计的业务读接口获取。
+     */
     tasksOf(userId: string, tenantId: string, status?: string): Promise<TaskView[]>;
+    /**
+     * 查询最近 200 项未领取候选中的可见任务；当前候选身份与批准/read 权限均需成立。
+     * 列表不是占用承诺，领取必须再次锁定并校验；待领取任务不会混入 tasksOf/AI 的可决定清单。
+     */
+    candidateTasks(userId: string, tenantId: string): Promise<TaskView[]>;
+    /** 共用安全摘要投影；候选规则在读取时解析，组织变化即时影响候选清单，历史变量仍始终掩码。 */
+    private listTasks;
+    /** 以业务对象读权限查看审批轮次；步骤标题取提交时的快照，隐藏内部 policy、提示词、工具历史和运行凭据。 */
+    history(aggregate: string, businessKey: string, ctx: Ctx): Promise<{
+        id: any;
+        process: string;
+        status: any;
+        currentStep: any;
+        currentSteps: any[];
+        definitionVersion: string | null;
+        createdAt: string;
+        updatedAt: string;
+        steps: {
+            index: any;
+            title: string;
+            branchPath: BranchLocation[];
+            dependsOn: number[];
+            kind: any;
+            status: any;
+            decision: any;
+            detailRestricted: boolean;
+            actor: any;
+            updatedAt: string;
+            dueAt: string | null;
+        }[];
+    }[]>;
+    /**
+     * 按业务对象当前 read/范围读取本流程的人工操作记录，跨轮次以递增 ID 游标分页。
+     * after 是服务端返回的十进制字符串，避免 bigint 转为 JS number 丢失精度；默认 50、最多 200 条。
+     * 历史意见仅供同一对象的授权读者共享，不返回任务变量或 AI 提示词；旧迁移前的动作不会伪造补录。
+     */
+    taskHistory(aggregate: string, businessKey: string, ctx: Ctx, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        items: {
+            id: string;
+            instanceId: any;
+            taskId: any;
+            actorId: any;
+            action: any;
+            reason: any;
+            details: any;
+            createdAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
     /** 审批人做出决定；流程结束时在同一事务里执行结论命令 */
-    decide(taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected', comment?: string): Promise<{
+    decide(taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string, expectedRevision?: number): Promise<{
+        finished: boolean;
+        outcome?: string;
+    }>;
+    /** AI 助理的动作回执可与人工待办决定共用该事务，重试不重复审批。 */
+    /**
+     * 先按租户/受托人定位任务，再锁实例和任务并实时验证能力/单据可见性；过期待办不允许再次决定。
+     * 委派未归还或 waiting 时拒绝决定；候选/启用流转的节点要求 revision，避免责任或阶段变化后旧决定仍生效。
+     * 驳回/退回直接结束；all 等待全部，any 等任一原票及全部追加票；批准后激活已满足依赖的前后签。
+     * 外层拥有事务提交权，可与 AI 助理动作回执共同提交；finished:false 仅表示流程还需后续步骤。
+     */
+    decideIn(tx: Transaction<any>, taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string, expectedRevision?: number): Promise<{
         finished: boolean;
         outcome?: string;
     }>;
+    /** 先执行带版本的领域结论命令，成功后才关闭剩余待办并写流程终态，保证两边不会各自成功。 */
+    private finish;
+    /**
+     * 在实例锁内完成一项节点，再开启所有前驱已通过且尚无持久记录的节点；AND 汇合等待每条分支末端。
+     * 创建节点和最终领域结论都在当前事务内，失败回滚本次签署；重启只依赖数据库状态，唯一键阻止重复节点。
+     * current_step 仅保留最小活跃索引给旧读者，决定、AI 与提醒均以节点自身状态为准。
+     */
+    private advance;
+    /** 只有仍然占据该节点的 run 能提交；调用方需在同一事务核验 AI run 租约。 */
+    /**
+     * 锁定实例、节点和业务对象，校验 run 仍占据当前节点且对象版本未变；旧轮次/旧 run 回执一律冲突。
+     * 保存判定时同时保存敏感明文/查询范围证据，history 据此决定后来读者能否查看理由。
+     * manual 仅开人工接管待办；return/ pass 分别进入共同 finish/advance，保持领域命令约束不变。
+     */
+    completeAi(tx: Transaction<any>, stepId: string, runId: string, decision: AiDecision, actor?: Ctx): Promise<{
+        finished: boolean;
+    }>;
 }