199 lines
5.9 KiB
Markdown
199 lines
5.9 KiB
Markdown
# CLAUDE.md - 海外预约系统项目指南
|
||
|
||
## 项目概述
|
||
|
||
这是一个**海外预约服务系统**，包含微信小程序、后端API和管理后台三个模块。系统支持多种服务类型的预约（航班票务、酒店预订、机场接送等），并具备邀请奖励和佣金分成机制。
|
||
|
||
## 技术栈
|
||
|
||
### 后端 (backend/)
|
||
- **框架**: Node.js + Express.js 4.18
|
||
- **数据库**: MySQL 8.0 + Sequelize ORM
|
||
- **缓存**: Redis 7
|
||
- **认证**: JWT + 微信登录
|
||
- **测试**: Jest + Supertest
|
||
|
||
### 小程序 (miniprogram/)
|
||
- **框架**: uni-app + Vue 3 + Vite
|
||
- **UI库**: uView Plus 3.6
|
||
- **国际化**: vue-i18n (中文/英文/西班牙语)
|
||
|
||
### 管理后台 (admin/)
|
||
- **框架**: Vue 3 + Vite
|
||
- **UI库**: Element Plus 2.6
|
||
- **状态管理**: Pinia
|
||
- **图表**: ECharts
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
overseas-appointment-system/
|
||
├── miniprogram/ # 微信小程序
|
||
│ └── src/
|
||
│ ├── pages/ # 页面（index/appointment/me/login等）
|
||
│ ├── components/ # 公共组件
|
||
│ ├── modules/api/ # API封装（AppServer.js）
|
||
│ └── locale/ # 多语言文件
|
||
├── backend/ # 后端API
|
||
│ └── src/
|
||
│ ├── controllers/ # 控制器层（24个）
|
||
│ ├── services/ # 业务逻辑层（20+个）
|
||
│ ├── models/ # 数据模型（16个）
|
||
│ ├── routes/ # 路由定义（27个）
|
||
│ ├── middleware/ # 中间件（auth/rbac/validation等）
|
||
│ ├── config/ # 配置文件
|
||
│ ├── migrations/ # 数据库迁移
|
||
│ └── tests/ # 测试用例（28个）
|
||
├── admin/ # 管理后台
|
||
│ └── src/
|
||
│ ├── views/ # 页面（12个模块）
|
||
│ ├── stores/ # Pinia状态
|
||
│ └── router/ # 路由配置
|
||
└── docker/ # Docker部署配置
|
||
```
|
||
|
||
## 核心数据模型
|
||
|
||
| 模型 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| User | user | 用户（含邀请码、余额、多语言偏好） |
|
||
| Appointment | appointment | 预约记录 |
|
||
| Service | service | 服务项目（多语言标题/描述） |
|
||
| Category | category | 服务分类 |
|
||
| Invitation | invitation | 邀请关系 |
|
||
| Commission | commission | 佣金记录 |
|
||
| PaymentOrder | payment_orders | 支付订单（离线支付） |
|
||
| Withdrawal | withdrawal | 提现申请 |
|
||
| Notification | notification | 系统通知 |
|
||
| Admin | admin | 管理员（super_admin/admin/operator） |
|
||
|
||
## 常用开发命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm run install:all
|
||
|
||
# 后端开发
|
||
cd backend && npm run dev
|
||
|
||
# 小程序开发
|
||
cd miniprogram && npm run dev:mp-weixin
|
||
|
||
# 管理后台开发
|
||
cd admin && npm run dev
|
||
|
||
# 数据库初始化
|
||
cd backend && npm run db:init
|
||
|
||
# 运行测试
|
||
cd backend && npm test
|
||
|
||
# Docker部署
|
||
docker-compose up -d
|
||
```
|
||
|
||
## API结构
|
||
|
||
- **基础路径**: `/api/v1/`
|
||
- **认证方式**: Bearer Token (JWT)
|
||
- **多语言**: `Accept-Language` 头或 `?language=zh|en|es`
|
||
|
||
### 主要API端点
|
||
|
||
```
|
||
# 认证
|
||
POST /api/v1/auth/wechat-login # 微信登录
|
||
POST /api/v1/auth/refresh-token # 刷新令牌
|
||
|
||
# 用户
|
||
GET /api/v1/users/profile # 获取用户信息
|
||
PUT /api/v1/users/profile # 更新用户信息
|
||
|
||
# 预约
|
||
POST /api/v1/appointments # 创建预约
|
||
GET /api/v1/appointments # 预约列表
|
||
GET /api/v1/appointments/:id # 预约详情
|
||
|
||
# 邀请与佣金
|
||
POST /api/v1/invitations/generate # 生成邀请码
|
||
GET /api/v1/invitations/stats # 邀请统计
|
||
GET /api/v1/commissions # 佣金列表
|
||
|
||
# 提现
|
||
POST /api/v1/withdrawals # 申请提现
|
||
GET /api/v1/withdrawals # 提现记录
|
||
|
||
# 管理员API
|
||
/api/v1/admin/* # 管理后台专用接口
|
||
```
|
||
|
||
## 业务流程
|
||
|
||
### 预约流程
|
||
1. 用户选择服务 → 2. 填写预约表单 → 3. 上传附件（可选） → 4. 提交生成预约号 → 5. 状态流转 (pending → confirmed → in-progress → completed)
|
||
|
||
### 邀请与佣金流程
|
||
1. 用户获取邀请码 → 2. 分享给新用户 → 3. 新用户注册绑定 → 4. 新用户首次支付 → 5. 自动计算佣金（默认2%） → 6. 佣金入账邀请者余额
|
||
|
||
### 提现流程
|
||
用户申请 (waiting) → 管理员审核 → 批准 (completed) / 拒绝 (rejected)
|
||
|
||
## 关键配置文件
|
||
|
||
- `backend/.env` - 后端环境变量（数据库、Redis、JWT、微信配置）
|
||
- `backend/src/config/env.js` - 配置读取
|
||
- `docker-compose.yml` - 生产环境Docker编排
|
||
- `docker-compose.dev.yml` - 开发环境数据库
|
||
|
||
## 编码规范
|
||
|
||
### 后端
|
||
- 使用async/await处理异步
|
||
- 控制器负责请求/响应，业务逻辑放service层
|
||
- 统一响应格式: `{ success: boolean, data: any, error?: { code, message } }`
|
||
- 使用express-validator进行参数验证
|
||
|
||
### 前端
|
||
- 组件使用Vue 3 Composition API
|
||
- API调用集中在 `modules/api/AppServer.js`
|
||
- 多语言键值定义在 `locale/` 目录
|
||
|
||
## 注意事项
|
||
|
||
1. **多语言字段**: Service、Category、Notification等模型包含 `_zh`、`_en`、`_es` 后缀的字段
|
||
2. **UUID主键**: 所有主表使用UUID而非自增ID
|
||
3. **预约编号格式**: `APT` + `YYYYMMDD` + 6位数字
|
||
4. **订单编号格式**: `ORD` + `YYYYMMDD` + 6位数字
|
||
5. **佣金计算**: 支付金额 × 佣金比例（系统配置表可调整）
|
||
6. **权限角色**: super_admin > admin > operator
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cd backend
|
||
npm test # 运行所有测试
|
||
npm run test:coverage # 测试覆盖率
|
||
npm run test:watch # 监听模式
|
||
```
|
||
|
||
测试覆盖: 认证、预约流程、佣金计算、提现、文件上传、RBAC权限等。
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
# 生产环境
|
||
docker-compose up -d
|
||
|
||
# 扩展API实例
|
||
docker-compose up -d --scale api=3
|
||
|
||
# 查看日志
|
||
docker-compose logs -f api
|
||
```
|
||
|
||
## 健康检查
|
||
|
||
- `GET /health` - 服务健康状态
|
||
- `GET /metrics` - 性能指标
|
||
- `GET /api-docs` - Swagger API文档
|