admin/timeline-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
timeline-server/BACKEND_FOUNDATION_README.md
jhao 10ef5918fc
Some checks failed
test/timeline-server/pipeline/head There was a failure building this commit
Details
feat(user-service): 实现用户服务核心功能与数据同步 
- 新增用户资料、偏好设置、自定义字段管理功能
- 实现评论、反应、相册与智能集合的完整业务逻辑
- 添加离线变更记录与数据同步机制支持冲突解决
- 集成 Redis 缓存配置与用户统计数据聚合
- 创建 8 个业务控制器处理用户交互请求
- 新增 Feign 客户端与故事服务集成
- 补充详细的后端实现与 WebSocket 指南文档
- 更新项目依赖配置支持新增功能模块
2026-02-25 15:04:30 +08:00

7.6 KiB
Raw Permalink Blame History

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)

<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)

<!-- 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:

# 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

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
Reference in New Issue View Git Blame Copy Permalink