全新的前端ui

2026-07-16 16:34:18 +08:00
parent 1a9003261d
commit e59d9c72ee
352 changed files with 39009 additions and 196 deletions
@@ -17,10 +17,10 @@

 ## 更新摘要
 **变更内容**
- 新增测量文件S3自动迁移功能，当更新型号的路径相关字段时自动迁移现有CSV文件
- 增强型号更新接口的智能文件处理逻辑
- 实现S3服务端文件复制与删除操作，确保数据一致性
- 优化型号管理流程，减少手动文件干预需求
+- 后端API层进行了小幅调整，优化了数据验证和错误处理逻辑
+- 数据建模层的重要修复，改进了字段约束和数据完整性检查
+- 增强了型号CRUD操作的健壮性和一致性保障
+- 完善了异常处理和日志记录机制

 ## 目录
 1. [简介](#简介)
@@ -34,18 +34,18 @@
 9. [结论](#结论)

 ## 简介
-本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。**最新更新**：新增squig.link外部数据源支持及测量文件S3自动迁移功能，显著提升型号数据管理的自动化程度和数据一致性保障。
+本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。**最新更新**：基于后端API层的小幅调整和数据建模层的重要修复，进一步提升了系统的稳定性和数据一致性保障。

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

 ```mermaid
 graph TB
@@ -85,15 +85,15 @@ MS -. 存储 .-> S3["S3对象存储"]
 - [frontend/src/views/model/components/ModelFormDialog.vue:1-555](file://frontend/src/views/model/components/ModelFormDialog.vue#L1-L555)

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

 **章节来源**
 - [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
@@ -107,7 +107,7 @@ MS -. 存储 .-> S3["S3对象存储"]
 - [frontend/src/views/model/components/ModelFormDialog.vue:158-464](file://frontend/src/views/model/components/ModelFormDialog.vue#L158-L464)

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

 ```mermaid
 sequenceDiagram
@@ -225,18 +225,16 @@ datetime create_at
 - 内容类型：multipart/form-data
 - 表单字段：
  - measurement_file：频响文件（CSV/TXT/JSON），可选
-  - **squiglink_csv**：squig.link抓取的CSV内容，可选
+  - squiglink_csv：squig.link抓取的CSV内容，可选
  - brand_name、name、form、rig、source、eq_key
 - 文件处理：
-  - **优先级**：squiglink_csv > measurement_file > 无文件
+  - 优先级：squiglink_csv > measurement_file > 无文件
  - TXT文件自动转换为CSV
  - 仅允许.csv、.txt、.json
  - 上传至S3，键值包含source、form、brand_name、name
 - 成功响应：创建后的型号信息
 - 异常响应：重复、格式不支持、通用错误

-**更新** 新增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)
@@ -250,12 +248,10 @@ datetime create_at
 - 路径参数：model_id（整数）
 - 表单字段：同创建，支持部分字段更新（传入'null'表示保持原值）
 - 文件处理：同创建，若上传需提供source与form
- **智能文件迁移**：当未上传新文件且路径相关字段（source、form、brand_name、name）发生变更时，系统自动将现有CSV文件从旧路径迁移到新路径
+- 智能文件迁移：当未上传新文件且路径相关字段（source、form、brand_name、name）发生变更时，系统自动将现有CSV文件从旧路径迁移到新路径
 - 成功响应：更新后的型号信息
 - 异常响应：未找到、重复、格式不支持、通用错误

-**新增** 智能S3文件自动迁移功能，确保数据一致性与完整性
-
 **章节来源**
 - [backend/src/routes/models.js:439-535](file://backend/src/routes/models.js#L439-L535)
 - [backend/src/validators/model.js:12-19](file://backend/src/validators/model.js#L12-L19)
@@ -322,10 +318,10 @@ string model
  - 输出：推送成功数量、任务ID与推送数据

 **章节来源**
- [backend/src/routes/models.js:565-665](file://backend/src/routes/models.js#L565-L665)
+- [backend/src/routes/models.js:565-665](file://backend/src/routes/models.js#L565-665)

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

 **章节来源**
@@ -349,30 +345,28 @@ string model
  - share_url：squig.link分享链接（必填）
  - selected_file：用户选择的特定文件名（可选）
 - 功能特性：
-  - **自动抓取**：根据share_url自动解析并抓取频响数据
-  - **候选选择**：当存在多个匹配文件时，返回候选列表供用户选择
-  - **直接下载**：当提供selected_file时，直接下载指定文件
-  - **佩戴方式检测**：从squigsites.json自动检测佩戴方式
+  - 自动抓取：根据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）
+- 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外部数据源支持
+- ModelFormDialog组件：集成squig.link导入功能
+- 自动填充：抓取成功后自动填充品牌、型号、佩戴方式等字段
+- 候选选择：多文件匹配时提供选择对话框
+- 实时预览：显示数据URL便于验证

 **章节来源**
 - [backend/src/routes/models.js:307-369](file://backend/src/routes/models.js#L307-369)
@@ -382,17 +376,17 @@ string model
 ### S3文件自动迁移功能

 #### 智能文件迁移机制
- **触发条件**：更新型号时未上传新文件且路径相关字段发生变更
- **路径字段**：source（来源）、form（佩戴方式）、brand_name（品牌名）、name（型号名）
- **迁移策略**：服务端直接复制后删除，无需下载再上传
- **原子操作**：复制成功后才删除旧文件，确保数据完整性
+- 触发条件：更新型号时未上传新文件且路径相关字段发生变更
+- 路径字段：source（来源）、form（佩戴方式）、brand_name（品牌名）、name（型号名）
+- 迁移策略：服务端直接复制后删除，无需下载再上传
+- 原子操作：复制成功后才删除旧文件，确保数据完整性

 #### S3存储服务功能
- **文件路径构建**：autoeq/measurements/{source}/data/{form}/{brandFirstChar}/{brand model}.csv
- **上传服务**：uploadMeasurementToS3 - 支持CSV文件上传到S3
- **读取服务**：getMeasurementFromS3 - 从S3读取CSV文件内容
- **迁移服务**：moveMeasurementOnS3 - 实现S3文件的智能迁移
- **路径生成**：buildMeasurementKey - 根据参数生成标准S3 Key
+- 文件路径构建：autoeq/measurements/{source}/data/{form}/{brandFirstChar}/{brand model}.csv
+- 上传服务：uploadMeasurementToS3 - 支持CSV文件上传到S3
+- 读取服务：getMeasurementFromS3 - 从S3读取CSV文件内容
+- 迁移服务：moveMeasurementOnS3 - 实现S3文件的智能迁移
+- 路径生成：buildMeasurementKey - 根据参数生成标准S3 Key

 #### 迁移流程详解
 ```mermaid
@@ -414,26 +408,24 @@ K --> L
 ```

 **图表来源**
- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-L509)
+- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-509)
 - [backend/src/services/measurementStorage.js:116-157](file://backend/src/services/measurementStorage.js#L116-L157)

 #### 错误处理与日志记录
- **文件不存在**：跳过迁移并记录日志，不影响更新操作
- **网络异常**：抛出明确错误信息，便于问题排查
- **权限问题**：详细的错误描述，指导权限配置
- **路径冲突**：自动检测路径变化，避免不必要的操作
-
-**新增** 完整的S3文件自动迁移功能，提升数据管理自动化水平
+- 文件不存在：跳过迁移并记录日志，不影响更新操作
+- 网络异常：抛出明确错误信息，便于问题排查
+- 权限问题：详细的错误描述，指导权限配置
+- 路径冲突：自动检测路径变化，避免不必要的操作

 **章节来源**
- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-L509)
+- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-509)
 - [backend/src/services/measurementStorage.js:110-165](file://backend/src/services/measurementStorage.js#L110-L165)

 ## 依赖分析
- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互，**新增squiglink服务依赖与measurementStorage服务依赖**
+- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互，新增squiglink服务依赖与measurementStorage服务依赖
 - 模型依赖：Model.js 依赖Sequelize ORM
 - 前端依赖：frontend/src/api/model.js 依赖通用请求封装
- **服务依赖**：squiglink.js 依赖axios、logger，提供外部数据源抓取功能；measurementStorage.js 依赖AWS SDK、logger，提供S3存储服务
+- 服务依赖：squiglink.js 依赖axios、logger，提供外部数据源抓取功能；measurementStorage.js 依赖AWS SDK、logger，提供S3存储服务

 ```mermaid
 graph LR
@@ -466,10 +458,10 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - Meilisearch超时：查询与删除文档设置超时，防止阻塞
 - 文件上传：内存存储multer，建议在高并发场景下优化为流式处理或外部对象存储直传
 - 验证前置：使用Zod在进入数据库操作前完成字段校验，减少无效请求
- **squig.link抓取超时**：设置15秒超时，避免外部服务影响系统性能
- **squigsites.json缓存**：1小时TTL减少对外部服务的频繁请求
- **S3迁移优化**：服务端直接复制，避免网络传输开销，提高迁移效率
- **路径变更检测**：智能判断是否需要迁移，避免不必要的S3操作
+- squig.link抓取超时：设置15秒超时，避免外部服务影响系统性能
+- squigsites.json缓存：1小时TTL减少对外部服务的频繁请求
+- S3迁移优化：服务端直接复制，避免网络传输开销，提高迁移效率
+- 路径变更检测：智能判断是否需要迁移，避免不必要的S3操作

 ## 故障排除指南
 - 401 未登录/无效凭证：检查Authorization头是否为Bearer Token且有效
@@ -478,10 +470,10 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - 重复型号：创建/更新时如提示品牌+型号已存在，请调整参数
 - 文件格式不支持：仅允许.csv、.txt、.json，TXT会自动转换为CSV
 - Meilisearch异常：检查服务连通性与API密钥
- **squig.link抓取失败**：检查share_url格式、网络连通性、目标站点可用性
- **squig.link文件下载失败**：确认文件存在、权限正确、支持的文件后缀
- **S3迁移失败**：检查AWS凭证配置、S3 Bucket权限、网络连接状态
- **文件路径错误**：确认source、form、brand_name、name字段值符合规范
+- squig.link抓取失败：检查share_url格式、网络连通性、目标站点可用性
+- squig.link文件下载失败：确认文件存在、权限正确、支持的文件后缀
+- S3迁移失败：检查AWS凭证配置、S3 Bucket权限、网络连接状态
+- 文件路径错误：确认source、form、brand_name、name字段值符合规范

 **章节来源**
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -492,4 +484,4 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - [backend/src/services/measurementStorage.js:149-156](file://backend/src/services/measurementStorage.js#L149-L156)

 ## 结论
-型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。**最新更新**：新增squig.link外部数据源支持及测量文件S3自动迁移功能，显著提升了型号数据的获取效率和数据一致性保障。智能文件迁移机制确保了在更新型号路径相关字段时，现有CSV文件能够自动迁移到新路径，无需人工干预。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略、**squig.link抓取的超时与缓存策略**、**S3迁移的性能监控与错误处理**，并在删除型号前做好OTA关联清理。
+型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。**最新更新**：基于后端API层的小幅调整和数据建模层的重要修复，进一步提升了系统的稳定性和数据一致性保障。智能文件迁移机制确保了在更新型号路径相关字段时，现有CSV文件能够自动迁移到新路径，无需人工干预。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略、squig.link抓取的超时与缓存策略、S3迁移的性能监控与错误处理，并在删除型号前做好OTA关联清理。