# 后端代码改进工作记录

> 基于 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 防护失效 | ⏸️ 搁置 | 鉴权相关，暂不处理 |