# annual-ring

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

## Basic Information

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

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

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-04-23
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 年轮 (Annual Ring)

族谱管理系统，寓意文化代代相传，如树木年轮般记录家族历史。本系统采用前后端分离架构，后端基于Spring Boot 3.x开发，前端基于Vue 3开发，支持基于地图的家族位置定位功能。

## 技术栈

### 后端 (annual-ring-api)
- **核心框架**: 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

### 前端 (annual-ring-vue)
- **前端框架**: Vue 3 + Ant Design Vue
- **构建工具**: Vite
- **HTTP客户端**: Axios
- **地图库**: Leaflet
- **状态管理**: Pinia
- **查询管理**: TanStack Vue Query

## 项目结构

```
.
├── annual-ring-api/        # 后端API项目
│   ├── src/                # 后端源代码
│   │   ├── main/java/      # Java主代码
│   │   └── main/resources/ # 配置文件和资源
│   └── pom.xml             # Maven配置
├── annual-ring-vue/        # 前端Vue项目
│   └── frontend/           # 前端源代码
│       ├── src/            # Vue主代码
│       ├── package.json    # npm依赖配置
│       └── vite.config.js  # Vite构建配置
└── README.md               # 项目说明文档
```

## 功能特性

- **族谱管理**: 记录家族成员信息，维护家族关系图谱
- **地图定位**: 基于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>
```

### 后端开发 (annual-ring-api)

#### 配置数据库

系统支持两种配置方式：

1. **使用配置文件（推荐）**
   在 `annual-ring-api/src/main/resources/application.properties` 文件中配置激活的环境：
   ```
   spring.profiles.active=dev  # 使用H2数据库（开发环境）
   # 或者
   spring.profiles.active=prod # 使用PostgreSQL数据库（生产环境）
   ```

2. **开发环境配置（H2数据库）**
   H2数据库配置位于 `annual-ring-api/src/main/resources/application-dev.properties`

3. **生产环境配置（PostgreSQL数据库）**
   PostgreSQL数据库配置位于 `annual-ring-api/src/main/resources/application-prod.properties`

#### 数据库初始化

系统使用SQL脚本进行数据库初始化，确保在应用启动时自动创建默认数据：
- 表结构定义: `annual-ring-api/src/main/resources/db/init/schema.sql`
- 默认数据初始化: `annual-ring-api/src/main/resources/db/init/data.sql`

默认初始化数据包括：
- 管理员用户: admin / admin123
- 示例家族树: 张氏家族
- 示例家族成员: 张大山、李小花、张小明、张小红

#### 数据库迁移

系统使用Liquibase进行数据库版本管理：
```bash
cd annual-ring-api
mvn liquibase:update
```

#### 构建项目

```bash
cd annual-ring-api
mvn clean package
```

#### 运行项目

```bash
cd annual-ring-api
mvn spring-boot:run
```

或者

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

### 前端开发 (annual-ring-vue)

#### 安装依赖

```bash
cd annual-ring-vue/frontend
npm install
```

#### 开发环境运行

```bash
cd annual-ring-vue/frontend
npm run dev
```

访问 http://localhost:3000 查看应用

#### 构建生产版本

```bash
cd annual-ring-vue/frontend
npm run build
```

构建后的文件将生成在 `annual-ring-vue/frontend/dist` 目录下

## 依赖管理

### 后端依赖管理

项目配置了以下仓库以确保依赖正常下载：
- Maven Central Repository
- OSGeo Release Repository (用于GeoTools)
- OSGeo Snapshot Repository (用于GeoTools快照版本)

### 前端依赖管理

前端依赖通过npm管理，配置文件位于 `annual-ring-vue/frontend/package.json`

## 测试

### 后端测试

```bash
cd annual-ring-api
mvn test
```

### 前端测试

```bash
cd annual-ring-vue/frontend
npm test
```

## 许可证

该项目未指定许可证。

## 联系方式

项目维护者: Simonby

## 前端开发指南

前端项目位于 `annual-ring-vue/frontend` 目录下，采用Vue 3 + Ant Design Vue技术栈构建。

### 目录结构

```
annual-ring-vue/frontend/
├── src/
│   ├── api/               # API请求配置
│   ├── auth/              # 认证相关组件
│   ├── dashboard/         # 仪表盘组件
│   ├── family/            # 家族相关组件
│   ├── stores/            # Pinia状态管理
│   ├── user/              # 用户管理组件
│   ├── utils/             # 工具函数
│   ├── views/             # 页面视图
│   ├── App.vue            # 根组件
│   ├── main.js            # 入口文件
│   └── router.js          # 路由配置
├── index.html             # HTML模板
├── package.json           # npm依赖配置
└── vite.config.js         # Vite构建配置
```

### 开发环境

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

### 构建部署

运行以下命令构建生产版本：
```bash
cd annual-ring-vue/frontend
npm run build
```

构建后的文件将生成在 `annual-ring-vue/frontend/dist` 目录下，可以部署到任何静态文件服务器。