# AI 表格数据分析 SOP

> 当用户诉求涉及查询、筛选、排序、统计、Top/Bottom N、分组聚合、判断全局结论时，必须先读本文档再执行。

## 1. 查询决策树

```
用户要做什么？
│
├─ 查看/导出原始记录明细
│   → record query [--filters] [--sort] [--field-ids] [--limit]
│
├─ 按条件筛选记录（如"状态=进行中的记录"）
│   → record query --filters '{"operator":"and","operands":[...]}'
│
├─ 取 Top N / Bottom N（如"销售额最高的5条"）
│   → record query --sort '[{"fieldId":"xxx","direction":"desc"}]' --limit 5
│
├─ 全量统计（如"一共多少条"、"所有记录的总销售额"）
│   → record stats --stats '[{"fieldId":"...","statsType":"COUNT|SUM|AVG|..."}]'
│
├─ 分组统计（如"每个状态各有多少条"）
│   → record group-stats --group '[...]' --stats '[{"fieldId":"...","statsType":"count"}]'
│
├─ 条件唯一实体数（如"有索赔单的门店共有多少家"）
│   → record group-stats --filters '{...}' --stats '[{"fieldId":"<实体字段>","statsType":"distinct"}]'
│
└─ 判断全局结论（如"是否所有记录都满足条件"）
    → record stats 对反向过滤结果 COUNT；只有需要行级证据时再 record query
```

## 2. 核心规则

### 2.1 禁止基于默认分页下全局结论

`record query` 默认返回 100 条。如果返回 JSON 中 `data.nextCursor` 非空，表示还有后续数据，当前结果**不是全量**。

```json
{"data": {"nextCursor": "3hf5MtLbLZ", "records": [...]}}
```

- ❌ 错误：只查了默认 100 条就说"共 100 条记录"
- ✅ 正确：使用 `--all` 自动翻页拿全量，再统计

### 2.2 能在服务端过滤的，不要拉到本地再过滤

| 需求 | 正确做法 | 错误做法 |
|------|---------|---------|
| 筛选"状态=已完成" | `--filters '{"operator":"and","operands":[{"operator":"eq","operands":["fldXXX","已完成"]}]}'` | `--all` 拉全量再本地 filter |
| 按日期降序取最新5条 | `--sort '[...]' --limit 5` | `--all` 拉全量再本地 sort + slice |
| 模糊搜索标题含"Q1" | `--filters` 用 `contain` 操作符 | 全量拉取再本地 grep |

### 2.3 聚合必须优先在服务端完成

以下场景均有服务端聚合入口，不得先用 `record query --all` 下载全表计算：

- `record stats`：不分组的 COUNT / SUM / AVG / MAX / MIN / MEDIAN / DISTINCT / 完整率等
- `record group-stats`：分组统计，以及不带 group 的条件 DISTINCT 唯一计数
- 任意条件比率：分别聚合分子与分母，再对齐范围和 `dataVersion` 计算

只有用户要求记录明细、少量样本校验、精确分位数输入，或聚合接口明确返回不支持/错误时，才允许使用 `record query`。需要先逐行运算再聚合的指标（例如两个日期相减）必须使用表内已有且可聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能下载全表本地二次计算。

### 2.4 --all 使用注意

```bash
dws aitable record query \
  --base-id <baseId> \
  --table-id <tableId> \
  --all \
  --field-ids <只取需要的字段> \
  --format json
```

- **必须配合 `--field-ids`** 限制返回字段，减少数据量
- 对于大表（>1000条），先告知用户可能耗时
- `--all` 会自动处理分页，无需手动翻页

## 3. filters 快速参考

详细语法见 [aitable-filter-sort.md](./aitable-filter-sort.md)。

### 常用操作符速查

| 操作符 | 适用类型 | 含义 | 示例 operands |
|--------|---------|------|-------------|
| `eq` | 通用 | 等于 | `["fldXXX", "值"]` |
| `ne` | 通用 | 不等于 | `["fldXXX", "值"]` |
| `gt` / `lt` | 数值/日期 | 大于/小于 | `["fldXXX", "25"]` |
| `gte` / `lte` | 数值/日期 | 大于等于/小于等于 | `["fldXXX", "100"]` |
| `contain` | 文本 | 包含 | `["fldXXX", "关键词"]` |
| `exist` / `un_exist` | 通用 | 有值/为空 | `["fldXXX"]`（无第二参数） |
| `any_of` | 多选 | 包含任一 | `["fldXXX", "选项A"]` |

### filters 结构模板

```json
{
  "operator": "and",
  "operands": [
    {"operator": "eq", "operands": ["<fieldId>", "<值>"]},
    {"operator": "gt", "operands": ["<fieldId>", "<数值>"]}
  ]
}
```

## 4. 分析结果呈现规范

### 4.1 必须包含的信息

- **数据范围**：基于哪个表、哪些筛选条件、查询了多少条记录
- **计算方法**：用了什么聚合方式（sum/count/avg 等）
- **结果值**：精确到合理小数位

### 4.2 示例

> 基于「销售数据」表，筛选条件：日期 ≥ 2026-01-01，共查询到 342 条记录。
> - 总销售额：¥1,234,567.89（SUM）
> - 平均单价：¥3,610.46（AVG）
> - 最大单笔：¥89,000.00（MAX）

## 5. 任务选路心智模型

| 用户诉求 | 优先方案 | 不要误走 |
|---------|---------|---------|
| 一次性标量统计 | `record stats` | 不要 `record query --all` 后本地聚合 |
| 分组/去重统计 | `record group-stats` | 不要下载全表 groupby / 去重 |
| 长期展示派生指标 | 创建 formula 字段（见 [formula-guide](./aitable-formula-guide.md)） | 不要每次手算再手动写入 |
| 按条件筛选记录 | `record query --filters` | 不要 `--all` 拉全量再本地 filter |
| 取最新/最大/前N | `--sort + --limit` | 不要 `--all` 再本地排序取前N |
| 关键词检索 | `record query --filters` 用 `contain` | 不要把表格当搜索引擎全文检索 |
| 验证"是否全部满足" | 反向 filters（筛不满足的），看是否有结果 | 不要 `--all` 逐条遍历 |