# 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 级别的深度提取
- 未进行交互式教学
- 遵守边界规则