基于 Spring Boot 3.4.2 + Vue 3.x 的现代化宠物医院管理系统，采用微服务架构和前后端分离设计。

PetClinic 是一个功能完整的宠物医院管理平台，提供宠物档案管理、兽医排班、预约系统、医疗记录跟踪等核心功能。系统采用领域驱动设计（DDD）原则，具备高可用性、可扩展性和安全性。

• 🏥 微服务架构 - 6个独立微服务，松耦合设计
• 🔐 安全认证 - 基于 Keycloak 的 OAuth2/OIDC 认证
• 📊 实时监控 - Spring Boot Actuator + SkyWalking 链路追踪
• 🚀 容器化部署 - Docker + Docker Compose 多环境支持
• 📱 响应式前端 - Vue 3.x + TDesign UI 组件库
• 🧪 全面测试 - 单元测试 + 集成测试 + 端到端测试

• 🏢 宠物医院管理人员 - 机构运营和数据分析
• 🩺 兽医和医护人员 - 日常诊疗和患者管理
• 🐾 宠物主人 - 预约和宠物健康追踪
• 🔧 系统管理员 - 系统维护和权限管理

技术	版本	用途
Spring Boot	3.4.2	核心框架
Spring Cloud	2023.0.0	微服务支持
Keycloak	22.0	身份认证
MySQL	8.0	主数据库
Redis	7.0	缓存
Nacos	2.2.3	服务注册与发现
Seata	1.7.1	分布式事务
Resilience4j	2.1.0	熔断降级

技术	版本	用途
Vue	3.x	核心框架
TypeScript	5.0	类型安全
TDesign	1.0	UI组件库
Pinia	2.0	状态管理
Vite	5.0	构建工具

• 容器化: Docker + Docker Compose
• 监控告警: Spring Boot Actuator
• 链路追踪: SkyWalking + Zipkin

petclinic/
├── services/                # 微服务模块 (6个核心服务)
│   ├── user-service/       # 用户服务 (端口: 8081)
│   ├── pet-service/        # 宠物服务 (端口: 8082)
│   ├── vet-service/        # 兽医服务 (端口: 8083)
│   ├── appointment-service/ # 预约服务 (端口: 8084)
│   ├── medical-record-service/ # 病历服务 (端口: 8085)
│   └── sync-service/       # 同步服务 (端口: 8086)
├── frontend/               # Vue 3.x 前端应用
│   ├── src/                # 源代码目录
│   ├── public/             # 静态资源
│   ├── package.json        # 依赖配置
│   └── Dockerfile          # 容器配置
├── common/                 # 公共模块库
│   ├── core/               # 核心工具类
│   └── security/           # 安全组件
├── infrastructure/         # 基础设施配置
├── keycloak/              # Keycloak认证服务
├── nacos-config/          # Nacos配置中心
├── sql/                   # 数据库脚本
├── scripts/              # 部署和测试脚本
├── docker-compose.*.yml   # 多环境Docker配置 (9个环境)
└── pom.xml               # Maven父项目配置

工具	版本	备注
JDK	21+	推荐使用 Kona JDK 21
Node.js	18+	推荐使用 18.17.0+
Docker	20.10+	容器化支持
MySQL	8.0+	数据库
Redis	7.0+	缓存
Maven	3.6+	构建工具
pnpm	8.0+	包管理器

工具	版本	备注
JDK	21+	推荐使用 Kona JDK 21
Node.js	18+	推荐使用 18.17.0+
Docker	20.10+	容器化支持
MySQL	8.0+	数据库
Redis	7.0+	缓存
Maven	3.6+	构建工具
pnpm	8.0+	包管理器

1. 克隆项目

git clone <repository-url>
cd copilotcli-petclinic

2. 启动基础设施 (推荐使用轻量级配置)

# 使用轻量级配置快速启动
docker-compose -f docker-compose.lightweight.yml up -d

# 或者使用开发环境完整配置
docker-compose -f docker-compose.dev.yml up -d

3. 启动后端服务

# 编译整个项目
mvn clean compile

# 批量启动所有微服务 (推荐)
./scripts/start-all-services.sh

# 或者单独启动服务
cd services/user-service && mvn spring-boot:run
cd services/pet-service && mvn spring-boot:run
# ... 其他服务端口请参考下表

4. 启动前端应用

cd frontend
pnpm install
pnpm dev

服务	端口	健康检查地址
API Gateway	8080	http://localhost:8080/actuator/health
User Service	8081	http://localhost:8081/actuator/health
Pet Service	8082	http://localhost:8082/actuator/health
Vet Service	8083	http://localhost:8083/actuator/health
Appointment Service	8084	http://localhost:8084/actuator/health
Medical Record Service	8085	http://localhost:8085/actuator/health
Sync Service	8086	http://localhost:8086/actuator/health

# 完整开发环境（包含所有基础设施）
docker-compose -f docker-compose.dev.yml up -d

# 或者使用轻量级配置（推荐用于快速开发）
docker-compose -f docker-compose.lightweight.yml up -d

# 测试环境配置
docker-compose -f docker-compose.test.yml up -d

# 或者使用简单配置
docker-compose -f docker-compose.simple.yml up -d

# 构建生产镜像
docker-compose -f docker-compose.prod.yml build

# 启动生产服务
docker-compose -f docker-compose.prod.yml up -d

# ARM64架构兼容配置
docker-compose -f docker-compose.arm64.yml up -d

• 用户服务 (user-service): 用户注册、登录、权限管理
• 宠物服务 (pet-service): 宠物档案管理、健康记录跟踪
• 兽医服务 (vet-service): 兽医信息管理、排班安排
• 预约服务 (appointment-service): 在线预约、时间冲突检测
• 病历服务 (medical-record-service): 就诊记录、诊断方案管理
• 同步服务 (sync-service): 数据同步、批量处理

• 服务注册与发现: 基于Nacos的服务治理
• 配置中心: 统一配置管理，支持动态刷新
• 分布式事务: 基于Seata的分布式事务管理
• 熔断降级: Resilience4j实现的容错机制
• 链路追踪: SkyWalking + Zipkin全链路监控

• OAuth2/OIDC: 基于Keycloak的统一认证
• RBAC权限控制: 基于角色的细粒度权限管理
• JWT令牌: 无状态认证机制
• API安全: 接口级别的访问控制

• 多数据源支持: MySQL主从复制配置
• 缓存策略: Redis多级缓存优化
• 数据一致性: Seata分布式事务保证
• 数据备份: 自动备份和恢复机制

• 健康检查: Spring Boot Actuator端点
• 指标收集: Prometheus格式的指标输出
• 日志聚合: 结构化JSON日志记录
• 链路追踪: SkyWalking + Zipkin全链路监控

系统提供完整的OpenAPI 3.0文档，每个微服务都有独立的API文档：

• 用户服务: http://localhost:8081/swagger-ui.html
• 宠物服务: http://localhost:8082/swagger-ui.html
• 兽医服务: http://localhost:8083/swagger-ui.html
• 预约服务: http://localhost:8084/swagger-ui.html
• 病历服务: http://localhost:8085/swagger-ui.html

通过API网关统一访问所有服务：

• 开发环境: http://localhost:8080/swagger-ui.html
• 生产环境: https://api.petclinic.example.com/swagger-ui.html

# 检查单个服务健康状态
curl http://localhost:8081/actuator/health

# 通过API网关检查所有服务健康状态
curl http://localhost:8080/actuator/health

# 检查微服务健康状态汇总
curl http://localhost:8080/actuator/health/details

# 获取服务指标数据
curl http://localhost:8081/actuator/metrics

# 获取 Prometheus 格式指标
curl http://localhost:8081/actuator/prometheus

# 查看JVM指标
curl http://localhost:8081/actuator/metrics/jvm.memory.used

# 查看服务信息
curl http://localhost:8081/actuator/info

# 查看环境配置
curl http://localhost:8081/actuator/env

# 查看Bean定义
curl http://localhost:8081/actuator/beans

• 确保 Docker 已正确安装并运行。
• 检查端口 8080 是否被占用。

• 检查后端服务是否已启动。
• 确保前端配置中的 API 地址正确。

• 检查 MySQL 服务是否运行。
• 验证数据库配置是否正确。

1. 提交 Issue：描述问题或建议。
2. Fork 项目：创建自己的分支。
3. 提交 Pull Request：确保代码符合规范并通过测试。 curl http://localhost:8081/actuator/env

### 日志查看
```bash
# 查看特定服务日志
docker-compose logs -f user-service

# 查看所有服务日志
docker-compose logs -f

# 查看最近100行日志
docker-compose logs --tail=100

• 后端IDE: IntelliJ IDEA Ultimate
• 前端IDE: VS Code 或 WebStorm
• 数据库工具: DBeaver / MySQL Workbench
• API测试: Postman / Insomnia
• 容器管理: Docker Desktop

• 代码规范: 遵循 Google Java代码风格
• 测试覆盖率: 目标80%指令覆盖率 (参考 测试报告)
• 安全检查: 集成TCA代码分析工具

# 后端测试
mvn test
mvn jacoco:report

# 前端开发
cd frontend && pnpm lint
cd frontend && pnpm build

# 数据库操作
mysql -u root -p < sql/init-database.sql

• 端口冲突: 检查端口占用情况
• 数据库连接: 验证MySQL服务状态
• 服务注册: 确认Nacos服务发现
• 认证问题: 检查Keycloak配置

查看 问题修复记录 获取常见问题的解决方案。

文档	说明	链接
架构设计	详细技术架构说明	petclinic-archi.md
开发指南	开发环境搭建和规范	DEVELOPMENT.md
测试报告	代码测试覆盖率统计	TEST_COVERAGE_SUMMARY.md
生产部署	生产环境部署说明	petclinic-prd.md
问题修复	常见问题解决方案	PROBLEM_FIXES_SUMMARY.md
前端修复	前端完整修复记录	FRONTEND_FIX_COMPLETE.md
医疗记录	病历服务配置说明	MEDICAL_RECORDS_SETUP.md

本项目采用 MIT 许可证。

• 项目仓库: GitHub Repository
• 问题反馈: Issue Tracker
• 技术讨论: Discussions Forum
• 邮箱支持: petclinic-support@example.com

---

🛠️ 开发团队: PetClinic开发团队
⚙️ 技术栈: Spring Boot 3.4.2 + Vue 3.x + Docker + Microservices
📦 版本: v1.0.0
🔄 最后更新: 2025-10-24
✅ 状态: 生产就绪 (参考 验证报告)