酒店订单搜索服务

一个基于Spring Boot的微服务,通过客户电子邮件搜索酒店预订订单,支持GenAI集成模式。

  • by eriksterneberg
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 eriksterneberg/hotel-demo-service

使用说明

酒店演示服务-电子邮件订单搜索

Spring Boot微服务演示了通过客户电子邮件搜索酒店预订订单的GenAI集成模式。

🎯 特性

  • ✅ 精确电子邮件匹配搜索:使用客户电子邮件快速准确地检索订单
  • ✅ MCP工具集成:作为AI助手集成的模型上下文协议工具公开
  • ✅ 综合订单详情:返回预订日期、酒店信息、客人姓名、付款详情
  • ✅ PII保护:在日志中自动屏蔽电子邮件 PiiMaskingConverter
  • ✅ 字段级加密:敏感客户数据的Jasypt加密(AES-256-GCM)
  • ✅ Bean配置测试:用于捕获Spring上下文错误的集成测试
  • ✅ 完全可观察性:Prometheus指标、OpenTetry跟踪、结构化日志记录
  • ✅ REST API:用于测试的HTTP端点(MCP工具是主要接口)

🚀 快速开始

先决条件

  • Java 25
  • Docker&Docker编写
  • 制造

构建并运行

# 1. Start Cassandra database
make db-setup

# 2. Build the project
make build

# 3. Run the application
make run

该服务将在 http://localhost:8080

使用MCP工具

主要接口是MCP工具,Claude等AI助手可以通过模型上下文协议调用该工具:

工具名称: search_orders_by_email

参数:

  • email (必填):要搜索的客户电子邮件地址
  • customerId (必填):执行搜索的工作人员的ID
  • minConfidenceThreshold (可选):最小置信度得分(0-100),默认为70

示例用法 (通过AI助手):

Find hotel orders for john.doe@example.com

AI助手将自动调用该工具并为您格式化结果。

通过REST API进行测试(用于开发)

# Search for orders by email (exact match)
curl -X POST http://localhost:8080/api/orders/search \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "customerId": "staff-123"
  }'

# Example response
{
  "results": [
    {
      "orderId": null,
      "customerEmail": "john.doe@example.com",
      "bookingDateStart": "2025-12-24T16:00:00",
      "bookingDateEnd": "2025-12-27T12:00:00",
      "hotelName": "Grand Plaza Hotel",
      "hotelAddress": "123 Main Street, New York, NY 10001, USA",
      "roomType": "Deluxe Suite",
      "guestNames": ["John Doe", "Jane Doe"],
      "paymentMethod": "Credit Card - Visa",
      "totalAmount": 899.99,
      "orderStatus": "CONFIRMED",
      "confidenceScore": 100,
      "exactMatch": true,
      "fuzzyMatch": false
    }
  ],
  "searchMetadata": {
    "searchEmail": "***@example.com",
    "resultCount": 1,
    "minConfidenceThreshold": 70,
    "executionTimeMs": 52,
    "exactMatchCount": 1,
    "fuzzyMatchCount": 0
  }
}

备注:提供REST端点是为了方便开发/测试。MCP工具是人工智能集成的主要接口。

📚 技术栈

  • Java 25 带弹簧靴3.5.7
  • 等级9.0 构建系统
  • Apache卡桑德拉4.1 用于可扩展的数据存储
  • Spring数据Cassandra 用于数据库集成
  • Jasypt 用于PII加密(AES-256-GCM)
  • MCP Java SDK 用于模型上下文协议集成
  • 千分尺+开放遥测 可观察性
  • Logback 使用结构化JSON日志记录
  • JUnit5+Mockito 用于测试

🏗️ 建筑

┌─────────────────┐
│ MCP Tool        │ (EmailOrderSearchTool - PRIMARY INTERFACE)
└────────┬────────┘
         │
┌────────▼────────┐
│ REST API        │ (OrderSearchController - for testing)
└────────┬────────┘
         │
┌────────▼────────┐
│ Service Layer   │ (OrderSearchService)
└────────┬────────┘
         │
┌────────▼────────┐
│ Repository      │ (OrderRepository)
└────────┬────────┘
         │
┌────────▼────────┐
│ Cassandra DB    │ (with SASI indexes)
└─────────────────┘

MCP工具模式

这 EmailOrderSearchTool 实现了模型上下文协议(MCP)工具模式:

  • 工具名称: search_orders_by_email
  • 工具版本: 1.0.0
  • 输入架构:定义见 specs/001-email-order-search/contracts/mcp-tool-schema.json
  • 输出模式:退货 McpToolResponse 包含结果和元数据
  • 用法:专为人工智能代理设计,以协助售后人员处理客户查询

🧪 测试

该项目包括全面的测试覆盖范围:

  • 单元测试:服务层逻辑、加密、验证
  • 集成测试:Spring上下文加载,bean配置
  • 组件测试:DTO序列化、实体映射
# Run all tests
make test

# Generate coverage report
make coverage

# View coverage report
open build/reports/jacoco/test/html/index.html

关键集成测试

  • BeanConfigurationTest:捕获Spring bean配置错误(例如,没有@Primary的重复bean)
  • EncryptionServiceTest:验证Jasypt加密/解密
  • OrderSearchServiceTest:使用模拟存储库测试订单搜索逻辑

📋 生成文件目标

make help          # Show all available commands
make build         # Build the project
make test          # Run tests
make run           # Run the application
make clean         # Clean build artifacts
make check         # Run code quality checks
make coverage      # Generate test coverage report
make docker-build  # Build Docker image
make docker-run    # Run with Docker Compose
make db-setup      # Start Cassandra and load schema
make db-stop       # Stop Cassandra

🔒 安全

  • PII屏蔽:电子邮件地址在日志中被屏蔽(例如。, ***@example.com)使用自定义Logback转换器
  • 字段级加密:使用Jasypt(AES-256-GCM和PBKDF2)对客户电子邮件进行静态加密
  • 安全配置:通过环境变量外部化加密密码
  • 验证:使用Bean验证(JSR-380)进行输入验证
  • 豆类隔离: @Primary 注释确保加密服务的bean选择正确

📊 可观测性

  • 指标:可在 http://localhost:8080/actuator/prometheus
  • 健康:可在 http://localhost:8080/actuator/health
  • 追踪:具有跨度上下文传播的OpenTetry跟踪

🎓 学习目标

该项目展示了:

  1. Spring Boot最佳实践:分层架构、依赖注入、配置外部化、bean生命周期管理
  2. NoSQL数据建模:使用分区键和集群列的Cassandra模式设计
  3. 可观察性模式:具有PII掩码的度量、跟踪和结构化JSON日志记录
  4. 安全模式:使用Jasypt进行字段级加密、日志屏蔽、安全配置
  5. 测试驱动开发:单元测试、集成测试、bean配置测试、覆盖率报告
  6. GenAI集成:用于人工智能辅助客户服务的MCP工具模式
  7. 错误预防:在CI/CD期间捕获Spring上下文错误的集成测试

📖 文档

🤝 贡献

这是一个用于学习目的的演示项目。看 specs/001-email-order-search/ 完整的规范和实施计划。

📝 许可证

MIT许可证-有关详细信息,请参阅许可证文件


🐛 已知限制

  • 模糊匹配:尚未实施(仅与电子邮件完全匹配)
  • 订单编号:当前未在搜索结果中返回(将在未来的迭代中添加)
  • 分页:返回所有匹配结果(考虑分页用于生产)

状态:MVP完成(用户故事1-电子邮件完全匹配)✅
备注:模糊匹配功能将在未来的迭代中实现