Browse Source

feat: 优化海关 SQLite 查询并补充回归测试

ly 3 days ago
parent
commit
5c6930f9b1
63 changed files with 5203 additions and 295 deletions
  1. 6 0
      .env.example
  2. 15 7
      README.md
  3. 7 1
      agent.cordis.yml
  4. 3 0
      bff/dist/src/harness/runtime.js
  5. 0 0
      bff/dist/src/harness/runtime.js.map
  6. 20 4
      bff/dist/src/harness/tools/index.js
  7. 0 0
      bff/dist/src/harness/tools/index.js.map
  8. 4 0
      bff/dist/src/routes/chat.js
  9. 0 0
      bff/dist/src/routes/chat.js.map
  10. 0 0
      bff/dist/src/tools/client.js.map
  11. 52 0
      bff/dist/test/query-contract.test.js
  12. 0 0
      bff/dist/test/query-contract.test.js.map
  13. 3 0
      bff/src/harness/runtime.ts
  14. 20 4
      bff/src/harness/tools/index.ts
  15. 1 1
      bff/src/harness/types.ts
  16. 4 0
      bff/src/routes/chat.ts
  17. 11 1
      bff/src/tools/client.ts
  18. 49 0
      bff/test/query-contract.test.ts
  19. 125 0
      docs/07-大数据查询设计与实测.md
  20. 2073 0
      docs/08-统计表业务目录.json
  21. 62 0
      docs/09-扩展测试与界面回归.md
  22. 55 0
      docs/evidence/20261118/exact-index-requalification.json
  23. 39 0
      docs/evidence/20261118/focus-index-experiment.json
  24. 8 0
      docs/evidence/20261118/lineage-source-requalification.json
  25. 194 0
      docs/evidence/20261118/monthly-4m.json
  26. 57 0
      docs/evidence/20261118/pipeline-100k.json
  27. 172 0
      docs/evidence/20261118/raw-4m.json
  28. 732 0
      docs/evidence/20261118/zip-business-parity.json
  29. BIN
      docs/evidence/ui-regression-20261118/08-narrow-trace.jpg
  30. BIN
      docs/evidence/ui-regression-20261118/09-final-warning.jpg
  31. 88 0
      samples/ui_regression.csv
  32. 14 0
      samples/ui_regression.expected.json
  33. 203 0
      scripts/benchmark_queries.py
  34. 1 1
      scripts/e2e.mjs
  35. 64 0
      scripts/upgrade_query_storage.py
  36. 56 0
      scripts/verify_business_parity.py
  37. 3 3
      tools-service/tests/test_api.py
  38. 186 0
      tools-service/tests/test_large_query_design.py
  39. 1 1
      tools-service/tests/test_objects.py
  40. 1 1
      tools-service/tests/test_pipeline.py
  41. 197 0
      tools-service/tests/test_query_regressions.py
  42. 19 2
      tools-service/toolsvc/api.py
  43. 78 0
      tools-service/toolsvc/catalog.py
  44. 3 0
      tools-service/toolsvc/config.py
  45. 5 0
      tools-service/toolsvc/customs/engine/excel.py
  46. 45 0
      tools-service/toolsvc/customs/engine/query_summaries.py
  47. 12 12
      tools-service/toolsvc/customs/engine/reports.py
  48. 3 7
      tools-service/toolsvc/customs/engine/storage.py
  49. 14 7
      tools-service/toolsvc/customs/pipeline.py
  50. 31 29
      tools-service/toolsvc/objects.py
  51. 88 0
      tools-service/toolsvc/query_indexes.py
  52. 36 0
      tools-service/toolsvc/query_precision.py
  53. 246 205
      tools-service/toolsvc/readers.py
  54. 0 0
      web/dist/assets/index-BPwH3D6I.css
  55. 0 0
      web/dist/assets/index-DpV5XlOc.js
  56. 2 2
      web/dist/index.html
  57. 14 5
      web/src/App.tsx
  58. 2 0
      web/src/api/types.ts
  59. 5 0
      web/src/components/ChatMessageView.tsx
  60. 26 0
      web/src/components/WorkspaceCreateDialog.tsx
  61. 4 1
      web/src/pages/ChatPage.tsx
  62. 23 0
      web/src/styles/app.css
  63. 21 1
      web/test/render.test.tsx

+ 6 - 0
.env.example

@@ -44,3 +44,9 @@ CDA_MAX_UPLOAD_MB=512
 # CDA_HARNESS=embedded
 # 指定 Python 可执行文件(默认 python / python3)
 # CDA_PYTHON=C:\Python312\python.exe
+
+# SQLite 问数约束:普通读取和聚合共用;不影响离线业务报表公式
+CDA_QUERY_TIMEOUT_MS=5000
+CDA_QUERY_MAX_OFFSET=10000
+# 业务单元格文本预算,行级溯源与响应元数据另计
+CDA_QUERY_MAX_BYTES=1048576

+ 15 - 7
README.md

@@ -1,4 +1,4 @@
-# 海关问数 Agent(CustomesDataAgent)
+# 海关问数 Agent(CustomesDataAgent)
 
 海关电子元器件进出口数据的**问数平台**:把海关原始 CSV 处理成 16 张统计报表,再用一个"只用工具里的数字说话"的 Agent 回答业务问题。
 
@@ -77,7 +77,7 @@ CustomesDataAgent/
 │  ├─ src/verify/              #   输出核验层:数字抽取 + 台账反查 + 裁决
 │  ├─ src/routes/              #   工作区/文件/处理/会话/对话(SSE)/系统
 │  ├─ src/store/               #   sqlite:会话、消息、会话台账
-│  └─ test/                    #   65 项单元与接口测试
+│  └─ test/                    #   69 项单元与接口测试
 ├─ tools-service/              # Python 工具执行服务
 │  ├─ toolsvc/customs/         # ★ 可替换的数据处理模块(契约 + engine + rules/)
 │  ├─ toolsvc/objects.py       #   对象库、原始数据索引、行级血缘
@@ -85,8 +85,8 @@ CustomesDataAgent/
 │  ├─ toolsvc/calc.py          #   calculator(带输入溯源)
 │  ├─ toolsvc/readers.py       #   data_read(SQL 过滤/排序/聚合)
 │  ├─ toolsvc/api.py           #   HTTP 接口
-│  └─ tests/                   #   85 项单元与接口测试
-├─ web/                        # React 前端(27 项单测:格式化 + 组件渲染)
+│  └─ tests/                   #   272 项单元与接口测试
+├─ web/                        # React 前端(29 项单测:格式化 + 组件渲染)
 ├─ scripts/                    # start/stop/e2e/run_tests/样本数据生成
 ├─ deploy/                     # Dockerfile + docker-compose(单镜像一键部署)
 ├─ samples/                    # 可复现的测试数据集 + 预言机(expected.json)
@@ -112,9 +112,9 @@ CustomesDataAgent/
 
 | 测试组 | 数量 | 命令 |
 |---|---|---|
-| Python 引擎与接口(pytest) | 85 | `cd tools-service && python -m pytest tests/` |
-| BFF 单元与接口(node:test) | 65 | `cd bff && npm run build && node --test "dist/test/*.test.js"` |
-| 前端单元 + 渲染(vitest) | 27 | `cd web && npx vitest run` |
+| Python 引擎与接口(pytest) | 272 | `cd tools-service && python -m pytest tests/` |
+| BFF 单元与接口(node:test) | 69 | `cd bff && npm run build && node --test "dist/test/*.test.js"` |
+| 前端单元 + 渲染(vitest) | 29 | `cd web && npx vitest run` |
 | 端到端联调(真实服务 + 真实模型) | 33 项检查 | `node scripts/e2e.mjs` |
 | 真实浏览器交互(CDP 点击 + 截图) | 3 步断言 + 6 张截图 | `node scripts/ui_probe.mjs` |
 
@@ -150,3 +150,11 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_tests.ps1
   `CDA_LOCAL_BASE_URL`(llama.cpp / vLLM / Ollama 的 `/v1` 端点)即可,代码零改动。
 * Harness 默认使用内嵌实现(与 DeepSeek Harness 同语义、零外部进程、离线可用);
   装好 DSH CLI 后可设 `CDA_HARNESS=dsh` 转交给官方运行时,见 `bff/src/harness/dshAdapter.ts`。
+
+## 大数据查询补充(2026-11-18)
+
+在原23张Excel报表之外增加2张SQLite查询汇总表,补充业务表目录、定向联合索引、Decimal精确筛选与排序、受限聚合、按需计数、行号游标、查询时限、版本缓存和分批血缘。业务分类与统计公式保持不变。
+
+设计、口径差异、四百万行查询样本与十万唯一申报完整流程的实测范围,以及未验证项,见 [大数据查询设计与实测](docs/07-大数据查询设计与实测.md);机器可读目录见 [统计表业务目录](docs/08-统计表业务目录.json)。这些结果不能外推真实四百万行完整流水线性能。
+
+最新扩展回归与界面验证见 [docs/09-扩展测试与界面回归.md](docs/09-扩展测试与界面回归.md)。

+ 7 - 1
agent.cordis.yml

@@ -37,7 +37,7 @@ limits:
   # 单次 data_read 最多返回多少行(模型只看得到的部分)
   maxRowsPerRead: 50
   # 工具结果写进上下文前的字符上限
-  maxToolResultChars: 8000
+  maxToolResultChars: 24000
   # 单次对话最长时间(毫秒)
   timeoutMs: 300000
 
@@ -68,6 +68,12 @@ systemPrompt: |
   - 严禁用"其他月份"或"0"填补缺失值。表里为空就是空,你要如实说明"该月无记录/指数不可计算"。
   - 只读数据,不修改数据。你没有写文件、执行命令的能力,也不要假装有。
 
+  ## 大数据选表与查询
+  - 金额数量全量问答优先用“查询_叶子类目月度”或“查询_品牌型号月度”;前者不含品牌型号维度,后者覆盖所有纳入记录而非TopN。指数、占比、增长率仍从原模板对应口径取值。
+  - 聚合前调用 list_objects(object_id, table) 查看完整表目录,确认 row_grain、coverage、denominator、aggregation。禁止把父级合计与子级明细、全部范围与入选路径、不同港口粒度混加。
+  - 截断结果只是子集,不能把本页求和当全量。查询返回 total=null 表示未计数,不是零。需要全部匹配行数时显式 count_mode=exact;自然顺序深翻页使用 next_cursor,超时则缩小范围。
+  - 平均单价为总金额/总数量,成交数量须单位可比;占比、环比、年度样本加权指数不得简单求和或平均。
+
   ## 口径(回答时必须使用这些定义)
   - 金额单位:美元(不换汇、不缩放);数量:成交数量。
   - 三类指数以 2025 年 1 月为基期、基点 1000:价格指数按年度前 100 型号加权(单样本权重上限 10%),金额/数量指数用类目全部记录。

+ 3 - 0
bff/dist/src/harness/runtime.js

@@ -105,6 +105,7 @@ export class EmbeddedHarness {
                             log.warn(`写台账失败: ${error.message}`);
                         }
                     }
+                    const queryStatus = (outcome.content && typeof outcome.content === 'object' ? outcome.content : {});
                     yield {
                         type: 'tool_result',
                         callId: call.id,
@@ -114,6 +115,8 @@ export class EmbeddedHarness {
                         durationMs: outcome.durationMs,
                         objectIds: outcome.output.objectIds ?? [],
                         summary: summarize(outcome.content, outcome.error),
+                        truncated: queryStatus.truncated === true,
+                        warning: typeof queryStatus.warning === 'string' ? queryStatus.warning : undefined,
                     };
                     messages.push({
                         role: 'tool',

File diff suppressed because it is too large
+ 0 - 0
bff/dist/src/harness/runtime.js.map


+ 20 - 4
bff/dist/src/harness/tools/index.js

@@ -16,6 +16,8 @@ export function createCustomsTools(options) {
         parameters: {
             type: 'object',
             properties: {
+                object_id: { type: 'string', description: '可选:只查看该对象' },
+                table: { type: 'string', description: '可选:查看这张表的完整业务目录(粒度、口径、聚合限制);聚合前必须检查' },
                 kind: {
                     type: 'string',
                     enum: ['all', 'raw', 'stat'],
@@ -32,17 +34,21 @@ export function createCustomsTools(options) {
                 throw new Error('缺少工作区:请先在前端创建一个工作区');
             const kind = String(args.kind || 'all');
             const { items } = await client.listObjects(workspaceId, kind === 'all' ? undefined : kind);
-            const objects = items.map((item) => ({
+            const objects = items.filter(item => !args.object_id || item.id === args.object_id).map((item) => ({
                 object_id: item.id,
                 name: item.name,
                 kind: item.kind,
                 rows: item.rows,
                 created_at: item.created_at,
-                tables: item.tables.map((table) => ({
+                tables: item.tables.filter(table => !args.table || table.name === args.table).map((table) => ({
                     table: table.name,
                     rows: table.rows,
-                    columns: table.columns.slice(0, 40),
+                    columns: table.columns.slice(0, args.table ? 40 : 12),
                     column_count: table.columns.length,
+                    catalog: args.table ? table.catalog : table.catalog ? {
+                        subject: table.catalog.subject, row_grain: table.catalog.row_grain,
+                        preferred_for: table.catalog.preferred_for,
+                    } : undefined,
                 })),
             }));
             return {
@@ -150,7 +156,9 @@ export function createCustomsTools(options) {
                     },
                 },
                 limit: { type: 'integer', description: `返回行数,最多 ${maxRowsPerRead}`, minimum: 1, maximum: maxRowsPerRead },
-                offset: { type: 'integer', description: '分页偏移', minimum: 0 },
+                offset: { type: 'integer', description: '浅分页偏移,最多10000;深分页使用cursor', minimum: 0, maximum: 10000 },
+                cursor: { type: 'string', description: '上次返回的next_cursor;仅自然行号顺序,不可与排序/聚合/OFFSET混用' },
+                count_mode: { type: 'string', enum: ['auto', 'none', 'exact'], description: 'auto默认:无筛选读元数据行数;有筛选不做精确计数;需要时显式exact' },
                 aggregate: {
                     type: 'object',
                     description: '分组聚合模式:{group_by:[列], metrics:[{column,fn,alias}]},fn ∈ sum/avg/count/min/max',
@@ -173,6 +181,8 @@ export function createCustomsTools(options) {
                 order_by: Array.isArray(args.order_by) ? args.order_by : undefined,
                 limit,
                 offset: Number(args.offset ?? 0) || 0,
+                count_mode: args.count_mode,
+                cursor: args.cursor ? String(args.cursor) : undefined,
                 aggregate: args.aggregate ?? undefined,
                 call_id: context.callId,
                 session_id: context.sessionId,
@@ -201,6 +211,12 @@ export function createCustomsTools(options) {
                     table: result.table,
                     columns: result.columns,
                     total_matching_rows: result.total,
+                    total_exact: result.total_exact,
+                    truncated: result.truncated,
+                    truncation_reason: result.truncation_reason,
+                    next_cursor: result.next_cursor,
+                    warning: result.warning,
+                    cache_hit: result.cache_hit,
                     offset: result.offset,
                     limit: result.limit,
                     exhausted: result.exhausted,

File diff suppressed because it is too large
+ 0 - 0
bff/dist/src/harness/tools/index.js.map


+ 4 - 0
bff/dist/src/routes/chat.js

@@ -184,6 +184,8 @@ function forwardEvent(sse, event, collected) {
                 duration_ms: event.durationMs,
                 object_ids: event.objectIds,
                 summary: event.summary,
+                truncated: event.truncated,
+                warning: event.warning,
             });
             sse.send('tool_result', {
                 call_id: event.callId,
@@ -193,6 +195,8 @@ function forwardEvent(sse, event, collected) {
                 duration_ms: event.durationMs,
                 object_ids: event.objectIds,
                 summary: event.summary,
+                truncated: event.truncated,
+                warning: event.warning,
             });
             break;
         case 'step':

File diff suppressed because it is too large
+ 0 - 0
bff/dist/src/routes/chat.js.map


File diff suppressed because it is too large
+ 0 - 0
bff/dist/src/tools/client.js.map


+ 52 - 0
bff/dist/test/query-contract.test.js

@@ -0,0 +1,52 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCustomsTools } from '../src/harness/tools/index.js';
+import { ToolRegistry, defineTool } from '../src/harness/registry.js';
+import { EmbeddedHarness } from '../src/harness/runtime.js';
+import { ReplayLlmClient } from '../src/harness/llm.js';
+import { presetFromObject } from '../src/harness/preset.js';
+const context = { callId: 'contract_call', sessionId: 'contract_session', workspaceId: 'contract_workspace' };
+function fixture() {
+    const payloads = [];
+    const client = {
+        async listObjects() { return { items: [{ id: 'obj1', name: 'test', kind: 'stat', rows: 100, created_at: '2026-11-18', tables: [{ name: '查询_品牌型号月度', rows: 100, columns: ['品牌', '型号', '金额'], catalog: { subject: '品牌型号', row_grain: '方向×年月×品牌×型号', coverage: '全部纳入记录', aggregation: { non_additive: ['价格指数'] }, metric_definitions: { 金额: '严格Decimal总计' }, preferred_for: '全量金额数量' } }] }] }; },
+        async dataRead(payload) { payloads.push(payload); return { object_id: 'obj1', table: '查询_品牌型号月度', columns: ['金额'], rows: [{ values: { 金额: '0.3' }, _trace: { object_id: 'obj1', table: '查询_品牌型号月度', row_index: 0, row_hash: 'sha256:row' } }], total: null, total_exact: false, truncated: true, truncation_reason: 'row_limit', next_cursor: 'bound-cursor', warning: '仅返回受限子集,不能作为全量', cache_hit: true, offset: 0, limit: 50, exhausted: false }; },
+    };
+    return { tools: createCustomsTools({ client, maxRowsPerRead: 50, maxToolResultChars: 24000 }), payloads };
+}
+test('单表目录保留业务粒度、定义与不可加指标', async () => {
+    const { tools } = fixture();
+    const list = tools.find(t => t.name === 'list_objects');
+    const output = await list.execute({ object_id: 'obj1', table: '查询_品牌型号月度' }, context);
+    const content = output.content;
+    assert.equal(content.objects[0].tables[0].catalog.coverage, '全部纳入记录');
+    assert.deepEqual(content.objects[0].tables[0].catalog.aggregation.non_additive, ['价格指数']);
+});
+test('查询参数透传、limit受限,未计数不能伪装成零', async () => {
+    const { tools, payloads } = fixture();
+    const read = tools.find(t => t.name === 'data_read');
+    const output = await read.execute({ object_id: 'obj1', limit: 500, cursor: 'cursor_in', count_mode: 'none' }, context);
+    assert.equal(payloads[0].limit, 50);
+    assert.equal(payloads[0].cursor, 'cursor_in');
+    assert.equal(payloads[0].count_mode, 'none');
+    assert.equal(output.content.total_matching_rows, null);
+    assert.equal(output.content.total_exact, false);
+    assert.equal(output.content.truncated, true);
+    assert.equal(output.content.next_cursor, 'bound-cursor');
+    assert.equal(output.rows[0]._trace.row_hash, 'sha256:row');
+});
+test('截断状态和警告须进入流式工具结果,供界面直接显示', async () => {
+    const registry = new ToolRegistry();
+    registry.register(defineTool({ name: 'bounded', description: 'bounded', parameters: { type: 'object' }, async execute() { return { content: { truncated: true, warning: '只显示一页,不能视为全部' }, rows: [] }; } }));
+    const llm = new ReplayLlmClient([{ toolCalls: [{ name: 'bounded', arguments: {} }] }, { text: '这里只展示一页。' }]);
+    const resolve = () => ({ provider: { id: 'deepseek', displayName: 'test', baseUrl: 'http://unused', apiKey: 'test', api: 'openai-completions', models: ['deepseek-flash'], supportsTools: true }, model: 'deepseek-flash', temperature: 0.1, maxOutputTokens: 1000 });
+    const runtime = new EmbeddedHarness({ registry, llm, resolve });
+    const preset = presetFromObject({ name: 'bounded-test', model: { provider: 'deepseek', name: 'deepseek-flash' }, tools: ['bounded'], systemPrompt: 'test', limits: { maxSteps: 3 } });
+    const events = [];
+    for await (const event of runtime.run({ sessionId: 's', workspaceId: 'w', messages: [{ role: 'user', content: 'query' }], preset }))
+        events.push(event);
+    const event = events.find(e => e.type === 'tool_result');
+    assert.equal(event.truncated, true);
+    assert.equal(event.warning, '只显示一页,不能视为全部');
+});
+//# sourceMappingURL=query-contract.test.js.map

File diff suppressed because it is too large
+ 0 - 0
bff/dist/test/query-contract.test.js.map


+ 3 - 0
bff/src/harness/runtime.ts

@@ -135,6 +135,7 @@ export class EmbeddedHarness implements HarnessRuntime {
               log.warn(`写台账失败: ${(error as Error).message}`);
             }
           }
+          const queryStatus=(outcome.content && typeof outcome.content==='object' ? outcome.content : {}) as Record<string, unknown>;
           yield {
             type: 'tool_result',
             callId: call.id,
@@ -144,6 +145,8 @@ export class EmbeddedHarness implements HarnessRuntime {
             durationMs: outcome.durationMs,
             objectIds: outcome.output.objectIds ?? [],
             summary: summarize(outcome.content, outcome.error),
+            truncated: queryStatus.truncated === true,
+            warning: typeof queryStatus.warning === 'string' ? queryStatus.warning : undefined,
           };
           messages.push({
             role: 'tool',

+ 20 - 4
bff/src/harness/tools/index.ts

@@ -28,6 +28,8 @@ export function createCustomsTools(options: ToolFactoryOptions): ToolDefinition[
     parameters: {
       type: 'object',
       properties: {
+        object_id: { type: 'string', description: '可选:只查看该对象' },
+        table: { type: 'string', description: '可选:查看这张表的完整业务目录(粒度、口径、聚合限制);聚合前必须检查' },
         kind: {
           type: 'string',
           enum: ['all', 'raw', 'stat'],
@@ -43,17 +45,21 @@ export function createCustomsTools(options: ToolFactoryOptions): ToolDefinition[
       if (!workspaceId) throw new Error('缺少工作区:请先在前端创建一个工作区');
       const kind = String(args.kind || 'all');
       const { items } = await client.listObjects(workspaceId, kind === 'all' ? undefined : kind);
-      const objects = items.map((item) => ({
+      const objects = items.filter(item => !args.object_id || item.id === args.object_id).map((item) => ({
         object_id: item.id,
         name: item.name,
         kind: item.kind,
         rows: item.rows,
         created_at: item.created_at,
-        tables: item.tables.map((table) => ({
+        tables: item.tables.filter(table => !args.table || table.name === args.table).map((table) => ({
           table: table.name,
           rows: table.rows,
-          columns: table.columns.slice(0, 40),
+          columns: table.columns.slice(0, args.table ? 40 : 12),
           column_count: table.columns.length,
+          catalog: args.table ? table.catalog : table.catalog ? {
+            subject: table.catalog.subject, row_grain: table.catalog.row_grain,
+            preferred_for: table.catalog.preferred_for,
+          } : undefined,
         })),
       }));
       return {
@@ -164,7 +170,9 @@ export function createCustomsTools(options: ToolFactoryOptions): ToolDefinition[
           },
         },
         limit: { type: 'integer', description: `返回行数,最多 ${maxRowsPerRead}`, minimum: 1, maximum: maxRowsPerRead },
-        offset: { type: 'integer', description: '分页偏移', minimum: 0 },
+        offset: { type: 'integer', description: '浅分页偏移,最多10000;深分页使用cursor', minimum: 0, maximum:10000 },
+        cursor: {type:'string', description:'上次返回的next_cursor;仅自然行号顺序,不可与排序/聚合/OFFSET混用'},
+        count_mode: {type:'string', enum:['auto','none','exact'], description:'auto默认:无筛选读元数据行数;有筛选不做精确计数;需要时显式exact'},
         aggregate: {
           type: 'object',
           description: '分组聚合模式:{group_by:[列], metrics:[{column,fn,alias}]},fn ∈ sum/avg/count/min/max',
@@ -186,6 +194,8 @@ export function createCustomsTools(options: ToolFactoryOptions): ToolDefinition[
         order_by: Array.isArray(args.order_by) ? (args.order_by as any[]) : undefined,
         limit,
         offset: Number(args.offset ?? 0) || 0,
+        count_mode: args.count_mode as 'auto'|'none'|'exact'|undefined,
+        cursor: args.cursor ? String(args.cursor) : undefined,
         aggregate: (args.aggregate as Record<string, unknown>) ?? undefined,
         call_id: context.callId,
         session_id: context.sessionId,
@@ -217,6 +227,12 @@ export function createCustomsTools(options: ToolFactoryOptions): ToolDefinition[
           table: result.table,
           columns: result.columns,
           total_matching_rows: result.total,
+          total_exact: result.total_exact,
+          truncated: result.truncated,
+          truncation_reason: result.truncation_reason,
+          next_cursor: result.next_cursor,
+          warning: result.warning,
+          cache_hit: result.cache_hit,
           offset: result.offset,
           limit: result.limit,
           exhausted: result.exhausted,

+ 1 - 1
bff/src/harness/types.ts

@@ -94,7 +94,7 @@ export type HarnessEvent =
   | { type: 'token'; text: string }
   | { type: 'reasoning'; text: string }
   | { type: 'tool_call'; callId: string; tool: string; args: Record<string, unknown> }
-  | { type: 'tool_result'; callId: string; tool: string; ok: boolean; rows: number; durationMs: number; objectIds: string[]; summary: string }
+  | { type: 'tool_result'; callId: string; tool: string; ok: boolean; rows: number; durationMs: number; objectIds: string[]; summary: string; truncated?: boolean; warning?: string }
   | { type: 'step'; index: number; maxSteps: number }
   | { type: 'final'; text: string; steps: number; toolCalls: number; usage?: Record<string, number> }
   | { type: 'error'; message: string; code?: string };

+ 4 - 0
bff/src/routes/chat.ts

@@ -224,6 +224,8 @@ function forwardEvent(sse: SseStream, event: HarnessEvent, collected: RunCollect
         duration_ms: event.durationMs,
         object_ids: event.objectIds,
         summary: event.summary,
+        truncated: event.truncated,
+        warning: event.warning,
       });
       sse.send('tool_result', {
         call_id: event.callId,
@@ -233,6 +235,8 @@ function forwardEvent(sse: SseStream, event: HarnessEvent, collected: RunCollect
         duration_ms: event.durationMs,
         object_ids: event.objectIds,
         summary: event.summary,
+        truncated: event.truncated,
+        warning: event.warning,
       });
       break;
     case 'step':

+ 11 - 1
bff/src/tools/client.ts

@@ -24,6 +24,7 @@ export interface TableInfo {
   sqlite_name: string;
   rows: number;
   columns: string[];
+  catalog?: Record<string, any>;
 }
 
 export interface ObjectInfo {
@@ -67,6 +68,9 @@ export interface DataReadPayload {
   limit?: number;
   offset?: number;
   aggregate?: Record<string, unknown>;
+  count_mode?: 'auto' | 'none' | 'exact';
+  cursor?: string;
+  use_cache?: boolean;
   /** 由工具层传入,让 Python 台账用同一个 call_id 记录 */
   call_id?: string;
   session_id?: string;
@@ -276,7 +280,13 @@ export class ToolsClient {
     table: string;
     columns: string[];
     rows: Array<{ values: Record<string, unknown>; _trace: Record<string, unknown> }>;
-    total: number;
+    total: number | null;
+    total_exact?: boolean;
+    truncated?: boolean;
+    truncation_reason?: string;
+    next_cursor?: string | null;
+    warning?: string | null;
+    cache_hit?: boolean;
     offset: number;
     limit: number;
     exhausted: boolean;

+ 49 - 0
bff/test/query-contract.test.ts

@@ -0,0 +1,49 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCustomsTools } from '../src/harness/tools/index.js';
+import { ToolRegistry, defineTool } from '../src/harness/registry.js';
+import { EmbeddedHarness } from '../src/harness/runtime.js';
+import { ReplayLlmClient } from '../src/harness/llm.js';
+import { presetFromObject } from '../src/harness/preset.js';
+import type { ToolsClient } from '../src/tools/client.js';
+
+const context={callId:'contract_call',sessionId:'contract_session',workspaceId:'contract_workspace'};
+function fixture() {
+  const payloads: any[]=[];
+  const client={
+    async listObjects() {return {items:[{id:'obj1',name:'test',kind:'stat',rows:100,created_at:'2026-11-18',tables:[{name:'查询_品牌型号月度',rows:100,columns:['品牌','型号','金额'],catalog:{subject:'品牌型号',row_grain:'方向×年月×品牌×型号',coverage:'全部纳入记录',aggregation:{non_additive:['价格指数']},metric_definitions:{金额:'严格Decimal总计'},preferred_for:'全量金额数量'}}]}]};},
+    async dataRead(payload:any) {payloads.push(payload);return {object_id:'obj1',table:'查询_品牌型号月度',columns:['金额'],rows:[{values:{金额:'0.3'},_trace:{object_id:'obj1',table:'查询_品牌型号月度',row_index:0,row_hash:'sha256:row'}}],total:null,total_exact:false,truncated:true,truncation_reason:'row_limit',next_cursor:'bound-cursor',warning:'仅返回受限子集,不能作为全量',cache_hit:true,offset:0,limit:50,exhausted:false};},
+  } as unknown as ToolsClient;
+  return {tools:createCustomsTools({client,maxRowsPerRead:50,maxToolResultChars:24000}),payloads};
+}
+
+test('单表目录保留业务粒度、定义与不可加指标',async()=>{
+  const {tools}=fixture();const list=tools.find(t=>t.name==='list_objects')!;
+  const output=await list.execute({object_id:'obj1',table:'查询_品牌型号月度'},context);
+  const content=output.content as any;
+  assert.equal(content.objects[0].tables[0].catalog.coverage,'全部纳入记录');
+  assert.deepEqual(content.objects[0].tables[0].catalog.aggregation.non_additive,['价格指数']);
+});
+
+test('查询参数透传、limit受限,未计数不能伪装成零',async()=>{
+  const {tools,payloads}=fixture();const read=tools.find(t=>t.name==='data_read')!;
+  const output=await read.execute({object_id:'obj1',limit:500,cursor:'cursor_in',count_mode:'none'},context);
+  assert.equal(payloads[0].limit,50);assert.equal(payloads[0].cursor,'cursor_in');assert.equal(payloads[0].count_mode,'none');
+  assert.equal((output.content as any).total_matching_rows,null);
+  assert.equal((output.content as any).total_exact,false);
+  assert.equal((output.content as any).truncated,true);
+  assert.equal((output.content as any).next_cursor,'bound-cursor');
+  assert.equal(output.rows![0]._trace.row_hash,'sha256:row');
+});
+
+test('截断状态和警告须进入流式工具结果,供界面直接显示',async()=>{
+  const registry=new ToolRegistry();registry.register(defineTool({name:'bounded',description:'bounded',parameters:{type:'object'},async execute(){return {content:{truncated:true,warning:'只显示一页,不能视为全部'},rows:[]};}}));
+  const llm=new ReplayLlmClient([{toolCalls:[{name:'bounded',arguments:{}}]},{text:'这里只展示一页。'}]);
+  const resolve=()=>({provider:{id:'deepseek',displayName:'test',baseUrl:'http://unused',apiKey:'test',api:'openai-completions' as const,models:['deepseek-flash'],supportsTools:true},model:'deepseek-flash',temperature:0.1,maxOutputTokens:1000});
+  const runtime=new EmbeddedHarness({registry,llm,resolve});
+  const preset=presetFromObject({name:'bounded-test',model:{provider:'deepseek',name:'deepseek-flash'},tools:['bounded'],systemPrompt:'test',limits:{maxSteps:3}});
+  const events=[];
+  for await(const event of runtime.run({sessionId:'s',workspaceId:'w',messages:[{role:'user',content:'query'}],preset}))events.push(event);
+  const event=events.find(e=>e.type==='tool_result') as any;
+  assert.equal(event.truncated,true);assert.equal(event.warning,'只显示一页,不能视为全部');
+});

+ 125 - 0
docs/07-大数据查询设计与实测.md

@@ -0,0 +1,125 @@
+# 海关 Agent 大数据查询设计与实测
+
+交付日期:2026-11-18。先完善 SQLite,不在本轮更换引擎。本文分别标出已实现、实测和未验证事项。证据 JSON 位于 `docs/evidence/20261118/`,测试数据位于被 Git 忽略的 `.run/`。
+
+## 1. 业务口径与 ZIP 对比
+
+本轮未改 `rules.py`、`structure.py`、`brandmatch.py` 或三个规则工作簿。分类、ISO 周四归月、项目 HS 范围、年度选样前100、10%封顶再分配、指数基期2025-01=1000、占比分母、环比公式不变。
+
+- 原有16张模板表和7张辅助表保留在原 Excel/CSV;新增2张 **只在 SQLite 查询服务中提供** 的表,故对象目录有25张表,Excel仍为23张。它们是查询加速投影,不是替换原统计模板。
+- `查询_叶子类目月度`:方向×年月×c1/c2/c3/c4叶子路径。一行不含父级合计;不限定TopN或价格样本。
+- `查询_品牌型号月度`:上述维度再加品牌、型号。保留未识别空组,不要求存储器分类映射成功;全量金额数量查询不能拿“入选路径”代替它。
+- 两表金额数量使用 `dsum`/Decimal 严格求和,记录数求和,单价重新用合计金额÷合计数量。无记录不补零,任何成员缺数向上传播。成交数量不同单位是否可比较仍由业务口径决定,不能通过建表解决。
+- `price_basket` 从“收集全部候选并排序”改为流式有界前100堆,排序键仍为 `(-Decimal金额, 品牌, 型号)`,权重公式和选中集合不变。
+- 新增查询语义防护:禁止对单价、占比、环比、加权指数做 sum/avg;混合层级报表求和必须显式固定/分组目录列出的层级、范围和分母等分区。无法确认外部统计文件口径时拒绝自动求和。
+
+`verify_business_parity.py` 在同一批已纳入记录和同一套规则下运行 ZIP 的原报表实现,对比20张业务输出表。金额、数量、单价、指数、权重、占比、环比及节点集合一致;3张表有既有的**展示标签差异**:重点分析根节点及辅助表的 `父级路径` / `占比分母范围` 使用 `MLCC`/`DDR`,ZIP使用 `[]`。另有“供应链条件占比”仅行顺序变化,来自显式稳定排序。对比使用保留重复条数的行多重集,只归一上述两个根标签的已知别名;这些差异保留并在证据中逐项列出,未宣称逐字节一致。质量摘要、映射审计、日历3表不列入业务指标对比。
+
+必须另行披露的上一版本与 ZIP 的输入适配差异:
+
+| 项目 | 当前 Agent | ZIP | 影响 |
+|---|---|---|---|
+| 仅提供人民币金额列 | 拒绝冒充美元;同时有明确美元列时选美元列 | 可将人民币表头/货币文本归一后当作输入金额 | 是数值输入口径差异,不能当作自动换汇 |
+| 非法千分位/未知数值 | 严格判未知并传播 | 归一策略有不同的容错范围 | 个别异常记录可能导致不同的缺数结果 |
+| 年份范围 | 入库时按ISO周四归属年限制start/end | 旧入库只校验周号/截止日期,报表再限制输出年度 | 纳入/排除审计与新全量查询范围可能不同 |
+| 空 G_MODEL | 排除 | 排除 | 相同;非空但品牌型号缺失仍计入总量 |
+
+因此,当前对比证明**同一纳入集合的统计逻辑一致**,不宣称任意脏输入与ZIP逐条纳入完全一致,也不宣称解决真实约35%未识别问题。
+
+## 2. 表目录与 Agent 选表
+
+`toolsvc/catalog.py` 覆盖全部原表和2张查询汇总,提供:主题、一行代表什么、覆盖范围、层级、可筛选维度、指标定义、分母说明、可累加字段、不可加指标、聚合所需分区及版本绑定。运行实例还返回实际年月范围、截止日期、规则哈希、参数及HS范围。
+
+`list_objects` 普通调用返回简短主题/粒度;`list_objects(object_id, table)` 返回单表完整目录。提示词要求聚合前查看完整目录,服务端再次检查。全量金额数量优先查2张查询表;指数、占比、增长率取对应原模板;原始明细用于复核。目录字符预算提高到24000,仍建议先定位对象,再查看单表,避免让大量表结构挤占上下文。
+
+原始导入文件保留原文和行哈希;派生YEAR/WEEK数值列用于正确处理周号范围/排序(防止文本“10”排在“2”前),以及2025.0等数值格式。尤其“已遮掩”统计CSV不是海关原始明细,不能因名为 `raw` 原文表就把它当成互斥可汇总记录。
+
+## 3. 查询与索引设计
+
+索引统一由 `query_indexes.py` 创建,在批量写入完成后创建并执行 ANALYZE,不给每列各建一个索引。
+
+| 路径 | 联合索引/访问方式 | 对应问题 |
+|---|---|---|
+| 原始申报 | HS_CODE,数值YEAR,数值WEEK,_row_index;数值YEAR,数值WEEK,_row_index | 某HS某年周明细、跨HS年周复核 |
+| 原结果表 | 方向,基础类目,数值年度,数值月度;方向,数值年度,数值月度,统计范围,统计层级,金额精确排序 | 类目时间序列、固定范围/层级月度TopN |
+| 叶子类目查询 | 方向,二级类目,数值年度,数值月度;方向,数值年度,数值月度,二级类目,金额精确排序 | 类目趋势、固定月份叶子节点排名 |
+| 品牌型号查询 | 方向,品牌,型号,数值年度,数值月度;方向,数值年度,数值月度,二级类目,金额精确排序 | 单型号趋势、月度全量型号TopN |
+| monthly | 保留原class/model/focus三个索引,新增focus_query(direction,year,c1,c3,brand,amount,quantity,n)覆盖索引 | 原重点路径品牌聚合;新增项来自实测回归 |
+
+索引使用与读取器相同的物理列:年度/月度查询和排序使用 `_num_`,避免“索引建在文本年度、查询却走数值影子列”的错配。金额排序改为原文 `COLLATE DECIMAL_VALUE`,相应索引采用相同排序规则;Decimal比较器由索引构建器和读取连接注册。第三方SQLite客户端如需使用这些排序索引,也必须注册该比较规则。
+
+金额数量等数值筛选先用影子列做包含边界的粗筛,再用 `decimal_cmp` 精筛,避免浮点碰撞错选;不等于及not_in不使用会误排除记录的浮点预筛。缺失影子值不再 `COALESCE(...,0)`,未知值不能冒充零。聚合仍读取原始文本使用Decimal,不从REAL影子列求和。
+
+执行计划和SQL/参数保存在证据文件。使用 `EXPLAIN QUERY PLAN` 识别 SEARCH、COVERING、SCAN和临时B树,仅作为诊断证据,不把其字符串格式当作产品API契约。[SQLite执行计划](https://sqlite.org/eqp.html)、[联合索引](https://sqlite.org/queryplanner.html)。
+
+## 4. 查询规模约束、缓存和血缘
+
+- 普通查询与聚合共用服务端行数上限(默认200;Agent默认最多50),以 `LIMIT cap+1` 判断截断;逐行消费受限结果,不整表fetchall。业务单元格文本默认预算1MiB,溯源和响应元数据另计;单行超过预算要求减少columns。
+- 返回 `truncated`、原因、`exhausted`、`next_cursor`、警告。TopN/聚合页不能被解释为全量总计。上限只约束返回值,不保证GROUP BY不扫描全量;昂贵查询仍受超时保护。
+- `count_mode=auto`:无筛选时读不可变表登记行数;有筛选/聚合时 `total=null,total_exact=false`,不先COUNT。需要精确总行数时显式 `exact`,同样受查询时限约束;`none`完全不计数。
+- 自然行号顺序支持绑定查询/对象版本的opaque `next_cursor`,以 `_row_index > last` 继续。当前自定义排序及聚合不支持游标,过滤/排序/聚合OFFSET上限10000。无筛选自然行序的深“行号跳转”直接改写成主键seek,保留溯源抽屉跳转功能。[SQLite游标分页原理](https://sqlite.org/rowvalue.html)。
+- 默认5秒时限,SQLite progress handler中断;超时返回HTTP408。只读连接,32MiB页缓存,临时表落盘;最多32筛选条件、12分组维度、16指标、单个IN最多500值。进度回调不是硬实时保证,锁等待及单个UDF执行有额外误差。[Python接口](https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.set_progress_handler)。
+- 有界进程缓存最多64项/16MiB,key绑定对象/输入哈希、规则哈希、业务参数哈希、处理器/目录/查询版本及SQLite文件版本、查询条件和预算。旧统计对象缺少规则/参数快照时禁用缓存,不假装已经绑定版本。缓存命中仍在本次调用中登记台账,不复用旧call_id。
+- 结果血缘每批读取1000行、写入1000条,避免整表fetchall和全对象大列表;每批独立事务,可通过INSERT OR REPLACE重试,尚无持久化任务队列或断点调度器。
+- `upgrade_query_storage.py` 默认只预览。raw仅更新派生索引;stat通过复制生成新查询对象,保留原统计文件、行哈希和业务血缘。`--summaries`确认原完整报表模板与working.sqlite均存在时回填两张查询表,不重新分类或改写原Excel。迁移会增加磁盘占用,不适合无空间预算直接批量执行。
+
+## 5. 本机实测结果
+
+环境:macOS 26.5.2 ARM64、Python 3.14.6、SQLite 3.53.4。合成数据、单机测试,未清空OS页缓存;“首轮”不是冷缓存证据,P95取少量重复样本,不是生产P95/SLA。部分测量有同机测试任务并行干扰。
+
+### 5.1 四百万行原始CSV,实际上传索引代码
+
+100万种品牌型号申报文本,4种品牌、197种原产国代码、2003种港口代码等;通过真实 `_index_raw` 流式读取、行哈希与索引,**不包含HTTP multipart缓冲、四百万行业务分类或报表**。
+
+- CSV生成6.142秒;上传索引器(不含业务索引,包含日历数值列与行哈希)28.158秒;新增两个索引3.646秒。
+- 进程峰值RSS117.14MiB;raw.sqlite由1,074,565,120增至1,254,981,632字节。索引有明确的磁盘成本。
+- HS/年/周 + 行号范围查询:P50 0.177→0.020ms;年周查询0.253→0.019ms,执行计划由主键范围过滤改为相应联合索引SEARCH。
+- 360万行深OFFSET:P50 91.179ms;同位置主键seek 0.009ms。实际 `read_rows` 无筛选元数据首屏调用12.443ms(含对象/目录等开销),不能把纯SQL时间当API时间。
+- 100ms预算的高基数组合查询在104.870ms被中断;第二次相同读取命中版本缓存。
+
+### 5.2 四百万行高基数monthly SQL样本
+
+这是**显式构造的已解析月度表**,不是四百万行原始数据经过分类后的产物。monthly有400万行、100万种型号,其他维度保持高基数;刻意加入缺失金额检查传播。
+
+| 查询 | 无现有索引P50 | 原三个索引P50 | 结论 |
+|---|---:|---:|---|
+| 类目年汇总 | 3064.805ms | 3020.252ms | 仍需聚合大量行;不能靠原索引解决 |
+| 单型号时间序列 | 217.911ms | 0.021ms | idx_model有效 |
+| 重点路径品牌汇总 | 1777.838ms | 2483.142ms | 优化器选idx_model方向前缀,出现回归 |
+
+针对最后一项新增覆盖索引后,单独复测P50为1450.355ms,计划为 `SEARCH monthly USING COVERING INDEX idx_focus_query`;新增索引构建6.027秒,数值结果哈希相同。它仍不是毫秒级类目汇总,日常问答优先查粗粒度表。
+
+- 叶子类目查询表96行,品牌型号查询表 **300万行**;不能假设品牌型号汇总一定小。
+- 初始汇总物化与索引构建88.480秒;该影子排序基线阶段峰值RSS251.22MiB(后续Decimal索引重建RSS未单独采样),数据文件合计1,954,004,992字节(不包含后续定向索引/Decimal排序索引复验的新增空间和重建时间)。
+- 两张表严格总计均为:金额NULL(因故意的缺失成员)、成交数量202000000、记录数4000000,与monthly严格求和一致;未把缺数当零。
+- 最终Decimal排序索引重建并ANALYZE用时112.527秒(单独复验,不是最终首次物化总时长);最终查询P50/P95:类目趋势0.022/0.101ms,型号趋势0.015/0.039ms,月度型号Top50 0.036/0.120ms。均实际命中相应索引,结果哈希与之前样本一致。索引精度有明显的离线构建成本,不能沿用REAL索引构建时间宣称最终性能。
+
+### 5.3 十万条唯一申报的真实业务全流程
+
+实际使用规则库、解析器、入库、原23表、2张查询表:55.713秒;对实际十万行原始CSV核验输入SHA256后,387031条结果行的分批血缘登记复验为3.665秒(该独立登记进程峰值59.25MiB);原处理进程峰值254.09MiB;处理产物601,464,046字节。申报文本去重实查100000种,区别于此前16种重复文本的测试。
+
+## 6. 仍未验证或未实现
+
+- 未提供真实四百万行原始申报,因此**没有真实四百万行全流程性能或识别率结论**。上面的4百万查询样本与10万完整业务流水线不能相互替代,也不能线性外推。
+- 尚未做多用户并发、持续读写、冷缓存、低内存压力、异常中断恢复、网络上传内存和生产SLA测试。HTTP上传仍有整文件缓冲及512MiB默认上限;原流水线仍会生成大量诊断CSV,实际磁盘可能很大。
+- 供应链层级报表仍包含高基数父路径字典及多次GROUP BY,4百万完整报表的RSS/磁盘/耗时未知。Top100堆、查询上限、分批血缘不等于全流水线内存已经完全有界。
+- 聚合分页仍需GROUP BY/排序后LIMIT,不能证明每次只处理200行。深排序游标、持久化后台导出、任务取消/恢复、跨进程缓存、并发准入队列均未实现。大导出暂建议离线批处理,不由交互问答接口一次返回。
+- 下一步应在相同硬件和真实脱敏样本上测四百万完整流程及典型并发,再看索引成本、查询尾延迟与流水线瓶颈是否足以支持换引擎;本轮没有“必须换引擎”的证据。
+
+## 7. 复现
+
+```sh
+.venv/bin/python -m pytest -c tools-service/pyproject.toml tools-service/tests
+.venv/bin/python scripts/benchmark_queries.py --rows 4000000 --pipeline-rows 100000
+.venv/bin/python scripts/verify_business_parity.py --legacy /path/to/component_trade_promax
+CDA_PYTHON="$PWD/.venv/bin/python" node scripts/e2e.mjs --keep
+# 先预览迁移,确认对象与空间;stat迁移生成新对象
+CDA_DATA_DIR="$PWD/data" .venv/bin/python scripts/upgrade_query_storage.py
+CDA_DATA_DIR="$PWD/data" .venv/bin/python scripts/upgrade_query_storage.py --apply --summaries --object-id OBJ_ID
+```
+
+当前来源血缘仍以来源对象和维度谓词登记;完整的条件到原始行执行下钻、成交单位一致性和生产可追溯链路还需真实数据验证。
+
+运行参数见 `.env.example`:CDA_QUERY_TIMEOUT_MS、CDA_QUERY_MAX_OFFSET、CDA_QUERY_MAX_BYTES。
+
+验证清单:Python 213 项、BFF 66 项、前端27项和真实模型端到端33项。完整机器可读目录见 `08-统计表业务目录.json`。`contains` 等前导通配搜索、任意OR/跨维度查询没有自动索引保证,仍可能全扫描并超时。

+ 2073 - 0
docs/08-统计表业务目录.json

@@ -0,0 +1,2073 @@
+[
+  {
+    "table": "1.0-3.0_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "基础类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "电容器指数",
+      "row_grain": "方向×年月×电容器二级类目",
+      "coverage": "类目全部金额数量;价格指数使用年度样本",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "基础类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.1_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "电容器总览",
+      "row_grain": "进出口方向×年月×电容器一级类目",
+      "coverage": "项目范围电容器全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.2.1_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "电容器年度结构",
+      "row_grain": "方向×年度×电容器二级类目",
+      "coverage": "当年已提供期间",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.2.2_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "电容器月度结构",
+      "row_grain": "方向×年月×二级类目",
+      "coverage": "类目全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.2.3 (1-4)_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "MLCC重点分析",
+      "row_grain": "方向×年度×应用/品牌国别/品牌/型号路径节点",
+      "coverage": "年度入选路径及其他桶;父级与子级不可相加",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.2.3 (5)_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "品牌",
+      "型号",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "MLCC型号月度",
+      "row_grain": "方向×年月×品牌型号×统计范围",
+      "coverage": "项目范围全部进口、限定入选路径是重叠视图,不可合计",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "品牌",
+        "型号",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "4.3_MLCC",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "品牌国别",
+      "原产国",
+      "贸易国",
+      "启运国",
+      "经停港/指运港",
+      "应用领域标签",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "MLCC供应链",
+      "row_grain": "方向×年度×供应链路径节点×港口粒度",
+      "coverage": "具体港口与港口国家地区为重叠视图;父子层级重复",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "品牌国别",
+        "原产国",
+        "贸易国",
+        "启运国",
+        "经停港/指运港",
+        "应用领域标签",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "1.0-3.0_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "基础类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器指数",
+      "row_grain": "方向×年月×类目节点;父子层级同时存在",
+      "coverage": "类目全部金额数量;价格指数使用年度样本",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "基础类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.1_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器总览",
+      "row_grain": "进出口方向×年月×存储器一级类目",
+      "coverage": "项目范围存储器全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.1&3&5_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "描述",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器年度结构",
+      "row_grain": "方向×年度×类目节点;父子层级同时存在",
+      "coverage": "当年已提供期间",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "描述",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.2_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器月度结构",
+      "row_grain": "方向×年月×二级类目",
+      "coverage": "类目全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.4_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器月度结构",
+      "row_grain": "方向×年月×三级类目",
+      "coverage": "类目全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.6_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "描述",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "存储器月度结构",
+      "row_grain": "方向×年月×DDR代际",
+      "coverage": "类目全部纳入记录",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "描述",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.7 (1-4)_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "描述",
+      "应用领域标签",
+      "品牌国别",
+      "品牌",
+      "前十大型号",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "DDR重点分析",
+      "row_grain": "方向×年度×应用/品牌国别/品牌/型号路径节点",
+      "coverage": "已分类DDR入选路径及其他桶;父级与子级不可相加",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "描述",
+        "应用领域标签",
+        "品牌国别",
+        "品牌",
+        "前十大型号",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.2.7 (5)_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "品牌",
+      "型号",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "应用领域标签",
+      "品牌国别",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "DDR型号月度",
+      "row_grain": "方向×年月×品牌型号×统计范围",
+      "coverage": "已分类DDR全部、限定入选路径是重叠视图,不可合计",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "品牌",
+        "型号",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "应用领域标签",
+        "品牌国别",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "5.3_存储器",
+    "columns": [
+      "进/出口",
+      "年度",
+      "一级类目",
+      "二级类目",
+      "品牌国别",
+      "原产国",
+      "贸易国",
+      "启运国",
+      "经停港/指运港",
+      "应用领域标签",
+      "实际金额(美元)",
+      "成交数量",
+      "平均单价(美元/成交数量单位)",
+      "金额指数",
+      "数量指数",
+      "价格指数",
+      "金额占比",
+      "数量占比",
+      "金额环比",
+      "数量环比",
+      "占比分母范围",
+      "记录数",
+      "计算说明",
+      "年度数据状态",
+      "统计层级",
+      "统计范围",
+      "选样年度",
+      "选样年度状态",
+      "品牌",
+      "前十大型号",
+      "港口所属国家地区",
+      "港口统计粒度"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "DDR供应链",
+      "row_grain": "方向×年度×供应链路径节点×港口粒度",
+      "coverage": "已分类DDR;具体港口与国家地区重叠;父子层级重复",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "一级类目",
+        "二级类目",
+        "品牌国别",
+        "原产国",
+        "贸易国",
+        "启运国",
+        "经停港/指运港",
+        "应用领域标签",
+        "占比分母范围",
+        "年度数据状态",
+        "统计层级",
+        "统计范围",
+        "选样年度",
+        "选样年度状态",
+        "品牌",
+        "前十大型号",
+        "港口所属国家地区",
+        "港口统计粒度"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "统计层级",
+          "统计范围",
+          "港口统计粒度",
+          "占比分母范围",
+          "选样年度"
+        ],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)",
+          "金额指数",
+          "数量指数",
+          "价格指数",
+          "金额占比",
+          "数量占比",
+          "金额环比",
+          "数量环比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价",
+        "金额指数": "本期金额 / 2025-01金额 × 1000",
+        "数量指数": "本期数量 / 2025-01数量 × 1000",
+        "价格指数": "年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加",
+        "金额环比": "本月金额 / 上月金额 - 1;缺数或零分母留空",
+        "数量环比": "本月数量 / 上月数量 - 1;缺数或零分母留空"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "样本权重",
+    "columns": [
+      "进/出口",
+      "基础类目",
+      "选样年度",
+      "排名",
+      "品牌",
+      "型号",
+      "年度金额(美元)",
+      "权重",
+      "样本数量",
+      "权重规则",
+      "年度数据状态"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "价格样本审计",
+      "row_grain": "方向×基础类目×选样年度×样本品牌型号",
+      "coverage": "年度前100;不同类目样本可能重叠",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "基础类目",
+        "选样年度",
+        "排名",
+        "品牌",
+        "型号",
+        "年度金额(美元)",
+        "样本数量",
+        "权重规则",
+        "年度数据状态"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [],
+        "required_partitions": [
+          "进/出口",
+          "选样年度"
+        ],
+        "non_additive": [
+          "权重"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "权重": "年度样本金额权重,封顶再分配;仅同一篮子可校验合计,不可跨篮子求和或平均"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "选样排除",
+    "columns": [
+      "进/出口",
+      "基础类目",
+      "选样年度",
+      "品牌",
+      "型号",
+      "年度金额(美元)",
+      "原因"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "价格样本审计",
+      "row_grain": "方向×基础类目×选样年度×排除品牌型号",
+      "coverage": "实际值仍计入总量,排除的只是价格选样",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "基础类目",
+        "选样年度",
+        "品牌",
+        "型号",
+        "年度金额(美元)",
+        "原因"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [],
+        "required_partitions": [
+          "进/出口",
+          "选样年度"
+        ],
+        "non_additive": [],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {},
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "重点全量层级",
+    "columns": [
+      "进/出口",
+      "年度",
+      "专项",
+      "层级",
+      "父级路径",
+      "名称",
+      "入选",
+      "实际金额(美元)",
+      "成交数量",
+      "金额占比",
+      "数量占比",
+      "占比分母范围",
+      "计算说明"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "重点分析审计",
+      "row_grain": "方向×年度×专项×层级×父级路径×节点",
+      "coverage": "完整候选节点;父子层级不可相加",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "专项",
+        "层级",
+        "父级路径",
+        "名称",
+        "入选",
+        "占比分母范围"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "层级",
+          "占比分母范围"
+        ],
+        "non_additive": [
+          "金额占比",
+          "数量占比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "供应链条件占比",
+    "columns": [
+      "进/出口",
+      "年度",
+      "专项",
+      "港口统计粒度",
+      "分析方式",
+      "层级",
+      "父级路径",
+      "节点",
+      "实际金额(美元)",
+      "成交数量",
+      "金额占比",
+      "数量占比",
+      "占比分母范围"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "供应链条件审计",
+      "row_grain": "方向×年度×专项×分析方式×港口粒度×层级×父级路径×节点",
+      "coverage": "分母随分析方式和路径改变,不可跨条件合计",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "专项",
+        "港口统计粒度",
+        "分析方式",
+        "层级",
+        "父级路径",
+        "节点",
+        "占比分母范围"
+      ],
+      "denominator": "以每行占比分母范围为准;父子/范围/港口粒度视图不能相加",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量"
+        ],
+        "required_partitions": [
+          "进/出口",
+          "层级",
+          "港口统计粒度",
+          "分析方式",
+          "占比分母范围"
+        ],
+        "non_additive": [
+          "金额占比",
+          "数量占比"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "金额占比": "本行金额 / 占比分母范围指定金额;不能跨分母累加",
+        "数量占比": "本行数量 / 占比分母范围指定数量;不能跨分母累加"
+      },
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "周四归月映射",
+    "columns": [
+      "ISO年",
+      "ISO周",
+      "周一日期",
+      "周日日期",
+      "周四日期",
+      "归属年",
+      "归属月",
+      "规则"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "日历",
+      "row_grain": "一个ISO年周",
+      "coverage": "整周按周四归月,不含业务金额",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "ISO年",
+        "ISO周",
+        "周一日期",
+        "周日日期",
+        "周四日期",
+        "归属年",
+        "归属月",
+        "规则"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [],
+        "required_partitions": [],
+        "non_additive": [],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {},
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "数据质量摘要",
+    "columns": [
+      "项目",
+      "值",
+      "说明"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "质量审计",
+      "row_grain": "一个运行指标或异常原因",
+      "coverage": "该运行输入、排除、识别与口径说明",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "项目",
+        "值",
+        "说明"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [],
+        "required_partitions": [],
+        "non_additive": [],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {},
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "映射冲突",
+    "columns": [
+      "类型",
+      "匹配键",
+      "冲突内容"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "规则审计",
+      "row_grain": "一个映射键的冲突",
+      "coverage": "规则库冲突,不含业务金额",
+      "hierarchy": "见粒度与统计层级字段;原模板可能混合父子节点",
+      "filter_dimensions": [
+        "类型",
+        "匹配键",
+        "冲突内容"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [],
+        "required_partitions": [],
+        "non_additive": [],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {},
+      "preferred_for": "按本表口径直接取值;求和前检查粒度",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "查询_叶子类目月度",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "描述",
+      "实际金额(美元)",
+      "成交数量",
+      "记录数",
+      "平均单价(美元/成交数量单位)"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "叶子类目月度总量",
+      "row_grain": "方向×年月×叶子类目路径",
+      "coverage": "全部纳入记录;未识别品牌/型号保留空组;不含父级合计、TopN截断或价格样本限制",
+      "hierarchy": "叶子且互斥",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "描述"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价"
+      },
+      "preferred_for": "全量金额数量问答",
+      "version_binding": {}
+    }
+  },
+  {
+    "table": "查询_品牌型号月度",
+    "columns": [
+      "进/出口",
+      "年度",
+      "月度",
+      "一级类目",
+      "二级类目",
+      "三级类目",
+      "描述",
+      "品牌",
+      "型号",
+      "实际金额(美元)",
+      "成交数量",
+      "记录数",
+      "平均单价(美元/成交数量单位)"
+    ],
+    "catalog": {
+      "version": "2026-11-18.1",
+      "subject": "完整品牌型号月度总量",
+      "row_grain": "方向×年月×叶子类目路径×品牌×型号",
+      "coverage": "全部纳入记录;未识别品牌/型号保留空组;不含父级合计、TopN截断或价格样本限制",
+      "hierarchy": "叶子且互斥",
+      "filter_dimensions": [
+        "进/出口",
+        "年度",
+        "月度",
+        "一级类目",
+        "二级类目",
+        "三级类目",
+        "描述",
+        "品牌",
+        "型号"
+      ],
+      "denominator": "本表不提供占比;计算前需明确可比范围和单位",
+      "aggregation": {
+        "additive_fields": [
+          "实际金额(美元)",
+          "成交数量",
+          "记录数"
+        ],
+        "required_partitions": [],
+        "non_additive": [
+          "平均单价(美元/成交数量单位)"
+        ],
+        "average_price": "sum(金额)/sum(数量),缺数传播;成交数量单位须可比",
+        "unknown_scope": false
+      },
+      "metric_definitions": {
+        "实际金额(美元)": "纳入范围的美元金额;任一成员缺失则合计未知",
+        "成交数量": "成交数量;只有单位可比时可累加;任一成员缺失则合计未知",
+        "平均单价(美元/成交数量单位)": "合计金额 / 合计成交数量;不能累加或简单平均各行单价"
+      },
+      "preferred_for": "全量金额数量问答",
+      "version_binding": {}
+    }
+  }
+]

+ 62 - 0
docs/09-扩展测试与界面回归.md

@@ -0,0 +1,62 @@
+# 扩展测试与界面回归(2026-11-18)
+
+本轮新增 64 项自动化测试:Python 59 项、BFF 3 项、前端 2 项。保持已有 ZIP 的分类、纳入范围、统计公式和 Decimal 精度;本轮没有新增业务口径差异。参数校验变严格,非法查询参数返回 400/422,不再出现 500 或静默更改查询范围。
+
+## 已执行的自动化验证
+
+| 测试组 | 通过 | 说明 |
+| --- | ---: | --- |
+| Python 引擎与接口 | 272 | 原项目全量 pytest;存在一条依赖库弃用提醒,无失败 |
+| BFF 单元与接口 | 69 | 构建后 node --test |
+| 前端单元与组件渲染 | 29 | 包括警告展示、工作区对话框;最终样式修改后重新通过 |
+| 服务联调 | 33 | 真实服务和 DeepSeek,含会话持久化、台账与静态页面 |
+| BFF / 前端构建 | 成功 | TypeScript 与生产构建 |
+
+### 新覆盖的风险
+
+- 聚合参数类型、非法排序方向、非正数 limit、超长/非法游标。
+- 不同分页大小、字节限制和空结果,游标连续性及精确/按需计数。
+- 随机 Decimal 独立预言机、大金额与正负数、缺失值传播。
+- 非可加指标的 16 种 sum/avg 拒绝案例,以及外部遮掩统计表聚合限制。
+- 32 个并发缓存读取的结果隔离、缓存数量/字节上界、超时后恢复。
+- 缓存命中仍独立登记 call_id,SQL 注入字符串仅作为条件值。
+- 工具目录契约、查询参数透传、SSE 与持久化结果的截断警告。
+- 不展开工具卡也能看到警告;新建工作区对话框的空白名称和提交状态。
+- 完整统计流程与固定预言机比对,不用生产输出本身生成期望值。
+
+## 测试发现并修复的问题
+
+1. 错误聚合参数可导致 500;非法排序被接受;非正数 limit 被静默改写。增加明确校验。
+2. 查询截断信息未完整传递到 BFF SSE、会话记录和界面。增加贯通字段,流式与历史工具卡均直接显示警告。
+3. 新建工作区使用 window.prompt,在内嵌浏览器无法工作。改用应用内表单对话框,防止空白名称及重复提交。
+4. 窄窗口下固定侧栏挤出聊天正文。增加 720px 以下上下布局,实际默认窄窗口中确认导航、正文、输入框与警告可见。
+
+## 真实界面回归
+
+程序地址:<http://127.0.0.1:8787>。在界面创建工作区 `界面回归_20261118`,通过文件选择器上传 `samples/ui_regression.csv`,点击全套统计处理,随后通过真实 DeepSeek 对话查询。
+
+固定样本 63 行包含:引号包裹的多行申报文本、小数金额、未知品牌、多品牌歧义、8 位 HS、非法周 54、范围外出口方向。预言机为 `samples/ui_regression.expected.json`。
+
+| 检查 | 实际结果 |
+| --- | --- |
+| 上传 | 63 行成功,原始对象 obj_6b37fe05 |
+| 全套处理 | run_de0c6ef6 成功;结果对象 obj_c006dbc4;25 张查询表(23 张报表 + 2 张查询汇总) |
+| 范围与异常 | 纳入 60 行,排除 3 行;界面提示 3 条数值/范围异常 |
+| 金额、数量、记录数 | 2025-01 进口 MLCC:183.00 美元、1830、60,与预言机一致 |
+| 模型问答 | 正确回答以上三项;页面显示数字核验通过,且引用当前工作区结果 |
+| 来源抽屉 | 点击 183,显示结果对象、表名、行号、行哈希、字段名与原始对象下钻条件 |
+| 部分结果 | 品牌型号月度 limit=5,显示受限子集警告;模型明确 5 行不是全部,精确总数 60 |
+| 刷新持久化 | 四条会话消息、结果和截断警告保留 |
+| 窄窗口 | 原默认窗口中验证布局修复后正文、导航、输入框、来源抽屉和警告可见 |
+
+### 界面证据
+
+![部分结果的可见警告](evidence/ui-regression-20261118/09-final-warning.jpg)
+
+![数字来源](evidence/ui-regression-20261118/08-narrow-trace.jpg)
+
+## 尚未验证的限制
+
+本轮为功能、边界和接口回归,不是新的四百万行性能实测;63 行界面样本不能证明百万行处理耗时、峰值内存或查询延迟。大数据实验与业务对照仍以 `07-大数据查询设计与实测.md` 的数据规模和边界为准。本轮未全面验证所有页面、所有浏览器或所有桌面尺寸。
+
+日志见 `.run/qualification-expanded/`。测试留下的独立工作区用于继续演示;未改动用户原始压缩包和历史数据。

+ 55 - 0
docs/evidence/20261118/exact-index-requalification.json

@@ -0,0 +1,55 @@
+{
+  "scope": "existing 4m monthly / 3m model-summary fixture; final Decimal-index definition requalification",
+  "exact_index_build_seconds": 112.527,
+  "queries": {
+    "class_timeline": {
+      "sql": "SELECT \"年度\",\"月度\",\"实际金额(美元)\" FROM q_class_month WHERE \"进/出口\"=? AND \"二级类目\"=? ORDER BY \"_num_年度\",\"_num_月度\",_row_index",
+      "parameters": [
+        "I",
+        "DRAM"
+      ],
+      "plan": [
+        "SEARCH q_class_month USING INDEX idx_query_5083ac899bb7 (进/出口=? AND 二级类目=?)"
+      ],
+      "first_ms": 0.101,
+      "p50_ms": 0.022,
+      "p95_ms": 0.101,
+      "rows": 24,
+      "result_sha256": "1880f1d02663fefc13d68c7f56b7136a6c17783e20743324b63689ae61b99807"
+    },
+    "model_timeline": {
+      "sql": "SELECT \"年度\",\"月度\",\"实际金额(美元)\" FROM q_model_month WHERE \"进/出口\"=? AND \"品牌\"=? AND \"型号\"=? ORDER BY \"_num_年度\",\"_num_月度\",_row_index",
+      "parameters": [
+        "I",
+        "SAMSUNG",
+        "TEST-00000001"
+      ],
+      "plan": [
+        "SEARCH q_model_month USING INDEX idx_query_3a945a8e1342 (进/出口=? AND 品牌=? AND 型号=?)"
+      ],
+      "first_ms": 0.039,
+      "p50_ms": 0.015,
+      "p95_ms": 0.039,
+      "rows": 3,
+      "result_sha256": "f3822908f6a03fe7c545c9bc38e7d4a1ab616d43fe34043379c1874634499547"
+    },
+    "month_top50": {
+      "sql": "SELECT \"品牌\",\"型号\",\"实际金额(美元)\" FROM q_model_month WHERE \"进/出口\"=? AND \"_num_年度\"=? AND \"_num_月度\"=? AND \"二级类目\"=? ORDER BY \"实际金额(美元)\" COLLATE DECIMAL_VALUE DESC,_row_index ASC LIMIT 50",
+      "parameters": [
+        "I",
+        "2025",
+        "1",
+        "DRAM"
+      ],
+      "plan": [
+        "SEARCH q_model_month USING INDEX idx_query_ac84ead4b611 (进/出口=? AND _num_年度=? AND _num_月度=? AND 二级类目=?)"
+      ],
+      "first_ms": 0.12,
+      "p50_ms": 0.036,
+      "p95_ms": 0.12,
+      "rows": 50,
+      "result_sha256": "5a2e98083e44cf6563baefc7d5be28f63a90929f64984c682f3c454eb01ecc80"
+    }
+  },
+  "sqlite_bytes": 878325760
+}

+ 39 - 0
docs/evidence/20261118/focus-index-experiment.json

@@ -0,0 +1,39 @@
+{
+  "before": {
+    "sql": "SELECT brand,dsum(amount) FROM monthly WHERE direction=? AND year=? AND c1=? AND c3=? GROUP BY brand",
+    "parameters": [
+      "I",
+      "2025",
+      "存储器",
+      "DDR"
+    ],
+    "plan": [
+      "SEARCH monthly USING INDEX idx_model (direction=?)"
+    ],
+    "first_ms": 3514.7,
+    "p50_ms": 2494.692,
+    "p95_ms": 3514.7,
+    "rows": 3,
+    "result_sha256": "d01d2250dd79e3789655a3f679e62a5051043bf95ab3f6e996a62212b44e13a6"
+  },
+  "after": {
+    "sql": "SELECT brand,dsum(amount) FROM monthly WHERE direction=? AND year=? AND c1=? AND c3=? GROUP BY brand",
+    "parameters": [
+      "I",
+      "2025",
+      "存储器",
+      "DDR"
+    ],
+    "plan": [
+      "SEARCH monthly USING COVERING INDEX idx_focus_query (direction=? AND year=? AND c1=? AND c3=?)"
+    ],
+    "first_ms": 1460.615,
+    "p50_ms": 1450.355,
+    "p95_ms": 1460.615,
+    "rows": 3,
+    "result_sha256": "d01d2250dd79e3789655a3f679e62a5051043bf95ab3f6e996a62212b44e13a6"
+  },
+  "index_build_seconds": 6.026850083959289,
+  "index_sql": "CREATE INDEX idx_focus_query ON monthly(direction,year,c1,c3,brand,amount,quantity,n)",
+  "sqlite_after_bytes": 1257381888
+}

+ 8 - 0
docs/evidence/20261118/lineage-source-requalification.json

@@ -0,0 +1,8 @@
+{
+  "scope": "actual 100k CSV parent object SHA256 matches processing input; batched 387031 row-lineage registration",
+  "source_rows": 100000,
+  "input_sha256_matches": true,
+  "registered_rows": 387031,
+  "seconds": 3.665,
+  "peak_rss_mb": 59.25
+}

+ 194 - 0
docs/evidence/20261118/monthly-4m.json

@@ -0,0 +1,194 @@
+{
+  "platform": "macOS-26.5.2-arm64-arm-64bit-Mach-O",
+  "python": "3.14.6",
+  "sqlite": "3.53.4",
+  "os_cache": "not flushed; first connection and warm repeats; not cold-cache evidence",
+  "rows": 4000000,
+  "phases": {
+    "monthly": {
+      "scope": "4m high-cardinality parsed monthly SQL fixture, NOT a 4m business parser/pipeline run",
+      "rows": 4000000,
+      "model_cardinality": 1000000,
+      "monthly_rows": 4000000,
+      "load_seconds": 7.849,
+      "existing_three_index_seconds": 10.047,
+      "before": {
+        "class_year": {
+          "sql": "SELECT c2,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND c1=? AND year=? GROUP BY c2",
+          "parameters": [
+            "I",
+            "存储器",
+            "2025"
+          ],
+          "plan": [
+            "SCAN monthly",
+            "USE TEMP B-TREE FOR GROUP BY"
+          ],
+          "first_ms": 3143.557,
+          "p50_ms": 3064.805,
+          "p95_ms": 3143.557,
+          "rows": 1,
+          "result_sha256": "60d224cc7ef8849c56cecb29285ec7dd8461753f31cf8d2148ef7e6502672239"
+        },
+        "one_model_timeline": {
+          "sql": "SELECT month,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND brand=? AND model=? GROUP BY month",
+          "parameters": [
+            "I",
+            "SAMSUNG",
+            "TEST-00000001"
+          ],
+          "plan": [
+            "SCAN monthly",
+            "USE TEMP B-TREE FOR GROUP BY"
+          ],
+          "first_ms": 218.332,
+          "p50_ms": 217.911,
+          "p95_ms": 218.332,
+          "rows": 3,
+          "result_sha256": "051f538236236c917174e7eadc0f267c9919a92c5d407a605673088b0fe21763"
+        },
+        "focus": {
+          "sql": "SELECT brand,dsum(amount) FROM monthly WHERE direction=? AND year=? AND c1=? AND c3=? GROUP BY brand",
+          "parameters": [
+            "I",
+            "2025",
+            "存储器",
+            "DDR"
+          ],
+          "plan": [
+            "SCAN monthly",
+            "USE TEMP B-TREE FOR GROUP BY"
+          ],
+          "first_ms": 1766.261,
+          "p50_ms": 1777.838,
+          "p95_ms": 1780.937,
+          "rows": 3,
+          "result_sha256": "d01d2250dd79e3789655a3f679e62a5051043bf95ab3f6e996a62212b44e13a6"
+        }
+      },
+      "after": {
+        "class_year": {
+          "sql": "SELECT c2,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND c1=? AND year=? GROUP BY c2",
+          "parameters": [
+            "I",
+            "存储器",
+            "2025"
+          ],
+          "plan": [
+            "SEARCH monthly USING INDEX idx_class (direction=? AND c1=?)"
+          ],
+          "first_ms": 3018.343,
+          "p50_ms": 3020.252,
+          "p95_ms": 3027.901,
+          "rows": 1,
+          "result_sha256": "60d224cc7ef8849c56cecb29285ec7dd8461753f31cf8d2148ef7e6502672239"
+        },
+        "one_model_timeline": {
+          "sql": "SELECT month,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND brand=? AND model=? GROUP BY month",
+          "parameters": [
+            "I",
+            "SAMSUNG",
+            "TEST-00000001"
+          ],
+          "plan": [
+            "SEARCH monthly USING INDEX idx_model (direction=? AND brand=? AND model=?)"
+          ],
+          "first_ms": 0.102,
+          "p50_ms": 0.021,
+          "p95_ms": 0.102,
+          "rows": 3,
+          "result_sha256": "051f538236236c917174e7eadc0f267c9919a92c5d407a605673088b0fe21763"
+        },
+        "focus": {
+          "sql": "SELECT brand,dsum(amount) FROM monthly WHERE direction=? AND year=? AND c1=? AND c3=? GROUP BY brand",
+          "parameters": [
+            "I",
+            "2025",
+            "存储器",
+            "DDR"
+          ],
+          "plan": [
+            "SEARCH monthly USING INDEX idx_model (direction=?)"
+          ],
+          "first_ms": 2488.714,
+          "p50_ms": 2483.142,
+          "p95_ms": 2488.714,
+          "rows": 3,
+          "result_sha256": "d01d2250dd79e3789655a3f679e62a5051043bf95ab3f6e996a62212b44e13a6"
+        }
+      },
+      "query_summary_build_seconds": 88.48,
+      "summary_row_counts": {
+        "查询_叶子类目月度": 96,
+        "查询_品牌型号月度": 3000000
+      },
+      "summary_queries": {
+        "class_timeline": {
+          "sql": "SELECT \"年度\",\"月度\",\"实际金额(美元)\" FROM q_class_month WHERE \"进/出口\"=? AND \"二级类目\"=? ORDER BY \"_num_年度\",\"_num_月度\",_row_index",
+          "parameters": [
+            "I",
+            "DRAM"
+          ],
+          "plan": [
+            "SEARCH q_class_month USING INDEX idx_query_5083ac899bb7 (进/出口=? AND 二级类目=?)"
+          ],
+          "first_ms": 0.084,
+          "p50_ms": 0.015,
+          "p95_ms": 0.084,
+          "rows": 24,
+          "result_sha256": "1880f1d02663fefc13d68c7f56b7136a6c17783e20743324b63689ae61b99807"
+        },
+        "model_timeline": {
+          "sql": "SELECT \"年度\",\"月度\",\"实际金额(美元)\" FROM q_model_month WHERE \"进/出口\"=? AND \"品牌\"=? AND \"型号\"=? ORDER BY \"_num_年度\",\"_num_月度\",_row_index",
+          "parameters": [
+            "I",
+            "SAMSUNG",
+            "TEST-00000001"
+          ],
+          "plan": [
+            "SEARCH q_model_month USING INDEX idx_query_3a945a8e1342 (进/出口=? AND 品牌=? AND 型号=?)"
+          ],
+          "first_ms": 0.035,
+          "p50_ms": 0.011,
+          "p95_ms": 0.035,
+          "rows": 3,
+          "result_sha256": "f3822908f6a03fe7c545c9bc38e7d4a1ab616d43fe34043379c1874634499547"
+        },
+        "month_top50": {
+          "sql": "SELECT \"品牌\",\"型号\",\"实际金额(美元)\" FROM q_model_month WHERE \"进/出口\"=? AND \"_num_年度\"=? AND \"_num_月度\"=? AND \"二级类目\"=? ORDER BY \"_num_实际金额(美元)\" DESC,_row_index ASC LIMIT 50",
+          "parameters": [
+            "I",
+            "2025",
+            "1",
+            "DRAM"
+          ],
+          "plan": [
+            "SEARCH q_model_month USING INDEX idx_query_d5d32784bdfe (进/出口=? AND _num_年度=? AND _num_月度=? AND 二级类目=?)"
+          ],
+          "first_ms": 0.093,
+          "p50_ms": 0.031,
+          "p95_ms": 0.093,
+          "rows": 50,
+          "result_sha256": "5a2e98083e44cf6563baefc7d5be28f63a90929f64984c682f3c454eb01ecc80"
+        }
+      },
+      "exact_summary_totals": {
+        "q_class_month": [
+          null,
+          "202000000",
+          4000000
+        ],
+        "q_model_month": [
+          null,
+          "202000000",
+          4000000
+        ]
+      },
+      "missing_amount_policy": "global sum is NULL due to deliberate missing members",
+      "disk_bytes": 1954004992
+    }
+  },
+  "phase_wall_seconds": 154.719,
+  "peak_rss_mb": 251.22,
+  "total_disk_bytes": 1954004992
+}

+ 57 - 0
docs/evidence/20261118/pipeline-100k.json

@@ -0,0 +1,57 @@
+{
+  "platform": "macOS-26.5.2-arm64-arm-64bit-Mach-O",
+  "python": "3.14.6",
+  "sqlite": "3.53.4",
+  "os_cache": "not flushed; first connection and warm repeats; not cold-cache evidence",
+  "rows": 4000000,
+  "phases": {
+    "pipeline": {
+      "scope": "full actual rules+parser+ingest+original 23 reports+2 query summaries; lineage registration separately timed",
+      "rows": 100000,
+      "distinct_declarations": 100000,
+      "seconds": 55.713,
+      "stats": {
+        "total": 100000,
+        "included": 100000,
+        "excluded": 0,
+        "alerts": 0,
+        "min_month": "2025-01",
+        "max_month": "2026-12",
+        "recognition": {
+          "brand_resolved": 100000,
+          "model_present": 100000
+        },
+        "exclusion_reasons": {},
+        "input_fields": [
+          "I_E_FLAG",
+          "HS_CODE",
+          "YEAR",
+          "WEEK",
+          "MONORSUM",
+          "COUNT",
+          "G_MODEL",
+          "ORIGIN_COUNTRY",
+          "TRADE_AREA_CODE",
+          "TRADE_COUNTRY",
+          "DISTINATE_PORT"
+        ],
+        "sha256": "94eaba5682a6b25d367662f83040e83ff84cbf1e3f8e7fbd85825b7932e28a51",
+        "cutoff": "2026-12-31",
+        "partial_year_rule": "仅 confirmed_complete_years 明确确认为全年,其余均为已提供期间暂算",
+        "seconds": 55.648,
+        "engine": {
+          "name": "customs-default",
+          "version": "2.2.0"
+        }
+      },
+      "lineage_seconds": 3.843,
+      "result_rows": 387031,
+      "workbook_sheets": 23,
+      "query_tables": 2,
+      "output_bytes": 601464046
+    }
+  },
+  "phase_wall_seconds": 59.797,
+  "peak_rss_mb": 254.09,
+  "total_disk_bytes": 724015508
+}

+ 172 - 0
docs/evidence/20261118/raw-4m.json

@@ -0,0 +1,172 @@
+{
+  "platform": "macOS-26.5.2-arm64-arm-64bit-Mach-O",
+  "python": "3.14.6",
+  "sqlite": "3.53.4",
+  "os_cache": "not flushed; first connection and warm repeats; not cold-cache evidence",
+  "rows": 4000000,
+  "phases": {
+    "raw": {
+      "scope": "production _index_raw streaming path; excludes HTTP multipart buffering and business classification",
+      "rows": 4000000,
+      "declared_distinct_models": 1000000,
+      "distinct_declarations": 1000000,
+      "generate_seconds": 6.142,
+      "indexer_without_business_indexes_seconds": 28.158,
+      "business_index_seconds": 3.646,
+      "business_indexes": [
+        {
+          "name": "idx_query_853f423ebfa0",
+          "columns": [
+            "HS_CODE",
+            "_num_YEAR",
+            "_num_WEEK",
+            "_row_index"
+          ]
+        },
+        {
+          "name": "idx_query_f8d60d505f80",
+          "columns": [
+            "_num_YEAR",
+            "_num_WEEK",
+            "_row_index"
+          ]
+        }
+      ],
+      "sqlite_before_bytes": 1074565120,
+      "sqlite_after_bytes": 1254981632,
+      "before": {
+        "hs_year_week_seek": {
+          "sql": "SELECT _row_index,MONORSUM_USD FROM raw WHERE HS_CODE=? AND _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            "8532241000",
+            "2025",
+            "1",
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INTEGER PRIMARY KEY (rowid>?)"
+          ],
+          "first_ms": 0.47,
+          "p50_ms": 0.177,
+          "p95_ms": 0.47,
+          "rows": 50,
+          "result_sha256": "614cc687193b75dac4dbc4ef319d4135edaa11a23102ea1a0ad7ef23027b5e69"
+        },
+        "year_week_seek": {
+          "sql": "SELECT _row_index,HS_CODE FROM raw WHERE _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            "2025",
+            "1",
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INTEGER PRIMARY KEY (rowid>?)"
+          ],
+          "first_ms": 0.259,
+          "p50_ms": 0.253,
+          "p95_ms": 0.259,
+          "rows": 50,
+          "result_sha256": "4dff15f1825966347c4b18c356915c50daa5ac0cebaab52e0d1ac31a73ad3aa2"
+        },
+        "deep_offset": {
+          "sql": "SELECT _row_index FROM raw ORDER BY _row_index LIMIT 50 OFFSET ?",
+          "parameters": [
+            3600000
+          ],
+          "plan": [
+            "SCAN raw"
+          ],
+          "first_ms": 90.833,
+          "p50_ms": 90.476,
+          "p95_ms": 90.833,
+          "rows": 50,
+          "result_sha256": "e2b12173a4a7d17dd545e0a6b1a38e98d55d321f6c43f00aad0d2ff88528ada9"
+        },
+        "deep_keyset": {
+          "sql": "SELECT _row_index FROM raw WHERE _row_index>=? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INTEGER PRIMARY KEY (rowid>?)"
+          ],
+          "first_ms": 0.029,
+          "p50_ms": 0.009,
+          "p95_ms": 0.029,
+          "rows": 50,
+          "result_sha256": "e2b12173a4a7d17dd545e0a6b1a38e98d55d321f6c43f00aad0d2ff88528ada9"
+        }
+      },
+      "after": {
+        "hs_year_week_seek": {
+          "sql": "SELECT _row_index,MONORSUM_USD FROM raw WHERE HS_CODE=? AND _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            "8532241000",
+            "2025",
+            "1",
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INDEX idx_query_853f423ebfa0 (HS_CODE=? AND _num_YEAR=? AND _num_WEEK=? AND _row_index>?)"
+          ],
+          "first_ms": 0.097,
+          "p50_ms": 0.02,
+          "p95_ms": 0.097,
+          "rows": 50,
+          "result_sha256": "614cc687193b75dac4dbc4ef319d4135edaa11a23102ea1a0ad7ef23027b5e69"
+        },
+        "year_week_seek": {
+          "sql": "SELECT _row_index,HS_CODE FROM raw WHERE _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            "2025",
+            "1",
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INDEX idx_query_f8d60d505f80 (_num_YEAR=? AND _num_WEEK=? AND _row_index>?)"
+          ],
+          "first_ms": 0.033,
+          "p50_ms": 0.019,
+          "p95_ms": 0.033,
+          "rows": 50,
+          "result_sha256": "4dff15f1825966347c4b18c356915c50daa5ac0cebaab52e0d1ac31a73ad3aa2"
+        },
+        "deep_offset": {
+          "sql": "SELECT _row_index FROM raw ORDER BY _row_index LIMIT 50 OFFSET ?",
+          "parameters": [
+            3600000
+          ],
+          "plan": [
+            "SCAN raw"
+          ],
+          "first_ms": 91.179,
+          "p50_ms": 91.179,
+          "p95_ms": 92.13,
+          "rows": 50,
+          "result_sha256": "e2b12173a4a7d17dd545e0a6b1a38e98d55d321f6c43f00aad0d2ff88528ada9"
+        },
+        "deep_keyset": {
+          "sql": "SELECT _row_index FROM raw WHERE _row_index>=? ORDER BY _row_index LIMIT 50",
+          "parameters": [
+            3600000
+          ],
+          "plan": [
+            "SEARCH raw USING INTEGER PRIMARY KEY (rowid>?)"
+          ],
+          "first_ms": 0.051,
+          "p50_ms": 0.009,
+          "p95_ms": 0.051,
+          "rows": 50,
+          "result_sha256": "e2b12173a4a7d17dd545e0a6b1a38e98d55d321f6c43f00aad0d2ff88528ada9"
+        }
+      },
+      "public_metadata_page_ms": 12.443,
+      "deadline_100ms_result": "interrupted_as_expected",
+      "deadline_elapsed_ms": 104.87,
+      "cache_second_hit": true
+    }
+  },
+  "phase_wall_seconds": 39.346,
+  "peak_rss_mb": 117.14,
+  "total_disk_bytes": 1625162772
+}

+ 732 - 0
docs/evidence/20261118/zip-business-parity.json

@@ -0,0 +1,732 @@
+{
+  "scope": "same ingested rows + same ZIP workbooks and parser; formula/output parity, not ingest-normalization parity",
+  "checked": [
+    {
+      "sheet": "1.0-3.0_MLCC",
+      "rows": 100,
+      "equal": true
+    },
+    {
+      "sheet": "1.0-3.0_存储器",
+      "rows": 260,
+      "equal": true
+    },
+    {
+      "sheet": "4.1_MLCC",
+      "rows": 20,
+      "equal": true
+    },
+    {
+      "sheet": "4.2.1_MLCC",
+      "rows": 10,
+      "equal": true
+    },
+    {
+      "sheet": "4.2.2_MLCC",
+      "rows": 100,
+      "equal": true
+    },
+    {
+      "sheet": "4.2.3 (1-4)_MLCC",
+      "rows": 44,
+      "equal": false
+    },
+    {
+      "sheet": "4.2.3 (5)_MLCC",
+      "rows": 480,
+      "equal": true
+    },
+    {
+      "sheet": "4.3_MLCC",
+      "rows": 136,
+      "equal": true
+    },
+    {
+      "sheet": "5.1_存储器",
+      "rows": 20,
+      "equal": true
+    },
+    {
+      "sheet": "5.2.1&3&5_存储器",
+      "rows": 26,
+      "equal": true
+    },
+    {
+      "sheet": "5.2.2_存储器",
+      "rows": 60,
+      "equal": true
+    },
+    {
+      "sheet": "5.2.4_存储器",
+      "rows": 120,
+      "equal": true
+    },
+    {
+      "sheet": "5.2.6_存储器",
+      "rows": 80,
+      "equal": true
+    },
+    {
+      "sheet": "5.2.7 (1-4)_存储器",
+      "rows": 101,
+      "equal": false
+    },
+    {
+      "sheet": "5.2.7 (5)_存储器",
+      "rows": 2040,
+      "equal": true
+    },
+    {
+      "sheet": "5.3_存储器",
+      "rows": 618,
+      "equal": true
+    },
+    {
+      "sheet": "供应链条件占比",
+      "rows": 4079,
+      "equal": false
+    },
+    {
+      "sheet": "样本权重",
+      "rows": 114,
+      "equal": true
+    },
+    {
+      "sheet": "选样排除",
+      "rows": 0,
+      "equal": true
+    },
+    {
+      "sheet": "重点全量层级",
+      "rows": 160,
+      "equal": false
+    }
+  ],
+  "differences": [
+    {
+      "sheet": "4.2.3 (1-4)_MLCC",
+      "current_rows": 44,
+      "zip_rows": 44,
+      "first_differences": [
+        {
+          "row": 1,
+          "current": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "工业应用",
+            "",
+            "",
+            "",
+            "434858.10",
+            "18695479",
+            "0.023260067313600255976324543489899349463043979777143",
+            "",
+            "",
+            "",
+            "0.21696561794902941164760306927212681528635280899058",
+            "0.21092038219621710927862090869505825585644161983967",
+            "",
+            "",
+            "MLCC",
+            "10",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "工业应用",
+            "",
+            "",
+            "",
+            "434858.10",
+            "18695479",
+            "0.023260067313600255976324543489899349463043979777143",
+            "",
+            "",
+            "",
+            "0.21696561794902941164760306927212681528635280899058",
+            "0.21092038219621710927862090869505825585644161983967",
+            "",
+            "",
+            "[]",
+            "10",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        },
+        {
+          "row": 2,
+          "current": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "先进计算",
+            "",
+            "",
+            "",
+            "385175.00",
+            "16356828",
+            "0.023548269872373787876231259508261626276194871034897",
+            "",
+            "",
+            "",
+            "0.19217701565986100668554986605260761171959529603553",
+            "0.18453597328411780768642548718483074656839807462322",
+            "",
+            "",
+            "MLCC",
+            "7",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "先进计算",
+            "",
+            "",
+            "",
+            "385175.00",
+            "16356828",
+            "0.023548269872373787876231259508261626276194871034897",
+            "",
+            "",
+            "",
+            "0.19217701565986100668554986605260761171959529603553",
+            "0.18453597328411780768642548718483074656839807462322",
+            "",
+            "",
+            "[]",
+            "7",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        },
+        {
+          "row": 3,
+          "current": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "未识别",
+            "",
+            "",
+            "",
+            "381795.38",
+            "17559661",
+            "0.021742753462040070135750342788508274732638631235535",
+            "",
+            "",
+            "",
+            "0.19049080735022414173996768123191905785000412668552",
+            "0.19810620574931553887078997570467038304235903828276",
+            "",
+            "",
+            "MLCC",
+            "8",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "电容器",
+            "多层瓷介电容器(MLCC)",
+            "未识别",
+            "",
+            "",
+            "",
+            "381795.38",
+            "17559661",
+            "0.021742753462040070135750342788508274732638631235535",
+            "",
+            "",
+            "",
+            "0.19049080735022414173996768123191905785000412668552",
+            "0.19810620574931553887078997570467038304235903828276",
+            "",
+            "",
+            "[]",
+            "8",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        }
+      ]
+    },
+    {
+      "sheet": "5.2.7 (1-4)_存储器",
+      "current_rows": 101,
+      "zip_rows": 101,
+      "first_differences": [
+        {
+          "row": 1,
+          "current": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "网络通信",
+            "",
+            "",
+            "",
+            "12533182.92",
+            "8315277",
+            "1.5072477946314957397089718117628552843158441985757",
+            "",
+            "",
+            "",
+            "0.17554203369886660457508882218482650529984079449506",
+            "0.18543990846553933216694066925676220395359879370619",
+            "",
+            "",
+            "DDR",
+            "31",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "网络通信",
+            "",
+            "",
+            "",
+            "12533182.92",
+            "8315277",
+            "1.5072477946314957397089718117628552843158441985757",
+            "",
+            "",
+            "",
+            "0.17554203369886660457508882218482650529984079449506",
+            "0.18543990846553933216694066925676220395359879370619",
+            "",
+            "",
+            "[]",
+            "31",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        },
+        {
+          "row": 2,
+          "current": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "新能源",
+            "",
+            "",
+            "",
+            "12497120.02",
+            "7682034",
+            "1.6267983219027668974128466497284443156591079914512",
+            "",
+            "",
+            "",
+            "0.17503693017907541202189412496057429756313462436060",
+            "0.17131788655857898396454284051068917856692932245191",
+            "",
+            "",
+            "DDR",
+            "32",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "新能源",
+            "",
+            "",
+            "",
+            "12497120.02",
+            "7682034",
+            "1.6267983219027668974128466497284443156591079914512",
+            "",
+            "",
+            "",
+            "0.17503693017907541202189412496057429756313462436060",
+            "0.17131788655857898396454284051068917856692932245191",
+            "",
+            "",
+            "[]",
+            "32",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        },
+        {
+          "row": 3,
+          "current": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "先进计算",
+            "",
+            "",
+            "",
+            "10317149.70",
+            "6295125",
+            "1.6389110144754869839756954786441889557395603740990",
+            "",
+            "",
+            "",
+            "0.14450387039541041660085307916957587368447191409638",
+            "0.14038827615473643131881383873982492335052682024059",
+            "",
+            "",
+            "DDR",
+            "26",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "存储器",
+            "DRAM",
+            "DDR",
+            "",
+            "先进计算",
+            "",
+            "",
+            "",
+            "10317149.70",
+            "6295125",
+            "1.6389110144754869839756954786441889557395603740990",
+            "",
+            "",
+            "",
+            "0.14450387039541041660085307916957587368447191409638",
+            "0.14038827615473643131881383873982492335052682024059",
+            "",
+            "",
+            "[]",
+            "26",
+            "",
+            "已提供期间暂算;未确认全年完整",
+            "应用领域标签",
+            "",
+            "",
+            "",
+            "",
+            ""
+          ]
+        }
+      ]
+    },
+    {
+      "sheet": "供应链条件占比",
+      "current_rows": 4079,
+      "zip_rows": 4079,
+      "first_differences": [
+        {
+          "row": 1835,
+          "current": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "中国",
+            "其他",
+            "3251663.61",
+            "2130162",
+            "0.10451044638277160699936350314230515334674241868207",
+            "0.10594722071091743862578701483282576205695856420901",
+            "同年同专项同品牌国别全部记录"
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "美国",
+            "先进计算",
+            "3812050.45",
+            "2328196",
+            "0.16757120474745271127467247005133499216227053656458",
+            "0.16214079140469866463088462153723969209492989846648",
+            "同年同专项同品牌国别全部记录"
+          ]
+        },
+        {
+          "row": 1836,
+          "current": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "中国",
+            "工业应用",
+            "2451600.01",
+            "1577505",
+            "0.078795915607367311758105148612623661082803472130501",
+            "0.078459887279735444543359681016681737714625657500475",
+            "同年同专项同品牌国别全部记录"
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "韩国",
+            "先进计算",
+            "3220726.07",
+            "1851937",
+            "0.18367497909826509770515332085036033095612583754681",
+            "0.17848555253903853732474787335228955504987212115996",
+            "同年同专项同品牌国别全部记录"
+          ]
+        },
+        {
+          "row": 1837,
+          "current": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "中国",
+            "新能源",
+            "6858993.45",
+            "4116771",
+            "0.22045222174627302399666379457441031691053424452399",
+            "0.20475458944122761307774706094670121112337341729750",
+            "同年同专项同品牌国别全部记录"
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "DDR",
+            "具体港口",
+            "品牌国别条件",
+            "app",
+            "中国",
+            "其他",
+            "3251663.61",
+            "2130162",
+            "0.10451044638277160699936350314230515334674241868207",
+            "0.10594722071091743862578701483282576205695856420901",
+            "同年同专项同品牌国别全部记录"
+          ]
+        }
+      ]
+    },
+    {
+      "sheet": "重点全量层级",
+      "current_rows": 160,
+      "zip_rows": 160,
+      "first_differences": [
+        {
+          "row": 1,
+          "current": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "MLCC",
+            "工业应用",
+            "True",
+            "434858.10",
+            "18695479",
+            "0.21696561794902941164760306927212681528635280899058",
+            "0.21092038219621710927862090869505825585644161983967",
+            "MLCC",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "[]",
+            "工业应用",
+            "True",
+            "434858.10",
+            "18695479",
+            "0.21696561794902941164760306927212681528635280899058",
+            "0.21092038219621710927862090869505825585644161983967",
+            "[]",
+            ""
+          ]
+        },
+        {
+          "row": 2,
+          "current": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "MLCC",
+            "先进计算",
+            "True",
+            "385175.00",
+            "16356828",
+            "0.19217701565986100668554986605260761171959529603553",
+            "0.18453597328411780768642548718483074656839807462322",
+            "MLCC",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "[]",
+            "先进计算",
+            "True",
+            "385175.00",
+            "16356828",
+            "0.19217701565986100668554986605260761171959529603553",
+            "0.18453597328411780768642548718483074656839807462322",
+            "[]",
+            ""
+          ]
+        },
+        {
+          "row": 3,
+          "current": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "MLCC",
+            "未识别",
+            "True",
+            "381795.38",
+            "17559661",
+            "0.19049080735022414173996768123191905785000412668552",
+            "0.19810620574931553887078997570467038304235903828276",
+            "MLCC",
+            ""
+          ],
+          "zip": [
+            "I",
+            "2025",
+            "MLCC",
+            "应用领域标签",
+            "[]",
+            "未识别",
+            "True",
+            "381795.38",
+            "17559661",
+            "0.19049080735022414173996768123191905785000412668552",
+            "0.19810620574931553887078997570467038304235903828276",
+            "[]",
+            ""
+          ]
+        }
+      ]
+    }
+  ],
+  "metric_or_scope_value_differences": [],
+  "row_order_only_tables": [
+    "供应链条件占比"
+  ],
+  "comparison": "row multiset including duplicate multiplicities; only MLCC/DDR root label aliases normalized in two documented text fields",
+  "allowed_label_only_differences": [
+    "父级路径",
+    "占比分母范围"
+  ]
+}

BIN
docs/evidence/ui-regression-20261118/08-narrow-trace.jpg


BIN
docs/evidence/ui-regression-20261118/09-final-warning.jpg


+ 88 - 0
samples/ui_regression.csv

@@ -0,0 +1,88 @@
+I_E_FLAG,HS_CODE,YEAR,WEEK,MONORSUM_USD,COUNT,G_MODEL,ORIGIN_COUNTRY,TRADE_AREA_CODE,TRADE_COUNTRY,DISTINATE_PORT
+I,8532241000,2025,1,0.10,1,品牌:SAMSUNG;型号:UITEST-001;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.20,2,品牌:MICRON;型号:UITEST-002;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.30,3,品牌:TDK;型号:UITEST-003;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.40,4,品牌:MURATA;型号:UITEST-004;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.50,5,"品牌:SAMSUNG
+型号:UITEST-005
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.60,6,品牌:MICRON;型号:UITEST-006;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.70,7,品牌:ABACUS;型号:UITEST-007;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.80,8,品牌:MURATA;型号:UITEST-008;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,0.90,9,品牌:SAMSUNG;型号:UITEST-009;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.00,10,"品牌:MICRON
+型号:UITEST-010
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.10,11,品牌:MURATA、SAMSUNG;型号:UITEST-011;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.20,12,品牌:MURATA;型号:UITEST-012;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.30,13,品牌:SAMSUNG;型号:UITEST-013;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.40,14,品牌:MICRON;型号:UITEST-014;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.50,15,"品牌:TDK
+型号:UITEST-015
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.60,16,品牌:MURATA;型号:UITEST-016;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.70,17,品牌:SAMSUNG;型号:UITEST-017;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.80,18,品牌:MICRON;型号:UITEST-018;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,1.90,19,品牌:TDK;型号:UITEST-019;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.00,20,"品牌:MURATA
+型号:UITEST-020
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.10,21,品牌:SAMSUNG;型号:UITEST-021;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.20,22,品牌:MICRON;型号:UITEST-022;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.30,23,品牌:TDK;型号:UITEST-023;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.40,24,品牌:MURATA;型号:UITEST-024;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.50,25,"品牌:SAMSUNG
+型号:UITEST-025
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.60,26,品牌:MICRON;型号:UITEST-026;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.70,27,品牌:TDK;型号:UITEST-027;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.80,28,品牌:MURATA;型号:UITEST-028;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,2.90,29,品牌:SAMSUNG;型号:UITEST-029;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.00,30,"品牌:MICRON
+型号:UITEST-030
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.10,31,品牌:TDK;型号:UITEST-031;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.20,32,品牌:MURATA;型号:UITEST-032;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.30,33,品牌:SAMSUNG;型号:UITEST-033;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.40,34,品牌:MICRON;型号:UITEST-034;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.50,35,"品牌:TDK
+型号:UITEST-035
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.60,36,品牌:MURATA;型号:UITEST-036;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.70,37,品牌:SAMSUNG;型号:UITEST-037;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.80,38,品牌:MICRON;型号:UITEST-038;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,3.90,39,品牌:TDK;型号:UITEST-039;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.00,40,"品牌:MURATA
+型号:UITEST-040
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.10,41,品牌:SAMSUNG;型号:UITEST-041;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.20,42,品牌:MICRON;型号:UITEST-042;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.30,43,品牌:TDK;型号:UITEST-043;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.40,44,品牌:MURATA;型号:UITEST-044;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.50,45,"品牌:SAMSUNG
+型号:UITEST-045
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.60,46,品牌:MICRON;型号:UITEST-046;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.70,47,品牌:TDK;型号:UITEST-047;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.80,48,品牌:MURATA;型号:UITEST-048;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,4.90,49,品牌:SAMSUNG;型号:UITEST-049;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.00,50,"品牌:MICRON
+型号:UITEST-050
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.10,51,品牌:TDK;型号:UITEST-051;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.20,52,品牌:MURATA;型号:UITEST-052;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.30,53,品牌:SAMSUNG;型号:UITEST-053;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.40,54,品牌:MICRON;型号:UITEST-054;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.50,55,"品牌:TDK
+型号:UITEST-055
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.60,56,品牌:MURATA;型号:UITEST-056;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.70,57,品牌:SAMSUNG;型号:UITEST-057;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.80,58,品牌:MICRON;型号:UITEST-058;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,5.90,59,品牌:TDK;型号:UITEST-059;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,1,6.00,60,"品牌:MURATA
+型号:UITEST-060
+用途:计算机系统",JPN,KOR,JPN,JPN501
+I,85322410,2025,1,999.00,1,品牌:SAMSUNG;型号:UITEST-001;用途:计算机系统,JPN,KOR,JPN,JPN501
+I,8532241000,2025,54,999.00,1,品牌:SAMSUNG;型号:UITEST-001;用途:计算机系统,JPN,KOR,JPN,JPN501
+E,8532241000,2025,1,999.00,1,品牌:SAMSUNG;型号:UITEST-001;用途:计算机系统,JPN,KOR,JPN,JPN501

+ 14 - 0
samples/ui_regression.expected.json

@@ -0,0 +1,14 @@
+{
+  "synthetic": true,
+  "source_rows": 63,
+  "included": 60,
+  "excluded": 3,
+  "amount_usd": "183.00",
+  "quantity": "1830",
+  "unit_price": "0.10",
+  "brand_cases": [
+    "unknown brand",
+    "ambiguous multiple brands"
+  ],
+  "multiline_values": true
+}

+ 203 - 0
scripts/benchmark_queries.py

@@ -0,0 +1,203 @@
+"""Reproducible high-cardinality SQLite benchmark. Synthetic, never real-data evidence.
+
+.venv/bin/python scripts/benchmark_queries.py --rows 4000000 --pipeline-rows 100000
+4m raw CSV uses the real upload indexer; high-cardinality monthly is an explicit
+SQL fixture, not the result of classifying all 4m rows. Full pipeline is measured
+separately on --pipeline-rows unique declarations. Every phase records its scope.
+"""
+import argparse
+import csv
+import hashlib
+import json
+import math
+import os
+import platform
+import resource
+import sqlite3
+import statistics
+import sys
+import time
+from pathlib import Path
+
+ROOT=Path(__file__).resolve().parents[1]
+sys.path.insert(0,str(ROOT/'tools-service'))
+
+
+def rss_mb():
+    value=resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return round(value/(1024**2 if sys.platform=='darwin' else 1024),2)
+
+
+def disk_bytes(folder):return sum(p.stat().st_size for p in folder.rglob('*') if p.is_file())
+
+
+def timed_query(conn,sql,args=(),repeats=7):
+    timings=[];values=[]
+    for _ in range(repeats):
+        start=time.perf_counter(); values=[tuple(row) for row in conn.execute(sql,args)];timings.append((time.perf_counter()-start)*1000)
+    return dict(sql=sql,parameters=list(args),plan=[r[3] for r in conn.execute('EXPLAIN QUERY PLAN '+sql,args)],
+        first_ms=round(timings[0],3),p50_ms=round(statistics.median(timings),3),
+        p95_ms=round(sorted(timings)[math.ceil(.95*len(timings))-1],3),rows=len(values),
+        result_sha256=hashlib.sha256(json.dumps(values,default=str).encode()).hexdigest())
+
+
+def write_csv(path,rows,model_count=None):
+    model_count = model_count or max(1,rows//4)
+    with path.open('w',encoding='utf-8',newline='') as handle:
+        w=csv.writer(handle);w.writerow(['I_E_FLAG','HS_CODE','YEAR','WEEK','MONORSUM_USD','COUNT','G_MODEL','ORIGIN_COUNTRY','TRADE_AREA_CODE','TRADE_COUNTRY','DISTINATE_PORT'])
+        for i in range(rows):
+            cents=i%1000+1
+            w.writerow(['I' if i%5 else 'E',('8532241000','8542321010','8542321090','8542329010')[i%4],
+                2025+(i//52)%2,i%52+1,f'{cents//100}.{cents%100:02}',i%100+1,
+                f'品牌:{("MURATA","SAMSUNG","MICRON","SK HYNIX")[i%4]};型号:TEST-{i%model_count:08}',
+                f'X{i%197:03}',f'T{i%67:03}',f'D{i%89:03}',f'P{i%2003:04}'])
+
+
+def raw_phase(out,n):
+    from toolsvc import objects
+    from toolsvc.query_indexes import create_query_indexes
+    source=out/'raw.csv';start=time.perf_counter();write_csv(source,n);generated=time.perf_counter()-start
+    # Production importer, deliberately defer only business-index creation to obtain a baseline.
+    original=objects.create_query_indexes;objects.create_query_indexes=lambda *a,**kw:None
+    importer=objects.ObjectStore(out/'objects')
+    start=time.perf_counter();columns,count=importer._index_raw('bench',source);ingest=time.perf_counter()-start
+    objects.create_query_indexes=original
+    conn=sqlite3.connect(out/'raw.sqlite'); conn.row_factory=None
+    cases={
+        'hs_year_week_seek':('SELECT _row_index,MONORSUM_USD FROM raw WHERE HS_CODE=? AND _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50',('8532241000','2025','1',int(n*.9))),
+        'year_week_seek':('SELECT _row_index,HS_CODE FROM raw WHERE _num_YEAR=? AND _num_WEEK=? AND _row_index>? ORDER BY _row_index LIMIT 50',('2025','1',int(n*.9))),
+        'deep_offset':('SELECT _row_index FROM raw ORDER BY _row_index LIMIT 50 OFFSET ?',(int(n*.9),)),
+        'deep_keyset':('SELECT _row_index FROM raw WHERE _row_index>=? ORDER BY _row_index LIMIT 50',(int(n*.9),)),
+    }
+    before={k:timed_query(conn,*v) for k,v in cases.items()}
+    size_before=(out/'raw.sqlite').stat().st_size
+    start=time.perf_counter();indexes=create_query_indexes(conn,'raw',[r[1] for r in conn.execute('PRAGMA table_info(raw)')],raw=True);conn.execute('ANALYZE');conn.commit();index_seconds=time.perf_counter()-start
+    after={k:timed_query(conn,*v) for k,v in cases.items()}
+    assert all(before[k]['result_sha256']==after[k]['result_sha256'] for k in cases)
+    # Register the existing fixture without materializing the entire file in HTTP memory.
+    from toolsvc.objects import store,now
+    from toolsvc.db import database
+    ws=store.create_workspace('query benchmark')
+    with database.transaction() as app:
+        app.execute('INSERT INTO objects(id,workspace_id,name,kind,media_type,path,sha256,bytes,rows,columns_json,producer,parents_json,meta_json,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
+            ('bench_raw',ws['id'],'raw.csv','raw','text/csv',str(source),'sha256:synthetic-v1',source.stat().st_size,n,json.dumps(columns),'benchmark','[]',json.dumps({'sqlite_path':str(out/'raw.sqlite'),'lineage':{'rules_hash':'synthetic-query-fixture-v1','params_hash':str(n)}}),now()))
+        app.execute('INSERT INTO tables VALUES(?,?,?,?,?)',('bench_raw','raw','raw',n,json.dumps(columns)))
+    from toolsvc.readers import read_rows, QueryTimeout
+    start=time.perf_counter();page=read_rows('bench_raw',limit=50,use_cache=False);page_ms=(time.perf_counter()-start)*1000
+    assert page['total']==n and page['total_exact'] and len(page['rows'])==50
+    first=read_rows('bench_raw',limit=50);second=read_rows('bench_raw',limit=50)
+    assert second['cache_hit']
+    from toolsvc.config import settings
+    deadline_before=settings.query_timeout_ms;settings.query_timeout_ms=100
+    start=time.perf_counter()
+    try:
+        read_rows('bench_raw',aggregate={'group_by':['G_MODEL'],'metrics':[dict(column='MONORSUM_USD',fn='sum')]},limit=20,use_cache=False)
+        timeout='completed'
+    except QueryTimeout:timeout='interrupted_as_expected'
+    finally:settings.query_timeout_ms=deadline_before
+    conn.close()
+    return dict(scope='production _index_raw streaming path; excludes HTTP multipart buffering and business classification',rows=count,
+        declared_distinct_models=n//4,distinct_declarations=n//4,generate_seconds=round(generated,3),indexer_without_business_indexes_seconds=round(ingest,3),
+        business_index_seconds=round(index_seconds,3),business_indexes=indexes,sqlite_before_bytes=size_before,sqlite_after_bytes=(out/'raw.sqlite').stat().st_size,
+        before=before,after=after,public_metadata_page_ms=round(page_ms,3),deadline_100ms_result=timeout,
+        deadline_elapsed_ms=round((time.perf_counter()-start)*1000,3),cache_second_hit=second['cache_hit'])
+
+
+def pipeline_phase(out,n):
+    from toolsvc.customs import CustomsProcessRequest,CustomsOptions,load_processor
+    source=out/'pipeline.csv';write_csv(source,n,model_count=n)
+    start=time.perf_counter()
+    result=load_processor().process(CustomsProcessRequest(str(source),str(out/'pipeline'),options=CustomsOptions(directions=['I','E'],cutoff_date='2026-12-31')))
+    elapsed=time.perf_counter()-start
+    from toolsvc.objects import store
+    ws=store.create_workspace('pipeline lineage benchmark');parent=store.register_upload(ws['id'],'pipeline.csv',source.read_bytes())
+    assert parent['sha256'].removeprefix('sha256:')==result.lineage['input_sha256']
+    start=time.perf_counter();registered=store.register_processed(ws['id'],parent['id'],'result',out/'pipeline',result.to_dict());lineage=time.perf_counter()-start
+    with sqlite3.connect(out/'pipeline/working.sqlite') as verify:
+        distinct=verify.execute('SELECT COUNT(DISTINCT raw_model) FROM audit').fetchone()[0]
+    return dict(scope='full actual rules+parser+ingest+original 23 reports+2 query summaries; lineage registration separately timed',
+        rows=n,distinct_declarations=distinct,seconds=round(elapsed,3),stats=result.stats,lineage_seconds=round(lineage,3),result_rows=registered['rows'],
+        workbook_sheets=23,query_tables=2,output_bytes=disk_bytes(out/'pipeline'))
+
+
+def monthly_phase(out,n):
+    from toolsvc.customs.engine.storage import DIMENSIONS,connect
+    from toolsvc.customs.engine.query_summaries import build_query_summaries
+    from toolsvc.customs.engine.numbers import StrictSum
+    from toolsvc.query_precision import register_precision
+    db=connect(out/'monthly.sqlite')
+    db.execute('CREATE TABLE monthly('+','.join(c+' TEXT' for c in DIMENSIONS)+',amount TEXT,quantity TEXT,n INTEGER)')
+    insert='INSERT INTO monthly VALUES('+','.join('?' for _ in range(len(DIMENSIONS)+3))+')'
+    start=time.perf_counter();batch=[]
+    for i in range(n):
+        m=(i//4)%24; cents=i%1000+1; cap=i%4==0
+        values=['I' if i%5 else 'E',str(2025+m//12),f'{2025+m//12}-{m%12+1:02}',
+            '电容器' if cap else '存储器','MLCC' if cap else 'DRAM','' if cap else 'DDR','' if cap else 'DDR4',
+            ('MURATA','SAMSUNG','MICRON','SK HYNIX')[i%4],f'TEST-{i%max(1,n//4):08}', '日本' if cap else '韩国',
+            f'应用{i%9}',f'产国{i%197}',f'贸国{i%67}',f'启运{i%89}',f'港{i%2003}',f'港国{i%61}',str(int(not cap)),
+            None if i%100003==0 else f'{cents//100}.{cents%100:02}',str(i%100+1),1]
+        batch.append(values)
+        if len(batch)>=5000:db.executemany(insert,batch);batch.clear()
+    if batch:db.executemany(insert,batch)
+    db.commit();load=time.perf_counter()-start
+    cases={
+      'class_year':('SELECT c2,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND c1=? AND year=? GROUP BY c2',('I','存储器','2025')),
+      'one_model_timeline':('SELECT month,dsum(amount),dsum(quantity) FROM monthly WHERE direction=? AND brand=? AND model=? GROUP BY month',('I','SAMSUNG','TEST-00000001')),
+      'focus':('SELECT brand,dsum(amount) FROM monthly WHERE direction=? AND year=? AND c1=? AND c3=? GROUP BY brand',('I','2025','存储器','DDR')),
+    }
+    before={k:timed_query(db,*v,repeats=3) for k,v in cases.items()}
+    start=time.perf_counter()
+    for suffix,keys in [('class','direction,c1,c2,c3,c4,year'),('model','direction,brand,model,month'),('focus','direction,year,c1,c3,app,brand_country,brand')]:db.execute(f'CREATE INDEX idx_{suffix} ON monthly({keys})')
+    db.execute('ANALYZE');db.commit();index_seconds=time.perf_counter()-start
+    after={k:timed_query(db,*v,repeats=3) for k,v in cases.items()}
+    assert all(before[k]['result_sha256']==after[k]['result_sha256'] for k in cases)
+    from toolsvc.query_indexes import create_monthly_indexes
+    start=time.perf_counter();create_monthly_indexes(db);db.commit();covering_seconds=time.perf_counter()-start
+    final_focus=timed_query(db,*cases['focus'],repeats=3)
+    assert final_focus['result_sha256']==after['focus']['result_sha256']
+    target=out/'summaries';target.mkdir();sqlite3.connect(target/'stat.sqlite').close()
+    start=time.perf_counter();sheets=build_query_summaries(db,target);summary_seconds=time.perf_counter()-start
+    stat=sqlite3.connect(target/'stat.sqlite');register_precision(stat);stat.create_aggregate('dsum',1,StrictSum)
+    expected=tuple(db.execute('SELECT dsum(amount),dsum(quantity),SUM(n) FROM monthly').fetchone())
+    totals={}
+    for name in ('q_class_month','q_model_month'):
+        totals[name]=stat.execute(f'SELECT dsum("实际金额(美元)"),dsum("成交数量"),SUM(CAST("记录数" AS INTEGER)) FROM {name}').fetchone()
+        assert totals[name]==expected
+    queries={
+      'class_timeline':('SELECT "年度","月度","实际金额(美元)" FROM q_class_month WHERE "进/出口"=? AND "二级类目"=? ORDER BY "_num_年度","_num_月度",_row_index',('I','DRAM')),
+      'model_timeline':('SELECT "年度","月度","实际金额(美元)" FROM q_model_month WHERE "进/出口"=? AND "品牌"=? AND "型号"=? ORDER BY "_num_年度","_num_月度",_row_index',('I','SAMSUNG','TEST-00000001')),
+      'month_top50':('SELECT "品牌","型号","实际金额(美元)" FROM q_model_month WHERE "进/出口"=? AND "_num_年度"=? AND "_num_月度"=? AND "二级类目"=? ORDER BY "实际金额(美元)" COLLATE DECIMAL_VALUE DESC,_row_index ASC LIMIT 50',('I','2025','1','DRAM')),
+    }
+    summary_queries={k:timed_query(stat,*v) for k,v in queries.items()}
+    counts={s.sheet:s.rows for s in sheets}
+    stat.close();db.close()
+    return dict(scope='4m high-cardinality parsed monthly SQL fixture, NOT a 4m business parser/pipeline run',rows=n,
+        model_cardinality=n//4,monthly_rows=n,load_seconds=round(load,3),existing_three_index_seconds=round(index_seconds,3),
+        before=before,after=after,covering_focus=final_focus,covering_index_build_seconds=round(covering_seconds,3),query_summary_build_seconds=round(summary_seconds,3),summary_row_counts=counts,
+        summary_queries=summary_queries,exact_summary_totals=totals,missing_amount_policy='global sum is NULL due to deliberate missing members',
+        disk_bytes=disk_bytes(out))
+
+
+def main():
+    parser=argparse.ArgumentParser();parser.add_argument('--rows',type=int,default=4000000);parser.add_argument('--pipeline-rows',type=int,default=100000)
+    parser.add_argument('--out',type=Path,default=ROOT/'.run'/('bigdata-'+time.strftime('%Y%m%d-%H%M%S')))
+    parser.add_argument('--phase',choices=['all','raw','pipeline','monthly'],default='all');args=parser.parse_args()
+    args.out=args.out.resolve();args.out.mkdir(parents=True,exist_ok=True)
+    os.environ['CDA_DATA_DIR']=str(args.out/'service-data')
+    result=dict(platform=platform.platform(),python=platform.python_version(),sqlite=sqlite3.sqlite_version,os_cache='not flushed; first connection and warm repeats; not cold-cache evidence',rows=args.rows,phases={})
+    if args.phase=='all':
+        import subprocess
+        for phase in ('raw','pipeline','monthly'):
+            print('starting '+phase,flush=True)
+            subprocess.run([sys.executable,__file__,'--phase',phase,'--rows',str(args.rows),'--pipeline-rows',str(args.pipeline_rows),'--out',str(args.out/phase)],check=True)
+            result['phases'][phase]=json.loads((args.out/phase/'report.json').read_text())
+            (args.out/'report.json').write_text(json.dumps(result,ensure_ascii=False,indent=2))
+    else:
+        fn={'raw':raw_phase,'pipeline':pipeline_phase,'monthly':monthly_phase}[args.phase]
+        start=time.perf_counter();result['phases'][args.phase]=fn(args.out,args.pipeline_rows if args.phase=='pipeline' else args.rows)
+        result.update(phase_wall_seconds=round(time.perf_counter()-start,3),peak_rss_mb=rss_mb(),total_disk_bytes=disk_bytes(args.out))
+        (args.out/'report.json').write_text(json.dumps(result,ensure_ascii=False,indent=2))
+        print(json.dumps(dict(phase=args.phase,wall_seconds=result['phase_wall_seconds'],peak_rss_mb=result['peak_rss_mb']),ensure_ascii=False),flush=True)
+    print('report: '+str(args.out/'report.json'),flush=True)
+
+if __name__=='__main__':main()

+ 1 - 1
scripts/e2e.mjs

@@ -266,7 +266,7 @@ async function main() {
   const current = done;
   const statId = current?.object_id;
   const statObject = (await api(`/api/objects/${statId}`)).payload;
-  check(statObject?.tables?.length === 23, `生成 ${statObject?.tables?.length} 张结果表`, statObject?.tables?.map((t) => t.name));
+  check(statObject?.tables?.length === 25, `生成 ${statObject?.tables?.length} 张结果表`, statObject?.tables?.map((t) => t.name));
   check(statObject?.parents?.includes(uploaded.id), '结果对象血缘指向原始数据');
   check(Boolean(statObject?.meta?.lineage?.output_hash), '结果对象带输出哈希与参数哈希');
 

+ 64 - 0
scripts/upgrade_query_storage.py

@@ -0,0 +1,64 @@
+"""Dry-run by default. Raw derived indexes update in place; stat objects are copied.
+
+CDA_DATA_DIR=/absolute/data .venv/bin/python scripts/upgrade_query_storage.py --apply --summaries
+Preserves original stat files, row text/hashes, 23 workbook sheets and original business lineage.
+"""
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from pathlib import Path
+ROOT=Path(__file__).resolve().parents[1]
+sys.path.insert(0,str(ROOT/'tools-service'))
+from toolsvc.objects import store,new_id
+from toolsvc.config import settings
+from toolsvc.query_indexes import INDEX_VERSION,create_query_indexes,ensure_raw_calendar,quote
+from toolsvc.customs.engine.storage import connect,sha256_file
+from toolsvc.customs.engine.query_summaries import build_query_summaries
+
+
+def main():
+    p=argparse.ArgumentParser();p.add_argument('--apply',action='store_true');p.add_argument('--summaries',action='store_true');p.add_argument('--object-id');args=p.parse_args()
+    results=[]
+    for item in store.list_objects():
+        if args.object_id and item['id']!=args.object_id:continue
+        source=item['meta'].get('sqlite_path')
+        if not source:continue
+        if item['meta'].get('lineage',{}).get('query_index_version')==INDEX_VERSION:continue
+        entry=dict(object_id=item['id'],apply=args.apply,strategy='derived_raw_index' if item['kind']=='raw' else 'copy_new_stat_object',indexes=[],new_summaries=[])
+        if args.apply:
+            original=Path(source)
+            if item['kind']=='raw':target=original
+            else:
+                directory=settings.runs_dir/new_id('query_upgrade')
+                shutil.copytree(original.parent,directory)
+                target=directory/'stat.sqlite'
+                if original.name!='stat.sqlite':shutil.copy2(directory/original.name,target)
+            db=connect(target)
+            try:
+                for table in item['tables']:
+                    cols=[r[1] for r in db.execute(f'PRAGMA table_info({quote(table["sqlite_name"])})')]
+                    if item['kind']=='raw':
+                        ensure_raw_calendar(db,table['sqlite_name'],cols)
+                        cols=[r[1] for r in db.execute(f'PRAGMA table_info({quote(table["sqlite_name"])})')]
+                    entry['indexes']+=create_query_indexes(db,table['sqlite_name'],cols,raw=item['kind']=='raw')
+                db.execute('ANALYZE');db.commit()
+                exists=db.execute("SELECT 1 FROM sqlite_master WHERE name='q_class_month'").fetchone()
+            finally:db.close()
+            if item['kind']=='stat':
+                sheets=[dict(sheet=t['name'],table=t['sqlite_name'],rows=t['rows'],columns=t['columns']) for t in item['tables']]
+                if args.summaries and item['producer']=='customs_process' and {'1.0-3.0_MLCC','5.1_存储器'} <= {t['name'] for t in item['tables']} and (directory/'working.sqlite').exists() and not exists:
+                    working=connect(directory/'working.sqlite')
+                    try:extra=build_query_summaries(working,directory)
+                    finally:working.close()
+                    sheets += [s.__dict__ for s in extra];entry['new_summaries']=[s.sheet for s in extra]
+                lineage={**item['meta'].get('lineage',{}),'query_parent_object':item['id'],'query_index_version':INDEX_VERSION}
+                lineage['output_hash']='sha256:'+hashlib.sha256((item['sha256']+sha256_file(target)+INDEX_VERSION).encode()).hexdigest()
+                result=dict(sheets=sheets,lineage=lineage,stats=item['meta'].get('stats',{}),warnings=item['meta'].get('warnings',[]),xlsx_path=str(directory/'统计结果.xlsx') if (directory/'统计结果.xlsx').exists() else None)
+                created=store.register_processed(item['workspace_id'],item['parents'][0] if item['parents'] else item['id'],item['name']+'(查询优化)',directory,result,producer='query_index_upgrade')
+                entry['new_object_id']=created['id']
+        results.append(entry)
+    print(json.dumps(results,ensure_ascii=False,indent=2))
+
+if __name__=='__main__':main()

+ 56 - 0
scripts/verify_business_parity.py

@@ -0,0 +1,56 @@
+"""Run ZIP reports on the same ingested sample; compare original business CSVs exactly."""
+import argparse
+import csv
+from collections import Counter
+import json
+import sys
+import time
+from pathlib import Path
+
+ROOT=Path(__file__).resolve().parents[1]
+sys.path.insert(0,str(ROOT/'tools-service'))
+
+
+def main():
+    p=argparse.ArgumentParser();p.add_argument('--legacy',type=Path,required=True);p.add_argument('--out',type=Path,default=ROOT/'.run'/('parity-'+str(time.time_ns())));args=p.parse_args()
+    sys.path.insert(0,str(args.legacy.resolve()))
+    from toolsvc.customs import load_processor,CustomsProcessRequest,CustomsOptions
+    from toolsvc.customs.engine.storage import connect
+    from toolsvc.customs.engine.reports import Reports
+    from toolsvc.customs.engine.rules import Rules
+    from trade0909.reports import Reports as ZIPReports
+    out=args.out;out.mkdir(parents=True)
+    current=load_processor().process(CustomsProcessRequest(str(ROOT/'samples/small.csv'),str(out/'current'),options=CustomsOptions(cutoff_date='2026-12-31')))
+    config=json.loads((out/'current/run_config.json').read_text());stats=json.loads((out/'current/run_summary.json').read_text())
+    config['encoding']='utf-8-sig';config['delimiter']=','
+    rules=Rules(config['mapping_file'],config['field_file']);db=connect(out/'current/working.sqlite')
+    db.execute('CREATE TABLE IF NOT EXISTS fail_shapes(reason TEXT,field TEXT,shape TEXT,n INTEGER)')
+    legacy=out/'zip';legacy.mkdir()
+    ZIPReports(db,config,stats,rules,legacy).run();db.close()
+    checked=[]; differences=[]; metric_differences=[]; order_only=[]
+    for path in sorted((out/'current/精确结果CSV').glob('*.csv')):
+        # Audit wording and new engine/version metadata differ by design; compare business outputs.
+        if path.stem in ('数据质量摘要','映射冲突','周四归月映射'):continue
+        old=legacy/'精确结果CSV'/path.name
+        if not old.exists():differences.append(dict(sheet=path.stem,error='missing ZIP sheet'));continue
+        with path.open(encoding='utf-8-sig',newline='') as a,old.open(encoding='utf-8-sig',newline='') as b:
+            ar=list(csv.reader(a));br=list(csv.reader(b))
+        allowed_labels={'父级路径','占比分母范围'}
+        def canonical(rows):
+            return Counter(tuple('[]' if ar[0][i] in allowed_labels and value in ('MLCC','DDR') else value
+                                 for i,value in enumerate(row)) for row in rows)
+        equal_business = ar[0]==br[0] and canonical(ar[1:])==canonical(br[1:])
+        if not equal_business:
+            metric_differences.append(path.stem)
+        if ar!=br:
+            if Counter(map(tuple,ar[1:]))==Counter(map(tuple,br[1:])):
+                order_only.append(path.stem)
+            differences.append(dict(sheet=path.stem,current_rows=len(ar)-1,zip_rows=len(br)-1,
+                first_differences=[dict(row=i,current=x,zip=y) for i,(x,y) in enumerate(zip(ar,br)) if x!=y][:3]))
+        checked.append(dict(sheet=path.stem,rows=len(ar)-1,equal=ar==br))
+    report=dict(scope='same ingested rows + same ZIP workbooks and parser; formula/output parity, not ingest-normalization parity',checked=checked,differences=differences,metric_or_scope_value_differences=metric_differences,row_order_only_tables=order_only,comparison="row multiset including duplicate multiplicities; only MLCC/DDR root label aliases normalized in two documented text fields",allowed_label_only_differences=['父级路径','占比分母范围'])
+    (out/'report.json').write_text(json.dumps(report,ensure_ascii=False,indent=2))
+    print(json.dumps(dict(tables=len(checked),differences=len(differences),report=str(out/'report.json')),ensure_ascii=False))
+    if metric_differences:raise SystemExit(1)
+
+if __name__=='__main__':main()

+ 3 - 3
tools-service/tests/test_api.py

@@ -97,7 +97,7 @@ def test_customs_process_sync_tool(client, workspace, raw_object):
     assert response.status_code == 200, response.text
     payload = response.json()
     assert payload["object_id"].startswith("obj_")
-    assert len(payload["sheets"]) == 23
+    assert len(payload["sheets"]) == 25
     assert payload["lineage"]["output_hash"].startswith("sha256:")
     assert "统计结果.xlsx" in " ".join(payload["files"])
 
@@ -250,7 +250,7 @@ def test_customs_process_records_data_plane_ledger(client, workspace, raw_object
     assert entry["tool"] == "customs_process"
     assert raw_object["id"] in entry["object_ids"]
     assert output_object in entry["object_ids"]
-    assert entry["result"]["sheet_count"] == 23
+    assert entry["result"]["sheet_count"] == 25
 def test_preview_supports_offset(client, raw_object):
     first = client.get(f"/objects/{raw_object['id']}/preview", params={"table": "raw", "limit": 3}).json()
     second = client.get(f"/objects/{raw_object['id']}/preview", params={"table": "raw", "limit": 3, "offset": 2}).json()
@@ -289,6 +289,6 @@ def test_sheet_meta_endpoint(client, workspace, raw_object):
         json={"workspace_id": workspace["id"], "input_object_id": raw_object["id"]},
     ).json()
     meta = client.get(f"/objects/{processed['object_id']}/sheet_meta").json()
-    assert len(meta["tables"]) == 23
+    assert len(meta["tables"]) == 25
     assert meta["lineage"]["output_hash"].startswith("sha256:")
     assert meta["parents"] == [raw_object["id"]]

+ 186 - 0
tools-service/tests/test_large_query_design.py

@@ -0,0 +1,186 @@
+import json
+import sqlite3
+from decimal import Decimal
+from pathlib import Path
+
+import pytest
+from toolsvc.catalog import CLASS_SUMMARY, MODEL_SUMMARY, SPECS, describe_table
+from toolsvc.config import settings
+from toolsvc.customs.engine.numbers import StrictSum
+from toolsvc.db import database
+from toolsvc.objects import store
+from toolsvc.readers import read_rows, ReadError, QueryTimeout
+
+
+@pytest.fixture
+def raw():
+    ws=store.create_workspace('bounded query tests')
+    body='HS_CODE,YEAR,WEEK,MONORSUM,G_MODEL\n'+''.join(f'{8532241000+i%20},2025,{i%52+1},{i}.1,M{i}\n' for i in range(501))
+    return store.register_upload(ws['id'],'large.csv',body.encode())
+
+
+def test_business_indexes_and_search(raw):
+    path,table=store.table_sqlite(raw['id'],'raw')
+    with sqlite3.connect(path) as conn:
+        plan=conn.execute('EXPLAIN QUERY PLAN SELECT * FROM raw WHERE HS_CODE=? AND _num_YEAR=? AND _num_WEEK=? ORDER BY _row_index LIMIT 20',('8532241000','2025','1')).fetchall()
+        assert any('SEARCH' in r[3] and 'idx_query_' in r[3] for r in plan)
+
+
+def test_count_modes_and_filter_null_total(raw):
+    q=dict(object_id=raw['id'],filters=[dict(column='YEAR',value='2025')],limit=3)
+    auto=read_rows(**q)
+    assert auto['total'] is None and not auto['total_exact'] and auto['truncated']
+    exact=read_rows(**q,count_mode='exact')
+    assert exact['total']==501 and exact['total_exact']
+    assert read_rows(raw['id'],limit=3)['total']==501
+    assert read_rows(raw['id'],count_mode='none')['total'] is None
+
+
+def test_bound_aggregate_no_fetchall(raw):
+    q=read_rows(raw['id'],aggregate={'group_by':['G_MODEL'],'metrics':[{'fn':'sum','column':'MONORSUM'}]},limit=7)
+    assert len(q['rows'])==7 and q['truncated'] and q['truncation_reason']=='row_limit'
+    assert q['total'] is None and not q['exhausted']
+    assert q['columns']==['G_MODEL','sum_MONORSUM']
+    count=read_rows(raw['id'],aggregate={'group_by':['G_MODEL'],'metrics':[{'fn':'count'}]},limit=7,count_mode='exact')
+    assert count['total']==501
+
+
+def test_keyset_no_gaps_and_bound_to_query(raw):
+    kwargs=dict(object_id=raw['id'],limit=37,filters=[dict(column='YEAR',value='2025')])
+    seen=[];q=read_rows(**kwargs)
+    while True:
+        seen += [r['_trace']['row_index'] for r in q['rows']]
+        if not q['next_cursor']:break
+        q=read_rows(**kwargs,cursor=q['next_cursor'])
+    assert seen==list(range(501))
+    q=read_rows(raw['id'],limit=2)
+    with pytest.raises(ReadError,match='游标'):
+        read_rows(raw['id'],filters=[dict(column='YEAR',value='2026')],cursor=q['next_cursor'])
+    with pytest.raises(ReadError):read_rows(raw['id'],filters=[dict(column='YEAR',value='2025')],offset=10001)
+    assert read_rows(raw['id'],offset=10001)['rows']==[]
+
+
+@pytest.mark.parametrize('version_field',['rules_hash','params_hash','input_sha256'])
+def test_cache_version_and_independent_rows(raw,version_field):
+    q=read_rows(raw['id'],limit=2); again=read_rows(raw['id'],limit=2)
+    assert not q['cache_hit'] and again['cache_hit']
+    again['rows'][0]['values']['MONORSUM']='poison'
+    assert read_rows(raw['id'],limit=2)['rows'][0]['values']['MONORSUM']!='poison'
+    with database.transaction() as conn:
+        meta=raw['meta'];meta['lineage']={version_field:'changed-version'}
+        conn.execute('UPDATE objects SET meta_json=? WHERE id=?',(json.dumps(meta),raw['id']))
+    changed=read_rows(raw['id'],limit=2)
+    assert not changed['cache_hit'] and changed['query_version']!=q['query_version']
+
+
+def test_query_deadline(raw,monkeypatch):
+    monkeypatch.setattr(settings,'query_timeout_ms',0)
+    with pytest.raises(QueryTimeout):read_rows(raw['id'],count_mode='exact',use_cache=False)
+
+
+def test_response_byte_budget(raw,monkeypatch):
+    monkeypatch.setattr(settings,'query_max_bytes',180)
+    q=read_rows(raw['id'],limit=200,use_cache=False)
+    assert q['truncated'] and q['truncation_reason']=='byte_limit' and q['next_cursor']
+    monkeypatch.setattr(settings,'query_max_bytes',1)
+    with pytest.raises(ReadError,match='单行'):read_rows(raw['id'],use_cache=False)
+
+
+def test_invalid_aggregation_names_fail(raw):
+    for aggregate in [dict(group_by=['MISSING'],metrics=[dict(fn='count')]),
+                      dict(metrics=[dict(fn='sum',column='MONORSUM',alias='x'),dict(fn='count',alias='x')])]:
+        with pytest.raises(ReadError):read_rows(raw['id'],aggregate=aggregate)
+
+
+def test_catalog_covers_all_original_sheets(processed):
+    original=[s for s in processed['result'].sheets if s.kind!='query_summary']
+    assert len(original)==23 and all(s.sheet in SPECS for s in original)
+    for sheet in processed['result'].sheets:
+        cat=describe_table(sheet.sheet,sheet.columns)
+        assert all(cat[k] for k in ('subject','row_grain','coverage','aggregation'))
+
+
+def test_summaries_preserve_exact_total_and_missingness(processed):
+    with sqlite3.connect(processed['result'].sqlite_path) as stat, sqlite3.connect(processed['output']/'working.sqlite') as working:
+        for conn in (stat,working):conn.create_aggregate('dsum',1,StrictSum)
+        expected=working.execute('SELECT dsum(amount),dsum(quantity),COUNT(*) FROM fact').fetchone()
+        for table in ('q_class_month','q_model_month'):
+            total=stat.execute(f'SELECT dsum("实际金额(美元)"),dsum("成交数量"),SUM(CAST("记录数" AS INTEGER)) FROM {table}').fetchone()
+            assert [Decimal(x) if x is not None else None for x in total]==[Decimal(x) if x is not None else None for x in expected]
+            for row in stat.execute(f'SELECT "实际金额(美元)","成交数量","平均单价(美元/成交数量单位)" FROM {table}'):
+                if row[0] and row[1] and Decimal(row[1]): assert Decimal(row[2])==Decimal(row[0])/Decimal(row[1])
+
+
+def test_stat_semantic_guard_and_sum_summary(processed):
+    ws=store.create_workspace('summary')
+    source=store.register_upload(ws['id'],'synthetic.csv',b'x\n1\n')
+    item=store.register_processed(ws['id'],source['id'],'result',processed['output'],processed['result'].to_dict())
+    for fn,column in [('sum','价格指数'),('avg','平均单价(美元/成交数量单位)')]:
+        with pytest.raises(ReadError,match='不能'):
+            read_rows(item['id'],table='1.0-3.0_MLCC',aggregate={'metrics':[dict(fn=fn,column=column)]})
+    with pytest.raises(ReadError,match='重叠视图'):
+        read_rows(item['id'],table='1.0-3.0_存储器',aggregate={'metrics':[dict(fn='sum',column='实际金额(美元)')]})
+    q=read_rows(item['id'],table=CLASS_SUMMARY,aggregate={'metrics':[dict(fn='sum',column='实际金额(美元)')]})
+    assert len(q['rows'])==1
+    assert store.row_lineage(item['id'],MODEL_SUMMARY,0)['source_object_id']==source['id']
+
+
+def test_numeric_null_is_not_zero_and_literal_wildcards(processed):
+    from toolsvc.readers import _where
+    where,params=_where([dict(column='amount',value=0)],{'amount'},{'amount'})
+    with sqlite3.connect(':memory:') as conn:
+        from toolsvc.query_precision import register_precision
+        register_precision(conn)
+        conn.execute('CREATE TABLE t(amount TEXT,_num_amount REAL)')
+        conn.executemany('INSERT INTO t VALUES(?,?)',[('',None),('0',0)])
+        assert conn.execute('SELECT COUNT(*) FROM t WHERE '+where,params).fetchone()[0]==1
+
+
+def test_exact_financial_filter_and_order_after_float_collision():
+    from toolsvc.readers import _connect,_where
+    from toolsvc.query_precision import register_precision
+    conn=sqlite3.connect(':memory:');register_precision(conn)
+    conn.execute('CREATE TABLE t(amount TEXT,_num_amount REAL)')
+    conn.executemany('INSERT INTO t VALUES(?,?)',[(str(v),float(v)) for v in [9007199254740992,9007199254740993]])
+    for op,value,expected in [('=',9007199254740993,['9007199254740993']),('>',9007199254740992,['9007199254740993']),('!=',9007199254740992,['9007199254740993']),('in',[9007199254740993],['9007199254740993']),('not_in',[9007199254740992],['9007199254740993'])]:
+        where,params=_where([dict(column='amount',op=op,value=value)],{'amount'},{'amount'})
+        assert [r[0] for r in conn.execute('SELECT amount FROM t WHERE '+where,params)]==expected
+    assert conn.execute('SELECT amount FROM t ORDER BY amount COLLATE DECIMAL_VALUE DESC LIMIT 1').fetchone()[0]=='9007199254740993'
+    conn.close()
+
+
+def test_literal_search_does_not_expand_sql_wildcards():
+    ws=store.create_workspace('literal')
+    obj=store.register_upload(ws['id'],'l.csv',b'value\nM%1\nM_1\nM21\n')
+    result=read_rows(obj['id'],filters=[dict(column='value',op='contains',value='%')])
+    assert [r['values']['value'] for r in result['rows']]==['M%1']
+
+
+def test_service_import_order_is_independent(tmp_path):
+    import os,subprocess,sys
+    root=Path(__file__).resolve().parents[2]
+    result=subprocess.run([sys.executable,'-c','import toolsvc.query_indexes; import toolsvc.api'],cwd=root/'tools-service',env={**os.environ,'CDA_DATA_DIR':str(tmp_path/'import-data')},capture_output=True,text=True)
+    assert result.returncode==0,result.stderr
+
+
+def test_upgrade_copies_stat_and_preserves_original_bytes(processed):
+    import os,subprocess,sys,hashlib
+    ws=store.create_workspace('copy migration')
+    parent=store.register_upload(ws['id'],'marker.txt',b'x',index=False)
+    obj=store.register_processed(ws['id'],parent['id'],'old',processed['output'],processed['result'].to_dict())
+    path=Path(obj['meta']['sqlite_path']);before=hashlib.sha256(path.read_bytes()).hexdigest()
+    root=Path(__file__).resolve().parents[2]
+    run=subprocess.run([sys.executable,str(root/'scripts/upgrade_query_storage.py'),'--apply','--summaries','--object-id',obj['id']],env=os.environ,capture_output=True,text=True)
+    assert run.returncode==0,run.stderr
+    result=json.loads(run.stdout)[0];new=store.get_object(result['new_object_id'])
+    assert new['id']!=obj['id'] and new['meta']['sqlite_path']!=str(path)
+    assert hashlib.sha256(path.read_bytes()).hexdigest()==before
+    assert len(new['tables'])==25
+
+
+def test_raw_calendar_range_and_sort_keep_original_text():
+    ws=store.create_workspace('calendar')
+    obj=store.register_upload(ws['id'],'w.csv',b'YEAR,WEEK\n2025.0,10\n2025,2\n2025,1\n')
+    result=read_rows(obj['id'],filters=[dict(column='YEAR',value=2025),dict(column='WEEK',op='>=',value=2)],order_by=[dict(column='WEEK',dir='asc')])
+    assert [r['values']['WEEK'] for r in result['rows']]==['2','10']
+    assert result['rows'][1]['values']['YEAR']=='2025.0'

+ 1 - 1
tools-service/tests/test_objects.py

@@ -68,7 +68,7 @@ def test_data_read_filters_and_sorts(raw_object):
 
 
 def test_data_read_contains_filter(raw_object):
-    result = read_rows(raw_object["id"], filters=[{"column": "G_MODEL", "op": "contains", "value": "MURATA"}], limit=2)
+    result = read_rows(raw_object["id"], filters=[{"column": "G_MODEL", "op": "contains", "value": "MURATA"}], limit=2, count_mode="exact")
     assert result["total"] >= 1
     for row in result["rows"]:
         assert "MURATA" in row["values"]["G_MODEL"]

+ 1 - 1
tools-service/tests/test_pipeline.py

@@ -62,7 +62,7 @@ def test_all_template_sheets_are_present(processed):
         assert sheet in names, f"缺少模板表 {sheet}"
     for sheet in SUPPLEMENTARY_SHEETS:
         assert sheet in names, f"缺少补充表 {sheet}"
-    assert len(processed["result"].sheets) == 23
+    assert len(processed["result"].sheets) == 25
 
 
 def test_template_headers_keep_the_canonical_metric_names(stat_db):

+ 197 - 0
tools-service/tests/test_query_regressions.py

@@ -0,0 +1,197 @@
+"""Adversarial API inputs, independent Decimal oracles and pagination/cache regressions."""
+import base64
+import json
+import random
+import sqlite3
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+from decimal import Decimal
+
+import pytest
+from fastapi.testclient import TestClient
+from toolsvc.api import app
+from toolsvc.config import settings
+from toolsvc.objects import store
+from toolsvc.readers import read_rows, ReadError
+
+
+@pytest.fixture(scope='module')
+def client():
+    with TestClient(app,raise_server_exceptions=False) as c:yield c
+
+
+@pytest.fixture(scope='module')
+def rows_object():
+    ws=store.create_workspace('扩展查询回归')
+    return store.register_upload(ws['id'],'regression.csv',('YEAR,WEEK,MONORSUM,COUNT,G_MODEL\n'+''.join(f'2025,{i%52+1},{i}.01,{i+1},MODEL-{i:04}\n' for i in range(257))).encode())
+
+
+@pytest.mark.parametrize('change',[
+    {'aggregate':{'group_by':[{}],'metrics':[{'fn':'count'}]}},
+    {'aggregate':{'group_by':'YEAR','metrics':[{'fn':'count'}]}},
+    {'aggregate':{'metrics':['sum']}},
+    {'aggregate':{'metrics':{'fn':'count'}}},
+    {'aggregate':{'sum':'MONORSUM'}},
+    {'aggregate':{'group_by':[['YEAR']],'metrics':[{'fn':'count'}]}},
+    {'order_by':[{'column':{},'dir':'asc'}]},
+    {'order_by':[{'column':'YEAR','dir':'sideways'}]},
+    {'filters':[{'column':'YEAR','op':'in','value':[]}]},
+    {'filters':[{'column':'YEAR','op':'in','value':list(range(501))}]},
+    {'filters':[{'column':'YEAR','op':'between','value':[2025,2026]}]},
+    {'filters':[{'column':'YEAR','value':2025}]*33},
+    {'count_mode':'sometimes'},
+    {'offset':-1},
+    {'offset':2**80},
+    {'limit':0},
+    {'limit':-3},
+])
+def test_invalid_api_queries_return_client_error_not_500(client,rows_object,change):
+    response=client.post('/tools/data_read',json={'object_id':rows_object['id'],**change})
+    assert response.status_code in (400,422),response.text
+
+
+@pytest.mark.parametrize('cursor',['%%%','e30=',base64.urlsafe_b64encode(b'[]').decode(),'A'*5000])
+def test_bad_cursor_shapes(client,rows_object,cursor):
+    response=client.post('/tools/data_read',json={'object_id':rows_object['id'],'cursor':cursor})
+    assert response.status_code==400
+
+
+@pytest.mark.parametrize('page_size',[1,2,17,200])
+def test_all_page_boundaries_and_filtered_cursor(rows_object,page_size):
+    args=dict(object_id=rows_object['id'],filters=[{'column':'WEEK','op':'>=','value':25}],limit=page_size,use_cache=False)
+    seen=[]; result=read_rows(**args)
+    while True:
+        seen.extend(r['_trace']['row_index'] for r in result['rows'])
+        if result['next_cursor'] is None:break
+        result=read_rows(**args,cursor=result['next_cursor'])
+    expected=[i for i in range(257) if i%52+1>=25]
+    assert seen==expected and len(seen)==len(set(seen))
+    assert result['exhausted'] and not result['truncated']
+
+
+def test_byte_limited_cursor_does_not_skip_consumed_lookahead(rows_object,monkeypatch):
+    monkeypatch.setattr(settings,'query_max_bytes',360)
+    args=dict(object_id=rows_object['id'],columns=['G_MODEL'],limit=200,use_cache=False)
+    seen=[];result=read_rows(**args)
+    assert result['truncation_reason']=='byte_limit'
+    while True:
+        seen.extend(r['_trace']['row_index'] for r in result['rows'])
+        if result['next_cursor'] is None:break
+        result=read_rows(**args,cursor=result['next_cursor'])
+    assert seen==list(range(257))
+
+
+@pytest.mark.parametrize('mode',['auto','none','exact'])
+def test_empty_filtered_results_distinguish_unknown_count_from_zero(rows_object,mode):
+    q=read_rows(rows_object['id'],filters=[{'column':'G_MODEL','value':'absent'}],count_mode=mode)
+    assert q['rows']==[] and q['exhausted'] and q['next_cursor'] is None
+    assert q['total']==(0 if mode=='exact' else None)
+
+
+@pytest.mark.parametrize('seed',[7,31,197])
+def test_random_decimal_aggregates_match_independent_python_oracle(seed):
+    rng=random.Random(seed)
+    groups={str(g):[] for g in range(7)};records=[]
+    for i in range(350):
+        value=Decimal(rng.randrange(-10**18,10**18))/Decimal(1000)
+        group=str(i%7);groups[group].append(value);records.append(f'{group},{value}')
+    ws=store.create_workspace('decimal oracle')
+    obj=store.register_upload(ws['id'],'decimal.csv',('group,amount\n'+'\n'.join(records)+'\n').encode())
+    result=read_rows(obj['id'],aggregate={'group_by':['group'],'metrics':[{'fn':fn,'column':'amount','alias':fn} for fn in ('sum','min','max','avg')]},limit=20)
+    for row in result['rows']:
+        data=row['values'];values=groups[data['group']]
+        assert Decimal(data['sum'])==sum(values)
+        assert Decimal(data['min'])==min(values)
+        assert Decimal(data['max'])==max(values)
+        assert Decimal(data['avg'])==sum(values)/len(values)
+    assert not result['truncated']
+
+
+@pytest.mark.parametrize('fn',['sum','avg','min','max'])
+def test_unknown_member_propagates_for_each_exact_aggregate(fn):
+    ws=store.create_workspace('unknown')
+    obj=store.register_upload(ws['id'],'bad.csv',b'g,amount\na,1.5\na,masked-range\nb,0\n')
+    result=read_rows(obj['id'],aggregate={'group_by':['g'],'metrics':[{'fn':fn,'column':'amount','alias':'v'}]})
+    values={r['values']['g']:r['values']['v'] for r in result['rows']}
+    assert values=={'a':None,'b':'0'}
+
+
+def test_parallel_cache_reads_are_isolated(rows_object):
+    def query(_):return read_rows(rows_object['id'],limit=11)
+    with ThreadPoolExecutor(max_workers=8) as pool: results=list(pool.map(query,range(32)))
+    expected=[r['_trace']['row_hash'] for r in results[0]['rows']]
+    assert all([r['_trace']['row_hash'] for r in q['rows']]==expected for q in results)
+    results[0]['rows'][0]['values']['G_MODEL']='mutated'
+    assert read_rows(rows_object['id'],limit=11)['rows'][0]['values']['G_MODEL']=='MODEL-0000'
+
+
+def test_cache_eviction_is_bounded(rows_object,monkeypatch):
+    import toolsvc.readers as readers
+    monkeypatch.setattr(readers,'_CACHE',OrderedDict());monkeypatch.setattr(readers,'_CACHE_BYTES',0)
+    for offset in range(70):read_rows(rows_object['id'],limit=2,offset=offset)
+    assert len(readers._CACHE)<=64 and readers._CACHE_BYTES<=16*1024*1024
+    assert not read_rows(rows_object['id'],limit=2,offset=0)['cache_hit']
+
+
+def test_timeout_http_408_then_connection_recovers(client,rows_object,monkeypatch):
+    monkeypatch.setattr(settings,'query_timeout_ms',0)
+    q={'object_id':rows_object['id'],'count_mode':'exact','use_cache':False}
+    assert client.post('/tools/data_read',json=q).status_code==408
+    monkeypatch.setattr(settings,'query_timeout_ms',5000)
+    good=client.post('/tools/data_read',json=q)
+    assert good.status_code==200 and good.json()['total']==257
+
+
+def test_cache_hits_still_record_distinct_data_plane_calls(client,rows_object):
+    q={'object_id':rows_object['id'],'limit':3,'session_id':'cache-ledger-regression'}
+    first=client.post('/tools/data_read',json={**q,'call_id':'regression_read_1'}).json()
+    second=client.post('/tools/data_read',json={**q,'call_id':'regression_read_2'}).json()
+    assert second['cache_hit'] and first['rows']==second['rows']
+    calls=client.get('/ledger/calls',params={'session_id':q['session_id']}).json()['items']
+    assert {'regression_read_1','regression_read_2'} <= {c['call_id'] for c in calls}
+
+
+def test_sql_injection_is_a_literal_filter_and_cannot_change_schema(client,rows_object):
+    q={'object_id':rows_object['id'],'filters':[{'column':'G_MODEL','value':"' OR 1=1 --"}],'count_mode':'exact'}
+    result=client.post('/tools/data_read',json=q)
+    assert result.status_code==200 and result.json()['total']==0
+    q['filters']=[{'column':'G_MODEL); DROP TABLE raw;--','value':'x'}]
+    assert client.post('/tools/data_read',json=q).status_code==400
+    assert read_rows(rows_object['id'],limit=1)['total']==257
+
+
+@pytest.fixture(scope='module')
+def stat_object(processed,sample_csv):
+    ws=store.create_workspace('nonadditive policy')
+    source=store.register_upload(ws['id'],'sample.csv',sample_csv.read_bytes())
+    return store.register_processed(ws['id'],source['id'],'stat',processed['output'],processed['result'].to_dict())
+
+
+@pytest.mark.parametrize('metric',['价格指数','金额指数','数量指数','金额占比','数量占比','金额环比','数量环比','平均单价(美元/成交数量单位)'])
+@pytest.mark.parametrize('fn',['sum','avg'])
+def test_all_nonadditive_business_metrics_rejected(client,stat_object,metric,fn):
+    q={'object_id':stat_object['id'],'table':'1.0-3.0_MLCC','aggregate':{'metrics':[{'fn':fn,'column':metric}]}}
+    response=client.post('/tools/data_read',json=q)
+    assert response.status_code==400 and '不能' in response.json()['detail']
+
+
+def test_external_masked_stat_has_no_automatic_additivity(client):
+    ws=store.create_workspace('external masked')
+    obj=store.register_upload(ws['id'],'已遮掩.csv','实际金额(美元)\n100-200\n'.encode(),kind='stat')
+    response=client.post('/tools/data_read',json={'object_id':obj['id'],'aggregate':{'metrics':[{'fn':'sum','column':'实际金额(美元)'}]}})
+    assert response.status_code==400
+
+
+def test_browser_fixture_totals_are_a_fixed_oracle(tmp_path,root):
+    from toolsvc.customs import CustomsOptions,CustomsProcessRequest,load_processor
+    from toolsvc.customs.engine.numbers import StrictSum
+    expected=json.loads((root/'samples/ui_regression.expected.json').read_text())
+    result=load_processor().process(CustomsProcessRequest(str(root/'samples/ui_regression.csv'),str(tmp_path/'ui'),options=CustomsOptions(directions=['I'],cutoff_date='2026-12-31')))
+    assert [result.stats[k] for k in ('total','included','excluded')]==[63,60,3]
+    with sqlite3.connect(result.sqlite_path) as db:
+        db.create_aggregate('dsum',1,StrictSum)
+        for table in ('q_class_month','q_model_month'):
+            amount,quantity,n=db.execute(f'SELECT dsum("实际金额(美元)"),dsum("成交数量"),SUM(CAST("记录数" AS INTEGER)) FROM {table}').fetchone()
+            assert Decimal(amount)==Decimal(expected['amount_usd'])
+            assert Decimal(quantity)==Decimal(expected['quantity'])
+            assert n==expected['included']

+ 19 - 2
tools-service/toolsvc/api.py

@@ -40,7 +40,7 @@ from .customs import OPERATIONS, load_processor
 from .db import database
 from .ledger import ledger
 from .objects import store
-from .readers import ReadError, read_rows
+from .readers import QueryTimeout, ReadError, read_rows
 from .runs import build_options, runs
 
 
@@ -159,6 +159,8 @@ def preview_object(
         return store.preview(object_id, table, limit, offset)
     except KeyError as error:
         raise HTTPException(status_code=404, detail=str(error)) from error
+    except QueryTimeout as error:
+        raise HTTPException(status_code=408, detail=str(error)) from error
     except ReadError as error:
         raise HTTPException(status_code=400, detail=str(error)) from error
 
@@ -174,6 +176,8 @@ def object_row(object_id: str, table: str = "raw", row: int = Query(..., ge=0))
         return store.read_row(object_id, table, row)
     except KeyError as error:
         raise HTTPException(status_code=404, detail=str(error)) from error
+    except QueryTimeout as error:
+        raise HTTPException(status_code=408, detail=str(error)) from error
     except ReadError as error:
         raise HTTPException(status_code=400, detail=str(error)) from error
 
@@ -273,9 +277,12 @@ class DataReadRequest(BaseModel):
     columns: list[str] | None = None
     filters: list[dict] | None = None
     order_by: list[dict] | None = None
-    limit: int | None = None
+    limit: int | None = Field(default=None, gt=0)
     offset: int = 0
     aggregate: dict | None = None
+    count_mode: str = "auto"
+    cursor: str | None = None
+    use_cache: bool = True
     #: 由 BFF 传入:把本次调用登记进数据面台账,call_id 与溯源令牌一致
     call_id: str = ""
     session_id: str = ""
@@ -293,9 +300,14 @@ def tool_data_read(payload: DataReadRequest) -> dict:
             limit=payload.limit,
             offset=payload.offset,
             aggregate=payload.aggregate,
+            count_mode=payload.count_mode,
+            cursor=payload.cursor,
+            use_cache=payload.use_cache,
         )
     except KeyError as error:
         raise HTTPException(status_code=404, detail=str(error)) from error
+    except QueryTimeout as error:
+        raise HTTPException(status_code=408, detail=str(error)) from error
     except ReadError as error:
         raise HTTPException(status_code=400, detail=str(error)) from error
 
@@ -311,6 +323,11 @@ def tool_data_read(payload: DataReadRequest) -> dict:
                 "limit": payload.limit,
                 "offset": payload.offset,
                 "aggregate": payload.aggregate,
+                "columns": payload.columns,
+                "order_by": payload.order_by,
+                "count_mode": payload.count_mode,
+                "cursor": payload.cursor,
+                "query_version": result.get("query_version"),
             },
             {
                 "columns": result["columns"],

+ 78 - 0
tools-service/toolsvc/catalog.py

@@ -0,0 +1,78 @@
+"""Business table directory. Query semantics only: no classification/formula changes."""
+from __future__ import annotations
+
+CATALOG_VERSION = '2026-11-18.1'
+AMOUNT = '实际金额(美元)'
+QUANTITY = '成交数量'
+PRICE = '平均单价(美元/成交数量单位)'
+CLASS_SUMMARY = '查询_叶子类目月度'
+MODEL_SUMMARY = '查询_品牌型号月度'
+ADDITIVE = [AMOUNT, QUANTITY, '记录数']
+DEFINITIONS = {
+    AMOUNT: '纳入范围的美元金额;任一成员缺失则合计未知',
+    QUANTITY: '成交数量;只有单位可比时可累加;任一成员缺失则合计未知',
+    PRICE: '合计金额 / 合计成交数量;不能累加或简单平均各行单价',
+    '金额指数': '本期金额 / 2025-01金额 × 1000',
+    '数量指数': '本期数量 / 2025-01数量 × 1000',
+    '价格指数': '年度前100品牌型号样本的价格相对数加权;样本>=10时权重封顶10%',
+    '金额占比': '本行金额 / 占比分母范围指定金额;不能跨分母累加',
+    '数量占比': '本行数量 / 占比分母范围指定数量;不能跨分母累加',
+    '金额环比': '本月金额 / 上月金额 - 1;缺数或零分母留空',
+    '权重': '年度样本金额权重,封顶再分配;仅同一篮子可校验合计,不可跨篮子求和或平均',
+    '数量环比': '本月数量 / 上月数量 - 1;缺数或零分母留空',
+}
+# Each original report is described independently; names match the supplied ZIP.
+SPECS = {
+ '4.1_MLCC': ('电容器总览', '进出口方向×年月×电容器一级类目', '项目范围电容器全部纳入记录'),
+ '5.1_存储器': ('存储器总览', '进出口方向×年月×存储器一级类目', '项目范围存储器全部纳入记录'),
+ '1.0-3.0_MLCC': ('电容器指数', '方向×年月×电容器二级类目', '类目全部金额数量;价格指数使用年度样本'),
+ '1.0-3.0_存储器': ('存储器指数', '方向×年月×类目节点;父子层级同时存在', '类目全部金额数量;价格指数使用年度样本'),
+ '4.2.1_MLCC': ('电容器年度结构', '方向×年度×电容器二级类目', '当年已提供期间'),
+ '5.2.1&3&5_存储器': ('存储器年度结构', '方向×年度×类目节点;父子层级同时存在', '当年已提供期间'),
+ '4.2.2_MLCC': ('电容器月度结构', '方向×年月×二级类目', '类目全部纳入记录'),
+ '5.2.2_存储器': ('存储器月度结构', '方向×年月×二级类目', '类目全部纳入记录'),
+ '5.2.4_存储器': ('存储器月度结构', '方向×年月×三级类目', '类目全部纳入记录'),
+ '5.2.6_存储器': ('存储器月度结构', '方向×年月×DDR代际', '类目全部纳入记录'),
+ '4.2.3 (1-4)_MLCC': ('MLCC重点分析', '方向×年度×应用/品牌国别/品牌/型号路径节点', '年度入选路径及其他桶;父级与子级不可相加'),
+ '5.2.7 (1-4)_存储器': ('DDR重点分析', '方向×年度×应用/品牌国别/品牌/型号路径节点', '已分类DDR入选路径及其他桶;父级与子级不可相加'),
+ '4.2.3 (5)_MLCC': ('MLCC型号月度', '方向×年月×品牌型号×统计范围', '项目范围全部进口、限定入选路径是重叠视图,不可合计'),
+ '5.2.7 (5)_存储器': ('DDR型号月度', '方向×年月×品牌型号×统计范围', '已分类DDR全部、限定入选路径是重叠视图,不可合计'),
+ '4.3_MLCC': ('MLCC供应链', '方向×年度×供应链路径节点×港口粒度', '具体港口与港口国家地区为重叠视图;父子层级重复'),
+ '5.3_存储器': ('DDR供应链', '方向×年度×供应链路径节点×港口粒度', '已分类DDR;具体港口与国家地区重叠;父子层级重复'),
+ '样本权重': ('价格样本审计', '方向×基础类目×选样年度×样本品牌型号', '年度前100;不同类目样本可能重叠'),
+ '选样排除': ('价格样本审计', '方向×基础类目×选样年度×排除品牌型号', '实际值仍计入总量,排除的只是价格选样'),
+ '重点全量层级': ('重点分析审计', '方向×年度×专项×层级×父级路径×节点', '完整候选节点;父子层级不可相加'),
+ '供应链条件占比': ('供应链条件审计', '方向×年度×专项×分析方式×港口粒度×层级×父级路径×节点', '分母随分析方式和路径改变,不可跨条件合计'),
+ '周四归月映射': ('日历', '一个ISO年周', '整周按周四归月,不含业务金额'),
+ '数据质量摘要': ('质量审计', '一个运行指标或异常原因', '该运行输入、排除、识别与口径说明'),
+ '映射冲突': ('规则审计', '一个映射键的冲突', '规则库冲突,不含业务金额'),
+}
+
+
+def describe_table(name: str, columns: list[str], *, kind: str = 'stat', lineage: dict | None = None) -> dict:
+    if name in (CLASS_SUMMARY, MODEL_SUMMARY):
+        subject = '叶子类目月度总量' if name == CLASS_SUMMARY else '完整品牌型号月度总量'
+        grain = '方向×年月×叶子类目路径' + ('×品牌×型号' if name == MODEL_SUMMARY else '')
+        scope = '全部纳入记录;未识别品牌/型号保留空组;不含父级合计、TopN截断或价格样本限制'
+        additive = [c for c in ADDITIVE if c in columns]
+        partitions = []
+    elif name == 'raw':
+        subject, grain, scope = '导入文件原文', '一条导入记录', '原始申报或外部统计导入;未经验证的外部统计禁止推断可汇总性'
+        additive = list(columns) if kind == 'raw' else []
+        partitions = []
+    else:
+        subject, grain, scope = SPECS.get(name, ('自定义/外部表', '由调用方确认分组维度', '未知口径,禁止自动汇总'))
+        # Original reports are mixed views. Use summaries for additive queries.
+        additive = [c for c in ADDITIVE if c in columns] if name in SPECS else []
+        partitions = [c for c in ('进/出口', '统计层级', '层级', '统计范围', '港口统计粒度', '分析方式', '占比分母范围', '选样年度') if c in columns]
+    return dict(version=CATALOG_VERSION, subject=subject, row_grain=grain, coverage=scope,
+        hierarchy='叶子且互斥' if name in (CLASS_SUMMARY, MODEL_SUMMARY) else '见粒度与统计层级字段;原模板可能混合父子节点',
+        filter_dimensions=[c for c in columns if c not in DEFINITIONS and c not in ('记录数', '计算说明')],
+        denominator='以每行占比分母范围为准;父子/范围/港口粒度视图不能相加' if '占比分母范围' in columns else '本表不提供占比;计算前需明确可比范围和单位',
+        aggregation=dict(additive_fields=additive, required_partitions=partitions,
+            non_additive=[c for c in columns if c in DEFINITIONS and c not in ADDITIVE],
+            average_price='sum(金额)/sum(数量),缺数传播;成交数量单位须可比',
+            unknown_scope=subject in ('自定义/外部表', '导入文件原文') and not additive),
+        metric_definitions={c: DEFINITIONS[c] for c in columns if c in DEFINITIONS},
+        preferred_for='全量金额数量问答' if name in (CLASS_SUMMARY, MODEL_SUMMARY) else '按本表口径直接取值;求和前检查粒度',
+        version_binding=lineage or {})

+ 3 - 0
tools-service/toolsvc/config.py

@@ -22,6 +22,9 @@ class Settings:
     port: int = field(default_factory=lambda: int(_env("CDA_TOOLS_PORT", "8788")))
     #: data_read 单次返回行数上限
     max_rows: int = field(default_factory=lambda: int(_env("CDA_MAX_ROWS", "200")))
+    query_timeout_ms: int = field(default_factory=lambda: int(_env("CDA_QUERY_TIMEOUT_MS", "5000")))
+    query_max_offset: int = field(default_factory=lambda: int(_env("CDA_QUERY_MAX_OFFSET", "10000")))
+    query_max_bytes: int = field(default_factory=lambda: int(_env("CDA_QUERY_MAX_BYTES", "1048576")))
     #: 单文件上传上限(字节)
     max_upload_bytes: int = field(default_factory=lambda: int(_env("CDA_MAX_UPLOAD_MB", "512")) * 1024 * 1024)
     #: 台账 JSONL 是否落盘

+ 5 - 0
tools-service/toolsvc/customs/engine/excel.py

@@ -20,6 +20,8 @@ import sqlite3
 from decimal import Decimal
 from pathlib import Path
 
+from ...query_indexes import create_query_indexes
+
 from openpyxl import Workbook
 from openpyxl.cell import WriteOnlyCell
 from openpyxl.styles import Alignment, Font, PatternFill
@@ -171,6 +173,9 @@ class Output:
             entry["ws"].auto_filter.ref = f"A1:{get_column_letter(len(entry['headers']))}{entry['part_rows']}"
             entry["file"].close()
             self.db.execute("UPDATE sheet_meta SET row_count=? WHERE sheet=?", (entry["count"], entry["name"]))
+        for entry in self.sheets.values():
+            create_query_indexes(self.db, entry["table"], entry["headers"] + ['_num_' + h for h in entry['numeric']])
+        self.db.execute('ANALYZE')
         self.db.commit()
         path = self.out / "统计结果.xlsx"
         self.wb.save(path)

+ 45 - 0
tools-service/toolsvc/customs/engine/query_summaries.py

@@ -0,0 +1,45 @@
+"""Auxiliary leaf summaries. Existing 23 workbook sheets and formulas stay intact."""
+import hashlib
+import json
+import sqlite3
+from ...catalog import CLASS_SUMMARY, MODEL_SUMMARY, AMOUNT, QUANTITY, PRICE
+from ...query_indexes import create_query_indexes, quote
+from ..contract import SheetInfo
+from .numbers import number, ratio, to_text
+
+BASE_DIMS = ['direction','year','month','c1','c2','c3','c4']
+BASE_HEADERS = ['进/出口','年度','月度','一级类目','二级类目','三级类目','描述']
+
+
+def build_query_summaries(source, output_dir):
+    db=sqlite3.connect(str(output_dir/'stat.sqlite'))
+    sheets=[]
+    try:
+        for name, extras in [(CLASS_SUMMARY, []), (MODEL_SUMMARY, ['brand','model'])]:
+            dims=BASE_DIMS+extras
+            headers=BASE_HEADERS+(['品牌','型号'] if extras else [])+[AMOUNT,QUANTITY,'记录数',PRICE]
+            table='q_class_month' if not extras else 'q_model_month'
+            numeric=['年度','月度',AMOUNT,QUANTITY,'记录数',PRICE]
+            cols=['"_row_index" INTEGER PRIMARY KEY','"_row_hash" TEXT']+[quote(h)+' TEXT' for h in headers]+[quote('_num_'+h)+' REAL' for h in numeric]
+            db.execute(f'CREATE TABLE {quote(table)}({",".join(cols)})')
+            insert=f'INSERT INTO {quote(table)} VALUES({",".join("?" for _ in cols)})'
+            sql=f'SELECT {",".join(dims)},dsum(amount) amount,dsum(quantity) quantity,SUM(n) n FROM monthly GROUP BY {",".join(dims)}'
+            batch=[];count=0
+            for row in source.execute(sql):
+                amount=number(row['amount']);quantity=number(row['quantity'])
+                values=[row['direction'],row['year'],str(int(row['month'][-2:])),row['c1'],row['c2'],row['c3'],row['c4']]+[row[e] for e in extras]+[to_text(amount),to_text(quantity),str(row['n']),to_text(ratio(amount,quantity))]
+                rh='sha256:'+hashlib.sha256(json.dumps(values,ensure_ascii=False).encode()).hexdigest()
+                num=[]
+                for h in numeric:
+                    value=number(values[headers.index(h)])
+                    num.append(float(value) if value is not None else None)
+                batch.append((count,rh,*values,*num));count+=1
+                if len(batch)>=1000:
+                    db.executemany(insert,batch);batch.clear()
+            if batch:db.executemany(insert,batch)
+            create_query_indexes(db,table,headers+['_num_'+h for h in numeric])
+            sheets.append(SheetInfo(name,'query_summary',count,headers,table))
+        db.execute('ANALYZE')
+        db.commit()
+    finally:db.close()
+    return sheets

+ 12 - 12
tools-service/toolsvc/customs/engine/reports.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import csv
 import json
+import heapq
 import sqlite3
 from decimal import Decimal
 from pathlib import Path
@@ -187,18 +188,17 @@ class Reports:
 
         if self.state(year).startswith("已提供") and not self.config.get("allow_partial_year_basket", True):
             return [], "年度未确认完整;配置禁止暂算"
-        rows = list(self.store.aggregate(("brand", "model"), dict(filters, year=str(year))))
-        valid = []
-        for row in rows:
-            if not row["brand"] or not row["model"] or row["amount"] is None or row["amount"] <= 0:
-                self.output.row(
-                    "选样排除",
-                    [filters["direction"], name, year, row["brand"], row["model"], row["amount"], "品牌型号缺失或年度金额缺失/非正;实际值仍纳入"],
-                )
-            else:
-                valid.append(row)
-        valid.sort(key=lambda row: (-row["amount"], row["brand"], row["model"]))
-        selected = valid[:100]
+        def eligible():
+            for row in self.store.aggregate(("brand", "model"), dict(filters, year=str(year))):
+                if not row["brand"] or not row["model"] or row["amount"] is None or row["amount"] <= 0:
+                    self.output.row(
+                        "选样排除",
+                        [filters["direction"], name, year, row["brand"], row["model"], row["amount"], "品牌型号缺失或年度金额缺失/非正;实际值仍纳入"],
+                    )
+                else:
+                    yield row
+        # Same Decimal ordering and tie-break as sorting every candidate, O(100) heap.
+        selected = heapq.nsmallest(100, eligible(), key=lambda row: (-row["amount"], row["brand"], row["model"]))
         computed = weights([row["amount"] for row in selected])
         basket = []
         for rank, (row, weight) in enumerate(zip(selected, computed), 1):

+ 3 - 7
tools-service/toolsvc/customs/engine/storage.py

@@ -20,6 +20,7 @@ import re
 import unicodedata
 from collections import Counter
 from ...source import iter_source
+from ...query_indexes import create_monthly_indexes
 from collections.abc import Callable, Iterator
 from datetime import date
 from pathlib import Path
@@ -232,12 +233,7 @@ def ingest(config: dict, rules: Rules, out: Path, progress: Progress | None = No
         f"CREATE TABLE monthly AS SELECT {dimensions},dsum(amount) amount,dsum(quantity) quantity,count(*) n "
         f"FROM fact GROUP BY {dimensions}"
     )
-    for suffix, columns in [
-        ("class", "direction,c1,c2,c3,c4,year"),
-        ("model", "direction,brand,model,month"),
-        ("focus", "direction,year,c1,c3,app,brand_country,brand"),
-    ]:
-        database.execute(f"CREATE INDEX idx_{suffix} ON monthly({columns})")
+    create_monthly_indexes(database)
     database.commit()
     stats.update(
         recognition=dict(recognition),
@@ -265,7 +261,7 @@ class Store:
         clause = " AND ".join(f"{key}=?" for key in filters) or "1=1"
         select = (",".join(dimensions) + ",") if dimensions else ""
         group = " GROUP BY " + ",".join(dimensions) if dimensions else ""
-        query = f"SELECT {select}dsum(amount) amount,dsum(quantity) quantity,sum(n) n FROM monthly WHERE {clause}{group}"
+        query = f"SELECT {select}dsum(amount) amount,dsum(quantity) quantity,sum(n) n FROM monthly WHERE {clause}{group}" + (" ORDER BY " + ",".join(dimensions) if dimensions else "")
         for row in self.db.execute(query, list(filters.values())):
             result = dict(row)
             result["amount"] = number(row["amount"])

+ 14 - 7
tools-service/toolsvc/customs/pipeline.py

@@ -12,11 +12,12 @@ from datetime import datetime
 from pathlib import Path
 
 from .contract import CustomsProcessRequest, CustomsProcessResult, ProgressCallback, ProcessorError, SheetInfo
-from .engine.rules import Rules
-from .engine.storage import DIMENSIONS, connect, ingest
+from .engine.rules import Rules, MEMORY_HS
+from .engine.query_summaries import build_query_summaries
+from .engine.storage import sha256_file, DIMENSIONS, connect, ingest
 from .engine import reports as reports_module
 
-ENGINE_VERSION = "2.1.0"
+ENGINE_VERSION = "2.2.0"
 DEFAULT_RULES = Path(__file__).with_name("rules")
 
 
@@ -88,6 +89,8 @@ class DefaultCustomsProcessor:
                     )
                     for item in reporter.catalog
                 ]
+                report("构建查询专用叶子汇总…", 0.98)
+                sheets_written.extend(build_query_summaries(database, output_dir))
                 if stats["included"] == 0:
                     warnings.append("没有任何记录通过范围校验,结果表全部为空;请检查 HS 编码、进出口方向与年份。")
                 if stats["alerts"]:
@@ -103,14 +106,18 @@ class DefaultCustomsProcessor:
         stats["engine"] = {"name": self.name, "version": self.version}
         (output_dir / "run_summary.json").write_text(json.dumps(stats, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
 
-        output_hash = _sha256_text(
-            "|".join(f"{sheet.sheet}:{sheet.rows}" for sheet in sheets_written) + f"#{stats.get('sha256')}"
-        )
+        rules_hash = _params_hash({name: sha256_file(config[name]) for name in ("mapping_file", "field_file", "template_file")})
+        params_hash = _params_hash({"operation": request.operation, **options.to_dict()})
+        output_hash = _params_hash({"input": stats.get("sha256"), "rules": rules_hash, "params": params_hash,
+                                   "engine": self.version, "sqlite_sha256": sha256_file(output_dir / "stat.sqlite")})
         lineage = {
             "engine": {"name": self.name, "version": self.version},
             "input_sha256": stats.get("sha256"),
             "input_path": str(input_path),
-            "params_hash": _params_hash({"operation": request.operation, **options.to_dict()}),
+            "params_hash": params_hash,
+            "rules_hash": rules_hash,
+            "processing_options": options.to_dict(),
+            "hs_scope": sorted(set(rules.cap) | MEMORY_HS),
             "output_hash": output_hash,
             "started_at": datetime.now().isoformat(timespec="seconds"),
             "sheet_count": len(sheets_written),

+ 31 - 29
tools-service/toolsvc/objects.py

@@ -20,6 +20,9 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
+from .catalog import describe_table
+from .query_indexes import create_query_indexes, raw_numeric_columns, quote
+from .query_precision import number
 from .config import settings
 from .db import database
 
@@ -175,16 +178,22 @@ class ObjectStore:
             headers, rows = _iter_rows(path)
             columns = [normalize_header(header) or f"列{index + 1}" for index, header in enumerate(headers)]
             columns = _dedupe(columns)
+            if any(c in {'_row_index','_row_hash'} or c.startswith('_num_') for c in columns):
+                raise ValueError('输入表头使用了内部保留字段名')
+            calendar = raw_numeric_columns(columns)
+            calendar_positions = [columns.index(c) for c in calendar]
             quoted = ",".join(_quote(column) + " TEXT" for column in columns)
-            connection.execute(f'CREATE TABLE "raw" ("_row_index" INTEGER PRIMARY KEY,"_row_hash" TEXT,{quoted})')
-            placeholders = ",".join("?" for _ in range(len(columns) + 2))
+            shadows = ''.join(','+_quote('_num_'+c)+' REAL' for c in calendar)
+            connection.execute(f'CREATE TABLE "raw" ("_row_index" INTEGER PRIMARY KEY,"_row_hash" TEXT,{quoted}{shadows})')
+            placeholders = ",".join("?" for _ in range(len(columns) + 2 + len(calendar)))
             batch: list[tuple] = []
             count = 0
             for row in rows:
                 values = ["" if value is None else str(value) for value in row][: len(columns)]
                 values += [""] * (len(columns) - len(values))
                 row_hash = sha256_bytes(json.dumps(values, ensure_ascii=False).encode("utf-8"))
-                batch.append((count, row_hash, *values))
+                parsed_calendar = [number(values[i]) for i in calendar_positions]
+                batch.append((count, row_hash, *values, *(float(v) if v is not None else None for v in parsed_calendar)))
                 count += 1
                 if len(batch) >= 5000:
                     connection.executemany(f'INSERT INTO "raw" VALUES({placeholders})', batch)
@@ -192,6 +201,8 @@ class ObjectStore:
             if batch:
                 connection.executemany(f'INSERT INTO "raw" VALUES({placeholders})', batch)
             connection.execute('CREATE INDEX "idx_raw_row_hash" ON "raw"("_row_hash")')
+            create_query_indexes(connection, 'raw', columns + ['_num_'+c for c in calendar], raw=True)
+            connection.execute('ANALYZE')
             connection.commit()
         finally:
             connection.close()
@@ -211,9 +222,12 @@ class ObjectStore:
         item["parents"] = json.loads(item.pop("parents_json") or "[]")
         item["meta"] = json.loads(item.pop("meta_json") or "{}")
         item["tables"] = [
-            {"name": table["name"], "sqlite_name": table["sqlite_name"], "rows": table["rows"], "columns": json.loads(table["columns_json"] or "[]")}
+            {"name": table["name"], "sqlite_name": table["sqlite_name"], "rows": table["rows"], "columns": json.loads(table["columns_json"] or "[]"),
+             "catalog": describe_table(table["name"], json.loads(table["columns_json"] or "[]"), kind=item["kind"], lineage=item["meta"].get("lineage", {}))}
             for table in tables
         ]
+        for table in item["tables"]:
+            table["catalog"]["coverage_detail"] = {key: item["meta"].get("stats", {}).get(key) for key in ("min_month", "max_month", "cutoff")}
         return item
 
     def list_objects(self, workspace_id: str | None = None, kind: str | None = None) -> list[dict]:
@@ -319,38 +333,26 @@ class ObjectStore:
             return
         connection = sqlite3.connect(str(stat_db))
         connection.row_factory = sqlite3.Row
-        entries: list[tuple] = []
         try:
             for sheet in result.get("sheets", []):
                 table = sheet.get("table")
                 if not table:
                     continue
-                try:
-                    rows = connection.execute(f'SELECT * FROM "{table}"').fetchall()
-                except sqlite3.Error:
-                    continue
-                for row in rows:
-                    predicate = build_predicate(dict(row))
-                    entries.append(
-                        (
-                            object_id,
-                            sheet["sheet"],
-                            int(row["_row_index"]),
-                            str(row["_row_hash"]),
-                            input_object_id,
-                            json.dumps(predicate, ensure_ascii=False) if predicate else None,
-                        )
-                    )
+                cursor = connection.execute(f'SELECT * FROM {quote(table)}')
+                while True:
+                    rows = cursor.fetchmany(1000)
+                    if not rows:
+                        break
+                    entries = []
+                    for row in rows:
+                        predicate = build_predicate(dict(row))
+                        entries.append((object_id, sheet["sheet"], int(row["_row_index"]), str(row["_row_hash"]),
+                            input_object_id, json.dumps(predicate, ensure_ascii=False) if predicate else None))
+                    with database.transaction() as target:
+                        target.executemany(
+                            "INSERT OR REPLACE INTO row_lineage(object_id,table_name,row_index,row_hash,source_object_id,source_rows) VALUES(?,?,?,?,?,?)", entries)
         finally:
             connection.close()
-        if not entries:
-            return
-        with database.transaction() as connection:
-            connection.executemany(
-                "INSERT OR REPLACE INTO row_lineage(object_id,table_name,row_index,row_hash,source_object_id,source_rows) "
-                "VALUES(?,?,?,?,?,?)",
-                entries,
-            )
 
     def row_lineage(self, object_id: str, table: str, row_index: int) -> dict | None:
         with database.connect() as connection:

+ 88 - 0
tools-service/toolsvc/query_indexes.py

@@ -0,0 +1,88 @@
+"""Small workload-driven index portfolio; no automatic index-per-column strategy."""
+import hashlib
+import json
+from .query_precision import register_precision
+
+INDEX_VERSION = '2026-11-18.1'
+
+
+def quote(value):
+    return '"' + str(value).replace('"', '""') + '"'
+
+
+def create_query_indexes(db, table, columns, raw=False):
+    register_precision(db)
+    cols = set(columns)
+    portfolios = []
+    if raw:
+        from .customs.engine.storage import ALIASES, normalize_header
+        canonical = {}
+        lookup = {normalize_header(k).upper(): v for k, v in ALIASES.items()}
+        for col in columns:
+            key = normalize_header(col).upper()
+            canonical.setdefault(lookup.get(key, key), col)
+        # Exact HS+year+week trace, or year+week scan across HS. Raw values untouched.
+        for keys in [('HS_CODE', 'YEAR', 'WEEK'), ('YEAR', 'WEEK')]:
+            if all(k in canonical for k in keys):
+                portfolios.append([('_num_'+canonical[k]) if k in {'YEAR','WEEK'} and '_num_'+canonical[k] in cols else canonical[k] for k in keys] + ['_row_index'])
+    else:
+        # Timeline: one direction/class, chronological order. TopN: one month/scope.
+        if table == 'q_class_month':
+            candidates = [('进/出口','二级类目','年度','月度'),
+                          ('进/出口','年度','月度','二级类目','_num_实际金额(美元)')]
+        elif table == 'q_model_month':
+            candidates = [('进/出口','品牌','型号','年度','月度'),
+                          ('进/出口','年度','月度','二级类目','_num_实际金额(美元)')]
+        else:
+            candidates = [('进/出口','基础类目','年度','月度'),
+                          ('进/出口','年度','月度','统计范围','统计层级','_num_实际金额(美元)')]
+        for keys in candidates:
+            if all(k in cols for k in keys):
+                actual = ['_num_'+k if k in {'年度','月度','ISO年','ISO周','归属年','归属月','选样年度'} and '_num_'+k in cols else k for k in keys]
+                actual = ['实际金额(美元)' if k=='_num_实际金额(美元)' else k for k in actual]
+                portfolios.append(actual + ['_row_index'])
+    created=[]
+    for keys in portfolios:
+        orders = ['DESC' if k == '实际金额(美元)' else 'ASC' for k in keys]
+        suffix=hashlib.sha256(json.dumps([table,keys,orders],ensure_ascii=False).encode()).hexdigest()[:12]
+        name='idx_query_'+suffix
+        key_sql = ','.join(quote(k)+(' COLLATE DECIMAL_VALUE' if k=='实际金额(美元)' else '')+' '+order for k,order in zip(keys,orders))
+        db.execute(f'CREATE INDEX IF NOT EXISTS {quote(name)} ON {quote(table)}({key_sql})')
+        created.append(dict(name=name,columns=keys))
+    return created
+
+
+def create_monthly_indexes(db):
+    """Keep existing three paths plus one measured covering focus query (4m fixture)."""
+    indexes=[('class','direction,c1,c2,c3,c4,year'),
+             ('model','direction,brand,model,month'),
+             ('focus','direction,year,c1,c3,app,brand_country,brand'),
+             ('focus_query','direction,year,c1,c3,brand,amount,quantity,n')]
+    for suffix, columns in indexes:
+        db.execute(f'CREATE INDEX IF NOT EXISTS idx_{suffix} ON monthly({columns})')
+    db.execute('ANALYZE monthly')
+
+
+def raw_numeric_columns(columns):
+    from .customs.engine.storage import ALIASES, normalize_header
+    lookup = {normalize_header(k).upper(): v for k,v in ALIASES.items()}
+    return [c for c in columns if lookup.get(normalize_header(c).upper(),normalize_header(c).upper()) in {'YEAR','WEEK'}]
+
+
+def ensure_raw_calendar(db, table, columns):
+    """Backfill only missing derived calendar columns; keep raw text and row hashes."""
+    from .query_precision import number
+    existing={r[1] for r in db.execute(f'PRAGMA table_info({quote(table)})')}
+    new=[c for c in raw_numeric_columns(columns) if '_num_'+c not in existing]
+    if not new:return
+    for c in new:db.execute(f'ALTER TABLE {quote(table)} ADD COLUMN {quote("_num_"+c)} REAL')
+    cursor=db.execute(f'SELECT _row_index,{",".join(quote(c) for c in new)} FROM {quote(table)} ORDER BY _row_index')
+    update=f'UPDATE {quote(table)} SET '+','.join(quote('_num_'+c)+'=?' for c in new)+' WHERE _row_index=?'
+    while True:
+        rows=cursor.fetchmany(1000)
+        if not rows:break
+        batch=[]
+        for row in rows:
+            parsed=[number(v) for v in row[1:]]
+            batch.append(tuple(float(v) if v is not None else None for v in parsed)+(row[0],))
+        db.executemany(update,batch)

+ 36 - 0
tools-service/toolsvc/query_precision.py

@@ -0,0 +1,36 @@
+"""Exact text-number comparison for query filtering and indexed ordering."""
+_parse_number = None
+
+
+def number(value):
+    # Lazy import avoids objects -> index helpers -> customs -> storage cycles.
+    global _parse_number
+    if _parse_number is None:
+        from .customs.engine.numbers import number as parser
+        _parse_number = parser
+    return _parse_number(value)
+
+CALENDAR = {'YEAR','WEEK','年度','月度','ISO年','ISO周','归属年','归属月','选样年度','排名','记录数'}
+
+
+def decimal_compare(a,b):
+    left,right=number(a),number(b)
+    if left is None or right is None:return None
+    return (left>right)-(left<right)
+
+
+def decimal_collation(a,b):
+    left,right=number(a),number(b)
+    if left is None or right is None:
+        if left is None and right is None:return (a>b)-(a<b)
+        return -1 if left is None else 1
+    return (left>right)-(left<right)
+
+
+def register_precision(db):
+    db.create_function('decimal_cmp',2,decimal_compare,deterministic=True)
+    db.create_collation('DECIMAL_VALUE',decimal_collation)
+
+
+def numeric_field(column):
+    return column in {'MONORSUM','MONORSUM_USD','COUNT','amount','quantity'} or any(k in column for k in ('金额','数量','单价','价格','指数','占比','环比','权重'))

+ 246 - 205
tools-service/toolsvc/readers.py

@@ -1,259 +1,300 @@
-"""``data_read`` 的读取内核:按列/条件/排序/分页读取对象中的一张表。
-
-要点:
-* 只返回**满足条件的子集**,不返回整表;单次行数受 ``settings.max_rows`` 限制;
-* 每行携带 ``_trace``(object_id / table / row_index / row_hash),供核验层反查;
-* 过滤与排序都在 SQL 里完成,数值列用 ``_num_<列>`` 影子列,避免文本排序错误;
-* 支持 ``aggregate`` 模式直接返回分组汇总,避免把明细塞进模型上下文。
-"""
-
+"""Bounded SQLite reads with semantic checks, exact metrics, deadlines and versioned cache."""
 from __future__ import annotations
 
+import base64
+import copy
 import hashlib
 import json
 import sqlite3
+import threading
+import time
+from collections import OrderedDict
 from pathlib import Path
 
+from .catalog import CATALOG_VERSION, describe_table
 from .customs.engine.numbers import D, number, to_text
 from .config import settings
 from .objects import store
+from .query_precision import CALENDAR, numeric_field, register_precision
 
-ALLOWED_OPS = {"=", "!=", ">", ">=", "<", "<=", "contains", "startswith", "in", "not_in"}
-ALLOWED_AGGREGATES = {"sum", "avg", "count", "min", "max"}
+ALLOWED_OPS = {'=', '!=', '>', '>=', '<', '<=', 'contains', 'startswith', 'in', 'not_in'}
+ALLOWED_AGGREGATES = {'sum', 'avg', 'count', 'min', 'max'}
+CACHE_VERSION = 'query-v2-exact'
+_CACHE = OrderedDict()
+_CACHE_LOCK = threading.Lock()
+_CACHE_BYTES = 0
 
 
 class ReadError(ValueError):
-    """查询参数非法(列不存在、操作符不支持等)。"""
+    pass
 
 
-def _quote(identifier: str) -> str:
-    return '"' + str(identifier).replace('"', '""') + '"'
+class QueryTimeout(ReadError):
+    pass
 
 
-def _numeric_columns(sqlite_path: Path, table: str) -> set[str]:
-    connection = sqlite3.connect(str(sqlite_path))
-    try:
-        names = {row[1] for row in connection.execute(f'PRAGMA table_info({_quote(table)})')}
-    finally:
-        connection.close()
-    return {name[5:] for name in names if name.startswith("_num_")}
+def _quote(identifier):
+    return '"' + str(identifier).replace('"', '""') + '"'
 
 
 def _decimal_aggregate(operation):
     class Aggregate:
         def __init__(self):
             self.value, self.count, self.bad = None, 0, False
-
         def step(self, raw):
             value = number(raw)
             if value is None:
                 self.bad = True
                 return
             self.count += 1
-            if self.value is None:
-                self.value = value
-            elif operation in ('sum', 'avg'):
-                self.value += value
-            else:
-                self.value = (min if operation == 'min' else max)(self.value, value)
-
+            if self.value is None: self.value = value
+            elif operation in ('sum', 'avg'): self.value += value
+            else: self.value = (min if operation == 'min' else max)(self.value, value)
         def finalize(self):
-            if self.bad or not self.count:
-                return None
+            if self.bad or not self.count: return None
             return to_text(self.value / D(self.count) if operation == 'avg' else self.value)
     return Aggregate
 
 
-def _connect(sqlite_path: Path) -> sqlite3.Connection:
-    connection = sqlite3.connect(str(sqlite_path))
+def _connect(path):
+    connection = sqlite3.connect(f'{Path(path).resolve().as_uri()}?mode=ro', uri=True, timeout=1)
     connection.row_factory = sqlite3.Row
+    register_precision(connection)
+    connection.execute('PRAGMA temp_store=FILE')
+    connection.execute('PRAGMA cache_size=-32768')
     for operation in ('sum', 'avg', 'min', 'max'):
         connection.create_aggregate('exact_' + operation, 1, _decimal_aggregate(operation))
     return connection
 
 
-def _where(filters: list[dict], columns: set[str], numeric: set[str]) -> tuple[str, list]:
-    clauses: list[str] = []
-    params: list = []
-    for item in filters or []:
-        column = str(item.get("column") or "")
-        op = str(item.get("op") or "=").lower()
-        if column not in columns:
-            raise ReadError(f"列不存在: {column}")
-        if op not in ALLOWED_OPS:
-            raise ReadError(f"不支持的操作符: {op}")
-        value = item.get("value")
-        if op in ("contains", "startswith"):
-            clauses.append(f"CAST({_quote(column)} AS TEXT) LIKE ?")
-            params.append(("%" if op == "contains" else "") + str(value) + "%")
-            continue
-        if op in ("in", "not_in"):
-            values = value if isinstance(value, list) else [value]
-            if not values:
-                raise ReadError("in/not_in 需要非空数组")
-            placeholder = ",".join("?" for _ in values)
-            keyword = "IN" if op == "in" else "NOT IN"
-            clauses.append(f"{_quote(column)} {keyword} ({placeholder})")
-            params.extend(str(item_value) for item_value in values)
-            continue
-        target = f'_num_{column}' if column in numeric and _is_number(value) else column
-        if column in numeric and _is_number(value):
-            clauses.append(f"COALESCE({_quote(target)}, 0) {op} ?")
-            params.append(float(value))
-        else:
-            clauses.append(f"{_quote(target)} {op} ?")
-            params.append(str(value))
-    return (" AND ".join(clauses) or "1=1"), params
+def _numeric_columns(path, table):
+    with _connect(path) as conn:
+        return {row[1][5:] for row in conn.execute(f'PRAGMA table_info({_quote(table)})') if row[1].startswith('_num_')}
 
 
-def _is_number(value: object) -> bool:
-    try:
-        float(value)  # type: ignore[arg-type]
-        return True
-    except (TypeError, ValueError):
-        return False
+def _is_number(value):
+    return number(value) is not None
 
 
-def read_rows(
-    object_id: str,
-    table: str = "raw",
-    filters: list[dict] | None = None,
-    columns: list[str] | None = None,
-    order_by: list[dict] | None = None,
-    limit: int | None = None,
-    offset: int = 0,
-    aggregate: dict | None = None,
-) -> dict:
-    sqlite_path, sqlite_name = store.table_sqlite(object_id, table)
-    numeric = _numeric_columns(sqlite_path, sqlite_name)
-    connection = _connect(sqlite_path)
-    try:
-        info = [row[1] for row in connection.execute(f"PRAGMA table_info({_quote(sqlite_name)})")]
-        available = [name for name in info if not name.startswith("_")]
-        if not available:
-            raise ReadError(f"表 {table} 没有数据列")
-        selected = [column for column in (columns or available) if not column.startswith("_")]
-        unknown = [column for column in selected if column not in available]
-        if unknown:
-            raise ReadError(f"列不存在: {unknown}")
+def _where(filters, columns, numeric):
+    if len(filters or []) > 32: raise ReadError('最多32个过滤条件')
+    clauses=[]; params=[]
+    for item in filters or []:
+        column=str(item.get('column') or ''); op=str(item.get('op') or '=').lower()
+        if column not in columns: raise ReadError(f'列不存在: {column}')
+        if op not in ALLOWED_OPS: raise ReadError(f'不支持的操作符: {op}')
+        value=item.get('value')
+        if op in ('contains','startswith'):
+            # Literal search: user % and _ are not SQL wildcards.
+            text=str(value).replace('\\','\\\\').replace('%','\\%').replace('_','\\_')
+            clauses.append(f'{_quote(column)} LIKE ? ESCAPE \'\\\'')
+            params.append(('%' if op=='contains' else '')+text+'%')
+        elif op in ('in','not_in'):
+            values=value if isinstance(value,list) else [value]
+            if not values or len(values)>500: raise ReadError('in/not_in 需要1至500个值')
+            target='_num_'+column if column in numeric and all(_is_number(v) for v in values) else column
+            clauses.append(f'{_quote(target)} {"IN" if op=="in" else "NOT IN"} ({",".join("?" for _ in values)})')
+            if target!=column and column not in CALENDAR:
+                if op=='not_in':
+                    clauses.pop()
+                    clauses.append(' AND '.join(f'decimal_cmp({_quote(column)},?) != 0' for _ in values))
+                    params.extend(str(v) for v in values)
+                else:
+                    params.extend(float(v) for v in values)
+                    clauses.append('('+' OR '.join(f'decimal_cmp({_quote(column)},?) = 0' for _ in values)+')')
+                    params.extend(str(v) for v in values)
+            else:
+                params.extend(float(v) if target!=column else str(v) for v in values)
+        else:
+            target='_num_'+column if column in numeric and _is_number(value) else column
+            # NULL remains unknown. Never coerce missing numeric cells to zero.
+            if target!=column and column not in CALENDAR:
+                if op!='!=':
+                    coarse={'>' : '>=', '<' : '<='}.get(op,op)
+                    clauses.append(f'{_quote(target)} {coarse} ?');params.append(float(value))
+                clauses.append(f'decimal_cmp({_quote(column)},?) {op} 0');params.append(str(value))
+            else:
+                clauses.append(f'{_quote(target)} {op} ?')
+                params.append(float(value) if target!=column else str(value))
+    return ' AND '.join(clauses) or '1=1',params
 
-        where, params = _where(filters or [], set(available), numeric)
 
-        if aggregate:
-            return _aggregate(connection, sqlite_path, object_id, table, sqlite_name, available, numeric, where, params, aggregate)
+def _digest(value):
+    return hashlib.sha256(json.dumps(value,sort_keys=True,ensure_ascii=False,separators=(',',':')).encode()).hexdigest()
 
-        total = connection.execute(f'SELECT COUNT(*) FROM {_quote(sqlite_name)} WHERE {where}', params).fetchone()[0]
-        order_sql = ""
-        for item in order_by or []:
-            column = str(item.get("column") or "")
-            if column not in available:
-                raise ReadError(f"排序列不存在: {column}")
-            direction = "DESC" if str(item.get("dir") or item.get("direction") or "asc").lower().startswith("desc") else "ASC"
-            target = f'_num_{column}' if column in numeric else column
-            order_sql += f',{_quote(target)} {direction}'
-        if order_sql:
-            order_sql = " ORDER BY " + order_sql.lstrip(",")
-        else:
-            order_sql = ' ORDER BY "_row_index" ASC'
 
-        cap = max(1, min(int(limit or settings.max_rows), settings.max_rows))
-        offset = max(0, int(offset or 0))
-        select_sql = ",".join(_quote(column) for column in selected)
-        rows = connection.execute(
-            f'SELECT {select_sql},"_row_index","_row_hash" FROM {_quote(sqlite_name)} WHERE {where}{order_sql} LIMIT ? OFFSET ?',
-            [*params, cap, offset],
-        ).fetchall()
-        result_rows = []
-        for row in rows:
-            values = {column: row[column] for column in selected}
-            result_rows.append(
-                {
-                    "values": values,
-                    "_trace": {
-                        "object_id": object_id,
-                        "table": table,
-                        "row_index": int(row["_row_index"]),
-                        "row_hash": row["_row_hash"],
-                    },
-                }
-            )
-        return {
-            "object_id": object_id,
-            "table": table,
-            "columns": selected,
-            "rows": result_rows,
-            "total": total,
-            "offset": offset,
-            "limit": cap,
-            "exhausted": offset + len(result_rows) >= total,
-        }
-    finally:
-        connection.close()
+def _cache_get(key):
+    with _CACHE_LOCK:
+        if key not in _CACHE: return None
+        payload,size=_CACHE.pop(key);_CACHE[key]=(payload,size)
+        result=copy.deepcopy(payload);result['cache_hit']=True
+        return result
+
 
+def _cache_put(key, result):
+    global _CACHE_BYTES
+    size=len(json.dumps(result,ensure_ascii=False).encode())
+    if size>settings.query_max_bytes: return
+    with _CACHE_LOCK:
+        if key in _CACHE: _CACHE_BYTES-=_CACHE.pop(key)[1]
+        _CACHE[key]=(copy.deepcopy(result),size);_CACHE_BYTES+=size
+        while len(_CACHE)>64 or _CACHE_BYTES>16*1024*1024:
+            _CACHE_BYTES-=_CACHE.popitem(last=False)[1][1]
 
-def _aggregate(connection, sqlite_path, object_id, table, sqlite_name, available, numeric, where, params, aggregate: dict) -> dict:
-    group_by = [column for column in aggregate.get("group_by") or [] if column in available]
-    metrics = aggregate.get("metrics") or []
-    if not metrics:
-        metrics = [{"column": column, "fn": "sum", "alias": f"sum_{column}"} for column in (aggregate.get("sum") or []) if column in available]
-    if not metrics:
-        raise ReadError("aggregate 需要 metrics 或 sum")
 
-    selects: list[str] = []
-    aliases: list[str] = []
-    for column in group_by:
-        selects.append(_quote(column))
+def _validate_aggregate(catalog, group_by, metrics, filters):
+    policy=catalog['aggregation']
+    partitions=set(group_by)|{f.get('column') for f in filters or [] if f.get('op','=')=='='}
     for metric in metrics:
-        function = str(metric.get("fn") or "sum").lower()
-        if function not in ALLOWED_AGGREGATES:
-            raise ReadError(f"不支持的聚合函数: {function}")
-        column = metric.get("column")
-        if function == "count" and not column:
-            expression = "COUNT(*)"
+        fn=metric.get('fn','sum'); column=metric.get('column')
+        if fn not in ('sum','avg'): continue
+        if policy['unknown_scope']:raise ReadError('该表来源与可汇总性未确认,不能自动求和或平均;请先确认业务口径')
+        if column in policy['non_additive']:
+            raise ReadError(f'{column} 不能{fn}:请取原值,或对金额数量分别求和后重算单价;占比、增长率、加权指数按原口径计算')
+        if fn=='sum' and column not in policy['additive_fields']:
+            raise ReadError(f'{column} 未声明可累加;请核对表目录或使用查询专用汇总表')
+        missing=set(policy['required_partitions'])-partitions
+        if missing:
+            raise ReadError(f'原报表含重叠视图,聚合须固定或分组 {sorted(missing)};全量问答请使用查询_叶子类目月度或查询_品牌型号月度')
+
+
+def _compile_aggregate(aggregate, available, catalog, filters):
+    groups=aggregate.get('group_by') or []
+    if not isinstance(groups,list) or any(not isinstance(g,str) for g in groups):
+        raise ReadError('group_by 必须是字段名数组')
+    metric_input=aggregate.get('metrics')
+    sum_input=aggregate.get('sum',[])
+    if metric_input is not None and (not isinstance(metric_input,list) or any(not isinstance(m,dict) for m in metric_input)):
+        raise ReadError('metrics 必须是指标对象数组')
+    if not isinstance(sum_input,list) or any(not isinstance(c,str) for c in sum_input):
+        raise ReadError('sum 必须是字段名数组')
+    if len(groups)>12 or len(set(groups))!=len(groups) or any(g not in available for g in groups):
+        raise ReadError('group_by 含未知/重复维度或超过12个维度')
+    metrics=aggregate.get('metrics') or [dict(column=c,fn='sum',alias='sum_'+c) for c in aggregate.get('sum',[])]
+    if not metrics or len(metrics)>16: raise ReadError('aggregate 需要1至16个 metrics')
+    selects=[_quote(c) for c in groups];aliases=[]
+    for metric in metrics:
+        fn=str(metric.get('fn') or 'sum').lower();metric={**metric,'fn':fn}
+        col=metric.get('column')
+        if fn not in ALLOWED_AGGREGATES: raise ReadError(f'不支持的聚合函数: {fn}')
+        if fn=='count' and not col: expression='COUNT(*)'
         else:
-            if column not in available:
-                raise ReadError(f"聚合列不存在: {column}")
-            expression = (f"COUNT({_quote(column)})" if function == "count"
-                          else f"exact_{function}({_quote(column)})")
-        alias = str(metric.get("alias") or f"{function}_{column}")
-        aliases.append(alias)
-        selects.append(f'{expression} AS {_quote(alias)}')
-
-    group_sql = f' GROUP BY {",".join(_quote(column) for column in group_by)}' if group_by else ""
-    order_sql = ""
-    if metrics:
-        first_alias = str(metrics[0].get("alias") or f"{metrics[0].get('fn', 'sum')}_{metrics[0].get('column')}")
-        order_sql = f' ORDER BY CAST({_quote(first_alias)} AS REAL) DESC'
-
-    rows = connection.execute(
-        f'SELECT {",".join(selects)} FROM {_quote(sqlite_name)} WHERE {where}{group_sql}{order_sql}',
-        params,
-    ).fetchall()
-    result_rows = []
-    for row in rows:
-        values = dict(row)
-        signature = json.dumps(values, sort_keys=True, ensure_ascii=False, default=str)
-        result_rows.append(
-            {
-                "values": values,
-                "_trace": {
-                    "object_id": object_id,
-                    "table": table,
-                    "row_index": -1,
-                    "row_hash": "sha256:" + hashlib.sha256(signature.encode("utf-8")).hexdigest(),
-                    "aggregate": True,
-                },
-            }
-        )
-    return {
-        "object_id": object_id,
-        "table": table,
-        "columns": group_by + aliases,
-        "rows": result_rows,
-        "total": len(result_rows),
-        "offset": 0,
-        "limit": len(result_rows),
-        "exhausted": True,
-        "aggregate": True,
-        "group_by": group_by,
-    }
+            if col not in available: raise ReadError(f'聚合列不存在: {col}')
+            expression=f'COUNT({_quote(col)})' if fn=='count' else f'exact_{fn}({_quote(col)})'
+        # Generic raw numeric columns are allowed; externally imported stat tables aren't.
+        _validate_aggregate(catalog,groups,[metric],filters)
+        alias=str(metric.get('alias') or f'{fn}_{col}')
+        if alias in aliases or alias in groups or alias.startswith('_'): raise ReadError('聚合别名重复或保留')
+        aliases.append(alias);selects.append(f'{expression} AS {_quote(alias)}')
+    group_sql=' GROUP BY '+','.join(_quote(c) for c in groups) if groups else ''
+    # Tie-breaking makes exact Decimal TopN deterministic.
+    order=' ORDER BY '+_quote(aliases[0])+' COLLATE DECIMAL_VALUE DESC'+(' ,'+','.join(_quote(c) for c in groups) if groups else '')
+    return selects,groups,aliases,group_sql,order
+
+
+def read_rows(object_id, table='raw', filters=None, columns=None, order_by=None, limit=None,
+              offset=0, aggregate=None, count_mode='auto', cursor=None, use_cache=True):
+    started=time.monotonic()
+    if limit is not None and (not isinstance(limit,int) or isinstance(limit,bool) or limit<1):
+        raise ReadError('limit 必须是正整数')
+    if cursor is not None and (not isinstance(cursor,str) or len(cursor)>4096):
+        raise ReadError('游标格式或长度无效')
+    if count_mode not in ('auto','none','exact'): raise ReadError('count_mode 只支持 auto/none/exact')
+    if offset<0 or offset>2**63-1 or (offset>settings.query_max_offset and (filters or order_by or aggregate)):
+        raise ReadError('过滤/排序/聚合的OFFSET超过允许范围;请使用 next_cursor 或按行号追溯')
+    cap=max(1,min(int(limit or settings.max_rows),settings.max_rows))
+    item=store.get_object(object_id)
+    sqlite_path,sqlite_name=store.table_sqlite(object_id,table)
+    stat=sqlite_path.stat()
+    table_meta=next(t for t in item['tables'] if t['name']==table)
+    binding=dict(object=object_id,sha256=item['sha256'],lineage=item['meta'].get('lineage',{}),file=[stat.st_size,stat.st_mtime_ns],catalog=CATALOG_VERSION,reader=CACHE_VERSION)
+    shape=dict(binding=binding,table=table,filters=filters,columns=columns,order_by=order_by,aggregate=aggregate)
+    query_hash=_digest(shape)
+    cache_key=_digest([shape,cap,offset,count_mode,cursor,settings.query_timeout_ms,settings.query_max_bytes])
+    lineage=item['meta'].get('lineage',{})
+    cache_allowed=use_cache and (item['kind']=='raw' or all(lineage.get(k) for k in ('input_sha256','rules_hash','params_hash')))
+    if cache_allowed:
+        hit=_cache_get(cache_key)
+        if hit is not None:return hit
+    conn=_connect(sqlite_path)
+    deadline=started+settings.query_timeout_ms/1000
+    conn.set_progress_handler(lambda: int(time.monotonic()>deadline),1000)
+    try:
+        info=[row[1] for row in conn.execute(f'PRAGMA table_info({_quote(sqlite_name)})')]
+        available=[c for c in info if not c.startswith('_')]
+        numeric={c[5:] for c in info if c.startswith('_num_')}
+        selected=list(columns or available)
+        if not selected or any(c not in available for c in selected):raise ReadError('列不存在或不可读取')
+        where,params=_where(filters,set(available),numeric)
+        catalog=table_meta.get('catalog') or describe_table(table,available,kind=item['kind'])
+        total=None;total_exact=False;after=-1
+        if cursor:
+            if aggregate or order_by or offset:raise ReadError('游标目前仅支持自然行号顺序,且不能与OFFSET/聚合同时使用')
+            try:
+                decoded=json.loads(base64.urlsafe_b64decode(cursor))
+                if decoded['q']!=query_hash:raise ValueError()
+                after=decoded['after']
+                if not isinstance(after,int) or isinstance(after,bool) or not 0<=after<=2**63-1:raise ValueError()
+            except Exception as error:raise ReadError('游标无效或数据/规则/参数/查询条件已变化') from error
+        if aggregate:
+            selects,groups,aliases,group_sql,order_sql=_compile_aggregate(aggregate,available,catalog,filters)
+            sql=f'SELECT {",".join(selects)} FROM {_quote(sqlite_name)} WHERE {where}{group_sql}{order_sql} LIMIT ? OFFSET ?'
+            query_params=[*params,cap+1,offset]
+            selected=groups+aliases
+            if count_mode=='exact':
+                total=conn.execute(f'SELECT COUNT(*) FROM (SELECT 1 FROM {_quote(sqlite_name)} WHERE {where}{group_sql})',params).fetchone()[0];total_exact=True
+        else:
+            if count_mode=='exact':
+                total=conn.execute(f'SELECT COUNT(*) FROM {_quote(sqlite_name)} WHERE {where}',params).fetchone()[0];total_exact=True
+            elif count_mode=='auto' and not filters:
+                total=table_meta['rows'];total_exact=True  # immutable materialization metadata
+            order=[]
+            for item_order in order_by or []:
+                c=item_order.get('column')
+                if c not in available:raise ReadError(f'排序列不存在: {c}')
+                target='_num_'+c if c in numeric and not numeric_field(c) else c
+                expression=_quote(target)+(' COLLATE DECIMAL_VALUE' if numeric_field(c) else '')
+                direction=str(item_order.get('dir',item_order.get('direction','asc'))).lower()
+                if direction not in ('asc','desc'):raise ReadError('排序方向只支持asc/desc')
+                order.append(expression+(' DESC' if direction=='desc' else ' ASC'))
+            order.append('"_row_index" ASC')
+            query_params=list(params)
+            if cursor:
+                where+=' AND "_row_index">?';query_params.append(after)
+            elif not filters and not order_by and offset:
+                # Immutable tables have contiguous 0-based indices; direct seek avoids deep skip.
+                where+=' AND "_row_index">=?';query_params.append(offset);offset_sql=0
+            offset_sql=0 if cursor or (not filters and not order_by) else offset
+            sql=f'SELECT {",".join(_quote(c) for c in selected)},"_row_index","_row_hash" FROM {_quote(sqlite_name)} WHERE {where} ORDER BY {",".join(order)} LIMIT ? OFFSET ?'
+            query_params.extend([cap+1,offset_sql])
+        cur=conn.execute(sql,query_params)
+        result_rows=[];byte_count=0;truncated=False;reason=None
+        for row in cur:
+            if len(result_rows)>=cap:truncated=True;reason='row_limit';break
+            values={c:row[c] for c in selected}
+            size=len(json.dumps(values,ensure_ascii=False).encode())
+            if byte_count+size>settings.query_max_bytes:
+                if not result_rows:raise ReadError('单行超过响应字节预算,请减少 columns')
+                truncated=True;reason='byte_limit';break
+            byte_count+=size
+            trace=dict(object_id=object_id,table=table,row_index=-1 if aggregate else int(row['_row_index']),
+                row_hash='sha256:'+_digest(values) if aggregate else row['_row_hash'])
+            if aggregate:trace['aggregate']=True
+            result_rows.append(dict(values=values,_trace=trace))
+        next_cursor=None
+        if truncated and result_rows and not aggregate and not order_by:
+            next_cursor=base64.urlsafe_b64encode(json.dumps(dict(q=query_hash,after=result_rows[-1]['_trace']['row_index'])).encode()).decode()
+        result=dict(object_id=object_id,table=table,columns=selected,rows=result_rows,total=total,total_exact=total_exact,
+            offset=offset,limit=cap,exhausted=not truncated,truncated=truncated,truncation_reason=reason,next_cursor=next_cursor,
+            count_mode=count_mode,cache_hit=False,cache_enabled=cache_allowed,query_version=query_hash,
+            warning='仅返回受限子集,不能把本页相加当作全量总数;聚合仍可能扫描全部匹配行' if truncated else None)
+        if aggregate:result.update(aggregate=True,group_by=groups)
+        if time.monotonic()>deadline:raise QueryTimeout('查询超时;请缩小范围或使用叶子查询汇总,后台大导出尚未实现')
+        if cache_allowed:_cache_put(cache_key,result)
+        return result
+    except sqlite3.OperationalError as error:
+        if 'interrupt' in str(error).lower() or time.monotonic()>deadline:
+            raise QueryTimeout('查询超时,已中断;请增加筛选条件或使用查询汇总表') from error
+        raise ReadError(f'查询执行失败: {error}') from error
+    finally:
+        conn.close()

File diff suppressed because it is too large
+ 0 - 0
web/dist/assets/index-BPwH3D6I.css


File diff suppressed because it is too large
+ 0 - 0
web/dist/assets/index-DpV5XlOc.js


+ 2 - 2
web/dist/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>海关问数 Agent · 电子元器件进出口数据分析</title>
     <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='12' fill='%231f4fd1'/%3E%3Ctext x='32' y='43' font-size='30' text-anchor='middle' fill='white' font-family='sans-serif'%3E关%3C/text%3E%3C/svg%3E" />
-    <script type="module" crossorigin src="/assets/index-DlGlAdTE.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CR3nqj6D.css">
+    <script type="module" crossorigin src="/assets/index-DpV5XlOc.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BPwH3D6I.css">
   </head>
   <body>
     <div id="root"></div>

+ 14 - 5
web/src/App.tsx

@@ -6,6 +6,7 @@ import { ChatPage } from './pages/ChatPage';
 import { FilesPage } from './pages/FilesPage';
 import { ProcessPage } from './pages/ProcessPage';
 import { SystemPage } from './pages/SystemPage';
+import { WorkspaceCreateDialog } from './components/WorkspaceCreateDialog';
 
 
 type Tab = 'chat' | 'process' | 'files' | 'system';
@@ -34,6 +35,9 @@ export default function App() {
   const [toast, setToast] = useState<{ tone: 'success' | 'error' | 'info'; text: string } | null>(null);
   const [loading, setLoading] = useState(true);
   const [version, setVersion] = useState(0);
+  const [workspaceDialog,setWorkspaceDialog]=useState(false);
+  const [workspaceName,setWorkspaceName]=useState('');
+  const [creatingWorkspace,setCreatingWorkspace]=useState(false);
 
   // hash ↔ tab 双向同步(支持浏览器前进/后退)
   useEffect(() => {
@@ -75,15 +79,19 @@ export default function App() {
   }, [loadWorkspaces, showToast]);
 
   const createWorkspace = async () => {
-    const name = window.prompt('新工作区名称', `工作区 ${workspaces.length + 1}`);
-    if (!name) return;
+    const name = workspaceName.trim();
+    if (!name || creatingWorkspace) return;
+    setCreatingWorkspace(true);
     try {
-      const workspace = await api.createWorkspace(name.trim());
+      const workspace = await api.createWorkspace(name);
+      setWorkspaceDialog(false);
       setWorkspaces((current) => [workspace, ...current]);
       setWorkspaceId(workspace.id);
       showToast('success', '工作区已创建');
     } catch (error) {
       showToast('error', (error as Error).message);
+    } finally {
+      setCreatingWorkspace(false);
     }
   };
 
@@ -119,14 +127,14 @@ export default function App() {
         <div className="sidebar-section">
           <div className="sidebar-title">
             <span>工作区</span>
-            <button type="button" className="icon-button" title="新建工作区" onClick={createWorkspace}>
+            <button type="button" className="icon-button" title="新建工作区" onClick={() => {setWorkspaceName(`工作区 ${workspaces.length+1}`);setWorkspaceDialog(true);}}>
               +
             </button>
           </div>
           {loading ? (
             <Spinner label="加载中" />
           ) : workspaces.length === 0 ? (
-            <button type="button" className="ghost block" onClick={createWorkspace}>
+            <button type="button" className="ghost block" onClick={() => {setWorkspaceName(`工作区 ${workspaces.length+1}`);setWorkspaceDialog(true);}}>
               创建第一个工作区
             </button>
           ) : (
@@ -181,6 +189,7 @@ export default function App() {
         {tab === 'system' && <SystemPage />}
       </main>
 
+      <WorkspaceCreateDialog open={workspaceDialog} name={workspaceName} pending={creatingWorkspace} onNameChange={setWorkspaceName} onSubmit={()=>void createWorkspace()} onClose={()=>{if(!creatingWorkspace)setWorkspaceDialog(false);}} />
       {toast && <Toast tone={toast.tone} text={toast.text} onClose={() => setToast(null)} />}
       <span hidden data-version={version} />
     </div>

+ 2 - 0
web/src/api/types.ts

@@ -70,6 +70,8 @@ export interface ToolResultRecord {
   duration_ms?: number;
   object_ids?: string[];
   summary?: string;
+  truncated?: boolean;
+  warning?: string;
 }
 
 export interface ClaimChip {

+ 5 - 0
web/src/components/ChatMessageView.tsx

@@ -41,6 +41,10 @@ export function ChatMessageView({ message, onChipClick }: { message: ChatMessage
   );
 }
 
+export function QueryWarning({ result }: { result?: ToolResultRecord }) {
+  return result?.truncated ? <p className="hint warn" role="status">{result.warning || '仅展示部分结果,不能作为全量合计。'}</p> : null;
+}
+
 function ToolCard({ call, result }: { call: { id: string; name: string; arguments: string }; result?: ToolResultRecord }) {
   const [open, setOpen] = useState(false);
   let args: Record<string, unknown> = {};
@@ -66,6 +70,7 @@ function ToolCard({ call, result }: { call: { id: string; name: string; argument
         </span>
         <span className="tool-chevron">{open ? '−' : '+'}</span>
       </button>
+      <QueryWarning result={result} />
       {open && (
         <div className="tool-body">
           <div className="tool-section">

+ 26 - 0
web/src/components/WorkspaceCreateDialog.tsx

@@ -0,0 +1,26 @@
+import { Modal } from './Common';
+
+interface Props {
+  open: boolean;
+  name: string;
+  pending: boolean;
+  onNameChange(name: string): void;
+  onSubmit(): void;
+  onClose(): void;
+}
+
+export function WorkspaceCreateDialog({open,name,pending,onNameChange,onSubmit,onClose}: Props) {
+  return <Modal title="新建工作区" open={open} onClose={onClose} width={480}>
+    <form onSubmit={event=>{event.preventDefault();if(name.trim()&&!pending)onSubmit();}}>
+      <div className="field-grid">
+        <label style={{gridColumn:'1 / -1'}}>工作区名称
+          <input autoFocus required value={name} disabled={pending} onChange={event=>onNameChange(event.target.value)} />
+        </label>
+      </div>
+      <div className="button-row">
+        <button type="button" disabled={pending} onClick={onClose}>取消</button>
+        <button type="submit" className="primary" disabled={pending||!name.trim()}>{pending?'创建中…':'创建工作区'}</button>
+      </div>
+    </form>
+  </Modal>;
+}

+ 4 - 1
web/src/pages/ChatPage.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { api, streamChat } from '../api/client';
 import type { ChatMessage, ClaimChip, Session, ToolResultRecord, Verification, Workspace } from '../api/types';
-import { ChatMessageView, TraceChips } from '../components/ChatMessageView';
+import { ChatMessageView, TraceChips, QueryWarning } from '../components/ChatMessageView';
 import { TraceDrawer } from '../components/TraceDrawer';
 import { Spinner } from '../components/Common';
 import { relativeTime } from '../lib/format';
@@ -171,6 +171,8 @@ export function ChatPage({ workspace, onToast }: ChatPageProps) {
                             rows: data.rows,
                             duration_ms: data.duration_ms,
                             summary: data.summary,
+                            truncated: data.truncated,
+                            warning: data.warning,
                             object_ids: data.object_ids,
                           },
                         }
@@ -320,6 +322,7 @@ export function ChatPage({ workspace, onToast }: ChatPageProps) {
                               : '执行中…'}
                           </span>
                         </div>
+                        <QueryWarning result={tool.result} />
                       </div>
                     ))}
                   </div>

+ 23 - 0
web/src/styles/app.css

@@ -1703,3 +1703,26 @@ textarea:focus {
 .verification-table tr.soft-claim td {
   color: var(--text-faint);
 }
+
+/* Keep navigation and the active page reachable in a narrow embedded window. */
+@media (max-width: 720px) {
+  .app {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr);
+  }
+  .sidebar { gap: 8px; padding: 8px 10px; max-height: 210px; border-right: 0; border-bottom: 1px solid var(--border); }
+  .brand, .sidebar-foot, .nav-hint { display: none; }
+  .sidebar-section { gap: 4px; }
+  .nav { flex-direction: row; }
+  .nav-item { flex: 1; align-items: center; padding: 8px 4px; white-space: nowrap; }
+  .chat-layout { grid-template-columns: minmax(0, 1fr); grid-template-rows: auto minmax(0, 1fr); }
+  .session-list { max-height: 96px; border-right: 0; border-bottom: 1px solid var(--border); }
+  .session-head { padding: 4px 10px; }
+  .session-items { padding: 2px 6px; }
+  .chat-head { padding: 8px 10px; overflow-wrap: anywhere; }
+  .chat-head h2 { font-size: 13px; }
+  .chat-scroll { padding: 12px 10px 8px; }
+  .page { padding: 12px 10px 24px; }
+  .page-head { flex-wrap: wrap; }
+  .suggestions { grid-template-columns: minmax(0, 1fr); }
+}

+ 21 - 1
web/test/render.test.tsx

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { ChatMessageView, Markdownish, TraceChips, VerificationPanel } from '../src/components/ChatMessageView';
 import App from '../src/App';
+import { WorkspaceCreateDialog } from '../src/components/WorkspaceCreateDialog';
 import { TraceDrawer } from '../src/components/TraceDrawer';
 import { FilesPage, parseDeepLink } from '../src/pages/FilesPage';
 import type { ChatMessage } from '../src/api/types';
@@ -138,4 +139,23 @@ describe('溯源抽屉与深链', () => {
     const html = renderToStaticMarkup(<FilesPage workspace={null} onToast={() => {}} onChanged={() => {}} />);
     expect(html).toContain('请先在左侧选择一个工作区');
   });
-});
+});
+it('截断查询在工具卡片外层可见,不需要展开参数', () => {
+  const html=renderToStaticMarkup(<ChatMessageView message={message({
+    tool_calls:[{id:'bounded',name:'data_read',arguments:'{}'}],
+    tool_results:[{call_id:'bounded',tool:'data_read',ok:true,rows:5,duration_ms:2,summary:'5行',truncated:true,warning:'仅返回部分结果,不能作为全量合计'}],
+  })}/>);
+  expect(html).toContain('仅返回部分结果,不能作为全量合计');
+  expect(html).toContain('role="status"');
+});
+
+
+it('工作区创建使用应用内表单,空白名和提交中阻止重复提交', () => {
+  const render=(open:boolean,name:string,pending:boolean)=>renderToStaticMarkup(<WorkspaceCreateDialog open={open} name={name} pending={pending} onNameChange={()=>{}} onSubmit={()=>{}} onClose={()=>{}}/>);
+  expect(render(false,'test',false)).toBe('');
+  const ready=render(true,'界面回归',false);
+  expect(ready).toContain('role="dialog"');
+  expect(ready).toContain('工作区名称');
+  expect(render(true,'  ',false)).toMatch(/type="submit"[^>]*disabled/);
+  expect(render(true,'test',true)).toContain('创建中');
+});

Some files were not shown because too many files changed in this diff