HaniBlindBox/.kiro/specs/float-ball-migration/requirements.md

Requirements Document

Introduction

悬浮球功能迁移 - 将悬浮球配置管理功能从 PHP (ThinkPHP) 后端迁移到 .NET 10 后端。包括数据库表迁移、数据迁移和 API 接口迁移。悬浮球是首页显示的可点击浮动图标，支持展示图片弹窗或跳转页面两种交互方式。

Glossary

• Float_Ball_System: 悬浮球系统，负责管理和展示首页悬浮球配置
• Float_Ball_Config: 悬浮球配置实体，存储单个悬浮球的所有配置信息
• Float_Ball_Service: 悬浮球业务服务，处理悬浮球相关的业务逻辑
• Migration_Script: 数据迁移脚本，负责将 MySQL 数据迁移到 SQL Server

Requirements

Requirement 1: 数据库表迁移

User Story: As a developer, I want to create the float_ball_configs table in SQL Server, so that the system can store float ball configuration data.

Acceptance Criteria

1. THE Float_Ball_System SHALL create a float_ball_configs table in SQL Server with all required columns
2. THE Float_Ball_System SHALL support the following columns: id, status, type, image, link_url, position_x, position_y, width, height, effect, title, image_details, image_bj, image_details_x, image_details_y, image_details_w, image_details_h, created_at, updated_at
3. THE Float_Ball_System SHALL use appropriate SQL Server data types matching the original MySQL schema
4. THE Float_Ball_System SHALL set id as primary key with auto-increment

Requirement 2: 数据迁移

User Story: As a developer, I want to migrate existing float ball data from MySQL to SQL Server, so that the new system has all historical configurations.

Acceptance Criteria

1. THE Migration_Script SHALL read all records from MySQL float_ball_config table
2. THE Migration_Script SHALL transform Unix timestamps to SQL Server DATETIME2 format
3. THE Migration_Script SHALL insert all records into SQL Server float_ball_configs table preserving original IDs
4. THE Migration_Script SHALL verify record count consistency after migration
5. THE Migration_Script SHALL support incremental migration (skip already migrated records)
6. IF migration fails for a record, THEN THE Migration_Script SHALL log the error and continue with remaining records

Requirement 3: 获取悬浮球配置接口

User Story: As a frontend developer, I want to call the getFloatBall API, so that I can display float balls on the homepage.

Acceptance Criteria

1. WHEN a GET request is made to /api/getFloatBall, THE Float_Ball_System SHALL return all enabled float ball configurations
2. THE Float_Ball_System SHALL only return configurations where status equals 1 (enabled)
3. THE Float_Ball_System SHALL return the following fields for each configuration: id, type, image, link_url, position_x, position_y, width, height, effect, title, image_details, image_bj, image_details_x, image_details_y, image_details_w, image_details_h
4. THE Float_Ball_System SHALL NOT return status, created_at, updated_at fields in the response
5. THE Float_Ball_System SHALL return an empty array if no enabled configurations exist
6. THE Float_Ball_System SHALL NOT require authentication for this endpoint

Requirement 4: Entity Framework 实体配置

User Story: As a developer, I want to create the FloatBallConfig entity class, so that Entity Framework can map the database table correctly.

Acceptance Criteria

1. THE Float_Ball_System SHALL create a FloatBallConfig entity class in HoneyBox.Model
2. THE Float_Ball_System SHALL configure proper column mappings using Fluent API or Data Annotations
3. THE Float_Ball_System SHALL register the entity in HoneyBoxDbContext
4. THE Float_Ball_System SHALL support nullable fields for optional columns (title, image_details, image_bj, etc.)

Requirement 5: 响应格式兼容性

User Story: As a frontend developer, I want the API response format to be compatible with the existing frontend, so that no frontend changes are required.

Acceptance Criteria

1. THE Float_Ball_System SHALL return response in format: { "status": 1, "msg": "获取悬浮球配置成功", "data": [...] }
2. THE Float_Ball_System SHALL return status 1 for successful requests
3. THE Float_Ball_System SHALL return status 0 for failed requests with error message
4. WHEN returning image URLs, THE Float_Ball_System SHALL preserve the original URL format (already contains full CDN path)