# 项目使用文档

## 1. 文档概览

### 1.1 文档目标

这份文档用于说明 MobileModels 的使用方式、数据接入方式、维护方式和排查方式。文档不再按“项目说明 / 使用说明 / 数据库说明”拆开，而是整理成一份统一文档，方便不同角色在同一份上下文里完成阅读。

### 1.2 适用角色

- 产品或业务使用者：需要查设备、看字段、理解页面入口
- 数据维护者：需要维护品牌、来源排序、同步数据、刷新索引
- 服务端接入方：需要接 MySQL、按统一规则查询设备数据
- 运维维护者：需要启动服务、检查配置、处理运行问题

### 1.3 建议阅读路径

- 只想先跑起来：先看 `2. 快速开始`
- 只想用页面：先看 `3. 页面使用`
- 只想接数据库：先看 `4. 数据接入`
- 负责维护和发布：重点看 `5. 数据维护`、`6. 配置与运行`、`7. 排查指南`

## 2. 快速开始

### 2.1 项目提供什么

MobileModels 将下面几类能力放在一个项目里统一交付：

- 设备查询页面
- 数据管理页面
- 文档查看页面
- 设备索引构建
- MySQL schema 与 seed 生成
- 原始数据同步与自动调度

使用时不需要分别启动多个服务，默认通过 Docker Compose 统一运行。

### 2.2 启动服务

在项目根目录执行：

```bash
docker compose up --build -d
```

如果需要同时启动本地测试 MySQL：

```bash
docker compose -f docker-compose.yml -f docker-compose.test.yml up --build -d
```

如果需要覆盖默认环境变量：

```bash
cp .env.example .env
```

### 2.3 页面入口

- `设备查询`：`http://127.0.0.1:8123/web/device_query.html`
- `数据管理`：`http://127.0.0.1:8123/web/brand_management.html`
- `使用文档`：`http://127.0.0.1:8123/web/device_query.html?view=docs`

### 2.4 停止与重置

停止服务：

```bash
docker compose down
```

清空运行期数据：

```bash
docker compose down -v
```

### 2.5 启动后会自动完成什么

默认启动后会按配置完成以下动作：

1. 加载原始数据工作区
2. 构建设备索引
3. 生成 `dist/device_index.json`
4. 生成 `dist/mobilemodels_mysql_seed.sql`
5. 按配置决定是否自动装载 MySQL
6. 启动 Web 页面与 API
7. 启动项目内部的自动同步调度

## 3. 页面使用

### 3.1 页面结构

项目包含两个主页面和一个文档入口：

- `设备查询`：面向日常查询、联调、设备归类
- `数据管理`：面向品牌维护、来源维护、同步维护、索引维护
- `使用文档`：面向统一查看项目使用文档

### 3.2 设备查询页

设备查询页分为三个 tab。

#### 设备标识

适用输入：

- Android 原始标识，如 `SM-G9980`
- iOS 原始标识，如 `iPhone14,2`
- HarmonyOS 原始标识，如 `NOH-AL00`

适合场景：

- 设备管理
- 登录设备展示
- 服务端设备归类
- 客户端上报值排查

结果字段使用方式：

- 设备名称：`device_name`
- 品牌展示：优先 `market_brand`，为空再取 `brand`
- 厂商归属：优先 `parent_brand`，为空再取 `manufacturer_brand`
- 设备类型：`device_type`

不建议直接用作主展示的字段：

- `alias_norm`
- `source_file`
- `source_rank`
- `source_weight`
- `code`
- `code_alias`
- `ver_name`

#### 设备名称

适用输入：

- `iPad mini 7`
- `iPhone SE 3`
- 其他人工可读设备名称

查询行为：

1. 先尝试设备名称别名映射
2. 未命中时再查 `device_name` / `ver_name`

适合场景：

- 运营核对
- 人工排查
- 已知设备名但不知道原始标识

#### 标识索引

适用输入：

- 设备标识
- 常见设备名称

适合场景：

- 联调
- 索引识别结果比对
- 与 MySQL 查询结果做交叉验证

### 3.3 数据管理页

数据管理页按左侧导航分为五部分。

#### 品牌列表

这里维护：

- 品牌数、厂商数
- 品牌列表
- 品牌与厂商关系
- 品牌同义词

适用场景：

- 品牌口径调整
- 厂商归属调整
- 品牌展示不符合预期时排查

#### 手动补录

这里维护本地覆盖库。

这里可做的事：

- 新增独立品牌
- 在品牌下补录设备
- 编辑或删除本地补录记录

适用场景：

- 上游暂未收录的新品牌
- 学习机、教育终端、定制设备
- 需要立即参与页面查询和 MySQL 查询的补录数据

使用说明：

1. 品牌先建在本地覆盖库
2. 设备标识填客户端真实上报值
3. 保存后自动重建索引和 MySQL seed
4. 如果开启 MySQL 自动装载，会继续自动刷新 MySQL
5. 本地覆盖库不会被“原始数据同步”覆盖

#### 数据来源

这里维护来源优先级。

使用方式：

1. 直接拖拽来源顺序
2. 越靠前优先级越高
3. 保存后影响结果排序

适用场景：

- 多来源结果排序不符合预期
- 新来源加入后需要重新排序

#### 原始数据同步

这里维护：

- MySQL 自动装载开关
- 外部 MySQL 初始化
- 每日自动同步时间
- 同步状态与任务日志

适用场景：

- 上游数据更新后刷新本地数据
- 外部 MySQL 需要重建
- 调整自动同步策略

#### 索引数据

这里用于查看当前索引状态并手动重新加载。

适用场景：

- 同步完成后确认索引是否已生效
- 页面结果与预期不一致时检查索引版本

### 3.4 页面调试建议

如果页面查询结果异常，建议按下面顺序判断：

1. 先看输入值是否符合页面预期
2. 再看页面中的调试信息
3. 再看返回 JSON 是否包含预期字段
4. 再检查索引或 MySQL 数据是否已刷新

## 4. 数据接入

### 4.1 推荐查询入口

推荐统一查询下面这张主表：

```sql
mobilemodels.mm_device_catalog
```

这张表已经整合了设备标识、设备名称、品牌、厂商、来源和归一化结果。业务侧如果需要查设备信息，优先直接使用这张表，而不是自己拼接多张表或从页面逻辑反推字段。

### 4.2 推荐查询方式

主用方式是按 `alias_norm` 等值查询。

推荐 SQL：

```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;
```

### 4.3 为什么主推 `alias_norm`

客户端上报的原始 `model_raw` 可能包含大小写、横线、空格、下划线、逗号等差异。为了让相同设备尽可能稳定命中，项目统一把输入值归一化到 `alias_norm`，然后按 `alias_norm` 查询主表。

这也是页面查询与数据库查询保持一致的关键。

### 4.4 查询前归一化规则

归一化规则如下：

- 先转小写
- 只保留数字、英文字母、中文
- 去掉空格、横线、下划线、逗号及其他标点

正则示例：

```text
/[^0-9a-z\u4e00-\u9fff]+/g
```

JavaScript 示例：

```js
text.toLowerCase().replace(/[^0-9a-z\u4e00-\u9fff]+/g, "")
```

样例：

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

### 4.5 结果字段使用建议

面向设备管理场景，推荐按下面顺序取值：

- 设备名称：`device_name`
- 品牌展示：优先 `market_brand`，为空再取 `brand`
- 厂商归属：优先 `parent_brand`，为空再取 `manufacturer_brand`
- 设备类型：`device_type`

下面这些字段通常用于排查、排序或扩展匹配，不建议直接作为主展示字段：

- `alias_norm`
- `source_file`
- `source_rank`
- `source_weight`
- `code`
- `code_alias`
- `ver_name`

### 4.6 页面查询与数据库查询的关系

页面里的 `设备标识` 查询和 `设备名称` 查询，底层都依赖这张主表。因此：

- 页面结果和第三方直接查库结果应该保持同一口径
- 页面里的归一化规则应与服务端或业务接入侧保持一致
- 如果页面显示异常，先核对主表数据，再核对前端展示逻辑

## 5. 数据维护

### 5.1 数据来源

项目的数据来源分为两部分：

- 上游原始数据：`workspace/brands/*.md`
- 本地覆盖库：`workspace/local/manual_catalog.json`

上游原始数据用于同步官方或社区维护的数据，本地覆盖库用于补录当前业务需要但上游暂未收录的品牌和设备。

### 5.2 数据生成链路

完整链路如下：

1. 同步上游原始 markdown
2. 解析 `workspace/brands/*.md`
3. 合并 `workspace/local/manual_catalog.json`
4. 构建 `dist/device_index.json`
5. 导出 `dist/mobilemodels_mysql_seed.sql`
6. 按配置决定是否自动装载 MySQL

### 5.3 关键产物

- 索引文件：`dist/device_index.json`
- MySQL seed：`dist/mobilemodels_mysql_seed.sql`

### 5.4 常见维护动作

#### 刷新原始数据

适用于上游数据已变化，需要重新生成索引和 MySQL 数据。

#### 调整品牌关系

适用于品牌展示或厂商归属不符合预期的情况。

#### 手动补录品牌或设备

适用于上游未收录，但业务需要立即支持的设备。

维护方式：

1. 在 `数据管理 -> 手动补录` 中新增品牌或设备
2. 保存后自动刷新索引与 MySQL seed
3. 如关闭了 MySQL 自动装载，需按需手动初始化或刷新外部 MySQL

说明：

- 本地覆盖库不会被上游同步覆盖
- 本地补录来源默认优先级更高
- 适合维护学习机、教育设备、定制终端

#### 调整来源顺序

适用于多个来源的优先级需要重新定义的情况。

#### 重新加载索引

适用于索引已更新，但页面还没有使用到最新索引的情况。

## 6. 配置与运行

### 6.1 目录说明

```text
workspace/  上游原始数据与补充资料
dist/       索引产物与 MySQL seed
docs/       文档入口与兼容说明
sql/        MySQL schema
tools/      构建、同步、导入、服务脚本
web/        页面与静态资源
```

### 6.2 常见环境变量

- `MYSQL_HOST`
- `MYSQL_PORT`
- `MYSQL_DATABASE`
- `MYSQL_ROOT_USER`
- `MYSQL_ROOT_PASSWORD`
- `MYSQL_READER_USER`
- `MYSQL_READER_PASSWORD`
- `MYSQL_AUTO_LOAD`
- `SYNC_SCHEDULE_ENABLED`
- `SYNC_SCHEDULE_TIME`
- `GITHUB_PROXY_PREFIX`
- `TZ`

### 6.3 运行期配置落盘位置

- MySQL 自动装载：`/data/state/mysql_settings.json`
- 自动同步计划：`/data/state/sync_schedule.json`

### 6.4 运行约定

- Compose 会优先读取 shell 环境变量和项目根目录 `.env`
- 容器启动后会完成索引构建、服务启动，以及按配置决定是否自动装载 MySQL
- 自动同步运行在项目容器内部，不依赖 GitHub Actions
- 生产环境应替换默认数据库密码

### 6.5 MySQL 使用建议

- 生产环境不要继续使用默认密码
- 如果接外部 MySQL，先确认 root 账号具备建库建表权限
- 如关闭自动装载，需通过数据管理页手动初始化外部 MySQL

## 7. 排查指南

### 7.1 查不到设备标识

按下面顺序排查：

1. 确认输入的是客户端原始 `model_raw`
2. 确认归一化结果是否符合规则
3. 查看 `设备标识` 页调试信息和返回 JSON
4. 检查主表里是否存在对应 `alias_norm`

### 7.2 品牌或厂商归属不对

建议排查：

1. 查看 `数据管理 -> 品牌列表`
2. 核对 `market_brand` 与 `parent_brand`
3. 确认是否存在品牌同义词或父级归属未维护的情况

### 7.3 结果排序不符合预期

建议排查：

1. 查看 `数据管理 -> 数据来源`
2. 核对 `source_rank`
3. 确认结果是否来自预期来源文件

### 7.4 MySQL 没有刷新

建议排查：

1. 查看 `数据管理 -> 原始数据同步`
2. 检查 MySQL 自动装载开关
3. 查看同步状态与任务日志
4. 必要时手动初始化外部 MySQL

### 7.5 索引结果不对

建议排查：

1. 查看 `数据管理 -> 索引数据`
2. 检查 `dist/device_index.json` 是否已更新
3. 确认页面是否已经重新加载了最新索引

## 8. 常见问题

### 8.1 为什么页面结果和数据库结果不一致

优先检查以下两点：

- 页面是否使用了最新索引
- 数据库是否使用了最新 seed 数据

如果索引和 MySQL 数据版本不一致，页面和数据库查询结果就可能不同步。

### 8.2 为什么品牌字段有多个

项目同时保留原始品牌、展示品牌和父级厂商字段，是为了兼顾原始数据保留、业务展示口径和厂商归属口径。业务展示通常取 `market_brand`，厂商归属通常取 `parent_brand`。

### 8.3 什么时候用设备名称查询，什么时候用设备标识查询

- 主流程、服务端接入、设备管理：优先用设备标识查询
- 人工排查、运营核对、设备名反查：用设备名称查询

### 8.4 什么时候需要手动初始化外部 MySQL

当你使用的是外部 MySQL，且关闭了自动装载，或者数据库结构和数据需要重新初始化时，需要在数据管理页里手动执行初始化。
