# 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` 命令细化到可操作级别