fix: dev

GEMINI.md

@@ -0,0 +1,47 @@
+# PicPocket 后端项目核心指南 (GEMINI.md)
+
+## 1. 项目定位
+本项目是一个为微信小程序提供支撑的高性能图像处理后台，核心业务围绕“人脸评分”、“老照片修复”、“AI 抠图”和“智能图库”展开。
+
+## 2. 核心技术栈
+- **Web 框架**: FastAPI (Python 3.10+)
+- **异步处理**: `asyncio` + `ThreadPoolExecutor` (用于隔离 CV 推理等 CPU 密集型任务)
+- **图像处理**: OpenCV, NumPy, PIL
+- **AI 推理引擎**: 
+    - **人脸分析**: DeepFace (ArcFace), 自研 EnhancedFaceAnalyzer (YOLO + 颜值模型)
+    - **画质增强**: GFPGAN (修复), Real-ESRGAN (超清)
+    - **自动上色**: DDColor
+    - **智能抠图**: Rembg (通用), RVM (人像视频/图片)
+    - **风格化**: AnimeStylizer
+    - **向量检索**: CLIP (cn_clip) + Vector Store
+- **数据持久化**: MySQL (aiomysql 异步驱动)
+- **云端集成**: 百度云 BOS (对象存储), 微信内容安全接口
+
+## 3. API 路由规范 (`api_routes.py`)
+所有的 API 统一挂载在 `/facescore` 前缀下：
+
+| 接口路径 | 功能描述 | 核心逻辑/模型 |
+| :--- | :--- | :--- |
+| `/analyze` | 核心人脸分析接口 | YOLO 检测 + 颜值评分 + 年龄性别 (Hybrid 模式) |
+| `/app/analyze` | App 专用分析接口 | 在 `/analyze` 基础上增加设备信息记录 |
+| `/upload_file` | 文件上传 | 支持 `idphoto` 类型自动修复 |
+| `/check_image_security` | 安全检测 | 微信内容安全检测 |
+| `/detect_faces` | 纯人脸检测 | 快速返回 YOLO 检测框 |
+| `/image_search` | 以图搜图 | CLIP 向量相似度搜索 |
+| `/outputs` | 历史记录/搜索 | 支持分页、分类过滤及向量关键词检索 |
+| `/daily_category_stats` | 业务统计 | 统计当日各项功能的使用频率 |
+
+## 4. 关键开发守则 (必须遵守)
+- **禁止阻塞主线程**: 严禁在 `async def` 中直接进行耗时计算（如 `cv2.imread`, `model.predict`）。必须使用 `process_cpu_intensive_task`。
+- **内存与会话清理**: DeepFace 报错时应调用 `_recover_deepface_model`；频繁推理需注意显存释放。
+- **数据记录一致性**: 任何生成新文件的接口都必须通过 `_record_output_file` 异步记入数据库。
+- **安全性**: 优先执行 `check_image_security`；处理上传文件需确保 UUID 命名以防冲突。
+- **类型提示**: 所有新函数必须包含完整的 Typing 类型注解。
+
+## 5. 目录结构
+- `api_routes.py`: 所有 API 的定义与入口。
+- `face_analyzer.py`: 人脸检测与评分的核心逻辑实现。
+- `database.py`: 数据库异步操作封装。
+- `config.py`: 项目全局配置与模型开关。
+- `utils.py`: 图像保存、BOS 上传、单位转换等工具函数。
+- `*_processor.py`: 各 AI 功能模块的独立处理器。

prompt.md

@@ -1,35 +0,0 @@
-# PicPocket 后端开发核心指引 (AI Prompt)
-
-## 1. 项目定位
-本项目是一个为微信小程序提供支撑的高性能图像处理后台，核心业务围绕“人脸评分”、“老照片修复”、“AI 抠图”和“智能图库”展开。
-
-## 2. 技术栈架构
-- **框架**: FastAPI (Python 3.10+)
-- **异步处理**: `asyncio` + `ThreadPoolExecutor` (用于处理 CV 密集型任务)
-- **图像处理库**: OpenCV, PIL, NumPy
-- **AI 模型库**: 
-    - 人脸: DeepFace, InsightFace (analyzer)
-    - 修复: GFPGAN, Real-ESRGAN
-    - 上色: DDColor (ModelScope)
-    - 检索: CLIP (cn_clip), Faiss (Vector Store)
-    - 抠图: Rembg, RVM
-- **数据库**: MySQL (使用 aiomysql 异步驱动)
-- **存储**: 本地目录 + 百度云 BOS
-
-## 3. 编码规范 (必须严格遵守)
-- **异步原则**: 所有的数据库 IO、网络请求必须使用 `await`。CPU 密集型计算（如模型推理、图片加解密、复杂 OpenCV 操作）**必须**包裹在 `process_cpu_intensive_task` 或 `run_in_executor` 中执行，严禁阻塞主事件循环。
-- **日志规范**: 使用项目统一的 `logger`。关键步骤需记录 `_log_stage_duration` 以便监控耗时。
-- **内存安全**: 处理大图时注意清理显存/内存。对 DeepFace 等 Keras 模型，必要时调用 `_recover_deepface_model`。
-- **类型注解**: 函数定义必须包含完整的类型提示（Typing）。
-- **异常处理**: 业务接口需使用 `try...except` 捕获异常，并返回标准化的 `HTTPException` 或 JSON 错误响应。
-
-## 4. 核心业务逻辑点
-- **图片记录**: 每次生成/上传图片后，必须调用 `_record_output_file` 异步持久化到 MySQL。
-- **路径规则**: 原图/人脸裁剪存放在 `IMAGES_DIR`，处理后的标注图/结果图存放在 `OUTPUT_DIR`。
-- **安全性**: 涉及用户上传内容，优先调用 `wx_access_token.check_image_security`。
-- **数据结构**: 模型推理返回的 NumPy 对象在返回前端前必须经过 `convert_numpy_types` 处理，防止 JSON 序列化失败。
-
-## 5. AI 协作禁用项
-- **禁止胡编乱造**: 不确定的库用法必须要求查阅文档或询问用户。
-- **禁止破坏异步性**: 绝不允许在 FastAPI 的 `async def` 中直接运行耗时的同步计算。
-- **禁止忽略安全性**: 修改代码时不得移除现有的鉴权 (Basic Auth) 或安全检测逻辑。