hookehuyr

docs(config): 添加配置中心文档索引

- 新增 src/config/README.md:配置中心完整说明,包含应用配置、功能开关、权限系统、计划书字段/模板/条件规则、常量定义等模块的详细说明和使用指南

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
# Config 配置中心
> **概述**:本目录集中管理应用的所有配置项,包括功能开关、权限系统、计划书模板和常量定义。
## 目录结构
```
src/config/
├── README.md # 本文档
├── app.js # 应用全局配置
├── features.js # 功能开关配置
├── permissions.js # 权限配置中心
├── plan-fields.js # 计划书字段定义
├── plan-templates.js # 计划书模板配置
├── plan-conditions.js # 计划书条件规则
└── constants/ # 常量定义
└── orderStatus.js # 订单状态常量
```
---
## 核心文件说明
### 1. app.js - 应用全局配置
**职责**:管理应用级全局配置
**主要配置**
```javascript
import { USE_MOCK_DATA, API_CONFIG, FEATURE_FLAGS } from '@/config/app'
// Mock 数据开关(开发环境)
USE_MOCK_DATA = true
// API 请求配置
API_CONFIG = {
timeout: 10000,
showRequestLog: true,
showErrorToast: true
}
// 功能开关(已迁移到 features.js)
FEATURE_FLAGS = {
ENABLE_PLAN: true,
ENABLE_FAVORITE: true,
ENABLE_MESSAGE: true
}
```
**使用场景**
- 开发环境开启 Mock 数据
- 配置 API 超时时间
- 控制全局功能开关
---
### 2. features.js - 功能开关配置
**职责**:控制功能的启用/禁用,方便灰度发布和功能回滚
**当前功能开关**
```javascript
import { isFeatureEnabled, getFeatureConfig } from '@/config/features'
// TabBar 红点功能
features.tabbarBadge = true
features.tabbarBadgeField = 'unread_msg_count'
features.tabbarBadgeThreshold = 1
// 联系客服功能
features.contactService = false
// 意见反馈功能
features.feedback = false
```
**使用示例**
```javascript
// 检查功能是否启用
if (isFeatureEnabled('tabbarBadge')) {
// 显示红点
}
// 获取功能配置
const field = getFeatureConfig('tabbarBadgeField')
```
**最佳实践**
- ✅ 新功能建议默认为 `false`,灰度发布后开启
- ✅ 移除旧功能时设置 `false` 而非删除代码
- ✅ 功能开关命名采用 camelCase
---
### 3. permissions.js - 权限配置中心
**职责**:统一管理权限类型和提示文案
**权限类型**
```javascript
import { PermissionType, getPermissionConfig } from '@/config/permissions'
PermissionType.LOGIN // 登录权限
PermissionType.VIP // VIP 权限(预留)
PermissionType.VERIFIED // 实名认证(预留)
```
**权限提示配置**
```javascript
// 获取默认配置
const config = getPermissionConfig(PermissionType.LOGIN)
// { title: '温馨提示', content: '登录后即可使用完整功能', ... }
// 自定义文案
const customConfig = getPermissionConfig(PermissionType.LOGIN, {
content: '请先登录后查看资料详情'
})
```
**使用示例**
```javascript
import { checkPermission } from '@/composables/usePermission'
import { PermissionType } from '@/config/permissions'
// 检查登录权限
checkPermission(PermissionType.LOGIN, () => {
// 已登录,执行操作
})
```
---
### 4. plan-fields.js - 计划书字段定义
**职责**:统一管理计划书表单字段的配置信息
**核心概念**
#### 字段类型(FIELD_TYPES)
```javascript
FIELD_TYPES.TEXT // 文本输入
FIELD_TYPES.NUMBER // 数字输入
FIELD_TYPES.AMOUNT // 金额输入(带货币符号)
FIELD_TYPES.PERCENTAGE // 百分比输入
FIELD_TYPES.SELECT // 下拉选择
FIELD_TYPES.RADIO // 单选框
FIELD_TYPES.DATE // 日期选择
FIELD_TYPES.NAME // 姓名输入(带特殊校验)
```
#### 字段分组(FIELD_GROUPS)
```javascript
FIELD_GROUPS.BASIC // 基本信息:姓名、性别、生日
FIELD_GROUPS.COVERAGE // 保障:保额、缴费年期
FIELD_GROUPS.WITHDRAWAL // 提取:提取方式、金额等
```
#### 字段定义结构
```javascript
{
label: '申请人', // 显示标签
type: FIELD_TYPES.TEXT, // 字段类型
required: true, // 是否必填
api_field: 'customer_name', // API 字段名
placeholder: '请输入申请人姓名',
component: 'PlanFieldName', // 渲染组件
group: FIELD_GROUPS.BASIC, // 字段分组
validation: { // 验证规则
required: (value) => value?.trim()?.length >= 2
}
}
```
---
### 5. plan-templates.js - 计划书模板配置
**职责**:定义产品 form_sn 到模板组件和配置的映射关系
**快速添加新产品**
开发环境可使用文档解析工具:
1. 文档解析工具:`/admin/document-parser/index`(上传 PDF/Word,AI 自动解析)
2. API 配置工具:`/admin/document-parser/config`(配置 AI 服务)
**配置结构**
```javascript
{
form_sn: 'life-insurance-wiop3e',
name: 'WIOP3E 盈传创富保障计划 3 - 优选版',
category: 'life',
currency: 'USD',
payment_periods: ['5年', '10年', '直至65岁'],
age_range: { min: 18, max: 75 },
form_schema: protectionFormSchema,
submit_mapping: baseSubmitMapping
}
```
**表单 Schema 结构**
```javascript
const formSchema = {
base_fields: [
{
id: 'customer_name',
key: 'customer_name',
type: 'name',
label: '申请人',
placeholder: '请输入申请人',
required: true
}
],
withdrawal_fields: [
// 提取计划相关字段
]
}
```
---
### 6. plan-conditions.js - 计划书条件规则
**职责**:定义计划书表单字段的显示/隐藏/联动规则
**条件规则格式**
```javascript
// 新格式(推荐)
{
show_when: {
field: 'withdrawal_enabled',
op: 'eq',
value: '是'
},
clear_when_hidden: true // 隐藏时自动清空
}
// 旧格式(向后兼容)
{
show_when: {
field: 'withdrawal_enabled',
equals: '是'
}
}
```
**操作符(op)**
- `eq` - 等于
- `ne` - 不等于
- `gt` - 大于
- `lt` - 小于
- `in` - 包含于
---
### 7. constants/orderStatus.js - 订单状态常量
**职责**:统一管理订单状态值,避免魔法数字
**状态常量**
```javascript
import { ORDER_STATUS, mapOrderStatus, getStatusText } from '@/config/constants/orderStatus'
// API 状态值
ORDER_STATUS.PENDING // '3' - 待处理
ORDER_STATUS.PROCESSING // '5' - 处理中
ORDER_STATUS.GENERATED // '7' - 已生成
ORDER_STATUS.VIEWED // '9' - 已查看
// 状态映射
const frontendStatus = mapOrderStatus('7') // 返回: 'generated'
// 获取状态文本
const text = getStatusText('processing') // 返回: '处理中'
```
---
## 使用指南
### 添加新的功能开关
1.`features.js` 中添加开关定义:
```javascript
export const features = {
// ... 现有开关
newFeature: false // 新功能默认关闭
}
```
2. 在组件中使用:
```javascript
import { isFeatureEnabled } from '@/config/features'
if (isFeatureEnabled('newFeature')) {
// 功能逻辑
}
```
### 添加新的计划书产品
**方式一:使用文档解析工具(推荐)**
1. 访问 `/admin/document-parser/index`
2. 上传产品 PDF/Word 文档
3. AI 自动提取配置
4. 复制生成的配置到 `plan-templates.js`
**方式二:手动配置**
1.`plan-templates.js` 中添加新配置
2. 确保 `form_sn` 唯一
3. 定义 `form_schema``submit_mapping`
4.`plan-fields.js` 中添加必要字段定义
### 添加新的常量
1.`constants/` 目录下创建新文件(如 `productStatus.js`
2. 定义常量和辅助函数:
```javascript
export const PRODUCT_STATUS = {
ACTIVE: 'active',
INACTIVE: 'inactive'
}
export function getStatusText(status) {
return PRODUCT_STATUS[status] || '未知'
}
```
---
## 最佳实践
### 配置管理原则
| 原则 | 说明 | 示例 |
|------|------|------|
| **集中管理** | 所有配置统一放在 config 目录 | ✅ `/config/app.js`<br>❌ 散落在各组件 |
| **避免魔法值** | 使用常量替代硬编码值 | ✅ `ORDER_STATUS.PENDING`<br>`'3'` |
| **功能开关** | 新功能默认关闭,灰度发布 | ✅ `newFeature: false` |
| **类型安全** | 使用枚举而非字符串 | ✅ `FIELD_TYPES.TEXT`<br>`'text'` |
### 计划书配置规范
1. **字段命名一致性**`customer_name`(API)与 `customer_name`(前端)保持一致
2. **Schema 唯一性**`form_sn` 必须全局唯一
3. **字段复用**:优先复用 `plan-fields.js` 中已有字段
4. **条件规则**:使用新格式 `show_when: { field, op, value }`
### 配置文件组织
```
config/
├── 应用级配置 → app.js
├── 功能开关 → features.js
├── 权限配置 → permissions.js
├── 业务配置 → plan-*.js
└── 常量定义 → constants/
```
---
## 相关文档
- **[计划书模块文档](../../docs/modules/plan.md)** - 计划书功能详细说明
- **[经验教训总结](../../docs/lessons-learned.md)** - 开发中遇到的问题和解决方案
- **[项目 README](../../README.md)** - 项目概述
---
## 维护日志
- **2026-02-25**: 创建配置中心 README 文档
- **2026-02-14**: 添加订单状态常量
- **2026-02-13**: 重构权限配置中心
- **2026-02-06**: 创建计划书模板配置