create-windy 0.1.0

package/template/apps/web/src/style.css

@@ -0,0 +1,142 @@
+@import "tailwindcss";
+
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  font-family:
+    Inter,
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+}
+
+@theme inline {
+  --font-heading: var(--font-sans);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  html,
+  body,
+  #app {
+    @apply bg-background text-foreground;
+    min-height: 100%;
+  }
+  body,
+  #app {
+    min-height: 100svh;
+  }
+}

package/template/apps/web/src/style.webtest.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "vitest";
+// @ts-expect-error Vitest runs this contract test in Node; the browser bundle omits Node types.
+import { readFileSync } from "node:fs";
+// @ts-expect-error Vitest runs this contract test in Node; the browser bundle omits Node types.
+import { resolve } from "node:path";
+
+declare const process: { cwd(): string };
+
+const styles = readFileSync(resolve(process.cwd(), "src/style.css"), "utf8");
+
+describe("全局页面背景", () => {
+  test("html、body 与应用根节点共同使用主题背景，避免深色滚动露白", () => {
+    expect(styles).toMatch(
+      /html,\s*body,\s*#app\s*{\s*@apply bg-background text-foreground;/,
+    );
+    expect(styles).toMatch(/body,\s*#app\s*{\s*min-height: 100svh;/);
+  });
+});

package/template/apps/web/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "useDefineForClassFields": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "strict": true,
+    "jsx": "preserve",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}

package/template/apps/web/vite.config.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath, URL } from "node:url";
+import tailwindcss from "@tailwindcss/vite";
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+import { projectFingerprint, windyDevIdentityPlugin } from "./dev/dev-identity";
+
+const fingerprint =
+  process.env.WINDY_DEV_FINGERPRINT || projectFingerprint(process.cwd());
+const devPort = Number(process.env.WINDY_DEV_PORT || 8_746);
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss(), windyDevIdentityPlugin(fingerprint)],
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+  server: {
+    host: process.env.VITE_DEV_HOST ?? "127.0.0.1",
+    port: devPort,
+    strictPort: true,
+    proxy: {
+      "/api": process.env.API_UPSTREAM ?? "http://localhost:3000",
+    },
+  },
+});

package/template/apps/web/vitest.config.ts

@@ -0,0 +1,14 @@
+import { mergeConfig, defineConfig } from "vitest/config";
+import viteConfig from "./vite.config";
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      environment: "happy-dom",
+      include: ["src/**/*.webtest.ts"],
+      clearMocks: true,
+      restoreMocks: true,
+    },
+  }),
+);

package/template/bunfig.toml

@@ -0,0 +1,2 @@
+[workspace]
+packages = ["apps/*", "packages/*"]

package/template/docker-compose.yml

@@ -0,0 +1,74 @@
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: windy
+      POSTGRES_USER: windy
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?请在 .env 中设置 POSTGRES_PASSWORD}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U windy -d windy"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  migrate:
+    build:
+      context: .
+      dockerfile: apps/server/Dockerfile
+    command: ["bun", "run", "db:migrate"]
+    environment:
+      DATABASE_URL: postgresql://windy:${POSTGRES_PASSWORD}@postgres:5432/windy
+    volumes:
+      - ./packages:/app/packages
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  server:
+    build:
+      context: .
+      dockerfile: apps/server/Dockerfile
+    command: ["bun", "run", "--cwd", "apps/server", "dev"]
+    environment:
+      NODE_ENV: development
+      PORT: 3000
+      DATABASE_URL: postgresql://windy:${POSTGRES_PASSWORD}@postgres:5432/windy
+      WINDY_BOOTSTRAP_ADMIN_PASSWORD: ${WINDY_BOOTSTRAP_ADMIN_PASSWORD:?请在 .env 中设置管理员初始密码}
+      WINDY_AUDIT_QUEUE_FILE: /app/data/audit/recovery-queue.json
+      WINDY_CONTAINERIZED: "1"
+      WINDY_SYSTEM_USAGE_PATHS: /app/data/audit
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./apps/server:/app/apps/server
+      - ./packages:/app/packages
+      - server-audit-data:/app/data/audit
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+    command: ["bun", "run", "--cwd", "apps/web", "dev"]
+    environment:
+      NODE_ENV: development
+      WINDY_DEV_PORT: 9746
+      API_UPSTREAM: http://server:3000
+      VITE_DEV_HOST: 0.0.0.0
+    ports:
+      - "9746:9746"
+    volumes:
+      - ./apps/web:/app/apps/web
+      - ./packages:/app/packages
+    depends_on:
+      - server
+
+volumes:
+  postgres-data:
+  server-audit-data:

package/template/docs/adapters/ruoyi-vue-compatibility.md

@@ -0,0 +1,93 @@
+# RuoYi-Vue 兼容与迁移设计
+
+## 背景
+
+Windy Platform Template 需要替代两个现有 RuoYi-Vue 项目。存量项目为 Vue2 版本，运行依赖 MySQL 和 Redis。迁移目标以一次性导入新库为主，但在客户单机服务器场景中，仍需要具备连接旧 MySQL / Redis 运行的能力。
+
+密码不要求兼容旧 hash，迁移后可以统一重置密码。兼容重点是系统数据、权限链路、菜单路由、日志审计和后台能力闭环。
+
+## 设计结论
+
+采用“新平台 canonical schema + 可插拔 RuoYi-Vue Adapter”的方案。
+
+新项目默认不启用 RuoYi-Vue 兼容能力。旧项目通过独立 Adapter 接入迁移或运行时兼容，业务模块不得直接依赖旧 `sys_*` 表，也不得把 RuoYi-Vue 字段设计扩散到平台核心模型。
+
+## 兼容层职责
+
+RuoYi-Vue 兼容层是一个独立 Module，向平台暴露小而稳定的 Interface，内部隐藏旧库结构、字段差异、状态映射和迁移细节。
+
+兼容层至少包含三类 Adapter：
+
+- `import adapter`：从旧 MySQL 一次性导入用户、角色、部门、菜单、权限、字典、参数、通知、日志和任务数据。
+- `legacy runtime adapter`：在客户单机服务器过渡期连接旧 MySQL / Redis；本轮只允许只读能力，受控写入明确延期。
+- `report adapter`：输出 dry-run、迁移差异、失败行、权限映射、菜单树映射和回滚建议。
+
+## 迁移对象
+
+第一阶段迁移 RuoYi-Vue 的系统基础表：
+
+- 用户、角色、用户角色关系。
+- 部门、岗位、用户岗位关系。
+- 菜单、按钮权限、角色菜单关系。
+- 角色部门关系和数据权限范围。
+- 字典类型、字典数据。
+- 参数配置、通知公告。
+- 登录日志、操作日志。
+- 定时任务定义和任务执行日志。
+
+任务执行器、在线用户、服务监控、缓存监控不能直接迁移实现，只迁移必要配置和历史记录，运行时能力由新平台重新实现。
+
+## 权限与菜单
+
+权限链路是迁移验收重点。迁移后，同一个用户应尽量保持原有菜单可见性、按钮权限和部门数据范围。
+
+兼容层必须显式处理：
+
+- 超级管理员规则。
+- 用户启用/停用/删除状态。
+- 角色启用/停用状态。
+- 目录、菜单、按钮三类菜单节点。
+- 路由路径、组件路径、权限标识、图标、排序、显示/隐藏。
+- 角色菜单授权和角色部门数据范围。
+
+新平台内部可以拆分导航、权限、路由绑定、模块绑定和功能开关，但迁移报告必须能追踪到原始 RuoYi-Vue 行。
+
+## 运行时兼容
+
+运行时兼容只服务旧项目过渡，不作为新项目默认路径。
+
+在客户单机服务器上允许配置旧 MySQL / Redis 连接，用于：
+
+- 读取旧系统基础数据。
+- 对比新旧权限和菜单差异。
+- 迁移前 dry-run。
+- 必要时短期读取旧日志或旧配置。
+
+默认不允许新业务直接写旧库。旧库运行时受控写入、双写、补偿和 Redis 运行态兼容已明确延期；当前只保留未来 Adapter 边界，不实现写接口。
+
+## 若依能力吸收
+
+新底座应吸收 RuoYi-Vue 的产品闭环思路，而不是复刻其实现。
+
+优先吸收：
+
+- 用户、部门、岗位、角色、菜单、字典、参数、通知公告。
+- 操作日志、登录日志、在线用户。
+- 服务监控、缓存监控、数据库连接状态。
+- 定时任务和执行日志。
+- 代码生成或 CRUD 生成。
+- 系统接口文档。
+
+每个业务 Module 默认具备列表、查询、详情、新增、编辑、删除、导入、导出、权限、审计和错误闭环。
+
+当前平台已提供 `/api/system/operations` 和 Web 端 `/system/operations` 运维总览入口，用于承接在线用户、服务监控、缓存监控、定时任务、代码生成和系统接口这些闭环能力的产品位置。平台 Redis 探活、任务调度执行器、canonical CRUD 代码生成器和基于已注册 Module Manifest 的接口权限明细已接入；它们属于平台 canonical 能力，不等于启用本轮明确延期的 RuoYi 旧库运行时受控写入或旧 Redis 兼容。
+
+## 验收标准
+
+- 新项目可以完全不安装、不配置 RuoYi-Vue 兼容层。
+- 旧项目可以从 RuoYi-Vue MySQL 执行 dry-run，并得到迁移报告。
+- 用户、角色、部门、菜单、按钮权限和数据权限可以一次性导入新库。
+- 迁移后可对比指定用户在新旧系统中的菜单树和权限标识。
+- 迁移过程不要求兼容旧密码 hash，可统一重置密码。
+- 单机部署时可以配置旧 MySQL / Redis 连接用于过渡兼容。
+- 当前所有兼容读取必须经过 Adapter，并写入审计日志；受控写入重新立项后另行定义验收标准。

package/template/docs/architecture/admin-surface-boundary.md

@@ -0,0 +1,24 @@
+# 管理面准入与业务面隔离
+
+Windy Web 是 Platform Core 的管理控制面，只服务平台管理员、运维人员和授权审计人员。普通业务账号即使拥有某个业务 Module 的 API 权限，也不能进入 Windy AppShell。业务应用应拥有独立品牌、首页、导航、域名和工作区，并通过受 Guard 保护的 Windy Server API 使用平台能力。
+
+## 准入契约
+
+- `system.admin` Feature 表示 Windy 管理面能力，`system.admin.access` Permission 表示进入管理面的明确授权。
+- Web 在进入任意 AppShell 路由前调用 `GET /api/admin/bootstrap`；这包括没有页面级 Guard 的 `/` 根路由。
+- Server 按 License、Feature、Permission 顺序执行 Guard。License 限制期只放行这次准入判定本身，成功后 Web 仍会进入 License 恢复页，不能访问其它管理 API。
+- bootstrap 只返回 Module Manifest 声明的 Admin Route、与这些路由匹配的菜单树，以及管理面完成 RBAC/Feature 判断所需的元数据；不返回业务资源数据。
+- 缺少准入权限返回 403。Web 拒绝页不提供“返回工作台”，只允许退出登录，以及在配置 `VITE_BUSINESS_APP_URL` 时进入外部业务应用。
+
+## Module composition seam
+
+`ModuleManifest.adminRoutes` 是业务能力进入 Windy Web 的唯一显式 seam。API、Repository、Task、Feature、Permission、License 和 Audit 可以在没有 Admin Route 的情况下独立存在；这正是普通业务 Module 的默认形态。Windy Web 不应因为 Server 安装了业务 Module 就自动导入其 Vue 页面。
+
+示例工单不声明菜单或 Admin Route，Windy Web 也不依赖其 package、Vue 页面或 API client。其 Server API、Repository、Task 和数据范围契约继续保留，用于证明业务能力可以独立消费平台底座；若要提供工单界面，应在独立业务应用中实现并调用这些 API。
+
+## 失败与恢复
+
+- 401：会话失效，清理本地会话并返回登录页。
+- 403 且 bootstrap 拒绝：进入管理面拒绝页，不渲染 AppShell。
+- bootstrap 不可用：fail closed，进入快照不可用拒绝态。
+- License 限制：已通过 Admin 准入的账号进入 License 恢复页；普通业务账号仍先被 Admin 准入拒绝。

package/template/docs/architecture/data-scope-query-enforcement.md

@@ -0,0 +1,26 @@
+# Repository 级 Data Scope 强制
+
+## 目标与安全不变量
+
+Windy 只接受 Server 根据已验证会话、用户、启用角色和组织关系构造的 `ScopeContext`。HTTP query、body、Agent Tool 参数和导出请求都不是授权来源，不得从客户端覆盖 `actorId`、`departmentId` 或 ownership dimension。
+
+范围必须在 Repository 查询中与状态、搜索、排序、count 和分页同时生效。先读取候选集再在 service 内存过滤不是可接受的大数据路径。详情、更新和删除也必须把 ID 与同一 scope predicate 合并，不允许先执行裸 `get(id)` 再依赖调用者补一层判断。
+
+## 深模块接口
+
+1. [`context.ts`](../../apps/server/src/data-access/context.ts) 构造 nominal `ScopeContext`。它表达 `all`、`tenant`、`department`、`department-and-children`、`self` 和 `custom` grant，并对多角色授权去重。品牌实例由非枚举 Symbol 标记，普通 JSON 或对象展开不能冒充 Server context。
+2. [`query-specification.ts`](../../apps/server/src/data-access/query-specification.ts) 将 context 编译为与存储无关的 `DataScopeQuerySpecification`。多角色生成 union branches；部门后代由 Server 组织 Adapter 解析。
+3. [`drizzle-predicate.ts`](../../apps/server/src/data-access/drizzle-predicate.ts) 将 specification 编译为 Drizzle SQL predicate。无 grant 时固定 `false`，需要的 owner、tenant 或 dimension 未绑定时 fail fast，不会退回全量查询。
+4. [`drizzle-scoped-repository.ts`](../../apps/server/src/system/drizzle-scoped-repository.ts) 在 Repository 内把 scope 与软删除、状态和搜索条件合成同一个 `WHERE`。列表数据与 `count(*)` 复用该条件后再分页；详情、更新和软删除把 ID 与 scope 合并，直接 ID 越权返回稳定拒绝。写入还会校验变更后的 ownership，不能把可管理记录迁到范围之外。
+
+Core 只理解 ownership dimension 的稳定 key/value 契约，不知道下游项目或行业模型。测试 fixture 以 `projectId` 证明模块可显式绑定自有维度；`projectId` 不是 Windy Core 字段或内建范围。
+
+## 交付切片
+
+- D1：已完成 `ScopeContext`、Query Specification、Drizzle predicate compiler 和范围编译单元测试。
+- D2：已完成用户与示例 Work Order 的 list/count/search/pagination/get/update/delete Repository/SQL 下推；`bun run test:db:data-scope` 在临时 PostgreSQL 17 上验证搜索、分页总数、多角色并集、直接 ID 越权和写入不变性。
+- D3：已封堵 Agent Tool、导出、bulk/job 与工单定时任务旁路。用户 Tool 和导出只读取 Server Actor 上的 nominal context，忽略客户端提交的 `userId`、`departmentId`、`projectId` 等 ownership 参数；请求级 Tool 缺少 context 时 fail closed，Tool Manifest 与 Handler 在启动时必须一一对应。
+
+通用资源路由的 `dataAccess` 是必填判别联合：资源必须明确声明 `request` 并提供 scoped access，或声明 `platform`，不能因漏配可选字段静默回退裸 Repository。V1 异步 bulk handler 只接受显式 `platform` 资源，由服务端构造 nominal `all` context；需要继承申请人数据范围的异步资源必须先设计不可篡改的 context snapshot，不允许套用当前平台模式。工单运营快照同样使用服务端平台任务 Actor，不再暴露或调用裸 Repository。
+
+Search Provider 只能在 D1–D3 全部闭环后接入，不得先用 Provider 内存裁剪冒充 Repository 级强制。

package/template/docs/architecture/durable-jobs.md

@@ -0,0 +1,101 @@
+# Durable Job 深模块
+
+更新时间：2026-07-16。
+
+## 目标与边界
+
+Durable Job 是 Scheduler、批量导入导出和后续后台任务共享的持久化执行内核。核心只识别稳定的 `handlerKey`、JSON payload 和阶段，不依赖字典、报表或其它业务 DTO。业务 handler 通过注册表接入执行内核；领取、租约、心跳、取消、超时、重试和恢复都由 Execution Repository 状态机推进。
+
+它不是消息队列替代品，也不保存 artifact 二进制。任务表只保存 `ArtifactRef` 与完整性元数据，字节继续由 `BlobStore` 管理。
+
+## 持久化事实
+
+一次任务由八类可独立审计的事实组成：
+
+| 事实     | 责任                                                                |
+| -------- | ------------------------------------------------------------------- |
+| Job      | handler、payload、队列、优先级、幂等域、最终状态与执行策略          |
+| Stage    | 有序执行单元及其当前尝试次数                                        |
+| Attempt  | 某阶段的一次真实执行，记录 worker、超时边界和结果                   |
+| Lease    | worker 的有限期所有权；数据库只保存 token hash 和单调 fencing token |
+| Progress | 以 attempt 内 sequence 追加的进度事实，不覆盖历史                   |
+| Artifact | BlobStore 引用、Owner、hash、大小、类型和留存时间                   |
+| Failure  | 结构化错误码、可重试性、详情及发生位置                              |
+| Recovery | 人工恢复的原状态、操作者、理由与幂等请求号                          |
+
+外键统一使用 `ON DELETE RESTRICT`。任务历史不能因删除父记录被静默级联抹去；后续留存清理由显式策略处理。
+
+## 幂等与模块接口
+
+提交幂等域为 `requestedBy + handlerKey + idempotencyKey`。同一用户重放同一个业务请求会返回原任务，不会用重放 payload 覆盖已持久化事实；不同用户或不同 handler 可以安全复用外部请求号。
+
+`DurableJobRepository` 是事实持久化端口，当前提供内存和 Drizzle/PostgreSQL Adapter。`DurableExecutionRepository` 独占所有状态迁移和租约校验。`DurableJobService` 只负责提交输入不变量、聚合快照读取和列表边界。调用方读取 Job snapshot 时会同时获得 stages、attempts、leases、progress、artifacts、failures 和 recoveries，避免把多表拼装规则泄漏到业务模块。
+
+## Handler registry 与 Worker
+
+业务模块用稳定 `handlerKey` 注册 payload parser 和 executor。重复 key 会阻止 composition；未知 key 被领取后形成不可重试的 `HANDLER_NOT_REGISTERED` failure，不会把任务永久留在 running。parser 必须先把 `Record<string, unknown>` 收窄为业务 DTO，Durable Job 核心不引入业务类型。
+
+Worker 为 handler 提供 `AbortSignal`、heartbeat 和追加 progress。Worker 自动按 lease 时长的三分之一续租，同时允许长步骤主动 heartbeat。进程内 timeout 会触发 abort 和结构化失败；进程直接退出时，PostgreSQL 中的 `expiresAt` / `timeoutAt` 由下一实例 sweep，不依赖旧进程执行 finally。
+
+Handler 必须满足：
+
+- 以 Job ID 或业务幂等键保护外部副作用；租约只能防止同一时刻重复领取，不能撤销已发出的外部调用。
+- 在长循环、外部调用前后检查 `AbortSignal` 或 heartbeat，取消和 fencing 后立即停止。
+- 限流写 progress；progress sequence 由 Repository 在租约行锁内分配。
+- 用 `DurableHandlerError` 明确稳定错误码和是否可重试；未知异常默认可重试，但受 `maxAttempts` 限制。
+
+任务产物读取统一经过 `DurableArtifactService`：先按 `jobId + kind` 回读持久化元数据，再校验 Owner 或显式 manage 能力、留存时间、Blob 大小和 SHA-256。调用方不能凭 `ArtifactRef` 猜测下载；API 层仍需执行对应 RBAC Guard 并记录下载审计。
+
+## 数据库并发基础
+
+- `durable_jobs` 具有提交幂等唯一索引和按 queue/status/available/priority 的领取索引。
+- 每个 Job 的 stage key 与 ordinal 均唯一。
+- 每个 Stage 的 attempt number 唯一。
+- 每个 Stage 同时最多一个 `active` lease；租约过期不依赖进程内存判断。
+- progress sequence 在 attempt 内唯一；artifact kind 在 Job 内唯一。
+- `maxAttempts`、`timeoutSeconds`、ordinal、attempt number、fencing token 和数量字段由数据库检查约束保护。
+
+Claim 使用 `FOR UPDATE SKIP LOCKED`，多实例只会得到一个任务。数据库只保存 lease token 的 SHA-256；worker 后续写入还必须同时匹配 job/stage/attempt/lease、token hash、active 状态、未过期时间和单调 fencing token。旧 worker 即使晚到也不能完成新 attempt。
+
+Lease 或 timeout sweep 会终结旧 attempt 并写 Failure；只有 `currentAttempt < maxAttempts` 才按 `availableAt` 重排。queued 取消立即进入最终状态；running 取消先记录请求，协作 worker 或 expiry sweep 负责最终收口。人工恢复只接受 failed/cancelled 且没有 active lease 的任务，保留历史 attempts/failures，并在 `durable_job_recoveries` 记录带幂等键的恢复事实。
+
+## Scheduler 与 Bulk 兼容接入
+
+`LegacyDurableAdapter` 让旧 Scheduler/Bulk API 继续读取原有执行表，同时把真实执行所有权交给 durable lease runtime。`scheduled_task_runs` 与 `bulk_data_jobs` 只新增 nullable `durable_job_id`；旧状态、分页、重试次数、行级结果和下载接口均不改名，也不要求一次性回填历史记录。
+
+每个旧执行代次使用 `legacyId + generation` 作为 durable 幂等键，payload 只保存这两个稳定标识。handler 在每次领取时重新读取旧记录，不捕获提交进程的内存回调，因此新实例可以回收过期 lease 后继续执行。兼容规则如下：
+
+- 新 Scheduler run 和 Bulk attempt 在执行前关联 durable job；并发重复启动会命中同一提交事实和同一 lease claim。
+- 升级前已经处于 running、但尚无 `durable_job_id` 的记录由下一次 Scheduler tick 或 Bulk dispatch 自动采用。
+- handler 只有在旧记录仍为 running 且 generation 一致时执行；旧记录已完成、失败或进入 retry-pending 时，恢复重放是空操作，避免重复完成和重复生成 artifact。
+- durable runtime 只负责进程崩溃、租约和 fencing；Scheduler 的历史重试 run 与 Bulk 的业务失败重试状态仍由原服务维护，保持既有 API 可观察行为。
+- Bulk attempt 进入下一次业务重试时清空旧关联并创建新的代次幂等任务；旧 durable attempts/failures 仍保留审计历史。
+
+这是一条渐进迁移边界：新业务应直接注册 durable handler，不再新增另一套 `running` 状态机；Scheduler/Bulk Adapter 只服务现有接口兼容。
+
+## 审批超时接入
+
+最小审批注册稳定 handler `system.workflow.timeout` 和独立 queue。创建审批时以 WorkItem ID 作为提交幂等键，把 Job 的 `availableAt` 固定为审批 `dueAt`；payload 只保存 WorkItem ID。handler 到期后重新读取当前 WorkItem 与版本，只有 `pending` 或 `claimed` 才执行服务账号专用的 `timeout` 命令，已终结任务重复执行为空操作。
+
+启动与每次派发前会分页扫描尚未终结的审批并幂等补交 Job，用于覆盖“审批事实已提交、进程在 durable submit 前退出”的短窗口。调度器只负责唤醒派发，真实任务、可用时间、重试和执行结果都在 Durable Job 表中；新实例重建 Repository、Registry 和 Worker 后可以继续领取，不依赖旧进程 timer 或闭包。完整审批边界见[最小审批工作流](./minimal-approval-workflow.md)。
+
+## 运维与验证
+
+事实模型、执行恢复与兼容关联分别使用 `0023_fresh_thunderbolt_ross.sql`、`0024_misty_lizard.sql`、`0025_premium_songbird.sql`；审批事实和通知目标分别由 `0026_aberrant_doctor_octopus.sql`、`0027_tiny_diamondback.sql` 前向演进。上线前执行：
+
+```bash
+bun run db:migrate
+bun run test:db:migrations
+bun run typecheck
+bun test apps/server/src/jobs packages/database/src/schema.test.ts
+```
+
+PostgreSQL Repository 集成测试通过 `JOBS_TEST_DATABASE_URL` 启用，覆盖并发幂等提交、重复 claim、伪造 token、进程重建后的 lease recovery、timeout、cancel 和幂等人工恢复。兼容集成测试还需覆盖 running Bulk 在重建服务后的 lease 回收、旧记录关联、重复启动和重复完成空操作。迁移回归必须在全新 PostgreSQL 上执行一次并重复执行一次，第二次不得改变 Drizzle tracker 指纹。
+
+## 取舍
+
+- payload 使用类型化边界上的 `Record<string, unknown>`，核心不解释业务字段；业务 handler 必须在注册时自行校验 DTO。
+- 进度保留追加历史而不是只存百分比，便于定位卡点和恢复；高频任务需由 handler 限流，避免逐条业务记录写进度。
+- token 原文只允许短暂存在于 worker 进程，持久化层保存 SHA-256；数据库泄露不能直接伪造心跳或完成请求。
+- 自动重试有界，但人工恢复可产生新的 attempt；每次人工恢复都需要理由和幂等请求号，由运维/RBAC/审计入口在接入层约束。
+- 当前使用 PostgreSQL 作为 durable runtime 的并发真相。其它数据库必须实现同等 claim/lease 语义后才能声明兼容。

package/template/docs/architecture/minimal-approval-workflow.md

@@ -0,0 +1,60 @@
+# 最小审批工作流
+
+更新时间：2026-07-16。
+
+## 目标与边界
+
+本模块提供业务模块可复用的最小审批原语，而不是 BPMN 或完整流程平台。业务模块提交标题、候选角色、截止时间和通用 `TargetRef`，审批模块负责领取、转交、决定、取消、超时、持久化事实、授权、审计和通知。它不解释采购、合同等业务 DTO，也不新增业务详情页。
+
+当前不支持多步骤编排、条件分支、会签/或签、加签、抄送、代理人、流程设计器和可视化审批中心。需要这些能力时必须先建立独立领域模型，不能向当前状态机不断追加可选字段。
+
+## 状态机与命令
+
+`WorkItem` 聚合包含请求人、候选角色、可选领取人、截止时间、版本和 TargetRef。状态仅有 `pending`、`claimed`、`approved`、`rejected`、`cancelled`、`timed-out`；命令仅有 `claim`、`transfer`、`approve`、`reject`、`cancel`、`timeout`。
+
+- 候选角色用户可以领取 pending 任务；领取后只有当前领取人可以决定。
+- transfer 需要管理权限，并把任务保持在 claimed；目标领取人从服务端账号目录解析，客户端不能提交角色快照。
+- approve/reject 产生类型化 Decision；reject、transfer 和 cancel 要求 Reason。
+- 请求人可以取消未终结任务；服务账号专用 timeout 只能在截止时间到达后终结 pending/claimed。
+- 所有终态不可再次迁移；每个命令使用 expectedVersion，旧版本写入返回冲突。
+
+纯领域函数不依赖 HTTP、数据库、通知或定时器。完整转换和不变量由单元测试覆盖。
+
+## 持久化、幂等与并发
+
+`workflow_work_items` 保存聚合当前快照，`workflow_transitions` 追加不可变流转事实。事实包含命令、前后状态、Actor、发生时间、Decision、Reason、前后领取人、TargetRef 和结果快照；外键禁止级联删除。
+
+创建幂等域为“请求人 + idempotency key”，命令幂等域为“Actor + idempotency key”。PostgreSQL Adapter 在事务中取得幂等 advisory lock，再锁定 WorkItem 行并检查 expectedVersion；并发领取同一版本时只有一个成功。重放同一请求返回已经持久化的结果，不重复写流转事实。
+
+## Feature、RBAC、可见范围与审计
+
+能力基础 Key 是 `system.workflow`。Manifest 同时注册 Feature、`read/create/approve/manage` 权限、九个 API 绑定、隐藏入口和审计动作。列表、详情、历史、创建与全部命令均先执行服务端 Feature/RBAC Guard；直接调用 API 不能绕过。
+
+Repository 还执行对象级可见范围：请求人、候选角色用户、当前领取人和具有 manage 权限的用户可以读取；其他用户按不存在处理。领域状态机再次验证候选角色、当前领取人、请求人、管理权限和服务账号，避免只依赖列表过滤或前端按钮。
+
+mutation 在写入前记录关键 intent，成功后审计命令、前后状态、Decision 和 TargetRef。完整 Reason 保存在受保护的流转历史中，不复制到普通日志或审计 metadata，避免敏感审批说明扩散。
+
+## 通知与业务跳转
+
+审批通过站内通知的窄业务端口发送消息。新任务按候选角色投递；转交按新领取人投递；其它迁移通知请求人。通知携带原始通用 `TargetRef`，由消费端决定如何打开已有业务路由，审批模块不依赖业务页面。
+
+每条业务通知使用工作项 ID 和版本构造稳定 `sourceKey`，进程重试不会重复发布。收件箱和已读入口都按当前用户与角色重新校验受众；普通通知管理 API 不接受受众、TargetRef 或 source key。该扩展不是通知中心 P1：组织范围、管理端定向/定时发布、偏好、合并策略和外部渠道仍未实现。
+
+## Durable 超时与重启恢复
+
+创建 WorkItem 后，以 WorkItem ID 幂等提交 `system.workflow.timeout` Durable Job，`availableAt` 等于 `dueAt`。Job payload 只包含 WorkItem ID。到期 handler 重新读取 PostgreSQL 当前状态与版本，再以服务 Actor 执行 timeout；终态重复处理为空操作。
+
+服务启动和每次 timeout 派发前会扫描 pending/claimed WorkItem 并幂等补交任务。这同时覆盖两类恢复：旧进程已经提交 Job 后退出，新实例从持久化 queue 继续领取；或旧进程在 WorkItem 提交后、Job 提交前退出，新实例通过 reconcile 补齐。任务最多尝试五次，单次 timeout 为 30 秒。
+
+## 运维与验证
+
+上线必须执行 migration `0026_aberrant_doctor_octopus.sql` 和 `0027_tiny_diamondback.sql`。建议门禁：
+
+```bash
+bun run db:migrate
+bun run test:db:migrations
+bun run typecheck
+bun test apps/server/src/workflow packages/database/src
+```
+
+真实 PostgreSQL 集成测试通过 `WORKFLOW_TEST_DATABASE_URL` 启用，覆盖创建/命令幂等、并发领取仅一方成功、候选角色与对象可见范围，以及重建 Durable Repository/Registry/Worker 后执行到期任务。迁移回归必须在全新数据库执行一次并重复执行一次，第二次不得改变 tracker 指纹。