# Backend API Foundation - Personal User Enhancements

This document describes the backend foundation setup for the personal user enhancements feature.

## Overview

This foundation provides the base infrastructure for 10 feature areas:
1. Smart Collections
2. Album Management
3. Personal Statistics
4. Offline Editing
5. Comments on Content
6. Reactions on Content
7. Visual Theme Customization
8. Layout Preferences
9. Timeline Display Options
10. Profile Customization

## Database Schema

### Migration File
- **Location**: `timeline-sql/V1.4.0__personal_user_enhancements.sql`
- **Tables Created**:
  - `album` - 相册表
  - `album_photo` - 相册照片关联表
  - `reaction` - 反应表 (LIKE, LOVE, LAUGH, WOW, SAD)
  - `comment` - 通用评论表 (支持多实体类型)
  - `user_preferences` - 用户偏好设置表
  - `user_profile` - 用户个人资料表
  - `user_custom_field` - 用户自定义字段表
  - `smart_collection` - 智能收藏集表
  - `offline_change_record` - 离线变更记录表
  
### Schema Extensions
- Extended `user_stats_cache` table with new fields:
  - `total_albums` - 总相册数
  - `total_photos` - 总照片数
  - `total_storage_bytes` - 总存储字节数
  - `monthly_uploads_json` - 月度上传统计JSON
  - `yearly_uploads_json` - 年度上传统计JSON
  - `storage_breakdown_json` - 存储分类统计JSON

## Entity Classes

All entity classes are located in `timeline-user-service/src/main/java/com/timeline/user/entity/`:

- `Album.java` - 相册实体
- `AlbumPhoto.java` - 相册照片关联实体
- `Reaction.java` - 反应实体
- `Comment.java` - 评论实体
- `UserPreferences.java` - 用户偏好实体
- `UserProfile.java` - 用户资料实体
- `UserCustomField.java` - 自定义字段实体
- `UserStatsCache.java` - 统计缓存实体

## DTO Classes

All DTO classes are located in `timeline-user-service/src/main/java/com/timeline/user/dto/`:

### Album DTOs
- `AlbumDto.java` - 相册数据传输对象
- `AlbumPhotoDto.java` - 相册照片数据传输对象
- `CreateAlbumRequest.java` - 创建相册请求
- `UpdateAlbumRequest.java` - 更新相册请求

### Comment DTOs
- `CommentDto.java` - 评论数据传输对象
- `CreateCommentRequest.java` - 创建评论请求

### Other DTOs
- `ReactionDto.java` - 反应数据传输对象
- `UserStatisticsDto.java` - 用户统计数据传输对象

## Controller Structure

All controllers are located in `timeline-user-service/src/main/java/com/timeline/user/controller/`:

### AlbumController
- `GET /api/v1/albums` - 获取用户所有相册
- `POST /api/v1/albums` - 创建相册
- `GET /api/v1/albums/:id` - 获取相册详情
- `PUT /api/v1/albums/:id` - 更新相册
- `DELETE /api/v1/albums/:id` - 删除相册
- `POST /api/v1/albums/:id/photos` - 添加照片到相册
- `DELETE /api/v1/albums/:id/photos` - 从相册移除照片
- `PUT /api/v1/albums/:id/photos/order` - 重新排序照片
- `PUT /api/v1/albums/:id/cover` - 设置相册封面

### CommentController
- `GET /api/v1/comments/:entityType/:entityId` - 获取评论列表
- `POST /api/v1/comments` - 创建评论
- `PUT /api/v1/comments/:id` - 更新评论
- `DELETE /api/v1/comments/:id` - 删除评论

### ReactionController
- `GET /api/v1/reactions/:entityType/:entityId` - 获取反应汇总
- `POST /api/v1/reactions` - 添加或更新反应
- `DELETE /api/v1/reactions/:entityType/:entityId` - 移除反应

### StatisticsController
- `GET /api/v1/statistics/overview` - 获取统计概览 (缓存5分钟)
- `GET /api/v1/statistics/uploads` - 获取上传趋势
- `GET /api/v1/statistics/storage` - 获取存储分类
- `POST /api/v1/statistics/refresh` - 强制刷新统计

### PreferencesController
- `GET /api/v1/preferences` - 获取用户偏好设置
- `PUT /api/v1/preferences/theme` - 更新主题偏好
- `PUT /api/v1/preferences/layout` - 更新布局偏好
- `PUT /api/v1/preferences/timeline` - 更新时间线显示偏好

### ProfileController
- `GET /api/v1/profile` - 获取用户个人资料
- `PUT /api/v1/profile` - 更新用户个人资料
- `POST /api/v1/profile/cover` - 上传封面照片
- `PUT /api/v1/profile/custom-fields` - 更新自定义字段

## Redis Configuration

### RedisConfig.java
- **Location**: `timeline-user-service/src/main/java/com/timeline/user/config/RedisConfig.java`
- **Purpose**: 统计数据缓存配置
- **TTL**: 5分钟
- **Features**:
  - RedisTemplate配置
  - RedisCacheManager配置
  - JSON序列化支持

## Property-Based Testing

### Dependencies
- **jqwik 1.7.4** - Java property-based testing library
- Added to parent `pom.xml` in `dependencyManagement`
- Added to `timeline-user-service/pom.xml` in `dependencies`

### Test Data Generators
- **Location**: `timeline-user-service/src/test/java/com/timeline/user/testutil/TestDataGenerators.java`
- **Purpose**: 生成随机测试数据用于属性测试
- **Generators**:
  - `albums()` - 生成随机相册实体
  - `comments()` - 生成随机评论实体
  - `reactions()` - 生成随机反应实体
  - `userPreferences()` - 生成随机用户偏好实体
  - `userProfiles()` - 生成随机用户资料实体
  - `createAlbumRequests()` - 生成随机创建相册请求
  - `createCommentRequests()` - 生成随机创建评论请求

### Example Property Test
- **Location**: `timeline-user-service/src/test/java/com/timeline/user/entity/AlbumPropertyTest.java`
- **Tests**:
  - Property 4: Album creation with required fields
  - Property 9: Cover photo assignment
  - Album name length constraints
  - Album photo count limits

## Next Steps

### Implementation Tasks
1. **Implement Service Layer**
   - Create service interfaces and implementations
   - Add business logic for each feature
   - Implement validation rules

2. **Implement DAO Layer**
   - Create MyBatis mapper interfaces
   - Create XML mapper files
   - Implement database queries

3. **Complete Controller Logic**
   - Replace TODO comments with actual implementations
   - Add error handling
   - Add authentication/authorization checks

4. **Add Property-Based Tests**
   - Implement all 52 correctness properties from design document
   - Test each property with 100+ iterations
   - Add integration tests

5. **Configure Redis**
   - Add Redis connection properties to application.properties
   - Test caching functionality
   - Implement cache invalidation logic

6. **Add WebSocket Support**
   - Configure STOMP topics for real-time updates
   - Implement notification delivery for comments and reactions

## Dependencies Added

### Parent POM (timeline-server/pom.xml)
```xml
<dependency>
    <groupId>net.jqwik</groupId>
    <artifactId>jqwik</artifactId>
    <version>1.7.4</version>
    <scope>test</scope>
</dependency>
```

### User Service POM (timeline-user-service/pom.xml)
```xml
<!-- Redis for caching -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- jqwik for property-based testing -->
<dependency>
    <groupId>net.jqwik</groupId>
    <artifactId>jqwik</artifactId>
    <scope>test</scope>
</dependency>
```

## Running the Migration

To apply the database migration:

```bash
# Using Flyway or your migration tool
# The migration file will be automatically detected and applied
# Location: timeline-sql/V1.4.0__personal_user_enhancements.sql
```

## Running Property Tests

```bash
cd timeline-server/timeline-user-service
mvn test
```

## Notes

- All controller methods are currently stubs with TODO comments
- Service layer implementation is required before controllers can function
- DAO/Mapper layer needs to be created
- Redis configuration requires connection properties in application.properties
- Property-based tests demonstrate the testing approach but need full implementation