74 lines
4.3 KiB
Markdown
74 lines
4.3 KiB
Markdown
# 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)
|