HaniBlindBox/.kiro/specs/marketing-management-frontend/requirements.md

Requirements Document

Introduction

本文档定义了营销活动管理模块从老项目（PHP ThinkPHP + Layui）迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）的功能需求。营销活动模块包含优惠券管理、广告管理和排行榜管理三大子模块，是运营推广的核心功能。

Glossary

• Admin_System: 后台管理系统，用于管理营销活动配置
• Coupon: 优惠券，用于用户消费抵扣
• Coupon_Receive: 优惠券领取记录，记录用户领取优惠券的历史
• Advert: 广告/轮播图，用于首页和各页面的广告展示
• Advert_Type: 广告类型，用于分类管理广告
• Rank_Prize: 排行榜奖品，周榜/月榜的奖品配置
• Rank_Log: 排行榜中奖记录，记录用户获得排行榜奖品的历史
• User_Rank: 用户排行榜，展示各类用户排名数据

Requirements

Requirement 1: 优惠券列表管理

User Story: As a 运营人员, I want to 查看和管理优惠券列表, so that I can 配置各类优惠券供用户使用。

Acceptance Criteria

1. WHEN 运营人员访问优惠券列表页面 THEN THE Admin_System SHALL 显示优惠券列表，包含ID、名称、满减门槛、优惠金额、有效期、类型、创建时间
2. WHEN 运营人员输入标题关键词搜索 THEN THE Admin_System SHALL 返回标题包含关键词的优惠券列表
3. WHEN 运营人员选择优惠券类型筛选 THEN THE Admin_System SHALL 返回指定类型的优惠券列表
4. WHEN 优惠券列表数据量大 THEN THE Admin_System SHALL 支持分页显示
5. WHEN 运营人员点击删除按钮 THEN THE Admin_System SHALL 显示确认弹窗，确认后删除优惠券

Requirement 2: 优惠券新增

User Story: As a 运营人员, I want to 新增优惠券, so that I can 创建新的优惠活动。

Acceptance Criteria

1. WHEN 运营人员点击添加优惠券按钮 THEN THE Admin_System SHALL 显示新增优惠券表单弹窗
2. WHEN 运营人员填写优惠券表单 THEN THE Admin_System SHALL 提供类型选择（新人优惠券/权益优惠券/满减优惠券）
3. WHEN 运营人员填写优惠券表单 THEN THE Admin_System SHALL 提供使用限制选择（不限制/一番赏/无限赏/擂台赏/全局赏/领主赏/连击赏）
4. WHEN 运营人员提交表单时名称为空 THEN THE Admin_System SHALL 显示验证错误提示
5. WHEN 运营人员提交表单时满减门槛或优惠金额格式错误 THEN THE Admin_System SHALL 显示验证错误提示
6. WHEN 运营人员提交有效表单 THEN THE Admin_System SHALL 创建优惠券并刷新列表

Requirement 3: 优惠券编辑

User Story: As a 运营人员, I want to 编辑优惠券, so that I can 修改优惠券配置。

Acceptance Criteria

1. WHEN 运营人员点击编辑按钮 THEN THE Admin_System SHALL 显示编辑表单弹窗并填充当前数据
2. WHEN 运营人员修改并提交有效表单 THEN THE Admin_System SHALL 更新优惠券并刷新列表
3. IF 编辑时发生网络错误 THEN THE Admin_System SHALL 显示错误提示并保留表单数据

Requirement 4: 优惠券领取记录

User Story: As a 运营人员, I want to 查看优惠券领取记录, so that I can 了解优惠券的使用情况。

Acceptance Criteria

1. WHEN 运营人员访问优惠券领取记录页面 THEN THE Admin_System SHALL 显示领取记录列表，包含ID、用户信息、优惠券名称、满减门槛、优惠金额、状态、过期时间、领取时间
2. WHEN 运营人员输入用户ID搜索 THEN THE Admin_System SHALL 返回该用户的领取记录
3. WHEN 运营人员输入优惠券标题搜索 THEN THE Admin_System SHALL 返回包含该标题的领取记录
4. WHEN 运营人员选择状态筛选 THEN THE Admin_System SHALL 返回指定状态（未使用/已使用/已过期）的记录
5. WHEN 领取记录数据量大 THEN THE Admin_System SHALL 支持分页显示

Requirement 5: 广告列表管理

User Story: As a 运营人员, I want to 查看和管理广告列表, so that I can 配置各页面的广告展示。

Acceptance Criteria

1. WHEN 运营人员访问广告列表页面 THEN THE Admin_System SHALL 显示广告列表，包含类型、图片、排序值
2. WHEN 运营人员选择广告类型筛选 THEN THE Admin_System SHALL 返回指定类型的广告列表
3. WHEN 运营人员点击查看全部类型按钮 THEN THE Admin_System SHALL 显示广告类型管理弹窗
4. WHEN 运营人员点击删除按钮 THEN THE Admin_System SHALL 显示确认弹窗，确认后删除广告
5. WHEN 广告列表数据量大 THEN THE Admin_System SHALL 支持分页显示

Requirement 6: 广告新增

User Story: As a 运营人员, I want to 新增广告, so that I can 添加新的广告展示。

Acceptance Criteria

1. WHEN 运营人员点击添加轮播图按钮 THEN THE Admin_System SHALL 显示新增广告表单弹窗
2. WHEN 运营人员填写广告表单 THEN THE Admin_System SHALL 提供广告类型选择（动态加载）
3. WHEN 运营人员填写广告表单 THEN THE Admin_System SHALL 提供跳转类型选择（不跳转/优惠券/一番赏/无限赏/连击赏/自定义URL）
4. WHEN 运营人员选择跳转类型为优惠券 THEN THE Admin_System SHALL 显示优惠券ID输入框
5. WHEN 运营人员选择跳转类型为盒子 THEN THE Admin_System SHALL 显示盒子ID输入框
6. WHEN 运营人员选择跳转类型为自定义URL THEN THE Admin_System SHALL 显示跳转链接输入框
7. WHEN 运营人员提交表单时图片为空 THEN THE Admin_System SHALL 显示验证错误提示
8. WHEN 运营人员提交有效表单 THEN THE Admin_System SHALL 创建广告并刷新列表

Requirement 7: 广告编辑

User Story: As a 运营人员, I want to 编辑广告, so that I can 修改广告配置。

Acceptance Criteria

1. WHEN 运营人员点击编辑按钮 THEN THE Admin_System SHALL 显示编辑表单弹窗并填充当前数据
2. WHEN 运营人员修改并提交有效表单 THEN THE Admin_System SHALL 更新广告并刷新列表
3. IF 编辑时发生网络错误 THEN THE Admin_System SHALL 显示错误提示并保留表单数据

Requirement 8: 广告类型管理

User Story: As a 运营人员, I want to 管理广告类型, so that I can 分类管理广告。

Acceptance Criteria

1. WHEN 运营人员打开广告类型管理弹窗 THEN THE Admin_System SHALL 显示类型列表，包含ID、类型名称、排序
2. WHEN 运营人员点击添加类型按钮 THEN THE Admin_System SHALL 显示新增类型表单
3. WHEN 运营人员提交类型表单时名称为空 THEN THE Admin_System SHALL 显示验证错误提示
4. WHEN 运营人员提交类型表单时名称已存在 THEN THE Admin_System SHALL 显示重复错误提示
5. WHEN 运营人员点击编辑类型按钮 THEN THE Admin_System SHALL 显示编辑表单并填充当前数据
6. WHEN 运营人员点击删除类型按钮且该类型下有广告 THEN THE Admin_System SHALL 显示错误提示禁止删除
7. WHEN 运营人员点击删除类型按钮且该类型下无广告 THEN THE Admin_System SHALL 删除类型并刷新列表

Requirement 9: 周榜奖品管理

User Story: As a 运营人员, I want to 管理周榜奖品, so that I can 配置周排行榜的奖励。

Acceptance Criteria

1. WHEN 运营人员访问周榜奖品页面 THEN THE Admin_System SHALL 显示奖品列表，包含排名、奖品名称、图片、售价、采购价、奖赏类型
2. WHEN 运营人员点击添加奖品按钮 THEN THE Admin_System SHALL 显示新增奖品表单弹窗
3. WHEN 运营人员提交表单时排名已存在 THEN THE Admin_System SHALL 显示重复错误提示
4. WHEN 运营人员提交表单时必填字段为空 THEN THE Admin_System SHALL 显示验证错误提示
5. WHEN 运营人员点击编辑按钮 THEN THE Admin_System SHALL 显示编辑表单弹窗并填充当前数据
6. WHEN 运营人员点击删除按钮 THEN THE Admin_System SHALL 显示确认弹窗，确认后删除奖品

Requirement 10: 周榜中奖记录

User Story: As a 运营人员, I want to 查看周榜中奖记录, so that I can 了解周榜奖品的发放情况。

Acceptance Criteria

1. WHEN 运营人员访问周榜中奖记录页面 THEN THE Admin_System SHALL 显示中奖记录列表，包含排名、用户信息、奖品信息、消费金额、统计时间
2. WHEN 运营人员输入用户UID搜索 THEN THE Admin_System SHALL 返回该用户的中奖记录
3. WHEN 运营人员输入手机号搜索 THEN THE Admin_System SHALL 返回该手机号用户的中奖记录
4. WHEN 中奖记录数据量大 THEN THE Admin_System SHALL 支持分页显示

Requirement 11: 月榜奖品管理

User Story: As a 运营人员, I want to 管理月榜奖品, so that I can 配置月排行榜的奖励。

Acceptance Criteria

1. WHEN 运营人员访问月榜奖品页面 THEN THE Admin_System SHALL 显示奖品列表，包含排名、奖品名称、图片、售价、采购价、奖赏类型
2. WHEN 运营人员点击添加奖品按钮 THEN THE Admin_System SHALL 显示新增奖品表单弹窗
3. WHEN 运营人员提交表单时排名已存在 THEN THE Admin_System SHALL 显示重复错误提示
4. WHEN 运营人员提交表单时必填字段为空 THEN THE Admin_System SHALL 显示验证错误提示
5. WHEN 运营人员点击编辑按钮 THEN THE Admin_System SHALL 显示编辑表单弹窗并填充当前数据
6. WHEN 运营人员点击删除按钮 THEN THE Admin_System SHALL 显示确认弹窗，确认后删除奖品

Requirement 12: 月榜中奖记录

User Story: As a 运营人员, I want to 查看月榜中奖记录, so that I can 了解月榜奖品的发放情况。

Acceptance Criteria

1. WHEN 运营人员访问月榜中奖记录页面 THEN THE Admin_System SHALL 显示中奖记录列表，包含排名、用户信息、奖品信息、消费金额、统计时间
2. WHEN 运营人员输入用户UID搜索 THEN THE Admin_System SHALL 返回该用户的中奖记录
3. WHEN 运营人员输入手机号搜索 THEN THE Admin_System SHALL 返回该手机号用户的中奖记录
4. WHEN 中奖记录数据量大 THEN THE Admin_System SHALL 支持分页显示

Requirement 13: 用户排行榜

User Story: As a 运营人员, I want to 查看用户排行榜, so that I can 了解用户的各类排名数据。

Acceptance Criteria

1. WHEN 运营人员访问用户排行榜页面 THEN THE Admin_System SHALL 显示排行榜类型切换（邀请新人/亏损补贴/达达券/钻石/UU币）
2. WHEN 运营人员切换排行榜类型 THEN THE Admin_System SHALL 加载对应类型的排行榜数据
3. WHEN 运营人员查看邀请新人排行榜 THEN THE Admin_System SHALL 显示排名、用户信息、邀请人数
4. WHEN 运营人员查看亏损补贴排行榜 THEN THE Admin_System SHALL 显示排名、用户信息、消耗金额、达达券金额、出货金额、亏损率
5. WHEN 运营人员查看货币排行榜 THEN THE Admin_System SHALL 显示排名、用户信息、货币数量
6. WHEN 排行榜数据量大 THEN THE Admin_System SHALL 支持分页显示

Requirement 14: 路由和权限配置

User Story: As a 系统管理员, I want to 配置营销活动模块的路由和权限, so that I can 控制用户访问权限。

Acceptance Criteria

1. THE Admin_System SHALL 配置优惠券管理路由 /business/coupon/list
2. THE Admin_System SHALL 配置优惠券领取记录路由 /business/coupon/receive
3. THE Admin_System SHALL 配置广告管理路由 /business/advert/list
4. THE Admin_System SHALL 配置周榜奖品路由 /business/rank/week
5. THE Admin_System SHALL 配置周榜中奖记录路由 /business/rank/week-log
6. THE Admin_System SHALL 配置月榜奖品路由 /business/rank/month
7. THE Admin_System SHALL 配置月榜中奖记录路由 /business/rank/month-log
8. THE Admin_System SHALL 配置用户排行榜路由 /business/rank/user
9. THE Admin_System SHALL 配置权限标识 coupon:list, coupon:add, coupon:edit, coupon:delete
10. THE Admin_System SHALL 配置权限标识 advert:list, advert:add, advert:edit, advert:delete
11. THE Admin_System SHALL 配置权限标识 rank:list, rank:add, rank:edit, rank:delete

Requirement 15: API接口规范

User Story: As a 开发人员, I want to 定义统一的API接口规范, so that I can 保证前后端数据交互的一致性。

Acceptance Criteria

1. THE Admin_System SHALL 提供优惠券列表查询API GET /api/business/coupon
2. THE Admin_System SHALL 提供优惠券新增API POST /api/business/coupon
3. THE Admin_System SHALL 提供优惠券编辑API PUT /api/business/coupon/{id}
4. THE Admin_System SHALL 提供优惠券删除API DELETE /api/business/coupon/{id}
5. THE Admin_System SHALL 提供优惠券领取记录查询API GET /api/business/coupon/receive
6. THE Admin_System SHALL 提供广告列表查询API GET /api/business/advert
7. THE Admin_System SHALL 提供广告新增API POST /api/business/advert
8. THE Admin_System SHALL 提供广告编辑API PUT /api/business/advert/{id}
9. THE Admin_System SHALL 提供广告删除API DELETE /api/business/advert/{id}
10. THE Admin_System SHALL 提供广告类型列表查询API GET /api/business/advert/types
11. THE Admin_System SHALL 提供广告类型新增API POST /api/business/advert/types
12. THE Admin_System SHALL 提供广告类型编辑API PUT /api/business/advert/types/{id}
13. THE Admin_System SHALL 提供广告类型删除API DELETE /api/business/advert/types/{id}
14. THE Admin_System SHALL 提供周榜奖品列表查询API GET /api/business/rank/week
15. THE Admin_System SHALL 提供周榜奖品新增API POST /api/business/rank/week
16. THE Admin_System SHALL 提供周榜奖品编辑API PUT /api/business/rank/week/{id}
17. THE Admin_System SHALL 提供周榜奖品删除API DELETE /api/business/rank/week/{id}
18. THE Admin_System SHALL 提供周榜中奖记录查询API GET /api/business/rank/week/log
19. THE Admin_System SHALL 提供月榜奖品列表查询API GET /api/business/rank/month
20. THE Admin_System SHALL 提供月榜奖品新增API POST /api/business/rank/month
21. THE Admin_System SHALL 提供月榜奖品编辑API PUT /api/business/rank/month/{id}
22. THE Admin_System SHALL 提供月榜奖品删除API DELETE /api/business/rank/month/{id}
23. THE Admin_System SHALL 提供月榜中奖记录查询API GET /api/business/rank/month/log
24. THE Admin_System SHALL 提供用户排行榜查询API GET /api/business/rank/user
25. WHEN API调用成功 THEN THE Admin_System SHALL 返回统一格式响应 { code: 0, message: "success", data: {...} }
26. WHEN API调用失败 THEN THE Admin_System SHALL 返回统一格式错误响应 { code: number, message: "error message" }