hookehuyr

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

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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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**: 创建计划书模板配置