# Design Document: 系统配置模块前端迁移 ## Overview 本设计文档描述系统配置模块从老项目（PHP ThinkPHP + Layui）迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）的技术设计方案。系统配置模块包含8个子模块：基础设置、微信支付配置、支付宝支付配置、小程序配置、H5配置、上传配置、签到配置和系统设置。 ## Architecture ### 整体架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 前端 (Vue 3 + Element Plus) │ ├─────────────────────────────────────────────────────────────┤ │ views/business/config/ │ │ ├── base.vue (基础设置页面) │ │ ├── weixinpay.vue (微信支付配置页面) │ │ ├── alipay.vue (支付宝支付配置页面) │ │ ├── miniprogram.vue (小程序配置页面) │ │ ├── h5.vue (H5配置页面) │ │ ├── uploads.vue (上传配置页面) │ │ ├── sign.vue (签到配置页面) │ │ └── system.vue (系统设置页面) │ ├─────────────────────────────────────────────────────────────┤ │ api/business/config.ts (API调用层) │ ├─────────────────────────────────────────────────────────────┤ │ 后端 (ASP.NET Core) │ │ ConfigController.cs + AdminConfigService.cs │ │ - GET /api/admin/business/config/{key} │ │ - PUT /api/admin/business/config/{key} │ │ - GET /api/admin/business/config/keys │ └─────────────────────────────────────────────────────────────┘ ``` ### 配置键映射 | 配置键 | 说明 | 对应页面 | |--------|------|----------| | base | 基础设置 | base.vue | | weixinpay_setting | 微信支付配置 | weixinpay.vue | | alipay_setting | 支付宝支付配置 | alipay.vue | | miniprogram_setting | 小程序配置 | miniprogram.vue | | h5_setting | H5配置 | h5.vue | | uploads | 上传配置 | uploads.vue | | sign | 签到配置 | sign.vue | | systemconfig | 系统配置 | system.vue | | app_setting | 应用设置 | system.vue | | user_config | 用户UID设置 | system.vue | | infinite_multiple | 无限赏抽奖倍数 | system.vue | | rank_setting | 排行榜设置 | system.vue | | system_test | 内测配置 | system.vue | ## Components and Interfaces ### 前端API接口定义 ```typescript // api/business/config.ts // 配置键类型 export type ConfigKey = | 'base' | 'weixinpay_setting' | 'alipay_setting' | 'miniprogram_setting' | 'h5_setting' | 'uploads' | 'sign' | 'systemconfig' | 'app_setting' | 'user_config' | 'infinite_multiple' | 'rank_setting' | 'system_test'; // 获取配置 export function getConfig(key: ConfigKey): Promise>; // 更新配置 export function updateConfig(key: ConfigKey, value: T): Promise>; // 获取所有配置键 export function getConfigKeys(): Promise>; ``` ### 数据模型定义 ```typescript // 基础设置 export interface BaseSetting { title: string; // 网站名称 logistics_code: string; // 物流code lianji_max_num: number; // 连击赏最大抽取次数 fx_bili: number; // 分销奖励比例 coupon_ling_max_ci: number; // 赏券每人每天最多领取次数 coupon_a_xz_max: number; // 特级赏券限制参与人数 coupon_b_xz_max: number; // 终极赏券限制参与人数 coupon_c_xz_max: number; // 高级赏券限制参与人数 coupon_d_xz_max: number; // 普通赏券限制参与人数 free_post: number; // 背包满多少包邮 post_money: number; // 背包发货运费 three_time: number; // 一番赏三发+时间(秒) five_time: number; // 一番赏五发+时间(秒) erweima: string; // 福利进群二维码 share_title: string; // 分享标题 share_image: string; // 分享图片 draw_people_num: number; // 抽奖券拉人上限 is_shou_tan: number; // 首页是否弹窗 0关闭 1开启 is_exchange: number; // 兑换开关 0关闭 1开启 } // 微信支付商户 export interface WeixinPayMerchant { name: string; // 商户名称 mch_id: string; // 商户号 keys: string; // 商户密钥 order_prefix: string; // 订单前缀(3位) weight: number; // 权重 is_enabled: number; // 是否启用 0禁用 1启用 remark: string; // 备注 } // 微信支付配置 export interface WeixinPaySetting { merchants: WeixinPayMerchant[]; } // 支付宝商户 export interface AlipayMerchant { name: string; // 商户名称 appId: string; // 应用ID privateKey: string; // 应用私钥 publicKey: string; // 支付宝公钥 weight: number; // 权重 is_enabled: number; // 是否启用 remark: string; // 备注 } // 支付宝配置 export interface AlipaySetting { merchants: AlipayMerchant[]; } // 小程序配置项 export interface MiniprogramConfig { name: string; // 小程序名称 appid: string; // AppId appsecret: string; // AppSecret domain: string; // 域名(逗号分隔) order_prefix: string; // 订单前缀(2位) is_default: number; // 是否默认 0否 1是 merchants: number[]; // 关联商户索引 } // 小程序配置 export interface MiniprogramSetting { miniprograms: MiniprogramConfig[]; } // H5应用配置项 export interface H5AppConfig { name: string; // 应用名称 appid: string; // AppId appsecret: string; // AppSecret domain: string; // 域名(逗号分隔) order_prefix: string; // 订单前缀(2位) is_default: number; // 是否默认 0否 1是 pay_type: string; // 支付方式 alipay/wechat wx_merchant_index: number; // 微信商户索引 ali_merchant_index: number; // 支付宝商户索引 } // H5配置 export interface H5Setting { h5apps: H5AppConfig[]; } // 上传配置 export interface UploadSetting { type: string; // 存储类型 local/aliyun/tencent bucket: string; // 空间名称 region: string; // 地域 accessKeyId: string; // AccessKeyId accessKeySecret: string; // AccessKeySecret domain: string; // 请求域名 } // 签到配置 export interface SignSetting { one_num: number; // 第一天奖励 two_num: number; // 第二天奖励 three_num: number; // 第三天奖励 four_num: number; // 第四天奖励 five_num: number; // 第五天奖励 six_num: number; // 第六天奖励 seven_num: number; // 第七天奖励 } // 应用设置 export interface AppSetting { project_name: string; // 项目名称 buy_popup: number; // 购买弹窗 1弹出一次 2每天显示 mall_buy_limit: number; // 商城购买次数 balance_name: string; // 余额名称 balance_icon: string; // 余额图标 currency1_name: string; // 货币1名称 currency1_icon: string; // 货币1图标 currency2_name: string; // 货币2名称 currency2_icon: string; // 货币2图标 win_audio: string; // 中奖音频 version: string; // 小程序版本号 sign_threshold: number; // 签到消费门槛 exchange_show_threshold: number; // 显示兑换达达券按钮门槛 takeout_box_id: number; // 外卖盒子ID daily_free_draw_id: number; // 每日免费抽奖ID box_exchange_limit: number; // 盒柜兑换次数限制 daily_coupon_limit: number; // 每天优惠券次数 } // 用户UID配置 export interface UserConfig { uid_type: string; // UID类型 real_id/number/random uid_length: number; // UID长度 } // 内测配置 export interface SystemTest { is_test: number; // 是否开启内测 0关闭 1开启 disable_wechat_pay: number; // 是否禁用微信支付 0启用 1禁用 sign_multiple: number; // 签到倍数 } // 无限赏抽奖倍数 export interface InfiniteMultiple { multiple: number; // 抽奖倍数 1000/10000/100000 } // 排行榜设置 export interface RankSetting { dada_type: string; // 达达券排行榜统计方式 day/week/month/year/custom dada_start: string; // 达达券自定义开始时间 dada_end: string; // 达达券自定义结束时间 diamond_type: string; // 钻石排行榜统计方式 diamond_start: string; // 钻石自定义开始时间 diamond_end: string; // 钻石自定义结束时间 uu_type: string; // UU币排行榜统计方式 uu_start: string; // UU币自定义开始时间 uu_end: string; // UU币自定义结束时间 } ``` ### 页面组件结构 ``` views/business/config/ ├── base.vue # 基础设置页面 ├── weixinpay.vue # 微信支付配置页面 │ └── components/ │ └── MerchantForm.vue # 商户表单组件(可复用) ├── alipay.vue # 支付宝支付配置页面 ├── miniprogram.vue # 小程序配置页面 │ └── components/ │ └── MiniprogramForm.vue # 小程序表单组件 ├── h5.vue # H5配置页面 │ └── components/ │ └── H5AppForm.vue # H5应用表单组件 ├── uploads.vue # 上传配置页面 ├── sign.vue # 签到配置页面 └── system.vue # 系统设置页面(多卡片) └── components/ ├── AppSettingCard.vue # 应用设置卡片 ├── UserConfigCard.vue # 用户UID设置卡片 ├── SystemTestCard.vue # 内测配置卡片 ├── InfiniteMultipleCard.vue # 无限赏抽奖倍数卡片 └── RankSettingCard.vue # 排行榜设置卡片 ``` ## Data Models ### 后端已有的配置模型 后端 `ConfigModels.cs` 已定义以下模型： - `WeixinPaySetting` / `WeixinPayMerchant` - `MiniprogramSetting` / `MiniprogramConfig` - `H5Setting` / `H5AppConfig` ### 需要补充的后端模型 后端需要补充以下配置模型的验证逻辑： - `AlipaySetting` / `AlipayMerchant` - 支付宝配置验证 - `BaseSetting` - 基础设置验证 - `SignSetting` - 签到配置验证 - `AppSetting` - 应用设置验证 - `UserConfig` - 用户UID配置验证 - `SystemTest` - 内测配置验证 - `InfiniteMultiple` - 无限赏抽奖倍数验证 - `RankSetting` - 排行榜设置验证 ## 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: 配置保存后获取一致性 *For any* 有效的配置数据，保存配置后再获取，应该返回与保存时相同的数据。 **Validates: Requirements 1.2, 1.3, 1.4, 7.2** ### Property 2: 微信支付商户前缀唯一性验证 *For any* 微信支付商户列表，所有商户的订单前缀必须是3位字符且互不相同。 **Validates: Requirements 2.4** ### Property 3: 小程序默认唯一性验证 *For any* 小程序配置列表，必须有且只有一个默认小程序。 **Validates: Requirements 4.4, 4.9** ### Property 4: H5应用默认唯一性验证 *For any* H5应用配置列表，必须有且只有一个默认H5应用。 **Validates: Requirements 5.4, 5.11** ### Property 5: 商户列表最少保留一个 *For any* 商户列表（微信支付/支付宝），删除操作后至少保留一个商户。 **Validates: Requirements 2.7, 3.7** ### Property 6: API响应格式一致性 *For any* 配置API调用，响应格式应该符合 `ApiResponse` 结构。 **Validates: Requirements 10.1, 10.2, 10.3** ## Error Handling ### 前端错误处理 1. **网络错误**: 显示网络错误提示，允许重试 2. **验证错误**: 在表单字段下方显示具体错误信息 3. **保存失败**: 显示错误消息，保留用户输入 4. **加载失败**: 显示加载失败提示，允许重新加载 ### 后端错误处理 1. **配置键无效**: 返回 400 Bad Request，错误信息 "不支持的配置键" 2. **配置值格式错误**: 返回 400 Bad Request，具体验证错误信息 3. **保存失败**: 返回 500 Internal Server Error ## Testing Strategy ### 单元测试 1. **API调用测试**: 测试 `config.ts` 中的API调用函数 2. **表单验证测试**: 测试各配置页面的表单验证逻辑 3. **数据转换测试**: 测试前后端数据格式转换 ### 属性测试 使用 fast-check 进行属性测试： 1. **配置保存一致性测试**: 生成随机配置数据，验证保存后获取一致 2. **前缀唯一性测试**: 生成随机商户列表，验证前缀唯一性检查 3. **默认唯一性测试**: 生成随机小程序/H5列表，验证默认唯一性检查 ### 测试配置 - 属性测试最少运行 100 次迭代 - 每个属性测试需要标注对应的设计文档属性编号 - 标签格式: **Feature: system-config-frontend, Property {number}: {property_text}**