135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
# Explore 报告：Lumina
|
|
|
|
**项目类型：** 代码仓库
|
|
**完成阶段：** 5/5
|
|
**包含图示：** 是
|
|
**核心设计：** 3 个
|
|
**状态：** 完成
|
|
|
|
---
|
|
|
|
## 阶段 1：定位
|
|
|
|
**是什么：** Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。
|
|
|
|
**为什么值得学习：**
|
|
- 完整的内容处理 AI Pipeline 架构
|
|
- 领域驱动分层设计，关注点分离清晰
|
|
- 支持多租户的内容管理，内置治理功能
|
|
|
|
**目标用户：** 需要构建自托管知识库或 AI 增强 CMS 的开发者。
|
|
|
|
---
|
|
|
|
## 阶段 2：结构
|
|
|
|
```
|
|
lumina-main/
|
|
├── backend/ # FastAPI Python 后端
|
|
│ ├── app/
|
|
│ │ ├── api/routers/ # 16 个 REST 端点模块
|
|
│ │ ├── domain/ # 业务逻辑层 ⭐
|
|
│ │ ├── core/ # 配置与依赖
|
|
│ │ └── schemas/ # Pydantic 数据模型
|
|
│ ├── alembic/ # 数据库迁移
|
|
│ ├── ai_client.py # AI 客户端抽象
|
|
│ └── models.py # SQLAlchemy ORM 定义
|
|
└── frontend/ # Next.js React 前端
|
|
└── src/
|
|
├── app/ # App Router 结构
|
|
└── components/ # 可复用 UI 组件
|
|
```
|
|
|
|
**入口点：**
|
|
- 后端：`backend/app/domain/` - 业务逻辑
|
|
- 前端：`frontend/src/app/(routes)/` - 页面路由
|
|
|
|
---
|
|
|
|
## 阶段 3：流程
|
|
|
|
**核心流程：文章导入 → AI 处理 → 存储**
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
|
|
│ URL 提交 │────▶│ ingest_service │────▶│ Router │
|
|
└─────────────┘ └──────────────────┘ └──────┬──────┘
|
|
│
|
|
┌─────────────┐ ┌──────────────────┐ │
|
|
│ 响应 │◀────│ pipeline_service │◀──────────┘
|
|
└─────────────┘ └──────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ ORM │
|
|
└─────────────┘
|
|
```
|
|
|
|
**关键文件：** `backend/app/domain/article_ai_pipeline_service.py` - 模块化 AI 处理链，支持可配置步骤（清洗 → 打标签 → 摘要 → 嵌入）。
|
|
|
|
---
|
|
|
|
## 阶段 4：起步路径
|
|
|
|
**前置要求：**
|
|
- Python 3.11+
|
|
- PostgreSQL
|
|
|
|
**设置命令：**
|
|
```bash
|
|
cd backend
|
|
pip install -e .
|
|
alembic upgrade head # 初始化数据库模式
|
|
uvicorn app.main:app --reload # 启动开发服务器
|
|
```
|
|
|
|
**首个观察点：** 在 router 中查看 `article_ai_pipeline_service.py` 的调用链。
|
|
|
|
**安全的首个修改：** 修改 `core/settings.py` 中的 `AI_MODEL`，观察不同的 AI 行为。
|
|
|
|
---kanyii
|
|
|
|
## 阶段 5：核心设计
|
|
|
|
| # | 设计 | 位置 | 重要性 |
|
|
|---|------|------|--------|
|
|
| 1 | **领域服务层** | `app/domain/*.py` | API 与数据库解耦；AI 集成可独立演进 |
|
|
| 2 | **AI Pipeline 架构** | `article_ai_pipeline_service.py` | AI 处理不耦合 ORM；可配置、可追踪 |
|
|
| 3 | **路由注册器** | `api/router_registry.py` | 集中注册；新增模块无需改动 main.py |
|
|
|
|
---
|
|
|
|
## 架构图示
|
|
|
|
**后端领域架构：**
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ API 路由层 │
|
|
│ (article, ai_tasks, auth, settings...) │
|
|
└──────────────────┬──────────────────────┘
|
|
│
|
|
┌──────────────────▼──────────────────────┐
|
|
│ 领域服务层 │
|
|
│ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │article_query │ │article_command │ │
|
|
│ └──────────────┘ └──────────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ai_pipeline │ │ingest_service │ │
|
|
│ └──────────────┘ └──────────────────┘ │
|
|
└──────────────────┬──────────────────────┘
|
|
│
|
|
┌──────────────────▼──────────────────────┐
|
|
│ SQLAlchemy 模型层 │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 验证备注
|
|
|
|
- 按 v0.5.0 规范完成 5 个阶段
|
|
- 未进行 essence 级别的深度提取
|
|
- 未进行交互式教学
|
|
- 遵守边界规则
|