Refine web UI and usage docs
This commit is contained in:
+3
-163
@@ -1,165 +1,5 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
Compose 的环境变量来源顺序：
|
||||
|
||||
1. 当前 shell 环境变量
|
||||
2. 项目根目录 `.env`
|
||||
3. `docker-compose.yml` 中的默认值
|
||||
|
||||
停止服务：
|
||||
|
||||
```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 服务
|
||||
|
||||
首次启动默认值仍来自环境变量；之后可在 Web UI 中修改自动装载开关，运行期配置会持久化到 `/data/state/mysql_settings.json`。
|
||||
|
||||
## MySQL 默认连接
|
||||
|
||||
- Host: `127.0.0.1`
|
||||
- Port: `3306`
|
||||
- Database: `mobilemodels`
|
||||
- Reader User: `mobilemodels_reader`
|
||||
|
||||
如需自定义账号密码，请使用 `.env` 覆盖默认值。
|
||||
|
||||
常用变量：
|
||||
|
||||
- `MYSQL_HOST`
|
||||
- `MYSQL_PORT`
|
||||
- `TZ`
|
||||
- `MYSQL_ROOT_USER`
|
||||
- `MYSQL_ROOT_PASSWORD`
|
||||
- `MYSQL_DATABASE`
|
||||
- `MYSQL_READER_USER`
|
||||
- `MYSQL_READER_PASSWORD`
|
||||
- `MYSQL_AUTO_LOAD`
|
||||
- `SYNC_SCHEDULE_ENABLED`
|
||||
- `SYNC_SCHEDULE_TIME`
|
||||
- `GITHUB_PROXY_PREFIX`
|
||||
|
||||
## 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 手动初始化
|
||||
- 原始数据同步
|
||||
- 每日自动同步时间点设置
|
||||
- 索引数据查看与重新加载
|
||||
|
||||
### 外部 MySQL 手动初始化
|
||||
|
||||
- 页面入口：`数据管理 -> 原始数据同步 -> 初始化外部 MySQL`
|
||||
- 适用于 `MYSQL_AUTO_LOAD=0` 的远程 MySQL
|
||||
- 点击后会执行 schema 与 seed 导入，自动创建数据库，并重建 `mobilemodels` 相关表与视图
|
||||
- 执行前请确认 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_ROOT_USER`、`MYSQL_ROOT_PASSWORD` 指向正确且具备建库建表权限
|
||||
|
||||
### MySQL 自动装载开关
|
||||
|
||||
- 页面入口：`数据管理 -> 原始数据同步 -> MySQL 自动装载`
|
||||
- 保存后会更新运行期配置 `/data/state/mysql_settings.json`
|
||||
- 会影响后续“开始同步原始数据”是否自动刷新 MySQL
|
||||
- 也会影响容器后续启动时是否自动执行 schema 与 seed 导入
|
||||
|
||||
### 每日自动同步
|
||||
|
||||
- 调度器运行在项目容器内部，不依赖 GitHub Actions
|
||||
- 页面入口：`数据管理 -> 原始数据同步`
|
||||
- 可设置是否启用，以及每天执行的时间点
|
||||
- 可选配置 GitHub 加速前缀，例如 `https://ghfast.top/`
|
||||
- 运行期配置持久化在 `/data/state/sync_schedule.json`
|
||||
- 时间按容器时区执行，默认值来自 `TZ`，默认 `Asia/Shanghai`
|
||||
|
||||
## 说明
|
||||
|
||||
- 原始数据、索引和 MySQL seed 运行时持久化在 Docker volume 中，不回写本地工作区
|
||||
- 交付环境建议覆盖默认的 `MYSQL_ROOT_PASSWORD` 和 `MYSQL_READER_PASSWORD`
|
||||
- [项目使用文档](../README.md)
|
||||
|
||||
Reference in New Issue
Block a user