# spa-well

**Repository Path**: legendsoft/spa-well

## Basic Information

- **Project Name**: spa-well
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SPA-WELL 青岛工人温泉疗养院系统

## 项目简介

青岛工人温泉疗养院综合管理系统，提供健康档案管理、疗养团管理、在线咨询、内容管理等核心业务功能。

## 技术栈

| 类型 | 技术 | 版本 |
|-----|------|------|
| 基础框架 | Spring Boot | 2.1.17.RELEASE |
| 持久层 | MyBatis + PageHelper | 2.1.4 / 1.4.3 |
| 数据库 | MySQL | 8.x |
| 缓存 | Redis + Spring Session | 2.1.10.RELEASE |
| 对象映射 | MapStruct | 1.4.2.Final |
| 工具类 | Lombok | - |
| 认证 | JWT | 0.12.6 |
| 微服务 | Spring Cloud Alibaba | 2.1.4.RELEASE |
| 数据库迁移 | Flyway | - |

## 架构设计

采用 **DDD 领域驱动设计 + 洋葱架构**，依赖方向由外向内，内层不依赖外层。

```
┌─────────────────────────────────────────────────────────────┐
│                    Interface Layer（接口层）                  │
│                      Controller / API                        │
├─────────────────────────────────────────────────────────────┤
│                  Application Layer（应用层）                  │
│              AppService / DTO / Factory                      │
├─────────────────────────────────────────────────────────────┤
│                    Domain Layer（领域层）                     │
│           Entity / Repository Interface / DomainService      │
├─────────────────────────────────────────────────────────────┤
│               Infrastructure Layer（基础设施层）              │
│          Repository Impl / Config / External Service         │
└─────────────────────────────────────────────────────────────┘
```

## 项目结构

```
spa-well/
├── pom.xml                              # 根 POM（版本管理、依赖管理）
│
├── qws-infrastructure/                  # 【基础设施层】
│   ├── pom.xml
│   ├── framework-common/                # 框架通用模块
│   │   └── 全局配置、异常处理、MyBatis 扩展、UUID 工具
│   └── hgiam-client/                    # IAM 认证客户端
│       └── SSO 认证、OpenAPI 客户端、JWT 工具
│
├── qws-shared/                          # 【通用业务层】
│   ├── pom.xml
│   ├── hg-sysmenu/                      # 系统菜单模块
│   │   └── 菜单管理、按钮权限
│   └── hg-filestore/                    # 文件存储模块
│       └── 文件上传/下载、多存储支持（本地/阿里云 OSS）
│
├── qws-business/                        # 【核心业务层】
│   ├── pom.xml
│   ├── hg-sys/                          # 系统管理模块
│   │   └── 角色管理、操作日志
│   ├── hg-cms/                          # 内容管理模块
│   │   └── Banner、栏目、文章管理
│   ├── hg-health/                       # 健康档案模块
│   │   └── 健康档案、体检报告
│   ├── hg-caregroup/                    # 疗养团模块
│   │   └── 疗养团、成员、排班管理
│   └── hg-consult/                      # 在线咨询模块
│       └── 咨询会话、消息管理
│
└── qws-services/                        # 【启动聚合层】
    ├── pom.xml
    ├── qws-archive-service/             # 健康档案服务
    │   └── 面向档案管理的独立服务
    └── qws-mobile-service/              # 移动端服务
        └── 面向移动端的 API 服务
```

## 模块说明

### 基础设施层（qws-infrastructure）

| 模块 | 职责 | 包路径 |
|-----|------|--------|
| framework-common | 全局配置、异常处理、MyBatis UUID 拦截器 | com.hgxx.common |
| hgiam-client | SSO 认证（JWT/OAuth2）、OpenAPI 客户端 | com.hgiam.support |

### 通用业务层（qws-shared）

| 模块 | 职责 | 数据库表 |
|-----|------|---------|
| hg-sysmenu | 系统菜单、按钮权限管理 | sys_menu |
| hg-filestore | 文件上传下载、存储管理 | file_info, file_chunk_info |

### 核心业务层（qws-business）

| 模块 | 职责 | 数据库表 |
|-----|------|---------|
| hg-sys | 角色管理、操作日志 | sys_role, sys_log |
| hg-cms | Banner、栏目、文章管理 | cms_banner, cms_category, cms_content |
| hg-health | 健康档案、体检报告 | health_profile, health_report |
| hg-caregroup | 疗养团、成员、排班 | care_group, care_group_member, care_group_schedule |
| hg-consult | 在线咨询会话、消息 | consult_session, consult_message |

### 启动聚合层（qws-services）

| 服务 | 聚合模块 | 说明 |
|-----|---------|------|
| qws-archive-service | health, caregroup, consult | 健康档案管理服务 |
| qws-mobile-service | health, caregroup, consult, cms | 移动端 API 服务 |

## 业务模块内部结构

每个业务模块遵循洋葱架构分层：

```
hg-{domain}/
├── application/                 # 应用层
│   ├── dto/                     # 数据传输对象
│   ├── factories/               # 领域对象工厂（MapStruct）
│   └── service/                 # 应用服务（事务边界）
│       └── {Domain}AppService.java
│
├── domain/                      # 领域层（无技术依赖）
│   ├── model/                   # 聚合根、实体、值对象、枚举
│   ├── repository/              # 仓储接口（只定义）
│   └── service/                 # 领域服务（业务规则）
│
├── infrastructure/              # 基础设施层
│   ├── config/                  # 模块配置
│   ├── persistence/             # 持久化实现
│   │   ├── dataobject/          # DO（数据库映射）
│   │   ├── mapper/              # MyBatis Mapper
│   │   └── repositoryimpl/      # 仓储实现
│   └── storage/                 # 外部存储
│
└── interfaces/                  # 接口层
    └── controller/              # REST API
```

## 快速开始

### 环境要求

- JDK 1.8+
- Maven 3.6+
- MySQL 8.0+
- Redis 5.0+

### 本地运行

```bash
# 1. 克隆项目
git clone {repository-url}
cd spa-well

# 2. 编译项目
mvn clean install -DskipTests

# 3. 配置数据库和 Redis
# 修改 qws-services/qws-archive-service/src/main/resources/application.yml

# 4. 运行服务
cd qws-services/qws-archive-service
mvn spring-boot:run
```

### 数据库初始化

项目使用 Flyway 自动迁移数据库，启动时自动执行 `db/migration` 下的 SQL 脚本。

## 开发规范

### ID 规范

- 所有实体 ID 使用 `java.util.UUID` 类型
- 数据库字段使用 `BINARY(16)` 存储
- ID 由 MyBatis 拦截器自动生成 UUIDv7（禁止手动设置）

### 命名规范

| 类型 | 格式 | 示例 |
|-----|------|------|
| 模块目录 | `qws-{layer}` 或 `hg-{domain}` | qws-infrastructure, hg-health |
| 包名 | `com.hgxx.{domain}` | com.hgxx.health |
| 领域模型 | `{业务名}` | HealthProfile |
| 仓储接口 | `{业务名}Repository` | HealthProfileRepository |
| 应用服务 | `{业务名}AppService` | HealthAppService |
| 控制器 | `{业务名}Controller` | HealthProfileController |
| DTO | `{业务名}DTO` | HealthProfileDTO |
| DO | `{业务名}DO` | HealthProfileDO |

### Controller 规范

- 所有请求地址以 `/api` 开头
- 所有 ID 类型路径参数使用 `UUID` 类型
- 入参使用 DTO + Spring Boot 校验注解
- 返回值使用 `R<T>` 统一包装

```java
@RestController
@RequestMapping("/api/health-profiles")
public class HealthProfileController {
    
    @GetMapping("/{id}")
    public R<HealthProfileDTO> getById(@PathVariable UUID id) {
        return R.ok(healthAppService.getById(id));
    }
}
```

## 相关文档

- [后端技术规范](/.trae/rules/backendrule.md)
- [ID 使用规范](/.trae/rules/backendrule-id.md)
- [MyBatis 规范](/.trae/rules/mybatis.md)
- [模块分类方案](/.trae/documents/spa-well-layered-modules-plan.md)

## 许可证

内部项目，仅供青岛工人温泉疗养院使用。