# 02 · 总体架构与项目结构

## 1. 架构分层

```
┌─────────────────────────────────────────────────┐
│ Controller 层：QueryController（REST API）       │
│   POST /api/query  →  自然语言问题                │
├─────────────────────────────────────────────────┤
│ Service 层：MetricQueryService（编排）           │
│   槽位提取 → 本体推理 → SQL 生成 → 校验 → 查询 → 归因│
├──────────────┬──────────────┬───────────────────┤
│ ontology 模块 │  sql 模块    │   llm 模块         │
│ 本体加载+推理  │ 模板+DSL生成 │  DeepSeek 调用     │
│ (Jena)       │ +口径校验    │  槽位提取+归因      │
├──────────────┴──────────────┴───────────────────┤
│ query 模块：MaxComputeQueryService（复用已有）    │
└─────────────────────────────────────────────────┘
         ↓
   数据层：现有 MaxCompute 账单表 + 维度表
```

**数据流（一次查询）**：
```
问题 → [llm] 槽位提取 → [ontology] 等价识别/维度展开 → [sql] 模板+参数 → [sql] 口径校验
     → [query] MaxCompute 执行 → [llm] 归因分析 → 响应
```

## 2. Maven 项目结构（单模块 + 分层 package）

```
metric-ontology-query/
├── pom.xml
└── src/main/
    ├── java/com/example/metric/
    │   ├── MetricQueryApplication.java          # 启动类
    │   ├── controller/
    │   │   └── QueryController.java             # REST API
    │   ├── service/
    │   │   └── MetricQueryService.java          # 编排核心
    │   ├── ontology/
    │   │   ├── OntologyService.java             # 本体加载 + 推理
    │   │   └── OntologyProperties.java          # 本体/配置路径
    │   ├── sql/
    │   │   ├── SqlGenerator.java                # SQL 生成（模板+DSL）
    │   │   ├── CaliberValidator.java            # 口径校验
    │   │   └── MetricDefinition.java            # 指标定义模型
    │   ├── llm/
    │   │   ├── LlmService.java                  # DeepSeek 调用
    │   │   └── QueryIntent.java                 # 槽位模型
    │   └── query/
    │       └── MaxComputeQueryService.java      # 复用已有封装
    └── resources/
        ├── ontology/metric.ttl                  # 本体骨架
        ├── config/metrics.yaml                  # 指标配置
        └── application.yml
```

## 3. 模块职责边界

| 模块 | 职责 | 依赖 |
|------|------|------|
| controller | 接收 HTTP 请求，返回结果 | service |
| service | 编排查询流程 | ontology、sql、llm、query |
| ontology | 本体加载、推理（等价/层级/派生） | Jena |
| sql | 模板/DSL 生成 SQL、口径校验 | ontology（读映射） |
| llm | 槽位提取、归因分析 | DeepSeek API |
| query | MaxCompute 执行 | 已有 SDK 封装 |

**关键约束**：模块间只通过接口交互，`service` 是唯一的编排入口，`ontology` 不依赖 `sql`/`llm`（本体是独立的语义层）。

## 4. 关键设计决策（承上启下）

1. **本体精简**：`metric.ttl` 只放概念类、关系、公理（推理关系），不放口径表达式和映射
2. **配置驱动**：`metrics.yaml` 放指标的口径、映射、计算逻辑，新增指标只加配置
3. **复用 MaxCompute 封装**：直接复用已有的 `MaxComputeQueryService`，不重复造轮子