yuanzhen869/MobileModels
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
637764f622466f65e5b4503c79d11ac9d498ba62
MobileModels/README.md
T
yuanzhen869 d29cbed1fa Rename docs nav label
2026-04-14 18:43:19 +08:00

13 KiB
Raw Blame History

项目使用文档

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 启动服务

在项目根目录执行：

docker compose up --build -d

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

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

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

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 停止与重置

停止服务：

docker compose down

清空运行期数据：

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 推荐查询入口

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

mobilemodels.mm_device_catalog

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

4.2 推荐查询方式

主用方式是按 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;

4.3 为什么主推 alias_norm

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

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

4.4 查询前归一化规则

归一化规则如下：

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

正则示例：

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

JavaScript 示例：

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

样例：

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 目录说明

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，且关闭了自动装载，或者数据库结构和数据需要重新初始化时，需要在数据管理页里手动执行初始化。

Reference in New Issue View Git Blame Copy Permalink