@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/AGENTS.md

@@ -1,13 +1,96 @@
-<!-- cage:begin v0.1.0 -->
-## Cage 框架约定
-
-1. 先声明聚合、状态、命令、约束和事件，再实现 handler、查询与页面。
-2. 修改后运行 cage check、cage gen、cage verify；用 cage impact --base-file 旧本体图.json 查看影响。
-3. domain 的声明必须是模块顶层 export const，并从 index.ts 导出。
-4. handler 的读依赖写入 reads；写入只走命令，第三方 IO 通过连接器。
-5. 前端从 @app/contracts 导入契约；生成物通过 cage gen 更新。
-6. 不得手写 HTTP 路由、拼接 SQL 或嵌入密钥；unsafe 必须注明 reason、owner。
-7. 迁移草稿需审查，已发布的迁移不可修改；新增能力点由管理员授权。
-8. 错误码见 docs/errors；完整示例见框架仓库 examples/purchase-admin。
-<!-- cage:end -->
+# 本项目的业务开发说明
+
+这是 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

@@ -16,6 +16,8 @@ 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

package/templates/app/README.md

@@ -1,27 +1,55 @@
-# 采购工作台
+# 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`，然后进入本目录。独立模板项目先执行 `pnpm install`、`pnpm build:app`、`pnpm cage gen`。
+在本项目根目录执行 `pnpm install`、`pnpm build:app`；无需克隆或构建框架仓库。
 
 ```powershell
-pnpm cage db setup
-pnpm cage db up
-# 仅首次初始化独立新集群时执行；已有库随后用 cage migrate。
-pnpm cage db init
+# 首次配置时复制，已有 .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
 ```
 
-连接池、事务、数据库初始化和凭证生成均由框架提供，项目不写连接或建库脚本。`cage db setup` 生成随机密码和本地 `.env`，重复运行保留已有配置。开发库位于 `127.0.0.1:54329/cage_dev`，测试库位于独立容器的 54330 端口。`cage db down` 停止容器但保留开发数据卷；`cage db up` 再次启动。package.json 中的 `db:*` 是相同命令的简写。
+数据库配置位于本项目根目录的 `.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。
 
-CLI 自动读取项目 `.env`，部署环境变量优先。`CAGE_APP_DATABASE_URL`、`CAGE_READ_DATABASE_URL`、`CAGE_MIGRATE_DATABASE_URL` 分别连接写入、只读和迁移账号。超级用户仅用于初始化，API/worker 不接收其凭证。
+### 首次只提供管理员连接
+
+在 `.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` 验证全部框架测试。
 
-浏览器打开 <http://localhost:5173>。初始管理员凭证在 API 终端显示一次。
-如果 Windows Docker/Hyper-V 保留了该端口，在 `.env` 设置 `CAGE_WEB_PORT=15173`；终端会打印实际地址。`PORT` 控制 API 端口，Vite 代理同步使用它。未配置数据库连接串时才使用原有内嵌 PostgreSQL。
+浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。初始管理员凭证在 API 终端显示一次。
+`CAGE_WEB_PORT` 控制 Web 端口，`PORT` 控制 API 端口，Vite 代理同步使用它。缺少数据库配置时会给出错误，需填写 `.env` 后重新启动。
 
 ## 体验完整采购流程
 
@@ -47,12 +75,14 @@ CLI 自动读取项目 `.env`，部署环境变量优先。`CAGE_APP_DATABASE_UR
 
 图谱主标题显示中文业务名称，下面保留英文代码标识。框架会读取声明现有的 `description`；本项目在 `cage.config.json` 的 `graph.labels` 中补充状态、字段等名称，也可覆盖较长描述。例如 `"command:PurchaseOrder.approve": "通过审批"`。键为 `节点类型:本体节点 ID`，可从节点详情复制 ID；中文标题只用于显示，不改变命令、权限标识或数据库。新增业务声明时同时补上需要的名称，然后在图谱中点击“重新抽取”。
 
-- `packages/domain/src/inventory.ts`：最简聚合和库存锁。
-- `purchase-order.ts`：状态、命令、约束和事件。
-- `reactions.ts`：同事务建锁与异步释放，包含资源配对标记。
-- `approvals.ts`、`erp.ts`：封闭审批路由、出站和入站映射。
-- `queries.ts`、`jobs.ts`：安全视图查询及过期草稿清理。
+- `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`：仅依赖生成契约的 React 界面。
+- `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

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.1.0",
-    "@yss123/cage-connectors": "0.1.0"
+    "@yss123/cage-http": "0.2.0",
+    "@yss123/cage-connectors": "0.2.0"
   }
 }

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')} />
+  );
+}

package/templates/app/apps/web/src/app/workspace-layout.tsx

@@ -0,0 +1,70 @@
+// 应用壳组合模块公开入口，只持有导航和会话；表单、筛选、命令留在各业务模块。
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { client, currentUser } from '@app/contracts';
+import { PurchaseOrdersPage } from '../modules/purchase';
+import { InventoryPage } from '../modules/inventory';
+import { ApprovalTasksPage, useApprovalTasks } from '../modules/approval';
+
+export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
+  const [tab, setTab] = useState<'orders' | 'tasks' | 'stock'>('orders');
+  const tasks = useApprovalTasks();
+  const cache = useQueryClient();
+  return (
+    <div className="workspace">
+      <aside>
+        <a className="brand" href="/">
+          cage<span>采购工作台</span>
+        </a>
+        <span className="nav-caption">工作空间</span>
+        <nav>
+          {(
+            [
+              ['orders', '01', '采购单'],
+              ['tasks', '02', '审批待办'],
+              ['stock', '03', '库存台账'],
+            ] as const
+          ).map(([key, no, label]) => (
+            <button key={key} className={tab === key ? 'selected' : ''} onClick={() => setTab(key)}>
+              <span>{no}</span>
+              {label}
+              {key === 'tasks' && <b>{tasks.data?.length ?? 0}</b>}
+            </button>
+          ))}
+        </nav>
+        <div className="aside-bottom">
+          <a href="/admin/">系统管理 ↗</a>
+          <div className="user">
+            <span className="avatar">{currentUser()?.name?.slice(0, 1) ?? '用'}</span>
+            <div>
+              {currentUser()?.name}
+              <small>已登录</small>
+            </div>
+          </div>
+          <button
+            className="logout"
+            onClick={async () => {
+              await client.logout();
+              cache.clear();
+              onLogout();
+            }}
+          >
+            退出登录
+          </button>
+        </div>
+      </aside>
+      <main className="content">
+        <header>
+          <span>采购管理 / {tab === 'orders' ? '采购单' : tab === 'tasks' ? '审批待办' : '库存台账'}</span>
+          <span className="live-dot">团队工作空间</span>
+        </header>
+        {tab === 'orders' && <PurchaseOrdersPage pendingTasks={tasks.data?.length} />}
+        {tab === 'tasks' && <ApprovalTasksPage />}
+        {tab === 'stock' && <InventoryPage />}
+        <div className="page-footer">
+          CAGE / PROCUREMENT WORKSPACE<span>业务操作均受权限与数据范围约束</span>
+        </div>
+      </main>
+    </div>
+  );
+}