# 系统架构设计文档 ## 1. 系统概述 家庭药品与应急物资管理系统（YaoXiang）是一个基于 Web 的家庭药品库存管理系统，支持 AI 自动录入、智能搜索、到期提醒等功能。系统采用前后端分离架构，支持 Docker 单容器部署。 ## 2. 技术栈 ### 前端 - **框架**: React 18+ - **语言**: TypeScript - **构建工具**: Vite - **UI 库**: Ant Design Mobile 5.x（移动端优化） - **状态管理**: Zustand - **路由**: React Router 6 - **HTTP 客户端**: Axios - **PWA**: vite-plugin-pwa ### 后端 - **框架**: FastAPI - **语言**: Python 3.11+ - **ORM**: SQLAlchemy 2.0 - **数据库迁移**: Alembic - **文件存储**: 本地文件系统 - **任务队列**: 无（采用异步任务） ### 数据库 - **主数据库**: SQLite（可升级 PostgreSQL） - **缓存**: 无（可选 Redis） ### AI Provider - **多模态模型**: OpenAI GPT-4o / Gemini / Claude - **文本模型**: DeepSeek / Ollama - **抽象层**: 统一 Provider 接口 ### 部署 - **容器化**: Docker - **编排**: Docker Compose - **反向代理**: Nginx（前端静态文件） ## 3. 系统架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端层 │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 手机浏览器 │ │ 平板浏览器 │ │ PC 浏览器 │ │ │ │ (PWA) │ │ (大屏模式) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 前端应用层 │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ React App │ │ PWA 配置 │ │ 状态管理 │ │ │ │ (Vite) │ │ Service Worker │ │ (Zustand) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 页面组件 │ │ 业务组件 │ │ API 调用层 │ │ │ │ (Router) │ │ (Ant Design)│ │ (Axios) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API 通信层 │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────────┐ │ │ │ RESTful API │ │ │ │ POST /api/auth/login │ │ │ │ GET /api/medicines │ │ │ │ POST /api/medicines │ │ │ │ POST /api/medicines/recognize │ │ │ │ ... │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 后端应用层 │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ FastAPI │ │ 路由层 │ │ 中间件 │ │ │ │ (Router) │ │ (APIRouter)│ │ (Auth) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 服务层 │ │ 数据访问层 │ │ 模型层 │ │ │ │ (Service) │ │ (Repository)│ │ (Model) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ AI Provider│ │ 通知系统 │ │ 文件存储 │ │ │ │ (Abstract) │ │ (Provider) │ │ (Local) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 数据存储层 │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ SQLite │ │ 文件系统 │ │ 缓存 │ │ │ │ (Database) │ │ (Uploads) │ │ (可选) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 4. 模块划分 ### 4.1 前端模块 ``` frontend/ ├── src/ │ ├── api/ # API 调用层 │ │ ├── client.ts # Axios 实例配置 │ │ ├── auth.ts # 认证相关 API │ │ ├── medicines.ts # 药品管理 API │ │ ├── categories.ts # 分类管理 API │ │ ├── batches.ts # 批次管理 API │ │ └── notifications.ts # 通知相关 API │ ├── components/ # 业务组件 │ │ ├── MedicineCard/ # 药品卡片 │ │ ├── BatchForm/ # 批次表单 │ │ ├── CategoryTree/ # 分类树 │ │ └── SearchBar/ # 搜索栏 │ ├── pages/ # 页面组件 │ │ ├── Home/ # 首页（库存概览） │ │ ├── MedicineList/ # 药品列表 │ │ ├── MedicineDetail/ # 药品详情 │ │ ├── AddMedicine/ # 添加药品 │ │ ├── QuickDispense/ # 快速取药（大屏模式） │ │ ├── Scanner/ # AI 识别 │ │ ├── Search/ # 搜索页面 │ │ ├── Notifications/ # 通知中心 │ │ ├── Settings/ # 设置页面 │ │ └── Login/ # 登录页面 │ ├── stores/ # 状态管理 │ │ ├── authStore.ts # 认证状态 │ │ ├── medicineStore.ts # 药品状态 │ │ └── uiStore.ts # UI 状态 │ ├── hooks/ # 自定义 Hooks │ │ ├── useAuth.ts # 认证 Hook │ │ ├── useMedicine.ts # 药品 Hook │ │ └── useCamera.ts # 摄像头 Hook │ ├── utils/ # 工具函数 │ │ ├── date.ts # 日期处理 │ │ ├── storage.ts # 本地存储 │ │ └── validators.ts # 表单验证 │ ├── types/ # TypeScript 类型 │ │ ├── medicine.ts # 药品类型 │ │ ├── batch.ts # 批次类型 │ │ ├── user.ts # 用户类型 │ │ └── api.ts # API 响应类型 │ ├── styles/ # 样式文件 │ │ ├── global.css # 全局样式 │ │ └── variables.css # CSS 变量 │ ├── App.tsx # 根组件 │ ├── main.tsx # 入口文件 │ └── router.tsx # 路由配置 ├── public/ # 静态资源 ├── index.html # HTML 模板 ├── vite.config.ts # Vite 配置 ├── tsconfig.json # TypeScript 配置 └── package.json # 依赖配置 ``` ### 4.2 后端模块 ``` backend/ ├── app/ │ ├── api/ # 路由层 │ │ ├── v1/ # API 版本 │ │ │ ├── auth.py # 认证路由 │ │ │ ├── medicines.py # 药品路由 │ │ │ ├── batches.py # 批次路由 │ │ │ ├── categories.py # 分类路由 │ │ │ ├── search.py # 搜索路由 │ │ │ ├── notifications.py # 通知路由 │ │ │ ├── ai.py # AI 识别路由 │ │ │ └── users.py # 用户管理路由 │ │ └── router.py # 路由汇总 │ ├── core/ # 核心配置 │ │ ├── config.py # 配置管理 │ │ ├── security.py # 安全工具 │ │ └── deps.py # 依赖注入 │ ├── models/ # 数据模型 │ │ ├── medicine.py # 药品模型 │ │ ├── batch.py # 批次模型 │ │ ├── category.py # 分类模型 │ │ ├── user.py # 用户模型 │ │ ├── notification.py # 通知模型 │ │ └── audit.py # 审计日志模型 │ ├── schemas/ # Pydantic 模型 │ │ ├── medicine.py # 药品 Schema │ │ ├── batch.py # 批次 Schema │ │ ├── category.py # 分类 Schema │ │ ├── user.py # 用户 Schema │ │ └── auth.py # 认证 Schema │ ├── services/ # 服务层 │ │ ├── medicine.py # 药品服务 │ │ ├── batch.py # 批次服务 │ │ ├── category.py # 分类服务 │ │ ├── user.py # 用户服务 │ │ ├── auth.py # 认证服务 │ │ ├── notification.py # 通知服务 │ │ └── search.py # 搜索服务 │ ├── repositories/ # 数据访问层 │ │ ├── medicine.py # 药品仓库 │ │ ├── batch.py # 批次仓库 │ │ ├── category.py # 分类仓库 │ │ └── user.py # 用户仓库 │ ├── ai/ # AI Provider │ │ ├── provider.py # 抽象基类 │ │ ├── openai.py # OpenAI 实现 │ │ ├── gemini.py # Gemini 实现 │ │ ├── claude.py # Claude 实现 │ │ ├── deepseek.py # DeepSeek 实现 │ │ ├── ollama.py # Ollama 实现 │ │ └── manager.py # Provider 管理器 │ ├── notifications/ # 通知系统 │ │ ├── provider.py # 抽象基类 │ │ ├── serverchan.py # Server酱 │ │ ├── pushplus.py # PushPlus │ │ ├── bark.py # Bark │ │ ├── wechat.py # 企业微信 │ │ ├── telegram.py # Telegram │ │ ├── email.py # 邮件 │ │ └── manager.py # 通知管理器 │ ├── storage/ # 文件存储 │ │ ├── local.py # 本地存储 │ │ └── manager.py # 存储管理器 │ ├── tasks/ # 异步任务 │ │ ├── expiry_check.py # 到期检查任务 │ │ └── stock_check.py # 库存检查任务 │ ├── database.py # 数据库连接 │ └── main.py # 应用入口 ├── alembic/ # 数据库迁移 │ ├── versions/ │ └── env.py ├── tests/ # 测试文件 ├── requirements.txt # 依赖配置 ├── alembic.ini # Alembic 配置 ├── Dockerfile # Docker 配置 └── .env.example # 环境变量示例 ``` ## 5. 数据流设计 ### 5.1 AI 自动录入流程 ``` 用户上传图片 │ ▼ ┌─────────────────┐ │ 图片预处理 │ │ (压缩/格式化) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 调用 Vision │ │ Provider │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 返回识别结果 │ │ (JSON) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 用户确认/编辑 │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 保存到数据库 │ │ + 保存图片 │ └─────────────────┘ ``` ### 5.2 快速取药流程 ``` 用户选择药品 │ ▼ ┌─────────────────┐ │ 显示药品详情 │ │ (可用批次列表) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 用户选择批次 │ │ 输入取药数量 │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 扣减库存 │ │ 记录审计日志 │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 检查库存阈值 │ │ 触发通知(可选) │ └─────────────────┘ ``` ### 5.3 到期提醒流程 ``` 定时任务触发 │ ▼ ┌─────────────────┐ │ 查询即将过期 │ │ 批次 (90/30/7天)│ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 生成提醒内容 │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 调用通知系统 │ │ 发送提醒 │ └─────────────────┘ ``` ## 6. AI Provider 抽象层设计 ### 6.1 抽象接口 ```python from abc import ABC, abstractmethod from typing import Optional from pydantic import BaseModel class VisionResult(BaseModel): """视觉识别结果""" generic_name: str brand_name: Optional[str] manufacturer: Optional[str] specification: Optional[str] class DateResult(BaseModel): """日期识别结果""" production_date: Optional[str] expiry_date: Optional[str] class LeafletResult(BaseModel): """说明书识别结果""" indications: str adult_dose: str child_dose: Optional[str] contraindications: str notes: Optional[str] class VisionProvider(ABC): """视觉模型提供者抽象基类""" @abstractmethod async def recognize_medicine(self, image_bytes: bytes) -> VisionResult: """识别药盒信息""" pass @abstractmethod async def recognize_dates(self, image_bytes: bytes) -> DateResult: """识别日期信息""" pass class TextProvider(ABC): """文本模型提供者抽象基类""" @abstractmethod async def summarize_leaflet(self, text: str) -> LeafletResult: """总结说明书内容""" pass @abstractmethod async def natural_language_search(self, query: str, medicines: list) -> list: """自然语言搜索""" pass ``` ### 6.2 Provider 管理器 ```python class AIManager: """AI Provider 管理器""" def __init__(self): self.vision_providers: dict[str, VisionProvider] = {} self.text_providers: dict[str, TextProvider] = {} def register_vision_provider(self, name: str, provider: VisionProvider): """注册视觉模型提供者""" self.vision_providers[name] = provider def register_text_provider(self, name: str, provider: TextProvider): """注册文本模型提供者""" self.text_providers[name] = provider def get_vision_provider(self, name: str) -> VisionProvider: """获取视觉模型提供者""" return self.vision_providers.get(name) def get_text_provider(self, name: str) -> TextProvider: """获取文本模型提供者""" return self.text_providers.get(name) ``` ## 7. 通知系统设计 ### 7.1 通知 Provider 抽象 ```python from abc import ABC, abstractmethod class NotificationProvider(ABC): """通知提供者抽象基类""" @abstractmethod async def send(self, title: str, content: str) -> bool: """发送通知""" pass @abstractmethod def validate_config(self) -> bool: """验证配置""" pass ``` ### 7.2 通知管理器 ```python class NotificationManager: """通知管理器""" def __init__(self): self.providers: list[NotificationProvider] = [] def add_provider(self, provider: NotificationProvider): """添加通知提供者""" self.providers.append(provider) async def send_notification(self, title: str, content: str): """发送通知到所有提供者""" for provider in self.providers: try: await provider.send(title, content) except Exception as e: # 记录错误但不中断 pass ``` ## 8. 认证授权设计 ### 8.1 用户角色 - **admin**: 管理员，拥有所有权限 - **user**: 普通用户，可查看、添加库存、取药 - **readonly**: 只读用户，仅可查看 ### 8.2 权限矩阵 | 功能 | admin | user | readonly | |------|-------|------|----------| | 查看药品 | ✓ | ✓ | ✓ | | 添加药品 | ✓ | ✓ | ✗ | | 修改药品 | ✓ | ✓ | ✗ | | 删除药品 | ✓ | ✗ | ✗ | | 取药 | ✓ | ✓ | ✗ | | 用户管理 | ✓ | ✗ | ✗ | | 系统设置 | ✓ | ✗ | ✗ | | 通知管理 | ✓ | ✓ | ✗ | ### 8.3 JWT 认证流程 ``` 用户登录 │ ▼ ┌─────────────────┐ │ 验证用户名密码 │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 生成 JWT Token │ │ (Access Token) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 返回 Token │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 前端存储 Token │ │ (localStorage) │ └─────────────────┘ │ ▼ ┌─────────────────┐ │ 后续请求携带 │ │ Authorization │ │ Header │ └─────────────────┘ ``` ## 9. 插件系统设计 ### 9.1 插件接口 ```python from abc import ABC, abstractmethod class Plugin(ABC): """插件抽象基类""" @abstractmethod def get_name(self) -> str: """获取插件名称""" pass @abstractmethod def get_description(self) -> str: """获取插件描述""" pass @abstractmethod def initialize(self, app): """初始化插件""" pass ``` ### 9.2 插件管理器 ```python class PluginManager: """插件管理器""" def __init__(self): self.plugins: dict[str, Plugin] = {} def register_plugin(self, plugin: Plugin): """注册插件""" name = plugin.get_name() self.plugins[name] = plugin def get_plugin(self, name: str) -> Plugin: """获取插件""" return self.plugins.get(name) def list_plugins(self) -> list[str]: """列出所有插件""" return list(self.plugins.keys()) ``` ## 10. MCP 协议支持 ### 10.1 MCP 工具定义 ```python from mcp import Tool # 查询库存工具 query_inventory_tool = Tool( name="query_inventory", description="查询家庭药品库存", inputSchema={ "type": "object", "properties": { "medicine_name": { "type": "string", "description": "药品名称" } } } ) # 取药工具 dispense_medicine_tool = Tool( name="dispense_medicine", description="取药操作", inputSchema={ "type": "object", "properties": { "medicine_id": { "type": "integer", "description": "药品ID" }, "quantity": { "type": "integer", "description": "取药数量" } }, "required": ["medicine_id", "quantity"] } ) ``` ## 11. 部署架构 ``` ┌─────────────────────────────────────────┐ │ Docker 容器 │ ├─────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Nginx │ │ FastAPI │ │ │ │ (静态文件) │ │ (后端) │ │ │ │ :80 │ │ :8000 │ │ │ └─────────────┘ └─────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ SQLite │ │ 文件存储 │ │ │ │ (数据库) │ │ (图片) │ │ │ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────┘ ``` ## 12. 环境变量配置 ```bash # 数据库配置 DATABASE_URL=sqlite:///./data/yaoxiang.db # AI Provider 配置 AI_PROVIDER=openai OPENAI_API_KEY=sk-xxx OPENAI_MODEL=gpt-4o # 通知配置 NOTIFICATION_PROVIDERS=serverchan,pushplus SERVERCHAN_KEY=xxx PUSHPLUS_TOKEN=xxx # 安全配置 JWT_SECRET_KEY=xxx JWT_ALGORITHM=HS256 JWT_EXPIRATION_HOURS=24 # 文件存储配置 UPLOAD_DIR=./data/uploads MAX_UPLOAD_SIZE=10485760 # 10MB # 应用配置 APP_NAME=药箱 APP_VERSION=1.0.0 DEBUG=false ``` ## 13. 开发规范 ### 13.1 代码风格 - **Python**: 遵循 PEP 8，使用 Black 格式化 - **TypeScript**: 遵循 ESLint 规则，使用 Prettier 格式化 - **Git**: 使用 Conventional Commits 规范 ### 13.2 分支管理 - `main`: 生产分支 - `develop`: 开发分支 - `feature/*`: 功能分支 - `bugfix/*`: 修复分支 - `release/*`: 发布分支 ### 13.3 提交规范 ``` feat: 新功能 fix: 修复 bug docs: 文档更新 style: 代码格式调整 refactor: 重构 test: 测试相关 chore: 构建/工具相关 ``` ## 14. 性能优化 ### 14.1 前端优化 - 路由懒加载 - 图片懒加载 - 虚拟列表（长列表优化） - Service Worker 缓存 ### 14.2 后端优化 - 数据库连接池 - 查询优化（索引、分页） - 异步处理耗时任务 - 响应缓存 ## 15. 安全设计 ### 15.1 认证安全 - 密码使用 bcrypt 加密存储 - JWT Token 定期轮换 - 登录失败次数限制 ### 15.2 数据安全 - 敏感配置使用环境变量 - 文件上传类型验证 - SQL 注入防护（ORM） - XSS 防护（前端） ### 15.3 传输安全 - 支持 HTTPS - CORS 配置 - 请求限流