民宿预订平台 (Homestay Booking Platform)

English | 中文

民宿预订平台是一个连接房客、房东和平台管理员的综合业务系统，覆盖房源发布、平台审核、在线搜索、下单支付、入住退房、评价反馈、收益统计和后台监管等完整流程。

25 个业务模块 · 10W+ 行代码 · 267 次 commit · 持续迭代 16 个月 · 50+ 篇项目文档

项目背景

Homestay 是一个单人独立交付的全栈项目，覆盖 25 个业务模块、10W+ 行代码，后端 Spring Boot 3 + 前端 Vue 3 + MySQL / Redis / Elasticsearch / 支付宝完整链路。

项目从 2025 年 2 月持续迭代至今，我借助 AI 编码工具（Cursor / Claude Code / Kimi Code CLI 等）完成 90% 的编码工作，自己负责架构设计、需求决策、代码审查、关键模块攻关与质量把控。

这种工作流让我一个人就能 cover 三端（用户端 / 房东端 / 管理员端）的全部交付，也是 2026 年 AI 时代全栈工程师的一个真实缩影。

工具链迭代：Cursor Pro → Claude Code CLI → Kimi Code CLI

目录

• 项目亮点
• 技术栈
• 系统架构
• 系统角色
• 功能概览
• 核心业务流程
• 项目结构
• 快速开始
• 配置说明
• 测试与构建
• 文档索引
• 安全说明
• 许可证

项目亮点

• 三端一体：用户端、房东端、管理员端共用后端能力，分别覆盖消费、经营和平台治理场景。
• Elasticsearch 房源搜索：支持全文检索、条件筛选、地理坐标索引与搜索、相似房源推荐，搜索结果可个性化排序。
• 智能个性化推荐引擎：基于用户历史订单、收藏行为、浏览轨迹构建用户画像，实现热门推荐、个性化推荐、基于位置的推荐和相似房源推荐四种策略，支持三级降级兜底与结果多样化。
• 动态定价引擎：支持周末溢价、节假日调价、连住折扣、提前预订优惠等多维度定价规则，作用域覆盖全局/城市/房东/房源组/单个房源，支持调休补班识别与订单价格快照锁定。
• 用户行为追踪与画像：异步埋点采集搜索、浏览、点击、收藏、预订、分享等行为事件，定时聚合用户画像（价格偏好、位置偏好、房型偏好、设施偏好），反哺推荐引擎形成闭环。
• 优惠券营销系统：支持优惠券模板管理、用户领取（悲观锁防超领）、订单核销、过期清理、批量发放与 ROI 分析。
• 订单自动化状态机：基于定时任务实现订单自动入住、自动退房、超时取消（待确认/待支付/支付中三级场景），支持历史订单状态批量修复。
• 房源智能特征分析：从房源类型、价格竞争力、设施组合、位置优势、预订活跃度、周末流行度、用户评价、入住便利性 8 个维度自动生成房源特色标签，并根据用户搜索条件动态提升匹配标签优先级。
• Redis 分布式锁：基于 Lua 脚本实现原子解锁，防止误删其他线程的锁，Redis 不可用时自动降级为无锁模式。
• 价格竞争力分析：同区域/同城市/同类型多级降级比价，结合季节性因子输出竞争力等级与价格建议。
• 地图找房体验：集成高德地图，支持位置搜索、周边检索、距离计算和地图展示。
• 支付集成：接入支付宝沙箱支付（页面跳转支付 + 扫码支付），支持订单支付、异步回调、状态查询和退款。
• 工程化后端：统一响应、全局异常、权限注解、DTO 映射、缓存、数据库迁移和审计日志。

近期工程化增强（2026-08）

消息架构（RabbitMQ 三场景）

flowchart LR
    subgraph S1["① 订单超时 · DLX 延迟队列"]
        direction LR
        O1[下单] --> O2[延迟队列<br/>TTL 2h] --> O3[DLX 死信<br/>→ 消费队列] --> O4[幂等校验<br/>→ 系统取消]
    end
    subgraph S2["② 批量发券 · 消息驱动 + 重试队列"]
        direction LR
        C1[创建任务] --> C2[主队列] --> C3[消费者发券<br/>逐条入账] --> C4[失败进重试队列<br/>60s 后自动重试 ≤3 次]
    end
    subgraph S3["③ 通知推送 · 可靠投递"]
        direction LR
        N1[事务提交] --> N2[主队列] --> N3[WebSocket<br/>实时推送] --> N4[进程崩溃不丢<br/>重启自动补推]
    end

统一模式：主队列 + 重试/延迟队列（TTL 死信回主）、消费者手动 ack + 幂等校验、mq-enabled 开关降级、定时任务兜底。详细图见 obsidian-vault/03-后端/后端-RabbitMQ 消息架构.md。

技术栈

系统架构

矢量版：docs/architecture.svg（本地 docs/architecture.drawio 为 draw.io 可编辑源，按 .gitignore 约定不入库）。

系统角色

功能概览

用户端

房东端

管理员端

后端能力

AI 客服 Agent（三层架构）

详细设计见 obsidian-vault/04-架构分析/方案-AI客服Agent-三方权限矩阵.md（v1.0），测试见 obsidian-vault/04-架构分析/AI客服Agent-测试报告.md。

核心业务流程

房源发布与审核

房东创建房源草稿
  -> 补充位置、设施、描述和图片
  -> 提交审核
  -> 管理员审核
  -> 审核通过后上线 / 审核拒绝后退回修改

订单生命周期

房客提交订单
  -> 待支付
  -> 已支付
  -> 房东确认
  -> 准备入住
  -> 已入住（定时任务自动流转）
  -> 已退房（定时任务自动流转）
  -> 已完成
  -> 房客评价

退款与争议

房客申请退款
  -> 房东审核
  -> 同意退款 -> 退款中 -> 退款完成
  -> 拒绝退款 -> 用户发起争议 -> 管理员介入处理

收益结算

订单完成
  -> 生成房东收益
  -> 进入可结算金额
  -> 房东查看收益统计与趋势

项目结构

homestay3/
├── homestay-front/          # 用户端 + 房东端，Vue 3 + Vite
├── homestay-admin/          # 管理员端，Vue 3 + Vite
├── homestay-backend/        # 后端 API，Spring Boot
├── docs/                    # 项目说明文档
│   └── INSTALL.md           # 安装教程（含 AI Agent 安装指引）
├── tools/                   # 本地工具脚本或辅助工具
├── docker-compose.yml       # Docker Compose 配置（含 Elasticsearch）
├── README.md                # 项目总览（中文）
├── README_EN.md             # 项目总览（英文）
└── .gitignore               # Git 忽略规则

后端主要分层：

com.homestay3.homestaybackend
├── config/                  # 安全、缓存、跨域、WebSocket、支付等配置
├── controller/              # REST API 控制器
├── service/                 # 核心业务逻辑
│   ├── search/              # 搜索与推荐相关服务
│   ├── agent/               # AI 客服（工具、LLM 客户端）
│   └── gateway/             # 支付网关
├── repository/              # JPA 数据访问层
├── entity/                  # 数据库实体
├── dto/                     # 数据传输对象
├── mapper/                  # MapStruct 映射
├── model/                   # 枚举和常量
├── annotation/              # 自定义注解（@RateLimit / @OperationLog / @RedisLock）
├── aspect/                  # AOP 切面（限流 / 操作日志 / 分布式锁 / 接口耗时）
├── mq/                      # RabbitMQ 生产者与消费者
├── exception/               # 全局异常处理
├── security/                # JWT 与认证授权
├── util/                    # 通用工具类
└── job/                     # 定时任务

快速开始

完整的安装教程（含 AI Agent 自动安装指引）见 docs/INSTALL.md。

环境要求

1. 克隆项目

git clone https://github.com/goaltang/homestay3.git
cd homestay3

2. 启动基础设施

MySQL — 创建数据库：

mysql -u root -p -e "CREATE DATABASE homestay_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

Redis — 确保 Redis 在 localhost:6379 运行：

redis-server --daemonize yes

Elasticsearch（可选） — 通过 Docker Compose 启动：

docker-compose up -d elasticsearch

注意：elasticsearch.enabled=false 仅关闭索引同步与 ES 搜索降级为 JPA，但 ElasticsearchRepository 仍会初始化，ES 容器必须保持在线，否则后端启动失败。

RabbitMQ（可选，订单超时延迟队列） — 通过 Docker Compose 启动：

docker-compose up -d rabbitmq

管理台地址：http://localhost:15672（默认账号 homestay / homestay123，可在 compose 中修改）。订单超时采用「RabbitMQ 延迟队列为主 + 定时轮询兜底」双保险：MQ 不可用时，轮询任务仍会取消超时订单，因此不启动 RabbitMQ 也不影响系统正确性。

3. 配置后端

复制配置模板并修改：

cd homestay-backend
cp src/main/resources/application.example.properties src/main/resources/application-local.properties

编辑 application-local.properties，填入本地的 MySQL 密码、Redis 密码、JWT 密钥等。

也可以直接修改 application.properties，但请注意不要将敏感信息提交到仓库。

4. 启动后端

cd homestay-backend
mvn clean compile
mvn spring-boot:run

后端默认运行在 http://localhost:8081。Flyway 会自动执行全部数据库迁移（V1 ~ V49，共 41 个脚本），无需手动建表。

5. 启动用户端和房东端

cd homestay-front
cp .env.example .env.local   # 可选，配置高德地图 Key
npm install
npm run dev

访问 http://localhost:5173。Vite 已配置代理，/api 请求自动转发到后端 http://127.0.0.1:8081。

6. 启动管理员端

cd homestay-admin
npm install
npm run dev

访问 http://localhost:5174。Vite 已配置代理，/api 请求自动转发到后端。

首次使用

首次启动后端时，DataInitializer 会自动初始化默认设施数据，AdminServiceImpl 会自动创建默认管理员账号 admin / admin888（ROLE_ADMIN，仅当 admin 用户不存在时创建）。

• 管理员：直接用 admin / admin888 登录管理端（localhost:5174）。
• 房客 / 房东：在用户端 (localhost:5173) 注册账号即可使用。

配置说明

后端配置文件位于：

homestay-backend/src/main/resources/application.properties

本地运行需要关注这些配置：

前端环境变量：

测试与构建

后端

cd homestay-backend
mvn test
mvn clean package

测试构成（60 个测试类，全部 H2 内存库）：

• 单元测试：src/test/java/.../mq/（MQ 消费者：订单超时/批量发券/通知推送）、service/impl/（订单/支付/券/争议/通知/审核等核心规则）、service/agent/（AI 客服：工具注册/写工具只读校验/两阶段编排）、service/search/（ES 降级/画像聚合）、aspect/（@RateLimit/@RedisLock/@OperationLog 三个切面）
• API 自动化测试：src/test/java/.../api/（AuthApiTest / OrderApiTest / CouponApiTest / NotificationApiTest，验证认证、下单、发券、通知全链路，H2 内存库 + MQ 降级路径）
• 集成测试：src/test/java/.../integration/（BookingWorkflow / ConcurrentBooking 并发防超卖等）

⚠️ 测试安全红线：所有测试必须走 application-test.properties（H2 内存库），禁止连接真实 MySQL（历史曾发生测试清空生产数据事故）。

用户端

cd homestay-front
npm run build

管理员端

cd homestay-admin
npm run build

文档索引

安全说明

本仓库不包含任何真实密钥：application.properties 已被 .gitignore 排除，仓库内仅提供
application.example.properties 模板（数据库密码、JWT 密钥、支付宝私钥、LLM API Key 等均为占位符）。
请复制为 application-local.properties 并填入本地真实值，切勿将真实密钥提交到仓库。

许可证

MIT License