HaniBlindBox/.kiro/specs/system-config-frontend/design.md

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接口定义

// 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<T>(key: ConfigKey): Promise<ApiResponse<T>>;

// 更新配置
export function updateConfig<T>(key: ConfigKey, value: T): Promise<ApiResponse<void>>;

// 获取所有配置键
export function getConfigKeys(): Promise<ApiResponse<string[]>>;

数据模型定义

// 基础设置
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<T> 结构。

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}