diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d204ec4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,198 @@ +# 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|pt` + +### 主要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`、`_pt` 后缀的字段 +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文档 diff --git a/admin/package-lock.json b/admin/package-lock.json index 4b96f4d..7ccc6a0 100644 --- a/admin/package-lock.json +++ b/admin/package-lock.json @@ -1241,6 +1241,7 @@ "resolved": "https://registry.npmjs.org/@types/lodash-es/-/lodash-es-4.17.12.tgz", "integrity": "sha512-0NgftHUcV4v34VhXm8QBSftKVXtbkBG3ViCjs6+eJ5a6y6Mi/jiFGPc1sC7QK+9BFhWrURE3EOggmWaSxL9OzQ==", "license": "MIT", + "peer": true, "dependencies": { "@types/lodash": "*" } @@ -2070,13 +2071,15 @@ "version": "4.17.21", "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/lodash-es": { "version": "4.17.21", "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==", - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/lodash-unified": { "version": "1.0.3", @@ -2427,6 +2430,7 @@ "integrity": "sha512-w8GmOxZfBmKknvdXU1sdM9NHcoQejwF/4mNgj2JuEEdRaHwwF12K7e9eXn1nLZ07ad+du76mkVsyeb2rKGllsA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@types/estree": "1.0.8" }, @@ -2493,6 +2497,7 @@ "integrity": "sha512-N+7WK20/wOr7CzA2snJcUSSNTCzeCGUTFY3OgeQP3mZ1aj9NMQ0mSTXwlrnd89j33zzQJGqIN52GIOmYrfq46A==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "chokidar": "^4.0.0", "immutable": "^5.0.2", @@ -2803,6 +2808,7 @@ "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.21.3", "postcss": "^8.4.43", @@ -2862,6 +2868,7 @@ "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.25.tgz", "integrity": "sha512-YLVdgv2K13WJ6n+kD5owehKtEXwdwXuj2TTyJMsO7pSeKw2bfRNZGjhB7YzrpbMYj5b5QsUebHpOqR3R3ziy/g==", "license": "MIT", + "peer": true, "dependencies": { "@vue/compiler-dom": "3.5.25", "@vue/compiler-sfc": "3.5.25", diff --git a/backend/.env b/backend/.env new file mode 100644 index 0000000..923ef10 --- /dev/null +++ b/backend/.env @@ -0,0 +1,35 @@ +# Server Configuration +NODE_ENV=development +PORT=3000 + +# Database Configuration +DB_HOST=192.168.195.15 +DB_PORT=3306 +DB_NAME=overseas_appointment +DB_USER=root +DB_PASSWORD=root123456 + +# Redis Configuration +REDIS_HOST=192.168.195.15 +REDIS_PORT=6379 +REDIS_PASSWORD= + +# JWT Configuration +JWT_SECRET=your-secret-key-change-in-production +JWT_EXPIRES_IN=7d +JWT_REFRESH_EXPIRES_IN=30d + +# WeChat Configuration +WECHAT_APP_ID=your-wechat-app-id +WECHAT_APP_SECRET=your-wechat-app-secret + +# File Upload Configuration +UPLOAD_PATH=./uploads +MAX_FILE_SIZE=5242880 + +# Rate Limiting +RATE_LIMIT_WINDOW=60000 +RATE_LIMIT_MAX=100 + +# Logging +LOG_LEVEL=info diff --git a/backend/.env.example b/backend/.env.example index eedef00..923ef10 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -3,14 +3,14 @@ NODE_ENV=development PORT=3000 # Database Configuration -DB_HOST=localhost +DB_HOST=192.168.195.15 DB_PORT=3306 DB_NAME=overseas_appointment DB_USER=root -DB_PASSWORD= +DB_PASSWORD=root123456 # Redis Configuration -REDIS_HOST=localhost +REDIS_HOST=192.168.195.15 REDIS_PORT=6379 REDIS_PASSWORD= diff --git a/backend/.gitignore b/backend/.gitignore index 2a204ca..e856f03 100644 --- a/backend/.gitignore +++ b/backend/.gitignore @@ -3,7 +3,6 @@ node_modules/ package-lock.json # Environment variables -.env # Logs logs/