# eh-trip

**Repository Path**: MISSMYSEIF/eh-trip

## Basic Information

- **Project Name**: eh-trip
- **Description**: 一款旅行智库项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-31
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 美途智库（eh-trip）

> 智慧文旅综合服务平台：覆盖景点、酒店、路线、资讯、订单、评论、收藏、搜索等核心业务，配套 Web 前台、管理后台、移动端 H5 与鸿蒙 App。后端支持 **SQLite（开发默认）/ MySQL（生产）** 双数据库，并对短信、对象存储、支付、地图、微信登录、**AI 大模型**等第三方能力做了 **Mock/真实 可切换** 的抽象封装。

> 📌 **最后更新：v1.4.216（2026-10-22）**　|　变更记录见 [变更日志](./docs/changelog/变更日志.md)

---

## ✨ 特性

- **零依赖开发**：默认使用 SQLite + 内存版 Redis，无需安装 MySQL / Redis 即可一键启动并自动建表 + 写入示例数据。
- **多数据库**：通过 Spring Profile 在 SQLite 与 MySQL 间切换，分页方言自动适配。
- **第三方对接即插即用**：未配置密钥时自动降级为 Mock（日志打印 / 占位返回），配置环境变量即切换为真实服务，含签名与回调验签。
- **支付闭环与对账**：支付/退款双向异步回调 + 状态幂等 + 金额校验；回调丢失时由定时对账任务主动查单补偿，避免漏单与库存不释放。
- **AI 智能能力**（可选）：智能问答 / 行程推荐 / 评论摘要 / 资讯草稿，**默认关闭**；开启后带每日配额与失败降级，密钥走环境变量。
- **完整文档**：架构、API、开发、部署、数据库、变更日志与第三方对接教程一应俱全（`docs/`）。
- **CI 流水线**：`.github/workflows/ci.yml` 把「后端全量测试 + Web / Admin / App 三端单测与构建 + pytest + Playwright E2E + 鸿蒙页面注册静态门禁」串成门禁（除 flyway-mysql 作业用专用 MySQL 8 服务容器验证生产建表外，其余零外部依赖、全部基于 SQLite）。各端实测用例数随版本演进，**最新命令级证据与数字以 [`docs/verification/<版本>/`](./docs/verification/) 取证工件为准**（每轮定版落盘，不在本 README 静态维护）。
- **一键脚本**：`scripts/start.ps1` / `scripts/stop.ps1`（推荐，支持 `-Frontends/-Profile/-SkipBuild/-Wait` 等参数）与 `start.bat` / `stop.bat` 一键启停开发环境（Windows）。
- **默认管理员**：`admin` / `admin123`。
- **开源协议**：MIT。

---

## 🛠 技术栈

Spring Boot 3.5.16 · MyBatis-Plus 3.5.17 · SQLite / MySQL 8 · Redis（可选）· springdoc-openapi（Swagger UI）· Spring Security + JWT · Vue3 + Vite · uni-app · ArkTS(Harmony)

---

## 🚀 快速开始

### 方式一：一键脚本（Windows）

```bat
start.bat   # 启动后端(8080) + Web(3000)/Admin(3001)/App(3002)
stop.bat    # 停止
```
> 推荐改用 PowerShell 脚本（功能更全、按端口精准停止，不影响 IDE 的 Java 语言服务器）：
> ```powershell
> .\scripts\start.ps1                 # 构建并启动后端 + 各前端
> .\scripts\start.ps1 -SkipBuild      # 已构建时跳过 mvn install，启动更快
> .\scripts\start.ps1 -Profile mysql  # 使用 MySQL profile 启动
> .\scripts\start.ps1 -Frontends web  # 只启动指定前端
> .\scripts\stop.ps1                  # 按端口精准停止后端
> ```

## 常见问题（FAQ）

- **端口冲突**：后端默认 8080。若被占用，`start.ps1` 启动会失败，先 `.\scripts\stop.ps1` 释放，或改 `application.yml` 的 `server.port`。
- **密钥弱校验拒绝启动**：微信支付 V3 要求 `WECHAT_PAY_API_V3_KEY` 恰为 32 字节，长度不符时启动期即判为「未就绪」并降级为 Mock，不是报错。
- **Mock 降级是正常的**：未配置 `AMAP_KEY` / `DASHSCOPE_API_KEY` / `WECHAT_PAY_*` / `ALIPAY_*` 时，地图、AI、支付等通道自动降级为 Mock，不影响本地开发；配齐环境变量后即恢复真实调用。
- **密钥只走环境变量**：所有第三方密钥（高德 `AMAP_KEY`、AI `DASHSCOPE_API_KEY`、微信 `WECHAT_PAY_*`、支付宝 `ALIPAY_*` 等）仅通过环境变量注入，**禁止硬编码**。详见 `docs/integrations/`。
- **业务异常返回 200**：全局异常处理器对 `BusinessException` 等业务异常统一返回 **HTTP 200**，错误由响应体 `code` 表达；仅参数校验失败（`@Valid` / 类型错误 / 缺失参数）返回 HTTP 400。客户端**必须依据响应体 `code===200` 判定成功**，不能仅凭 HTTP 状态码。

> App（uni-app）的 API 基址可在「个人中心 → 服务器地址」运行时修改，真机调试请填开发机局域网 IP；详见 [部署文档](./docs/deployment/部署文档.md) §2.1。

### 方式二：手动

```bash
# 后端（默认 SQLite 开发环境）
cd eh-trip-server
mvn install -DskipTests -Djacoco.skip=true
mvn -pl eh-trip-api spring-boot:run -Dspring-boot.run.profiles=sqlite

# 前端（任选）
cd eh-trip-web   && npm install && npm run dev        # 前台 3000
cd eh-trip-admin && npm install && npm run dev        # 管理后台 3001
cd eh-trip-app   && npm install && npm run dev:h5     # 移动端（uni-app）3002
```

- 接口文档：http://localhost:8080/api/v1/swagger-ui.html
- 默认管理员：`admin` / `admin123`（或手机号 `13800000000`）

> 切换到 MySQL 生产环境：本地准备 MySQL 8 + Redis 7，启动时指定 `-Dspring-boot.run.profiles=mysql`；首次启动会由 Flyway 执行 `db/migration/` 下的脚本（当前 `V1__baseline.sql` + `V2__unique_active_invoice.sql`）建库（目录：`eh-trip-server/eh-trip-api/src/main/resources/db/migration/`），无需手工建表。
>
> ⚠️ **当前数据库策略：基线 + 增量迁移并行。** `db/migration/` 目录当前含 `V1__baseline.sql` 与
> `V2__unique_active_invoice.sql` 两个脚本（历史变更已并入基线，其后新增迁移以 `V{N}__*.sql` 增量追加）。因此：
> - 开发者：新增结构变更一律**追加 `V{N}__*.sql`（版本号递增）**并同步 `db/sqlite/schema.sql`；**不得修改已入库的历史脚本**
>   （Flyway 校验和不匹配会直接启动失败），详见 `docs/development/数据库迁移指南.md`；
> - SQLite 开发库另有 `SqliteColumnMigrator` 在启动时补列，详见 `docs/database/数据库文档.md`。

---

## 📁 目录结构

```
eh-trip-server   后端（common / model / auth / service / api）
eh-trip-web      前端前台（Vue3 + Vite）
eh-trip-admin    管理后台（Vue3 + Vite）
eh-trip-app      移动端 H5（uni-app）
eh-trip-harmony  鸿蒙 App（ArkTS）
docs/            项目文档（架构/API/开发/部署/数据库/对接教程/变更日志）
tests/           Python API 测试（pytest）+ Playwright E2E（tests/e2e，可接入真实环境）
scripts/start.ps1、start.bat 等  一键启停脚本（推荐 start.ps1，详见下方「常见问题」）
LICENSE          MIT 协议
```

---

## 🔌 第三方对接

所有第三方能力均已抽象为接口并支持 Mock/真实切换，密钥通过环境变量注入。详见 [第三方对接总览](./docs/integrations/总览.md)：

- 阿里云短信 · 阿里云 OSS（含 STS 临时凭证）· 微信支付（API v3）· 支付宝支付 · 高德地图 · 微信登录
- [AI 智能能力（阿里云百炼 · 通义千问）](./docs/integrations/AI智能能力.md) —— 零基础手把手：申请 Key → 环境变量 → 联调 → 上线检查清单

---

## 📚 文档

- [架构设计](./docs/architecture/架构设计.md)
- [开发指南](./docs/development/开发指南.md)
- [API 接口文档](./docs/api/API接口文档.md)
- [部署文档](./docs/deployment/部署文档.md)
- [数据库文档](./docs/database/数据库文档.md)
- [E2E 端到端测试指南](./docs/development/E2E端到端测试指南.md)
- [CI 流水线指南](./docs/development/CI流水线指南.md)
- [变更日志](./docs/changelog/变更日志.md)

---

## 🧪 测试

```bash
# 后端单元/集成测试（需 JDK 25）
cd eh-trip-server && mvn test

# 前端单元测试（vitest）
cd eh-trip-web   && npm run test:unit
cd eh-trip-admin && npm run test:unit

# API 集成测试（pytest，需后端已启动于 http://localhost:8080）
cd tests && pip install -r requirements.txt && pytest

# 端到端测试（Playwright，可接入真实环境；详见 docs/development/E2E端到端测试指南.md）
npm install && npx playwright install chromium
npm run test:e2e            # 全量；写数据的下单用例默认跳过，需 E2E_ALLOW_MUTATIONS=1
```

> E2E 支持通过 `.env.e2e`（模板见 `.env.e2e.example`）配置基址与账号，既可跑本地 docker 环境，也可直接指向已部署环境。

---

## 📄 开源协议

本项目基于 [MIT License](./LICENSE) 开源。