refactor: restore root layout and split mysql config
This commit is contained in:
18
docs/README.md
Normal file
18
docs/README.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# 项目文档
|
||||
|
||||
交付版文档统一收敛到本目录，便于部署、培训和对外交付。
|
||||
|
||||
## 文档索引
|
||||
|
||||
- [部署与使用说明](web-ui.md)
|
||||
- [MySQL 设计说明](mysql-query-design.md)
|
||||
- [索引构建与设备映射说明](device-mapper.md)
|
||||
|
||||
## 目录说明
|
||||
|
||||
- `web-ui.md`
|
||||
- Docker Compose 启动、页面入口、MySQL 连接和管理能力说明
|
||||
- `mysql-query-design.md`
|
||||
- 主表设计、兼容视图、推荐查询方式
|
||||
- `device-mapper.md`
|
||||
- `dist/device_index.json` 构建方式与索引字段说明
|
||||
57
docs/device-mapper.md
Normal file
57
docs/device-mapper.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Device Mapper Usage
|
||||
|
||||
This tool builds a cross-platform lookup index from `workspace/brands/*.md`.
|
||||
|
||||
## 1) Build index
|
||||
|
||||
```bash
|
||||
python3 tools/device_mapper.py build
|
||||
```
|
||||
|
||||
Output file: `dist/device_index.json`
|
||||
|
||||
## 2) Query from command line
|
||||
|
||||
```bash
|
||||
python3 tools/device_mapper.py find --name 'iPhone14,5' --brand Apple
|
||||
python3 tools/device_mapper.py find --name 'M2102J2SC' --brand Xiaomi
|
||||
python3 tools/device_mapper.py find --name 'L55M5-AD' --brand Xiaomi
|
||||
```
|
||||
|
||||
## 3) JSON structure
|
||||
|
||||
- `records`: normalized device records
|
||||
- `device_name`: standard marketing name
|
||||
- `brand`: normalized brand
|
||||
- `manufacturer_brand`: manufacturer-level brand
|
||||
- `market_brand`: market sub-brand
|
||||
- `device_type`: `phone | tablet | wear | tv | other`
|
||||
- `aliases`: all searchable aliases
|
||||
- `lookup`: normalized alias -> candidate `record.id[]`
|
||||
- `brand_aliases`: normalized brand aliases to filter by app-provided brand
|
||||
- `brand_management`: brand governance metadata
|
||||
|
||||
## 4) App-side integration
|
||||
|
||||
1. Load `dist/device_index.json` into memory.
|
||||
2. Normalize input `name` and optional `brand`.
|
||||
3. Use `lookup[normalized_name]` to fetch candidate records.
|
||||
4. Normalize brand via `brand_management`.
|
||||
5. Filter records by normalized manufacturer or market brand when needed.
|
||||
6. Return first candidate or all candidates.
|
||||
|
||||
Normalization rule:
|
||||
|
||||
- lower-case
|
||||
- keep only `[0-9a-z\u4e00-\u9fff]`
|
||||
- remove spaces, hyphens, underscores and punctuation
|
||||
|
||||
## 5) Device type mapping
|
||||
|
||||
Supported categories:
|
||||
|
||||
- `phone`
|
||||
- `tablet`
|
||||
- `wear`
|
||||
- `tv`
|
||||
- `other`
|
||||
142
docs/mysql-query-design.md
Normal file
142
docs/mysql-query-design.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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`
|
||||
- 页面联调和数据库联调使用同一套原始数据与归一化规则
|
||||
- 生产环境务必替换默认数据库密码
|
||||
116
docs/web-ui.md
Normal file
116
docs/web-ui.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# Web UI
|
||||
|
||||
## 启动方式
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
停止服务：
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
重置 MySQL 和运行期数据：
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## 页面入口
|
||||
|
||||
- `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`：相关文档
|
||||
|
||||
整个功能栈统一运行在 Docker Compose 中，不再依赖本地 Python。
|
||||
|
||||
原始数据工作空间位于项目内的 `workspace/` 目录。
|
||||
|
||||
## 启动后自动完成的动作
|
||||
|
||||
- 从 `workspace/brands` 构建设备索引
|
||||
- 生成 `dist/device_index.json`
|
||||
- 导出 MySQL seed 文件
|
||||
- 如开启 `MYSQL_AUTO_LOAD=1`，则加载 MySQL schema 与 seed 数据
|
||||
- 启动 Web 页面与 API 服务
|
||||
|
||||
## MySQL 默认连接
|
||||
|
||||
- Host: `127.0.0.1`
|
||||
- Port: `3306`
|
||||
- Database: `mobilemodels`
|
||||
- Reader User: `mobilemodels_reader`
|
||||
|
||||
如需自定义账号密码，请使用 `.env` 覆盖默认值。
|
||||
|
||||
## MySQL 模式
|
||||
|
||||
- 主配置 `docker-compose.yml`
|
||||
- 面向远程 MySQL
|
||||
- 默认不自动装载 schema/seed
|
||||
- 测试配置 `docker-compose.test.yml`
|
||||
- 额外启动一个本地测试 MySQL
|
||||
- 应用容器会自动把数据加载进去
|
||||
|
||||
## 设备查询
|
||||
|
||||
页面顶部统一提供三个导航入口：
|
||||
|
||||
- `设备查询`
|
||||
- `数据管理`
|
||||
- `相关文档`
|
||||
|
||||
设备查询页顶部包含两个页内 tab：
|
||||
|
||||
- `SQL 查询`
|
||||
- `索引查询`
|
||||
|
||||
### SQL 查询
|
||||
|
||||
- 直接调用 Compose 内 API 查询 MySQL 主表 `mobilemodels.mm_device_catalog`
|
||||
- 服务端先将输入归一化为 `alias_norm`
|
||||
- 页面展示实际执行的 SQL、返回结果和 JSON
|
||||
- 页面同时展示只读连接信息，便于第三方联调
|
||||
|
||||
### 索引查询
|
||||
|
||||
- 基于 `dist/device_index.json` 内存索引进行快速识别
|
||||
- 适合前端联调、接口对比和结果核验
|
||||
|
||||
### 平台输入建议
|
||||
|
||||
- Android / iOS / HarmonyOS：直接使用客户端原始上报的 `model_raw`
|
||||
- 输入框会根据所选平台自动提供示例值
|
||||
- 未输入时，系统会使用当前平台的默认示例值发起查询
|
||||
|
||||
## 数据管理
|
||||
|
||||
数据管理页支持：
|
||||
|
||||
- 品牌列表管理
|
||||
- 品牌与厂商关系管理
|
||||
- 品牌同义词管理
|
||||
- 数据来源优先级管理
|
||||
- 原始数据同步
|
||||
- 索引数据查看与重新加载
|
||||
|
||||
## 说明
|
||||
|
||||
- 原始数据、索引和 MySQL seed 运行时持久化在 Docker volume 中，不回写本地工作区
|
||||
- 交付环境建议覆盖默认的 `MYSQL_ROOT_PASSWORD` 和 `MYSQL_READER_PASSWORD`
|
||||
Reference in New Issue
Block a user