CherryHQ-cherry-studio/v2-refactor-temp/docs/knowledge/knowledge-structure-change-list.md

Knowledge 待修改数据结构清单

本文档用于记录 Knowledge V2 还需要修改的数据结构项。

只记录已经确认的结构性调整，不记录未确认的 UI 推断或实现细节。

已确认

1. 复用 groupTable，为 knowledge_base 增加 groupId

结论

• 不新增独立的 knowledge_group 表。
• 复用现有 src/main/data/db/schemas/group.ts 中的 groupTable。
• 在 knowledge_base 上增加 groupId 字段，关联到 groupTable.id。
• 如果上层为 Knowledge 创建专用分组，group.entityType 约定使用：
  • 建议值：knowledge_base
• 当前 KnowledgeBaseService 不额外强校验 entityType，行为与现有 topic.groupId 一致。

目的

• 支撑 Knowledge V2 左侧知识库列表的分组组织能力。
• 让知识库分组成为业务数据，而不是 renderer 本地 mock 字段。
• 避免误用 knowledge_item.groupId：
  • knowledge_item.groupId 的语义仍然是 item 级来源/容器分组
  • 不能复用于知识库导航分组

需要修改的结构

1. SQLite Schema

   • src/main/data/db/schemas/knowledge.ts
   • 在 knowledgeBaseTable 上新增：
     • groupId: text().references(() => groupTable.id, { onDelete: 'set null' })

2. Shared Data Types / API Schema

   • src/shared/data/types/knowledge.*
   • src/shared/data/api/schemas/knowledges.ts
   • 需要让 KnowledgeBase、CreateKnowledgeBaseDto、UpdateKnowledgeBaseDto 支持 groupId

3. Data Service / Handler 约束

   • KnowledgeBaseService
   • knowledge 相关 handler
   • 保持与 topic.groupId 一致：
     • service 层不额外增加 groupId / entityType 业务校验
     • create / update 对 groupId 直接透传，不做 trim 或空值归一化
     • 由 SQLite 外键约束负责引用完整性

4. Migration / 兼容策略

   • 旧知识库数据当前没有 groupId
   • 迁移阶段允许先写入 null
   • 是否补默认分组，后续单独确认

当前不做

• 不新增 knowledge_group 表
• 不把 knowledge_item.groupId 改造成知识库分组字段
• 不做多级分组
• 不做 group 专属额外字段：
  • 如 icon
  • color
  • isDefault
  • parentId

影响范围

• knowledge_base 主数据结构
• knowledge base DataApi 输入输出契约
• 后续 renderer 左侧分组列表的数据来源

2. 暂不为 knowledge_base 持久化图标字段

结论

• 当前不在 knowledge_base 上持久化 emoji 或 icon 字段。
• 未来知识库会支持自定义图标，但具体结构尚未确定；等图标模型确定后再补数据字段。
• 当前知识库页面的固定图标只作为 UI 展示资产存在，不进入 DataApi / SQLite 主数据结构。

目的

• 避免在 V2 开发阶段引入很快会被自定义图标替换的临时数据字段。
• 保持知识库主数据只包含当前已经确定的业务属性。

需要修改的结构

1. SQLite Schema

   • src/main/data/db/schemas/knowledge.ts
   • knowledgeBaseTable 不包含 emoji / icon 字段。

2. Shared Data Types / API Schema

   • src/shared/data/types/knowledge.ts
   • src/shared/data/api/schemas/knowledges.ts
   • KnowledgeBase、CreateKnowledgeBaseDto、UpdateKnowledgeBaseDto 不暴露知识库图标字段。

3. Data Service / Handler 约束

   • KnowledgeBaseService
   • knowledge 相关 handler
   • 不接收、不生成、不返回知识库图标字段。

4. Migration / 兼容策略

   • V2 开发阶段不保留知识库 emoji 兼容逻辑。

当前不做

• 不新增 emoji
• 不新增 icon
• 不新增 iconType
• 不新增 iconUrl
• 不新增 cover
• 不新增 separatorRule

影响范围

• knowledge_base 主数据结构
• knowledge base DataApi 输入输出契约
• renderer 中知识库列表与详情头部的持久化图标数据来源

待补充

• 后续新的结构调整项继续按同样格式追加到本文档