Design Document
Overview
本设计文档描述"内容与辅助"模块从老项目（PHP ThinkPHP + Layui）迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）的技术设计方案。该模块包含三个子模块：单页管理（Danye）、悬浮球配置（FloatBall）、福利屋入口（WelfareHouse）。
Architecture
系统架构
┌─────────────────────────────────────────────────────────────────┐
│ 前端 (Vue 3 + Element Plus) │
├─────────────────────────────────────────────────────────────────┤
│ views/business/ │
│ ├── danye/ # 单页管理页面 │
│ │ ├── list.vue # 单页列表 │
│ │ └── components/ # 组件 │
│ ├── floatball/ # 悬浮球配置页面 │
│ │ ├── list.vue # 悬浮球列表 │
│ │ └── components/ # 组件 │
│ └── welfarehouse/ # 福利屋入口页面 │
│ ├── list.vue # 福利屋列表 │
│ └── components/ # 组件 │
├─────────────────────────────────────────────────────────────────┤
│ api/business/ │
│ ├── danye.ts # 单页API │
│ ├── floatball.ts # 悬浮球API │
│ └── welfarehouse.ts # 福利屋API │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 后端 (ASP.NET Core) │
├─────────────────────────────────────────────────────────────────┤
│ HoneyBox.Admin.Business/ │
│ ├── Controllers/ │
│ │ ├── DanyeController.cs │
│ │ ├── FloatBallController.cs │
│ │ └── WelfareHouseController.cs │
│ ├── Services/ │
│ │ ├── DanyeService.cs │
│ │ ├── FloatBallService.cs │
│ │ └── WelfareHouseService.cs │
│ └── Models/ │
│ ├── Danye/ │
│ ├── FloatBall/ │
│ └── WelfareHouse/ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 数据库 (SQL Server) │
├─────────────────────────────────────────────────────────────────┤
│ ├── danye # 单页内容表 (已存在) │
│ ├── float_ball_config # 悬浮球配置表 (已存在) │
│ └── welfare_house # 福利屋配置表 (已存在) │
└─────────────────────────────────────────────────────────────────┘
数据库实体（已存在）
Danye 实体
public class Danye
{
public int Id { get; set; }
public string Title { get; set; }
public string Content { get; set; }
public int UpdateTime { get; set; }
public byte Status { get; set; }
public byte IsImageOptimizer { get; set; }
}
FloatBallConfig 实体
public class FloatBallConfig
{
public int Id { get; set; }
public byte Status { get; set; }
public byte Type { get; set; } // 1展示图片 2跳转页面
public string Image { get; set; }
public string LinkUrl { get; set; }
public string PositionX { get; set; }
public string PositionY { get; set; }
public string Width { get; set; }
public string Height { get; set; }
public byte Effect { get; set; } // 0无 1缩放动画
public string? Title { get; set; }
public string? ImageDetails { get; set; }
public string? ImageBj { get; set; }
public string? ImageDetailsX { get; set; }
public string? ImageDetailsY { get; set; }
public string? ImageDetailsW { get; set; }
public string? ImageDetailsH { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime UpdatedAt { get; set; }
}
WelfareHouse 实体
public class WelfareHouse
{
public int Id { get; set; }
public string Name { get; set; }
public string Image { get; set; }
public string Url { get; set; }
public int Sort { get; set; }
public byte Status { get; set; }
public int? CreateTime { get; set; }
public int? UpdateTime { get; set; }
}
Components
后端组件
1. DanyeController
GET /api/business/danye - 获取单页列表GET /api/business/danye/{id} - 获取单页详情PUT /api/business/danye/{id} - 更新单页内容PUT /api/business/danye/{id}/image-optimizer - 切换图片优化状态
2. FloatBallController
GET /api/business/floatball - 获取悬浮球列表（分页）GET /api/business/floatball/{id} - 获取悬浮球详情POST /api/business/floatball - 新增悬浮球PUT /api/business/floatball/{id} - 更新悬浮球DELETE /api/business/floatball/{id} - 删除悬浮球PUT /api/business/floatball/{id}/status - 切换状态
3. WelfareHouseController
GET /api/business/welfarehouse - 获取福利屋列表（分页）GET /api/business/welfarehouse/{id} - 获取福利屋详情POST /api/business/welfarehouse - 新增福利屋入口PUT /api/business/welfarehouse/{id} - 更新福利屋入口DELETE /api/business/welfarehouse/{id} - 删除福利屋入口PUT /api/business/welfarehouse/{id}/status - 切换状态
前端组件
1. 单页管理模块
DanyeList.vue - 单页列表页面DanyeTable.vue - 单页表格组件DanyeFormDialog.vue - 单页编辑弹窗（含富文本编辑器）
2. 悬浮球配置模块
FloatBallList.vue - 悬浮球列表页面FloatBallTable.vue - 悬浮球表格组件FloatBallFormDialog.vue - 悬浮球表单弹窗
3. 福利屋入口模块
WelfareHouseList.vue - 福利屋列表页面WelfareHouseTable.vue - 福利屋表格组件WelfareHouseFormDialog.vue - 福利屋表单弹窗
Data Models
后端 Models
Danye Models
// 列表响应
public class DanyeResponse
{
public int Id { get; set; }
public string Title { get; set; }
public bool IsImageOptimizer { get; set; }
public DateTime UpdateTime { get; set; }
}
// 详情响应
public class DanyeDetailResponse
{
public int Id { get; set; }
public string Title { get; set; }
public string Content { get; set; }
public bool IsImageOptimizer { get; set; }
}
// 更新请求
public class DanyeUpdateRequest
{
public string? Title { get; set; }
public string Content { get; set; }
}
FloatBall Models
// 列表请求
public class FloatBallListRequest
{
public int Page { get; set; } = 1;
public int PageSize { get; set; } = 10;
}
// 响应
public class FloatBallResponse
{
public int Id { get; set; }
public string? Title { get; set; }
public int Type { get; set; }
public string Image { get; set; }
public string? ImageBj { get; set; }
public string? ImageDetails { get; set; }
public string LinkUrl { get; set; }
public string PositionX { get; set; }
public string PositionY { get; set; }
public string Width { get; set; }
public string Height { get; set; }
public string? ImageDetailsX { get; set; }
public string? ImageDetailsY { get; set; }
public string? ImageDetailsW { get; set; }
public string? ImageDetailsH { get; set; }
public int Effect { get; set; }
public int Status { get; set; }
public DateTime CreatedAt { get; set; }
}
// 创建/更新请求
public class FloatBallCreateRequest
{
public string? Title { get; set; }
public int Type { get; set; }
public string Image { get; set; }
public string? ImageBj { get; set; }
public string? ImageDetails { get; set; }
public string? LinkUrl { get; set; }
public string PositionX { get; set; }
public string PositionY { get; set; }
public string Width { get; set; }
public string Height { get; set; }
public string? ImageDetailsX { get; set; }
public string? ImageDetailsY { get; set; }
public string? ImageDetailsW { get; set; }
public string? ImageDetailsH { get; set; }
public int Effect { get; set; }
public int Status { get; set; } = 1;
}
WelfareHouse Models
// 列表请求
public class WelfareHouseListRequest
{
public int Page { get; set; } = 1;
public int PageSize { get; set; } = 10;
}
// 响应
public class WelfareHouseResponse
{
public int Id { get; set; }
public string Name { get; set; }
public string Image { get; set; }
public string Url { get; set; }
public int Sort { get; set; }
public int Status { get; set; }
public DateTime? CreateTime { get; set; }
}
// 创建/更新请求
public class WelfareHouseCreateRequest
{
public string Name { get; set; }
public string Image { get; set; }
public string Url { get; set; }
public int Sort { get; set; }
public int Status { get; set; } = 1;
}
前端 TypeScript 接口
// Danye
interface DanyeResponse {
id: number
title: string
isImageOptimizer: boolean
updateTime: string
}
interface DanyeDetailResponse {
id: number
title: string
content: string
isImageOptimizer: boolean
}
interface DanyeUpdateRequest {
title?: string
content: string
}
// FloatBall
interface FloatBallListRequest {
page: number
pageSize: number
}
interface FloatBallResponse {
id: number
title?: string
type: number
image: string
imageBj?: string
imageDetails?: string
linkUrl: string
positionX: string
positionY: string
width: string
height: string
imageDetailsX?: string
imageDetailsY?: string
imageDetailsW?: string
imageDetailsH?: string
effect: number
status: number
createdAt: string
}
interface FloatBallCreateRequest {
title?: string
type: number
image: string
imageBj?: string
imageDetails?: string
linkUrl?: string
positionX: string
positionY: string
width: string
height: string
imageDetailsX?: string
imageDetailsY?: string
imageDetailsW?: string
imageDetailsH?: string
effect: number
status?: number
}
// WelfareHouse
interface WelfareHouseListRequest {
page: number
pageSize: number
}
interface WelfareHouseResponse {
id: number
name: string
image: string
url: string
sort: number
status: number
createTime?: string
}
interface WelfareHouseCreateRequest {
name: string
image: string
url: string
sort: number
status?: number
}
API Design
单页管理 API
| 方法 |
路径 |
描述 |
请求体 |
响应 |
| GET |
/api/business/danye |
获取单页列表 |
- |
ApiResponse<List<DanyeResponse>> |
| GET |
/api/business/danye/{id} |
获取单页详情 |
- |
ApiResponse<DanyeDetailResponse> |
| PUT |
/api/business/danye/{id} |
更新单页内容 |
DanyeUpdateRequest |
ApiResponse<bool> |
| PUT |
/api/business/danye/{id}/image-optimizer |
切换图片优化 |
{ isImageOptimizer: bool } |
ApiResponse<bool> |
悬浮球配置 API
| 方法 |
路径 |
描述 |
请求体 |
响应 |
| GET |
/api/business/floatball |
获取悬浮球列表 |
Query: page, pageSize |
PagedResponse<FloatBallResponse> |
| GET |
/api/business/floatball/{id} |
获取悬浮球详情 |
- |
ApiResponse<FloatBallResponse> |
| POST |
/api/business/floatball |
新增悬浮球 |
FloatBallCreateRequest |
ApiResponse<int> |
| PUT |
/api/business/floatball/{id} |
更新悬浮球 |
FloatBallCreateRequest |
ApiResponse<bool> |
| DELETE |
/api/business/floatball/{id} |
删除悬浮球 |
- |
ApiResponse<bool> |
| PUT |
/api/business/floatball/{id}/status |
切换状态 |
{ status: int } |
ApiResponse<bool> |
福利屋入口 API
| 方法 |
路径 |
描述 |
请求体 |
响应 |
| GET |
/api/business/welfarehouse |
获取福利屋列表 |
Query: page, pageSize |
PagedResponse<WelfareHouseResponse> |
| GET |
/api/business/welfarehouse/{id} |
获取福利屋详情 |
- |
ApiResponse<WelfareHouseResponse> |
| POST |
/api/business/welfarehouse |
新增福利屋入口 |
WelfareHouseCreateRequest |
ApiResponse<int> |
| PUT |
/api/business/welfarehouse/{id} |
更新福利屋入口 |
WelfareHouseCreateRequest |
ApiResponse<bool> |
| DELETE |
/api/business/welfarehouse/{id} |
删除福利屋入口 |
- |
ApiResponse<bool> |
| PUT |
/api/business/welfarehouse/{id}/status |
切换状态 |
{ status: int } |
ApiResponse<bool> |
UI Design
单页管理页面
┌─────────────────────────────────────────────────────────────────┐
│ 单页管理 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ID │ 标题 │ 图片优化 │ 更新时间 │ 操作 │ │
│ ├────┼────────────────────────┼─────────┼───────────┼───────┤ │
│ │ 1 │ 关于我们 │ [开关] │ 2026-01-18│ [编辑]│ │
│ │ 2 │ 用户协议 │ [开关] │ 2026-01-18│ [编辑]│ │
│ │ 3 │ 隐私政策 │ [开关] │ 2026-01-18│ [编辑]│ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
单页编辑弹窗
┌─────────────────────────────────────────────────────────────────┐
│ 编辑单页 [X] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 标题: [关于我们________________] (ID 2-20 不可编辑) │
│ │
│ 内容: │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ [B] [I] [U] [图片] [链接] ... ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ││
│ │ 富文本编辑区域 ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ [取消] [保存] │
└─────────────────────────────────────────────────────────────────┘
悬浮球列表页面
┌─────────────────────────────────────────────────────────────────┐
│ 悬浮球配置 [+ 新增] │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ID │ 标题 │ 图片 │ 背景图 │ 详情图 │ 类型 │ 链接 │ 位置 │ ... │ │
│ ├────┼─────┼─────┼───────┼───────┼─────┼─────┼─────┼─────┤ │
│ │ 1 │ 活动 │ [img]│ [img] │ [img] │ 跳转 │ /act│ 10,20│ ... │ │
│ │ 2 │ 客服 │ [img]│ - │ - │ 展示 │ - │ 10,80│ ... │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 共 2 条 < 1 > │
└─────────────────────────────────────────────────────────────────┘
悬浮球表单弹窗
┌─────────────────────────────────────────────────────────────────┐
│ 新增悬浮球 [X] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 标题: [____________________] │
│ │
│ 类型: (●) 展示图片 ( ) 跳转页面 │
│ │
│ 悬浮球图片: [上传] [预览] │
│ 背景图片: [上传] [预览] │
│ 详情图片: [上传] [预览] │
│ │
│ 跳转链接: [____________________] (类型为跳转时显示) │
│ │
│ 位置设置: │
│ X: [____] Y: [____] │
│ │
│ 尺寸设置: │
│ 宽: [____] 高: [____] │
│ │
│ 详情图位置: │
│ X: [____] Y: [____] 宽: [____] 高: [____] │
│ │
│ 特效: [无特效 ▼] │
│ 状态: [开关] │
│ │
│ [取消] [保存] │
└─────────────────────────────────────────────────────────────────┘
福利屋入口列表页面
┌─────────────────────────────────────────────────────────────────┐
│ 福利屋入口 [+ 新增] │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ID │ 名称 │ 图片 │ 链接 │ 排序 │ 状态 │ 创建时间 │ 操作│
│ ├────┼─────────┼──────┼──────────┼─────┼─────┼─────────┼─────┤ │
│ │ 1 │ 签到有礼 │ [img] │ /sign │ 1 │ [开关]│ 01-18 │ [编辑][删除]│
│ │ 2 │ 新人福利 │ [img] │ /newbie │ 2 │ [开关]│ 01-18 │ [编辑][删除]│
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 共 2 条 < 1 > │
└─────────────────────────────────────────────────────────────────┘
福利屋入口表单弹窗
┌─────────────────────────────────────────────────────────────────┐
│ 新增福利屋入口 [X] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 名称: [____________________] * │
│ │
│ 图片: [上传] [预览] * │
│ │
│ 跳转链接: [____________________] * │
│ │
│ 排序: [____] * │
│ │
│ 状态: [开关] │
│ │
│ [取消] [保存] │
└─────────────────────────────────────────────────────────────────┘
Security Considerations
- 权限控制: 所有 API 需要验证管理员登录状态和权限
- 输入验证: 后端对所有输入进行验证，防止 XSS 和 SQL 注入
- 富文本安全: 富文本内容需要进行 HTML 净化处理
- 图片上传: 验证图片类型和大小，防止恶意文件上传
Performance Considerations
- 分页加载: 悬浮球和福利屋列表使用分页加载
- 图片懒加载: 表格中的图片使用懒加载
- 富文本编辑器: 按需加载富文本编辑器组件
Testing Strategy
- 单元测试: 后端 Service 层单元测试
- API 测试: 使用 Swagger 测试 API 接口
- 前端组件测试: Vue 组件单元测试
- 属性测试: 验证搜索、分页、表单验证等通用属性
Dependencies
后端依赖
- Entity Framework Core (已有)
- Mapster (已有)
前端依赖
- Element Plus (已有)
- WangEditor 或 TinyMCE (富文本编辑器，需确认项目中使用的编辑器)
- Vue Router (已有)
References
- Requirements:
.kiro/specs/content-auxiliary-frontend/requirements.md
- PHP 参考代码:
server/php/app/admin/controller/Danye.php
- PHP 参考代码:
server/php/app/admin/controller/FloatBall.php
- PHP 参考代码:
server/php/app/admin/controller/WelfareHouse.php
- 实体定义:
server/HoneyBox/src/HoneyBox.Model/Entities/Danye.cs
- 实体定义:
server/HoneyBox/src/HoneyBox.Model/Entities/FloatBallConfig.cs
- 实体定义:
server/HoneyBox/src/HoneyBox.Model/Entities/WelfareHouse.cs
