@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/apps/web/src/modules/auth/pages/login-page.tsx

@@ -0,0 +1,59 @@
+// 登录页属于认证模块；表单反馈留在模块内，会话切换由 app 处理。
+import { useState, type FormEvent } from 'react';
+import { client } from '@app/contracts';
+import { errorMessage } from '../../../shared/lib/error-message';
+
+export function LoginPage({ onLogin }: { onLogin: () => void }) {
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setBusy(true);
+    setError('');
+    const data = new FormData(event.currentTarget);
+    const result = await client.login(String(data.get('username')), String(data.get('password')));
+    setBusy(false);
+    if (result.ok) onLogin();
+    else setError(errorMessage(result));
+  }
+  return (
+    <main className="login">
+      <div className="login-intro">
+        <span className="eyebrow">CAGE / OPERATIONS</span>
+        <h1>
+          每一笔采购，
+          <br />
+          有据可循。
+        </h1>
+        <p>
+          从需求到审批，再到入库。
+          <br />
+          让团队在同一张工作台上协作。
+        </p>
+        <span className="edition">采购管理 · 示例工作台 / 01</span>
+      </div>
+      <form onSubmit={submit} className="login-form">
+        <span className="eyebrow">WELCOME BACK</span>
+        <h2>登录工作台</h2>
+        <p className="muted">使用管理员分配的账号继续。</p>
+        <label>
+          账号
+          <input name="username" autoComplete="username" required autoFocus />
+        </label>
+        <label>
+          密码
+          <input name="password" type="password" autoComplete="current-password" required />
+        </label>
+        {error && (
+          <p className="error" role="alert">
+            {error}
+          </p>
+        )}
+        <button className="primary" disabled={busy}>
+          {busy ? '正在登录…' : '登录 →'}
+        </button>
+        <small>首次启动的管理员账号显示在 API 终端。</small>
+      </form>
+    </main>
+  );
+}

package/templates/app/apps/web/src/modules/inventory/index.ts

@@ -0,0 +1 @@
+export { InventoryPage } from './pages/inventory-page';

package/templates/app/apps/web/src/modules/inventory/pages/inventory-page.tsx

@@ -0,0 +1,74 @@
+// 库存模块只管理台账页面，登记物料通过生成的 Inventory.create 命令。
+import { can, inventory, useInventoryList } from '@app/contracts';
+import { useCommand } from '../../../shared/hooks/use-command';
+import { Notice } from '../../../shared/ui/notice';
+import { PageHeading } from '../../../shared/ui/page-heading';
+
+export function InventoryPage() {
+  const stock = useInventoryList({ pageSize: 100 });
+  const { run, busy, message, clearMessage } = useCommand();
+  return (
+    <>
+      <PageHeading eyebrow="INVENTORY" title="库存台账" description="查看物料与当前登记数量。" />
+      {message && <Notice onClose={clearMessage}>{message}</Notice>}
+      <section className="panel">
+        <div className="section-head">
+          <h2>物料台账</h2>
+        </div>
+        {can('Inventory.create') && (
+          <form
+            className="stock-form"
+            onSubmit={async (event) => {
+              event.preventDefault();
+              const form = event.currentTarget;
+              const data = new FormData(form);
+              if (
+                await run(
+                  () =>
+                    inventory.create({
+                      sku: String(data.get('sku')),
+                      available: Number(data.get('available')),
+                    }),
+                  '物料已登记',
+                )
+              )
+                form.reset();
+            }}
+          >
+            <label>
+              物料编码
+              <input name="sku" required maxLength={64} />
+            </label>
+            <label>
+              登记数量
+              <input name="available" type="number" min="0" step="1" required />
+            </label>
+            <button className="primary" disabled={busy}>
+              登记物料
+            </button>
+          </form>
+        )}
+        {stock.isError && <p className="error">{stock.error.message}</p>}
+        <table>
+          <thead>
+            <tr>
+              <th>物料编码</th>
+              <th>登记数量</th>
+            </tr>
+          </thead>
+          <tbody>
+            {stock.data?.items.map((item) => (
+              <tr key={item.id}>
+                <td className="mono">{item.sku}</td>
+                <td>{item.available}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+        {stock.data?.items.length === 0 && (
+          <p className="empty">尚未登记物料。请先登记采购单使用的物料编码。</p>
+        )}
+      </section>
+    </>
+  );
+}

package/templates/app/apps/web/src/modules/purchase/components/purchase-order-form.tsx

@@ -0,0 +1,60 @@
+// 只处理采购草稿输入；状态迁移、创建人和权限仍由领域命令决定。
+import { useState, type FormEvent } from 'react';
+import { purchaseOrder } from '@app/contracts';
+import type { RunCommand } from '../../../shared/hooks/use-command';
+
+export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunCommand }) {
+  const [busy, setBusy] = useState(false);
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setBusy(true);
+    const data = new FormData(event.currentTarget);
+    const ok = await run(
+      () =>
+        purchaseOrder.create({
+          amount: String(data.get('amount')),
+          supplierPhone: String(data.get('phone')) || undefined,
+          items: [{ sku: String(data.get('sku')), qty: Number(data.get('qty')) }],
+        }),
+      '采购单已保存为草稿',
+    );
+    setBusy(false);
+    if (ok) close();
+  }
+  return (
+    <div className="modal-backdrop">
+      <section role="dialog" aria-modal="true" aria-labelledby="new-order-title" className="modal">
+        <div className="section-head">
+          <h2 id="new-order-title">新建采购单</h2>
+          <button onClick={close} aria-label="关闭">
+            ×
+          </button>
+        </div>
+        <form onSubmit={submit}>
+          <label>
+            物料编码
+            <input name="sku" placeholder="例如 A-01" required autoFocus maxLength={64} />
+          </label>
+          <div className="form-row">
+            <label>
+              数量
+              <input name="qty" type="number" min="1" step="1" defaultValue="1" required />
+            </label>
+            <label>
+              采购金额（元）
+              <input name="amount" type="number" min="0.01" step="0.01" required />
+            </label>
+          </div>
+          <label>
+            供应商电话
+            <input name="phone" type="tel" maxLength={32} />
+          </label>
+          <p className="muted">保存后可在列表提交审批，创建人和部门会自动填写。</p>
+          <button className="primary" disabled={busy}>
+            {busy ? '保存中…' : '保存草稿'}
+          </button>
+        </form>
+      </section>
+    </div>
+  );
+}

package/templates/app/apps/web/src/modules/purchase/index.ts

@@ -0,0 +1,2 @@
+// 模块公开入口：应用壳只需要页面，不依赖内部表单与本地状态。
+export { PurchaseOrdersPage } from './pages/purchase-orders-page';

package/templates/app/apps/web/src/modules/purchase/pages/purchase-orders-page.tsx

@@ -0,0 +1,210 @@
+// 采购页面拥有筛选、分页、新建和导出状态；其他模块不用了解这些实现细节。
+import { useState } from 'react';
+import { can, client, purchaseOrder, usePurchaseOrderList, useTransfer } from '@app/contracts';
+import { useCommand } from '../../../shared/hooks/use-command';
+import { errorMessage } from '../../../shared/lib/error-message';
+import { Notice } from '../../../shared/ui/notice';
+import { PageHeading } from '../../../shared/ui/page-heading';
+import { PurchaseOrderForm } from '../components/purchase-order-form';
+
+const statusLabels: Record<string, string> = {
+  draft: '草稿',
+  pending_approval: '待审批',
+  approved: '已通过',
+  received: '已收货',
+  rejected: '已驳回',
+  cancelled: '已取消',
+};
+const currency = (value: string) =>
+  new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' }).format(Number(value));
+
+export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number }) {
+  const [status, setStatus] = useState('');
+  const [page, setPage] = useState(1);
+  const [creating, setCreating] = useState(false);
+  const [exporting, setExporting] = useState(false);
+  const [exportId, setExportId] = useState<string | null>(null);
+  const [exportError, setExportError] = useState('');
+  const exportTask = useTransfer(exportId);
+  const { run, busy, message, clearMessage } = useCommand();
+  // 列表和统计来自服务端；待办数量由 app 组合层传入，采购模块不依赖审批页面。
+  const orders = usePurchaseOrderList({ status, page, pageSize: 10, sort: '-createdAt' });
+  async function exportCsv() {
+    setExporting(true);
+    setExportError('');
+    const result = await purchaseOrder.export({ status });
+    setExporting(false);
+    if (result.ok) setExportId(result.data.id);
+    else setExportError(errorMessage(result));
+  }
+  return (
+    <>
+      <PageHeading eyebrow="PURCHASE ORDERS" title="采购单" description="每一张单据的进展，清晰可见。">
+        {can('PurchaseOrder.create') && (
+          <button className="primary" onClick={() => setCreating(true)}>
+            ＋ 新建采购单
+          </button>
+        )}
+      </PageHeading>
+      {message && <Notice onClose={clearMessage}>{message}</Notice>}
+      {exportError && <Notice onClose={() => setExportError('')}>{exportError}</Notice>}
+      {exportId && (
+        <div role="status" className="notice">
+          {exportTask.isError ? (
+            `导出状态读取失败：${exportTask.error.message}`
+          ) : exportTask.data?.status === 'completed' ? (
+            <a href={client.transferDownloadUrl(exportId)}>导出已完成，点击下载 CSV（24 小时内有效） ↗</a>
+          ) : exportTask.data?.status === 'failed' ? (
+            `导出失败：${exportTask.data.errorCode ?? '请重新尝试'}`
+          ) : exportTask.data?.status === 'expired' ? (
+            '导出文件已过期，请重新导出'
+          ) : (
+            '正在后台生成导出文件…'
+          )}
+          <button onClick={() => setExportId(null)} aria-label="关闭导出提示">
+            ×
+          </button>
+        </div>
+      )}
+      <div className="summary">
+        <div>
+          <small>当前筛选单据</small>
+          <strong>
+            {orders.data?.total ?? '—'}
+            <span> 单</span>
+          </strong>
+        </div>
+        <div>
+          <small>我的待办</small>
+          <strong>
+            {pendingTasks ?? '—'}
+            <span> 项</span>
+          </strong>
+        </div>
+        <div className="summary-note">
+          <span>完整记录 · 每步可追溯</span>
+          <p>
+            提交、审批和同步进展
+            <br />
+            统一记录在单据中。
+          </p>
+        </div>
+      </div>
+      <section className="panel">
+        <div className="toolbar">
+          <div className="filters">
+            {[
+              ['', '全部'],
+              ['draft', '草稿'],
+              ['pending_approval', '待审批'],
+              ['approved', '已通过'],
+              ['received', '已收货'],
+            ].map(([value, label]) => (
+              <button
+                className={status === value ? 'active' : ''}
+                key={value}
+                onClick={() => {
+                  setStatus(value);
+                  setPage(1);
+                }}
+              >
+                {label}
+              </button>
+            ))}
+          </div>
+          {can('PurchaseOrder.export') && (
+            <button disabled={busy || exporting} onClick={exportCsv}>
+              导出 CSV ↗
+            </button>
+          )}
+        </div>
+        {orders.isPending ? (
+          <p className="empty">正在读取采购单…</p>
+        ) : orders.isError ? (
+          <p role="alert" className="error">
+            读取失败：{orders.error.message}
+          </p>
+        ) : (
+          <>
+            <div className="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>单据编号 / 创建时间</th>
+                    <th>物料</th>
+                    <th>采购金额</th>
+                    <th>状态</th>
+                    <th>ERP 单号</th>
+                    <th>操作</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {orders.data.items.map((order) => (
+                    <tr key={order.id}>
+                      <td>
+                        <strong className="mono">PO-{order.id.slice(0, 8).toUpperCase()}</strong>
+                        <small>{new Date(order.createdAt).toLocaleString('zh-CN')}</small>
+                      </td>
+                      <td>{order.items.map((i) => `${i.sku} × ${i.qty}`).join('、')}</td>
+                      <td className="amount">{currency(order.amount)}</td>
+                      <td>
+                        <span className={`badge ${order.status}`}>{statusLabels[order.status]}</span>
+                      </td>
+                      <td className="mono muted">{order.erpNo || '—'}</td>
+                      <td>
+                        <div className="actions">
+                          {order.status === 'draft' && can('PurchaseOrder.submit') && (
+                            <button
+                              disabled={busy}
+                              onClick={() =>
+                                run(() => purchaseOrder.submit(order.id, order.version), '已提交审批')
+                              }
+                            >
+                              提交审批
+                            </button>
+                          )}
+                          {['draft', 'pending_approval', 'approved'].includes(order.status) &&
+                            can('PurchaseOrder.cancel') && (
+                              <button
+                                disabled={busy}
+                                onClick={() =>
+                                  run(() => purchaseOrder.cancel(order.id, order.version), '采购单已取消')
+                                }
+                              >
+                                取消
+                              </button>
+                            )}
+                        </div>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            {!orders.data.items.length && (
+              <div className="empty">
+                <span className="empty-symbol">▤</span>
+                <h3>暂无采购单</h3>
+                <p>新建一张采购单，开始记录你的采购需求。</p>
+              </div>
+            )}
+            <footer className="pagination">
+              <span>
+                共 {orders.data.total} 单 · 第 {page} 页
+              </span>
+              <div>
+                <button disabled={page === 1} onClick={() => setPage(page - 1)}>
+                  上一页
+                </button>
+                <button disabled={page * 10 >= orders.data.total} onClick={() => setPage(page + 1)}>
+                  下一页
+                </button>
+              </div>
+            </footer>
+          </>
+        )}
+      </section>
+      {creating && <PurchaseOrderForm close={() => setCreating(false)} run={run} />}
+    </>
+  );
+}

package/templates/app/apps/web/src/shared/hooks/use-command.ts

@@ -0,0 +1,29 @@
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import type { CageResult } from '@app/contracts';
+import { errorMessage } from '../lib/error-message';
+
+export type RunCommand = (
+  action: () => Promise<CageResult<unknown, string>>,
+  success: string,
+) => Promise<boolean>;
+
+/**
+ * 页面间复用提交状态和结果提示，不包含采购或库存的业务判断。
+ * 成功后使查询缓存失效，让列表从服务端重新读取版本和状态；写入仍由生成 SDK 完成。
+ */
+export function useCommand() {
+  const cache = useQueryClient();
+  const [busy, setBusy] = useState(false);
+  const [message, setMessage] = useState('');
+  const run: RunCommand = async (action, success) => {
+    setBusy(true);
+    setMessage('');
+    const result = await action();
+    setBusy(false);
+    setMessage(result.ok ? success : errorMessage(result));
+    if (result.ok) await cache.invalidateQueries();
+    return result.ok;
+  };
+  return { run, busy, message, clearMessage: () => setMessage('') };
+}

package/templates/app/apps/web/src/shared/lib/error-message.ts

@@ -0,0 +1,15 @@
+import type { CageResult } from '@app/contracts';
+
+/** 将框架错误码转换成操作提示，保留 requestId 供用户向维护人员反馈。 */
+export function errorMessage(r: Extract<CageResult<unknown, string>, { ok: false }>): string {
+  const labels: Record<string, string> = {
+    FORBIDDEN: '你没有执行此操作的权限',
+    INVALID_INPUT: '请检查填写内容',
+    CONFLICT: '单据已更新，请刷新后重试',
+    UNAUTHENTICATED: '登录已过期',
+    CONSTRAINT_VIOLATED: '未满足审批条件，请检查审批人或额度',
+    STOCK_SHORT: '库存不足',
+    NETWORK: '连接失败，请稍后重试',
+  };
+  return `${labels[r.domainCode ?? r.code] ?? r.domainCode ?? r.code}${r.requestId ? ` · 请求 ${r.requestId.slice(0, 8)}` : ''}`;
+}

package/templates/app/apps/web/src/shared/ui/notice.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+
+/** 通用提示容器只负责呈现；提示文案和关闭后的业务行为由调用页面决定。 */
+export function Notice({ children, onClose }: { children: ReactNode; onClose: () => void }) {
+  return (
+    <div role="status" className="notice">
+      {children}
+      <button onClick={onClose} aria-label="关闭提示">
+        ×
+      </button>
+    </div>
+  );
+}

package/templates/app/apps/web/src/shared/ui/page-heading.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+
+/** 统一页面标题的排版；不读取路由或业务状态，避免共享 UI 反向依赖某项业务。 */
+export function PageHeading({
+  eyebrow,
+  title,
+  description,
+  children,
+}: {
+  eyebrow: string;
+  title: string;
+  description: string;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="page-title">
+      <div>
+        <span className="eyebrow">{eyebrow}</span>
+        <h1>
+          {title}
+          <span className="title-dot">.</span>
+        </h1>
+        <p className="muted">{description}</p>
+      </div>
+      {children}
+    </div>
+  );
+}

package/templates/app/apps/web/vite.config.ts

@@ -4,6 +4,9 @@ import { defineConfig } from 'vite';
 // Windows 的 Docker/Hyper-V 可能保留 5173，允许从项目 .env 显式选择可用端口。
 const api = `http://127.0.0.1:${process.env.PORT ?? '3000'}`;
 export default defineConfig({
+  // 本地 --framework-path 会把 SDK 链接到另一个 node_modules。
+  // hooks 与页面必须共用同一个 React/Query 实例，否则构建成功也会在登录后白屏。
+  resolve: { dedupe: ['react', 'react-dom', '@tanstack/react-query'] },
   server: {
     port: Number(process.env.CAGE_WEB_PORT ?? 5173),
     strictPort: true,

package/templates/app/cage.config.json

@@ -1,8 +1,8 @@
 {
   "domain": "packages/domain/src/index.ts",
   "contracts": "packages/contracts/src",
+  "structure": "modular",
   "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
-  "devDbPort": 54329,
   "graph": {
     "title": "采购业务图谱",
     "labels": {

package/templates/app/docs/ai/README.md

@@ -0,0 +1,77 @@
+# 业务开发指南（给 Codex 等编程工具）
+
+这是 `create-cage-app` 产物自带的业务开发资料。目标是让 Codex 等编程工具只读当前项目，就能增加业务对象、操作、审批、报表和页面。先读根目录 `AGENTS.md`，再按任务定位本页资料；无需另行克隆 Cage 框架仓库。
+
+## 先认识当前应用
+
+| 目录 | 开发业务时放什么 |
+| --- | --- |
+| `packages/domain/src/modules/<业务>` | 按业务集中聚合、命令、事件、审批、查询与任务；跨模块反应放 workflows，外部协议放 integrations |
+| `packages/contracts/src/aggregates`、`queries` | 按聚合目录生成 API 与类型；通过根 @app/contracts 使用，通过 gen 更新 |
+| `apps/api/src` | API 与 worker 的薄启动入口；普通业务不在这里写路由 |
+| `apps/web/src/app`、`modules`、`shared` | 应用组合 / 业务页面与交互 / 无具体业务归属的共用代码 |
+| `db/migrations` | 生成后审查的迁移；更新已有数据库中的表 |
+| `.env` / `.env.example` | 本机配置 / 不含真实凭证的配置说明 |
+| `docs/ai`、`docs/errors` | 业务开发方法与错误排查 |
+
+下文路径均相对**应用根目录**，即生成项目的 `package.json` 所在目录。框架包使用 `@yss123/cage-*`，作为依赖安装；当前项目不应复制或重新实现这些包。框架维护者在源码仓库读本页时，应用根目录为 `examples/purchase-admin`。
+
+创建时可选 `blank`（空白业务项目）或 `purchase`（采购示例项目）。空白项目只有组织基础模型，新增客户业务写入根目录的 `packages/domain/src`；采购参考源码放在 `docs/examples/purchase-admin`，不参与注册、编译或建表。阅读本指南中的采购路径时，空白项目在该参考目录下查找，采购项目直接在应用根目录查找。先读本项目 AGENTS.md 的模板说明，不能把参考代码误当成已运行的业务。
+
+## 推荐阅读顺序
+
+| 顺序 | 资料 | 读完应能回答 |
+| --- | --- | --- |
+| 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
+| 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
+| 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
+| 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
+| 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
+| 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
+| 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
+| 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
+| 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
+| 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
+
+第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
+
+## 按任务找入口
+
+| 用户需求 | 优先修改 | 需要一起考虑 |
+| --- | --- | --- |
+| 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
+| 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
+| 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
+| 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
+| 修改审批顺序/条件/选人 | 所属领域模块 `approvals.ts` | `routable`、角色/负责人数据、结论命令约束 |
+| 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
+| 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
+| 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
+| 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
+| 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
+
+## 三份协作材料各管什么
+
+- **AGENTS.md** 是工作入口：必守边界、目录、顺序和验证要求。`<!-- cage:begin ... -->` 到 `<!-- cage:end -->` 为框架托管区，`cage sync` 更新它；项目自己的规则放在外面。
+- **标准范例** 是可运行证据：采购模板包含完整运行链路，空白模板保留离线参考源码。按需学习其中模式，客户业务仍写在本项目自己的 domain 和页面中。
+- **错误码册** 是诊断索引：按真实错误码查位置、触发原因、修复步骤和正反例；不要靠放开权限或关闭门禁“修好”报错。
+
+`docs/ai` 与 `docs/errors` 已放入分发模板，创建项目时一起复制，可离线阅读。框架仓库中的标准范例使用根目录的规范文档，资料位置由应用 AGENTS.md 指明。
+
+## 当前实现边界
+
+以下区分可避免 agent 把方案中的愿景写成不存在的功能。
+
+| 已有能力 | 使用边界 |
+| --- | --- |
+| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
+| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
+| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
+| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
+| 代码审批路由与适配接口 | 顺序步骤、条件步骤、步骤内任一/全部审批；没有通用可视化流程设计器、任意 JS 选人、转签/加签 API |
+| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
+| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
+| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
+| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
+
+文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。