SourceMind—02-SAD-软件架构设计说明书

作者
Post Views: 5

1. 架构设计哲学

1.1 核心设计原则

原则说明
事件驱动 (Event-Driven)所有业务流程通过事件异步驱动，服务间解耦
流水线化 (Pipeline)复杂业务编排为可观察的 Pipeline 阶段
知识资产化知识图谱作为一等公民，支持版本、共享、复制
数据隔离多租户架构，知识数据与用户学习数据物理分离
可演化新功能通过监听现有事件扩展，无需修改核心代码

1.2 架构风格

采用 Event-Driven Architecture + CQRS + Modular Monolith（初期）/ Microservices（未来） 。

2. 系统上下文

┌─────────────────────────────────────────────────────┐
│                    用户/浏览器                        │
└─────────────────┬───────────────────────┬───────────┘
                  │ HTTP/WS               │ SSE
                  ▼                       ▼
┌──────────────────────────────────────────────────────┐
│                API Gateway / BFF                       │
│              (认证、限流、路由)                          │
└─────────┬─────────────────────────────┬──────────────┘
          │                             │
          ▼                             ▼
┌──────────────────┐    ┌──────────────────────────────┐
│   REST API       │    │   Event Bus (Message Queue)    │
│  (同步操作)       │    │  (异步事件驱动)                  │
└──────┬───────────┘    └──────────┬───────────────────┘
       │                           │
       ▼                           ▼
┌──────────────────────────────────────────────────────┐
│                   Service Layer                        │
│   ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐  │
│   │Works- │ │Proje-│ │Knowl-│ │Learn-│ │Pipeline  │  │
│   │pace   │ │ct    │ │edge  │ │Journ-│ │Engine    │  │
│   │Service│ │Service│ │Graph │ │ey    │ │          │  │
│   │       │ │      │ │Service│ │Service│ │          │  │
│   └──────┘ └──────┘ └──────┘ └──────┘ └──────────┘  │
└──────────────────────────────────────────────────────┘
       │                                               │
       ▼                                               ▼
┌──────────────────┐                    ┌──────────────────┐
│   PostgreSQL     │                    │   Vector DB      │
│  (业务数据、事件)  │                    │  (知识检索)       │
└──────────────────┘                    └──────────────────┘

3. 核心架构：事件驱动流水线

3.1 领域事件定义

┌─────────────────────────────────────────┐
│              领域事件流                    │
├─────────────────────────────────────────┤
│ Project.Created                         │
│ Document.Uploaded                       │
│ Document.Parsed                         │
│ Knowledge.Extracted                     │
│ Knowledge.Merged                        │
│ KnowledgeDependency.Inferred            │
│ KnowledgeGraph.Built                    │
│ Assessment.Generated                    │
│ LearningPath.Generated                  │
│ Project.Updated (资料变更 → 新版本)       │
│ Project.Shared                          │
│ Project.Copied                          │
└─────────────────────────────────────────┘
每个事件包含： 
{
  "eventId": "uuid",
  "eventType": "Knowledge.Extracted",
  "timestamp": "2026-07-30T12:00:00Z",
  "source": "project-service",
  "data": {
    "projectId": "uuid",
    "pipelineId": "uuid",
    "stageId": "knowledge-extraction",
    "payload": { ... }
  }
}

3.2 Pipeline 状态机

每个 Pipeline 实例的状态机： 
PENDING → PROCESSING → COMPLETED
                  ↘ FAILED → RETRYING → PROCESSING
状态详情：
状态说明可转换到
PENDING等待处理PROCESSING
PROCESSING正在处理中COMPLETED, FAILED
COMPLETED处理成功– (终态)
FAILED处理失败RETRYING
RETRYING重试中PROCESSING, FAILED

3.3 Pipeline 阶段编排

Pipeline 定义（可配置）:
  stages:
    - name: document-parse
      handler: DocumentParseHandler
      timeout: 120s
      retry: 3
    - name: ocr
      handler: OCRHandler
      timeout: 300s
      retry: 2
      depends_on: [document-parse]
    - name: image-understanding
      handler: ImageUnderstandingHandler
      timeout: 300s
      retry: 2
      depends_on: [document-parse]
    - name: knowledge-extraction
      handler: KnowledgeExtractionHandler
      timeout: 600s
      retry: 3
      depends_on: [ocr, image-understanding]
    - name: knowledge-merging
      handler: KnowledgeMergingHandler
      timeout: 120s
      retry: 2
      depends_on: [knowledge-extraction]
    - name: dependency-inference
      handler: DependencyInferenceHandler
      timeout: 300s
      retry: 2
      depends_on: [knowledge-merging]
    - name: graph-building
      handler: GraphBuildingHandler
      timeout: 60s
      retry: 2
      depends_on: [dependency-inference]
    - name: assessment-generation
      handler: AssessmentGenerationHandler
      timeout: 300s
      retry: 2
      depends_on: [graph-building]
    - name: learning-path-generation
      handler: LearningPathGenerationHandler
      timeout: 120s
      retry: 2
      depends_on: [assessment-generation]

4. 分层架构详情

4.1 表现层 (Frontend)

技术用途
React / Next.js前端框架
D3.js / Cytoscape.js知识图谱可视化
SSE (Server-Sent Events)实时接收 Pipeline 状态更新

4.2 API 网关层

功能说明
身份认证JWT Token 鉴权
路由转发请求分发到对应服务
限流接口级限流保护
SSE 端点为前端提供实时事件推送

4.3 服务层

4.3.1 WorkspaceService

职责说明
租户管理Tenant 的创建、配置
工作区 CRUDWorkspace 的创建、更新、删除
成员管理工作区成员的邀请与角色管理
资源配额工作区存储、项目数限制

4.3.2 ProjectService

职责说明
项目 CRUD学习项目的创建、更新、删除
资料管理上传/删除/关联学习资料
版本管理资料变更时创建新版本
共享管理生成分享链接、处理复制请求
发布事件在关键节点发布领域事件

4.3.3 PipelineEngine

职责说明
Pipeline 编排按 DAG 定义执行流水线各阶段
状态管理维护每个 Pipeline 实例的状态
重试机制失败阶段自动重试（可配置次数）
进度推送通过 EventBus 向外推送进度事件
Handler 注册可插拔的 Handler 管理器

4.3.4 KnowledgeGraphService

职责说明
三层图谱管理Global / Project / User 三层知识图谱
节点 CRUD知识节点的增删改查
关系管理知识节点间关系（前置、后继、包含、关联、对比）
图谱搜索语义搜索知识节点
公共知识库管理 Global Knowledge Graph

4.3.5 LearningJourneyService

职责说明
能力评估根据知识图谱生成评估试题并判定掌握程度
知识缺口分析对比目标和当前掌握度，定位薄弱环节
学习路线生成基于知识依赖关系和用户水平生成个性化路线
学习记录追踪用户学习行为和数据
答题引擎评估题目生成、答案判定、错题记录

4.3.6 各 Handler（Pipeline 阶段执行器）

Handler输入输出
DocumentParseHandler原始文件结构化文本
OCRHandler图片/扫描 PDF识别文本
ImageUnderstandingHandler文档图片图片描述文本
KnowledgeExtractionHandler结构化文本知识点列表
KnowledgeMergingHandler知识点列表去重合并后的知识点
DependencyInferenceHandler知识点带依赖关系的知识网络
GraphBuildingHandler知识网络序列化的知识图谱
AssessmentGenerationHandler知识图谱评估试题集
LearningPathGenerationHandler评估结果 + 知识图谱个性化学习路径

4.4 基础设施层

组件选型方向用途
消息队列RabbitMQ / Redis StreamEventBus 实现
主数据库PostgreSQL业务数据、事件存储
向量数据库pgvector / Milvus知识向量化存储和语义检索
对象存储MinIO / S3文档、图片等文件存储
缓存RedisPipeline 状态缓存、热点数据
AI 服务OpenAI API / 本地 LLM知识抽取、评估生成等 AI 任务

5. 三层知识图谱设计

5.1 L1: Global Knowledge Graph (公共)

特性:
  - 全平台唯一
  - 由系统维护或经审核的用户贡献
  - 包含通用知识: "Promise"、"EventLoop"、"CPU"、"React"
  - 所有用户可读

存储:
  表: global_knowledge_nodes
  表: global_knowledge_relations

5.2 L2: Project Graph (项目)

特性:
  - 每个 Project 独立
  - 从项目资料自动提取生成
  - 可以被分享和复制
  - 随资料增加持续演化

存储:
  表: project_knowledge_nodes
  表: project_knowledge_relations

关联策略:
  节点可以通过 reference_id 关联到 Global 节点
  如: Project 中的 "Fiber" 可关联到 Global 中的 "React"

5.3 L3: User Graph (用户)

特性:
  - 记录用户对每个知识点的掌握状态
  - 属于个人，不可分享
  - 随着学习和评估不断更新

存储:
  表: user_knowledge_states

字段:
  - user_id
  - node_id (关联到 Project 或 Global 节点)
  - node_type (project | global)
  - mastery_level (0~100)
  - confidence (0~1)
  - last_reviewed_at
  - review_count

6. 数据隔离方案

6.1 多租户层次

Tenant (租户)
  └── User (用户)
       └── Workspace (工作区)
            ├── Project → Knowledge Graph
            ├── Project → Knowledge Graph
            └── Learning Journey

6.2 隔离策略

数据隔离级别说明
Workspace 数据Tenant 级别不同租户完全隔离
Project 数据Workspace 级别同一 Workspace 内共享
User 学习数据User 级别仅用户本人可见
Global 知识全平台所有用户只读

6.3 数据归属策略

知识节点和学习状态分离:

User A 的知识图谱:
  - 节点: "EventLoop" (引用 Global 节点)
  - 掌握度: 80% (UserKnowledge 表中)

User B 的知识图谱:
  - 节点: "EventLoop" (引用同一 Global 节点)
  - 掌握度: 45% (UserKnowledge 表中)

优势:
  - "EventLoop" 节点只存一次
  - 一万个用户也不会存一万个 "EventLoop"
  - 每个用户只存自己的学习状态

7. 版本管理设计

7.1 版本创建触发条件

Project 资料变更时:
  - 新增 PDF/文档
  - 删除文档
  - 更新文档

触发动作:
  1. 创建 ProjectVersion
  2. 启动新 Pipeline
  3. 完成后生成新版本的知识图谱
  4. 记录版本 Diff

7.2 版本结构

{
  "versionId": "uuid",
  "projectId": "uuid",
  "versionNumber": 3,
  "snapshot": {
    "graphId": "uuid",
    "nodeCount": 234,
    "relationCount": 567
  },
  "diff": {
    "addedNodes": [...],
    "removedNodes": [...],
    "modifiedNodes": [...]
  },
  "createdAt": "2026-07-30T12:00:00Z",
  "sourceDocuments": ["doc1", "doc2"]
}

7.3 版本对比

用户可对比任意两个版本的差异，系统展示：
  • 新增 的知识节点（绿色标记）
  • 移除 的知识节点（红色标记）
  • 变更 的知识节点（黄色标记）

8. API 设计

8.1 设计原则

  • RESTful + Event-driven
  • 同步 API 用于 CRUD 操作
  • 异步 Pipeline 通过 SSE 推送进度
  • 统一响应格式

8.2 核心 API 端点

# Workspace 管理
GET    /api/v1/workspaces                        # 获取工作区列表
POST   /api/v1/workspaces                        # 创建工作区
GET    /api/v1/workspaces/{workspaceId}           # 获取工作区详情
PUT    /api/v1/workspaces/{workspaceId}           # 更新工作区
DELETE /api/v1/workspaces/{workspaceId}           # 删除工作区

# Project 管理
GET    /api/v1/workspaces/{wsId}/projects              # 项目列表
POST   /api/v1/workspaces/{wsId}/projects              # 创建项目
GET    /api/v1/workspaces/{wsId}/projects/{projectId}  # 项目详情
PUT    /api/v1/workspaces/{wsId}/projects/{projectId}  # 更新项目
DELETE /api/v1/workspaces/{wsId}/projects/{projectId}  # 删除项目
POST   /api/v1/workspaces/{wsId}/projects/{projectId}/share    # 分享
POST   /api/v1/workspaces/{wsId}/projects/{projectId}/copy     # 复制

# 资料管理
POST   /api/v1/projects/{projectId}/documents         # 上传资料
DELETE /api/v1/projects/{projectId}/documents/{docId}  # 删除资料
GET    /api/v1/projects/{projectId}/documents          # 资料列表

# Pipeline 管理
GET    /api/v1/projects/{projectId}/pipeline            # 获取 Pipeline 状态
GET    /api/v1/projects/{projectId}/pipeline/events     # SSE: 实时推送进度

# 知识图谱
GET    /api/v1/projects/{projectId}/graph               # 获取项目图谱
GET    /api/v1/projects/{projectId}/graph/node/{nodeId} # 节点详情
GET    /api/v1/global-graph                             # 公共知识图谱
GET    /api/v1/users/{userId}/graph                     # 用户知识状态

# 学习旅程
GET    /api/v1/projects/{projectId}/learning-path        # 获取学习路线
POST   /api/v1/projects/{projectId}/assessment           # 启动能力评估
GET    /api/v1/projects/{projectId}/assessment/{id}      # 评估结果
POST   /api/v1/projects/{projectId}/quiz                 # 提交答题
GET    /api/v1/users/{userId}/learning-records           # 学习记录

# 版本管理
GET    /api/v1/projects/{projectId}/versions              # 版本列表
GET    /api/v1/projects/{projectId}/versions/{vId}        # 版本详情
GET    /api/v1/projects/{projectId}/versions/{vId}/diff   # 版本对比

9. 错误处理策略

错误类型处理方式HTTP 状态码
请求参数校验失败返回校验错误详情400
资源不存在返回 404404
权限不足–403
Pipeline 阶段错误记录错误 → 自动重试 → 通知用户202 (异步)
AI 服务超时重试 → 降级处理–
并发冲突乐观锁重试409

10. 安全设计

维度策略
认证JWT Token，支持刷新
授权RBAC，资源级权限检查
API 安全HTTPS，请求签名校验
数据安全敏感数据加密存储
多租户安全所有查询强制带上 Tenant ID 过滤

11. 未来扩展点

扩展方向接入方式
视频课程自动生成监听 LearningPath.Generated 事件，新增 PipelineHandler
AI 对话助手基于 Project 知识图谱的 RAG 问答
团队协作编辑Workspace 成员角色细化
第三方集成 (Notion/飞书)通过 Webhook/API 接入
移动端复用 BFF API
知识卡片/闪卡复习基于 UserKnowledge 的间隔重复系统

发表评论