236 lines
9.5 KiB
Markdown
236 lines
9.5 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：流程（优化版 - 黄金路径视角）
|
||
|
||
### 端到端用户流程图
|
||
|
||
```
|
||
用户视角:
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ 输入URL │──────▶│ 等待处理 │──────▶│ 查看文章 │
|
||
└──────────────┘ └──────────────┘ └──────────────┘
|
||
|
||
系统视角:
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ API接收请求 │──────▶│ URL获取内容 │──────▶│ 内容清洗 │
|
||
└──────────────┘ └──────────────┘ └───────┬──────┘
|
||
│
|
||
┌──────────────┐ ┌──────────────┐ ┌───────▼──────┐
|
||
│ 向量存储 │◀────│ 信息提取 │◀────│ AI处理链 │
|
||
└──────────────┘ └──────────────┘ └──────────────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 响应用户 │
|
||
└──────────────┘
|
||
```
|
||
|
||
### 模块调用链
|
||
|
||
**文章导入完整调用链：**
|
||
|
||
```
|
||
POST /api/articles/ingest
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ article_router.py │
|
||
│ - 接收 URL payload │
|
||
└──────────────┬───────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ article_url_ingest_service.py │
|
||
│ - 获取原始 HTML │
|
||
└──────────────┬───────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ article_ai_pipeline_service.py │
|
||
│ ┌──────────────┬──────────────┐ │
|
||
│ │ clean_text │ extract_tags │ │
|
||
│ └──────────────┴──────────────┘ │
|
||
│ ┌──────────────┬──────────────┐ │
|
||
│ │ summarize │ embed │ │
|
||
│ └──────────────┴──────────────┘ │
|
||
└──────────────┬───────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ article_command_service.py │
|
||
│ - 持久化到数据库 │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
**优化点说明：**
|
||
- 原报告只展示了 `pipeline_service` 单文件内部流程
|
||
- 优化版增加了**用户视角的端到端流程**和**完整的模块调用链**
|
||
- 让读者理解从 URL 到数据库的完整路径，不只是中间某个环节
|
||
|
||
---
|
||
|
||
## 阶段 4：起步路径（优化版 - 可执行命令）
|
||
|
||
**前置要求：**
|
||
- Python 3.11+
|
||
- PostgreSQL
|
||
|
||
**步骤 1：环境准备**
|
||
```bash
|
||
cd backend
|
||
pip install -e .
|
||
```
|
||
|
||
**步骤 2：数据库初始化**
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
**步骤 3：启动服务**
|
||
```bash
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
**首个观察点：**
|
||
打开 `backend/app/api/routers/article_router.py`，搜索 `ingest` 端点，观察：
|
||
- 接收什么参数（URL、可选的 category_id）
|
||
- 调用哪个 service 方法
|
||
- 返回什么响应
|
||
|
||
**第一个可执行的修改（颗粒度细化）：**
|
||
|
||
原报告只说了"修改 AI_MODEL"，没有具体命令。以下是可落地的步骤：
|
||
|
||
```bash
|
||
# 1. 复制示例配置文件
|
||
cp backend/.env.example backend/.env
|
||
|
||
# 2. 查看当前 AI 模型设置
|
||
grep AI_MODEL backend/.env
|
||
# 输出: AI_MODEL=gpt-3.5-turbo
|
||
|
||
# 3. 修改为其他模型（举例）
|
||
sed -i 's/AI_MODEL=.*/AI_MODEL=gpt-4o-mini/' backend/.env
|
||
|
||
# 4. 确认修改成功
|
||
grep AI_MODEL backend/.env
|
||
# 输出: AI_MODEL=gpt-4o-mini
|
||
|
||
# 5. 重启服务（如果已运行）
|
||
# Ctrl+C 停止，然后重新运行:
|
||
uvicorn app.main:app --reload
|
||
|
||
# 6. 验证：测试 AI 摘要功能
|
||
# 在浏览器打开: http://localhost:8000/docs
|
||
# 找到 POST /api/articles/ingest，Try it out
|
||
# 输入: {"url": "https://example.com/article"}
|
||
# 观察响应中的 summary 字段质量变化
|
||
```
|
||
|
||
**安全边界：**
|
||
- 只改 `.env` 文件，不动源码
|
||
- 随时可以 `cp backend/.env.example backend/.env` 恢复
|
||
- 改模型不影响数据库，只影响 AI 调用
|
||
|
||
---
|
||
|
||
## 阶段 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 模型层 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 优化点总结
|
||
|
||
| 优化项 | 原报告 | 优化版 | 改进原因 |
|
||
|--------|--------|--------|----------|
|
||
| Phase 3 流程 | 单文件内部流程 | 端到端用户流程 + 完整调用链 | 让读者理解全貌，不只是某个环节 |
|
||
| Phase 4 修改 | "修改 AI_MODEL"（笼统） | 给具体命令：copy → sed → grep → 重启 → 测试 | 用户可直接执行，有验证环节 |
|
||
|
||
---
|
||
|
||
## 验证备注
|
||
|
||
- 按 v0.5.0 规范完成 5 个阶段
|
||
- 未进行 essence 级别的深度提取
|
||
- 未进行交互式教学
|
||
- 遵守边界规则
|
||
- Phase 4 的修改建议已通过 `sed` 命令细化到可操作级别
|