@yss123/cage-cli 0.2.0 → 0.3.0

package/templates/app/apps/web/src/shared/ui/attachment-upload.tsx

@@ -0,0 +1,163 @@
+/**
+ * 受控附件选择与可恢复上传界面，连接客户端分片任务、上传会话查询和父表单的附件 ID。
+ * 上传 ready 仅说明字节准备完成，正式绑定到业务记录仍需调用方提交领域命令。
+ * 本地校验用于及时反馈，文件策略、归属与下载权限始终由服务端重新检查。
+ */
+// 文件上传与业务保存分开：这里只产出已完成的 ID，最终关联仍由调用方的领域命令提交。
+import { useEffect, useRef, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { client, useFileUpload, type FileUploadTask, type UploadSession } from '@app/contracts';
+import './attachment-upload.css';
+
+/**
+ * 上传组件契约：父组件持有附件草稿，上传任务状态在本组件内维护。
+ */
+interface Props {
+  /**
+   * 最终绑定附件的完整命令名，供服务端验证上传用途及调用能力。
+   */
+  command: string;
+  /**
+   * 该命令目标聚合上的文件字段名，必须匹配生成的字段策略。
+   */
+  field: string;
+  /**
+   * 编辑已有记录时的目标 UUID；创建命令尚无记录时省略。
+   */
+  targetId?: string;
+  /**
+   * 由生成契约提供的策略：maxBytes 为字节上限，maxCount 缺省按单附件，accept 为允许的 MIME 列表。
+   */
+  policy: { maxBytes: number; maxCount?: number; accept: readonly string[] };
+  /**
+   * 父表单当前选择的已准备附件 ID；不是服务端已经保存的关联证明。
+   */
+  value: string[];
+  /**
+   * 附件新增或移除时回传完整 ID 列表，父表单决定何时提交。
+   */
+  onChange: (ids: string[]) => void;
+  /**
+   * 当任一任务处于上传流程时通知父表单，以便阻止不完整附件的保存。
+   */
+  onBusyChange: (busy: boolean) => void;
+}
+/**
+ * 以 1024 为单位换算文件大小供展示；输入为字节，不参与服务端大小限制判断。
+ */
+const size = (bytes: number) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : bytes >= 1024 ** 2 ? `${(bytes / 1024 ** 2).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`;
+
+/**
+ * 按 id 查询可访问的文件元信息，成功后提供受服务端鉴权的下载地址。
+ * 加载与不可访问分别提示；不通过存储内部路径绕过下载权限。
+ */
+export function FileLink({ id }: { id: string }) {
+  const query = useQuery({ queryKey: ['file-info', id], queryFn: async () => {
+    const result = await client.fileInfo(id);
+    if (!result.ok) throw new Error(result.code);
+    return result.data;
+  } });
+  if (query.isPending) return <span className="muted">正在读取附件…</span>;
+  if (query.isError) return <span role="status">附件不可访问</span>;
+  return <a href={client.fileDownloadUrl(id)}>{query.data.filename} <small className="muted">{size(query.data.bytes)}</small></a>;
+}
+
+/**
+ * 先读取匹配 command/field/targetId 的可恢复会话，再创建或继续本地文件任务。
+ * 通过 refs 读取最新父表单值及任务列表，卸载时 dispose 已创建任务；取消/删除业务关联不是卸载的隐含效果。
+ * 父组件负责保存 value；移除选中项只改变草稿，不直接删除服务端已绑定文件。
+ */
+export function AttachmentUpload(props: Props) {
+  const { command, field, targetId, policy, value, onChange, onBusyChange } = props;
+  const current = useRef(props); current.current = props;
+  const [tasks, setTasks] = useState<{ key: number; file: File; task: FileUploadTask }[]>([]);
+  const [error, setError] = useState('');
+  const sequence = useRef(0), tasksRef = useRef(tasks); tasksRef.current = tasks;
+  const [active, setActive] = useState<Record<number, boolean>>({});
+  const pending = useQuery({ queryKey: ['file-uploads', command, field, targetId], queryFn: async () => {
+    const result = await client.uploadSessions({ command, field, targetId });
+    if (!result.ok) throw new Error(result.code);
+    return result.data;
+  } });
+  useEffect(() => { onBusyChange(Object.values(active).some(Boolean)); }, [active, onBusyChange]);
+  useEffect(() => () => { for (const entry of tasksRef.current) entry.task.dispose(); }, []);
+
+  /**
+   * 校验选中文件数量、字节大小和 MIME 后构造上传任务；session 可指定待续传的会话。
+   * 数量同时计入已选附件与未结束任务，续传时实际文件内容匹配由 SDK/服务端验证。
+   */
+  function add(files: FileList | null, session?: UploadSession) {
+    if (!files?.length) return;
+    setError('');
+    const maximum = policy.maxCount ?? 1;
+    const working = tasks.filter(entry => !['completed', 'cancelled'].includes(entry.task.getSnapshot().status)).length;
+    if (value.length + working + files.length > maximum) { setError(`最多选择 ${maximum} 个附件，请先取消多余任务。`); return; }
+    for (const file of Array.from(files)) {
+      if (file.size < 1 || file.size > policy.maxBytes || !policy.accept.includes(file.type || 'application/octet-stream')) {
+        setError(`“${file.name}”的大小或类型不符合要求。`); continue;
+      }
+      const task = client.upload(file, { command, field, targetId }, { uploadId: session?.id });
+      const key = ++sequence.current;
+      setActive(previous => ({ ...previous, [key]: true }));
+      setTasks(previous => [...previous, { key, file, task }]);
+    }
+  }
+  /**
+   * 把已准备的上传 ID 纳入当前父表单草稿；读取最新 props，拒绝重复项及超过数量上限。
+   * 名字表示采用完成结果，此函数是事件处理器，不是 React hook。
+   */
+  function useCompleted(id: string) {
+    const { value, onChange, policy } = current.current;
+    if (value.includes(id)) return;
+    if (value.length >= (policy.maxCount ?? 1)) { setError('附件数量已达到上限，请移除后重试。'); return; }
+    onChange([...value, id]);
+  }
+  const taskIds = new Set(tasks.map(entry => entry.task.getSnapshot().id));
+  const recoverable = (pending.data ?? []).filter(session => !value.includes(session.id) && !taskIds.has(session.id));
+  return <div className="attachment-upload">
+    <div className="attachment-heading"><strong>附件</strong><span className="muted">{value.length} / {policy.maxCount ?? 1}</span></div>
+    <label className="attachment-picker">
+      <span>＋ 选择文件</span>
+      <input type="file" multiple={(policy.maxCount ?? 1) > 1} accept={policy.accept.join(',')} disabled={value.length >= (policy.maxCount ?? 1)}
+        onChange={event => { add(event.target.files); event.target.value = ''; }} />
+      <small>支持暂停与续传 · 单文件最大 {size(policy.maxBytes)}</small>
+    </label>
+    <p className="muted attachment-hint">上传完成后，保存记录才会正式关联；未完成的上传可以稍后恢复。</p>
+    {error && <p role="alert" className="attachment-error">{error}</p>}
+    {value.map(id => <div className="attachment-row" key={id}><FileLink id={id} /><button type="button" onClick={() => onChange(value.filter(item => item !== id))}>移除</button></div>)}
+    {tasks.map(entry => value.includes(entry.task.getSnapshot().id ?? '') ? null : <UploadRow key={entry.key} file={entry.file} task={entry.task}
+      onDone={id => { setActive(previous => ({ ...previous, [entry.key]: false })); useCompleted(id); }} onBusy={busy => setActive(previous => previous[entry.key] === busy ? previous : ({ ...previous, [entry.key]: busy }))} />)}
+    {recoverable.length > 0 && <div className="attachment-recovery"><strong>可恢复的上传</strong><p className="muted">继续上传时，请重新选择原文件；已完成部分会先核对内容。</p>
+      {recoverable.map(session => <div className="attachment-row" key={session.id}><span>{session.filename} <small className="muted">{size(session.bytes)}</small></span><div className="actions">
+        {session.status === 'ready' ? <button type="button" onClick={() => useCompleted(session.id)}>使用附件</button> : <label className="attachment-resume">选择原文件续传<input type="file" onChange={event => { add(event.target.files, session); event.target.value = ''; }} /></label>}
+        <button type="button" onClick={async () => { const result = await client.cancelUpload(session.id); if (result.ok) void pending.refetch(); else setError('取消失败，请重试。'); }}>取消</button>
+      </div></div>)}
+    </div>}
+    {pending.isError && <p role="status" className="muted">暂时无法查询可恢复任务。<button type="button" onClick={() => void pending.refetch()}>重试</button></p>}
+  </div>;
+}
+
+/**
+ * 订阅单个 FileUploadTask，挂载后启动，向父组件报告 busy 与完成 ID。
+ * 进度使用 confirmedBytes；暂停/继续/取消交给 SDK，失败从订阅快照显示。
+ * start/cancel 的 Promise 失败在这里不另行抛到页面，错误可见性依赖任务状态；资源释放由外层统一处理。
+ */
+function UploadRow({ file, task, onDone, onBusy }: { file: File; task: FileUploadTask; onDone: (id: string) => void; onBusy: (busy: boolean) => void }) {
+  const state = useFileUpload(task);
+  const callbacks = useRef({ onDone, onBusy }); callbacks.current = { onDone, onBusy };
+  const busy = ['initializing', 'verifying', 'uploading', 'completing'].includes(state.status);
+  const start = () => { void task.start().then(session => callbacks.current.onDone(session.id)).catch(() => {}); };
+  useEffect(() => { start(); }, [task]);
+  useEffect(() => { callbacks.current.onBusy(busy); }, [busy]);
+  const labels = { idle: '等待上传', initializing: '准备上传', verifying: '核对已上传内容', uploading: '上传中', paused: '已暂停', completing: '校验与合并中', completed: '上传完成', failed: '上传失败，可重试', cancelled: '已取消' };
+  if (state.status === 'cancelled') return null;
+  return <div className="attachment-task"><div className="attachment-row"><span>{file.name}</span><div className="actions">
+    {busy && state.status !== 'completing' && <button type="button" onClick={() => task.pause()}>暂停</button>}
+    {['paused', 'failed', 'completed'].includes(state.status) && <button type="button" onClick={state.status === 'completed' && state.id ? () => onDone(state.id!) : start}>{state.status === 'completed' ? '使用附件' : '继续'}</button>}
+    <button type="button" onClick={() => { void task.cancel().catch(() => {}); }}>取消</button>
+  </div></div>
+    <progress aria-label={`${file.name} 上传进度`} max={state.totalBytes} value={state.confirmedBytes} />
+    <div className="attachment-progress" role="status"><span>{labels[state.status]}</span><span>{size(state.confirmedBytes)} / {size(state.totalBytes)}{state.bytesPerSecond > 0 ? ` · ${size(state.bytesPerSecond)}/s` : ''}</span></div>
+    {state.error && <p className="attachment-error">{({ NETWORK: '网络中断，已上传内容会保留。', TIMEOUT: '请求超时，可继续重试。', FORBIDDEN: '权限不足，请联系管理员。', UNAUTHENTICATED: '登录已失效，请重新登录。', NOT_FOUND: '上传会话或业务记录不可访问。', INVALID_INPUT: '文件不符合要求，请重新选择。', CONFLICT: '上传状态有变化，请稍后重试。', RATE_LIMITED: '上传配额或请求次数已达上限，请稍后重试。' } as Record<string, string>)[state.error] ?? state.error}</p>}
+  </div>;
+}

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

@@ -1,6 +1,13 @@
+/**
+ * 业务操作结果的可关闭提示，内容和关闭状态由页面或 useCommand 持有。
+ */
 import type { ReactNode } from 'react';
 
 /** 通用提示容器只负责呈现；提示文案和关闭后的业务行为由调用页面决定。 */
+/**
+ * 呈现 children 消息并在关闭按钮点击时调用 onClose。
+ * 仅关闭提示，不回滚已经提交的命令，也不取消正在运行的任务。
+ */
 export function Notice({ children, onClose }: { children: ReactNode; onClose: () => void }) {
   return (
     <div role="status" className="notice">

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

@@ -1,6 +1,13 @@
+/**
+ * 业务页公共标题区，统一标题、说明与右侧操作的布局，不包含查询和权限逻辑。
+ */
 import type { ReactNode } from 'react';
 
 /** 统一页面标题的排版；不读取路由或业务状态，避免共享 UI 反向依赖某项业务。 */
+/**
+ * 展示 eyebrow 分类文字、title 主标题、description 说明和 children 操作区。
+ * 操作按钮及其 can 检查由使用页面提供；此组件不会替调用方判断权限。
+ */
 export function PageHeading({
   eyebrow,
   title,

package/templates/app/apps/web/src/shared/ui/page-state.css

@@ -0,0 +1,47 @@
+/**
+ * 共享页面状态卡与返回链接的样式，采购和空白模板均由同步流程取得同一版本。
+ * 颜色变量由应用主题提供；这里只排版标题、说明和操作，具体错误分类由 PageState/QueryFailure 决定。
+ */
+/* 与两套工作台共享的纸面状态卡；状态清楚可读，链接保持可聚焦和可复制。 */
+.route-state {
+  margin: 32px 0;
+  padding: 68px 36px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #fdfefb;
+  text-align: center;
+}
+.route-state-mark {
+  display: block;
+  margin-bottom: 20px;
+  color: #7d9866;
+  font:
+    italic 42px Georgia,
+    serif;
+}
+.route-state h1 {
+  font-size: 26px;
+  letter-spacing: -0.5px;
+}
+.route-state p {
+  margin: 16px 0 26px;
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.9;
+}
+.route-link {
+  display: inline-flex;
+  align-items: center;
+  padding: 10px 16px;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  background: #f1f5eb;
+  color: var(--green);
+  font-size: 12px;
+}
+.route-link:hover {
+  background: #e4ecd9;
+}
+.route-state > button {
+  margin-left: 12px;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 供列表、详情和路由守卫复用的页面级状态组件。
+ * 将服务端可确认的错误与可恢复操作对应，保留返回链接；不泄露范围外记录是否真实存在。
+ */
+import type { ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { CageQueryError } from '@app/contracts';
+import './page-state.css';
+
+/** 页面级状态保留导航入口，详情直达失败时也能回到列表，而不是出现空白页。 */
+/**
+ * 渲染标题、说明、返回链接和可选附加操作。
+ * props.title/description 为调用方提供的当前状态；to 是业务返回地址，label 缺省为返回列表。
+ * children 可放重试按钮；组件只呈现内容，不自行读取数据或推断错误。
+ */
+export function PageState({
+  title,
+  description,
+  to,
+  label = '返回列表',
+  children,
+}: {
+  title: string;
+  description: string;
+  to: string;
+  label?: string;
+  children?: ReactNode;
+}) {
+  return (
+    <section className="route-state" aria-labelledby="route-state-title">
+      <span className="route-state-mark" aria-hidden="true">
+        ↗
+      </span>
+      <h1 id="route-state-title">{title}</h1>
+      <p>{description}</p>
+      <Link className="route-link" to={to}>
+        {label}
+      </Link>
+      {children}
+    </section>
+  );
+}
+
+/** 按服务端错误区分权限、范围/不存在和服务故障；不从 URL 推断记录是否存在。 */
+/**
+ * 将查询异常映射为页面状态。CageQueryError 的 FORBIDDEN 与 NOT_FOUND 不展示重试按钮，其他错误允许调用 retry。
+ * props.error 为实际查询异常；to/label 决定退出路径，retry 由页面绑定 refetch。
+ * NOT_FOUND 同时涵盖记录不存在与不在可访问范围，不能据此向用户确认数据库中有无此记录。
+ */
+export function QueryFailure({
+  error,
+  to,
+  label,
+  retry,
+}: {
+  error: Error;
+  to: string;
+  label?: string;
+  retry: () => void;
+}) {
+  const code = error instanceof CageQueryError ? error.result.code : undefined;
+  const title = code === 'FORBIDDEN' ? '暂无访问权限' : code === 'NOT_FOUND' ? '记录不可用' : '暂时无法读取';
+  const description =
+    code === 'FORBIDDEN'
+      ? '当前账号没有访问此页面所需的权限，请联系管理员。'
+      : code === 'NOT_FOUND'
+        ? '记录不存在，或不在你当前可访问的数据范围内。'
+        : code === 'UNAUTHENTICATED'
+          ? '登录已过期，请重新登录后继续。'
+          : '请检查网络或稍后重新尝试。';
+  return (
+    <PageState title={title} description={description} to={to} label={label}>
+      {code !== 'FORBIDDEN' && code !== 'NOT_FOUND' && <button onClick={retry}>重新读取</button>}
+    </PageState>
+  );
+}

package/templates/app/apps/web/src/shared/ui/require-capability.tsx

@@ -0,0 +1,34 @@
+/**
+ * 业务路由的界面能力守卫，根据当前 SDK 能力快照决定渲染页面还是无权限提示。
+ * 服务端对请求独立授权；缓存中的能力只影响界面入口，不增加数据可见范围。
+ */
+import type { ReactNode } from 'react';
+import { useCan } from '@app/contracts';
+import { PageState } from './page-state';
+
+/** 直接输入 URL 也给出权限提示；真正的授权和数据范围仍由后端接口强制执行。 */
+/**
+ * 检查 capability 对应的页面入口权限，允许时渲染 children，否则提供回到 home 的链接。
+ * 需放在已恢复会话的路由内，避免把尚未加载的能力列表当作最终账号权限。
+ */
+export function RequireCapability({
+  capability,
+  children,
+  home,
+}: {
+  capability: Parameters<typeof useCan>[0];
+  children: ReactNode;
+  home: string;
+}) {
+  const allowed = useCan(capability);
+  return allowed ? (
+    children
+  ) : (
+    <PageState
+      title="暂无访问权限"
+      description="当前账号没有访问此页面所需的权限，请联系管理员。"
+      to={home}
+      label="返回工作台"
+    />
+  );
+}

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

@@ -1,3 +1,8 @@
+/**
+ * 采购 Web 的 Vite 配置：选定严格端口并将 API、认证、附件等请求代理到本地后端。
+ * 对 React 及查询库去重，避免 workspace 中出现多个 hooks 上下文。
+ * 此处代理只服务开发环境，生产部署的 SPA 回退与接口转发由部署配置负责。
+ */
 import { defineConfig } from 'vite';
 
 // 浏览器请求保持同源，让 cookie 会话和 CSRF 验证与生产环境使用同一种方式。

package/templates/app/cage.config.json

@@ -6,6 +6,8 @@
   "graph": {
     "title": "采购业务图谱",
     "labels": {
+      "module:purchase": "采购管理",
+      "module:inventory": "库存管理",
       "aggregate:PurchaseOrder": "采购单",
       "aggregate:Inventory": "库存台账",
       "aggregate:InventoryLock": "库存锁",
@@ -13,6 +15,13 @@
       "aggregate:User": "用户",
       "aggregate:Role": "角色",
       "command:PurchaseOrder.create": "新建采购单",
+      "command:PurchaseOrder.explainPurpose": "补充采购用途",
+      "command:PurchaseOrder.returnForChanges": "退回修改",
+      "field:PurchaseOrder.reason": "采购用途",
+      "capability:Sys.ai.use": "使用智能助理",
+      "capability:Sys.ai.models.manage": "管理 AI 模型",
+      "command:PurchaseOrder.setAttachments": "修改采购附件",
+      "field:PurchaseOrder.attachments": "采购附件",
       "command:PurchaseOrder.submit": "提交审批",
       "command:PurchaseOrder.approve": "通过审批",
       "command:PurchaseOrder.reject": "驳回审批",

package/templates/app/db/migrations/0002_draft.sql

@@ -0,0 +1,12 @@
+-- 迁移草稿：由 cage gen 生成，人审后提交；已发布的迁移不要修改
+-- 破坏性变更按「先扩展再收缩」分多次发布
+
+-- 新列 PurchaseOrder.attachments（必填）：先加可空列，回填后再加 NOT NULL
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "attachments" jsonb;
+-- 已有采购单没有附件；审查后的前向迁移只填充新列，保留所有既有业务字段。
+UPDATE "core"."purchase_order" SET "attachments" = '[]'::jsonb WHERE "attachments" IS NULL;
+ALTER TABLE "core"."purchase_order" ALTER COLUMN "attachments" SET NOT NULL;
+
+/* cage:schema
+{"version":1,"tables":[{"schema":"core","name":"inventory","aggregate":"Inventory","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"sku","type":"text","notNull":true,"unique":true},{"name":"available","type":"integer","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","deleted"],"indexes":[{"name":"inventory_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"inventory_lock","aggregate":"InventoryLock","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"order_id","type":"uuid","notNull":true},{"name":"items","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["held","released"],"indexes":[{"name":"inventory_lock_status_idx","columns":["tenant_id","status"]}]},{"schema":"sys","name":"dept","aggregate":"Dept","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"name","type":"text","notNull":true},{"name":"code","type":"text","notNull":false},{"name":"parent_id","type":"uuid","notNull":false,"references":"sys.dept"},{"name":"ancestors","type":"text","notNull":true},{"name":"leader_id","type":"uuid","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"dept_status_idx","columns":["tenant_id","status"]},{"name":"dept_parent_id_idx","columns":["parent_id"]}]},{"schema":"sys","name":"user","aggregate":"User","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"username","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"role_ids","type":"jsonb","notNull":true},{"name":"phone","type":"text","notNull":false},{"name":"email","type":"text","notNull":false},{"name":"sso_subject","type":"text","notNull":false},{"name":"password_hash","type":"text","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","disabled"],"indexes":[{"name":"user_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"user_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"purchase_order","aggregate":"PurchaseOrder","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"created_by","type":"uuid","notNull":true,"references":"sys.user"},{"name":"supplier_phone","type":"text","notNull":false},{"name":"amount","type":"numeric(18,2)","notNull":true},{"name":"items","type":"jsonb","notNull":true},{"name":"erp_no","type":"text","notNull":false},{"name":"attachments","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["draft","pending_approval","approved","received","rejected","cancelled"],"indexes":[{"name":"purchase_order_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"purchase_order_tenant_created_by_idx","columns":["tenant_id","created_by"]},{"name":"purchase_order_status_idx","columns":["tenant_id","status"]}]},{"schema":"sys","name":"role","aggregate":"Role","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"code","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"capabilities","type":"jsonb","notNull":true},{"name":"scopes","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"role_status_idx","columns":["tenant_id","status"]}]}]}
+*/

package/templates/app/db/migrations/0003_draft.sql

@@ -0,0 +1,8 @@
+-- 迁移草稿：由 cage gen 生成，人审后提交；已发布的迁移不要修改
+-- 破坏性变更按「先扩展再收缩」分多次发布
+
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "reason" text;
+
+/* cage:schema
+{"version":1,"tables":[{"schema":"core","name":"inventory","aggregate":"Inventory","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"sku","type":"text","notNull":true,"unique":true},{"name":"available","type":"integer","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","deleted"],"indexes":[{"name":"inventory_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"inventory_lock","aggregate":"InventoryLock","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"order_id","type":"uuid","notNull":true},{"name":"items","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["held","released"],"indexes":[{"name":"inventory_lock_status_idx","columns":["tenant_id","status"]}]},{"schema":"sys","name":"dept","aggregate":"Dept","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"name","type":"text","notNull":true},{"name":"code","type":"text","notNull":false},{"name":"parent_id","type":"uuid","notNull":false,"references":"sys.dept"},{"name":"ancestors","type":"text","notNull":true},{"name":"leader_id","type":"uuid","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"dept_status_idx","columns":["tenant_id","status"]},{"name":"dept_parent_id_idx","columns":["parent_id"]}]},{"schema":"sys","name":"user","aggregate":"User","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"username","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"role_ids","type":"jsonb","notNull":true},{"name":"phone","type":"text","notNull":false},{"name":"email","type":"text","notNull":false},{"name":"sso_subject","type":"text","notNull":false},{"name":"password_hash","type":"text","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","disabled"],"indexes":[{"name":"user_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"user_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"purchase_order","aggregate":"PurchaseOrder","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"created_by","type":"uuid","notNull":true,"references":"sys.user"},{"name":"supplier_phone","type":"text","notNull":false},{"name":"amount","type":"numeric(18,2)","notNull":true},{"name":"reason","type":"text","notNull":false},{"name":"items","type":"jsonb","notNull":true},{"name":"erp_no","type":"text","notNull":false},{"name":"attachments","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["draft","pending_approval","approved","received","rejected","cancelled"],"indexes":[{"name":"purchase_order_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"purchase_order_tenant_created_by_idx","columns":["tenant_id","created_by"]},{"name":"purchase_order_status_idx","columns":["tenant_id","status"]}]},{"schema":"sys","name":"role","aggregate":"Role","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"code","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"capabilities","type":"jsonb","notNull":true},{"name":"scopes","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"role_status_idx","columns":["tenant_id","status"]}]}]}
+*/

package/templates/app/deploy/nginx.conf

@@ -0,0 +1,52 @@
+# 示例：Nginx 与 Cage API 在同一主机，API 监听 3000。
+# 将 root 换成实际构建产物目录；容器部署时将 proxy_pass 换成 API 服务地址。
+server {
+    listen 80;
+    server_name _;
+    root /srv/cage/web;
+    index index.html;
+
+    # 单次请求只承载一个分片；流式转发避免代理先把完整分片落盘。
+    location ~ ^/api/sys/uploads/[^/]+/parts/[0-9]+$ {
+        client_max_body_size 16m;
+        proxy_request_buffering off;
+        proxy_http_version 1.1;
+        proxy_read_timeout 1800s;
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    # AI 事件必须逐段送达浏览器，不能由代理压缩或聚齐完整回复再交付。
+    location ~ ^/api/ai/(runs/[^/]+/events|admin/personality-preview)$ {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_cache off;
+        gzip off;
+        proxy_read_timeout 75s;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    # 服务端拥有的入口保留原 URI；包含 /admin 的页面、脚本和样式。
+    location ~ ^/(api|auth|hooks|admin)(/|$) {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+    location = /healthz {
+        proxy_pass http://127.0.0.1:3000;
+    }
+    # 丢失的构建资源直接 404，防止浏览器把 index.html 当作 JS/CSS 解析。
+    location ^~ /assets/ {
+        try_files $uri =404;
+    }
+    # 业务详情深链接交给 React Router，刷新后仍能进入同一页面。
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

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

@@ -25,16 +25,27 @@
 | 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
 | 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
 | 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
+| 编码必读 | [详细中文注释规范](commenting.md) | 如何说明文件职责、API、字段、关键流程、权限/事务与失败边界，并同步维护注释？ |
 | 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
+| 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
 | 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
+| 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
+| 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
 | 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
 | 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
 | 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
 | 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
 | 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
+| 按需 | [文件字段与断点续传](files.md) | 私有上传、分片恢复、命令绑定、下载授权和存储部署 |
 
 第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
 
+框架源码与脚手架应用都要求详细中文注释。新建或修改代码时按[注释规范](commenting.md)同步说明文件职责与调用链、导出 API/类型字段、组件/hooks 和关键流程的“做什么、为什么、怎么做、边界”；修改既有行为时连同相关上下游说明一起更新。注释属于交付内容，不能用“代码自解释”免除，也不能以逐行翻译或注释字数代替质量。
+
+不确定框架支持什么时先用 `pnpm exec cage capabilities 关键词 --format json` 查看当前版本公开签名；功能未生效时用 `pnpm exec cage doctor` 区分注册、生成、构建、迁移、授权和实际进程。未检查项为 `unknown`，不能作为验证通过。
+
+遇到 AI 审批、业务助理、随页助理、模型管理、性格或 Responses 需求，先读[原生智能化指南](intelligence.md)。这些是框架可选能力：后端循环、工具、会话与偏好记忆、HTTP 和 SDK 由框架提供；应用配置声明、策略、授权、页面快照及界面。入口不要求每次加载整份本体或全部指南，按本次任务读取相关章节即可。
+
 ## 按任务找入口
 
 | 用户需求 | 优先修改 | 需要一起考虑 |
@@ -42,11 +53,16 @@
 | 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
 | 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
 | 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
+| 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
 | 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
 | 修改审批顺序/条件/选人 | 所属领域模块 `approvals.ts` | `routable`、角色/负责人数据、结论命令约束 |
+| AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
+| 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
+| 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
 | 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
 | 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
 | 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
+| 文件上传/业务附件 | file/files 字段 + 用户命令 + 客户端上传任务 | 断点续传、当前权限、命令绑定、私有存储及清理；见[文件指南](files.md) |
 | 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
 | 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
 
@@ -68,9 +84,14 @@
 | 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
 | fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
 | 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
+| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
+| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
 | 代码审批路由与适配接口 | 顺序步骤、条件步骤、步骤内任一/全部审批；没有通用可视化流程设计器、任意 JS 选人、转签/加签 API |
+| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
+| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
 | 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
 | 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
+| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
 | 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
 | 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
 

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

@@ -69,6 +69,14 @@ worker → 消费 outbox → 异步反应 / 审批 / 连接器
 
 资源标签 `acquires: 'inventory.lock'`、`releases: 'inventory.lock'` 为图规则提供证据。它们不会自动加锁或释放，真正效果来自 `acquireLock/releaseLock` 命令。
 
+有界批量步骤可用 `reactionEach`：声明目标命令、最大项数、唯一排序键和映射，按稳定顺序串行调用。`order` 表达同一事件的步骤依赖，同事务链仍整体回滚。具体声明见[原语指南](primitives.md#有界集合与步骤顺序)。
+
+出站分成外部执行与短事务回写两个阶段。框架先领取本地执行租约，用 `${tenantId}:${declaredKey}` 作为远端幂等键，可靠保存回执后再在短事务调用成功命令；回写失败可复用已保存回执。远端必须实际支持幂等，框架不能承诺任意外部系统恰好一次。不可安全重试的写入结果未知时隔离并要求核对，不能把超时当作远端未执行。
+
+当前没有通用的远端回执确认或解除 `unknown` 的管理入口，普通死信重放不会解除未知状态。此类操作要按连接器实际协议制定受控恢复或业务补偿；不能发明恢复 API，也不能直接 SQL 改执行状态后重发。
+
+首阶段按单机、API 与 worker 同版本升级部署。worker 启动校验必要引擎，发布消费者清单、注册指纹和心跳；不认识事件或缺少必要消费者时不会静默完成。停止时先停新任务、取消可取消 IO，再有界等待在途工作；定时任务同时使用本地运行标记与数据库互斥锁防止跨周期/实例重叠。连接器限流和认证队列均为单进程预算，多实例共享限流另需设计。
+
 ## 权限是几层判断
 
 | 层 | 例子 | 说明 |
@@ -84,6 +92,23 @@ worker → 消费 outbox → 异步反应 / 审批 / 连接器
 
 `useCan()`、`can()` 只决定按钮呈现；前端隐藏按钮不能代替后端授权。新增命令不会自动授给已有生产角色，角色分配和额度调整也受防提权约束。
 
+授权通知监听异常时不再复用缓存，每次重新读取授权；重新订阅后清空缓存，并阻止旧请求回填旧上下文。`/readyz` 反映数据库和授权监听健康，`/healthz` 仅表示存活。诊断入口受 `Sys.ops.read` 及相关对象 read/范围控制，`explain` 解释调用身份、能力、范围、状态与硬约束，不能预测 handler 的业务结果；新建对象的最终范围无法提前确定时返回 unknown。
+
+## 审计保证
+
+| 入口 | 保证与失败行为 |
+| --- | --- |
+| 命令成功 | 与业务变更、版本和 outbox 同事务提交；写审计失败整笔回滚 |
+| 命令拒绝 | FORBIDDEN / NOT_FOUND / CONSTRAINT_VIOLATED 异步尽力记录；失败有日志，不宣称所有错误均已留痕 |
+| 密码登录失败 | 等待尝试写审计；失败有日志，请求仍拒绝登录，属于尽力记录 |
+| get / list / related 的潜在敏感明文 | 具备相应 unmask 能力时先完成可靠审计再交付；失败拒绝结果 |
+| 自定义 query | 按 reads 保守审计潜在敏感明文；声明 audit.purpose 时另外可靠记录目的；任一可靠审计失败均拒绝交付 |
+| 导出生成、下载 | 可靠审计；下载还复核当前权限与访问指纹；失败不交付文件 |
+| 导入任务及成功行 | 任务提交与目标命令按各自事务审计；异步逐行/原子方式见任务协议 |
+| 普通掩码读取、诊断元数据 | 默认无统一专门审计 |
+
+成功登录、step-up 和退出目前没有统一专门审计。审计保证按入口区分，不能把“有审计”理解为每一种请求都可靠留痕。可靠读取失败使用 `CAGE-AUDIT-001`，凭 requestId 定位数据库与权限故障；默认日志只保留允许的执行元数据，错误文本、原始 payload 与外部响应不进入默认结构化日志。
+
 ## 数据库连接属于框架核心能力
 
 项目提供连接配置，框架管理连接池、事务、上下文变量和 SQL。普通业务不需要自己编写 `pg.Pool`、表仓储或连接释放逻辑。
@@ -103,6 +128,7 @@ APP、READ、MIGRATE 指向**同一个已经存在的数据库**，用不同账
 | `init` | 角色、schema、授权、随机凭证及 `.env` | 安装 PG、启动 Docker、创建数据库、创建业务表 |
 | `gen` | 本地 contracts、SQL、状态图、迁移草稿 | 应用数据库迁移 |
 | `migrate` | 已有库的表、索引、安全视图、迁移历史 | 每次启动新建数据库 |
+| `bootstrap` | 显式初始化组织，将初始凭据交付到新的受限文件 | 自动授予业务能力、日常启动时重置密码 |
 | `dev` | 连接已有库，启动 API、worker、Web，监听声明重新生成 | 自动迁移或内嵌临时数据库兜底 |
 
 读路径使用 `safe.*`，业务表位于 `core.*`，组织和运行数据位于 `sys.*`。安全视图结合会话上下文执行范围过滤与掩码；手写报表也必须走这层。连接现有库不意味着自动把历史任意表变成 Cage 聚合，需要专门的映射与迁移方案。