@clawos-dev/clawd 0.2.142-beta.298.934a65b → 0.2.143-beta.300.c2a3792

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/main.ts

@@ -0,0 +1,116 @@
+import './polyfill';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { AppModule } from './app.module';
+import * as path from 'node:path';
+import cookieParser from 'cookie-parser';
+import { authGate, loginHandler, callbackHandler } from './auth/gate';
+
+// app-builder build 模式（spec 2026-06-01 + 2026-06-02 §5.6.4 子路径 fix）：
+//   - dev（通过 clawd 启）：nest 单进程 mount vite middleware，前端 HMR + /api 都从
+//     CLAWD_PREVIEW_PORT 出。所有 URL 走子路径 `/preview/<port>/`，含两层 prefix 处理：
+//       1. vite createServer 传 base=/preview/<port>/，让 vite middleware 识别带前缀的
+//          请求并剥前缀做内部路由 + HTML transform 时给 asset URL 加前缀
+//       2. nest setGlobalPrefix=preview/<port>/api，让 /preview/<port>/api/* 也被 nest 路由匹配
+//     不这样配，daemon preview-proxy 反代过来的请求（含 /preview/<port>/ 前缀）会被 nest 和 vite
+//     都不识别 → 全 404 / 'spa' 兜底返 HTML（API 接不通）
+//   - prod / 脱离 clawd：nest 起来时 express.static serve web/dist，base=/ globalPrefix=api
+//
+// CLAWD_PREVIEW_PORT 由 daemon supervisor 启动时注入；FC_SERVER_PORT / PORT 是 FC 部署 / 本地脱离 clawd 调试的回退。
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+
+  const isDev = process.env.NODE_ENV !== 'production';
+  const isClawdDev = !!process.env.CLAWD_PREVIEW_PORT;
+  const port =
+    Number(process.env.CLAWD_PREVIEW_PORT) ||
+    Number(process.env.FC_SERVER_PORT) ||
+    Number(process.env.PORT) ||
+    3000;
+
+  // 子路径 prefix：clawd dev 模式下挂 /preview/<port>/，其它（prod / 本地 vite 独跑）走根路径。
+  const subPath = isClawdDev ? `preview/${port}` : '';
+  const apiPrefix = subPath ? `${subPath}/api` : 'api';
+  const viteBase = subPath ? `/${subPath}/` : '/';
+
+  app.setGlobalPrefix(apiPrefix, { exclude: ['/'] });
+
+  // TTC 飞书登录门禁（PR-6）。前端 HTML 由 vite middleware(dev) / express.static(prod) serve、
+  // 不走 Nest 路由，Nest guard 拦不住，所以门禁是 Express 中间件，必须挂在下方 vite middleware
+  // (约:75) / useStaticAssets(约:99) 之前。/api/* 也先经过它（gate 在 vite 守卫和 nest router 之前）。
+  // /auth/login、/auth/callback 直接在 express 层注册，不带 globalPrefix；子路径部署带同样前缀。
+  // fail-loud：门禁启用却没配 SESSION_SECRET，会用空密钥签 cookie（可被伪造）—— 直接拒启动。
+  if (process.env.DATACLAW_AUTH_DISABLED !== '1' && !process.env.SESSION_SECRET) {
+    throw new Error('[auth] 缺 SESSION_SECRET：登录门禁启用时必填（否则 session cookie 可被伪造）。本地调试可设 DATACLAW_AUTH_DISABLED=1 跳过门禁。');
+  }
+  app.use(cookieParser());
+  const httpAdapter = app.getHttpAdapter();
+  const authBasePath = subPath ? `/${subPath}` : '';
+  httpAdapter.get(`${authBasePath}/auth/login`, loginHandler);
+  httpAdapter.get(`${authBasePath}/auth/callback`, callbackHandler);
+  app.use(authGate);
+
+  if (isDev && isClawdDev) {
+    // dev 模式 + 通过 clawd 启的 → mount vite middleware，root=../../web
+    const { createServer: createViteServer } = await import('vite');
+    const viteRoot = path.resolve(__dirname, '..', '..', 'web');
+    // vite 6+ 默认 server.allowedHosts: []（只放 localhost / .localhost / IP）防 DNS rebinding。
+    // frpc tunnel 转发过来的 Host header 是 daemon 当前 subdomain（CLAWD_TUNNEL_HOST 由
+    // daemon supervisor 注入），不在白名单 → vite middleware 直接拒（老板 tunnel URL 404 根因）。
+    // 显式把它加进 allowedHosts。
+    const tunnelHost = process.env.CLAWD_TUNNEL_HOST || '';
+    const allowedHosts = ['localhost', '127.0.0.1', ...(tunnelHost ? [tunnelHost] : [])];
+    const vite = await createViteServer({
+      root: viteRoot,
+      // **显式 inline base**：不依赖 web/vite.config.js 解析路径（middleware mode + ESM 配置
+      // 文件解析有时不可靠）。vite 据此识别带前缀的请求 + transformIndexHtml 注入带前缀的 asset URL。
+      base: viteBase,
+      server: {
+        middlewareMode: true,
+        // HMR WS 复用 nest 的 http.Server —— 跟 HTTP 共享同一个 fd / 同一个端口。
+        // 不设这个 vite 会 fallback standalone 用 24678，多 project 并发会撞。
+        hmr: { server: app.getHttpServer() },
+        allowedHosts,
+      },
+      // appType: 'spa' 让 vite middleware 自己 serve index.html + fallback 路由（base 下任何
+      // 非 vite asset 路径都返 index.html）。
+      appType: 'spa',
+    });
+    // /api/* 守卫：实测 vite 'spa' catch-all 会先吃掉 /api/* 返 HTML，导致 API 拿不到 JSON。
+    // Express middleware 栈顺序：vite.middlewares 这一行加进去时 nest controllers 还没挂
+    // （nest router init 在 app.listen 时），所以 vite 拦截优先于 nest router → 命中 /api 也走 vite。
+    // 守卫：req.url 命中 apiPrefix 时直接 next() 跳过 vite，让 nest router 接管返 JSON。
+    const apiPathPrefix = `/${apiPrefix}/`; // 如 '/preview/6173/api/' 或 '/api/'
+    app.use((req: any, res: any, next: any) => {
+      if (typeof req.url === 'string' && req.url.startsWith(apiPathPrefix)) {
+        return next(); // skip vite，让 nest router 处理 /api/*
+      }
+      return vite.middlewares(req, res, next);
+    });
+    console.log(`[clawd-dev] vite middleware mounted (root=${viteRoot}, base=${viteBase}, apiPrefix=${apiPrefix}, allowedHosts=${allowedHosts.join(',')})`);
+  } else {
+    // prod / 脱离 clawd 跑：直接 serve 前端静态资源。
+    //
+    // 路径解析两条路（覆盖 FC 部署与本地 monorepo 启动两种场景）：
+    //   1. FC（CODE_DIR=./server 只上传 server/，运行时 __dirname=dist/）
+    //      publish.sh BUILD_CMD 末尾会跑 `mkdir -p dist/public && cp -R ../web/dist/. dist/public/`
+    //      把前端打包产物塞进 dist/public，跟着 server 一起上传到 FC。所以 prod 优先用
+    //      __dirname/public 这条 FC 内可达的绝对路径。
+    //   2. 本地 monorepo `node dist/main.js`（极少用，但保留兼容）：__dirname/public 不存在
+    //      时 fallback 到 ../../web/dist（monorepo 相对路径）。
+    //
+    // 历史坑：spec 2026-06-03 前只有路径 2，FC 上 404 整个前端 —— 因为 ../../web/dist 在 FC
+    // 容器里压根不存在（CODE_DIR 只上传了 server/）。dev 时靠 vite middleware 走内存编译没暴露。
+    const fs = await import('node:fs');
+    const fcStaticDir = path.resolve(__dirname, 'public');
+    const monorepoStaticDir = path.resolve(__dirname, '..', '..', 'web', 'dist');
+    const staticDir = fs.existsSync(fcStaticDir) ? fcStaticDir : monorepoStaticDir;
+    app.useStaticAssets(staticDir);
+    console.log(`[prod] serving static from ${staticDir}`);
+  }
+
+  await app.listen(port, '0.0.0.0');
+  console.log(`server listening on :${port} (${isDev ? 'dev' : 'prod'}${isClawdDev ? ' / clawd' : ''})`);
+}
+
+bootstrap();

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/polyfill.ts

@@ -0,0 +1,6 @@
+// Dev 模式 .env loader：`nest start --watch` 不会经过 `node --env-file=.env`，
+// server 拿不到 DATACLAW_* env → loadDataclawConfig 会 fail-loud。
+// 这里在 nest bootstrap 之前显式 require dotenv 把 .env 填进 process.env。
+// prod 路径（node --env-file=.env dist/main.js）Node 自带 loader 已经填了，dotenv 看到
+// 已存在的 env 不会覆盖（默认行为），行为对齐。
+require('dotenv/config');

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2021",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "declaration": false
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "guestbook-web",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.4.0",
+    "vite": "^6.0.0"
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/App.jsx

@@ -0,0 +1,9 @@
+import { useAuthGate } from './auth';
+import PerformanceQueryPage from './pages/PerformanceQueryPage';
+
+export default function App() {
+  const { ready, authed } = useAuthGate();
+  if (!ready) return <div>加载中…</div>;
+  if (!authed) return <div>请先飞书登录</div>;
+  return <PerformanceQueryPage />;
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/api.js

@@ -0,0 +1,19 @@
+// 只调 app 自己的 BFF（/api/*），绝不直连 dataclaw —— 密钥/身份都在 server 侧注入，不进浏览器。
+//
+// dev 隧道模式下页面挂在子路径 /preview/<port>/ 下（见 vite.config.js base），
+// 所以 API_BASE 要拼上 import.meta.env.BASE_URL，否则 fetch 会打到错误的绝对路径。
+const API_BASE = (import.meta.env.BASE_URL || '/').replace(/\/+$/, '') + '/api';
+
+async function req(path, opts = {}) {
+  const res = await fetch(API_BASE + path, {
+    headers: { 'Content-Type': 'application/json' },
+    ...opts,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || json.ok === false) throw new Error(json.error || `请求失败 ${res.status}`);
+  return json;
+}
+
+export const getSchema = (dataset) => req(`/schema?dataset=${encodeURIComponent(dataset || '')}`);
+export const runQuery = (body) => req('/query', { method: 'POST', body: JSON.stringify(body) });
+export const searchConsultants = (kw) => req(`/consultants?keyword=${encodeURIComponent(kw)}`);

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/auth.js

@@ -0,0 +1,7 @@
+import { useEffect, useState } from 'react';
+// 门禁 hook 占位：真实飞书登录态检测在 PR-6。返回 { ready, authed }。
+export function useAuthGate() {
+  const [state, setState] = useState({ ready: false, authed: false });
+  useEffect(() => { setState({ ready: true, authed: true }); }, []); // 占位：默认已登录
+  return state;
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/components/BarChart.jsx

@@ -0,0 +1,38 @@
+// 纯 SVG 横向柱状图，不引第三方依赖。props { rows, labelField, valueField }。
+export default function BarChart({ rows, labelField, valueField }) {
+  if (!rows || rows.length === 0) return null;
+
+  const data = rows.map((r) => ({
+    label: String(r[labelField] ?? ''),
+    value: Number(r[valueField]) || 0,
+  }));
+  const max = Math.max(...data.map((d) => d.value), 0) || 1;
+
+  const rowH = 24;
+  const gap = 8;
+  const labelW = 150;
+  const barAreaW = 360;
+  const valueW = 120;
+  const width = labelW + barAreaW + valueW;
+  const height = data.length * (rowH + gap) + gap;
+
+  return (
+    <svg width={width} height={height} role="img" aria-label="柱状图" style={{ maxWidth: '100%' }}>
+      {data.map((d, i) => {
+        const y = gap + i * (rowH + gap);
+        const w = Math.max(0, (d.value / max) * barAreaW);
+        return (
+          <g key={i}>
+            <text x={labelW - 8} y={y + rowH / 2} textAnchor="end" dominantBaseline="middle" fontSize="12" fill="#374151">
+              {d.label}
+            </text>
+            <rect x={labelW} y={y} width={w} height={rowH} rx="3" fill="#2563eb" />
+            <text x={labelW + w + 6} y={y + rowH / 2} dominantBaseline="middle" fontSize="12" fill="#1f2328">
+              {d.value.toLocaleString('zh-CN')}
+            </text>
+          </g>
+        );
+      })}
+    </svg>
+  );
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/components/FilterRow.jsx

@@ -0,0 +1,79 @@
+import { ENUM_HINTS } from '../enums';
+
+// 操作符中文标签（仅展示用，没命中就回退显示原始 code）。
+const OP_LABELS = {
+  eq: '等于', ne: '不等于', contains: '包含',
+  gt: '大于', gte: '大于等于', lt: '小于', lte: '小于等于',
+  between: '区间', in: '属于', notin: '不属于',
+};
+
+// 单条筛选。受控：props { field（来自 /api/schema 的字段元数据）, value:{field,op,value}, onChange, onRemove }。
+// 控件选择规则：
+//   - op === 'between'        → 两个输入框
+//   - op === 'in' / 'notin'   → 单输入框，逗号分隔（值为数组）
+//   - ENUM_HINTS 命中该字段   → 下拉，选项来自 ENUM_HINTS[sourceField]
+//   - 否则按 field.type        → string=text / number=number / date=date
+// 操作符下拉选项直接来自 field.operators。
+export default function FilterRow({ field, value, onChange, onRemove }) {
+  const type = field.type || 'string';
+  const enumValues = ENUM_HINTS[field.sourceField];
+  const ops = field.operators && field.operators.length ? field.operators : [value.op].filter(Boolean);
+  const inputType = type === 'number' ? 'number' : type === 'date' ? 'date' : 'text';
+  const label = (field.aliases && field.aliases[0]) || field.sourceField;
+
+  const coerce = (raw) => (type === 'number' && raw !== '' ? Number(raw) : raw);
+  const set = (patch) => onChange({ ...value, ...patch });
+
+  // 切操作符时 value 形态可能要换（标量 / 二元区间 / 数组），统一重置避免形态错配。
+  const onOpChange = (e) => {
+    const op = e.target.value;
+    const next = op === 'between' ? ['', ''] : op === 'in' || op === 'notin' ? [] : '';
+    set({ op, value: next });
+  };
+
+  const renderValueControl = () => {
+    if (value.op === 'between') {
+      const v = Array.isArray(value.value) ? value.value : ['', ''];
+      return (
+        <span className="filter-between">
+          <input type={inputType} value={v[0] ?? ''} onChange={(e) => set({ value: [coerce(e.target.value), v[1] ?? ''] })} />
+          <span className="sep">~</span>
+          <input type={inputType} value={v[1] ?? ''} onChange={(e) => set({ value: [v[0] ?? '', coerce(e.target.value)] })} />
+        </span>
+      );
+    }
+    if (value.op === 'in' || value.op === 'notin') {
+      const text = Array.isArray(value.value) ? value.value.join(',') : value.value ?? '';
+      return (
+        <input
+          className="filter-value"
+          placeholder="多个值用逗号分隔"
+          value={text}
+          onChange={(e) => set({ value: e.target.value.split(',').map((s) => coerce(s.trim())).filter((s) => s !== '') })}
+        />
+      );
+    }
+    if (enumValues) {
+      return (
+        <select className="filter-value" value={value.value ?? ''} onChange={(e) => set({ value: e.target.value })}>
+          <option value="">请选择</option>
+          {enumValues.map((opt) => <option key={opt} value={opt}>{opt}</option>)}
+        </select>
+      );
+    }
+    return (
+      <input className="filter-value" type={inputType} value={value.value ?? ''} onChange={(e) => set({ value: coerce(e.target.value) })} />
+    );
+  };
+
+  return (
+    <div className="filter-row">
+      <span className="filter-label">{label}</span>
+      <select className="filter-op" value={value.op} onChange={onOpChange}>
+        {ops.map((op) => <option key={op} value={op}>{OP_LABELS[op] || op}</option>)}
+      </select>
+      {renderValueControl()}
+      <button type="button" className="filter-remove" onClick={onRemove}>删除</button>
+    </div>
+  );
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/components/ResultCards.jsx

@@ -0,0 +1,17 @@
+// 结果卡片。props { rows, titleField, valueField }。数字按 zh-CN 千分位展示。
+export default function ResultCards({ rows, titleField, valueField }) {
+  if (!rows || rows.length === 0) return <div className="empty">无数据</div>;
+  return (
+    <div className="cards">
+      {rows.map((r, i) => {
+        const v = r[valueField];
+        return (
+          <div className="card" key={i}>
+            <div className="card-title">{String(r[titleField] ?? '')}</div>
+            <div className="card-value">{typeof v === 'number' ? v.toLocaleString('zh-CN') : String(v ?? '')}</div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/components/ResultTable.jsx

@@ -0,0 +1,21 @@
+// 结果表格。列取 rows[0] 的 key，数字按 zh-CN 千分位展示，空数组显示「无数据」。
+export default function ResultTable({ rows }) {
+  if (!rows || rows.length === 0) return <div className="empty">无数据</div>;
+  const cols = Object.keys(rows[0]);
+  return (
+    <table className="result-table">
+      <thead>
+        <tr>{cols.map((c) => <th key={c}>{c}</th>)}</tr>
+      </thead>
+      <tbody>
+        {rows.map((r, i) => (
+          <tr key={i}>
+            {cols.map((c) => (
+              <td key={c}>{typeof r[c] === 'number' ? r[c].toLocaleString('zh-CN') : String(r[c] ?? '')}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/components/SchemaFilters.jsx

@@ -0,0 +1,93 @@
+import { useEffect, useState } from 'react';
+import { getSchema } from '../api';
+import { INTERNAL_FIELDS, ENUM_HINTS, TYPE_DEFAULT_OP } from '../enums';
+import FilterRow from './FilterRow';
+
+// 给 schema 没覆盖到的字段（如预置的 Billing日期）按字段名兜底猜类型。
+function guessType(sourceField) {
+  if (/日期|时间|date|time/i.test(sourceField)) return 'date';
+  return 'string';
+}
+
+const FALLBACK_OPS = {
+  string: ['contains', 'eq', 'ne', 'in', 'notin'],
+  number: ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'between', 'in', 'notin'],
+  date: ['eq', 'gt', 'gte', 'lt', 'lte', 'between'],
+};
+
+function initValue(op) {
+  if (op === 'between') return ['', ''];
+  if (op === 'in' || op === 'notin') return [];
+  return '';
+}
+
+// 受控筛选区。拉 /api/schema 拿字段元数据，过滤掉 INTERNAL_FIELDS，
+// 渲染已选 filters（FilterRow）+ 「+ 添加筛选字段」下拉。
+// props { dataset, filters, onChange }。
+export default function SchemaFilters({ dataset, filters, onChange }) {
+  const [fields, setFields] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    let alive = true;
+    setLoading(true);
+    setError('');
+    getSchema(dataset)
+      .then((json) => {
+        if (!alive) return;
+        const data = json.data;
+        // 传了 dataset 时 data 可能是单对象；否则是数组。
+        const entry = Array.isArray(data) ? data.find((d) => d.dataset === dataset) : data;
+        const fs = (entry?.fields || []).filter((f) => !INTERNAL_FIELDS.has(f.sourceField));
+        setFields(fs);
+      })
+      .catch((e) => { if (alive) setError(e.message || '加载 schema 失败'); })
+      .finally(() => { if (alive) setLoading(false); });
+    return () => { alive = false; };
+  }, [dataset]);
+
+  // 取字段元数据：schema 里找得到用真的，找不到（预置 filter / 未加载）给兜底。
+  const metaFor = (sourceField) => {
+    const found = fields.find((f) => f.sourceField === sourceField);
+    if (found) return found;
+    const type = ENUM_HINTS[sourceField] ? 'string' : guessType(sourceField);
+    return { sourceField, type, operators: FALLBACK_OPS[type], aliases: [] };
+  };
+
+  const update = (i, next) => onChange(filters.map((f, idx) => (idx === i ? next : f)));
+  const remove = (i) => onChange(filters.filter((_, idx) => idx !== i));
+  const add = (e) => {
+    const sourceField = e.target.value;
+    e.target.value = '';
+    if (!sourceField) return;
+    const meta = metaFor(sourceField);
+    const wanted = TYPE_DEFAULT_OP[meta.type];
+    const op = wanted && meta.operators?.includes(wanted) ? wanted : meta.operators?.[0] || 'eq';
+    onChange([...filters, { field: sourceField, op, value: initValue(op) }]);
+  };
+
+  if (error) return <div className="error">筛选项加载失败：{error}</div>;
+
+  return (
+    <div className="schema-filters">
+      {filters.map((f, i) => (
+        <FilterRow
+          key={i}
+          field={metaFor(f.field)}
+          value={f}
+          onChange={(next) => update(i, next)}
+          onRemove={() => remove(i)}
+        />
+      ))}
+      <select className="filter-add" value="" onChange={add} disabled={loading}>
+        <option value="">{loading ? '加载字段中…' : '+ 添加筛选字段'}</option>
+        {fields.map((f) => (
+          <option key={f.sourceField} value={f.sourceField}>
+            {(f.aliases && f.aliases[0]) || f.sourceField}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/enums.js

@@ -0,0 +1,22 @@
+// 枚举可选值 / 内部字段 —— 逐字对齐后端 query-filters.js。
+//
+// 为什么前端要自带这份常量：
+//   - /api/schema 只给 field.type / field.operators / aliases，**不给枚举候选值**，
+//     所以状态类字段的下拉选项只能在前端硬编码（ENUM_HINTS）。
+//   - describeDatasets 仍会返回 ID / 各级编号 等内部字段，前端要主动过滤掉不渲染
+//     （INTERNAL_FIELDS）。
+// 后端 query-filters.js 改了这里也要同步改。
+
+export const ENUM_HINTS = {
+  候选人状态: ['推荐', '1面', '2面', '3面', '4面', '终面', 'Offer', '已入职', '淘汰'],
+  顾问类型: ['正式', '实习', '外部合作顾问', '兼职', '外包', '虚拟账号'],
+  顾问在职状态: ['在职', '离职'],
+};
+
+export const INTERNAL_FIELDS = new Set([
+  'ID', 'unique_id', '链接', 'SourceID', '发票ID', '客户ID', '职位ID',
+  '业绩所属一级团队编号', '业绩所属二级团队编号', '业绩所属三级团队编号', '所属OP名称', '候选人ID',
+]);
+
+// 每种字段类型添加筛选时的默认操作符。
+export const TYPE_DEFAULT_OP = { string: 'contains', number: 'eq', date: 'eq' };

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/main.jsx

@@ -0,0 +1,6 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+import './styles.css';
+
+createRoot(document.getElementById('root')).render(<App />);

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/pages/PerformanceQueryPage.jsx

@@ -0,0 +1,102 @@
+import { useState } from 'react';
+import { runQuery } from '../api';
+import SchemaFilters from '../components/SchemaFilters';
+import ResultTable from '../components/ResultTable';
+import BarChart from '../components/BarChart';
+
+// 数据集：起手页用 performance。agent 按用户需求改成
+// performance / consultant_progress / metadata_user 之一即可。
+// 数据范围（scope）不在前端选 —— 后端按建页人身份隐式裁剪。
+const DATASET = 'performance';
+
+// 聚合字段用真名。注意：`业绩所属二级团队` 是真实字段名，
+// 「顾问所属N级团队」只是它的 alias，查询 groupBy / aggregations 必须用真名。
+const GROUP_FIELD = '业绩所属二级团队';
+const METRIC = '业绩';
+
+// 预置一个 Billing 日期区间示例。
+// 提示：PPL 大范围查询很慢，务必带状态/时间区间（如 Billing 日期 between）收敛扫描范围。
+const INITIAL_FILTERS = [
+  { field: 'Billing日期', op: 'between', value: ['2026-01-01', '2026-06-30'] },
+];
+
+// 结果列名由后端决定（聚合后可能不叫原名），这里挑出展示用的标签列 / 数值列，兜底防错配。
+function pickFields(rows, preferredLabel, preferredValue) {
+  const cols = Object.keys(rows[0]);
+  const labelField = cols.includes(preferredLabel)
+    ? preferredLabel
+    : cols.find((c) => typeof rows[0][c] !== 'number') || cols[0];
+  const valueField = cols.includes(preferredValue)
+    ? preferredValue
+    : cols.find((c) => typeof rows[0][c] === 'number' && c !== labelField) || cols[cols.length - 1];
+  return { labelField, valueField };
+}
+
+export default function PerformanceQueryPage() {
+  const [filters, setFilters] = useState(INITIAL_FILTERS);
+  const [groupBy, setGroupBy] = useState(GROUP_FIELD);
+  const [rows, setRows] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [ran, setRan] = useState(false);
+
+  const onQuery = async () => {
+    setLoading(true);
+    setError('');
+    try {
+      const json = await runQuery({
+        dataset: DATASET,
+        filters,
+        groupBy,
+        aggregations: [{ field: METRIC, op: 'sum' }],
+        orderBy: { field: METRIC, direction: 'desc' },
+        limit: 50,
+      });
+      setRows(json.data?.rows || []);
+      setTotal(json.data?.total || 0);
+      setRan(true);
+    } catch (e) {
+      setError(e.message || '查询失败');
+      setRows([]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const picked = rows.length ? pickFields(rows, groupBy, METRIC) : null;
+
+  return (
+    <div className="page">
+      <h1>业绩查询（示例）</h1>
+      <p className="hint">数据集：{DATASET}。数据范围由后端按你的身份自动裁剪。</p>
+
+      <section className="panel">
+        <label className="group-by">
+          分组字段
+          <input value={groupBy} onChange={(e) => setGroupBy(e.target.value)} />
+        </label>
+        <SchemaFilters dataset={DATASET} filters={filters} onChange={setFilters} />
+        <button type="button" className="btn-primary" onClick={onQuery} disabled={loading}>
+          {loading ? '查询中…' : '查询'}
+        </button>
+      </section>
+
+      {error && <div className="error">{error}</div>}
+
+      {ran && !error && (
+        <section className="results">
+          <div className="results-head">
+            共 {total.toLocaleString('zh-CN')} 条，按 {METRIC} 汇总（Top {rows.length}）
+          </div>
+          {picked && rows.length > 0 && (
+            <div className="chart-wrap">
+              <BarChart rows={rows} labelField={picked.labelField} valueField={picked.valueField} />
+            </div>
+          )}
+          <ResultTable rows={rows} />
+        </section>
+      )}
+    </div>
+  );
+}