Ascend/SmartMeeting
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
SmartMeeting/speakr/docs/rework-notes/backend-improvement-log.md

7.6 KiB
Raw Blame History

后端代码改进工作记录

基于 2026-06-23 的代码审查，记录所有发现的问题及处理状态。 注：问题编号与分析报告一致。

一、暂不处理（鉴权相关，后续配合主系统调整）

编号 问题 原因
#1 auto_login() 完全绕过认证 鉴权在主系统完成，我们是补充子系统
#2 未认证接口泄露敏感数据 同上
#4 CSRF 防护全局失效 同上

二、已处理

#8 recording.py 下载接口重复代码抽取

  • 状态: ✅ 已完成
  • 文件: src/services/document_service.py、src/api/recording.py
  • 修复: 抽取 add_unicode_paragraph() / create_docx_with_unicode_title() / save_and_send_docx() 到 document_service.py，4 个下载接口共减少约 280 行重复代码

#9 recording.py 大文件拆分

  • 状态: ✅ 已完成
  • 文件: src/api/recording_download.py（新建）
  • 修复: 下载路由拆分到独立蓝图 recording_download_bp，recording.py 从 1610 行降至约 1330 行；在 api/__init__.py 统一注册

#3 字段名不匹配 Bug：error_msg vs error_message

  • 状态: ✅ 已完成
  • 文件: src/services/transcription_service.py:202, :581
  • 问题: 模型字段是 error_message，service 写入 recording.error_msg（不存在的属性），错误信息丢失
  • 修复: 两处 error_msg 改为 error_message

#10 错误处理不一致且泄露内部异常

  • 状态: 🔴 已还原（撤销全局错误处理器和 api_response.py）
  • 文件: src/api/ 下所有蓝图文件
  • 问题: 51 处 return jsonify({'error': str(e)}), 500 把内部异常暴露给客户端
  • 处理: 曾创建 api_response.py 和全局错误处理器替换，但用户认为全局错误处理器不需要，已还原
  • 后续: 等 #11 统一返回和日志方案重新设计后再处理

#5 硬编码默认密钥（仅警告）

  • 状态: ✅ 已完成（报警告，不阻止启动）
  • 文件: src/config.py:17, :73
  • 处理: validate_config() 已有警告逻辑，get_app_config() 中保留默认值但启动时打印警告

#15 LLM/Voiceprint 客户端无超时和重试

  • 状态: ✅ 已完成
  • 文件: src/clients/llm_client.py、src/clients/voiceprint_client.py
  • 修复:
    • llm_client: 添加 httpx.Timeout(connect=10, read=300, write=60, pool=30)，print() 改为 logging
    • voiceprint_client: 改用持久化 httpx.Client 复用连接池，添加指数退避重试（3次），细化异常类型

#16 双入口文件端口不一致

  • 状态: ✅ 已完成
  • 文件: src/app.py
  • 修复: 端口和 debug 模式从环境变量 FLASK_PORT / FLASK_DEBUG 读取，默认 5000 / false

#20 config.py 循环依赖风险

  • 状态: ✅ 已完成
  • 文件: src/config.py、src/app.py、src/services/register.py
  • 修复: get_app_config() 移除对 src.clients 的导入；新增 init_early_services() 在蓝图注册前初始化 chunking_service 和 EMBEDDINGS_AVAILABLE

#21 admin.py 绕过 config 直接读 os.environ

  • 状态: ✅ 已完成
  • 文件: src/api/admin.py:466-470、src/config.py
  • 修复: 自动处理配置项（ENABLE_AUTO_PROCESSING 等 5 项）移入 config.py；admin.py 从 current_app.config 读取

三、标记待做（高优先级）

#11 统一错误返回格式

  • 状态: 🔴 已还原（撤销全局错误处理器和 api_response.py）
  • 处理: 曾创建 api_response.py 和全局错误处理器，但已还原；后续需重新设计统一返回和日志方案
  • 优先级: 高（在 #6/#7/#12 之前）

#19 统一日志格式

  • 状态: ✅ 已完成
  • 修复:
    • src/config.py: print() 改为 logging.warning()
    • src/clients/llm_client.py: print() 改为 logging.info() / logging.error()
    • src/api/draft_api.py: 约 20 条英文日志全部改为中文
    • src/services/llm_service.py: 约 15 条英文/混杂日志全部改为中文，语义更清晰
    • src/services/audio_chunking.py: 约 40 条英文日志全部改为中文，统计和建议部分语义优化
    • 所有日志语言统一为中文，语义表达便于调试

四、标记待做（性能优化，有空再处理）

#6 N+1 查询优化

  • 文件: src/api/admin.py:81-93, :645-652、src/models/recording.py:38-64
  • 问题: admin 接口和 to_dict 列表场景存在 N+1 查询
  • 处理: 标记，当前系统规模无性能问题，有空再优化
  • 优先级: 中

#7 后台线程管理优化

  • 文件: src/api/recording.py 多处 threading.Thread
  • 问题: 无线程池、无任务队列、无重试
  • 处理: 标记，当前无并发压力，后续引入 ThreadPoolExecutor 或 Celery
  • 优先级: 中（与 #6 一致）

#12 缺少输入校验

  • 问题: POST/PUT 接口缺少 email 格式、密码强度、字段长度等校验
  • 处理: 标记，后续引入 marshmallow/pydantic
  • 优先级: 中（与 #6/#7 一致）

#13 sync_service.py 每轮循环重建 engine（PostgreSQL）

  • 文件: src/services/sync_service.py:78
  • 问题: create_engine 在循环内每次重建，连接泄漏
  • 优先级: 高（与 #11 一致，数据库返工）

#14 数据库迁移仅支持 SQLite（PostgreSQL）

  • 文件: src/services/register.py:130-161
  • 问题: PRAGMA table_info 是 SQLite 专有，PostgreSQL 上不执行
  • 优先级: 高（与 #11 一致，数据库返工）

#17 缺失数据库索引（PostgreSQL）

  • 文件: src/models/recording.py 等
  • 问题: 关键列无 index=True，PostgreSQL 不会自动建索引
  • 优先级: 高（与 #11 一致，数据库返工）

#18 datetime 时区不一致（PostgreSQL）

  • 文件: 多模型和 API 混用 datetime.now / datetime.utcnow
  • 问题: 跨时区部署时时间错乱
  • 优先级: 高（与 #11 一致，数据库返工）

进度追踪

编号 问题 状态 备注
#8 下载接口重复代码抽取 ✅ 已完成 优先级最高，已处理
#9 大文件拆分 ✅ 已完成 优先级最高，已处理
#3 error_msg 字段名修复 ✅ 已完成 可改，已处理
#10 错误处理统一 🔴 已还原 全局错误处理器不需要，已撤销
#5 硬编码密钥警告 ✅ 已完成 仅警告，已处理
#15 客户端超时和重试 ✅ 已完成 同 #3/#10 优先级
#16 双入口文件端口 ✅ 已完成 同 #3/#10 优先级
#20 config.py 循环依赖 ✅ 已完成 同 #3/#10 优先级
#21 admin.py 绕过 config ✅ 已完成 同 #3/#10 优先级
#11 统一错误返回格式 🟡 部分完成 高优先级，需完善日志
#19 统一日志格式 ✅ 已完成 高优先级，已处理
#13 sync_service engine 复用 📋 待做 中优先级，数据库返工
#14 数据库迁移跨库兼容 📋 待做 中优先级，数据库返工
#17 数据库索引 📋 待做 中优先级，数据库返工
#18 时区统一 📋 待做 中优先级，数据库返工
#6 N+1 查询优化 📋 待做 中优先级，优化
#7 后台线程管理 📋 待做 中优先级，优化
#12 输入校验 📋 待做 中优先级，优化
#1 认证绕过 ⏸️ 搁置 鉴权相关，暂不处理
#2 未认证接口泄露数据 ⏸️ 搁置 鉴权相关，暂不处理
#4 CSRF 防护失效 ⏸️ 搁置 鉴权相关，暂不处理