refactor: restore root layout and split mysql config

docs/web-ui.md

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