yuanzhen869/MobileModels
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine web UI and usage docs

Browse Source
This commit is contained in:
yuanzhen869
2026-04-14 13:54:02 +08:00
parent 0ba4fef55e
commit 0c01b91fd7
13 changed files with 21990 additions and 18993 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+461 -27
View File
@@ -1,55 +1,489 @@
# 手机品牌型号汇总
# 项目使用文档
当前项目以根目录作为统一入口，支持通过 Docker Compose 直接启动设备查询、数据管理和 MySQL 服务。
## 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，一起叠加测试配置启动：
如果需要同时启动本地测试 MySQL：
```bash
docker compose -f docker-compose.yml -f docker-compose.test.yml up --build -d
```
如需自定义 MySQL 连接，先复制环境模板：
如果需要覆盖默认环境变量：
```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`
- `设备查询`：`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 数据管理页
数据管理页按左侧导航分为四部分。
#### 品牌列表
这里维护：
- 品牌数、厂商数
- 品牌列表
- 品牌与厂商关系
- 品牌同义词
适用场景：
- 品牌口径调整
- 厂商归属调整
- 品牌展示不符合预期时排查
#### 数据来源
这里维护来源优先级。
使用方式：
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
workspace/ 上游原始数据、补充资料与历史文件
dist/ 构建产物与 MySQL seed
docs/ 项目文档
/[^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`。这些原始 markdown 是后续索引与 MySQL 数据生成的基础。
### 5.2 数据生成链路
完整链路如下：
1. 同步上游原始 markdown
2. 解析 `workspace/brands/*.md`
3. 构建 `dist/device_index.json`
4. 导出 `dist/mobilemodels_mysql_seed.sql`
5. 加载 MySQL schema 与 seed
### 5.3 关键产物
- 索引文件：`dist/device_index.json`
- MySQL seed：`dist/mobilemodels_mysql_seed.sql`
### 5.4 常见维护动作
#### 刷新原始数据
适用于上游数据已变化，需要重新生成索引和 MySQL 数据。
#### 调整品牌关系
适用于品牌展示或厂商归属不符合预期的情况。
#### 调整来源顺序
适用于多个来源的优先级需要重新定义的情况。
#### 重新加载索引
适用于索引已更新，但页面还没有使用到最新索引的情况。
## 6. 配置与运行
### 6.1 目录说明
```text
workspace/ 上游原始数据与补充资料
dist/ 索引产物与 MySQL seed
docs/ 文档入口与兼容说明
sql/ MySQL schema
tools/ 构建、同步、导入与服务脚本
tools/ 构建、同步、导入、服务脚本
web/ 页面与静态资源
```
## 说明
### 6.2 常见环境变量
- `workspace/` 用于存放原始数据工作区
- `docker-compose.yml`、`Dockerfile`、`tools/` 都位于项目主目录
- 默认主配置面向远程 MySQL
- `docker-compose.test.yml` 中的 MySQL 仅用于本地测试
- 容器内生成的 `dist/device_index.json` 与 `dist/mobilemodels_mysql_seed.sql` 会直接挂载到宿主机项目根目录的 `dist/`
- Compose 会优先读取 shell 环境变量和项目根目录 `.env`，再回退到 `docker-compose.yml` 默认值
- 上游原始 git 同步、索引构建和 MySQL 刷新都在容器内完成
- 项目内置“每日自动同步”调度，不依赖 GitHub Actions；时间点可在数据管理页设置，也可用 `.env` 覆盖默认值
- 如需 GitHub 加速，可配置 `GITHUB_PROXY_PREFIX`，也可在数据管理页直接修改
- `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 运行期配置落盘位置
- [docs/README.md](docs/README.md)
- [docs/web-ui.md](docs/web-ui.md)
- 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，且关闭了自动装载，或者数据库结构和数据需要重新初始化时，需要在数据管理页里手动执行初始化。