修改 wiki

.qoder/repowiki/zh/content/系统架构/后端架构.md

@@ -22,6 +22,13 @@
 - [backend/src/services/measurementStorage.js](file://backend/src/services/measurementStorage.js)
 </cite>
 
+## 更新摘要
+**变更内容**
+- 增强了curveClient服务的错误处理和日志记录机制
+- 提升了音频曲线API集成的可靠性和可观测性
+- 优化了外部API调用的超时配置和异常处理
+- 完善了响应数据的详细日志输出用于调试
+
 ## 目录
 1. [引言](#引言)
 2. [项目结构](#项目结构)
@@ -392,6 +399,8 @@ I --> |是| K["放行"]
 - 外部服务错误
   - S3/曲线服务捕获异常并记录日志，抛出统一错误
 
+**更新** curveClient服务增强了错误处理和日志记录机制，提升了音频曲线API集成的可靠性
+
 章节来源
 - [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [backend/src/routes/auth.js:60-64](file://backend/src/routes/auth.js#L60-L64)
@@ -485,6 +494,62 @@ App->>App : "listen(PORT)"
 - [backend/src/app.js:22-34](file://backend/src/app.js#L22-L34)
 - [backend/src/app.js:42-59](file://backend/src/app.js#L42-L59)
 
+### 音频曲线API集成增强
+
+**新增** curveClient服务经过重大增强，显著提升了音频曲线API集成的可靠性和可观测性：
+
+#### 增强的错误处理机制
+- **网络请求异常处理**：axios请求失败时记录详细的警告日志，包含完整的URL和错误信息
+- **HTTP状态码验证**：对非200状态码进行专门处理，返回明确的错误信息
+- **响应数据验证**：多层嵌套的响应数据结构解析，支持多种格式
+- **Base64解码容错**：自定义字符映射和标准Base64转换的错误处理
+- **JSON解析异常**：解码后JSON格式的验证和错误捕获
+
+#### 完善的日志记录系统
+- **请求追踪日志**：记录完整的请求参数（品牌、型号、佩戴方式、目标类型、完整URL）
+- **响应调试日志**：详细记录响应状态码、数据类型和部分响应内容（限制长度避免日志过大）
+- **错误诊断日志**：关键错误点记录原始数据片段，便于问题定位
+- **结构化日志格式**：统一的timestamp-level-message格式，支持元数据扩展
+
+#### 可靠的超时配置
+- **请求超时控制**：默认20秒超时，防止长时间阻塞
+- **连接超时保护**：Redis客户端配置10秒连接超时
+- **重试机制**：Redis操作最多重试2次
+
+```mermaid
+sequenceDiagram
+participant Client as "调用方"
+participant Curve as "curveClient.js"
+participant Axios as "Axios HTTP客户端"
+participant Logger as "日志系统"
+participant External as "外部曲线API"
+Client->>Curve : fetchAndValidateCurve()
+Curve->>Logger : 记录请求参数日志
+Curve->>Axios : GET 请求(带超时配置)
+Axios->>External : 发送HTTP请求
+External-->>Axios : 返回响应
+Axios-->>Curve : 响应数据
+Curve->>Logger : 记录响应状态和数据类型
+Curve->>Curve : 解析响应数据
+alt 解析成功
+Curve->>Curve : Base64解码
+Curve->>Curve : JSON解析
+Curve->>Curve : 验证parametric_eq结构
+Curve-->>Client : 返回验证结果
+else 解析失败
+Curve->>Logger : 记录详细错误信息
+Curve-->>Client : 返回错误信息
+end
+```
+
+图表来源
+- [backend/src/services/curveClient.js:81-138](file://backend/src/services/curveClient.js#L81-L138)
+- [backend/src/config/logger.js:10-26](file://backend/src/config/logger.js#L10-L26)
+
+章节来源
+- [backend/src/services/curveClient.js:1-147](file://backend/src/services/curveClient.js#L1-147)
+- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
+
 ## 依赖关系分析
 - 包管理与运行
   - 依赖 express、sequelize、mysql2、jsonwebtoken、winston、ioredis 等
@@ -531,6 +596,10 @@ SVC --> LOG["logger.js"]
   - 设置超时与错误处理，避免阻塞请求
 - 日志
   - 控制台与文件双通道，避免 info 级日志过多
+- 音频曲线API
+  - 合理的超时配置（20秒）防止长时间等待
+  - 响应数据截断日志避免日志过大
+  - 错误处理快速失败，不阻塞主流程
 
 ## 故障排查指南
 - 认证失败
@@ -545,15 +614,22 @@ SVC --> LOG["logger.js"]
 - S3 读取/上传失败
   - 检查凭证或 IAM 角色配置
   - 关注 NoSuchKey 等特定异常
+- **音频曲线API问题**
+  - 检查 CURVE_API_BASE_URL 环境变量配置
+  - 查看详细的请求和响应日志，特别是响应数据类型和内容
+  - 确认网络连接和防火墙设置
+  - 检查Base64编码格式是否正确
+  - 验证parametric_eq数据结构是否符合要求
 
 章节来源
 - [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
 - [backend/src/app.js:48-51](file://backend/src/app.js#L48-L51)
 - [backend/src/config/redis.js:24-26](file://backend/src/config/redis.js#L24-L26)
 - [backend/src/services/measurementStorage.js:102-107](file://backend/src/services/measurementStorage.js#L102-L107)
+- [backend/src/services/curveClient.js:92-116](file://backend/src/services/curveClient.js#L92-L116)
 
 ## 结论
-本后端以 Express 为核心，采用清晰的分层与模块化设计，结合 Sequelize、Redis 与 Winston 实现了稳定的数据访问、缓存与日志能力。认证授权、请求限制与统一响应提升了安全性与一致性。建议后续引入 API 版本前缀、完善错误分类与指标上报，持续优化数据库与缓存策略以提升整体性能与可观测性。
+本后端以 Express 为核心，采用清晰的分层与模块化设计，结合 Sequelize、Redis 与 Winston 实现了稳定的数据访问、缓存与日志能力。认证授权、请求限制与统一响应提升了安全性与一致性。**最新的curveClient服务增强显著提升了音频曲线API集成的可靠性和可观测性，通过完善的错误处理机制、详细的日志记录和合理的超时配置，确保了外部服务调用的稳定性。** 建议后续引入 API 版本前缀、完善错误分类与指标上报，持续优化数据库与缓存策略以提升整体性能与可观测性。
 
 ## 附录
 - 环境变量
@@ -563,6 +639,7 @@ SVC --> LOG["logger.js"]
   - JWT_SECRET：令牌签名密钥
   - DASHBOARD_ADMIN_*：超级管理员初始化用户名与密码
   - AWS_*：S3 区域、凭证与桶名
+  - **CURVE_API_BASE_URL：音频曲线API基础地址**
 - 路由示例
   - GET / → 根路径
   - GET /health → 健康检查
@@ -578,4 +655,5 @@ SVC --> LOG["logger.js"]
 - [backend/src/services/userBootstrap.js:9-10](file://backend/src/services/userBootstrap.js#L9-L10)
 - [backend/src/services/measurementStorage.js:9-12](file://backend/src/services/measurementStorage.js#L9-L12)
 - [backend/src/app.js:22-34](file://backend/src/app.js#L22-L34)
-- [backend/src/routes/auth.js:24-77](file://backend/src/routes/auth.js#L24-L77)
+- [backend/src/routes/auth.js:24-77](file://backend/src/routes/auth.js#L24-L77)
+- [backend/src/services/curveClient.js:8](file://backend/src/services/curveClient.js#L8)