Post Views: 6
1. 技术选型
1.1 后端技术栈
| 技术 | 选型 | 说明 |
|---|
| 编程语言 | Python 3.10+ | 生态丰富、AI/ML 库完善、快速迭代 |
| Web 框架 | FastAPI | 高性能异步框架、自动 OpenAPI 文档 |
| 数据库 | PostgreSQL 16 + pgvector | 关系型 + 向量检索一体 |
| 消息队列 | RabbitMQ 或 Redis Stream | EventBus 实现 |
| 缓存 | Redis 7+ | 状态缓存、Session、实时进度 |
| 对象存储 | MinIO（自部署） / 阿里云 OSS | 文件存储 |
| ORM | SQLAlchemy 2.0 | 成熟异步 ORM，支持 Alembic 迁移 |
| 数据库迁移 | Alembic | 数据库版本迁移管理 |
| 任务调度 | Celery / ARQ (基于 Redis) | Pipeline 异步任务队列 |
| 配置中心 | Pydantic Settings v2 | 基于环境变量的配置管理 |
| AI/LLM | OpenAI API / LangChain / 本地 LLM (Ollama) | 知识抽取、评估生成 |
| 认证 | PyJWT / python-jose | JWT 身份认证 |
1.2 前端技术栈
| 技术 | 选型 | 说明 |
|---|
| 框架 | React 18+ | 前端 UI 框架 |
| 构建工具 | Vite 5+ | 快速开发服务器与打包 |
| 语言 | TypeScript | 类型安全 |
| UI 组件库 | Ant Design 6+ | 企业级 UI 组件库 |
| 状态管理 | Zustand | 轻量状态管理 |
| 路由 | react-router-dom v6 | 前端路由 |
| HTTP 客户端 | Axios | HTTP 请求封装 |
| 知识图谱可视化 | Cytoscape.js | 知识图谱渲染 |
| 实时通信 | SSE (Server-Sent Events) | Pipeline 进度推送 |
| 数据可视化 | ECharts / D3.js | 学习数据图表 |
1.3 DevOps
| 工具 | 用途 |
|---|
| Docker + Docker Compose | 本地开发/测试 |
| GitHub Actions | CI/CD |
| Swagger / OpenAPI | API 文档 |
| Prometheus + Grafana | 监控 |
| ELK / Loki | 日志聚合 |
2. 开发阶段规划
阶段一：核心基础设施（第 1~2 周）
目标：搭建项目骨架，跑通最简核心流程
后端:
- 项目初始化（FastAPI 项目脚手架、目录结构）
- 数据模型定义（SQLAlchemy 2.0 ORM）
- Alembic 数据库迁移初始化
- JWT 认证中间件（FastAPI Depends）
- Workspace CRUD API
- Project CRUD API
- 文件上传/下载 API（对接 MinIO）
- 基础 EventBus 实现（Redis Stream / Redis pub-sub）
前端:
- Vite + React + TypeScript 项目初始化
- 登录/注册页面
- Workspace 列表页
- Project 列表/详情页
- 文件上传组件
交付物:
- 用户可以注册登录
- 用户可以创建 Workspace 和 Project
- 用户可以上传 PDF 到项目
阶段二：Pipeline 引擎（第 3~4 周）
目标：实现异步 Pipeline 流水线和实时状态推送
后端:
- PipelineEngine 核心结构（DAG 编排）
- Pipeline 状态机管理
- DocumentParseHandler（PDF 解析）
- SSE 端点：实时推送进度
- Pipeline 表 + Stage 表数据操作
- 重试机制
前端:
- Pipeline 进度展示组件（进度条 + 阶段列表）
- SSE 连接管理 Hook
交付物:
- 上传 PDF 后自动启动 Pipeline
- 用户可实时查看每个阶段的处理进度
- 错误时显示提示和重试按钮
阶段三：AI 知识抽取（第 5~7 周）
目标：接入 LLM 完成知识抽取、合并、关系推理
后端:
- LLM 服务封装（OpenAI / 本地 LLM 适配器）
- KnowledgeExtractionHandler（AI 抽取知识点）
- KnowledgeMergingHandler（去重合并）
- DependencyInferenceHandler（知识依赖推理）
- GraphBuildingHandler（图谱构建）
- 知识节点 + 关系 CRUD API
- pgvector 向量存储和语义搜索
交付物:
- 文档资料完成全流程 Pipeline
- 自动生成带依赖关系的知识图谱数据
- 知识图谱可视化接口可用
阶段四：知识图谱与可视化（第 8~9 周）
目标：构建三层知识图谱，实现图谱可视化
后端:
- Global Knowledge Graph 管理 API
- Project Knowledge Graph API
- User Knowledge State API
- 知识图谱搜索接口
- Global ↔ Project 节点关联
前端:
- 知识图谱可视化组件（Cytoscape.js）
- 节点详情弹窗
- 图谱搜索功能
- 用户掌握程度热力图
交付物:
- 三层知识图谱完整可用
- 用户可浏览和搜索知识图谱
- 全局知识库开始积累
阶段五：学习旅程（第 10~12 周）
目标：实现能力评估、学习路线、答题系统
后端:
- AssessmentGenerationHandler（AI 生成试题）
- LearningPathGenerationHandler（生成学习路线）
- 答题引擎（提交/判分）
- 能力评估分析
- 知识缺口定位
- 学习记录追踪
前端:
- 能力评估页面（问卷模式）
- 学习路线视图（顺序/进度）
- 答题练习界面
- 学习统计仪表盘
交付物:
- 用户可进行能力评估
- 生成个性化学习路线
- 支持答题练习和自动判分
- 学习数据可视化
阶段六：共享与版本（第 13~14 周）
目标：实现分享、复制、版本管理
后端:
- 项目分享（Token 生成 / 权限控制）
- 项目复制（深拷贝知识图谱）
- 版本管理（资料变更触发新版本）
- 版本 Diff 计算
- 版本对比 API
前端:
- 项目分享对话框
- 版本列表/对比页面
- 版本 Diff 可视化
交付物:
- 用户可分享并复制项目
- 自动版本管理
- 版本对比展示（新增/移除/变更）
阶段七：优化与发布（第 15~16 周）
目标：性能优化、测试、部署上线
后端:
- 性能优化（数据库查询、缓存策略）
- 单元测试 + 集成测试
- 安全审计
- Docker Compose 部署配置
- 监控接入（Prometheus + Grafana）
前端:
- 响应式适配
- 加载状态优化
- 错误处理完善
- 使用文档
交付物:
- 生产可部署版本
- 自动化测试覆盖核心流程
- 监控告警就绪
3. 项目目录结构
icat-learn-os/
├── backend/
│ ├── main.py # FastAPI 主入口
│ ├── common/
│ │ ├── config.py # Pydantic Settings 配置
│ │ ├── db.py # SQLAlchemy 引擎与 Session
│ │ ├── runtime.py # FastAPI 应用工厂
│ │ ├── log.py # 日志配置
│ │ ├── cache.py # 缓存抽象层
│ │ ├── response.py # 统一响应格式
│ │ └── errors.py # 错误处理
│ ├── model/ # SQLAlchemy ORM 模型
│ │ ├── base.py # 基类（UUID 主键、审计字段）
│ │ ├── workspace.py
│ │ ├── project.py
│ │ ├── document.py
│ │ ├── knowledge.py
│ │ └── learning.py
│ ├── dao/ # 数据访问层
│ │ ├── base_dao.py # 通用 CRUD
│ │ └── ...
│ ├── service/ # 业务逻辑层
│ │ ├── workspace_service.py
│ │ ├── project_service.py
│ │ ├── document_service.py
│ │ ├── pipeline_service.py
│ │ ├── knowledge_service.py
│ │ ├── learning_service.py
│ │ └── share_service.py
│ ├── api/ # API 路由
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── workspace.py
│ │ ├── project.py
│ │ ├── document.py
│ │ ├── pipeline.py
│ │ ├── knowledge.py
│ │ ├── learning.py
│ │ └── share.py
│ ├── pipeline/ # Pipeline 引擎
│ │ ├── engine.py
│ │ ├── state_machine.py
│ │ └── handlers/
│ │ ├── document_parse.py
│ │ ├── ocr.py
│ │ ├── knowledge_extraction.py
│ │ ├── knowledge_merging.py
│ │ ├── dependency_inference.py
│ │ └── graph_building.py
│ ├── eventbus/ # 事件总线
│ │ ├── bus.py
│ │ └── events.py
│ ├── ai/ # AI 服务封装
│ │ ├── client.py
│ │ └── prompts.py
│ ├── alembic/ # 数据库迁移
│ │ ├── env.py
│ │ └── versions/
│ ├── alembic.ini
│ ├── .env
│ ├── requirements.txt
│ ├── Dockerfile
│ └── pyproject.toml
│
├── frontend/
│ ├── src/
│ │ ├── api/ # API 请求封装（Axios）
│ │ ├── components/ # UI 组件
│ │ │ ├── pipeline/ # Pipeline 进度组件
│ │ │ ├── graph/ # 知识图谱组件
│ │ │ └── assessment/ # 评估组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── store/ # Zustand 状态管理
│ │ ├── router/ # react-router-dom 路由
│ │ ├── theme/ # 主题配置
│ │ ├── i18n/ # 国际化
│ │ ├── types/ # TypeScript 类型
│ │ ├── App.tsx
│ │ └── main.tsx # Vite 入口
│ ├── index.html
│ ├── vite.config.ts
│ ├── tsconfig.json
│ ├── package.json
│ └── Dockerfile
│
├── docker-compose.yml
├── docker-compose.dev.yml
├── Makefile
└── README.md
4. 关键依赖清单
4.1 Python 依赖
fastapi>=0.110.0 # Web 框架
uvicorn[standard]>=0.27.0 # ASGI 服务器
sqlalchemy>=2.0.25 # ORM
psycopg2-binary>=2.9.9 # PostgreSQL 驱动
alembic>=1.13.0 # 数据库迁移
pydantic>=2.5.0 # 数据验证
pydantic-settings>=2.1.0 # 配置管理
redis>=5.0.0 # Redis 客户端
httpx>=0.26.0 # HTTP 客户端（AI 服务调用）
python-jose[cryptography]>=3.3.0 # JWT 认证
openai>=1.6.0 # OpenAI API 客户端
pgvector>=0.2.0 # pgvector 驱动
minio>=7.2.0 # MinIO 对象存储
celery>=5.3.0 # 异步任务队列（可选）
langchain>=0.1.0 # LLM 编排框架（可选）
python-multipart>=0.0.6 # 文件上传
loguru>=0.7.2 # 日志（可选）
4.2 Node.js 依赖
{
"react": "^18",
"react-dom": "^18",
"react-router-dom": "^6",
"antd": "^5",
"@ant-design/icons": "^5",
"zustand": "^4",
"cytoscape": "^3",
"echarts": "^5",
"axios": "^1",
"dayjs": "^1",
"vite": "^5",
"@vitejs/plugin-react": "^4",
"typescript": "~5.3"
}
5. 质量保障
| 维度 | 要求 | 工具 |
|---|
| 单元测试 | 核心服务覆盖 > 80% | pytest + pytest-cov |
| API 测试 | 所有 API 端点自动化测试 | pytest + httpx (TestClient) |
| 前端测试 | 核心组件测试 | Vitest + Testing Library |
| 代码规范 | Python PEP 8 + Lint | Ruff / Flake8 + Black |
| 安全扫描 | 依赖漏洞检测 | pip-audit / Snyk |
| 性能基准 | Pipeline 各阶段性能基线 | pytest-benchmark |
6. 部署架构
┌─────────────┐
│ Nginx │
│ (反向代理) │
└──────┬──────┘
│
┌───────────┴───────────┐
│ │
┌──────▼──────┐ ┌───────▼───────┐
│ Frontend │ │ Backend API │
│ (Vite+React) │ │ (Python/FastAPI)|
└──────┬───────┘ └───────┬────────┘
│ │
└───────────┬───────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ PostgreSQL │ │ Redis │ │ MinIO │
│ + pgvector │ │ (缓存/MQ) │ │ (对象存储) │
└───────────┘ └─────────────┘ └─────────────┘
7. 环境配置
| 环境 | 用途 | 配置 |
|---|
| dev | 本地开发 | Docker Compose 一键启动 |
| staging | 集成测试 | 云服务器 / 本地服务器 |
| production | 正式上线 | 云服务（云原生） |