wangdl/api-server
2
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

M3-04 Workspace Experience Module #32

New Issue
Closed
opened 2026-05-22 21:09:50 +08:00 by wangdl · 1 comment
wangdl commented 2026-05-22 21:09:50 +08:00
Owner
Copy Link

目标

设计知习工作空间体验模块，为 C 端 Web 和 iOS 提供最近打开、收藏、标签、搜索和工作台聚合数据能力。

背景说明

随着用户知识库和学习内容的增长，需要快速找到最近使用的知识库、收藏的知识点、通过标签和搜索定位内容。Workspace Experience 模块提供这些"体验增强"功能，支撑 Web 工作台和 iOS 快速入口。

它不涉及核心学习逻辑，但直接影响用户的日常使用体验。

模块职责

  1. 本模块负责：

    • 最近打开记录（知识库/知识点/学习会话/对话）
    • 收藏功能（知识库/知识点/资料）
    • 标签管理（CRUD + 关联 KnowledgeItem/Material）
    • 全局搜索（跨知识库搜索，基于 MySQL 全文索引或 Qdrant）
    • 工作台聚合数据（今日待复习数、本周学习时长、最近知识库等）

  2. 本模块不负责：

    • 知识库管理（走 Workspace & KnowledgeBase）
    • 学习引擎（走 Learning Engine）
    • 知识点管理（走 Artifact & KnowledgeItem）

候选数据对象

  • RecentItem（最近打开）
  • Favorite（收藏）
  • Tag（标签）
  • KnowledgeItemTag（知识点-标签关联）
  • WorkspaceDashboard（工作台聚合数据）
  • SearchHistory（搜索历史）

基础设施依赖判断

  • MySQL：是（最近记录、收藏、标签）
  • Redis：是（Dashboard 缓存、热门标签缓存）
  • BullMQ：否
  • Qdrant：需判断（全局搜索是否走 Qdrant 语义搜索）
  • AI Gateway：否
  • Content Safety：是（标签名称需要审核）

API 设计

  1. CAPI：
    • 最近打开列表
    • 收藏/取消收藏
    • 收藏列表
    • 标签 CRUD + 关联管理
    • 全局搜索
    • 工作台聚合数据

Domain Event 设计

  • ItemFavorited / ItemUnfavorited
  • TagCreated / TagDeleted
  • SearchPerformed

交付检查

  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：是
  • 是否需要 Qdrant：否（当前阶段使用 MySQL LIKE 搜索）
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：是
  • 是否需要 Cost 记录：否
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：否
  • 是否需要 E2E/集成测试：是

验收标准

  1. RecentItem / Favorite / Tag Prisma schema
  2. 最近打开记录策略（记录哪些类型、保留多少条）
  3. 收藏功能设计
  4. 标签系统设计
  5. 全局搜索方案设计（MySQL 全文索引或 Qdrant，请判断）
  6. 工作台聚合数据接口设计
  7. 集成测试覆盖搜索和收藏流程

禁止事项

  • 禁止搜索功能跨用户泄露数据
  • 禁止标签名称不经过 Content Safety
  • 禁止 Dashboard 数据实时计算（应缓存）

不建议当前阶段实现

  • 高级搜索筛选（按日期/类型/知识库多条件组合）
  • 搜索建议和自动补全
  • 标签推荐和自动标签
  • 知识图谱可视化
## 目标 设计知习工作空间体验模块，为 C 端 Web 和 iOS 提供最近打开、收藏、标签、搜索和工作台聚合数据能力。 ## 背景说明 随着用户知识库和学习内容的增长，需要快速找到最近使用的知识库、收藏的知识点、通过标签和搜索定位内容。Workspace Experience 模块提供这些"体验增强"功能，支撑 Web 工作台和 iOS 快速入口。 它不涉及核心学习逻辑，但直接影响用户的日常使用体验。 ## 模块职责 1. 本模块负责： - 最近打开记录（知识库/知识点/学习会话/对话） - 收藏功能（知识库/知识点/资料） - 标签管理（CRUD + 关联 KnowledgeItem/Material） - 全局搜索（跨知识库搜索，基于 MySQL 全文索引或 Qdrant） - 工作台聚合数据（今日待复习数、本周学习时长、最近知识库等） 2. 本模块不负责： - 知识库管理（走 Workspace & KnowledgeBase） - 学习引擎（走 Learning Engine） - 知识点管理（走 Artifact & KnowledgeItem） ## 候选数据对象 - RecentItem（最近打开） - Favorite（收藏） - Tag（标签） - KnowledgeItemTag（知识点-标签关联） - WorkspaceDashboard（工作台聚合数据） - SearchHistory（搜索历史） ## 基础设施依赖判断 - MySQL：是（最近记录、收藏、标签） - Redis：是（Dashboard 缓存、热门标签缓存） - BullMQ：否 - Qdrant：需判断（全局搜索是否走 Qdrant 语义搜索） - AI Gateway：否 - Content Safety：是（标签名称需要审核） ## API 设计 1. CAPI： - 最近打开列表 - 收藏/取消收藏 - 收藏列表 - 标签 CRUD + 关联管理 - 全局搜索 - 工作台聚合数据 ## Domain Event 设计 - ItemFavorited / ItemUnfavorited - TagCreated / TagDeleted - SearchPerformed ## 交付检查 - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：是 - [x] 是否需要 Qdrant：否（当前阶段使用 MySQL LIKE 搜索） - [x] 是否需要 AI Gateway：否 - [x] 是否需要 Content Safety：是 - [x] 是否需要 Cost 记录：否 - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：否 - [x] 是否需要 E2E/集成测试：是 ## 验收标准 1. RecentItem / Favorite / Tag Prisma schema 2. 最近打开记录策略（记录哪些类型、保留多少条） 3. 收藏功能设计 4. 标签系统设计 5. 全局搜索方案设计（MySQL 全文索引或 Qdrant，请判断） 6. 工作台聚合数据接口设计 7. 集成测试覆盖搜索和收藏流程 ## 禁止事项 - 禁止搜索功能跨用户泄露数据 - 禁止标签名称不经过 Content Safety - 禁止 Dashboard 数据实时计算（应缓存） ## 不建议当前阶段实现 - 高级搜索筛选（按日期/类型/知识库多条件组合） - 搜索建议和自动补全 - 标签推荐和自动标签 - 知识图谱可视化
wangdl added this to the M3：学习复习闭环（P2） milestone 2026-05-22 21:09:50 +08:00
wangdl self-assigned this 2026-05-22 21:09:50 +08:00
wangdl commented 2026-05-24 14:43:52 +08:00
Author
Owner
Copy Link

✅ M3-04 实施完成

交付内容

模块 说明
WorkspaceModule 工作空间体验模块，含 14 个 CAPI 端点
WorkspaceService 业务逻辑：Content Safety 标签审核 + EventBus 事件发布 + Redis Dashboard 缓存
WorkspaceRepository 数据访问：RecentItem/Favorite/Tag/SearchHistory/Search/Dashboard

Prisma 新增模型

模型 说明
RecentItem 最近打开记录（targetType+targetId，上限 50 条，自动淘汰）
Favorite 收藏（userId+targetType+targetId 唯一约束）
SearchHistory 搜索历史（上限 20 条）

Tag 系统

  • 复用已有 Tag + KnowledgeItemTag 模型
  • Tag CRUD 完整实现（创建/更新/删除/列表）
  • 贴标签/去标签（attach/detach）
  • 查看知识点标签
  • 标签名经过 ContentSafetyService 审核

领域事件（5 个）

ItemFavorited → 收藏项目时发布
ItemUnfavorited → 取消收藏时发布
TagCreated → 创建标签时发布
TagDeleted → 删除标签时发布
SearchPerformed → 执行搜索时发布

API 端点

端点 方法 说明
/api/workspace/recent GET 最近打开列表
/api/workspace/recent POST 记录最近打开
/api/workspace/favorites GET 收藏列表
/api/workspace/favorites POST 添加收藏
/api/workspace/favorites/:id DELETE 取消收藏
/api/workspace/tags GET 标签列表
/api/workspace/tags POST 创建标签
/api/workspace/tags/:id PATCH 更新标签
/api/workspace/tags/:id DELETE 删除标签
/api/workspace/tags/:id/attach POST 贴标签
/api/workspace/tags/:id/detach DELETE 去标签
/api/workspace/items/:itemId/tags GET 查看知识点标签
/api/workspace/search?q= GET 全局搜索（MySQL LIKE）
/api/workspace/search-history GET 搜索历史
/api/workspace/dashboard GET 工作台聚合数据（Redis 缓存 5min）

搜索方案

当前阶段使用 MySQL LIKE 搜索 KnowledgeBase 标题和 KnowledgeItem 标题/内容。后续可通过 Qdrant 语义搜索增强。

Dashboard 缓存策略

Dashboard 数据包含：今日待复习数、本周学习时长、最近知识库列表。通过 Redis 缓存（TTL 300s），避免每次请求实时计算。

E2E（test/m3.e2e-spec.ts）

10 tests covering: recent listing/recording, favorites add/list, tags list/create, search, search history, dashboard, and 401 auth checks.

npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts  # 18 passed, 1 pre-existing failure
## ✅ M3-04 实施完成 ### 交付内容 | 模块 | 说明 | |------|------| | `WorkspaceModule` | 工作空间体验模块，含 14 个 CAPI 端点 | | `WorkspaceService` | 业务逻辑：Content Safety 标签审核 + EventBus 事件发布 + Redis Dashboard 缓存 | | `WorkspaceRepository` | 数据访问：RecentItem/Favorite/Tag/SearchHistory/Search/Dashboard | ### Prisma 新增模型 | 模型 | 说明 | |------|------| | `RecentItem` | 最近打开记录（targetType+targetId，上限 50 条，自动淘汰） | | `Favorite` | 收藏（userId+targetType+targetId 唯一约束） | | `SearchHistory` | 搜索历史（上限 20 条） | ### Tag 系统 - 复用已有 `Tag` + `KnowledgeItemTag` 模型 - Tag CRUD 完整实现（创建/更新/删除/列表） - 贴标签/去标签（attach/detach） - 查看知识点标签 - 标签名经过 ContentSafetyService 审核 ### 领域事件（5 个） ``` ItemFavorited → 收藏项目时发布 ItemUnfavorited → 取消收藏时发布 TagCreated → 创建标签时发布 TagDeleted → 删除标签时发布 SearchPerformed → 执行搜索时发布 ``` ### API 端点 | 端点 | 方法 | 说明 | |------|------|------| | `/api/workspace/recent` | GET | 最近打开列表 | | `/api/workspace/recent` | POST | 记录最近打开 | | `/api/workspace/favorites` | GET | 收藏列表 | | `/api/workspace/favorites` | POST | 添加收藏 | | `/api/workspace/favorites/:id` | DELETE | 取消收藏 | | `/api/workspace/tags` | GET | 标签列表 | | `/api/workspace/tags` | POST | 创建标签 | | `/api/workspace/tags/:id` | PATCH | 更新标签 | | `/api/workspace/tags/:id` | DELETE | 删除标签 | | `/api/workspace/tags/:id/attach` | POST | 贴标签 | | `/api/workspace/tags/:id/detach` | DELETE | 去标签 | | `/api/workspace/items/:itemId/tags` | GET | 查看知识点标签 | | `/api/workspace/search?q=` | GET | 全局搜索（MySQL LIKE） | | `/api/workspace/search-history` | GET | 搜索历史 | | `/api/workspace/dashboard` | GET | 工作台聚合数据（Redis 缓存 5min） | ### 搜索方案 当前阶段使用 MySQL LIKE 搜索 KnowledgeBase 标题和 KnowledgeItem 标题/内容。后续可通过 Qdrant 语义搜索增强。 ### Dashboard 缓存策略 Dashboard 数据包含：今日待复习数、本周学习时长、最近知识库列表。通过 Redis 缓存（TTL 300s），避免每次请求实时计算。 ### E2E（test/m3.e2e-spec.ts） 10 tests covering: recent listing/recording, favorites add/list, tags list/create, search, search history, dashboard, and 401 auth checks. ```bash npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts # 18 passed, 1 pre-existing failure ```
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M3：学习复习闭环（P2）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#32
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?