# MySQL 设计说明

本文档说明交付版 MobileModels 的 MySQL 数据组织方式、兼容层设计与推荐查询方式。

## 设计目标

- 所有设备标识都能落到 MySQL 查询
- 支持第三方直接查库，保证查询速度
- 保留兼容旧结构的访问方式
- 页面侧和 SQL 接入侧统一使用同一份设备数据

## 主表

主推物理表：

```sql
mobilemodels.mm_device_catalog
```

主表整合了设备型号、品牌、厂商、来源、别名归一化结果和兼容字段，适合作为统一查询入口。

### 关键字段

- `model`
- `record_id`
- `alias_norm`
- `device_name`
- `brand`
- `manufacturer_brand`
- `parent_brand`
- `market_brand`
- `device_type`
- `source_file`
- `section`
- `source_rank`
- `source_weight`
- `code`
- `code_alias`
- `ver_name`

## 推荐查询方式

### 1. 第三方直接查主表

推荐按 `alias_norm` 等值查询：

```sql
SELECT
  model,
  record_id,
  alias_norm,
  device_name,
  brand,
  manufacturer_brand,
  parent_brand,
  market_brand,
  device_type,
  source_file,
  section,
  source_rank,
  source_weight,
  code,
  code_alias,
  ver_name
FROM mobilemodels.mm_device_catalog
WHERE alias_norm = ?
ORDER BY source_rank ASC, record_id ASC
LIMIT 20;
```

### 2. 页面 SQL 查询

页面的 `SQL 查询` tab 也是基于这张主表。

查询流程：

1. 接收客户端原始上报值
2. 服务端归一化为 `alias_norm`
3. 按主表等值查询
4. 返回结果列表、执行 SQL 和 JSON 输出

## 兼容视图

为了兼容旧系统，当前仍保留以下视图：

```sql
mobilemodels.mm_device_lookup
mobilemodels.mm_device_record
mobilemodels.models
python_services_test.models
```

其中旧结构 `python_services_test.models` 主要用于兼容既有查询逻辑，不再作为主推接入方式。

## 兼容旧结构查询示例

```sql
SELECT
  model,
  dtype,
  brand,
  brand_title,
  code,
  code_alias,
  model_name,
  ver_name
FROM python_services_test.models
WHERE model = ?
LIMIT 20;
```

## 归一化规则

`alias_norm` 统一按以下规则生成：

- 全部转小写
- 仅保留 `[0-9a-z中文]`
- 去掉空格、横线、下划线和其他标点

示例：

```text
SM-G9980   -> smg9980
iPhone14,2 -> iphone142
NOH-AL00   -> nohal00
```

## 数据来源

主表和索引数据均由以下流程生成：

1. 同步上游原始 markdown 数据
2. 解析 `workspace/brands/*.md`
3. 构建 `dist/device_index.json`
4. 导出 `dist/mobilemodels_mysql_seed.sql`
5. 加载 MySQL schema 与 seed

## 交付建议

- 第三方新接入优先使用 `mm_device_catalog`
- 页面联调和数据库联调使用同一套原始数据与归一化规则
- 生产环境务必替换默认数据库密码