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

日期: 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（维度配置表）

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（知识库表）

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（维度关联表）

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（标签表）

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（知识-标签关联表）

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 配置

# 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：

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": ""
  }
}

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

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

@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 验证）

2026-06-20-dimension-knowledge-base-design.md 11 KB 履歴 Raw