# 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文档