# 维度配置 + 知识库动态管理平台

**日期:** 2026-06-20
**状态:** 设计完成，待实现
**范围:** cfc-backend（实体/Service/Controller）+ cfc-web（Vuex/Api/组件）

---

## 1. 架构概述

```
product_dimension_config (维度定义)
         ↓ 1:N（知识点可归属多个维度）
knowledge_tag ← dan_knowledge_base_dimension (中间关联表)
         ↓
dan_knowledge_base (知识库)
         ↓ 实时推送
Dify 知识库 (dify.bianwoyy.cn)
```

**核心目标：** 管理后台的维度配置和知识点管理从硬编码改为数据库驱动，新增进维度无需修改前端代码。同时支持知识点实时同步到 Dify 知识库。

---

## 2. 数据库设计

### 2.1 product_dimension_config（维度配置表）

```sql
CREATE TABLE product_dimension_config (
    id            BIGINT PRIMARY KEY AUTO_INCREMENT,
    dimension_code VARCHAR(50)  NOT NULL UNIQUE COMMENT '维度代码: body/mind/wisdom/action/wealth',
    dimension_name VARCHAR(100) NOT NULL COMMENT '维度名称',
    dimension_type VARCHAR(50)  NOT NULL DEFAULT 'five' COMMENT '类型: five(三维)/action(行动)/other',
    parent_id     BIGINT COMMENT '父级ID，无父级为NULL',
    sort          INT DEFAULT 0 COMMENT '排序',
    enabled       TINYINT(1) DEFAULT 1 COMMENT '启用: 0禁用 1启用',
    dify_dataset_id VARCHAR(100) COMMENT 'Dify Dataset ID，不填则不同步',
    remark        VARCHAR(500) COMMENT '备注',
    created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at    DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### 2.2 dan_knowledge_base（知识库表）

```sql
CREATE TABLE dan_knowledge_base (
    id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    title       VARCHAR(200) NOT NULL COMMENT '知识标题',
    content     TEXT NOT NULL COMMENT '知识内容',
    sort        INT DEFAULT 0 COMMENT '排序',
    status      TINYINT(1) DEFAULT 1 COMMENT '状态: 0禁用 1启用',
    remark      VARCHAR(500) COMMENT '备注',
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### 2.3 dan_knowledge_base_dimension（维度关联表）

```sql
CREATE TABLE dan_knowledge_base_dimension (
    id           BIGINT PRIMARY KEY AUTO_INCREMENT,
    knowledge_id BIGINT NOT NULL COMMENT '知识库ID',
    dimension_id BIGINT NOT NULL COMMENT '维度配置ID',
    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_knowledge_dimension (knowledge_id, dimension_id),
    FOREIGN KEY (knowledge_id) REFERENCES dan_knowledge_base(id) ON DELETE CASCADE,
    FOREIGN KEY (dimension_id) REFERENCES product_dimension_config(id) ON DELETE CASCADE
);
```

### 2.4 dan_knowledge_tag（标签表）

```sql
CREATE TABLE dan_knowledge_tag (
    id       BIGINT PRIMARY KEY AUTO_INCREMENT,
    tag_name VARCHAR(100) NOT NULL UNIQUE COMMENT '标签名',
    tag_type VARCHAR(50) DEFAULT 'custom' COMMENT '标签类型: custom/auto',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### 2.5 dan_knowledge_base_tag（知识-标签关联表）

```sql
CREATE TABLE dan_knowledge_base_tag (
    id           BIGINT PRIMARY KEY AUTO_INCREMENT,
    knowledge_id BIGINT NOT NULL,
    tag_id       BIGINT NOT NULL,
    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_knowledge_tag (knowledge_id, tag_id),
    FOREIGN KEY (knowledge_id) REFERENCES dan_knowledge_base(id) ON DELETE CASCADE,
    FOREIGN KEY (tag_id) REFERENCES dan_knowledge_tag(id) ON DELETE CASCADE
);
```

---

## 3. Dify 同步设计

### 3.1 Dify 配置

```yaml
# application.yml
dify:
  base-url: http://dify.bianwoyou.cn
  api-key: ${DIFY_API_KEY:}
  timeout: 10000
```

### 3.2 同步时机

| 事件 | Dify 操作 | API |
|------|-----------|-----|
| 知识点新增且已关联维度 | 创建文档 | `POST /v1/datasets/{dataset_id}/documents` |
| 知识点编辑 | 更新文档（如 Dify 支持按 doc_id 更新） | `PUT /v1/datasets/{dataset_id}/documents/{doc_id}` |
| 知识点删除 | 删除文档 | `DELETE /v1/datasets/{dataset_id}/documents/{doc_id}` |
| 维度解绑 | 从 dataset 中移除文档 | 同上 |

**推送规则：**
- 知识点关联了多个维度 → 同时推送到多个 Dify dataset
- 维度未配置 `dify_dataset_id` → 跳过 Dify 同步，不报错
- Dify 调用失败 → 记录 error log，知识库 CRUD 本身不失败（Dify 同步是异步的，不阻塞主流程）

### 3.3 Dify 文档创建请求格式

根据 Dify 标准知识库 API：

```json
POST http://dify.bianwoyou.cn/v1/datasets/{dataset_id}/documents
Headers: Authorization: Bearer {api_key}
Body: {
  "indexing_technique": "high_quality",
  "process_rule": {
    "rules": [],
    "mode": "custom",
    "order": 3
  },
  "doc_form": "text_raw",
  "doc_language": "Chinese",
  "data_source": {
    "type": "upload_file",
    "upload_file_id": "{{file_id}}"  // 如用文件方式
  },
  "primary_web": {
    "site_url": "",
    "og_image_selector": ""
  }
}
```

**本系统采用文本方式直接创建文档：**

```json
POST http://dify.bianwoyou.cn/v1/datasets/{dataset_id}/documents
Headers: Authorization: Bearer {api_key}
Body: {
  "indexing_technique": "high_quality",
  "process_rule": {
    "rules": [],
    "mode": "custom",
    "order": 3
  },
  "doc_form": "text_raw",
  "doc_language": "Chinese"
}
```

> 注：完整 Dify API 格式以 Dify 官方文档为准，实现时使用 `@Value("${dify.base-url}")` + RestTemplate 调用，API 格式留占位符待 Dify 接入时补充。

### 3.4 Dify 同步 Service

```java
@Service
public class DifySyncService {

    @Value("${dify.base-url}")
    private String difyBaseUrl;

    @Value("${dify.api-key}")
    private String difyApiKey;

    // 推送知识点到 Dify（异步，不阻塞主流程）
    @Async
    public void syncToDify(KnowledgeBase knowledge, List<String> dimensionCodes) {
        // 1. 查找每个维度对应的 dify_dataset_id
        // 2. 调用 Dify API 创建文档
        // 3. 失败记录 error log，不抛异常
    }

    // 从 Dify 删除
    @Async
    public void removeFromDify(Long knowledgeId, String difyDatasetId) { ... }
}
```

---

## 4. 后端 API 设计

### 4.1 维度配置 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/admin/dimension-config/list` | POST | 分页列表，`{dimensionType, enabled}` 筛选 |
| `/api/admin/dimension-config/get` | POST | 详情 `{id}` |
| `/api/admin/dimension-config/save` | POST | 新增/更新，body 包含所有字段 |
| `/api/admin/dimension-config/delete` | POST | 删除 `{id}` |
| `/api/admin/dimension-config/tree` | POST | 树形结构（parent_id 层级） |

### 4.2 知识库 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/admin/knowledge-base/list` | POST | 分页 `{dimensionCode, tagId, keyword, page, size}` |
| `/api/admin/knowledge-base/get` | POST | 详情 `{id}`，返回知识点 + 关联维度列表 + 关联标签列表 |
| `/api/admin/knowledge-base/save` | POST | 新增/更新，body 含 `dimensionIds[]`，同步更新关联表 |
| `/api/admin/knowledge-base/delete` | POST | 删除 `{id}`，级联删除关联记录 |
| `/api/admin/knowledge-base/bind-dimensions` | POST | 绑定维度 `{knowledgeId, dimensionIds[]}` |
| `/api/admin/knowledge-base/bind-tags` | POST | 绑定标签 `{knowledgeId, tagIds[]}` |

### 4.3 标签 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/admin/knowledge-tag/list` | POST | 标签列表，无分页 |
| `/api/admin/knowledge-tag/save` | POST | 新增/更新标签 |
| `/api/admin/knowledge-tag/delete` | POST | 删除 `{id}`，级联删除关联记录 |

---

## 5. 前端设计

### 5.1 目录结构

```
cfc-web/src/
├── api/
│   └── dimension.js           # 维度配置 + 知识库 + 标签 API 封装
├── store/
│   └── modules/
│       └── dimension.js       # Vuex store（dimensions, dimensionTree, knowledgeList, tags）
├── components/
│   ├── DimensionSelector/     # 维度下拉选择器
│   ├── KnowledgeTable/         # 知识库动态表格
│   ├── KnowledgeDialog/        # 新增/编辑对话框
│   └── TagSelector/            # 标签多选组件
└── views/admin/
    ├── dimension/              # 维度配置管理页（空目录待创建）
    └── knowledge/              # 知识库管理页（空目录待创建）
```

### 5.2 组件规格

**DimensionSelector** — `el-select`，支持多选（`:multiple`），按 `dimensionType` 过滤选项，数据来自 Vuex store

**KnowledgeTable** — `el-table`，根据传入 `dimensionCode` 或 `tagId` 动态加载，支持排序、分页

**KnowledgeDialog** — `el-dialog`，新增/编辑共用，包含：
- 维度多选（`DimensionSelector`）
- 标签多选（`TagSelector`）
- 标题、内容、排序、状态表单字段

**TagSelector** — `el-select` + `el-tag`，支持新增标签（`@new-tag`）

### 5.3 页面

**维度配置管理页** `cfc-web/src/views/admin/dimension/index.vue`
- 树形列表展示维度层级（`el-tree`）
- 新增/编辑维度弹窗（含 `dify_dataset_id` 字段）
- 支持拖拽排序

**知识库管理页** `cfc-web/src/views/admin/knowledge/index.vue`
- 左侧：维度树 + 标签列表（筛选面板）
- 右侧：知识点表格（分页）
- 顶部：搜索框 + 新增按钮
- 行内：编辑/删除/绑定维度/绑定标签

---

## 6. 实现顺序

```
Phase 1: 后端基础设施
  Task 1: 创建 5 张数据库表
  Task 2: 创建 Entity + Mapper
  Task 3: 创建 DimensionConfig CRUD Controller + Service
  Task 4: 创建 KnowledgeBase CRUD Controller + Service（不含 Dify 同步）
  Task 5: 创建 KnowledgeTag CRUD Controller + Service
  Task 6: 创建 KnowledgeBase 与 Dimension/Tag 的关联管理
  Task 7: DifySyncService（异步推送，配置占位符）

Phase 2: 前端核心
  Task 8: api/dimension.js API 封装
  Task 9: store/modules/dimension.js Vuex 模块
  Task 10: DimensionSelector 组件
  Task 11: TagSelector 组件
  Task 12: KnowledgeTable 组件
  Task 13: KnowledgeDialog 组件

Phase 3: 管理页面
  Task 14: 维度配置管理页（dimension/index.vue）
  Task 15: 知识库管理页（knowledge/index.vue）

Phase 4: Dify 集成
  Task 16: 补充 Dify API 格式（以 Dify 官方文档为准）
  Task 17: 全流程联调
```

---

## 7. 验收标准

- [ ] 维度配置增删改查正常，树形展示正确
- [ ] 知识点增删改查正常，支持按维度/标签筛选
- [ ] 知识点与多维度关联保存正确（一个知识点可属多个维度）
- [ ] 知识点与多标签关联保存正确
- [ ] Dify 同步为异步，不影响知识库 CRUD 响应速度
- [ ] Dify 同步失败时知识库操作本身不报错
- [ ] 新增维度后前端无需修改代码即可展示
- [ ] 无硬编码维度名称（grep 验证）