375 lines
15 KiB
Markdown
375 lines
15 KiB
Markdown
# 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<T>(key: ConfigKey): Promise<ApiResponse<T>>;
|
||
|
||
// 更新配置
|
||
export function updateConfig<T>(key: ConfigKey, value: T): Promise<ApiResponse<void>>;
|
||
|
||
// 获取所有配置键
|
||
export function getConfigKeys(): Promise<ApiResponse<string[]>>;
|
||
```
|
||
|
||
### 数据模型定义
|
||
|
||
```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<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}**
|