ljwx-shiti/docs/RISK_VERIFICATION.md

项目风险验证清单

本文档列出了项目中已识别的风险点及其修订措施和验证方法。

🔴 Critical 风险（已修复）

1. Python + PaddleOCR 依赖冲突

原风险: Python 3.12+ 与 PaddleOCR 存在兼容性问题

修订措施:

• 使用 Python 3.11
• PaddleOCR 作为可选依赖（[paddle] extra）
• 提供纯规则降级路径

验证方法:

# 不安装 paddle 也能成功
pip install -e "."

# ENABLE_PADDLE_OCR=false 时降级到规则切分
ENABLE_PADDLE_OCR=false pytest tests/test_block_cutter.py -v

验证标准: ✅ 不安装 PaddleOCR 时，系统仍能正常运行

---

2. 测试数据库配置不明确

原风险: conftest.py 配置含糊，测试可能污染开发数据库

修订措施:

• docker-compose 中独立的 postgres-test（端口 5433）
• 使用 tmpfs，测试后自动清理
• 每个测试用事务包裹并 rollback

验证方法:

# 启动测试数据库
docker compose up -d postgres-test

# 运行测试
cd backend && pytest -v

# 验证测试数据库独立
psql -h localhost -p 5433 -U wrongbook -d wrongbook_test -c "SELECT count(*) FROM wrong_questions;"

验证标准: ✅ 测试运行在独立数据库，不影响开发数据

---

3. Celery + async 代码混用

原风险: Celery task 内直接调用 async 代码会导致 event loop 错误

修订措施:

• 使用 asyncio.run() 包装 async 代码
• 在 Celery prefork 模式下创建新的 event loop

验证方法:

# 运行 Celery 任务测试
cd backend && pytest tests/test_tasks.py -v

# 验证不会出现 event loop 重入错误

验证标准: ✅ Celery task 能正确调用 async 代码，无 event loop 错误

---

4. WebSocket 鉴权不安全

原风险: /ws/{user_id} 路径暴露用户 ID，无鉴权

修订措施:

• 改为 /ws?token=<jwt_token>
• JWT query parameter 鉴权
• 鉴权失败返回 close(4001)

验证方法:

# 运行 WebSocket 测试
cd backend && pytest tests/test_websocket.py -v

# 测试场景：
# 1. 无 token → 连接被拒
# 2. 错误 token → 连接被拒（code=4001）
# 3. 正确 token → 连接成功

验证标准: ✅ 无有效 JWT 无法建立 WebSocket 连接

---

5. Elasticsearch 形同虚设

原风险: docker-compose 中有 ES 但未使用，增加复杂度

修订措施:

• 删除 Elasticsearch
• 使用 PostgreSQL tsvector 全文检索
• 减少一个故障点

验证方法:

# 验证 docker-compose 中无 ES 服务
docker compose config | grep -i elasticsearch
# 应该无输出

# 验证全文检索使用 tsvector
cd backend && pytest tests/test_questions_api.py::test_search_by_keyword -v

验证标准: ✅ 全文检索功能正常，无 ES 依赖

---

6. Flutter 鸿蒙适配阻断构建

原风险: 要求三端（Android/iOS/HarmonyOS）同时跑通

修订措施:

• 只声明 android + ios 平台
• 鸿蒙作为占位接口，不阻断构建
• PlatformService 抽象层，鸿蒙方法抛 UnimplementedError

验证方法:

# Flutter 分析应该通过
cd app && flutter analyze

# 构建 Android 应该成功
cd app && flutter build apk --debug

验证标准: ✅ flutter analyze 在 android+ios 平台通过

---

🟡 Important 风险（已修复）

7. AI 调用不可追溯

原风险: 无法追溯 AI 调用历史，难以调试和优化

修订措施:

• 新增 ai_invocation_logs 表
• 记录：model_name, prompt_version, input_hash, output_json
• 每次 AI 调用自动记录

验证方法:

# 运行 AI 调用测试
cd backend && pytest tests/test_sonnet_recognizer.py -v

# 验证日志记录
psql -h localhost -p 5432 -U wrongbook -d wrongbook -c "SELECT count(*) FROM ai_invocation_logs;"

验证标准: ✅ 每次 AI 调用都有日志记录

---

8. 全局异常处理缺失

原风险: 异常未统一处理，返回格式不一致

修订措施:

• middleware.py 中实现 RequestIdMiddleware
• register_exception_handlers 统一处理异常
• 所有错误返回统一格式：{"code": xxx, "data": null, "message": "xxx"}
• structlog 记录所有异常，带 request_id

验证方法:

# 运行异常处理测试
cd backend && pytest tests/test_middleware.py -v

# 验证所有错误返回统一格式

验证标准: ✅ 所有错误返回统一格式，日志可通过 request_id 串联

---

9. 图片存储不安全

原风险: 数据库存储裸 URL，可能泄露或失效

修订措施:

• 数据库只存 object_key
• API 返回时生成 presigned URL
• URL 有效期可配置（默认 1 小时）

验证方法:

# 运行存储测试
cd backend && pytest tests/test_storage.py -v

# 验证 API 返回 presigned URL
curl -H "Authorization: Bearer <token>" http://localhost:8000/api/v1/questions/1
# 响应中的图片字段应该是 presigned URL

验证标准: ✅ API 返回 presigned URL，URL 有时效性

---

10. AI 模型名硬编码

原风险: 模型名硬编码在代码中，难以切换

修订措施:

• 所有 AI 配置放在 .env 中
• ANTHROPIC_MODEL, ANTHROPIC_TEMPERATURE 等可配置
• prompt 模板放在 backend/app/prompts/ 目录

验证方法:

# 验证配置可读取
cd backend && python -c "from app.config import settings; print(settings.ANTHROPIC_MODEL)"

# 验证 prompt 模板独立文件
ls backend/app/prompts/

验证标准: ✅ AI 配置可通过环境变量修改

---

验证矩阵总览

风险项	严重程度	状态	验证命令
Python+PaddleOCR	🔴 Critical	✅ 已修复	pip install -e "."
测试DB	🔴 Critical	✅ 已修复	pytest -v
Celery+async	🔴 Critical	✅ 已修复	pytest tests/test_tasks.py -v
WS鉴权	🔴 Critical	✅ 已修复	pytest tests/test_websocket.py -v
ES形同虚设	🔴 Critical	✅ 已修复	docker compose config
Flutter鸿蒙	🔴 Critical	✅ 已修复	flutter analyze
AI可追溯	🟡 Important	✅ 已修复	pytest tests/test_sonnet_recognizer.py -v
全局异常	🟡 Important	✅ 已修复	pytest tests/test_middleware.py -v
存储安全	🟡 Important	✅ 已修复	pytest tests/test_storage.py -v
模型名硬编码	🟡 Important	✅ 已修复	python -c "from app.config import settings; print(settings.ANTHROPIC_MODEL)"

---

完整验证流程

1. 环境准备

# 启动基础服务
docker compose up -d postgres postgres-test redis minio

# 安装依赖（不含 PaddleOCR）
cd backend && pip install -e ".[dev]"

2. 运行所有测试

# Python 代码检查
cd backend && ruff check .

# Python 测试
cd backend && pytest -v

# Flutter 分析（如果已创建）
cd app && flutter analyze

# Docker Compose 配置验证
docker compose config --quiet

3. 集成测试

# 构建并启动所有服务
docker compose build
docker compose up -d

# 等待服务启动
sleep 10

# 验证 API 可访问
curl -s http://localhost:8000/docs | head -5

# 运行集成测试
cd backend && pytest tests/test_integration.py -v

# 清理
docker compose down

4. 验证标准

所有测试通过，输出：

✅ Python lint check: PASSED
✅ Python tests: PASSED (XX tests)
✅ Flutter analyze: PASSED
✅ Docker compose config: PASSED
✅ Integration tests: PASSED

🎉 All checks passed!

---

持续验证

CI/CD 集成（未来）

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Start services
        run: docker compose up -d
      - name: Run tests
        run: |
          cd backend
          pip install -e ".[dev]"
          ruff check .
          pytest -v

定期审查

• 每周: 运行完整测试套件
• 每月: 审查 AI 调用日志，优化 prompt
• 每季度: 更新依赖版本，修复安全漏洞

---

问题反馈

如果发现任何风险点未被覆盖，请：

1. 在 GitHub Issues 中提交
2. 标注严重程度（🔴 Critical / 🟡 Important / 🟢 Nice to have）
3. 提供复现步骤
4. 建议修复方案