# 药箱 · YaoXiang

家庭药品与应急物资管理系统

## 功能介绍

### 核心功能

- **药品管理**: 添加、编辑、删除药品信息，支持通用名、商品名、规格等
- **批次管理**: 每个药品可有多个批次，独立管理库存和有效期
- **分类管理**: 二级分类（药品/医疗器械/应急用品/消耗品）
- **智能搜索**: 支持按名称、症状搜索，AI 自然语言搜索
- **AI 识别**: 拍照识别药盒、有效期、说明书，自动建档
- **到期提醒**: 90天/30天/7天过期提醒，支持有效期宽限（最多60天）
- **库存提醒**: 低库存自动提醒
- **用户管理**: 多用户支持，角色权限划分（管理员/普通用户/只读）
- **通知系统**: 支持 Server酱、PushPlus、Bark 等多种通知渠道
- **大屏模式**: 平板快速取药，大按钮方便操作

### 技术特性

- **前端**: React 18 + TypeScript + Vite + Ant Design Mobile
- **后端**: FastAPI + SQLAlchemy + SQLite
- **AI**: 支持 OpenAI、Gemini、Claude、DeepSeek、Ollama
- **部署**: Docker 单容器部署

## 项目结构

```
YaoXiang/
├── frontend/                # 前端代码
│   ├── src/
│   │   ├── api/            # API 调用层
│   │   ├── components/     # 公共组件
│   │   ├── pages/          # 页面组件
│   │   ├── stores/         # 状态管理
│   │   ├── hooks/          # 自定义 Hooks
│   │   ├── types/          # TypeScript 类型
│   │   └── utils/          # 工具函数
│   └── package.json
│
├── backend/                 # 后端代码
│   ├── app/
│   │   ├── api/            # API 路由
│   │   ├── models/         # 数据模型
│   │   ├── schemas/        # Pydantic 模式
│   │   ├── services/       # 业务逻辑
│   │   ├── repositories/   # 数据访问
│   │   ├── ai/             # AI Provider
│   │   └── notifications/  # 通知系统
│   └── requirements.txt
│
├── docs/                    # 开发文档
├── start.ps1               # Windows 启动脚本
├── start.sh                # Linux/Mac 启动脚本
└── README.md
```

## 安装与运行

### 前置要求

- Node.js 18+
- Python 3.11+
- npm

### 快速开始

**Windows:**

```powershell
# 安装依赖
.\start.ps1 install

# 启动服务
.\start.ps1 start
```

**Linux / Mac:**

```bash
# 赋予执行权限（首次）
chmod +x start.sh

# 安装依赖
./start.sh install

# 启动服务
./start.sh start
```

**手动安装:**

```bash
# 安装前端依赖
cd frontend
npm install

# 安装后端依赖
cd ../backend
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\activate
pip install -r requirements.txt

# 启动后端
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 启动前端（新终端）
cd frontend
npm run dev
```

### 访问地址

- 前端: http://localhost:5173
- 后端 API: http://localhost:8000
- API 文档: http://localhost:8000/docs

### 默认账号

首次启动会自动创建管理员账号：
- 用户名: admin
- 密码: admin123

## 配置说明

在 `backend/` 目录下创建 `.env` 文件：

```bash
cp .env.example .env
```

### AI API 配置

支持多种 AI Provider，选择一种配置即可：

**OpenAI:**

```bash
AI_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4o
```

**Gemini:**

```bash
AI_PROVIDER=gemini
GEMINI_API_KEY=your-api-key
GEMINI_MODEL=gemini-pro-vision
```

**DeepSeek:**

```bash
AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_MODEL=deepseek-chat
```

**Ollama (本地部署):**

```bash
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llava
```

### 通知配置

配置通知渠道，药品过期和库存不足时会发送提醒：

**Server酱:**

1. 访问 https://sct.ftqq.com/ 注册获取 SendKey
2. 配置：
```bash
NOTIFICATION_PROVIDERS=serverchan
SERVERCHAN_KEY=your-send-key
```

**PushPlus:**

1. 访问 https://www.pushplus.plus/ 注册获取 Token
2. 配置：
```bash
NOTIFICATION_PROVIDERS=pushplus
PUSHPLUS_TOKEN=your-token
```

**多渠道同时启用:**

```bash
NOTIFICATION_PROVIDERS=serverchan,pushplus
SERVERCHAN_KEY=your-key
PUSHPLUS_TOKEN=your-token
```

### 其他配置

```bash
# 安全配置（请修改为自己的密钥）
JWT_SECRET_KEY=your-secret-key

# 数据库配置（默认 SQLite）
DATABASE_URL=sqlite+aiosqlite:///./data/yaoxiang.db

# 文件上传配置
UPLOAD_DIR=./data/uploads
MAX_UPLOAD_SIZE=10485760  # 10MB
```

## 常用命令

```powershell
# Windows
.\start.ps1 install       # 安装依赖
.\start.ps1 start         # 启动所有服务
.\start.ps1 start:f       # 仅启动前端
.\start.ps1 start:b       # 仅启动后端
.\start.ps1 build         # 构建生产版本
.\start.ps1 clean         # 清理缓存
.\start.ps1 help          # 显示帮助
```

```bash
# Linux / Mac
./start.sh install        # 安装依赖
./start.sh start          # 启动所有服务
./start.sh start:f        # 仅启动前端
./start.sh start:b        # 仅启动后端
./start.sh build          # 构建生产版本
./start.sh clean          # 清理缓存
./start.sh help           # 显示帮助
```

## 开发文档

详细文档请查看 `docs/` 目录：

- [系统架构设计](docs/architecture.md)
- [数据库设计](docs/database.md)
- [前端开发文档](frontend/DEVELOPMENT.md)
- [后端开发文档](backend/DEVELOPMENT.md)
- [API 接口文档](docs/api.md)

## 许可证

MIT License

## 声明

本项目由 [小米 MiMoCode]([mimo.xiaomi.com/zh/mimocode](https://mimo.xiaomi.com/zh/mimocode)) 助生成。