# cfc-web 管理后台重构：基于 ProductDimensionConfig + KnowledgeBase 的动态渲染

**日期:** 2026-06-20
**状态:** 草稿
**影响范围:** cfc-web (Vue 2 Admin Panel) + cfc-backend (部分 API 增强)
**任务数:** 13 个 (Task 1-13, Task 4 推迟)
**总工时预估:** 5-10 天

## 1. 概述

### 1.1 问题

cfc-web 管理后台中大量硬编码了产品维度结构（五维、三维、行动维度等），导致：
- 新增/修改维度需要改多处前端代码
- KnowledgeBase CRUD 与维度配置的关联不清晰
- 后端 `ProductDimensionConfig` 和 `DanKnowledgeBase` 表已有数据，但前端未充分使用

### 1.2 目标

将管理后台重构为基于 `ProductDimensionConfig` + `KnowledgeBase` 动态渲染的模式：

```
ProductDimensionConfig (维度定义)
        ↓ 动态加载
KnowledgeBase (知识点内容) ──→ 统一管理 CRUD
        ↓
渲染组件 (动态表单/表格/树)
```

### 1.3 成功标准

- [ ] 新增维度只需在 `ProductDimensionConfig` 表插入一行 + 对应 KnowledgeBase 数据
- [ ] 无需修改前端代码即可展示新维度
- [ ] 所有 KnowledgeBase CRUD 路径一致
- [ ] 现有功能完全保留，UI 无退化

## 2. 先行发现

已有后端实体和 API：

| 资源 | 位置 | 状态 |
|------|------|------|
| `ProductDimensionConfig` entity | `cfc-backend/.../entity/ProductDimensionConfig.java` | ✅ 存在 |
| `DanKnowledgeBase` entity | `cfc-backend/.../entity/DanKnowledgeBase.java` | ✅ 存在 |
| `DanKnowledgeBaseController` | `cfc-backend/.../controller/admin/DanKnowledgeBaseController.java` | ✅ 存在 |
| `AdminController` (含维度相关接口) | `cfc-backend/.../controller/admin/AdminController.java` | ✅ 存在 |
| KnowledgeBase 管理页面 | `cfc-web/src/views/admin/knowledge/` | ✅ 存在 |
| 维度相关配置 | `cfc-web/src/views/admin/dimension/` | 硬编码严重 |

## 3. 实施计划

### 任务依赖关系

```
Task 1 ─→ Task 3 ─→ Task 5 ─→ Task 7 ─→ Task 10
Task 2 ─→ Task 6 ─→ Task 8 ─→ Task 9 ─→ Task 10
                                            ↓
Task 11 (独立) ←──────────────────── Task 10
Task 12 (依赖 Task 5)
Task 13 (依赖 Task 5)
```

### 3.1 阶段 1：后端 API 统一 (1-3 天)

**Task 1: 梳理 ProductDimensionConfig API 端点和数据结构**
*依赖: 无*

涉及文件：
- `cfc-backend/.../controller/admin/AdminController.java` — 检查现有维度接口
- `cfc-backend/.../entity/ProductDimensionConfig.java` — 确认字段
- `cfc-backend/.../service/ProductDimensionConfigService.java` — 确认业务逻辑

具体操作：
1. 检查 `AdminController` 中已有接口：`listProductDimensionConfigs`, `getProductDimensionConfig`, `saveProductDimensionConfig`, `deleteProductDimensionConfig`
2. 确保 API 路径统一为 `/api/admin/dimension-config/**`
3. 验证返回 JSON 结构包含：`id`, `dimensionCode`, `dimensionName`, `dimensionType`, `parentId`, `sort`, `enabled`, `remark`
4. 验证完成后，写下确认的 API 接口清单

**Task 2: 统一 KnowledgeBase API**
*依赖: 无*

涉及文件：
- `cfc-backend/.../controller/admin/DanKnowledgeBaseController.java` — 检查/补充接口
- `cfc-backend/.../entity/DanKnowledgeBase.java` — 确认字段

具体操作：
1. 检查 `DanKnowledgeBaseController` 现有接口是否覆盖分页查询 + 按 `dimensionCode` 筛选
2. 确认所有接口统一前缀 `/api/admin/knowledge-base/`
3. 若缺少接口则补充：
   - `POST /api/admin/knowledge-base/list` → 分页 + 按 `dimensionCode` 筛选
   - `POST /api/admin/knowledge-base/create` → 新建
   - `POST /api/admin/knowledge-base/update` → 更新
   - `POST /api/admin/knowledge-base/delete` → 删除 (逻辑删除)
   - `POST /api/admin/knowledge-base/get` → 详情

**Task 3: 添加维度树接口**
*依赖: Task 1 完成*

- `POST /api/admin/dimension-config/tree` → 返回层级树结构
- 用于前端树形选择器
- 如果后台已有类似接口则跳过

### 3.2 阶段 2: 前端核心组件 (2-3 天)

**Task 5: 创建 Vuex Store 模块**

`cfc-web/src/store/modules/dimension.js`:

```javascript
import { getDimensionConfigs, getKnowledgeBaseList } from '@/api/dimension'

export default {
  namespaced: true,
  state: {
    dimensions: [],        // ProductDimensionConfig 列表
    dimensionTree: [],     // 维度树
    knowledgeList: [],     // KnowledgeBase 列表
    knowledgeTotal: 0,
    loading: false
  },
  mutations: {
    SET_DIMENSIONS(state, list) {
      state.dimensions = list
    },
    SET_DIMENSION_TREE(state, tree) {
      state.dimensionTree = tree
    },
    SET_KNOWLEDGE_LIST(state, { list, total }) {
      state.knowledgeList = list
      state.knowledgeTotal = total
    }
  },
  actions: {
    async fetchDimensions({ commit }) {
      const res = await getDimensionConfigs()
      commit('SET_DIMENSIONS', res.data || [])
    },
    async fetchKnowledge({ commit }, params) {
      const res = await getKnowledgeBaseList(params)
      commit('SET_KNOWLEDGE_LIST', {
        list: res.data?.records || [],
        total: res.data?.total || 0
      })
    }
  }
}
```

**Task 6: 通用 API 封装**

`cfc-web/src/api/dimension.js`:

```javascript
import request from '@/utils/request'

export function getDimensionConfigs(data) {
  return request({
    url: '/api/admin/dimension-config/list',
    method: 'post',
    data
  })
}

export function getDimensionTree() {
  return request({
    url: '/api/admin/dimension-config/tree',
    method: 'post'
  })
}

export function saveDimensionConfig(data) {
  return request({
    url: '/api/admin/dimension-config/save',
    method: 'post',
    data
  })
}

export function deleteDimensionConfig(id) {
  return request({
    url: '/api/admin/dimension-config/delete',
    method: 'post',
    data: { id }
  })
}

export function getKnowledgeBaseList(data) {
  return request({
    url: '/api/admin/knowledge-base/list',
    method: 'post',
    data
  })
}

export function saveKnowledgeBase(data) {
  return request({
    url: '/api/admin/knowledge-base/save',
    method: 'post',
    data
  })
}

export function deleteKnowledgeBase(id) {
  return request({
    url: '/api/admin/knowledge-base/delete',
    method: 'post',
    data: { id }
  })
}
```

**Task 7: 动态维度选择器组件**

`cfc-web/src/components/DimensionSelector/index.vue`:

```vue
<template>
  <el-select v-model="selectedValue" :multiple="multiple" clearable filterable placeholder="选择维度">
    <el-option
      v-for="dim in dimensionOptions"
      :key="dim.dimensionCode"
      :label="dim.dimensionName"
      :value="dim.dimensionCode"
    />
  </el-select>
</template>

<script>
import { mapState } from 'vuex'

export default {
  props: {
    value: { type: [String, Array], default: '' },
    multiple: { type: Boolean, default: false },
    dimensionType: { type: String, default: '' }
  },
  computed: {
    ...mapState('dimension', ['dimensions']),
    dimensionOptions() {
      let list = this.dimensions
      if (this.dimensionType) {
        list = list.filter(d => d.dimensionType === this.dimensionType)
      }
      return list
    },
    selectedValue: {
      get() { return this.value },
      set(val) { this.$emit('input', val) }
    }
  }
}
</script>
```

**Task 8: KnowledgeBase 动态表格组件**

`cfc-web/src/components/KnowledgeTable/index.vue` — 通用表格展示，根据传入的 `dimensionCode` 动态加载对应数据：

```vue
<template>
  <el-table :data="list" v-loading="loading" stripe>
    <el-table-column prop="id" label="ID" width="80" />
    <el-table-column prop="title" label="标题" min-width="200" show-overflow-tooltip />
    <el-table-column prop="content" label="内容" min-width="300" show-overflow-tooltip />
    <el-table-column prop="sort" label="排序" width="80" align="center" />
    <el-table-column label="状态" width="100" align="center">
      <template slot-scope="{ row }">
        <el-tag :type="row.status === 1 ? 'success' : 'info'">
          {{ row.status === 1 ? '启用' : '禁用' }}
        </el-tag>
      </template>
    </el-table-column>
    <el-table-column label="操作" width="200" fixed="right">
      <template slot-scope="{ row }">
        <el-button size="mini" type="text" @click="handleEdit(row)">编辑</el-button>
        <el-button size="mini" type="text" style="color: #f56c6c" @click="handleDelete(row)">删除</el-button>
      </template>
    </el-table-column>
  </el-table>
</template>
```

**Task 9: 通用 KnowledgeBase 编辑对话框**

`cfc-web/src/components/KnowledgeDialog/index.vue` — 新增/编辑共用的对话框：

```vue
<template>
  <el-dialog :title="isEdit ? '编辑知识点' : '新增知识点'" :visible.sync="visible" width="700px">
    <el-form ref="form" :model="form" :rules="rules" label-width="120px">
      <el-form-item label="维度" prop="dimensionCode">
        <dimension-selector v-model="form.dimensionCode" />
      </el-form-item>
      <el-form-item label="标题" prop="title">
        <el-input v-model="form.title" placeholder="请输入标题" maxlength="200" />
      </el-form-item>
      <el-form-item label="内容" prop="content">
        <el-input type="textarea" v-model="form.content" :rows="6" placeholder="请输入内容" />
      </el-form-item>
      <el-form-item label="排序" prop="sort">
        <el-input-number v-model="form.sort" :min="0" :max="9999" />
      </el-form-item>
      <el-form-item label="状态">
        <el-switch v-model="form.status" :active-value="1" :inactive-value="0" />
      </el-form-item>
    </el-form>
    <span slot="footer">
      <el-button @click="visible = false">取消</el-button>
      <el-button type="primary" @click="handleSubmit" :loading="submitting">保存</el-button>
    </span>
  </el-dialog>
</template>
```

### 3.3 阶段 3: 现有视图迁移 (2-4 天)

**Task 10: 重构 KnowledgeBase 管理页面**
*依赖: Task 2, 5, 6, 7, 8, 9*

涉及文件：
- `cfc-web/src/views/admin/knowledge/index.vue` — 主页面
- `cfc-web/src/views/admin/knowledge/*.vue` — 相关子页面

具体操作：
1. 使用 `DimensionSelector` 组件替换硬编码的维度下拉框
2. 使用 `KnowledgeTable` 组件替换现有表格
3. 使用 `KnowledgeDialog` 组件替换新增/编辑弹窗
4. 清理不再需要的本地状态和方法
5. 移除硬编码的维度字段

**Task 11: 重构维度配置管理页面**
*依赖: Task 1, 3*

涉及文件：
- `cfc-web/src/views/admin/dimension/index.vue` — 维度配置页面

具体操作：
1. 从 `ProductDimensionConfig` API 动态加载维度列表
2. 树形展示维度层级（使用 `el-tree` + dimension tree API）
3. 支持拖拽排序（`el-tree` draggable + API 保存排序）
4. CRUD 操作直接对接后端 API

**Task 12: 替换硬编码维度引用**
*依赖: Task 5 完成*

通过以下 grep 模式搜索所有硬编码引用：

```bash
# 搜索硬编码的五维名称
grep -rn "五维·\|五維·" cfc-web/src/
grep -rn "五维\.\|五維\." cfc-web/src/

# 搜索硬编码的三维名称
grep -rn "三维·\|三維·" cfc-web/src/

# 搜索硬编码的行动维度
grep -rn "行动维度\|行動維度" cfc-web/src/

# 搜索其他可能的硬编码维度名
grep -rn "'五维'\|\"五维\"\|'三维'\|\"三维\"\|'行动'\|\"行动\"" cfc-web/src/
```

涉及文件（预计）：
- `cfc-web/src/views/admin/dimension/index.vue` — 维度管理
- `cfc-web/src/views/admin/knowledge/*.vue` — 知识点管理
- `cfc-web/src/views/admin/task/*.vue` — 任务管理
- `cfc-web/src/views/admin/energy/*.vue` — 能量管理
- `cfc-web/src/views/admin/assessment/*.vue` — 测评管理

具体操作：
1. 对每个匹配文件，将硬编码字符串替换为 `dimensions[dimensionCode].dimensionName` 的动态读取
2. 使用 `dimensionCode` 作为唯一标识，`dimensionName` 作为展示名
3. 确保替换后显示内容与原样一致

**Task 13: 添加缓存机制**
*依赖: Task 5 完成*

具体操作：
1. Dimension config 数据缓存到 `localStorage`，key: `cfc_dimensions_${version}`
2. 后端返回 `version` 字段，前端对比版本号决定是否刷新
3. 管理后台发布新维度后更新版本号
4. 缓存有效期 24 小时，过期自动刷新

## 4. 阶段 4 (可选): 批量导入支持

**⚠️ 推迟至下一迭代 — 当前不实施**

~~Task 4: 添加批量接口 `POST /api/admin/knowledge-base/batch-save`~~
- 当前阶段不需要批量导入功能
- 基础 CRUD 已满足日常运营需求

## 5. 测试策略

### 5.1 后端测试 (每个 API Task 后执行)

| 测试类型 | 内容 | 命令 |
|---------|------|------|
| 编译验证 | API 编译通过 | `mvn clean compile -pl cfc-backend` |
| 单元测试 | Controller + Service 层 | `mvn test -pl cfc-backend -Dtest=*ControllerTest,*ServiceTest` |
| API 测试 | 手动 curl 验证 CRUD | `curl -X POST http://localhost:8080/api/admin/...` |

### 5.2 前端测试 (每个组件 Task 后执行)

| 测试类型 | 内容 | 命令 |
|---------|------|------|
| 编译验证 | 无语法错误 | `cd cfc-web && npm run build -- --no-progress` |
| Lint | 代码风格 | `cd cfc-web && npm run lint` |
| 手动测试 | 浏览器打开确认 UI 正常 | 打开 localhost:8082 对应页面 |

### 5.3 回归测试 (全部 Task 完成后)

1. 遍历所有管理后台页面，确认无 404/白屏
2. 验证 CRUD 操作正常
3. grep 确认无残留硬编码（使用 Task 12 中列出的 grep 模式）
4. 检查浏览器 Console 无报错

## 6. 验收清单

| # | 检查项 | 验证方式 |
|---|--------|----------|
| 1 | 维度配置 CRUD 正常 | 手动测试增删改查 |
| 2 | KnowledgeBase CRUD 正常 | 手动测试增删改查 |
| 3 | 维度树展示正确 | 检查层级关系 |
| 4 | 新增维度后前端自动展示 | 配置 → 刷新页面 → 出现 |
| 5 | 无硬编码维度名称 | grep 检查 `五维`、`三维` 等字符串 |
| 6 | 所有页面正常渲染 | 遍历所有 admin 页面，Console 无报错 |
| 7 | 旧功能无退化 | 回归测试各管理页面 |

## 7. 分支策略

```
feature/refactor-dimension-dynamic
├── task/01-backend-api-review     # Task 1
├── task/02-knowledge-api          # Task 2
├── task/03-dimension-tree-api     # Task 3
├── task/05-vuex-store             # Task 5
├── task/06-api-package            # Task 6
├── task/07-dimension-selector     # Task 7
├── task/08-knowledge-table        # Task 8
├── task/09-knowledge-dialog       # Task 9
├── task/10-migrate-knowledge      # Task 10
├── task/11-migrate-dimension      # Task 11
├── task/12-replace-hardcode       # Task 12 (可拆分子分支)
└── task/13-cache                  # Task 13
```

- 每个 Task 在 feature/refactor-dimension-dynamic 上开独立分支
- 合并前需 Code Review
- 合并后验证 CI 通过

## 8. 回滚方案

- 每个 Task 独立分支，合并前 Code Review
- 若某 Task 导致问题，revert 该分支后重新合并
- 后端 API 变更需确保向前兼容（旧接口保留至下个版本）
- 若阶段 3 迁移导致页面故障，可回退到旧版组件（新旧组件共存）