@yss123/cage-cli 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
+  "type": "module",
+  "bin": {
+    "cage": "./bin/cage.js",
+    "create-cage-app": "./bin/create-cage-app.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "graph-ui",
+    "templates"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "dependency-cruiser": "^17.0.1",
+    "eslint": "^9.35.0",
+    "pg": "^8.16.3",
+    "ts-morph": "^26.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.12",
+    "zod": "^4.1.5",
+    "@yss123/cage-kernel": "0.2.0",
+    "@yss123/cage-lint": "0.2.0",
+    "@yss123/cage-testkit": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shunshunyue/cage.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/shunshunyue/cage#readme",
+  "bugs": {
+    "url": "https://github.com/shunshunyue/cage/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.ts && tsc -p tsconfig.json && tsc -p ui/tsconfig.json && node scripts/build-graph.ts && node scripts/copy-assets.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p ui/tsconfig.json",
+    "test": "vitest run"
+  }
 }

package/templates/app/.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+**/node_modules
+**/dist
+.git
+.cage
+**/.cage
+generated
+.env
+.env.*
+*.log

package/templates/app/.env.example

@@ -0,0 +1,61 @@
+# Cage 业务项目配置：复制此文件为同目录的 .env，首次只填写管理员数据库连接。
+# .env 位于业务项目根目录，与 package.json、cage.config.json 同级。
+# pnpm exec cage init / pnpm dev / pnpm migrate 自动读取它；同名外部环境变量优先。
+# 修改后重启 dev；migrate 在下次执行时读取新值。不要把 .env 提交到 Git。
+# 数据库需已经存在并能连接；框架不安装 PostgreSQL、不创建数据库、不管理 Docker。
+
+# ===== 第一步：提供已有数据库的管理员连接，执行 pnpm exec cage init =====
+# 格式：postgresql://用户名:密码@主机:端口/数据库名
+# 将 127.0.0.1、5432、business_db 换成实际地址、端口和已有数据库名。
+# 密码中的特殊字符必须 URL 编码，例如 @ 写成 %40、# 写成 %23、% 写成 %25。
+# [首次初始化必填] 管理员通常叫 postgres；若你的管理员叫 root，使用实际账号名。
+# 管理员需要创建角色、schema 和授权的权限。连接的数据库必须已经存在。
+# 将下面的管理员密码、主机、端口和库名改为实际值，再执行 pnpm exec cage init。
+# init 会创建框架账号、生成独立随机密码和 Cookie 密钥，并自动填好下面的配置。
+# 成功后管理员连接会从 .env 移除；日常开发不用再提供管理员密码。
+CAGE_ADMIN_DATABASE_URL=postgresql://postgres:REPLACE_WITH_ADMIN_PASSWORD@127.0.0.1:5432/business_db
+
+# ===== 第二步：以下配置由 init 自动填充，无需手动创建账号或编写授权 SQL =====
+# 三个连接使用同一个数据库，主机、端口、库名一致，账号权限不同。
+# 重复 init 会验证并复用已保存的账号，不重置密码。
+# 若集群已有 Cage 账号且本项目未保存连接，需复用原凭证，不能仅凭管理员重置其他项目的密码。
+
+# [必填] 业务写入账号 cage_app：API 和 worker 执行命令、审计和后台任务使用。
+# 它有业务所需读写权限，不应使用 postgres 超级用户替代。
+# CAGE_APP_DATABASE_URL=
+
+# [必填] 安全查询账号 cage_read：仅通过安全视图读取，经数据范围过滤和敏感字段掩码。
+# 不要与写入账号混用，否则会破坏读写权限隔离。
+# CAGE_READ_DATABASE_URL=
+
+# [执行迁移时必填] 迁移账号 cage_migrate：pnpm migrate 用它更新表、索引、视图和权限。
+# 它连接上述同一个数据库；迁移只在手动执行命令时发生，dev 不自动执行迁移。
+# 生产环境只给迁移任务配置此项，API / worker 无需获得此账号。
+# CAGE_MIGRATE_DATABASE_URL=
+
+# ===== 应用配置 =====
+# [init 自动生成] Cookie 签名密钥，不是数据库密码，也不是网页登录密码。
+# 自动生成 32 字节随机值；已有值保留。同一应用的多个实例使用同一值。
+# CAGE_COOKIE_SECRET=
+
+# [可选，开发默认 fake] 第三方连接器阶段：fake 使用模拟实现；test / prod 使用真实适配器。
+# 本项只影响第三方外部服务，fake 阶段仍连接真实 PostgreSQL。
+# test / prod 需另行配置业务连接器要求的地址与密钥，不是修改此值就完成对接。
+CAGE_STAGE=fake
+
+# [可选，Vite 默认 5173] 本地 Web 页面端口。这里选 15173，减少 Windows 保留端口冲突。
+# 多个应用同时运行时，各选一个空闲端口；它与数据库端口无关。
+CAGE_WEB_PORT=15173
+
+# [可选，默认 3000] API 服务端口；本地 Web 代理自动转发到这个端口。
+PORT=3000
+
+# [可选，范例默认 0.0.0.0] API 监听地址；这里使用 127.0.0.1，仅允许本机访问。
+# 需要容器内或局域网访问时改为 0.0.0.0，并按部署环境配置网络访问权限。
+HOST=127.0.0.1
+
+# ===== 仅执行数据库测试时使用；正常启动不需要 =====
+# [可选] 独立、可丢弃 PostgreSQL 测试集群的管理连接，需有建库和管理角色权限。
+# 测试会创建/删除临时库、初始化集群级角色；不能指向业务或生产数据库所在的集群。
+# 不填写时测试工具使用内嵌真实 PostgreSQL；这仅是测试行为，dev 不会自动启动数据库。
+# CAGE_TEST_DATABASE_URL=postgresql://test_admin:REPLACE_WITH_TEST_PASSWORD@127.0.0.1:5433/postgres

package/templates/app/.github/workflows/cage.yml

@@ -0,0 +1,44 @@
+# 尚未配置框架发布地址时直接调用同一个 CLI 门禁。
+# 框架发布后可将此任务替换为远端 app-verify.yml 的 uses 引用。
+name: Cage application
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:18
+        env: { POSTGRES_PASSWORD: cage_ci }
+        ports: ['5432:5432']
+        options: --health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      CAGE_TEST_DATABASE_URL: postgres://postgres:cage_ci@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: pnpm/action-setup@v4
+        with: { version: 10.14.0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 24 }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build:app
+      - run: pnpm cage verify
+      - name: Pull request impact
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          pnpm cage impact --base "$BASE_SHA" --format md --out .cage/impact.md
+          cat .cage/impact.md >> "$GITHUB_STEP_SUMMARY"
+      - run: pnpm audit --prod --audit-level high
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: cage-report
+          include-hidden-files: true
+          path: |
+            .cage/verify.json
+            .cage/test-results.json
+            .cage/impact.md

package/templates/app/AGENTS.md

@@ -0,0 +1,96 @@
+# 本项目的业务开发说明
+
+这是 create-cage-app 生成的业务项目，当前包含采购演示，可逐步替换成客户业务。业务源码在本项目，框架通过 @yss123/cage-* 依赖提供。
+
+先读 [业务开发指南](docs/ai/README.md)，按需求查 [任务配方](docs/ai/recipes.md)、[完整采购范例](docs/ai/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
+
+## 项目自己的业务约定
+
+客户术语、角色权限、状态规则、第三方协议和验收标准写在本节或独立业务文档，再从这里链接。新增业务以用户需求为准，不因模板包含采购示例就固定实现采购流程。
+
+本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
+
+<!-- cage:begin v0.2.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`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
+
+### 业务代码放在哪里
+
+| 位置 | 职责 |
+| --- | --- |
+| `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` | 会话、导航、布局、模块组合；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 analyze` 后将 `.cage/ontology.json` 另存为独立文件；或使用真实 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 --base-file 旧图.json`，补中文图谱名。
+5. 页面使用生成方法并处理 code/domainCode；新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
+6. 按改动运行必要验证，交付时说明体验步骤、授权配置、迁移，以及通过/跳过/未执行项。
+
+### 必守边界
+
+- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。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、内核或数据库包。
+- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
+- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
+- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
+- 代码注释说明职责、关键流程和设计原因；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+
+### 最小命令形状
+
+```ts
+// 片段：Order 为已导出的聚合，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 dev`。已有配置不能覆盖。
+
+init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
+
+- `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 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；查询也会覆盖当前 .cage/ontology.json，旧基线务必另存。
+- `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` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
+- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
+- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
+
+框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+<!-- cage:end -->

package/templates/app/Dockerfile

@@ -0,0 +1,25 @@
+# 独立业务仓库使用已发布的 @yss123/cage-* 依赖；先提交 pnpm-lock.yaml。
+# --framework-path 创建的 link: 本地依赖只用于源码开发，不能拷贝进独立镜像。
+FROM node:24-bookworm-slim AS build
+RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
+WORKDIR /app
+COPY . .
+RUN pnpm install --frozen-lockfile && pnpm build:app
+RUN pnpm --filter @app/api deploy --prod --legacy /out/api
+
+# 发布过程先单独运行此 target，迁移账号只注入迁移任务。
+FROM build AS migration
+CMD ["pnpm", "cage", "migrate"]
+
+# API 与 worker 共用运行时镜像，通过启动命令区分职责。
+FROM node:24-bookworm-slim AS runtime
+WORKDIR /app
+COPY --from=build --chown=node:node /out/api /app
+COPY --from=build --chown=node:node /app/apps/web/dist /app/web
+# 系统管理与图谱共享中文显示配置；运行时工作目录同样保持为 /app。
+COPY --from=build --chown=node:node /app/cage.config.json /app/cage.config.json
+ENV NODE_ENV=production PORT=3000 WEB_DIR=/app/web
+USER node
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+# worker 启动命令：node dist/worker.js

package/templates/app/README.md

@@ -0,0 +1,88 @@
+# Cage 业务应用（含采购示例）
+
+这是可启动的标准范例：组织管理、采购单、审批待办、库存台账、库存锁生命周期和 ERP 出入站映射。
+
+## 让 AI 在本项目开发业务
+
+把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/ai/README.md)和[任务配方](docs/ai/recipes.md)实现需求。普通业务不需要修改框架源码。
+
+[采购全链路导读](docs/ai/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/ai/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/ai` 与 `docs/errors`，无需再次克隆框架。
+
+## 启动
+
+在本项目根目录执行 `pnpm install`、`pnpm build:app`；无需克隆或构建框架仓库。
+
+```powershell
+# 首次配置时复制，已有 .env 时直接编辑原文件。
+Copy-Item .env.example .env
+# 编辑 .env，只填写 CAGE_ADMIN_DATABASE_URL，连接已经存在的数据库。
+pnpm exec cage init
+# init 自动创建账号、生成密码和 Cookie 密钥，并写回 .env。
+pnpm gen
+# 审查 db/migrations 后执行表结构迁移。
+pnpm migrate
+pnpm dev
+```
+
+数据库配置位于本项目根目录的 `.env`，与 `package.json`、`cage.config.json` 同级。[`.env.example`](.env.example) 为每项提供中文注释、填写格式和是否必填。连接池和事务由框架提供，项目只需配置连接。
+
+| 配置项 | 用途 |
+| --- | --- |
+| `CAGE_APP_DATABASE_URL` | `cage_app` 账号：API/worker 业务读写 |
+| `CAGE_READ_DATABASE_URL` | `cage_read` 账号：仅查询安全视图 |
+| `CAGE_MIGRATE_DATABASE_URL` | `cage_migrate` 账号：手动执行表结构迁移 |
+
+三个连接由 `cage init` 自动生成，指向**同一个已经存在的数据库**，主机、端口和库名一致。CLI 自动读取 `.env`，部署环境中的同名变量优先。修改后重启 `dev`。`migrate` 在下次执行时读取配置。
+
+`pnpm migrate` 更新该库中的表、视图和索引；迁移历史记录在 `sys.schema_migrations`。`pnpm dev` 连接该库并启动 API、worker 和 Web，domain 变化后仅重新生成文件；表结构变更需审查迁移后手动执行。框架不创建数据库、不安装 PostgreSQL、不管理 Docker。
+
+### 首次只提供管理员连接
+
+在 `.env` 中填写 `CAGE_ADMIN_DATABASE_URL=postgresql://postgres:管理员密码@主机:端口/已有数据库名`。PostgreSQL 管理员通常叫 `postgres`，已有管理员叫 `root` 时使用实际账号名；连接串中的密码特殊字符需要 URL 编码。
+
+执行 `pnpm exec cage init` 会创建框架账号和授权，生成三个独立随机密码及 Cookie 密钥，自动填写 `.env`，成功后移除文件中的管理员连接。业务端口、自定义配置和已有 Cookie 密钥会保留；失败会回滚数据库并保留原 `.env`。日常启动不需要管理员连接。
+
+重复 `init` 会验证并复用已保存的三个账号，不更改密码。若集群已有 Cage 账号但本项目没有原连接，请先复用原凭证再运行 `init`；命令不会为了新项目重置其他项目的账号。部署时也可由平台直接提供三个账号连接，无需执行本地初始化。
+
+数据库除三个登录账号外，还有不允许登录的 `cage_view_owner`，由 `init` 一并创建，用于持有安全视图，无需填写密码。角色名属于整个 PostgreSQL 集群，不能为另一个项目随意重置密码。业务表及系统表由后续 `pnpm migrate` 创建，`init` 只准备角色、schema 和授权。连接现有数据库不表示框架会自动识别、接管其中任意历史业务表；接入历史表需另行映射和审查迁移。
+
+测试环境会初始化集群级角色，因此 `CAGE_TEST_DATABASE_URL` 必须指向独立测试集群。运行 `pnpm cage verify` 验证示例；框架仓库根目录的 `pnpm test:docker` 验证全部框架测试。
+
+浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。初始管理员凭证在 API 终端显示一次。
+`CAGE_WEB_PORT` 控制 Web 端口，`PORT` 控制 API 端口，Vite 代理同步使用它。缺少数据库配置时会给出错误，需填写 `.env` 后重新启动。
+
+## 体验完整采购流程
+
+1. 管理员在“库存台账”登记 `A-01` 等物料。
+2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
+3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
+4. 采购员新建并提交采购单；worker 建立审批待办。
+5. 经理在“审批待办”通过，内核同事务生成库存锁；worker 调用 fake ERP 并回写单号。
+6. 超过 50,000 元的采购走财务第二步，需另建 code 为 `finance` 的角色并分配审批人。
+7. 取消单据或收到 ERP 收货回调后，通过异步反应释放锁。回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
+
+`Inventory.available` 是演示台账数量。本例验证库存锁生命周期，尚未实现仓库级的并发扣减、实物库存及退货核算。
+
+本例的取消只改变本地单据并释放锁，尚未对接真实 ERP 的取消补偿接口。ERP 单号应答可能晚于取消或收货到达，`recordErpNo` 使用 `to: null` 保留当时的单据状态；它仍然检查允许的起始状态、调用身份和版本，并写入审计。上线前需确定外部订单撤销、退货或人工补偿的业务规则。
+
+## 文件怎么读
+
+在本目录运行 `pnpm exec cage graph`，浏览器打开终端输出的 <http://127.0.0.1:15418>，即可用图谱查看业务关系。页面支持中文/英文搜索、类型筛选、拖拽缩放、聚焦关联、声明位置与重新抽取，不需要启动数据库。
+
+默认“对象与字段”按表卡片展示采购单、库存台账和库存锁，字段收在对象卡片中，显示中文含义、类型、必填标记及实际表名。拖动表头可以移动整张卡片。勾选“包含系统组织模型”查看部门、用户等对象；字段引用从字段行连到目标表头。“业务流程”和“完整本体”用于查看命令、事件、审批等更完整的关系。页面所说的业务对象，技术上叫“聚合”，包含共同遵守业务规则的字段、状态和命令，不只是数据库表。
+
+线上的中文名称说明关系类型；点击连线、标签或节点详情中的“解释”，查看连接原因、业务用途、箭头方向和声明依据。可搜索 `PurchaseOrder.deptId` 后点击“聚焦关联”，看到采购单的所属部门字段**引用**部门卡片。字段详情中还可查看“采购审批分支”怎样用它**确定审批人**，点击解释会切换到完整本体显示对应连线。审批流程的“允许审批读取”表示字段可用范围，实际选人依据另有解释。
+
+图谱主标题显示中文业务名称，下面保留英文代码标识。框架会读取声明现有的 `description`；本项目在 `cage.config.json` 的 `graph.labels` 中补充状态、字段等名称，也可覆盖较长描述。例如 `"command:PurchaseOrder.approve": "通过审批"`。键为 `节点类型:本体节点 ID`，可从节点详情复制 ID；中文标题只用于显示，不改变命令、权限标识或数据库。新增业务声明时同时补上需要的名称，然后在图谱中点击“重新抽取”。
+
+- `packages/domain/src/modules/inventory`：最简聚合和库存锁。
+- `packages/domain/src/modules/purchase`：采购状态、命令、约束、事件、审批、查询和任务。
+- `packages/domain/src/workflows/purchase-inventory.ts`：同事务建锁与异步释放，包含资源配对标记。
+- `packages/domain/src/integrations/erp.ts`：出站、入站映射和验签。
+- `packages/contracts/src/aggregates/<聚合>`：生成的 SDK；页面统一从 `@app/contracts` 引入。
+- `apps/api/src`：API 和 worker 的薄启动入口。
+- `apps/web/src/app`、`modules`、`shared`：应用组合、业务页面、共享基础组件；`main.tsx` 只挂载。
+
+新增业务先读[工程目录与代码组织](docs/ai/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
+
+先运行 `pnpm cage gen` 再提交契约和迁移草稿；`pnpm cage verify` 检查完整工具链。派生测试遇到无法推断的业务输入会显示跳过，`purchase-order.test.ts` 另外准备真实业务数据覆盖成功审批和约束反例。

package/templates/app/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.cage/
+generated/
+.env
+.env.*
+!.env.example
+*.log

package/templates/app/apps/api/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@app/api",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/main.js",
+    "worker": "node dist/worker.js"
+  },
+  "dependencies": {
+    "@app/domain": "workspace:*",
+    "@yss123/cage-http": "0.2.0",
+    "@yss123/cage-connectors": "0.2.0"
+  }
+}

package/templates/app/apps/api/src/main.ts

@@ -0,0 +1,10 @@
+// 启动入口只装配框架：认证、业务路由和 /admin 都由 createServer 提供。
+// WEB_DIR 在部署镜像中指向 Vite 构建产物；本地由 Vite 独立提供前端。
+import { createServer } from '@yss123/cage-http';
+import * as domain from '@app/domain';
+
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台' });
+await server.listen();
+// 退出时释放数据库池及 LISTEN 连接，部署滚动替换时不会留下旧连接。
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());

package/templates/app/apps/api/src/worker.ts

@@ -0,0 +1,14 @@
+// API 与 worker 使用相同声明。worker 专门处理审批启动、异步反应和 ERP 推送。
+import { startWorker } from '@yss123/cage-http/worker';
+import { fakeConnector, stage } from '@yss123/cage-connectors';
+import * as domain from '@app/domain';
+
+// 本地和测试的 ERP 返回确定的单号，便于查看同步记录；生产环境走真实出口。
+if (stage() === 'fake') {
+  fakeConnector(domain.erp, {
+    pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId.slice(0, 8)}` }),
+  });
+}
+const worker = await startWorker({ domain });
+process.once('SIGINT', () => void worker.stop());
+process.once('SIGTERM', () => void worker.stop());

package/templates/app/apps/api/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

package/templates/app/apps/web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="theme-color" content="#153c35" />
+    <title>Cage · 采购工作台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/app/apps/web/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@app/web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "@tanstack/react-query": "^5.87.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "vite": "^7.1.4",
+    "typescript": "~5.9.3"
+  }
+}

package/templates/app/apps/web/src/app/app.tsx

@@ -0,0 +1,18 @@
+// 应用组合层只决定会话与页面的切换；具体业务交给 modules 下的页面。
+import { useEffect, useState } from 'react';
+import { loadMe } from '@app/contracts';
+import { LoginPage } from '../modules/auth';
+import { WorkspaceLayout } from './workspace-layout';
+
+export function App() {
+  const [session, setSession] = useState<'loading' | 'guest' | 'ready'>('loading');
+  useEffect(() => {
+    void loadMe().then((result) => setSession(result.ok ? 'ready' : 'guest'));
+  }, []);
+  if (session === 'loading') return <div className="loading">正在连接工作台…</div>;
+  return session === 'guest' ? (
+    <LoginPage onLogin={() => setSession('ready')} />
+  ) : (
+    <WorkspaceLayout onLogout={() => setSession('guest')} />
+  );
+}