outsource/appointment_system

Fork 0

18631081161 5c2469137c 国际化,管理后台修改.

2025-12-21 17:22:48 +08:00

5.9 KiB

Raw Blame History

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）

常用开发命令

# 安装依赖
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/*                   # 管理后台专用接口

业务流程

预约流程

用户选择服务 → 2. 填写预约表单 → 3. 上传附件（可选） → 4. 提交生成预约号 → 5. 状态流转 (pending → confirmed → in-progress → completed)

邀请与佣金流程

用户获取邀请码 → 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/ 目录

注意事项

多语言字段: Service、Category、Notification等模型包含 _zh、_en、_es 后缀的字段
UUID主键: 所有主表使用UUID而非自增ID
预约编号格式: APT + YYYYMMDD + 6位数字
订单编号格式: ORD + YYYYMMDD + 6位数字
佣金计算: 支付金额 × 佣金比例（系统配置表可调整）
权限角色: super_admin > admin > operator

测试

cd backend
npm test                    # 运行所有测试
npm run test:coverage       # 测试覆盖率
npm run test:watch          # 监听模式

测试覆盖: 认证、预约流程、佣金计算、提现、文件上传、RBAC权限等。

部署

# 生产环境
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文档

5.9 KiB Raw Blame History Unescape Escape