@yss123/cage-cli 0.2.0 → 0.3.1

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,13 +6,36 @@
   "graph": {
     "title": "采购业务图谱",
     "labels": {
+      "module:purchase": "采购管理",
+      "module:inventory": "库存管理",
       "aggregate:PurchaseOrder": "采购单",
+      "aggregate:ApprovalMember": "采购审批协作名录",
       "aggregate:Inventory": "库存台账",
       "aggregate:InventoryLock": "库存锁",
       "aggregate:Dept": "部门",
       "aggregate:User": "用户",
       "aggregate:Role": "角色",
       "command:PurchaseOrder.create": "新建采购单",
+      "command:PurchaseOrder.explainPurpose": "补充采购用途",
+      "command:PurchaseOrder.setReviewers": "设置专业复核人员",
+      "command:PurchaseOrder.returnForChanges": "退回修改",
+      "field:PurchaseOrder.reason": "采购用途",
+      "field:PurchaseOrder.needsSpecialistReview": "需要专业复核",
+      "field:PurchaseOrder.reviewerIds": "专业复核人员",
+      "command:ApprovalMember.create": "登记采购协作人",
+      "command:ApprovalMember.update": "修改协作人公开资料",
+      "command:ApprovalMember.retire": "退役采购协作人",
+      "field:ApprovalMember.userId": "协作账号",
+      "field:ApprovalMember.displayName": "公开业务姓名",
+      "field:ApprovalMember.specialty": "专业领域",
+      "state:ApprovalMember.active": "可选协作人",
+      "state:ApprovalMember.retired": "已退役协作人",
+      "capability:ApprovalMember.read": "查看采购协作名录",
+      "capability:ApprovalMember.export": "导出采购协作名录",
+      "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/db/migrations/0004_draft.sql

@@ -0,0 +1,27 @@
+-- 迁移草稿：由 cage gen 生成，人审后提交；已发布的迁移不要修改
+-- 破坏性变更按「先扩展再收缩」分多次发布
+
+-- 新表：来自聚合 ApprovalMember
+CREATE TABLE IF NOT EXISTS "core"."approval_member" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "tenant_id" uuid NOT NULL,
+  "user_id" uuid NOT NULL REFERENCES "sys"."user"(id),
+  "display_name" text NOT NULL,
+  "specialty" text NOT NULL,
+  "status" text NOT NULL,
+  "version" integer NOT NULL DEFAULT 1,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "approval_member_status_check" CHECK (status IN ('active', 'retired'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "approval_member_user_id_uq" ON "core"."approval_member" (tenant_id, "user_id");
+CREATE INDEX IF NOT EXISTS "approval_member_status_idx" ON "core"."approval_member" ("tenant_id", "status");
+CREATE INDEX IF NOT EXISTS "approval_member_user_id_idx" ON "core"."approval_member" ("user_id");
+
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "needs_specialist_review" boolean;
+
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "reviewer_ids" jsonb;
+
+/* cage:schema
+{"version":1,"tables":[{"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":"approval_member","aggregate":"ApprovalMember","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"user_id","type":"uuid","notNull":true,"references":"sys.user","unique":true},{"name":"display_name","type":"text","notNull":true},{"name":"specialty","type":"text","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","retired"],"indexes":[{"name":"approval_member_status_idx","columns":["tenant_id","status"]},{"name":"approval_member_user_id_idx","columns":["user_id"]}]},{"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":"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":"needs_specialist_review","type":"boolean","notNull":false},{"name":"reviewer_ids","type":"jsonb","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;
+    }
+}