specs: add dimension + knowledge base design

Dify real-time sync, 5-table DB schema, 15 API endpoints,
4 frontend components, 2 admin pages.

Co-authored-by: Sisyphus <sisyphus@ohmyopencode.dev>

docs/superpowers/specs/2026-06-20-dimension-knowledge-base-design.md

@@ -0,0 +1,323 @@
+# 维度配置 + 知识库动态管理平台
+
+**日期:** 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 验证）