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，不重复造轮子