feat(user-service): 实现用户服务核心功能与数据同步

- 新增用户资料、偏好设置、自定义字段管理功能 - 实现评论、反应、相册与智能集合的完整业务逻辑 - 添加离线变更记录与数据同步机制支持冲突解决 - 集成 Redis 缓存配置与用户统计数据聚合 - 创建 8 个业务控制器处理用户交互请求 - 新增 Feign 客户端与故事服务集成 - 补充详细的后端实现与 WebSocket 指南文档 - 更新项目依赖配置支持新增功能模块
2026-02-25 15:04:30 +08:00
parent 40412f6f67
commit 10ef5918fc
94 changed files with 9244 additions and 0 deletions
--- a/BACKEND_FOUNDATION_README.md
+++ b/BACKEND_FOUNDATION_README.md
@@ -0,0 +1,239 @@
+# 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