# annual-ring

**Repository Path**: evanyue/annual-ring

## Basic Information

- **Project Name**: annual-ring
- **Description**: # 年轮 (Annual Ring)

族谱管理系统，寓意文化代代相传，如树木年轮般记录家族历史。本系统基于Spring Boot 3.x开发，不仅能够管理族谱信息，还支持基于地图的家族位置定位功能。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 年轮 (Annual Ring)

族谱管理系统，寓意文化代代相传，如树木年轮般记录家族历史。本系统基于Spring Boot 3.x开发，不仅能够管理族谱信息，还支持基于地图的家族位置定位功能。

## 技术栈

- **核心框架**: Spring Boot 3.2.0
- **Java版本**: Java 17
- **构建工具**: Maven
- **权限认证**: Sa-Token 1.37.0
- **工具类库**: Hutool 5.8.24
- **地理空间处理**: GeoTools 32.3
- **数据库**: PostgreSQL (生产环境) / H2 (测试环境) (通过Spring Data JPA 和 MyBatis-Flex)
- **代码简化**: Lombok 1.18.20
- **前端框架**: Vue 3 + Element Plus + Leaflet (可嵌入式低代码方案)

## 项目结构

```
.
├── src
│   ├── main
│   │   ├── java
│   │   │   └── simonby
│   │   │       └── top
│   │   │           └── annualring
│   │   │               ├── AnnualRingApplication.java     # 主启动类
│   │   │               ├── adapter/                       # 适配层(Adapters)
│   │   │               │   ├── controller/               # 控制器
│   │   │               │   └── dto/                      # 数据传输对象
│   │   │               ├── application/                  # 应用层(Applications)
│   │   │               │   └── service/                  # 应用服务
│   │   │               ├── domain/                       # 领域层(Domains)
│   │   │               │   ├── model/                   # 领域模型
│   │   │               │   └── repository/              # 仓储接口
│   │   │               └── infrastructure/              # 基础设施层(Infrastructures)
│   │   │                   ├── config/                  # 配置类
│   │   │                   ├── mapper/                  # MyBatis-Flex Mapper接口
│   │   │                   └── repository/              # 仓储实现(Dao)
│   │   └── resources
│   │       └── application.properties  # 配置文件
│   └── test
│       └── java
│       │   └── simonby
│       │       └── top
│       │           └── annualring
│       │               └── AnnualRingApplicationTests.java  # 测试类
└── pom.xml  # Maven 项目配置文件
```

## 功能特性

- **族谱管理**: 记录家族成员信息，维护家族关系图谱
- **地图定位**: 基于GeoTools地理空间处理库，支持地图选点定位家庭位置
- **权限控制**: 集成Sa-Token权限认证框架，保护家族数据安全
- **多家族支持**: 一个用户可以管理多个家族树，一个家族树可以有多个成员
- **数据持久化**: 集成Spring Data JPA和MyBatis-Flex，简化数据库操作
- **工具支持**: 集成Hutool工具库，提供丰富的Java工具类以加速开发

## COLA架构设计

本项目采用COLA（Clean Object-Oriented and Layered Architecture）架构思想进行设计，分为四层：

1. **适配层（Adapter）**：
   - 负责处理用户接口和外部系统的交互
   - 包含控制器和数据传输对象（DTO）
   - 控制器将请求转发给应用服务

2. **应用层（Application）**：
   - 负责协调领域层和基础设施层
   - 处理用例和业务流程
   - 不包含核心业务逻辑

3. **领域层（Domain）**：
   - 包含核心业务逻辑
   - 包含实体、值对象、仓储接口等
   - 是系统的核心部分

4. **基础设施层（Infrastructure）**：
   - 包含技术实现细节
   - 如数据库访问、外部服务调用等
   - 实现领域层定义的仓储接口

## 数据库设计

系统使用JPA和MyBatis-Flex实现数据持久化，包含以下实体表：

1. **用户表（users）**：
   - 存储系统用户信息
   - 包含用户名、密码、邮箱、手机号等字段

2. **家族成员表（family_members）**：
   - 存储家族成员信息
   - 包含姓名、性别、出生/去世日期、地理位置等字段

3. **家族树表（family_trees）**：
   - 存储家族树信息
   - 包含家族名称、描述、创建者等字段

4. **用户家族关联表（user_families）**：
   - 存储用户与家族树的关联关系
   - 包含用户ID、家族树ID、角色等字段

所有数据访问对象（DAO）都遵循以"Dao"结尾的命名规范。

## MyBatis-Flex查询补偿

为了增强数据查询能力，系统集成了MyBatis-Flex框架，提供了以下功能：

1. **强大的QueryWrapper**：
   - 支持链式调用构建复杂查询条件
   - 类型安全，避免SQL注入
   - 支持关联查询、多表查询等高级功能

2. **灵活的Mapper接口**：
   - 继承BaseMapper获得基础CRUD操作
   - 支持自定义SQL查询
   - 提供默认方法实现复杂查询逻辑

3. **表定义支持**：
   - 通过表定义类实现字段安全引用
   - 避免硬编码字段名导致的错误

## 用户体系设计

### 核心实体

1. **用户(User)**: 系统的使用者，可以创建和管理多个家族树
2. **家族树(FamilyTree)**: 代表一个独立的家族谱系
3. **家庭成员(FamilyMember)**: 家族树中的具体成员信息
4. **用户家族关联(UserFamily)**: 管理用户与家族树之间的关系

### 用户角色

- **系统管理员**: 拥有系统的最高权限
- **家族管理员**: 可以管理特定家族树的所有信息
- **家族成员**: 可以查看和编辑自己相关的家族信息
- **访客**: 只能查看公开的家族信息

### 权限控制

基于Sa-Token框架实现细粒度的权限控制：
- 不同角色具有不同的操作权限
- 家族信息的访问控制
- 数据的增删改查权限管理

## 后台管理API

系统提供RESTful API用于后台管理，主要包括以下接口：

### 用户管理API
- `POST /api/users` - 创建用户
- `GET /api/users/{id}` - 根据ID获取用户
- `GET /api/users` - 获取所有用户
- `PUT /api/users/{id}` - 更新用户
- `DELETE /api/users/{id}` - 删除用户

### 家族成员管理API
- `POST /api/members` - 创建家族成员
- `GET /api/members/{id}` - 根据ID获取家族成员
- `GET /api/members/family-tree/{familyTreeId}` - 根据家族树ID获取所有成员
- `GET /api/members` - 获取所有家族成员
- `PUT /api/members/{id}` - 更新家族成员
- `DELETE /api/members/{id}` - 删除家族成员

### 家族树管理API
- `POST /api/family-trees` - 创建家族树
- `GET /api/family-trees/{id}` - 根据ID获取家族树
- `GET /api/family-trees/creator/{creatorId}` - 根据创建者ID获取家族树
- `GET /api/family-trees` - 获取所有家族树
- `PUT /api/family-trees/{id}` - 更新家族树
- `DELETE /api/family-trees/{id}` - 删除家族树

### 用户家族关联管理API
- `POST /api/user-families` - 创建用户家族关联关系
- `GET /api/user-families/{id}` - 根据ID获取用户家族关联关系
- `GET /api/user-families/user/{userId}` - 根据用户ID获取关联的家族树
- `GET /api/user-families/family-tree/{familyTreeId}` - 根据家族树ID获取关联的用户
- `GET /api/user-families` - 获取所有用户家族关联关系
- `PUT /api/user-families/{id}` - 更新用户家族关联关系
- `DELETE /api/user-families/{id}` - 删除用户家族关联关系

## 环境要求

- Java 17 或更高版本
- Maven 3.6+ 
- PostgreSQL 12+ (生产环境)
- H2数据库 (测试环境，已集成)

## 快速开始

### 克隆项目

```bash
git clone <repository-url>
```

### 配置数据库

在 [application.properties](file:///D:/project/annual-ring/src/main/resources/application.properties) 文件中配置PostgreSQL数据库连接：

``properties
spring.datasource.url=jdbc:postgresql://localhost:5432/your_database
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA配置
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
```

对于测试环境，系统使用内存数据库H2，无需额外配置。H2数据库配置位于 [src/test/resources/application.properties](file:///D:/project/annual-ring/src/test/resources/application.properties)：

``properties
# H2 Database configuration for testing
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# JPA configuration for testing
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.H2Dialect
```

### 添加PostgreSQL依赖

在 [pom.xml](file:///D:/project/annual-ring/pom.xml) 文件中添加PostgreSQL驱动依赖：

```xml
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>
```

### 构建项目

```bash
mvn clean package
```

### 运行项目

```bash
mvn spring-boot:run
```

或者

```bash
java -jar target/annual-ring-0.0.1-SNAPSHOT.jar
```

## 依赖管理

项目配置了以下仓库以确保依赖正常下载：

- Maven Central Repository
- OSGeo Release Repository (用于GeoTools)
- OSGeo Snapshot Repository (用于GeoTools快照版本)

## 测试

运行测试用例：

```bash
mvn test
```

## 许可证

该项目未指定许可证。

## 联系方式

项目维护者: Simonby

## 前端低代码平台选型

本项目推荐使用可嵌入式的低代码前端工具，以便于集成到现有系统中。

### 推荐的可嵌入式低代码工具

#### 1. 自定义Vue解决方案 (推荐)
特点：
- 基于Vue 3 + Element Plus的自定义解决方案
- 生成标准HTML/CSS/JavaScript代码
- 支持组件化开发和复用
- 易于与后端Spring Boot API集成
- 支持地图功能集成
- 完全可嵌入现有系统

#### 2. FormMaking (表单设计器)
特点：
- 基于Vue的可嵌入式表单设计器
- 支持生成HTML代码
- 可以灵活嵌入到现有系统中
- 提供丰富的表单组件
- 支持自定义组件

#### 3. 阿里低代码引擎 (LowCodeEngine)
特点：
- 阿里开源的低代码引擎
- 支持物料系统和插件系统
- 可以嵌入到现有系统中
- 提供完整的页面搭建能力

### 地图功能集成建议

考虑到项目需要地图定位功能，推荐以下地图组件：

1. **Leaflet + OpenStreetMap**：
   - 轻量级地图库
   - 可以嵌入到任何Web页面中
   - 支持标记、图层等高级功能

2. **高德地图/百度地图API**：
   - 国内地图服务，数据准确
   - 提供丰富的API接口
   - 支持移动端和PC端

### 快速开始

1. 创建新的前端项目：
   ```
   mkdir frontend
   cd frontend
   npm init -y
   ```

2. 安装依赖：
   ```
   npm install vue@next element-plus axios leaflet
   npm install -D @vitejs/plugin-vue vite
   ```

3. 开发环境运行：
   ```
   npm run dev
   ```

4. 构建生产版本：
   ```
   npm run build
   ```

构建后的文件将自动部署到 src/main/resources/static 目录，Spring Boot会自动提供静态资源服务。

## 前端开发指南

前端项目位于 frontend 目录下，采用Vue 3 + Element Plus技术栈构建。

### 目录结构

```
frontend/
├── public/                 # 静态资源
├── src/
│   ├── assets/             # 静态资源文件
│   ├── components/         # 可复用组件
│   ├── views/              # 页面视图
│   ├── router/             # 路由配置
│   ├── store/              # 状态管理
│   ├── utils/              # 工具函数
│   ├── App.vue             # 根组件
│   └── main.js             # 入口文件
├── index.html              # HTML模板
├── package.json            # 依赖配置
└── vite.config.js          # 构建配置
```

### 开发环境

1. 确保已安装Node.js (版本16+)
2. 在 frontend 目录下运行：
   ```
   npm install
   npm run dev
   ```
3. 访问 http://localhost:3000 查看应用

### 构建部署

运行以下命令构建生产版本：
```
npm run build
```

构建后的文件会自动复制到 src/main/resources/static 目录，打包到最终的JAR文件中。