TourGuide 基础框架

基于 JDK 8、Spring Boot、MyBatis-Plus、MySQL、Redis、JWT、Vue 3 和 Node.js 24.1.0 的旅游平台基础工程。

架构决策

后端采用一个可部署应用，基础设施统一维护，业务接口按客户端边界隔离。这样可以避免早期拆成多个服务造成重复配置，同时保留未来按模块拆分的清晰边界。

客户端	用户表	Token 类型	接口前缀	权限标识
管理后台	sys_admin_user	ADMIN	/api/admin/**	ADMIN
游客小程序	mini_user	MINI	/api/mini/**	MINI_USER
导游端	guide_user	GUIDE	/api/guide/**	GUIDE_USER

JWT 包含 clientType 声明，Redis 会话 Key 同时包含客户端类型和 Token ID。请求进入过滤器后会先比较接口前缀和 clientType，再查询对应用户表；不匹配时直接返回 401，不会回退查询其他端用户表。

目录说明

TourGuide/
├─ backend/                 Spring Boot 后端
│  ├─ db/schema.sql         tour_guide 数据库初始化脚本
│  └─ src/main/java/
│     ├─ api/admin/         管理后台接口
│     ├─ api/mini/          游客小程序接口
│     ├─ api/guide/         导游端接口
│     ├─ modules/user/      三端独立用户模型与服务
│     └─ security/          JWT、Redis 会话、分端校验
└─ frontend/                Vue 3 管理后台框架
   └─ src/views/            可替换的原型页面占位

本地启动步骤

1. 初始化数据库

• 目的：创建 tour_guide 数据库和三端独立用户表。
• 操作：在 MySQL 8 中执行 backend/db/schema.sql。
• 影响范围：创建 sys_role、sys_admin_user、mini_user、guide_user；不会删除已有表。
• 验证：执行 USE tour_guide; SHOW TABLES;，应显示三端用户表以及后台基础表。
• 注意：默认数据库账号为 root/root，可通过环境变量覆盖。

已有 tour_guide 数据库时，不要重新执行完整建库脚本。请在备份后执行一次导游管理增量脚本：

mysql -u root -p < backend/db/upgrade-guide-management.sql

该脚本会扩展 guide_user 字段，并创建 guide_team、guide_scenic_config、guide_auto_disable_config，不会删除现有导游数据。脚本仅用于升级一次，重复执行其中的 ALTER TABLE 会因字段已存在而失败。

若本机 MySQL 密码与默认配置不同，可运行安全初始化脚本。密码通过隐藏输入读取，不会写入项目文件：

& "backend/db/init-local.ps1"

已执行过旧版数据库脚本的环境，需依次执行 backend/db/upgrade-guide-team-management.sql、backend/db/upgrade-guide-team-detail.sql 和 backend/db/upgrade-order-management.sql，补充讲解队配置与订单表。

评价管理增量脚本生成于 2026-07-28 10:02:13 +08:00：

mysql -u root -p < backend/db/20260728_100213_upgrade_review_management.sql

执行后可查询迁移版本和首次执行时间，判断当前数据库是否已经升级：

SELECT `version`, `description`, `applied_at`
FROM `sys_schema_migration`
WHERE `version` = '20260728_100213_REVIEW_MANAGEMENT';

反馈管理增量脚本同时支持游客反馈与导游反馈，已有数据库执行：

mysql -u root -p < backend/db/migrations/20260728_120000_create_feedback_management.sql

执行后通过迁移版本 20260728_120000_FEEDBACK_MANAGEMENT 验证，并确认 user_feedback 表已创建。

订单详情页新增商品快照、支付时间线、服务节点和退款凭证字段，已有数据库需执行一次：

mysql -u root -p < backend/db/migrations/20260728_140000_upgrade_order_detail.sql

执行后可通过迁移版本 20260728_140000_ORDER_DETAIL 验证升级结果。

2. 启动 Redis

• 目的：保存登录会话并支持 Token 主动失效。
• 操作：启动本地 Redis，默认地址 127.0.0.1:6379，数据库索引为 0。
• 影响范围：会写入 tourguide:auth:session:{客户端类型}:{tokenId} 格式的 Key。
• 验证：登录后执行 KEYS tourguide:auth:session:* 可看到对应端会话。
• 注意：Redis 不可用时登录和鉴权会失败，避免 JWT 在服务端无法主动失效。

3. 启动后端

cd "backend"
mvn spring-boot:run

• 目的：启动三端统一后端应用。
• 操作：应用连接本地 tour_guide 和 Redis，并在首次启动时创建管理员。
• 影响范围：默认监听 8080 端口。
• 验证：访问 GET /api/health，应返回 status=UP。
• 注意：默认管理员为 admin / Admin@123456，仅用于本地开发；部署前必须修改。

可用环境变量：

MYSQL_URL
MYSQL_USERNAME
MYSQL_PASSWORD
REDIS_HOST
REDIS_PORT
REDIS_PASSWORD
REDIS_DATABASE
JWT_SECRET
BOOTSTRAP_ADMIN_USERNAME
BOOTSTRAP_ADMIN_PASSWORD
WECHAT_APPID
WECHAT_APP_SECRET
WECHAT_CONNECT_TIMEOUT_MILLIS
WECHAT_READ_TIMEOUT_MILLIS
UNIPUSH_ENABLED
UNIPUSH_APP_ID
UNIPUSH_APP_KEY
UNIPUSH_MASTER_SECRET
UNIPUSH_SERVICE_REMINDER_MINUTES

JWT_SECRET 至少使用 32 字节随机字符串。

微信小程序手机号授权登录使用 WECHAT_APPID 和 WECHAT_APP_SECRET。AppSecret 只能通过后端运行环境注入，禁止写入 application.yml、小程序源码或提交到版本库。

PowerShell 本地启动示例：

$env:WECHAT_APPID='<微信小程序 AppID>'
$env:WECHAT_APP_SECRET='<微信小程序 AppSecret>'
cd "backend"
mvn spring-boot:run

小程序登录接口为 POST /api/mini/auth/wechat-phone-login。小程序先通过 uni.login 获取 loginCode，再将手机号授权事件返回的 phoneCode 一并提交后端；后端完成微信身份校验后签发 MINI JWT。

微信登录排障：

• WECHAT_APPID、WECHAT_APP_SECRET 必须配置在后端启动进程环境变量中，修改后需要重启 Spring Boot。
• 微信小程序登录配置未完成：启动进程未读取到环境变量。
• AppID 或 AppSecret 配置错误：检查小程序主体、AppID、AppSecret 是否属于同一个小程序，并重新生成已泄露的密钥。
• 微信登录凭证无效：uni.login 返回的 code 已使用或过期，需要重新调用 uni.login。
• 微信登录服务暂不可用：查看后端错误日志中的 调用微信 GET 接口失败，确认代理、TLS、DNS 或连接超时原因。

UniPush 导游端推送启用步骤：

1. 在 DCloud 开发者后台为导游端应用 __UNI__F7E10FB 开通 UniPush，并在 HBuilderX 云端打包配置中完成 Android/iOS 厂商通道配置。
2. 执行 backend/db/migrate-local.ps1，应用迁移 20260803_100000_INTEGRATE_UNIPUSH。
3. 后端运行环境配置 UNIPUSH_ENABLED=true、UNIPUSH_APP_ID、UNIPUSH_APP_KEY、UNIPUSH_MASTER_SECRET。
4. UNIPUSH_SERVICE_REMINDER_MINUTES 控制服务开始前提醒分钟数，默认值为 10。

导游登录或应用启动后会调用 PUT /api/guide/push-device 上报当前 CID；退出登录或注销账号时调用 DELETE /api/guide/push-device 解绑，避免旧设备继续接收订单通知。

后台基础表

backend/db/schema.sql 已包含以下后台基础表，并为每张表和每个字段添加中文备注：

• sys_role：后台角色
• sys_admin_user：后台账号
• sys_dept：部门组织
• sys_post：岗位
• sys_menu：菜单与权限标识
• sys_role_menu：角色菜单关系
• sys_admin_user_post：后台用户岗位关系
• sys_dict_type、sys_dict_data：系统字典
• sys_config：参数配置
• sys_notice：通知公告
• sys_login_log：登录日志
• sys_operation_log：操作日志

脚本内置 ADMIN 角色、系统根部门、管理员岗位、系统管理菜单、通用状态字典和基础参数。所有初始化语句均按唯一键或存在性判断设计，可以重复执行，不会主动删除已有数据。

4. 启动前端

cd "frontend"
npm install
npm run dev

• 目的：启动 Vue 3 管理后台框架。
• 操作：Vite 使用 Node.js 24.1.0，开发服务监听 5173 并代理 /api 到后端 8080。
• 影响范围：后台 Token 仅保存于浏览器 admin_token，不会读取其他端 Token。
• 验证：打开 http://127.0.0.1:5173，使用初始化管理员登录。
• 注意：现有业务页面是原型占位，后续可以直接替换 frontend/src/views/ 中对应组件。

已提供接口

管理后台

• POST /api/admin/auth/login：后台登录
• POST /api/admin/auth/logout：后台退出
• GET /api/admin/auth/me：当前后台用户
• GET/POST/PUT/DELETE /api/admin/users：后台账号管理
• GET /api/admin/mini-users：小程序用户分页
• PUT /api/admin/mini-users/{id}/status：停启小程序用户
• GET/POST /api/admin/guide-users：导游账号查询和创建
• PUT /api/admin/guide-users/{id}/status：停启导游账号
• GET/POST /api/admin/guide-teams：讲解队分页查询和新建
• GET /api/admin/guide-teams/{id}：查询讲解队详情及景区配置
• PUT /api/admin/guide-teams/{id}：编辑讲解队
• PUT /api/admin/guide-teams/{id}/status：停启讲解队
• GET /api/admin/orders：订单分页查询，支持游客、导游、景区、状态和时间筛选
• GET /api/admin/reviews：按订单、游客、导游、评分、景区和时间分页查询评价
• GET /api/admin/reviews/scenic-options：查询评价景区筛选项
• DELETE /api/admin/reviews/{id}：逻辑删除评价并重新计算导游评分
• GET /api/admin/orders/{id}：查询订单详情
• GET /api/admin/orders/scenic-options：查询订单景区筛选项
• PUT /api/admin/orders/{id}/refund：执行订单退款

游客小程序

• POST /api/mini/auth/wechat-phone-login：微信小程序手机号授权登录
• POST /api/mini/auth/logout：小程序用户退出
• DELETE /api/mini/auth/account：匿名化并逻辑删除当前游客账号，存在未完成订单时拒绝注销
• GET /api/mini/profile：回显当前登录游客资料和实名状态
• PUT /api/mini/profile：修改当前游客昵称
• POST /api/mini/profile/avatar：上传并修改当前游客头像
• PUT /api/mini/profile/real-name：填写或更新真实姓名，非空即视为已实名
• POST /api/mini/reviews：为本人已完成订单提交评价

逻辑删除规范

• 除技术迁移表 sys_schema_migration 外，所有业务表统一使用 deleted 字段：0 正常、1 删除。
• MyBatis-Plus 实体统一启用逻辑删除，deleteById 和条件删除只更新删除标识，不执行物理删除。
• 角色权限、景区价格、汇合点和导游景区等关联配置采用“逻辑删除旧配置 + Upsert 恢复或覆盖”，避免唯一键冲突。
• 游客注销会匿名化手机号、OpenID、昵称、头像和实名信息，再逻辑删除账号；历史订单不物理删除。

导游端

• POST /api/guide/auth/login：导游登录
• POST /api/guide/auth/logout：导游退出
• GET/PUT /api/guide/profile：导游本人资料

验证命令

cd "backend"
mvn test

cd "../frontend"
npm run build

后端测试包含三类 JWT clientType 声明校验；前端构建用于验证路由、组件和请求层可以正常打包。