218 lines
5.9 KiB
Markdown
218 lines
5.9 KiB
Markdown
# 系统设置页面重新设计文档
|
||
|
||
## 概述
|
||
|
||
本次重新设计后台管理页面的系统设置页面，特别是添加了支付功能配置，使管理员可以通过后台界面完整配置和管理支付功能，无需手动修改环境变量。
|
||
|
||
## 新增功能
|
||
|
||
### 1. 支付配置区块
|
||
|
||
#### 支付功能开关
|
||
- 在配置区块头部添加了支付功能开关
|
||
- 管理员可以一键启用/禁用支付功能
|
||
|
||
#### 支付宝配置参数
|
||
- **支付宝应用ID (APP_ID)** - 从支付宝开放平台获取
|
||
- **应用私钥** - RSA2格式的应用私钥
|
||
- **支付宝公钥** - RSA2格式的应用公钥
|
||
- **支付宝平台公钥** - RSA2格式的支付宝平台公钥
|
||
- **异步通知URL** - 支付宝异步通知地址
|
||
- **同步返回URL** - 支付完成后的返回地址
|
||
- **支付宝网关地址** - 可配置正式/沙箱环境
|
||
- **支付超时时间** - 可设置5-120分钟
|
||
- **签名算法** - 支持RSA2和RSA
|
||
- **编码格式** - 支持utf-8和gbk
|
||
- **API版本** - 当前固定为1.0
|
||
|
||
#### 辅助功能
|
||
- **测试支付宝配置** - 验证配置参数是否正确
|
||
- **表单验证** - 实时验证必填项
|
||
- **输入提示** - 每个字段都有详细的说明
|
||
|
||
### 2. 系统信息增强
|
||
|
||
在系统信息卡片中新增：
|
||
- **支付功能状态** - 显示是否已启用
|
||
- **支付宝配置状态** - 显示是否已配置
|
||
|
||
### 3. 操作按钮增强
|
||
|
||
在操作卡片中新增：
|
||
- **测试支付功能** - 按钮仅在支付功能启用时显示
|
||
- 点击后创建测试订单并生成支付链接
|
||
|
||
### 4. API接口新增
|
||
|
||
#### `POST /api/v1/settings/test-alipay`
|
||
测试支付宝配置是否正确
|
||
|
||
**功能：**
|
||
- 验证APP_ID格式
|
||
- 验证密钥格式（是否包含BEGIN/END标记）
|
||
- 返回配置详情
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "支付宝配置测试成功！",
|
||
"details": {
|
||
"app_id": "your_app_id",
|
||
"gateway": "https://openapi.alipay.com/gateway.do",
|
||
"sign_type": "RSA2"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `POST /api/v1/settings/test-payment`
|
||
测试支付功能是否正常工作
|
||
|
||
**功能：**
|
||
- 检查支付功能是否启用
|
||
- 检查支付宝配置是否完整
|
||
- 创建测试订单
|
||
- 生成支付链接
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "支付功能测试成功！",
|
||
"payment_url": "https://openapi.alipay.com/...",
|
||
"order_number": "TEST123456789"
|
||
}
|
||
```
|
||
|
||
## 文件修改列表
|
||
|
||
### 1. `app/api/settings.py`
|
||
- 新增支付配置映射
|
||
- 新增 `test_alipay_config()` 函数
|
||
- 新增 `test_payment()` 函数
|
||
- 更新 `save_settings()` 函数支持支付配置保存
|
||
|
||
### 2. `config.py`
|
||
- 新增 `ALIPAY_NOTIFY_URL` 配置
|
||
- 新增 `ALIPAY_RETURN_URL` 配置
|
||
- 新增 `ALIPAY_TIMEOUT_EXPRESS` 配置
|
||
- 新增 `PAYMENT_ENABLED` 配置
|
||
|
||
### 3. `app/web/templates/settings/index.html`
|
||
- 新增支付配置卡片
|
||
- 新增测试支付宝配置按钮
|
||
- 新增测试支付功能模态框
|
||
- 增强系统信息显示
|
||
- 增强操作按钮
|
||
- 新增前端JavaScript处理函数
|
||
|
||
## 配置项说明
|
||
|
||
### 支付配置映射
|
||
|
||
```python
|
||
CONFIG_MAPPING = {
|
||
# ... 其他配置 ...
|
||
|
||
# 支付设置
|
||
'alipay_app_id': 'ALIPAY_APP_ID',
|
||
'alipay_private_key': 'ALIPAY_PRIVATE_KEY',
|
||
'alipay_public_key': 'ALIPAY_PUBLIC_KEY',
|
||
'alipay_alipay_public_key': 'ALIPAY_ALIPAY_PUBLIC_KEY',
|
||
'alipay_gateway': 'ALIPAY_GATEWAY',
|
||
'alipay_sign_type': 'ALIPAY_SIGN_TYPE',
|
||
'alipay_charset': 'ALIPAY_CHARSET',
|
||
'alipay_version': 'ALIPAY_VERSION',
|
||
'alipay_notify_url': 'ALIPAY_NOTIFY_URL',
|
||
'alipay_return_url': 'ALIPAY_RETURN_URL',
|
||
'alipay_timeout_express': 'ALIPAY_TIMEOUT_EXPRESS',
|
||
'payment_enabled': 'PAYMENT_ENABLED'
|
||
}
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
### 1. 配置支付宝参数
|
||
|
||
1. 登录支付宝开放平台 (https://open.alipay.com/)
|
||
2. 创建网站支付应用
|
||
3. 获取以下信息：
|
||
- APP_ID
|
||
- 应用私钥
|
||
- 应用公钥
|
||
- 支付宝平台公钥
|
||
|
||
### 2. 在系统设置中配置
|
||
|
||
1. 登录后台管理系统
|
||
2. 导航到"系统设置"页面
|
||
3. 滚动到"支付配置"区块
|
||
4. 启用支付功能开关
|
||
5. 填写支付宝配置信息
|
||
6. 点击"测试支付宝配置"验证参数
|
||
7. 点击"保存设置"
|
||
|
||
### 3. 测试支付功能
|
||
|
||
1. 在支付配置区块下方点击"测试支付宝配置"按钮
|
||
2. 验证配置无误后，点击"保存设置"
|
||
3. 在右侧操作卡片中点击"测试支付功能"按钮
|
||
4. 系统会创建测试订单并生成支付链接
|
||
5. 点击"是"打开支付链接进行测试
|
||
|
||
### 4. 上线生产环境
|
||
|
||
1. 将支付宝网关地址改为正式环境地址
|
||
2. 使用正式环境的APP_ID和密钥
|
||
3. 配置正确的异步通知URL和返回URL
|
||
4. 再次测试支付功能
|
||
5. 确认无误后正式启用
|
||
|
||
## 安全建议
|
||
|
||
### 1. 密钥管理
|
||
- 私钥和公钥信息非常重要，请妥善保管
|
||
- 不要将私钥提交到代码仓库
|
||
- 定期更换密钥（建议每6个月）
|
||
|
||
### 2. 配置安全
|
||
- 生产环境启用支付功能前，请确保已配置HTTPS
|
||
- 确认异步通知URL可正常访问
|
||
- 验证签名验证功能正常工作
|
||
|
||
### 3. 测试建议
|
||
- 先在沙箱环境测试配置
|
||
- 使用测试订单验证支付流程
|
||
- 确认异步通知能够正常更新订单状态
|
||
|
||
## 注意事项
|
||
|
||
### 1. 配置持久化
|
||
当前配置保存在内存中，重启后丢失。如需持久化，建议：
|
||
- 定期导出配置
|
||
- 使用环境变量配置生产环境
|
||
- 未来可扩展为数据库存储
|
||
|
||
### 2. 密钥显示
|
||
出于安全考虑，私钥字段在保存后不会回显。如需修改，请重新粘贴完整密钥。
|
||
|
||
### 3. 测试金额
|
||
测试订单使用0.01元作为测试金额，不会产生实际费用。
|
||
|
||
## 更新日志
|
||
|
||
### v1.1.0 (2025-12-11)
|
||
- 新增完整的支付配置管理界面
|
||
- 支持支付宝参数配置和测试
|
||
- 新增支付功能开关
|
||
- 增强系统信息显示
|
||
- 新增测试支付功能接口
|
||
- 优化用户体验和操作流程
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请查看：
|
||
- 日志文件：`logs/kamaxitong.log`
|
||
- 支付宝开放平台文档：https://open.alipay.com/
|
||
- 系统集成文档：`docs/alipay_integration.md`
|