docs(config): 添加配置中心文档索引
- 新增 src/config/README.md:配置中心完整说明,包含应用配置、功能开关、权限系统、计划书字段/模板/条件规则、常量定义等模块的详细说明和使用指南 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Showing
1 changed file
with
373 additions
and
0 deletions
src/config/README.md
0 → 100644
| 1 | +# Config 配置中心 | ||
| 2 | + | ||
| 3 | +> **概述**:本目录集中管理应用的所有配置项,包括功能开关、权限系统、计划书模板和常量定义。 | ||
| 4 | + | ||
| 5 | +## 目录结构 | ||
| 6 | + | ||
| 7 | +``` | ||
| 8 | +src/config/ | ||
| 9 | +├── README.md # 本文档 | ||
| 10 | +├── app.js # 应用全局配置 | ||
| 11 | +├── features.js # 功能开关配置 | ||
| 12 | +├── permissions.js # 权限配置中心 | ||
| 13 | +├── plan-fields.js # 计划书字段定义 | ||
| 14 | +├── plan-templates.js # 计划书模板配置 | ||
| 15 | +├── plan-conditions.js # 计划书条件规则 | ||
| 16 | +└── constants/ # 常量定义 | ||
| 17 | + └── orderStatus.js # 订单状态常量 | ||
| 18 | +``` | ||
| 19 | + | ||
| 20 | +--- | ||
| 21 | + | ||
| 22 | +## 核心文件说明 | ||
| 23 | + | ||
| 24 | +### 1. app.js - 应用全局配置 | ||
| 25 | + | ||
| 26 | +**职责**:管理应用级全局配置 | ||
| 27 | + | ||
| 28 | +**主要配置**: | ||
| 29 | +```javascript | ||
| 30 | +import { USE_MOCK_DATA, API_CONFIG, FEATURE_FLAGS } from '@/config/app' | ||
| 31 | + | ||
| 32 | +// Mock 数据开关(开发环境) | ||
| 33 | +USE_MOCK_DATA = true | ||
| 34 | + | ||
| 35 | +// API 请求配置 | ||
| 36 | +API_CONFIG = { | ||
| 37 | + timeout: 10000, | ||
| 38 | + showRequestLog: true, | ||
| 39 | + showErrorToast: true | ||
| 40 | +} | ||
| 41 | + | ||
| 42 | +// 功能开关(已迁移到 features.js) | ||
| 43 | +FEATURE_FLAGS = { | ||
| 44 | + ENABLE_PLAN: true, | ||
| 45 | + ENABLE_FAVORITE: true, | ||
| 46 | + ENABLE_MESSAGE: true | ||
| 47 | +} | ||
| 48 | +``` | ||
| 49 | + | ||
| 50 | +**使用场景**: | ||
| 51 | +- 开发环境开启 Mock 数据 | ||
| 52 | +- 配置 API 超时时间 | ||
| 53 | +- 控制全局功能开关 | ||
| 54 | + | ||
| 55 | +--- | ||
| 56 | + | ||
| 57 | +### 2. features.js - 功能开关配置 | ||
| 58 | + | ||
| 59 | +**职责**:控制功能的启用/禁用,方便灰度发布和功能回滚 | ||
| 60 | + | ||
| 61 | +**当前功能开关**: | ||
| 62 | +```javascript | ||
| 63 | +import { isFeatureEnabled, getFeatureConfig } from '@/config/features' | ||
| 64 | + | ||
| 65 | +// TabBar 红点功能 | ||
| 66 | +features.tabbarBadge = true | ||
| 67 | +features.tabbarBadgeField = 'unread_msg_count' | ||
| 68 | +features.tabbarBadgeThreshold = 1 | ||
| 69 | + | ||
| 70 | +// 联系客服功能 | ||
| 71 | +features.contactService = false | ||
| 72 | + | ||
| 73 | +// 意见反馈功能 | ||
| 74 | +features.feedback = false | ||
| 75 | +``` | ||
| 76 | + | ||
| 77 | +**使用示例**: | ||
| 78 | +```javascript | ||
| 79 | +// 检查功能是否启用 | ||
| 80 | +if (isFeatureEnabled('tabbarBadge')) { | ||
| 81 | + // 显示红点 | ||
| 82 | +} | ||
| 83 | + | ||
| 84 | +// 获取功能配置 | ||
| 85 | +const field = getFeatureConfig('tabbarBadgeField') | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +**最佳实践**: | ||
| 89 | +- ✅ 新功能建议默认为 `false`,灰度发布后开启 | ||
| 90 | +- ✅ 移除旧功能时设置 `false` 而非删除代码 | ||
| 91 | +- ✅ 功能开关命名采用 camelCase | ||
| 92 | + | ||
| 93 | +--- | ||
| 94 | + | ||
| 95 | +### 3. permissions.js - 权限配置中心 | ||
| 96 | + | ||
| 97 | +**职责**:统一管理权限类型和提示文案 | ||
| 98 | + | ||
| 99 | +**权限类型**: | ||
| 100 | +```javascript | ||
| 101 | +import { PermissionType, getPermissionConfig } from '@/config/permissions' | ||
| 102 | + | ||
| 103 | +PermissionType.LOGIN // 登录权限 | ||
| 104 | +PermissionType.VIP // VIP 权限(预留) | ||
| 105 | +PermissionType.VERIFIED // 实名认证(预留) | ||
| 106 | +``` | ||
| 107 | + | ||
| 108 | +**权限提示配置**: | ||
| 109 | +```javascript | ||
| 110 | +// 获取默认配置 | ||
| 111 | +const config = getPermissionConfig(PermissionType.LOGIN) | ||
| 112 | +// { title: '温馨提示', content: '登录后即可使用完整功能', ... } | ||
| 113 | + | ||
| 114 | +// 自定义文案 | ||
| 115 | +const customConfig = getPermissionConfig(PermissionType.LOGIN, { | ||
| 116 | + content: '请先登录后查看资料详情' | ||
| 117 | +}) | ||
| 118 | +``` | ||
| 119 | + | ||
| 120 | +**使用示例**: | ||
| 121 | +```javascript | ||
| 122 | +import { checkPermission } from '@/composables/usePermission' | ||
| 123 | +import { PermissionType } from '@/config/permissions' | ||
| 124 | + | ||
| 125 | +// 检查登录权限 | ||
| 126 | +checkPermission(PermissionType.LOGIN, () => { | ||
| 127 | + // 已登录,执行操作 | ||
| 128 | +}) | ||
| 129 | +``` | ||
| 130 | + | ||
| 131 | +--- | ||
| 132 | + | ||
| 133 | +### 4. plan-fields.js - 计划书字段定义 | ||
| 134 | + | ||
| 135 | +**职责**:统一管理计划书表单字段的配置信息 | ||
| 136 | + | ||
| 137 | +**核心概念**: | ||
| 138 | + | ||
| 139 | +#### 字段类型(FIELD_TYPES) | ||
| 140 | +```javascript | ||
| 141 | +FIELD_TYPES.TEXT // 文本输入 | ||
| 142 | +FIELD_TYPES.NUMBER // 数字输入 | ||
| 143 | +FIELD_TYPES.AMOUNT // 金额输入(带货币符号) | ||
| 144 | +FIELD_TYPES.PERCENTAGE // 百分比输入 | ||
| 145 | +FIELD_TYPES.SELECT // 下拉选择 | ||
| 146 | +FIELD_TYPES.RADIO // 单选框 | ||
| 147 | +FIELD_TYPES.DATE // 日期选择 | ||
| 148 | +FIELD_TYPES.NAME // 姓名输入(带特殊校验) | ||
| 149 | +``` | ||
| 150 | + | ||
| 151 | +#### 字段分组(FIELD_GROUPS) | ||
| 152 | +```javascript | ||
| 153 | +FIELD_GROUPS.BASIC // 基本信息:姓名、性别、生日 | ||
| 154 | +FIELD_GROUPS.COVERAGE // 保障:保额、缴费年期 | ||
| 155 | +FIELD_GROUPS.WITHDRAWAL // 提取:提取方式、金额等 | ||
| 156 | +``` | ||
| 157 | + | ||
| 158 | +#### 字段定义结构 | ||
| 159 | +```javascript | ||
| 160 | +{ | ||
| 161 | + label: '申请人', // 显示标签 | ||
| 162 | + type: FIELD_TYPES.TEXT, // 字段类型 | ||
| 163 | + required: true, // 是否必填 | ||
| 164 | + api_field: 'customer_name', // API 字段名 | ||
| 165 | + placeholder: '请输入申请人姓名', | ||
| 166 | + component: 'PlanFieldName', // 渲染组件 | ||
| 167 | + group: FIELD_GROUPS.BASIC, // 字段分组 | ||
| 168 | + validation: { // 验证规则 | ||
| 169 | + required: (value) => value?.trim()?.length >= 2 | ||
| 170 | + } | ||
| 171 | +} | ||
| 172 | +``` | ||
| 173 | + | ||
| 174 | +--- | ||
| 175 | + | ||
| 176 | +### 5. plan-templates.js - 计划书模板配置 | ||
| 177 | + | ||
| 178 | +**职责**:定义产品 form_sn 到模板组件和配置的映射关系 | ||
| 179 | + | ||
| 180 | +**快速添加新产品**: | ||
| 181 | +开发环境可使用文档解析工具: | ||
| 182 | +1. 文档解析工具:`/admin/document-parser/index`(上传 PDF/Word,AI 自动解析) | ||
| 183 | +2. API 配置工具:`/admin/document-parser/config`(配置 AI 服务) | ||
| 184 | + | ||
| 185 | +**配置结构**: | ||
| 186 | +```javascript | ||
| 187 | +{ | ||
| 188 | + form_sn: 'life-insurance-wiop3e', | ||
| 189 | + name: 'WIOP3E 盈传创富保障计划 3 - 优选版', | ||
| 190 | + category: 'life', | ||
| 191 | + currency: 'USD', | ||
| 192 | + payment_periods: ['5年', '10年', '直至65岁'], | ||
| 193 | + age_range: { min: 18, max: 75 }, | ||
| 194 | + form_schema: protectionFormSchema, | ||
| 195 | + submit_mapping: baseSubmitMapping | ||
| 196 | +} | ||
| 197 | +``` | ||
| 198 | + | ||
| 199 | +**表单 Schema 结构**: | ||
| 200 | +```javascript | ||
| 201 | +const formSchema = { | ||
| 202 | + base_fields: [ | ||
| 203 | + { | ||
| 204 | + id: 'customer_name', | ||
| 205 | + key: 'customer_name', | ||
| 206 | + type: 'name', | ||
| 207 | + label: '申请人', | ||
| 208 | + placeholder: '请输入申请人', | ||
| 209 | + required: true | ||
| 210 | + } | ||
| 211 | + ], | ||
| 212 | + withdrawal_fields: [ | ||
| 213 | + // 提取计划相关字段 | ||
| 214 | + ] | ||
| 215 | +} | ||
| 216 | +``` | ||
| 217 | + | ||
| 218 | +--- | ||
| 219 | + | ||
| 220 | +### 6. plan-conditions.js - 计划书条件规则 | ||
| 221 | + | ||
| 222 | +**职责**:定义计划书表单字段的显示/隐藏/联动规则 | ||
| 223 | + | ||
| 224 | +**条件规则格式**: | ||
| 225 | +```javascript | ||
| 226 | +// 新格式(推荐) | ||
| 227 | +{ | ||
| 228 | + show_when: { | ||
| 229 | + field: 'withdrawal_enabled', | ||
| 230 | + op: 'eq', | ||
| 231 | + value: '是' | ||
| 232 | + }, | ||
| 233 | + clear_when_hidden: true // 隐藏时自动清空 | ||
| 234 | +} | ||
| 235 | + | ||
| 236 | +// 旧格式(向后兼容) | ||
| 237 | +{ | ||
| 238 | + show_when: { | ||
| 239 | + field: 'withdrawal_enabled', | ||
| 240 | + equals: '是' | ||
| 241 | + } | ||
| 242 | +} | ||
| 243 | +``` | ||
| 244 | + | ||
| 245 | +**操作符(op)**: | ||
| 246 | +- `eq` - 等于 | ||
| 247 | +- `ne` - 不等于 | ||
| 248 | +- `gt` - 大于 | ||
| 249 | +- `lt` - 小于 | ||
| 250 | +- `in` - 包含于 | ||
| 251 | + | ||
| 252 | +--- | ||
| 253 | + | ||
| 254 | +### 7. constants/orderStatus.js - 订单状态常量 | ||
| 255 | + | ||
| 256 | +**职责**:统一管理订单状态值,避免魔法数字 | ||
| 257 | + | ||
| 258 | +**状态常量**: | ||
| 259 | +```javascript | ||
| 260 | +import { ORDER_STATUS, mapOrderStatus, getStatusText } from '@/config/constants/orderStatus' | ||
| 261 | + | ||
| 262 | +// API 状态值 | ||
| 263 | +ORDER_STATUS.PENDING // '3' - 待处理 | ||
| 264 | +ORDER_STATUS.PROCESSING // '5' - 处理中 | ||
| 265 | +ORDER_STATUS.GENERATED // '7' - 已生成 | ||
| 266 | +ORDER_STATUS.VIEWED // '9' - 已查看 | ||
| 267 | + | ||
| 268 | +// 状态映射 | ||
| 269 | +const frontendStatus = mapOrderStatus('7') // 返回: 'generated' | ||
| 270 | + | ||
| 271 | +// 获取状态文本 | ||
| 272 | +const text = getStatusText('processing') // 返回: '处理中' | ||
| 273 | +``` | ||
| 274 | + | ||
| 275 | +--- | ||
| 276 | + | ||
| 277 | +## 使用指南 | ||
| 278 | + | ||
| 279 | +### 添加新的功能开关 | ||
| 280 | + | ||
| 281 | +1. 在 `features.js` 中添加开关定义: | ||
| 282 | +```javascript | ||
| 283 | +export const features = { | ||
| 284 | + // ... 现有开关 | ||
| 285 | + newFeature: false // 新功能默认关闭 | ||
| 286 | +} | ||
| 287 | +``` | ||
| 288 | + | ||
| 289 | +2. 在组件中使用: | ||
| 290 | +```javascript | ||
| 291 | +import { isFeatureEnabled } from '@/config/features' | ||
| 292 | + | ||
| 293 | +if (isFeatureEnabled('newFeature')) { | ||
| 294 | + // 功能逻辑 | ||
| 295 | +} | ||
| 296 | +``` | ||
| 297 | + | ||
| 298 | +### 添加新的计划书产品 | ||
| 299 | + | ||
| 300 | +**方式一:使用文档解析工具(推荐)** | ||
| 301 | +1. 访问 `/admin/document-parser/index` | ||
| 302 | +2. 上传产品 PDF/Word 文档 | ||
| 303 | +3. AI 自动提取配置 | ||
| 304 | +4. 复制生成的配置到 `plan-templates.js` | ||
| 305 | + | ||
| 306 | +**方式二:手动配置** | ||
| 307 | +1. 在 `plan-templates.js` 中添加新配置 | ||
| 308 | +2. 确保 `form_sn` 唯一 | ||
| 309 | +3. 定义 `form_schema` 和 `submit_mapping` | ||
| 310 | +4. 在 `plan-fields.js` 中添加必要字段定义 | ||
| 311 | + | ||
| 312 | +### 添加新的常量 | ||
| 313 | + | ||
| 314 | +1. 在 `constants/` 目录下创建新文件(如 `productStatus.js`) | ||
| 315 | +2. 定义常量和辅助函数: | ||
| 316 | +```javascript | ||
| 317 | +export const PRODUCT_STATUS = { | ||
| 318 | + ACTIVE: 'active', | ||
| 319 | + INACTIVE: 'inactive' | ||
| 320 | +} | ||
| 321 | + | ||
| 322 | +export function getStatusText(status) { | ||
| 323 | + return PRODUCT_STATUS[status] || '未知' | ||
| 324 | +} | ||
| 325 | +``` | ||
| 326 | + | ||
| 327 | +--- | ||
| 328 | + | ||
| 329 | +## 最佳实践 | ||
| 330 | + | ||
| 331 | +### 配置管理原则 | ||
| 332 | + | ||
| 333 | +| 原则 | 说明 | 示例 | | ||
| 334 | +|------|------|------| | ||
| 335 | +| **集中管理** | 所有配置统一放在 config 目录 | ✅ `/config/app.js`<br>❌ 散落在各组件 | | ||
| 336 | +| **避免魔法值** | 使用常量替代硬编码值 | ✅ `ORDER_STATUS.PENDING`<br>❌ `'3'` | | ||
| 337 | +| **功能开关** | 新功能默认关闭,灰度发布 | ✅ `newFeature: false` | | ||
| 338 | +| **类型安全** | 使用枚举而非字符串 | ✅ `FIELD_TYPES.TEXT`<br>❌ `'text'` | | ||
| 339 | + | ||
| 340 | +### 计划书配置规范 | ||
| 341 | + | ||
| 342 | +1. **字段命名一致性**:`customer_name`(API)与 `customer_name`(前端)保持一致 | ||
| 343 | +2. **Schema 唯一性**:`form_sn` 必须全局唯一 | ||
| 344 | +3. **字段复用**:优先复用 `plan-fields.js` 中已有字段 | ||
| 345 | +4. **条件规则**:使用新格式 `show_when: { field, op, value }` | ||
| 346 | + | ||
| 347 | +### 配置文件组织 | ||
| 348 | + | ||
| 349 | +``` | ||
| 350 | +config/ | ||
| 351 | +├── 应用级配置 → app.js | ||
| 352 | +├── 功能开关 → features.js | ||
| 353 | +├── 权限配置 → permissions.js | ||
| 354 | +├── 业务配置 → plan-*.js | ||
| 355 | +└── 常量定义 → constants/ | ||
| 356 | +``` | ||
| 357 | + | ||
| 358 | +--- | ||
| 359 | + | ||
| 360 | +## 相关文档 | ||
| 361 | + | ||
| 362 | +- **[计划书模块文档](../../docs/modules/plan.md)** - 计划书功能详细说明 | ||
| 363 | +- **[经验教训总结](../../docs/lessons-learned.md)** - 开发中遇到的问题和解决方案 | ||
| 364 | +- **[项目 README](../../README.md)** - 项目概述 | ||
| 365 | + | ||
| 366 | +--- | ||
| 367 | + | ||
| 368 | +## 维护日志 | ||
| 369 | + | ||
| 370 | +- **2026-02-25**: 创建配置中心 README 文档 | ||
| 371 | +- **2026-02-14**: 添加订单状态常量 | ||
| 372 | +- **2026-02-13**: 重构权限配置中心 | ||
| 373 | +- **2026-02-06**: 创建计划书模板配置 |
-
Please register or login to post a comment