优化体验，修复 bug

2026-07-09 10:33:19 +08:00
parent e2577ff661
commit b4926ba148
21 changed files with 1196 additions and 260 deletions
@@ -10,8 +10,18 @@
 - [frontend/src/api/model.js](file://frontend/src/api/model.js)
 - [backend/src/models/Ota.js](file://backend/src/models/Ota.js)
 - [backend/src/routes/ota.js](file://backend/src/routes/ota.js)
+- [backend/src/services/squiglink.js](file://backend/src/services/squiglink.js)
+- [frontend/src/views/model/components/ModelFormDialog.vue](file://frontend/src/views/model/components/ModelFormDialog.vue)
 </cite>

+## 更新摘要
+**变更内容**
+- 新增squig.link外部URL数据源抓取功能
+- 增强模型创建/更新流程支持外部频响数据源
+- 添加squiglink_csv字段支持直接上传CSV内容
+- 新增squiglink-fetch接口用于从外部URL获取频响数据
+- 前端ModelFormDialog组件集成squig.link导入功能
+
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
@@ -24,63 +34,74 @@
 9. [结论](#结论)

 ## 简介
-本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。
+本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。**最新更新**：新增squig.link外部数据源支持，增强模型创建/更新流程以支持外部URL数据源。

 ## 项目结构
 型号管理API位于后端Express应用中，采用模块化设计：
- 路由层：集中于 models.js，提供型号的增删改查、搜索推送、频响文件处理等接口
+- 路由层：集中于 models.js，提供型号的增删改查、搜索推送、频响文件处理、**squig.link数据抓取**等接口
 - 模型层：Model.js 定义数据库表结构
 - 验证层：model.js 使用Zod进行请求体验证
 - 工具层：response.js 统一响应格式
 - 中间件：auth.js 提供鉴权保护
+- **服务层**：squiglink.js 提供squig.link外部数据源抓取服务
 - 前端封装：frontend/src/api/model.js 提供HTTP调用封装
+- **前端组件**：ModelFormDialog.vue 集成squig.link导入功能

 ```mermaid
 graph TB
-FE["前端应用<br/>frontend/src/api/model.js"] --> R["路由层<br/>backend/src/routes/models.js"]
+FE["前端应用<br/>frontend/src/api/model.js<br/>frontend/src/views/model/components/ModelFormDialog.vue"] --> R["路由层<br/>backend/src/routes/models.js"]
 R --> M["模型层<br/>backend/src/models/Model.js"]
 R --> V["验证层<br/>backend/src/validators/model.js"]
 R --> U["工具层<br/>backend/src/utils/response.js"]
 R --> A["中间件<br/>backend/src/middleware/auth.js"]
+R --> S["服务层<br/>backend/src/services/squiglink.js"]
 R -. 关联 .-> OTA["OTA模型<br/>backend/src/models/Ota.js"]
 ```

-图表来源
- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+**图表来源**
+- [backend/src/routes/models.js:1-659](file://backend/src/routes/models.js#L1-L659)
 - [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
 - [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [frontend/src/api/model.js:1-151](file://frontend/src/api/model.js#L1-L151)
+- [frontend/src/api/model.js:1-165](file://frontend/src/api/model.js#L1-L165)
 - [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [backend/src/services/squiglink.js:1-322](file://backend/src/services/squiglink.js#L1-L322)
+- [frontend/src/views/model/components/ModelFormDialog.vue:1-555](file://frontend/src/views/model/components/ModelFormDialog.vue#L1-L555)

-章节来源
- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+**章节来源**
+- [backend/src/routes/models.js:1-659](file://backend/src/routes/models.js#L1-L659)
 - [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
 - [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
- [frontend/src/api/model.js:1-151](file://frontend/src/api/model.js#L1-L151)
+- [frontend/src/api/model.js:1-165](file://frontend/src/api/model.js#L1-L165)
 - [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [backend/src/services/squiglink.js:1-322](file://backend/src/services/squiglink.js#L1-L322)
+- [frontend/src/views/model/components/ModelFormDialog.vue:1-555](file://frontend/src/views/model/components/ModelFormDialog.vue#L1-L555)

 ## 核心组件
- 路由控制器：models.js 提供型号的列表查询、详情获取、创建、更新、删除、搜索推送、频响文件上传与查询等接口
+- 路由控制器：models.js 提供型号的列表查询、详情获取、创建、更新、删除、搜索推送、频响文件上传与查询、**squig.link数据抓取**等接口
 - 数据模型：Model.js 定义型号字段及约束
 - 请求验证：model.js 使用Zod Schema进行创建/更新的输入校验
 - 统一响应：response.js 提供统一的响应结构
 - 鉴权中间件：auth.js 实现Bearer Token鉴权
+- **squig.link服务**：squiglink.js 提供外部数据源抓取功能
 - 前端封装：frontend/src/api/model.js 提供HTTP调用封装
+- **前端组件**：ModelFormDialog.vue 集成squig.link导入功能

-章节来源
+**章节来源**
 - [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
 - [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
 - [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
- [frontend/src/api/model.js:13-150](file://frontend/src/api/model.js#L13-L150)
+- [backend/src/services/squiglink.js:1-322](file://backend/src/services/squiglink.js#L1-L322)
+- [frontend/src/api/model.js:13-165](file://frontend/src/api/model.js#L13-L165)
+- [frontend/src/views/model/components/ModelFormDialog.vue:158-464](file://frontend/src/views/model/components/ModelFormDialog.vue#L158-L464)

 ## 架构概览
-型号管理API采用分层架构，路由层负责HTTP协议与参数解析，模型层负责数据持久化，验证层确保输入合法性，工具层统一输出格式，中间件提供安全控制。
+型号管理API采用分层架构，路由层负责HTTP协议与参数解析，模型层负责数据持久化，验证层确保输入合法性，工具层统一输出格式，中间件提供安全控制，**服务层提供外部数据源集成**。

 ```mermaid
 sequenceDiagram
@@ -88,6 +109,7 @@ participant C as "客户端"
 participant R as "路由(models.js)"
 participant V as "验证(model.js)"
 participant M as "模型(Model.js)"
+participant S as "服务(squiglink.js)"
 participant U as "响应(response.js)"
 participant A as "鉴权(auth.js)"
 C->>R : "HTTP请求"
@@ -95,16 +117,19 @@ R->>A : "鉴权检查"
 A-->>R : "通过/拒绝"
 R->>V : "请求体验证"
 V-->>R : "验证结果"
+R->>S : "外部数据源抓取可选"
+S-->>R : "抓取结果"
 R->>M : "数据库操作"
 M-->>R : "结果"
 R->>U : "封装响应"
 U-->>C : "统一响应"
 ```

-图表来源
- [backend/src/routes/models.js:307-361](file://backend/src/routes/models.js#L307-L361)
+**图表来源**
+- [backend/src/routes/models.js:307-369](file://backend/src/routes/models.js#L307-L369)
 - [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)
 - [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+- [backend/src/services/squiglink.js:261-310](file://backend/src/services/squiglink.js#L261-L310)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)

@@ -135,10 +160,10 @@ datetime create_at
 }
 ```

-图表来源
+**图表来源**
 - [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)

-章节来源
+**章节来源**
 - [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)

 ### 型号参数验证规则
@@ -149,7 +174,7 @@ datetime create_at
 - 更新请求体验证：
  - 字段同上，但允许部分字段为空（表示不更新）

-章节来源
+**章节来源**
 - [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)

 ### 型号CRUD接口
@@ -167,7 +192,7 @@ datetime create_at
 - 成功响应：包含items、total、skip、limit的分页数据
 - 异常响应：统一错误码与消息

-章节来源
+**章节来源**
 - [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -179,7 +204,7 @@ datetime create_at
 - 成功响应：型号基础字段
 - 异常响应：未找到或通用错误

-章节来源
+**章节来源**
 - [backend/src/routes/models.js:280-304](file://backend/src/routes/models.js#L280-L304)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -190,16 +215,20 @@ datetime create_at
 - 内容类型：multipart/form-data
 - 表单字段：
  - measurement_file：频响文件（CSV/TXT/JSON），可选
+  - **squiglink_csv**：squig.link抓取的CSV内容，可选
  - brand_name、name、form、rig、source、eq_key
 - 文件处理：
+  - **优先级**：squiglink_csv > measurement_file > 无文件
  - TXT文件自动转换为CSV
  - 仅允许.csv、.txt、.json
  - 上传至S3，键值包含source、form、brand_name、name
 - 成功响应：创建后的型号信息
 - 异常响应：重复、格式不支持、通用错误

-章节来源
- [backend/src/routes/models.js:306-361](file://backend/src/routes/models.js#L306-L361)
+**更新** 新增squiglink_csv字段支持直接上传CSV内容
+
+**章节来源**
+- [backend/src/routes/models.js:371-437](file://backend/src/routes/models.js#L371-L437)
 - [backend/src/validators/model.js:3-10](file://backend/src/validators/model.js#L3-L10)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -214,8 +243,8 @@ datetime create_at
 - 成功响应：更新后的型号信息
 - 异常响应：未找到、重复、格式不支持、通用错误

-章节来源
- [backend/src/routes/models.js:363-436](file://backend/src/routes/models.js#L363-L436)
+**章节来源**
+- [backend/src/routes/models.js:439-526](file://backend/src/routes/models.js#L439-L526)
 - [backend/src/validators/model.js:12-19](file://backend/src/validators/model.js#L12-L19)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -230,8 +259,8 @@ datetime create_at
 - 成功响应：删除成功
 - 异常响应：未找到、Meilisearch删除失败、通用错误

-章节来源
- [backend/src/routes/models.js:438-464](file://backend/src/routes/models.js#L438-L464)
+**章节来源**
+- [backend/src/routes/models.js:528-554](file://backend/src/routes/models.js#L528-L554)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)

@@ -240,7 +269,7 @@ datetime create_at
 - 支持按id或create_at排序，升序/降序
 - 分页参数：skip、limit（上限1000）

-章节来源
+**章节来源**
 - [backend/src/routes/models.js:136-157](file://backend/src/routes/models.js#L136-L157)

 ### 型号与OTA固件的一对多关联
@@ -264,11 +293,11 @@ string model
 }
 ```

-图表来源
+**图表来源**
 - [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
 - [backend/src/models/Ota.js:44-48](file://backend/src/models/Ota.js#L44-L48)

-章节来源
+**章节来源**
 - [backend/src/models/Ota.js:44-48](file://backend/src/models/Ota.js#L44-L48)

 ### Meilisearch搜索推送与校验
@@ -279,15 +308,15 @@ string model
  - 输入：model_ids数组
  - 输出：推送成功数量、任务ID与推送数据

-章节来源
- [backend/src/routes/models.js:466-566](file://backend/src/routes/models.js#L466-L566)
+**章节来源**
+- [backend/src/routes/models.js:556-656](file://backend/src/routes/models.js#L556-L656)

 ### 频响文件上传与查询
- 上传：POST /api/models/（multipart/form-data），支持TXT自动转换为CSV
+- 上传：POST /api/models/（multipart/form-data），支持TXT自动转换为CSV，**新增squiglink_csv字段**
 - 查询：GET /api/models/:model_id/measurement（仅Eafonyoung来源且存在form时可用）

-章节来源
- [backend/src/routes/models.js:306-361](file://backend/src/routes/models.js#L306-L361)
+**章节来源**
+- [backend/src/routes/models.js:371-437](file://backend/src/routes/models.js#L371-L437)
 - [backend/src/routes/models.js:246-278](file://backend/src/routes/models.js#L246-L278)

 ### EQ缓存与Meilisearch文档查询
@@ -295,13 +324,53 @@ string model
 - 获取指定Hash Field：GET /api/models/:model_id/eq-cache/field?key=...
 - 查询Meilisearch推送状态：GET /api/models/:model_id/meilisearch

-章节来源
+**章节来源**
 - [backend/src/routes/models.js:183-244](file://backend/src/routes/models.js#L183-L244)

+### Squig.link外部数据源集成
+
+#### Squig.link数据抓取接口
+- 方法与路径：POST /api/models/squiglink-fetch
+- 认证：需要登录
+- 请求体参数：
+  - share_url：squig.link分享链接（必填）
+  - selected_file：用户选择的特定文件名（可选）
+- 功能特性：
+  - **自动抓取**：根据share_url自动解析并抓取频响数据
+  - **候选选择**：当存在多个匹配文件时，返回候选列表供用户选择
+  - **直接下载**：当提供selected_file时，直接下载指定文件
+  - **佩戴方式检测**：从squigsites.json自动检测佩戴方式
+- 响应格式：
+  - 单个匹配：返回brand_name、model_name、form、csv_content、data_url
+  - 多个匹配：返回matches候选列表
+  - 错误：返回具体的抓取失败原因
+
+#### Squig.link服务功能
+- **URL解析**：解析squig.link分享URL，提取baseURL和share参数
+- **站点发现**：从https://squig.link/squigsites.json获取站点配置
+- **文件匹配**：在phone_book.json中查找匹配的测量文件
+- **数据下载**：支持多种文件后缀的频响数据下载
+- **格式转换**：将TXT文件转换为CSV格式
+- **缓存机制**：squigsites.json内存缓存（1小时TTL）
+
+#### 前端集成
+- **ModelFormDialog组件**：集成squig.link导入功能
+- **自动填充**：抓取成功后自动填充品牌、型号、佩戴方式等字段
+- **候选选择**：多文件匹配时提供选择对话框
+- **实时预览**：显示数据URL便于验证
+
+**新增** 完整的squig.link外部数据源支持
+
+**章节来源**
+- [backend/src/routes/models.js:307-369](file://backend/src/routes/models.js#L307-L369)
+- [backend/src/services/squiglink.js:1-322](file://backend/src/services/squiglink.js#L1-L322)
+- [frontend/src/views/model/components/ModelFormDialog.vue:158-464](file://frontend/src/views/model/components/ModelFormDialog.vue#L158-L464)
+
 ## 依赖分析
- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互
+- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互，**新增squiglink服务依赖**
 - 模型依赖：Model.js 依赖Sequelize ORM
 - 前端依赖：frontend/src/api/model.js 依赖通用请求封装
+- **服务依赖**：squiglink.js 依赖axios、logger，提供外部数据源抓取功能

 ```mermaid
 graph LR
@@ -309,25 +378,30 @@ R["models.js"] --> M["Model.js"]
 R --> V["model.js(Zod)"]
 R --> U["response.js"]
 R --> A["auth.js"]
+R --> S["squiglink.js"]
 R -. 外部 .-> MS["Meilisearch"]
 R -. 外部 .-> S3["S3存储"]
+S -. 外部 .-> SL["squig.link"]
 ```

-图表来源
- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+**图表来源**
+- [backend/src/routes/models.js:1-659](file://backend/src/routes/models.js#L1-L659)
 - [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
 - [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+- [backend/src/services/squiglink.js:1-322](file://backend/src/services/squiglink.js#L1-L322)

-章节来源
- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+**章节来源**
+- [backend/src/routes/models.js:1-659](file://backend/src/routes/models.js#L1-L659)

 ## 性能考虑
 - 分页限制：列表查询limit上限为1000，避免一次性返回过多数据
 - Meilisearch超时：查询与删除文档设置超时，防止阻塞
 - 文件上传：内存存储multer，建议在高并发场景下优化为流式处理或外部对象存储直传
 - 验证前置：使用Zod在进入数据库操作前完成字段校验，减少无效请求
+- **squig.link抓取超时**：设置15秒超时，避免外部服务影响系统性能
+- **squigsites.json缓存**：1小时TTL减少对外部服务的频繁请求

 ## 故障排除指南
 - 401 未登录/无效凭证：检查Authorization头是否为Bearer Token且有效
@@ -336,12 +410,15 @@ R -. 外部 .-> S3["S3存储"]
 - 重复型号：创建/更新时如提示品牌+型号已存在，请调整参数
 - 文件格式不支持：仅允许.csv、.txt、.json，TXT会自动转换为CSV
 - Meilisearch异常：检查服务连通性与API密钥
+- **squig.link抓取失败**：检查share_url格式、网络连通性、目标站点可用性
+- **squig.link文件下载失败**：确认文件存在、权限正确、支持的文件后缀

-章节来源
+**章节来源**
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
 - [backend/src/routes/models.js:314-317](file://backend/src/routes/models.js#L314-L317)
 - [backend/src/routes/models.js:322-325](file://backend/src/routes/models.js#L322-L325)
 - [backend/src/routes/models.js:450-455](file://backend/src/routes/models.js#L450-L455)
+- [backend/src/services/squiglink.js:33-47](file://backend/src/services/squiglink.js#L33-L47)

 ## 结论
-型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略，并在删除型号前做好OTA关联清理。
+型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。**最新更新**：新增squig.link外部数据源支持，显著提升了型号数据的获取效率和准确性。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略、**squig.link抓取的超时与缓存策略**，并在删除型号前做好OTA关联清理。