From d5ba35cf135958f4ef62c4dad04a2d39318ffb51 Mon Sep 17 00:00:00 2001 From: gpu Date: Tue, 6 Jan 2026 00:06:22 +0800 Subject: [PATCH] 333 --- .../specs/admin-business-migration/design.md | 725 ++++++++++++++++++ .../admin-business-migration/requirements.md | 167 ++++ .kiro/specs/admin-business-migration/tasks.md | 363 +++++++++ docs/对话记录.md | 319 ++++++++ 4 files changed, 1574 insertions(+) create mode 100644 .kiro/specs/admin-business-migration/design.md create mode 100644 .kiro/specs/admin-business-migration/requirements.md create mode 100644 .kiro/specs/admin-business-migration/tasks.md create mode 100644 docs/对话记录.md diff --git a/.kiro/specs/admin-business-migration/design.md b/.kiro/specs/admin-business-migration/design.md new file mode 100644 index 00000000..8d93ae28 --- /dev/null +++ b/.kiro/specs/admin-business-migration/design.md @@ -0,0 +1,725 @@ +# Design Document: Admin Business Migration + +## Overview + +本设计文档描述了 HoneyBox 后台管理系统业务模块迁移的技术架构和实现方案。核心目标是创建一个独立的 `HoneyBox.Admin.Business` 类库，将业务模块（系统配置、用户管理、商品管理、订单管理、财务管理、仪表盘）与基础后台管理框架解耦，实现业务模块的可插拔设计。 + +## Architecture + +### 整体架构图 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ HoneyBox.Admin (Web API) │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Program.cs │ │ +│ │ - AddHoneyBoxAdmin() // 基础服务注册 │ │ +│ │ - AddAdminBusiness() // 业务模块注册 (新增) │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────────────────┼─────────────────────────────────────┐ │ +│ │ Controllers/ │ │ │ +│ │ ├── AuthController.cs │ (基础控制器 - 已有) │ │ +│ │ ├── MenuController.cs │ │ │ +│ │ ├── RoleController.cs │ │ │ +│ │ └── ... │ │ │ +│ └─────────────────────────────────┼─────────────────────────────────────┘ │ +└────────────────────────────────────┼────────────────────────────────────────┘ + │ AddApplicationPart + ▼ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ HoneyBox.Admin.Business (Class Library) │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Controllers/ │ │ +│ │ ├── ConfigController.cs // 系统配置 │ │ +│ │ ├── UserController.cs // 用户管理 │ │ +│ │ ├── GoodsController.cs // 商品管理 │ │ +│ │ ├── OrderController.cs // 订单管理 │ │ +│ │ ├── FinanceController.cs // 财务管理 │ │ +│ │ └── DashboardController.cs // 仪表盘 │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Services/ │ │ +│ │ ├── IConfigService.cs / ConfigService.cs │ │ +│ │ ├── IUserBusinessService.cs / UserBusinessService.cs │ │ +│ │ ├── IGoodsService.cs / GoodsService.cs │ │ +│ │ ├── IOrderService.cs / OrderService.cs │ │ +│ │ ├── IFinanceService.cs / FinanceService.cs │ │ +│ │ └── IDashboardService.cs / DashboardService.cs │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Extensions/ │ │ +│ │ └── ServiceCollectionExtensions.cs // AddAdminBusiness 扩展方法 │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ + │ 引用 + ▼ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ HoneyBox.Model (Class Library) │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Data/HoneyBoxDbContext.cs // 业务数据库上下文 │ │ +│ │ Entities/ // 业务实体 (User, Goods, Order...) │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 项目依赖关系 + +``` +HoneyBox.Admin + ├── HoneyBox.Admin.Business (业务模块) + └── (自包含基础功能) + +HoneyBox.Admin.Business + └── HoneyBox.Model (业务实体和 DbContext) +``` + + +## Components and Interfaces + +### 1. HoneyBox.Admin.Business 项目结构 + +``` +HoneyBox.Admin.Business/ +├── Controllers/ +│ ├── ConfigController.cs +│ ├── UserController.cs +│ ├── GoodsController.cs +│ ├── OrderController.cs +│ ├── FinanceController.cs +│ └── DashboardController.cs +├── Services/ +│ ├── Interfaces/ +│ │ ├── IConfigService.cs +│ │ ├── IUserBusinessService.cs +│ │ ├── IGoodsService.cs +│ │ ├── IOrderService.cs +│ │ ├── IFinanceService.cs +│ │ └── IDashboardService.cs +│ ├── ConfigService.cs +│ ├── UserBusinessService.cs +│ ├── GoodsService.cs +│ ├── OrderService.cs +│ ├── FinanceService.cs +│ └── DashboardService.cs +├── Models/ +│ ├── Config/ +│ │ ├── ConfigDto.cs +│ │ └── ConfigUpdateRequest.cs +│ ├── User/ +│ │ ├── UserListRequest.cs +│ │ ├── UserListResponse.cs +│ │ ├── UserDetailResponse.cs +│ │ └── UserMoneyChangeRequest.cs +│ ├── Goods/ +│ │ ├── GoodsListRequest.cs +│ │ ├── GoodsListResponse.cs +│ │ ├── GoodsCreateRequest.cs +│ │ └── PrizeDto.cs +│ ├── Order/ +│ │ ├── OrderListRequest.cs +│ │ ├── OrderListResponse.cs +│ │ └── ShipOrderRequest.cs +│ └── Finance/ +│ ├── RankingListResponse.cs +│ └── FinanceDetailResponse.cs +├── Extensions/ +│ └── ServiceCollectionExtensions.cs +└── HoneyBox.Admin.Business.csproj +``` + +### 2. 核心接口定义 + +#### IConfigService + +```csharp +public interface IConfigService +{ + Task GetConfigAsync(string key) where T : class; + Task UpdateConfigAsync(string key, T config) where T : class; + Task ValidateConfigAsync(string key, object config); +} +``` + +#### IUserBusinessService + +```csharp +public interface IUserBusinessService +{ + Task> GetUserListAsync(UserListRequest request); + Task GetUserDetailAsync(long userId); + Task ChangeUserMoneyAsync(long userId, UserMoneyChangeRequest request); + Task SetUserStatusAsync(long userId, int status); + Task SetTestAccountAsync(long userId, int isTest); + Task ClearMobileAsync(long userId); + Task ClearWeChatAsync(long userId); + Task GiftCouponAsync(long userId, GiftCouponRequest request); + Task GiftCardAsync(long userId, GiftCardRequest request); + Task> GetVipLevelsAsync(); + Task UpdateVipLevelAsync(int id, VipLevelUpdateRequest request); + Task GetUserProfitLossAsync(long userId, DateRange? dateRange); + Task> GetSubordinateUsersAsync(long userId, int page, int pageSize); +} +``` + +#### IGoodsService + +```csharp +public interface IGoodsService +{ + Task> GetGoodsListAsync(GoodsListRequest request); + Task GetGoodsDetailAsync(long goodsId); + Task CreateGoodsAsync(GoodsCreateRequest request); + Task UpdateGoodsAsync(long goodsId, GoodsUpdateRequest request); + Task DeleteGoodsAsync(long goodsId); + Task SetGoodsStatusAsync(long goodsId, int status); + Task> GetPrizesAsync(long goodsId); + Task AddPrizeAsync(long goodsId, PrizeCreateRequest request); + Task UpdatePrizeAsync(long prizeId, PrizeUpdateRequest request); + Task DeletePrizeAsync(long prizeId); + Task> GetGoodsTypesAsync(); +} +``` + +#### IOrderService + +```csharp +public interface IOrderService +{ + Task> GetOrderListAsync(OrderListRequest request); + Task GetOrderDetailAsync(long orderId); + Task> GetStuckOrdersAsync(OrderListRequest request); + Task> GetRecoveryOrdersAsync(OrderListRequest request); + Task> GetShippingOrdersAsync(ShippingOrderListRequest request); + Task ShipOrderAsync(long orderId, ShipOrderRequest request); + Task CancelShippingOrderAsync(long orderId); + Task ExportOrdersAsync(OrderExportRequest request); +} +``` + +#### IFinanceService + +```csharp +public interface IFinanceService +{ + Task> GetConsumptionRankingAsync(FinanceQueryRequest request); + Task> GetBalanceDetailsAsync(FinanceQueryRequest request); + Task> GetIntegralDetailsAsync(FinanceQueryRequest request); + Task> GetScoreDetailsAsync(FinanceQueryRequest request); + Task> GetRechargeRecordsAsync(FinanceQueryRequest request); +} +``` + +#### IDashboardService + +```csharp +public interface IDashboardService +{ + Task GetOverviewAsync(); + Task> GetAdAccountsAsync(); + Task CreateAdAccountAsync(AdAccountCreateRequest request); +} +``` + + +## Data Models + +### 1. 请求/响应模型 + +#### 通用分页请求 + +```csharp +public class PagedRequest +{ + public int Page { get; set; } = 1; + public int PageSize { get; set; } = 20; +} + +public class PagedResult +{ + public List List { get; set; } = new(); + public int Total { get; set; } + public int Page { get; set; } + public int PageSize { get; set; } +} +``` + +#### 用户管理模型 + +```csharp +public class UserListRequest : PagedRequest +{ + public long? UserId { get; set; } + public string? Mobile { get; set; } + public string? Nickname { get; set; } + public string? LastLoginIp { get; set; } + public DateTime? StartDate { get; set; } + public DateTime? EndDate { get; set; } + public long? ParentId { get; set; } +} + +public class UserListResponse +{ + public long Id { get; set; } + public string? Uid { get; set; } + public string? Nickname { get; set; } + public string? Avatar { get; set; } + public string? Mobile { get; set; } + public decimal Balance { get; set; } + public decimal Integral { get; set; } + public decimal Diamond { get; set; } + public int VipLevel { get; set; } + public DateTime CreatedAt { get; set; } + public string? LastLoginIp { get; set; } + public int Status { get; set; } + public int IsTest { get; set; } + // 统计字段 + public decimal TotalConsumption { get; set; } + public decimal BoxValue { get; set; } + public decimal WeChatPayment { get; set; } + public decimal BalancePayment { get; set; } + public decimal IntegralPayment { get; set; } + public decimal RecoveryAmount { get; set; } + public decimal ShippingValue { get; set; } +} + +public class UserMoneyChangeRequest +{ + public int Type { get; set; } // 1-余额 2-积分 3-钻石 + public decimal Amount { get; set; } + public int Operation { get; set; } // 1-增加 2-扣除 + public string? Remark { get; set; } +} +``` + +#### 商品管理模型 + +```csharp +public class GoodsListRequest : PagedRequest +{ + public string? Title { get; set; } + public int? Status { get; set; } + public int? Type { get; set; } +} + +public class GoodsListResponse +{ + public long Id { get; set; } + public string Title { get; set; } = string.Empty; + public string ImgUrl { get; set; } = string.Empty; + public decimal Price { get; set; } + public int Type { get; set; } + public string TypeName { get; set; } = string.Empty; + public int Status { get; set; } + public int Stock { get; set; } + public int SaleStock { get; set; } + public DateTime CreatedAt { get; set; } + public DateTime? UpdatedAt { get; set; } +} + +public class GoodsCreateRequest +{ + public string Title { get; set; } = string.Empty; + public decimal Price { get; set; } + public int Type { get; set; } + public string ImgUrl { get; set; } = string.Empty; + public string ImgUrlDetail { get; set; } = string.Empty; + public int Stock { get; set; } + public int Sort { get; set; } + public int DailyLimit { get; set; } + public int LockIs { get; set; } + public int LockTime { get; set; } + public int IntegralIs { get; set; } + public int ShowIs { get; set; } + public int CouponIs { get; set; } + public int CouponPro { get; set; } + // 福利屋专用字段 + public DateTime? FlwStartTime { get; set; } + public DateTime? FlwEndTime { get; set; } + public DateTime? OpenTime { get; set; } + public int? ChoujiangXianzhi { get; set; } +} +``` + +#### 订单管理模型 + +```csharp +public class OrderListRequest : PagedRequest +{ + public long? UserId { get; set; } + public string? Mobile { get; set; } + public string? OrderNum { get; set; } + public DateTime? StartDate { get; set; } + public DateTime? EndDate { get; set; } + public int? Status { get; set; } +} + +public class OrderListResponse +{ + public long Id { get; set; } + public string OrderNum { get; set; } = string.Empty; + public long UserId { get; set; } + public string? UserNickname { get; set; } + public string? UserMobile { get; set; } + public string? UserUid { get; set; } + public string GoodsTitle { get; set; } = string.Empty; + public int OrderType { get; set; } + public decimal OrderTotal { get; set; } + public decimal Discount { get; set; } + public decimal DiscountTotal { get; set; } + public decimal WeChatPayment { get; set; } + public decimal BalancePayment { get; set; } + public decimal IntegralPayment { get; set; } + public decimal ScorePayment { get; set; } + public int Status { get; set; } + public DateTime CreatedAt { get; set; } +} + +public class ShipOrderRequest +{ + public string CourierName { get; set; } = string.Empty; + public string CourierNumber { get; set; } = string.Empty; +} +``` + +### 2. 配置模型 + +```csharp +public class WeixinPaySetting +{ + public List Merchants { get; set; } = new(); +} + +public class WeixinPayMerchant +{ + public string Name { get; set; } = string.Empty; + public string MchId { get; set; } = string.Empty; + public string OrderPrefix { get; set; } = string.Empty; // 必须3位 + public string ApiKey { get; set; } = string.Empty; + public string CertPath { get; set; } = string.Empty; +} + +public class MiniprogramSetting +{ + public List Miniprograms { get; set; } = new(); +} + +public class MiniprogramConfig +{ + public string Name { get; set; } = string.Empty; + public string AppId { get; set; } = string.Empty; + public string AppSecret { get; set; } = string.Empty; + public string OrderPrefix { get; set; } = string.Empty; // 必须2位 + public int IsDefault { get; set; } + public int MerchantIndex { get; set; } +} + +public class H5Setting +{ + public List H5Apps { get; set; } = new(); +} + +public class H5AppConfig +{ + public string Name { get; set; } = string.Empty; + public string OrderPrefix { get; set; } = string.Empty; // 必须2位 + public int IsDefault { get; set; } + public int WxMerchantIndex { get; set; } + public int AliMerchantIndex { get; set; } +} +``` + + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Configuration Round-Trip Consistency + +*For any* valid configuration object, saving it via UpdateConfigAsync and then retrieving it via GetConfigAsync should produce an equivalent object. + +**Validates: Requirements 3.1, 3.2** + +### Property 2: Merchant Prefix Uniqueness Validation + +*For any* weixinpay_setting configuration with duplicate merchant prefixes or prefixes not exactly 3 characters, the validation should fail and return an error. + +**Validates: Requirements 3.4** + +### Property 3: Default App Validation + +*For any* miniprogram_setting or h5_setting configuration without at least one default app, the validation should fail and return an error. + +**Validates: Requirements 3.5, 3.6** + +### Property 4: User List Pagination Consistency + +*For any* user list request with valid page and pageSize parameters, the returned list should contain at most pageSize items, and the total should reflect the actual count of matching users. + +**Validates: Requirements 4.1** + +### Property 5: User List Filter Accuracy + +*For any* user list request with filter parameters, all returned users should match all specified filter criteria. + +**Validates: Requirements 4.3** + +### Property 6: User Balance Change Audit Trail + +*For any* user balance/integral/diamond modification, a corresponding profit record should be created with the same amount and user ID. + +**Validates: Requirements 4.4** + +### Property 7: User Status Toggle Consistency + +*For any* user ban or unban operation, the user's status field should be updated to the expected value (disabled for ban, enabled for unban). + +**Validates: Requirements 4.5, 4.6** + +### Property 8: Goods Stock Increase Prize Replication + +*For any* goods stock increase operation, the number of prize configurations for new sets should equal the number of prize configurations in the first set. + +**Validates: Requirements 5.6** + +### Property 9: Prize Code Uniqueness + +*For any* prize added to a box, the generated prize_code should be unique within the entire goods_list table. + +**Validates: Requirements 5.8** + +### Property 10: Order List Filter Accuracy + +*For any* order list request with filter parameters, all returned orders should match all specified filter criteria. + +**Validates: Requirements 6.2** + +### Property 11: Order Prize Grouping + +*For any* order detail request, the returned prize list should be correctly grouped by prize_code with accurate counts. + +**Validates: Requirements 6.4** + +### Property 12: Shipping Order Cancellation Inventory Restoration + +*For any* shipping order cancellation, all prizes in the order should be restored to the user's inventory (status changed from shipped to available). + +**Validates: Requirements 6.6** + +### Property 13: Consumption Ranking Sort Order + +*For any* consumption ranking request, the returned users should be sorted by total consumption in descending order. + +**Validates: Requirements 7.1** + +### Property 14: Financial Query Filter Accuracy + +*For any* financial query (balance, integral, score, recharge) with filter parameters, all returned records should match all specified filter criteria. + +**Validates: Requirements 7.7** + +### Property 15: Dashboard Statistics Accuracy + +*For any* dashboard overview request, the returned statistics (today's registrations, consumption, new consumers) should match the actual counts from the database for the current day. + +**Validates: Requirements 8.1, 8.2, 8.3** + +### Property 16: API Response Format Consistency + +*For any* successful API call, the response should follow the format { code: 0, message: "success", data: {...} }. For any failed API call, the response should follow the format { code: error_code, message: "error description", data: null }. + +**Validates: Requirements 9.1, 9.2** + +### Property 17: Paginated Response Format + +*For any* paginated API request, the response data should contain list, total, page, and pageSize fields with correct values. + +**Validates: Requirements 9.3** + +### Property 18: Authentication Enforcement + +*For any* business API call without a valid JWT token, the system should return a 401 Unauthorized response. + +**Validates: Requirements 10.1** + +### Property 19: Permission Enforcement + +*For any* business API call where the user lacks the required permission, the system should return a 403 Forbidden response. + +**Validates: Requirements 10.2, 10.4** + + +## Error Handling + +### 错误码定义 + +| 错误码 | 说明 | 场景 | +|--------|------|------| +| 0 | 成功 | 所有成功响应 | +| 40001 | 认证失败 | Token 无效或过期 | +| 40101 | 权限不足 | 用户无权访问该资源 | +| 40201 | 参数验证失败 | 请求参数不符合要求 | +| 40401 | 资源不存在 | 请求的数据不存在 | +| 50001 | 服务器内部错误 | 未预期的异常 | + +### 异常处理策略 + +1. **业务异常** - 使用自定义 BusinessException，包含错误码和消息 +2. **验证异常** - 使用 FluentValidation 或 DataAnnotations，返回字段级错误 +3. **系统异常** - 通过全局异常过滤器捕获，记录日志并返回通用错误 + +```csharp +public class BusinessException : Exception +{ + public int Code { get; } + + public BusinessException(int code, string message) : base(message) + { + Code = code; + } +} + +// 全局异常过滤器 +public class BusinessExceptionFilter : IExceptionFilter +{ + public void OnException(ExceptionContext context) + { + if (context.Exception is BusinessException bex) + { + context.Result = new JsonResult(new ApiResponse + { + Code = bex.Code, + Message = bex.Message, + Data = null + }); + context.ExceptionHandled = true; + } + } +} +``` + +## Testing Strategy + +### 测试框架选择 + +- **单元测试**: xUnit + Moq +- **属性测试**: FsCheck (C# 属性测试库) +- **集成测试**: WebApplicationFactory + +### 测试分层 + +1. **单元测试** - 测试 Service 层的业务逻辑 + - 配置验证逻辑 + - 数据转换逻辑 + - 业务规则验证 + +2. **属性测试** - 验证通用属性 + - 分页一致性 + - 过滤准确性 + - 数据完整性 + +3. **集成测试** - 测试 API 端到端 + - 认证流程 + - 权限验证 + - 数据库操作 + +### 属性测试配置 + +```csharp +// 使用 FsCheck 进行属性测试 +// 每个属性测试至少运行 100 次迭代 + +[Property(MaxTest = 100)] +public Property ConfigRoundTrip_ShouldPreserveData() +{ + return Prop.ForAll(config => + { + // Feature: admin-business-migration, Property 1: Configuration Round-Trip Consistency + var saved = _configService.UpdateConfigAsync("test", config).Result; + var retrieved = _configService.GetConfigAsync("test").Result; + return saved && config.Equals(retrieved); + }); +} +``` + +### 测试覆盖要求 + +- 所有 Service 方法必须有单元测试 +- 所有正确性属性必须有对应的属性测试 +- 关键 API 端点必须有集成测试 +- 边界条件和错误场景必须有测试覆盖 + +## API Endpoints + +### 系统配置 API + +``` +GET /api/admin/business/config/{key} # 获取配置 +PUT /api/admin/business/config/{key} # 更新配置 +``` + +### 用户管理 API + +``` +GET /api/admin/business/users # 用户列表 +GET /api/admin/business/users/{id} # 用户详情 +PUT /api/admin/business/users/{id}/status # 封号/解封 +PUT /api/admin/business/users/{id}/money # 资金变动 +PUT /api/admin/business/users/{id}/test # 设置测试账号 +DELETE /api/admin/business/users/{id}/mobile # 清空手机号 +DELETE /api/admin/business/users/{id}/wechat # 清空微信绑定 +POST /api/admin/business/users/{id}/coupon # 赠送优惠券 +POST /api/admin/business/users/{id}/card # 赠送卡牌 +GET /api/admin/business/users/{id}/team # 下级用户 +GET /api/admin/business/users/{id}/profit # 盈亏统计 +GET /api/admin/business/vip # VIP等级列表 +PUT /api/admin/business/vip/{id} # 编辑VIP等级 +``` + +### 商品管理 API + +``` +GET /api/admin/business/goods # 盒子列表 +GET /api/admin/business/goods/{id} # 盒子详情 +POST /api/admin/business/goods # 新增盒子 +PUT /api/admin/business/goods/{id} # 编辑盒子 +DELETE /api/admin/business/goods/{id} # 删除盒子 +PUT /api/admin/business/goods/{id}/status # 上架/下架 +GET /api/admin/business/goods/{id}/prizes # 奖品列表 +POST /api/admin/business/goods/{id}/prizes # 添加奖品 +PUT /api/admin/business/prizes/{id} # 编辑奖品 +DELETE /api/admin/business/prizes/{id} # 删除奖品 +GET /api/admin/business/goods-types # 盒子类型列表 +``` + +### 订单管理 API + +``` +GET /api/admin/business/orders # 订单列表 +GET /api/admin/business/orders/{id} # 订单详情 +GET /api/admin/business/orders/stuck # 卡单列表 +GET /api/admin/business/orders/recovery # 兑换订单 +GET /api/admin/business/orders/shipping # 发货订单 +PUT /api/admin/business/orders/{id}/ship # 发货处理 +DELETE /api/admin/business/orders/{id}/ship # 取消发货 +GET /api/admin/business/orders/export # 导出订单 +``` + +### 财务管理 API + +``` +GET /api/admin/business/finance/ranking # 消费排行 +GET /api/admin/business/finance/balance # 余额明细 +GET /api/admin/business/finance/integral # 积分明细 +GET /api/admin/business/finance/score # 钻石明细 +GET /api/admin/business/finance/recharge # 充值记录 +``` + +### 仪表盘 API + +``` +GET /api/admin/business/dashboard # 仪表盘数据 +GET /api/admin/business/dashboard/ads # 广告账户列表 +POST /api/admin/business/dashboard/ads # 新增广告账户 +``` diff --git a/.kiro/specs/admin-business-migration/requirements.md b/.kiro/specs/admin-business-migration/requirements.md new file mode 100644 index 00000000..04593248 --- /dev/null +++ b/.kiro/specs/admin-business-migration/requirements.md @@ -0,0 +1,167 @@ +# Requirements Document + +## Introduction + +本文档定义了 HoneyBox 后台管理系统业务模块迁移的需求。目标是将 PHP (ThinkPHP 6.0) 后台管理的业务功能迁移至 ASP.NET Core，采用独立的 `HoneyBox.Admin.Business` 类库架构，实现业务模块与基础后台管理框架的解耦。 + +## Glossary + +- **Admin_System**: 后台管理系统，包含认证、菜单、角色、权限等基础功能 +- **Business_Module**: 业务模块，包含用户管理、商品管理、订单管理等业务功能 +- **HoneyBox_Admin**: 后台管理基础项目，包含认证、菜单、角色、权限等核心功能 +- **HoneyBox_Admin_Business**: 后台业务模块类库，包含所有业务相关的控制器和服务 +- **HoneyBoxDbContext**: 业务数据库上下文，访问 honey_box 业务库 +- **AdminDbContext**: 后台管理数据库上下文，访问 honey_box_admin 管理库 +- **Config_Table**: 系统配置表，存储各类配置的 JSON 数据 +- **User_Table**: 用户表，存储用户基本信息 +- **Goods_Table**: 商品表，存储盒子信息 +- **Order_Table**: 订单表，存储订单信息 +- **Box_Type**: 盒子类型，包含一番赏、无限赏、擂台赏、抽卡机等9种类型 + +## Requirements + +### Requirement 1: 项目架构搭建 + +**User Story:** As a developer, I want to create an independent HoneyBox.Admin.Business class library, so that business modules can be easily added or removed without affecting the core admin system. + +#### Acceptance Criteria + +1. THE HoneyBox_Admin_Business project SHALL be created as a separate class library +2. THE HoneyBox_Admin_Business project SHALL reference HoneyBox.Model for business entity access +3. WHEN HoneyBox.Admin starts, THE Admin_System SHALL load controllers from HoneyBox_Admin_Business assembly via AddApplicationPart +4. THE HoneyBox_Admin_Business project SHALL provide a ServiceCollectionExtensions class with AddAdminBusiness extension method +5. WHEN AddAdminBusiness is called, THE Admin_System SHALL register all business services and controllers automatically +6. THE HoneyBox_Admin_Business project SHALL have its own Controllers, Services, and Models directories + +### Requirement 2: 跨库数据访问配置 + +**User Story:** As a developer, I want to configure cross-database access, so that the admin system can query both admin database and business database. + +#### Acceptance Criteria + +1. WHEN the application starts, THE Admin_System SHALL inject both AdminDbContext and HoneyBoxDbContext +2. THE HoneyBoxDbContext SHALL connect to the honey_box business database +3. THE AdminDbContext SHALL connect to the honey_box_admin management database +4. WHEN a business service needs business data, THE Business_Module SHALL use HoneyBoxDbContext for queries +5. THE connection strings for both databases SHALL be configurable in appsettings.json + +### Requirement 3: 系统配置模块迁移 + +**User Story:** As an administrator, I want to manage system configurations, so that I can configure payment settings, upload settings, and other system parameters. + +#### Acceptance Criteria + +1. WHEN an administrator requests configuration by key, THE Config_Service SHALL return the configuration JSON data +2. WHEN an administrator updates configuration, THE Config_Service SHALL validate and save the JSON data to Config_Table +3. THE Config_Service SHALL support the following configuration keys: base, weixinpay_setting, alipay_setting, miniprogram_setting, h5_setting, uploads, systemconfig, sign +4. WHEN weixinpay_setting is updated, THE Config_Service SHALL validate that merchant prefixes are unique and exactly 3 characters +5. WHEN miniprogram_setting is updated, THE Config_Service SHALL validate that at least one default miniprogram is set +6. WHEN h5_setting is updated, THE Config_Service SHALL validate that at least one default H5 app is set +7. WHEN configuration is updated, THE Config_Service SHALL clear related Redis cache +8. IF configuration validation fails, THEN THE Config_Service SHALL return a descriptive error message + +### Requirement 4: 用户管理模块迁移 + +**User Story:** As an administrator, I want to manage users, so that I can view user information, modify user status, and handle user-related operations. + +#### Acceptance Criteria + +1. WHEN an administrator requests user list, THE User_Service SHALL return paginated user data with consumption statistics +2. THE user list SHALL include: user ID, UID, nickname, avatar, mobile, balance, integral, diamond, VIP level, registration time, last login IP +3. THE user list SHALL support filtering by: user_id, mobile, nickname, last_login_ip, registration date range, parent_id +4. WHEN an administrator modifies user balance/integral/diamond, THE User_Service SHALL record the change in profit tables +5. WHEN an administrator bans a user, THE User_Service SHALL set user status to disabled +6. WHEN an administrator unbans a user, THE User_Service SHALL set user status to enabled +7. WHEN an administrator sets test account flag, THE User_Service SHALL update the istest field +8. WHEN an administrator clears mobile binding, THE User_Service SHALL set mobile field to empty +9. WHEN an administrator clears WeChat binding, THE User_Service SHALL generate new random openid +10. WHEN an administrator gifts coupon to user, THE User_Service SHALL create coupon_receive records +11. WHEN an administrator gifts card to user, THE User_Service SHALL create order_list records with order_type=9 +12. THE User_Service SHALL provide VIP level management with CRUD operations +13. THE User_Service SHALL provide user profit/loss statistics calculation +14. THE User_Service SHALL provide subordinate user list query + +### Requirement 5: 商品管理模块迁移 + +**User Story:** As an administrator, I want to manage products (boxes), so that I can create, edit, and configure lottery boxes and their prizes. + +#### Acceptance Criteria + +1. WHEN an administrator requests goods list, THE Goods_Service SHALL return paginated box data +2. THE goods list SHALL support filtering by: title, status, type +3. THE Goods_Service SHALL support 9 box types: 一番赏(1), 无限赏(2), 擂台赏(3), 抽卡机(4), 福袋(5), 幸运赏(6), 盲盒(8), 扭蛋(9), 福利屋(15) +4. WHEN creating a box, THE Goods_Service SHALL validate required fields based on box type +5. WHEN editing a box, THE Goods_Service SHALL prevent stock reduction +6. WHEN increasing box stock, THE Goods_Service SHALL automatically copy prize configurations for new sets +7. THE Goods_Service SHALL provide prize management: add, edit, delete, stock adjustment +8. WHEN a prize is added to a box, THE Goods_Service SHALL generate unique prize_code +9. THE Goods_Service SHALL provide box type management with CRUD operations +10. WHEN box status changes, THE Goods_Service SHALL log the operation in admin_goods_log + +### Requirement 6: 订单管理模块迁移 + +**User Story:** As an administrator, I want to manage orders, so that I can view order details, handle shipping, and process refunds. + +#### Acceptance Criteria + +1. WHEN an administrator requests order list, THE Order_Service SHALL return paginated order data with user information +2. THE order list SHALL support filtering by: user_id, mobile, order_num, date range, status +3. THE Order_Service SHALL provide separate views for: purchase orders, stuck orders, recovery orders, shipping orders +4. WHEN viewing order details, THE Order_Service SHALL return prize list grouped by prize_code +5. WHEN an administrator ships an order, THE Order_Service SHALL update order status and record courier information +6. WHEN an administrator cancels a shipping order, THE Order_Service SHALL restore prizes to user's inventory +7. IF shipping order has freight payment, THEN THE Order_Service SHALL process refund via WeChat +8. THE Order_Service SHALL support batch shipping with Excel import +9. THE Order_Service SHALL support order export to Excel format +10. THE export function SHALL include: order number, user info, box info, amounts, payment details, time + +### Requirement 7: 财务管理模块迁移 + +**User Story:** As an administrator, I want to view financial data, so that I can monitor consumption rankings, balance changes, and recharge records. + +#### Acceptance Criteria + +1. WHEN an administrator requests consumption ranking, THE Finance_Service SHALL return users sorted by total consumption +2. THE consumption ranking SHALL include: user info, total consumption, WeChat payment, balance payment, integral payment +3. WHEN an administrator requests balance details, THE Finance_Service SHALL return profit_money records with user info +4. WHEN an administrator requests integral details, THE Finance_Service SHALL return profit_integral records with user info +5. WHEN an administrator requests score details, THE Finance_Service SHALL return profit_score records with user info +6. WHEN an administrator requests recharge records, THE Finance_Service SHALL return profit_pay records with user info +7. ALL financial queries SHALL support filtering by: user_id, mobile, date range + +### Requirement 8: 首页仪表盘模块迁移 + +**User Story:** As an administrator, I want to view dashboard statistics, so that I can monitor today's registrations, consumption, and advertising data. + +#### Acceptance Criteria + +1. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's registration count +2. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's consumption amount +3. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's new consumer count +4. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return total advertising revenue +5. THE Dashboard_Service SHALL provide advertising account management with CRUD operations + +### Requirement 9: API 响应格式标准化 + +**User Story:** As a frontend developer, I want consistent API response format, so that I can handle responses uniformly. + +#### Acceptance Criteria + +1. THE Business_Module SHALL return success responses in format: { code: 0, message: "success", data: {...} } +2. THE Business_Module SHALL return error responses in format: { code: error_code, message: "error description", data: null } +3. THE Business_Module SHALL return paginated responses in format: { code: 0, message: "success", data: { list: [...], total: N, page: N, pageSize: N } } +4. WHEN validation fails, THE Business_Module SHALL return code 40201 with field-specific error messages +5. WHEN authentication fails, THE Business_Module SHALL return code 40001 +6. WHEN permission denied, THE Business_Module SHALL return code 40101 + +### Requirement 10: 权限控制集成 + +**User Story:** As an administrator, I want business module APIs to be protected by permissions, so that only authorized users can access specific functions. + +#### Acceptance Criteria + +1. WHEN a business API is called, THE Admin_System SHALL verify user authentication via JWT token +2. WHEN a business API requires specific permission, THE Admin_System SHALL check user's role permissions +3. THE Business_Module SHALL use AdminPermission attribute to declare required permissions +4. IF user lacks required permission, THEN THE Admin_System SHALL return 403 Forbidden response +5. THE permission codes SHALL follow pattern: module:action (e.g., user:list, goods:add, order:ship) diff --git a/.kiro/specs/admin-business-migration/tasks.md b/.kiro/specs/admin-business-migration/tasks.md new file mode 100644 index 00000000..a308a3b6 --- /dev/null +++ b/.kiro/specs/admin-business-migration/tasks.md @@ -0,0 +1,363 @@ +# Implementation Plan: Admin Business Migration + +## Overview + +本任务列表将后台业务模块迁移分为6个阶段：项目架构搭建、系统配置模块、用户管理模块、商品管理模块、订单管理模块、财务管理和仪表盘模块。每个阶段包含具体的实现任务和测试任务。 + +## Tasks + +- [ ] 1. 项目架构搭建 + - [ ] 1.1 创建 HoneyBox.Admin.Business 类库项目 + - 在 `server/HoneyBox/src/` 下创建新的类库项目 + - 配置项目引用 HoneyBox.Model + - 添加必要的 NuGet 包（Microsoft.AspNetCore.Mvc.Core, Mapster 等） + - _Requirements: 1.1, 1.2_ + + - [ ] 1.2 创建项目目录结构 + - 创建 Controllers/ 目录 + - 创建 Services/Interfaces/ 目录 + - 创建 Models/ 目录 + - 创建 Extensions/ 目录 + - _Requirements: 1.6_ + + - [ ] 1.3 实现 ServiceCollectionExtensions 扩展方法 + - 创建 AddAdminBusiness 扩展方法 + - 实现 AddApplicationPart 加载业务控制器 + - 实现业务服务的自动注册 + - _Requirements: 1.3, 1.4, 1.5_ + + - [ ] 1.4 配置 HoneyBox.Admin 引用和启动 + - 在 HoneyBox.Admin.csproj 中添加对 HoneyBox.Admin.Business 的引用 + - 在 Program.cs 中调用 AddAdminBusiness() + - 配置 HoneyBoxDbContext 的注入 + - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5_ + + - [ ] 1.5 创建通用响应模型和基类 + - 创建 ApiResponse 通用响应模型 + - 创建 PagedRequest 和 PagedResult 分页模型 + - 创建 BusinessException 业务异常类 + - 创建 BusinessControllerBase 控制器基类 + - _Requirements: 9.1, 9.2, 9.3_ + + - [ ] 1.6 Checkpoint - 验证项目架构 + - 确保项目编译通过 + - 确保控制器能被正确加载 + - 确保服务能被正确注入 + + +- [ ] 2. 系统配置模块迁移 + - [ ] 2.1 创建配置服务接口和实现 + - 创建 IConfigService 接口 + - 实现 ConfigService，包含 GetConfigAsync 和 UpdateConfigAsync 方法 + - 实现配置的 JSON 序列化/反序列化 + - _Requirements: 3.1, 3.2, 3.3_ + + - [ ] 2.2 实现配置验证逻辑 + - 实现微信支付商户前缀验证（唯一性、3位字符） + - 实现小程序配置验证（至少一个默认） + - 实现 H5 配置验证（至少一个默认） + - _Requirements: 3.4, 3.5, 3.6_ + + - [ ] 2.3 实现 Redis 缓存清理 + - 配置更新后清理相关 Redis 缓存 + - 支持按配置 key 清理特定缓存 + - _Requirements: 3.7_ + + - [ ] 2.4 创建 ConfigController + - 实现 GET /api/admin/business/config/{key} 获取配置 + - 实现 PUT /api/admin/business/config/{key} 更新配置 + - 添加权限验证 [AdminPermission("config:view")] 和 [AdminPermission("config:edit")] + - _Requirements: 3.1, 3.2, 3.8, 10.3_ + + - [ ] 2.5 编写配置模块单元测试 + - 测试配置读取功能 + - 测试配置更新功能 + - 测试验证逻辑 + - _Requirements: 3.1, 3.2, 3.4, 3.5, 3.6_ + + - [ ] 2.6 编写配置模块属性测试 + - **Property 1: Configuration Round-Trip Consistency** + - **Validates: Requirements 3.1, 3.2** + + - [ ] 2.7 编写配置验证属性测试 + - **Property 2: Merchant Prefix Uniqueness Validation** + - **Property 3: Default App Validation** + - **Validates: Requirements 3.4, 3.5, 3.6** + + - [ ] 2.8 Checkpoint - 验证配置模块 + - 确保所有测试通过 + - 手动测试 API 端点 + - 验证 Redis 缓存清理功能 + +- [ ] 3. 用户管理模块迁移 + - [ ] 3.1 创建用户服务接口和实现 + - 创建 IUserBusinessService 接口 + - 实现 UserBusinessService 基础方法 + - 实现用户列表查询（含消费统计） + - _Requirements: 4.1, 4.2_ + + - [ ] 3.2 实现用户列表过滤功能 + - 支持按 user_id, mobile, nickname, last_login_ip 过滤 + - 支持按注册日期范围过滤 + - 支持按 parent_id 过滤 + - _Requirements: 4.3_ + + - [ ] 3.3 实现用户资金变动功能 + - 实现余额变动（增加/扣除） + - 实现积分变动（增加/扣除） + - 实现钻石变动（增加/扣除） + - 记录变动到 profit 表 + - _Requirements: 4.4_ + + - [ ] 3.4 实现用户状态管理功能 + - 实现封号/解封功能 + - 实现测试账号设置功能 + - 实现清空手机号功能 + - 实现清空微信绑定功能 + - _Requirements: 4.5, 4.6, 4.7, 4.8, 4.9_ + + - [ ] 3.5 实现用户赠送功能 + - 实现赠送优惠券功能 + - 实现赠送卡牌功能 + - _Requirements: 4.10, 4.11_ + + - [ ] 3.6 实现 VIP 管理功能 + - 实现 VIP 等级列表查询 + - 实现 VIP 等级编辑 + - _Requirements: 4.12_ + + - [ ] 3.7 实现用户统计功能 + - 实现用户盈亏统计计算 + - 实现下级用户列表查询 + - _Requirements: 4.13, 4.14_ + + - [ ] 3.8 创建 UserController + - 实现所有用户管理 API 端点 + - 添加权限验证 + - _Requirements: 4.1-4.14, 10.3_ + + - [ ] 3.9 编写用户模块单元测试 + - 测试用户列表查询 + - 测试资金变动功能 + - 测试状态管理功能 + - _Requirements: 4.1-4.14_ + + - [ ] 3.10 编写用户模块属性测试 + - **Property 4: User List Pagination Consistency** + - **Property 5: User List Filter Accuracy** + - **Property 6: User Balance Change Audit Trail** + - **Property 7: User Status Toggle Consistency** + - **Validates: Requirements 4.1, 4.3, 4.4, 4.5, 4.6** + + - [ ] 3.11 Checkpoint - 验证用户模块 + - 确保所有测试通过 + - 手动测试 API 端点 + + +- [ ] 4. 商品管理模块迁移 + - [ ] 4.1 创建商品服务接口和实现 + - 创建 IGoodsService 接口 + - 实现 GoodsService 基础方法 + - 实现商品列表查询（支持过滤） + - _Requirements: 5.1, 5.2_ + + - [ ] 4.2 实现商品 CRUD 功能 + - 实现商品创建（支持9种盒子类型） + - 实现商品编辑（防止库存减少） + - 实现商品删除 + - 实现商品上架/下架 + - _Requirements: 5.3, 5.4, 5.5_ + + - [ ] 4.3 实现库存增加时奖品复制逻辑 + - 当库存增加时自动复制奖品配置 + - 处理宝箱类型的子奖品复制 + - _Requirements: 5.6_ + + - [ ] 4.4 实现奖品管理功能 + - 实现奖品列表查询 + - 实现奖品添加（生成唯一 prize_code） + - 实现奖品编辑 + - 实现奖品删除 + - _Requirements: 5.7, 5.8_ + + - [ ] 4.5 实现盒子类型管理 + - 实现盒子类型列表查询 + - _Requirements: 5.9_ + + - [ ] 4.6 实现操作日志记录 + - 商品状态变更时记录日志 + - _Requirements: 5.10_ + + - [ ] 4.7 创建 GoodsController + - 实现所有商品管理 API 端点 + - 添加权限验证 + - _Requirements: 5.1-5.10, 10.3_ + + - [ ] 4.8 编写商品模块单元测试 + - 测试商品 CRUD 功能 + - 测试奖品管理功能 + - 测试库存增加逻辑 + - _Requirements: 5.1-5.10_ + + - [ ] 4.9 编写商品模块属性测试 + - **Property 8: Goods Stock Increase Prize Replication** + - **Property 9: Prize Code Uniqueness** + - **Validates: Requirements 5.6, 5.8** + + - [ ] 4.10 Checkpoint - 验证商品模块 + - 确保所有测试通过 + - 手动测试 API 端点 + +- [ ] 5. 订单管理模块迁移 + - [ ] 5.1 创建订单服务接口和实现 + - 创建 IOrderService 接口 + - 实现 OrderService 基础方法 + - 实现订单列表查询（支持过滤） + - _Requirements: 6.1, 6.2_ + + - [ ] 5.2 实现订单分类查询 + - 实现购买订单列表 + - 实现卡单列表 + - 实现兑换订单列表 + - 实现发货订单列表 + - _Requirements: 6.3_ + + - [ ] 5.3 实现订单详情查询 + - 实现订单详情（奖品按 prize_code 分组） + - _Requirements: 6.4_ + + - [ ] 5.4 实现发货功能 + - 实现单个订单发货 + - 更新订单状态和物流信息 + - _Requirements: 6.5_ + + - [ ] 5.5 实现取消发货功能 + - 实现取消发货订单 + - 恢复奖品到用户盒柜 + - _Requirements: 6.6_ + + - [ ] 5.6 实现订单导出功能 + - 实现订单导出为 Excel + - 包含所有必要字段 + - _Requirements: 6.9, 6.10_ + + - [ ] 5.7 创建 OrderController + - 实现所有订单管理 API 端点 + - 添加权限验证 + - _Requirements: 6.1-6.10, 10.3_ + + - [ ] 5.8 编写订单模块单元测试 + - 测试订单列表查询 + - 测试发货功能 + - 测试取消发货功能 + - _Requirements: 6.1-6.10_ + + - [ ] 5.9 编写订单模块属性测试 + - **Property 10: Order List Filter Accuracy** + - **Property 11: Order Prize Grouping** + - **Property 12: Shipping Order Cancellation Inventory Restoration** + - **Validates: Requirements 6.2, 6.4, 6.6** + + - [ ] 5.10 Checkpoint - 验证订单模块 + - 确保所有测试通过 + - 手动测试 API 端点 + + +- [ ] 6. 财务管理和仪表盘模块迁移 + - [ ] 6.1 创建财务服务接口和实现 + - 创建 IFinanceService 接口 + - 实现 FinanceService 基础方法 + - _Requirements: 7.1-7.7_ + + - [ ] 6.2 实现消费排行榜功能 + - 实现按消费金额排序的用户列表 + - 包含用户信息和各类支付金额 + - _Requirements: 7.1, 7.2_ + + - [ ] 6.3 实现财务明细查询 + - 实现余额明细查询 + - 实现积分明细查询 + - 实现钻石明细查询 + - 实现充值记录查询 + - 支持按 user_id, mobile, 日期范围过滤 + - _Requirements: 7.3, 7.4, 7.5, 7.6, 7.7_ + + - [ ] 6.4 创建 FinanceController + - 实现所有财务管理 API 端点 + - 添加权限验证 + - _Requirements: 7.1-7.7, 10.3_ + + - [ ] 6.5 创建仪表盘服务接口和实现 + - 创建 IDashboardService 接口 + - 实现 DashboardService 基础方法 + - _Requirements: 8.1-8.5_ + + - [ ] 6.6 实现仪表盘统计功能 + - 实现今日注册用户数统计 + - 实现今日消费金额统计 + - 实现今日新消费用户数统计 + - 实现广告收入统计 + - _Requirements: 8.1, 8.2, 8.3, 8.4_ + + - [ ] 6.7 实现广告账户管理 + - 实现广告账户列表查询 + - 实现广告账户创建 + - _Requirements: 8.5_ + + - [ ] 6.8 创建 DashboardController + - 实现所有仪表盘 API 端点 + - 添加权限验证 + - _Requirements: 8.1-8.5, 10.3_ + + - [ ] 6.9 编写财务和仪表盘模块单元测试 + - 测试消费排行榜功能 + - 测试财务明细查询 + - 测试仪表盘统计功能 + - _Requirements: 7.1-7.7, 8.1-8.5_ + + - [ ] 6.10 编写财务和仪表盘模块属性测试 + - **Property 13: Consumption Ranking Sort Order** + - **Property 14: Financial Query Filter Accuracy** + - **Property 15: Dashboard Statistics Accuracy** + - **Validates: Requirements 7.1, 7.7, 8.1, 8.2, 8.3** + + - [ ] 6.11 Checkpoint - 验证财务和仪表盘模块 + - 确保所有测试通过 + - 手动测试 API 端点 + +- [ ] 7. 权限和响应格式验证 + - [ ] 7.1 实现权限验证过滤器 + - 创建 AdminPermissionAttribute 特性 + - 实现权限检查逻辑 + - _Requirements: 10.1, 10.2, 10.3, 10.4_ + + - [ ] 7.2 配置业务模块权限 + - 为所有业务控制器添加权限特性 + - 在数据库中初始化权限数据 + - _Requirements: 10.5_ + + - [ ] 7.3 编写权限验证属性测试 + - **Property 18: Authentication Enforcement** + - **Property 19: Permission Enforcement** + - **Validates: Requirements 10.1, 10.2, 10.4** + + - [ ] 7.4 编写响应格式属性测试 + - **Property 16: API Response Format Consistency** + - **Property 17: Paginated Response Format** + - **Validates: Requirements 9.1, 9.2, 9.3** + + - [ ] 7.5 Final Checkpoint - 完整验证 + - 确保所有测试通过 + - 验证所有 API 端点 + - 验证权限控制 + - 验证响应格式 + +## Notes + +- All tasks are required for complete implementation +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate universal correctness properties +- Unit tests validate specific examples and edge cases +- 建议按阶段顺序执行，每个阶段完成后进行验证 +- 系统配置模块最简单，建议作为第一个迁移的业务模块 diff --git a/docs/对话记录.md b/docs/对话记录.md new file mode 100644 index 00000000..2932c5ec --- /dev/null +++ b/docs/对话记录.md @@ -0,0 +1,319 @@ +我们要把第三阶段的功能分为几大块 + +server\php\app\admin + +你先看一下php中的代码。看一下要先迁移哪个模块。 + + +好的，让我先看一下 PHP 后台的代码结构，分析各个模块的依赖关系和复杂度。 + +让我继续查看更多 PHP 控制器，了解订单、财务等模块： + +现在我对 PHP 后台的业务模块有了全面的了解。让我总结一下分析结果，并给出阶段3的模块划分建议： + +--- + +## 阶段3 业务模块迁移分析 + +根据 PHP 后台代码分析，我建议将阶段3分为以下几大块： + +### 模块划分建议 + +| 批次 | 模块名称 | PHP 控制器 | 复杂度 | 依赖关系 | 预计工时 | +|------|----------|-----------|--------|----------|----------| +| **批次1** | 首页仪表盘 | Index.php | 低 | 依赖用户、订单数据 | 1天 | +| **批次2** | 用户管理 | User.php | 高 | 核心模块，被其他模块依赖 | 3天 | +| **批次3** | 商品管理 | Goods.php, GoodsType.php | 高 | 9种盒子类型，奖品配置复杂 | 4天 | +| **批次4** | 订单管理 | Order.php | 高 | 依赖用户、商品，含发货/导出 | 3天 | +| **批次5** | 财务管理 | Finance.php, Withdraw.php | 中 | 依赖用户、订单 | 2天 | +| **批次6** | 系统配置 | Config.php | 中 | 独立模块 | 1天 | + +### 建议迁移顺序 + +**推荐从「首页仪表盘」开始**，原因： +1. 复杂度最低，可快速验证跨库访问是否正常 +2. 只读操作，不涉及数据修改 +3. 能快速看到成果，建立信心 + +**然后按以下顺序：** +1. **首页仪表盘** → 验证基础架构 +2. **用户管理** → 核心模块，其他模块都依赖它 +3. **商品管理** → 业务核心 +4. **订单管理** → 依赖用户和商品 +5. **财务管理** → 依赖用户和订单 +6. **系统配置** → 独立模块，可随时做 + +### 各模块主要功能 + +**首页仪表盘：** +- 今日注册/消费统计 +- 广告数据统计 + +**用户管理（2000+行代码）：** +- 用户列表（含消费统计、盒柜价值） +- 资金变动（余额/积分/钻石） +- 封号/解封、测试账号设置 +- 清空手机号/微信绑定 +- 赠送优惠券/卡牌 +- VIP管理、用户盈亏、下级用户 + +**商品管理（2300+行代码）：** +- 盒子CRUD（9种类型） +- 奖品管理（添加/编辑/删除/库存） +- 盒子类型管理 +- 复杂的库存和套数逻辑 + +**订单管理（1300+行代码）：** +- 卡单列表、购买订单、兑换订单 +- 发货订单（单个/批量发货） +- 订单导出（Excel） +- 订单取消 + +**财务管理：** +- 消费排行榜 +- 余额/积分/钻石明细 +- 充值记录 +- 提现审核 + +**系统配置：** +- 微信支付/支付宝配置 +- 小程序/H5配置 +- 上传配置 +- 系统参数 + +--- + +你想从哪个模块开始？我建议先从**首页仪表盘**开始，快速验证跨库访问，然后再进入**用户管理**这个核心模块。 + + +我的建议是，先迁移系统配置模块。系统配置 都是一些简单的curd。你觉得呢？ + +同意！系统配置确实是个好的起点： + +1. **独立性强** - 不依赖其他业务模块，可以独立完成 +2. **逻辑简单** - 就是配置的读取和保存，标准 CRUD +3. **验证跨库** - 需要访问 `honey_box` 业务库的 `config` 表，正好验证跨库访问 +4. **风险低** - 即使出问题也不影响核心业务 + +从 PHP 代码看，Config 模块主要功能： +- 基础配置 (base) +- 微信支付配置 (weixinpay_setting) +- 支付宝配置 (alipay_setting) +- 小程序配置 (miniprogram_setting) +- H5配置 (h5_setting) +- 上传配置 (uploads) +- 系统配置 (systemconfig) +- 签到配置 (sign) + +本质上就是对 `config` 表按 `key` 字段进行 JSON 数据的读写。 + +那我们开始吧？需要做的事情： + +1. **配置跨库访问** - 让 HoneyBox.Admin 能访问 `honey_box` 业务库 +2. **创建业务控制器目录** - `Controllers/Business/` +3. **创建 ConfigController** - 实现配置的 CRUD API +4. **创建 ConfigService** - 业务逻辑层 + +要我现在开始实现系统配置模块吗？ + +首先我们要搭建一下跨库的数据实体。配置好跨库访问。ConfigService 你打算创建在哪个位置 + + +好问题！根据迁移计划的架构设计，有两个选择： + +### 方案对比 + +| 方案 | 位置 | 优点 | 缺点 | +|------|------|------|------| +| A | `HoneyBox.Admin/Services/Business/` | Admin 项目自包含，可独立复用 | 业务逻辑分散在两个地方 | +| B | `HoneyBox.Core/Services/` | 业务逻辑集中，可被 Api 和 Admin 共用 | Admin 依赖 Core | + +### 我的建议：方案 B + +把 `ConfigService` 放在 `HoneyBox.Core/Services/` 中，原因： + +1. **配置服务是通用的** - 用户端 API 可能也需要读取某些配置（如系统开关、支付配置等） +2. **避免重复代码** - 如果放在 Admin 里，将来 Api 需要时还得再写一遍 +3. **符合分层架构** - Core 层本来就是放业务逻辑的地方 + +### 跨库访问架构 + +``` +HoneyBox.Admin + │ + ├── Controllers/Business/ConfigController.cs (后台管理 API) + │ + └── 引用 HoneyBox.Core + │ + ├── Services/ConfigService.cs (业务逻辑) + │ + └── 引用 HoneyBox.Model + │ + ├── Entities/Config.cs (实体) + └── Data/HoneyBoxDbContext.cs (已有，访问 honey_box 库) +``` + +### 需要做的步骤 + +1. **HoneyBox.Model** - 添加 `Config` 实体（如果还没有） +2. **HoneyBox.Core** - 创建 `IConfigService` 和 `ConfigService` +3. **HoneyBox.Admin** - 引用 Core，注入 `HoneyBoxDbContext`，创建 `ConfigController` + +你觉得这个方案可以吗？确认后我先看一下现有的实体和 DbContext 结构。 + + +你先看一下现在的实体，和DbContext ，然后在看一下我们最初设计的架构方案：docs\后台管理系统迁移计划.md + +好的，让我先查看现有的实体和 DbContext 结构： + +让我查看 Config 实体和迁移计划中的架构设计： + +现在我完全理解了架构设计。根据迁移计划： + +### 架构分析 + +**现有结构：** +- `HoneyBox.Admin` - 独立可复用的后台管理项目，自包含 Entities/Services/DbContext +- `HoneyBox.Model` - 业务数据层，已有 `Config` 实体和 `HoneyBoxDbContext` +- `HoneyBox.Core` - 用户端业务逻辑层 + +**迁移计划设计理念：** +- `HoneyBox.Admin` 通过**可选引用** `HoneyBox.Core/Model` 来访问业务数据 +- 业务模块的 Service 应该放在 `HoneyBox.Admin/Services/Business/` 下（保持 Admin 自包含） + +### 结论：ConfigService 应该放在 `HoneyBox.Admin/Services/Business/` + +原因： +1. **符合迁移计划设计** - Admin 项目自包含，业务服务放在 `Services/Business/` 下 +2. **Config 实体已存在** - `HoneyBox.Model` 已有 `Config` 实体，Admin 只需引用 Model 即可 +3. **保持独立性** - 如果放在 Core 里，会破坏 Admin 的独立可复用性 + +### 需要做的步骤 + +1. **配置 HoneyBox.Admin 引用 HoneyBox.Model** - 添加项目引用 +2. **注入 HoneyBoxDbContext** - 在 Admin 的 Program.cs 中配置 +3. **创建 `Services/Business/` 目录** - 存放业务服务 +4. **创建 `IConfigService` 和 `ConfigService`** - 配置管理服务 +5. **创建 `Controllers/Business/ConfigController`** - 配置管理 API + +你确认这个方案吗？确认后我开始实现。 + + +能创建一个 HoneyBox.Admin.Business 的后台管理核心库吗？我不想在webapi中写太多不是后台管理的业务代码，因为后面其他项目如果要使用的话，我直接把控制器中的 Business文件夹删掉就好了，在webapi中写太多，我不好清理代码。 + + +这个想法很好！创建一个独立的 `HoneyBox.Admin.Business` 类库来存放业务模块的服务，这样： + +1. **HoneyBox.Admin** - 保持纯净，只包含后台管理基础功能（认证、菜单、角色、权限） +2. **HoneyBox.Admin.Business** - 业务模块服务（配置、用户、商品、订单等） +3. **复用时** - 只需删除 `Controllers/Business/` 和移除对 `HoneyBox.Admin.Business` 的引用 + +### 新的架构 + +``` +HoneyBox.sln +├── src/ +│ ├── HoneyBox.Admin/ # 后台管理基础 (可独立复用) +│ │ ├── Controllers/ +│ │ │ ├── AuthController.cs # 认证 +│ │ │ ├── MenuController.cs # 菜单 +│ │ │ ├── RoleController.cs # 角色 +│ │ │ └── Business/ # 业务控制器 (复用时删除) +│ │ │ └── ConfigController.cs +│ │ ├── Services/ # 基础服务 (认证、菜单、角色) +│ │ ├── Entities/ # Admin 专用实体 +│ │ └── Data/AdminDbContext.cs +│ │ +│ ├── HoneyBox.Admin.Business/ # 业务模块服务 (新增) +│ │ ├── Services/ +│ │ │ ├── IConfigService.cs +│ │ │ ├── ConfigService.cs +│ │ │ ├── IUserBusinessService.cs # 后续 +│ │ │ └── ... +│ │ ├── Models/ # 业务 DTO +│ │ └── HoneyBox.Admin.Business.csproj +│ │ +│ ├── HoneyBox.Model/ # 业务实体 (已有 Config 等) +│ └── HoneyBox.Core/ # 用户端业务逻辑 +``` + +### 依赖关系 + +``` +HoneyBox.Admin + ├── HoneyBox.Admin.Business (业务服务) + └── (自包含基础功能) + +HoneyBox.Admin.Business + └── HoneyBox.Model (业务实体) +``` + +确认这个方案吗？我现在开始创建 `HoneyBox.Admin.Business` 项目。 + +业务的控制器也能在HoneyBox.Admin.Business类库中创建吗？在HoneyBox.Admin启动的时候挂在一下.这个好搞不 + +可以的！ASP.NET Core 支持从外部程序集加载控制器，只需要在启动时配置一下。 + +### 实现方式 + +```csharp +// HoneyBox.Admin/Program.cs +builder.Services.AddControllers() + .AddApplicationPart(typeof(HoneyBox.Admin.Business.Controllers.ConfigController).Assembly); +``` + +或者更优雅的方式，在 `HoneyBox.Admin.Business` 中提供扩展方法： + +```csharp +// HoneyBox.Admin.Business/Extensions/ServiceCollectionExtensions.cs +public static class ServiceCollectionExtensions +{ + public static IMvcBuilder AddAdminBusiness(this IMvcBuilder builder) + { + // 注册控制器 + builder.AddApplicationPart(typeof(ConfigController).Assembly); + + // 注册服务 + builder.Services.AddScoped(); + // ... 其他业务服务 + + return builder; + } +} + +// HoneyBox.Admin/Program.cs +builder.Services.AddControllers() + .AddAdminBusiness(); // 一行搞定 +``` + +### 最终架构 + +``` +HoneyBox.Admin.Business/ # 业务模块 (完全独立) +├── Controllers/ +│ ├── ConfigController.cs +│ ├── UserController.cs +│ └── ... +├── Services/ +│ ├── IConfigService.cs +│ ├── ConfigService.cs +│ └── ... +├── Models/ # 业务 DTO +└── Extensions/ + └── ServiceCollectionExtensions.cs # 一键注册 +``` + +**复用 HoneyBox.Admin 时：** +- 移除对 `HoneyBox.Admin.Business` 的引用 +- 删除 `.AddAdminBusiness()` 调用 +- 完事！ + +这样更干净，要开始创建吗？ + +可以，你先创建一下后台业务的迁移过程，架构设计，怎么迁移，迁移步骤，验证逻辑，我们先创建需求文档。 + +server\php\app\admin\controller 这个是控制器 + +server\php\app\admin\view 这个是后台管理的页面。 + +我们要分几个阶段去迁移完成。 \ No newline at end of file