# 语义配置说明

在 **配置中心**（`/admin`）页面可视化维护，也可直接编辑 `config/` 目录下的 YAML 文件。

设计参考 ChatBI 开源产品（如 SuperSonic）的语义层：**卡片接入 → 维度 → 指标 → 语义模型 → 字段关联**。

---

## 配置入口

| 页面 | 地址 | 用途 |
|------|------|------|
| Agent 管理 | `/agents` | 按语义模型管理问数 Agent，验证配置、试跑 |
| 配置中心 | `/admin` | 卡片/指标/维度/模型/关联 CRUD |
| 智能问数 | `/chat` | 自然语言提问 |

```
http://127.0.0.1:8000/agents
http://127.0.0.1:8000/admin
```

填写 API 密钥后点击「加载配置」，即可对各类配置进行增删改。

---

## 一、卡片接入（cards）

注册观远 BI 卡片，是问数系统的数据来源。

| 字段 | 说明 | 示例 |
|------|------|------|
| name | 卡片编码（唯一） | `store_detail` |
| title | 卡片名称 | `门店明细` |
| card_id | 观远 cardId | `n8fceb70ea93c4dc0a20d50a` |
| description | 描述 | 门店明细表 |
| analyzer | 分析器类型 | `store_detail` / `region_summary` / `generic` |
| category | 分类 | `门店` |
| keywords | 路由关键词 | `["开店","门店","空军"]` |
| sample_questions | 示例问题 | `["空军2026年开店情况"]` |
| enabled | 是否启用 | `true` |

保存后可点击「测试拉数」验证 cardId 是否正确。

---

## 二、维度定义（dimensions）

定义可下钻分析的维度字段，供指标和问数引用。

| 字段 | 说明 | 示例 |
|------|------|------|
| code | 维度编码（唯一） | `franchise_dept` |
| name | 维度名称 | `加盟部门` |
| description | 描述 | 空军/陆军/代理商 |
| source_cards | 来源卡片 | `["store_detail"]` |
| source_field | 观远字段名 | `加盟部门` |
| type | 维度类型 | `categorical` / `time` / `geo` / `hierarchy` |
| values | 枚举值（可选） | `["空军","陆军"]` |

---

## 三、指标定义（metrics）

定义统一指标口径，供问数和理解使用。

| 字段 | 说明 | 示例 |
|------|------|------|
| code | 指标编码（唯一） | `open_store_count` |
| name | 指标名称 | `开店数` |
| category | 指标分类 | `门店经营` |
| description | 业务口径 | 按计入有效日期统计的新开店数量 |
| formula | 计算公式 | `count(门店) where 新老店判断=新店` |
| aggregation | 聚合方式 | `count` / `sum` / `avg` |
| unit | 单位 | `家` |
| source_cards | 来源卡片 | `["store_detail"]` |
| source_fields | 来源字段 | `["计入有效日期","加盟部门"]` |
| dimensions | 可分析维度编码 | `["franchise_dept","region_big"]` |
| filters | 默认过滤 | `{"加盟部门":"空军"}` |

---

## 四、语义模型（models）

将卡片、指标、关键词组织为业务分析主题。

| 字段 | 说明 | 示例 |
|------|------|------|
| name | 模型编码（唯一） | `store_model` |
| title | 模型名称 | `门店经营模型` |
| description | 描述 | 分析开店、关店、有效店 |
| cards | 关联卡片 | `["store_detail"]` |
| keywords | 路由关键词 | `["开店","门店","空军"]` |
| metrics | 关联指标 code | `["open_store_count"]` |
| sample_questions | 示例问题 | `["空军2026年开店情况"]` |

---

## 五、字段关联（relations）

定义跨模型 / 跨卡片的字段 join 关系。

| 字段 | 说明 | 示例 |
|------|------|------|
| name | 关系名称 | `store_to_region` |
| left_model | 左模型 | `store_model` |
| right_model | 右模型 | `sales_model` |
| left_card | 左卡片 | `store_detail` |
| right_card | 右卡片 | `region_summary` |
| left_field | 左字段 | `小区` |
| right_field | 右字段 | `小区` |
| join_type | 关联类型 | `many_to_one` |

---

## 配置文件位置

```
config/cards.yaml
config/dimensions.yaml
config/metrics.yaml
config/models.yaml
config/relations.yaml
```

页面保存后会自动写入这些文件。根目录 `cards.yaml` 仅在 `config/cards.yaml` 为空时自动迁移导入。

---

## API 端点

| 资源 | GET 列表 | POST 新增/更新 | DELETE 删除 |
|------|----------|----------------|-------------|
| 卡片 | `/config/cards` | `/config/cards` | `/config/cards/{id}` |
| 维度 | `/config/dimensions` | `/config/dimensions` | `/config/dimensions/{id}` |
| 指标 | `/config/metrics` | `/config/metrics` | `/config/metrics/{id}` |
| 模型 | `/config/models` | `/config/models` | `/config/models/{id}` |
| 关联 | `/config/relations` | `/config/relations` | `/config/relations/{id}` |

全部需要 `X-API-Key` 请求头。

---

## 问数系统如何使用配置

1. 用户提问
2. 匹配 `metrics` 中的指标名称/编码
3. 在 `models` 中按关键词 / 指标 / 示例问题匹配语义模型
4. 拉取模型关联的全部卡片数据
5. 按 `relations` 执行字段 join（如 小区 关联）
6. 运行分析器（`card.analyzer`）并 **计算配置指标**（`computed_metrics`）
7. 无模型匹配时 fallback 到卡片 `keywords`

验证配置：`GET /config/validate`

---

## 运行时返回字段（/chat）

| 字段 | 说明 |
|------|------|
| `model` / `model_title` | 命中的语义模型 |
| `matched_metrics` | 路由命中的指标编码 |
| `computed_metrics` | 实际计算出的指标值 |
| `join_audit` | 字段关联执行结果 |
| `cards_used` | 实际拉取的卡片列表 |
| `query_context` | 解析出的年份/维度过滤 |

---

## 推荐配置顺序

1. **卡片接入** — 注册观远 cardId，测试拉数
2. **维度定义** — 登记可分析字段
3. **指标定义** — 定义口径并关联维度和卡片
4. **语义模型** — 组织卡片、指标、关键词
5. **字段关联** — 配置跨卡 join（进阶）