kknongchang_2506/AiWork/202506/141838-URS推广模块创建规划.md

URS推广模块创建规划

任务时间: 2025年06月14日 18:38
任务类型: 模块开发规划
优先级: 高
状态: 📋 规划中

任务概述

Promotionurs模块已被移除，需要创建一个全新的URS推广模块来替代原有功能。新模块将基于现有Promotion模块的架构设计，但使用全新的命名体系和数据结构。

模块命名规划

1. 模块名称

• 模块目录: app/Module/UrsPromotion/
• 命名空间: App\Module\UrsPromotion
• 表名前缀: urs_promotion_
• 路由前缀: urs-promotion

2. 核心类命名

• 服务提供者: UrsPromotionServiceProvider
• 模型类: UrsUserReferral, UrsUserTalent, UrsProfit等
• 控制器: UrsUserReferralController, UrsUserTalentController等
• 仓库类: UrsUserReferralRepository, UrsUserTalentRepository等
• 逻辑类: UrsReferralLogic, UrsTalentLogic, UrsProfitLogic等
• 服务类: UrsReferralService, UrsTalentService, UrsProfitService等

数据库设计

1. 核心数据表

基于Promotion模块的表结构，创建URS专用的数据表：

1. urs_promotion_user_referrals - URS用户推荐关系表
2. urs_promotion_user_talents - URS达人等级表
   
3. urs_promotion_profits - URS团队收益记录表
4. urs_promotion_referral_codes - URS推荐码表
5. urs_promotion_talent_configs - URS达人等级配置表
6. urs_promotion_profit_rules - URS收益分成规则表
7. urs_promotion_referral_changes - URS推荐关系修改记录表
8. urs_promotion_user_relation_cache - URS用户关系缓存表
9. urs_promotion_invite_rewards - URS邀请奖励记录表
10. urs_promotion_referral_code_usages - URS邀请码使用记录表

2. 表结构特点

• 所有表名使用urs_promotion_前缀
• 保持与Promotion模块相同的字段结构和索引设计
• 独立的数据空间，与原Promotion模块完全隔离

目录结构规划

app/Module/UrsPromotion/
├── AdminControllers/        # 后台管理控制器
│   ├── Helper/             # 辅助类
│   ├── UrsUserReferralController.php
│   ├── UrsUserTalentController.php
│   ├── UrsProfitController.php
│   └── ...
├── Commands/               # 命令行工具
├── Databases/              # 数据库相关文件
│   ├── createsql/         # 数据库创建SQL
│   └── GenerateSql/       # 生成的SQL文件
├── Docs/                   # 详细文档目录
│   ├── README.md          # 文档索引
│   ├── 设计概述.md         # 模块整体设计
│   ├── 数据库设计.md       # 数据库表结构设计
│   ├── 模块接口.md         # 模块对外接口
│   └── URS推广系统.md      # URS推广系统设计
├── Enums/                  # 枚举类型定义
├── Events/                 # 事件类
├── Listeners/              # 事件监听器
├── Logics/                 # 业务逻辑类
├── Models/                 # 数据模型
├── Providers/              # 服务提供者
├── Repositorys/            # 数据仓库
└── Services/               # 开放服务类

后台菜单规划

1. 菜单层级结构

• 一级菜单: URS推广管理（新建顶级菜单）
• 二级菜单: URS配置、URS管理（功能分组）
• 三级菜单: 具体功能页面

2. 具体菜单配置

URS配置（二级菜单）

• 🌟 URS达人等级配置
• 💰 URS收益规则配置

URS管理（二级菜单）

• 🌟 URS达人等级管理
• 👥 URS用户推荐关系
• 🔄 URS推荐关系变更记录
• 🔗 URS推荐码管理
• 📊 URS推荐码使用记录
• 💰 URS团队收益记录
• 🎁 URS邀请奖励记录
• 🔄 URS用户关系缓存

3. 菜单图标和URI

• 使用fa-users-cog作为主菜单图标
• URI统一使用urs-前缀
• 保持与现有菜单风格一致

枚举设计

1. 核心枚举类

• URS_PROFIT_SOURCE_TYPE - URS收益来源类型
• URS_REFERRAL_LEVEL - URS推荐层级
• URS_PROFIT_RECORD_STATUS - URS收益记录状态
• URS_REFERRAL_CODE_STATUS - URS推荐码状态
• URS_TALENT_LEVEL - URS达人等级
• URS_TASK_STATUS - URS任务状态
• URS_TASK_TYPE - URS任务类型

2. 枚举值设计

• 保持与Promotion模块相同的枚举值结构
• 使用URS前缀区分命名空间
• 支持中文描述和英文值

事件系统设计

1. 核心事件

• UrsReferralCreatedEvent - URS推荐关系创建事件
• UrsReferralUpdatedEvent - URS推荐关系更新事件
• UrsTalentLevelChangedEvent - URS达人等级变更事件
• UrsProfitCreatedEvent - URS团队收益创建事件

2. 事件监听器

• DistributeUrsProfitListener - 分配URS团队收益监听器
• UpdateUrsCountsListener - 更新URS统计数据监听器
• UpdateUrsTalentLevelListener - 更新URS达人等级监听器

服务层设计

1. 对外服务接口

• UrsReferralService - URS推荐关系服务
• UrsTalentService - URS达人等级服务
• UrsProfitService - URS团队收益服务
• UrsReferralCodeService - URS推荐码服务

2. 内部逻辑层

• UrsReferralLogic - URS推荐关系逻辑
• UrsTalentLogic - URS达人等级逻辑
• UrsProfitLogic - URS团队收益逻辑
• UrsRelationCacheLogic - URS关系缓存逻辑

开发计划

阶段一：基础架构搭建

1. 创建模块目录结构
2. 创建服务提供者和基础配置
3. 设计和创建数据库表结构
4. 创建基础模型类

阶段二：核心功能实现

1. 实现推荐关系管理功能
2. 实现达人等级系统
3. 实现团队收益分成机制
4. 实现推荐码生成和管理

阶段三：后台管理功能

1. 创建后台控制器和仓库类
2. 配置后台菜单和路由
3. 实现数据展示和管理界面
4. 添加数据筛选和统计功能

阶段四：集成和测试

1. 与其他模块的事件集成
2. 缓存策略实现和优化
3. 功能测试和性能优化
4. 文档完善和代码审查

技术要求

1. 代码规范

• 遵循PSR-4命名标准
• 使用PHP enum语法定义枚举
• 模型继承自\UCore\ModelCore
• 控制器继承自UCore\DcatAdmin\AdminController

2. 数据库规范

• 所有表使用kku_前缀
• 表名使用urs_promotion_前缀
• 遵循现有的索引和约束设计
• 支持软删除和时间戳

3. 文档规范

• 提供完整的中文文档
• 包含设计概述、数据库设计、接口文档
• 代码注释使用中文
• 遵循项目文档格式标准

风险评估

1. 技术风险

• 数据迁移复杂性：需要考虑是否迁移原有数据
• 模块间依赖：需要确保与其他模块的兼容性
• 性能影响：大量数据时的查询性能优化

2. 业务风险

• 功能完整性：确保新模块覆盖原有功能
• 数据一致性：避免数据丢失或不一致
• 用户体验：保持后台管理的易用性

与现有模块的差异化

1. 命名空间隔离

• UrsPromotion模块与Promotion模块完全独立
• 使用不同的表名前缀和命名空间
• 避免类名和路由冲突

2. 功能定制化

• 针对URS业务场景的特殊需求
• 可能包含不同的分成比例和规则
• 支持URS特有的业务逻辑

3. 数据独立性

• 独立的数据库表和数据空间
• 不与现有Promotion模块数据混合
• 支持独立的配置和管理

开发优先级

高优先级

1. 数据库表结构设计和创建
2. 基础模型和枚举类创建
3. 核心业务逻辑实现
4. 后台管理基础功能

中优先级

1. 事件系统和监听器
2. 缓存策略实现
3. 数据统计和报表功能
4. 高级管理功能

低优先级

1. 性能优化和调优
2. 扩展功能开发
3. 文档完善
4. 测试用例编写

质量保证

1. 代码质量

• 遵循项目编码规范
• 进行代码审查
• 使用静态分析工具
• 编写单元测试

2. 功能质量

• 完整的功能测试
• 边界条件测试
• 性能压力测试
• 用户体验测试

3. 文档质量

• 完整的技术文档
• 清晰的使用说明
• 详细的API文档
• 维护更新记录

后续工作

1. 确认模块设计方案
2. 开始基础架构搭建
3. 逐步实现核心功能
4. 进行集成测试
5. 部署和上线

---

备注: 本规划文档将作为URS推广模块开发的指导文档，在开发过程中可能会根据实际情况进行调整和完善。