# 代码质量评估报告 & 修复清单

> 生成时间：2026-03-05  
> 状态说明：⬜ 待处理 | 🔧 进行中 | ✅ 已完成

---

## P0 - 致命级（立即处理）

### 1. ~~API 密钥/密码硬编码~~ （用户决定：暂不处理）

**问题**：敏感凭证直接写在源码中，已泄露到 Git 历史。

| 文件 | 行号 | 泄露内容 |
|------|------|----------|
| `services/service_gemini.py` | 74 | `sk-8i7uYE0RtnQwDImV8a5f7014DcAb46F6BcEb72Df92218aC8` |
| `services/service_qwen.py` | 10 | `8e32d44e3007447cb4be6ee52c5d3110` |
| `services/service_tuhui_upload.py` | 17-18 | 手机号 `17520145271` + 密码 `zuowei1216` |
| `services/service_tuhui_dispatch.py` | 16 | `tuhui_dispatch_key_2026` |

**修复步骤**：
1. 在服务商后台轮换所有泄露的密钥
2. 改为从环境变量读取，移除默认值
3. 清理 Git 历史（可选，但推荐）

---

### 2. ~~服务器 IP 硬编码~~ （用户决定：暂不处理）

**问题**：生产服务器地址硬编码。

| 文件 | 行号 | 硬编码内容 |
|------|------|------------|
| `services/service_tuhui_dispatch.py` | 15 | `http://1.12.50.92:8005` |
| `services/dispatch_service.py` | 15 | `http://1.12.50.92:8006` |

**修复**：改为纯环境变量，不提供默认值或使用 `localhost`。

---

## P1 - 架构问题（本周处理）

### 3. ✅ run.py 引用了不存在的模块

**问题**：`run.py:66` 中 `run_tianwang()` 函数导入了 `core.websocket_client`，但该模块不存在（只有 `websocket_client_v2`）。

**修复**：已改为 `from core.websocket_client_v2 import QingjianAPIClient`

---

### 4. ✅ 测试文件引用不存在的模块

**问题**：5 个测试文件导入了不存在的 `core.websocket_client`。

**修复**：全部改为 `from core.websocket_client_v2 import QingjianAPIClient`

---

### 5. ✅ legacy 目录冗余（84 文件，15MB）

**问题**：`legacy/` 目录包含 84 个已被 `core/` 替代的旧文件，全部被 git 跟踪。

**修复**：已执行 `git rm -r legacy/`

---

### 6. ⬜ 全局变量泛滥（17 处）

**问题**：大量使用 `global` 声明，导致难以测试和依赖注入。

| 文件 | 全局变量 |
|------|----------|
| `utils/image_queue.py` | `_semaphore`, `_max_concurrent`, `_max_queue`, `_queue_size` |
| `utils/health_check.py` | `_qingjian_connected`, `_wechat_ok`, `_last_alert_at` |
| `utils/content_filter.py` | `_COMPILED` |
| `services/service_tuhui_dispatch.py` | `_client` |
| `services/service_meitu.py` | `_service_stats` |
| `services/service_tuhui_upload.py` | `_tuhui_service` |
| `db/task_db/task_model.py` | `_task_manager` |
| `core/task_scheduler.py` | `_scheduler` |
| `core/task_trigger.py` | `_trigger_engine` |
| `core/workflow_router.py` | `_router` |
| `core/orchestrator.py` | `orchestrator` |
| `api/http_server.py` | `task_manager`, `task_scheduler` |

**修复**：改为类实例或依赖注入模式（长期重构）。

---

### 7. ⬜ God Class: customer_db.py（802 行）

**问题**：`CustomerProfile` 有 100+ 字段，`CustomerDatabase` 承担 5+ 种职责。

**修复**：拆分为：
- `customer_profile.py` — 数据模型
- `customer_repository.py` — CRUD
- `pricing_service.py` — 报价相关
- `risk_profile.py` — 风控相关

---

### 8. ~~下载函数重复实现（4 处）~~ （已移至 _archive，暂不处理）

| 文件 | 函数 |
|------|------|
| `image/image_tools.py:15` | `async def _download(url)` |
| `image/image_processor.py:22` | `async def _download(self, url)` |
| `services/service_meitu.py` | `async def _download_result(...)` |
| `services/service_vectorizer.py` | `async def _download_result(...)` |

**状态**：`image/` 目录已移至 `_archive/image/`，待后续需要时再重构。

---

## P2 - 代码质量（两周内处理）

### 9. ✅ 吞异常 `except: pass`（11 处）

**问题**：关键错误被静默忽略。

**修复**：
- `core/orchestrator.py:109` - 已添加 `logger.warning`
- `core/adapters/qianniu_adapter.py:29` - 已添加 `logger.warning`
- 其他位置（db 和 json 解析）属于合理的 fallback 模式，保留

---

### 10. ⬜ TODO/FIXME 残留（7 处）

| 文件 | 行号 | 内容 |
|------|------|------|
| `core/task_scheduler.py` | 141 | `# TODO: 实现 send_file 方法` |
| `core/task_scheduler.py` | 214 | `# TODO: 实现天网回调 API` |
| `core/engine.py` | 28 | `# TODO: 接入重构后的 Single Agent` |
| `api/http_server.py` | 236 | `# TODO: 实现其他状态查询` |
| `scripts/multi_process_launcher.py` | 107 | `# TODO: 从数据库加载活跃客户列表` |

**修复**：要么实现，要么删除并记录到 issue tracker。

---

### 11. ✅ 魔数散落各处

**修复**：已提取为命名常量
- `core/orchestrator.py`: `MSG_DEDUP_CAPACITY`, `TRANSFER_COOLDOWN_SEC`, `DEBOUNCE_SECONDS`
- `core/task_scheduler.py`: `TIMEOUT_CHECK_INTERVAL_SEC`, `ERROR_RETRY_DELAY_SEC`, `QUEUE_POLL_INTERVAL_SEC`

---

## P3 - 杂项清理

### 12. ✅ 根目录存在名为 `=` 的空文件

**修复**：已删除

---

### 13. ✅ `__pycache__` 缓存未清理

**问题**：磁盘上有 10 个 `__pycache__` 目录（虽然已被 gitignore）。

**修复**：已清理所有 `__pycache__` 目录

---

### 14. ✅ requirements.txt 版本约束过松

**问题**：`pydantic-ai>=0.0.20` 导致安装了 1.63.0，API 不兼容。

**修复**：已改为 `pydantic-ai>=0.0.20,<2.0.0`

---

## 修复进度追踪

| 优先级 | 总数 | 已完成 | 跳过 | 进度 |
|--------|------|--------|------|------|
| P0 | 2 | 0 | 2 | - |
| P1 | 6 | 3 | 0 | 50% |
| P2 | 3 | 2 | 0 | 67% |
| P3 | 3 | 3 | 0 | 100% |
| **合计** | **14** | **8** | **2** | **67%** |

---

## 修复记录

### 2026-03-05
- 创建评估文档
- ✅ 修复 `pydantic_ai_agent_v2.py` 中 `result.data` → `result.output` 的兼容性问题（"在呢铁子"bug）
- ✅ 修复 `run.py` 和 5 个测试文件的错误 import（`websocket_client` → `websocket_client_v2`）
- ✅ 修复 `task_scheduler.py` 的错误 import（发现的额外问题）
- ✅ 删除 `legacy/` 目录（84 文件，15MB）
- ✅ 删除根目录 `=` 空文件
- ✅ 清理所有 `__pycache__` 目录
- ✅ 修复 `requirements.txt` 版本约束
- ✅ 修复吞异常问题（`orchestrator.py`, `qianniu_adapter.py`）
- ✅ 提取魔数为命名常量（`orchestrator.py`, `task_scheduler.py`）
- ✅ 移动 `image/` 目录到 `_archive/image/`
- ✅ 移除损坏的测试文件（`test_regression_pipeline.py`, `test_rule_engine.py`）

---

## 待处理（长期重构）

以下项目需要更大范围重构，标记为长期任务：

- **P1 #6** 全局变量泛滥（17 处）→ 依赖注入重构
- **P1 #7** God Class customer_db.py（802 行）→ 领域拆分
- **P1 #8** 下载函数重复实现（4 处）→ 抽取公共模块
- **P2 #10** TODO/FIXME 残留（7 处）→ 实现或移入 issue tracker