@yss123/cage-cli 0.0.0-stage → 0.2.0

package/templates/blank/docs/examples/purchase-admin/apps/web/src/main.tsx

@@ -0,0 +1,13 @@
+// 唯一浏览器启动入口：挂载 React、全局 Provider 和样式；业务从 app 组合进入。
+import { createRoot } from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { App } from './app/app';
+import './app/styles/global.css';
+
+const queryClient = new QueryClient();
+
+createRoot(document.getElementById('root')!).render(
+  <QueryClientProvider client={queryClient}>
+    <App />
+  </QueryClientProvider>,
+);

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/approval/hooks/use-approval-tasks.ts

@@ -0,0 +1,20 @@
+import { useQuery } from '@tanstack/react-query';
+import { client } from '@app/contracts';
+import { errorMessage } from '../../../shared/lib/error-message';
+
+type Task = { id: string; businessKey: string; title: string; createdAt: string };
+
+/**
+ * 审批是框架通用接口，不属于某个聚合的生成方法，因此请求封装在审批模块内。
+ * 待办页面和导航角标复用同一缓存键，调用方不需要了解接口地址或响应形状。
+ */
+export function useApprovalTasks() {
+  return useQuery({
+    queryKey: ['tasks'],
+    queryFn: async () => {
+      const result = await client.get<Task[]>('/api/approval/tasks');
+      if (!result.ok) throw new Error(errorMessage(result));
+      return result.data;
+    },
+  });
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/approval/index.ts

@@ -0,0 +1,2 @@
+export { ApprovalTasksPage } from './pages/approval-tasks-page';
+export { useApprovalTasks } from './hooks/use-approval-tasks';

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/approval/pages/approval-tasks-page.tsx

@@ -0,0 +1,54 @@
+// 审批待办独立成页；结论调用框架审批接口，领域约束仍在后端执行。
+import { client } from '@app/contracts';
+import { useCommand } from '../../../shared/hooks/use-command';
+import { Notice } from '../../../shared/ui/notice';
+import { PageHeading } from '../../../shared/ui/page-heading';
+import { useApprovalTasks } from '../hooks/use-approval-tasks';
+
+export function ApprovalTasksPage() {
+  const tasks = useApprovalTasks();
+  const { run, busy, message, clearMessage } = useCommand();
+  return (
+    <>
+      <PageHeading eyebrow="APPROVAL INBOX" title="审批待办" description="处理分配给你的审批任务。" />
+      {message && <Notice onClose={clearMessage}>{message}</Notice>}
+      <section className="panel">
+        <div className="section-head">
+          <h2>待你处理</h2>
+          <button onClick={() => void tasks.refetch()}>刷新</button>
+        </div>
+        {tasks.isError && <p className="error">{tasks.error.message}</p>}
+        {tasks.isPending && <p className="empty">正在读取待办…</p>}
+        {tasks.data?.map((task) => (
+          <div className="task" key={task.id}>
+            <div>
+              <h3>{task.title}</h3>
+              <p className="mono muted">PO-{task.businessKey.slice(0, 8).toUpperCase()}</p>
+            </div>
+            <div className="actions">
+              <button
+                disabled={busy}
+                onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/reject`), '已驳回')}
+              >
+                驳回
+              </button>
+              <button
+                disabled={busy}
+                className="primary"
+                onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/approve`), '已通过审批')}
+              >
+                通过审批
+              </button>
+            </div>
+          </div>
+        ))}
+        {tasks.data?.length === 0 && (
+          <div className="empty">
+            <h3>待办已清空</h3>
+            <p>新任务分配给你后会显示在这里。</p>
+          </div>
+        )}
+      </section>
+    </>
+  );
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/auth/index.ts

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

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/apps/web/src/modules/inventory/index.ts

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

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/index.ts

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

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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>
+  );
+}