架构设计文档

1. 整体架构图

TrailSnap 采用典型的前后端分离架构，由前端展示层、后端服务层和数据存储层组成。

2. 技术选型及版本

2.1 前端技术栈

2.2 后端技术栈

• 编程语言: Python 3.12+
• Web 框架: FastAPI 0.122.0
• ASGI 服务器: Uvicorn 0.38.0
• ORM: SQLAlchemy 2.0.44
• 数据库迁移: Alembic 1.17.2
• 数据库驱动: psycopg2 (PostgreSQL)
• 任务/异步: APScheduler、aiohttp
• AI/CV (AI 微服务):
  • PaddleOCR ==3.3.2
  • PaddlePaddle-GPU ==3.2.0（可选 GPU）
  • OpenCV opencv-python-headless >=4.9.0
  • Torch >=2.0.0、TorchVision >=0.15.0（部分模型可用）
  • InsightFace（人脸）
• 日志: 自定义 JSON 队列日志 + 按日容量滚动（server 与 ai 均内置）

2.3 数据库

• PostgreSQL: 关系型数据库，存储用户、相册、照片元数据、系统设置等。

3. 目录结构与模块说明

3.1 根目录

• package/server: 后端服务代码
• package/website: 前端应用代码
• doc: 项目文档

3.2 后端结构 (package/server)

• app/: 核心应用代码
  • api/: API 路由定义 (EndPoints)，按功能模块划分 (user, album, photo, etc.)
  • core/: 核心配置与工具 (Logger, Config)
  • crud/: 数据库 CRUD 操作封装
  • db/: 数据库模型 (Models) 与会话管理 (Session)
  • schemas/: Pydantic 数据模型 (Request/Response schemas)
  • service/: 复杂业务逻辑与后台服务 (TaskManager, Indexer, Storage)
  • utils/: 通用工具函数 (Exif解析, 文件名处理)
• railway/: 铁路相关功能模块 (独立的数据处理与同步逻辑)
• yolo_ocr/: OCR 与票据识别相关模型与脚本
• main.py: 应用入口，路由挂载、CORS、中间件与端口配置（默认 :8000）

3.3 前端结构 (package/website)

• src/: 源代码
  • api/: 后端接口封装
  • assets/: 静态资源 (图片, CSS)
  • components/: 通用 Vue 组件 (PhotoGallery, TrainTicket, etc.)
  • composables/: 组合式函数 (Hooks)
  • layouts/: 页面布局组件
  • router/: 路由配置
  • stores/: Pinia 状态管理仓库
  • types/: TypeScript 类型定义
  • views/: 页面视图 (Pages)
  • package.json: 依赖与版本管理，内含脚本 dev/build/preview

3.4 AI 微服务结构 (package/ai)

• app/main.py: AI 服务入口（默认 :8001），挂载 ocr/face/object-detection/tickets 路由
• app/services/: 模型服务（ocr_service.py、face_service.py、model_manager.py 懒加载与资源释放）
• app/core/logger.py: JSON 队列日志，按日容量滚动
• requirements.txt: 依赖与版本约束（PaddleOCR、PaddlePaddle-GPU、Torch、OpenCV 等）

4. 关键交互与调用链