# PRD：集合功能增强

## 一、问题分析

### 问题 1：集合详情页不显示已收录文章

**页面**：`https://blog.ephron.ren/collections/data-structure`

**现象**：集合详情页显示「该集合暂无文章」，但实际上已有文章被收录到该集合。

**根因分析**：

路由代码 `blog/src/routes/pages.py` 第 488-519 行：
```python
for item in collection.get("items", []):
    post = get_post_by_slug(item["post_slug"], include_drafts=False)
    if post:
        items.append({...})
```

可能原因：
1. `blog_collection_items` 表中没有对应数据
2. 文章 slug 与集合中记录的 `post_slug` 不匹配
3. 文章是草稿状态但使用了 `include_drafts=False`

**需要验证**：查询数据库确认 `blog_collection_items` 表是否有数据。

---

### 问题 2：全部文章列表不显示集合归属

**页面**：`https://blog.ephron.ren/posts`

**现象**：文章列表只显示置顶、日期、标签、草稿标记，不显示文章所属的集合。

**用户期望**：已收录到集合的文章应在全部文章列表中显示集合标记（类似标签），方便识别哪些文章已被组织到集合中。

---

### 问题 3：新建文章/提示词时无法选择集合

**页面**：
- Blog：`https://blog.ephron.ren/admin/new`
- Prompt：`https://prompt.ephron.ren/admin/new`

**现象**：新建文章/提示词时，只能先创建内容，再手动编辑集合添加。

**用户期望**：创建时即可选择加入已有集合，提升内容组织效率。

---

## 二、需求详情

### 需求 1：修复集合详情页文章显示

**优先级**：P0（Bug 修复）

**验收标准**：
- [ ] 访问 `/collections/{key}` 能正确显示已收录的文章
- [ ] 文章按 `sort_order` 排序显示
- [ ] 显示文章标题、摘要、备注
- [ ] 空集合显示「该集合暂无文章」

**技术方案**：
1. 检查并修复 `blog_collection_items` 表数据
2. 确保 `get_post_by_slug` 在包含草稿时能正确返回
3. 添加日志排查 slug 匹配问题

---

### 需求 2：全部文章列表显示集合标记

**优先级**：P1（功能增强）

**验收标准**：
- [ ] 文章列表中，已收录到集合的文章显示集合标记
- [ ] 标记可点击，跳转到集合详情页
- [ ] 一篇文章可属于多个集合，显示所有集合标记
- [ ] 未收录到任何集合的文章不显示标记

**UI 设计**：
```
文章标题                                    📌 置顶
摘要内容...
2025-01-01  [标签1] [标签2]  [集合A] [集合B]  草稿
```

集合标记样式：
- 背景色：`var(--accent-glow)`（蓝色半透明）
- 文字色：`var(--accent)`
- 圆角：`4px`
- 前缀图标：`📁` 或 `📚`

**技术方案**：
1. 在 `pages.py` 的 `posts_list` 函数中，批量查询文章的集合归属
2. 使用 `get_all_collection_post_slugs()` 或更高效的批量查询
3. 将集合信息传递给模板
4. 模板中渲染集合标记

**API 变更**：
```python
# 新增批量查询函数
def get_posts_collections(post_slugs: list[str]) -> dict[str, list[dict]]:
    """
    批量查询多篇文章的集合归属
    返回: {post_slug: [{key, title}, ...]}
    """
```

---

### 需求 3：新建文章/提示词时选择集合

**优先级**：P1（功能增强）

#### 3.1 Blog 新建文章

**页面**：`/admin/new`

**验收标准**：
- [ ] 新建文章表单增加「选择集合」下拉框
- [ ] 支持多选（可加入多个集合）
- [ ] 显示集合名称和已有文章数量
- [ ] 提交时自动创建 `blog_collection_items` 记录
- [ ] 权限控制：需要 `blog.post.create_draft` 权限

**UI 设计**：
```html
<div class="form-group">
    <label>加入集合（可选）</label>
    <select name="collection_keys" multiple class="input">
        <option value="">-- 不加入集合 --</option>
        <option value="data-structure">数据结构 (5篇)</option>
        <option value="algorithm">算法 (3篇)</option>
    </select>
    <span class="hint">按住 Ctrl/Cmd 可多选</span>
</div>
```

**技术方案**：
1. `admin.py` 的 `new_collection_page` 函数传递集合列表
2. 表单增加 `collection_keys` 字段（数组）
3. `create_new_post` 函数处理集合关联
4. 调用 `add_item_to_collection` 创建关联记录

**API 变更**：
```python
# POST /admin/new 新增字段
collection_keys: list[str] = Form(default=[])  # 集合 key 列表
```

#### 3.2 Prompt 新建提示词

**页面**：`/admin/new`

**验收标准**：
- [ ] 新建提示词表单增加「选择集合」下拉框
- [ ] 支持多选
- [ ] 提交时自动创建 `collection_items` 记录
- [ ] 权限控制：需要 `prompt.create` 权限

**技术方案**：同 Blog，修改 Prompt 服务的 `admin.py` 和相关模板。

#### 3.3 API 创建文章/提示词

**Blog Service API**：
```python
# POST /api/service/posts
{
    "title": "文章标题",
    "content": "...",
    "tags": ["tag1"],
    "collection_keys": ["col1", "col2"]  # 新增
}
```

**Prompt Service API**：
```python
# POST /api/service/prompts
{
    "key": "prompt-key",
    "title": "提示词标题",
    "content": "...",
    "collection_keys": ["col1", "col2"]  # 新增
}
```

**验收标准**：
- [ ] API 支持 `collection_keys` 参数
- [ ] 参数可选，默认为空数组
- [ ] 自动创建集合关联记录
- [ ] 集合不存在时忽略（不报错）
- [ ] 权限检查：需要对应集合的编辑权限

---

## 三、数据模型

### Blog 集合表结构

```sql
-- 集合主表
CREATE TABLE blog_collections (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    key TEXT UNIQUE NOT NULL,
    title TEXT NOT NULL,
    description TEXT DEFAULT '',
    cover_image TEXT DEFAULT '',
    created_by TEXT,
    is_active INTEGER DEFAULT 1,
    created_at DATETIME DEFAULT (datetime('now')),
    updated_at DATETIME DEFAULT (datetime('now'))
);

-- 集合关联表
CREATE TABLE blog_collection_items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    collection_key TEXT NOT NULL,
    post_slug TEXT NOT NULL,
    sort_order INTEGER DEFAULT 0,
    note TEXT DEFAULT '',
    created_at DATETIME DEFAULT (datetime('now')),
    FOREIGN KEY (collection_key) REFERENCES blog_collections(key) ON DELETE CASCADE,
    UNIQUE(collection_key, post_slug)
);
```

### Prompt 集合表结构

```sql
-- 集合主表
CREATE TABLE collections (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    key TEXT UNIQUE NOT NULL,
    title TEXT NOT NULL,
    description TEXT DEFAULT '',
    created_by TEXT,
    is_active INTEGER DEFAULT 1,
    created_at DATETIME DEFAULT (datetime('now')),
    updated_at DATETIME DEFAULT (datetime('now'))
);

-- 集合关联表
CREATE TABLE collection_items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    collection_key TEXT NOT NULL,
    prompt_key TEXT NOT NULL,
    sort_order INTEGER DEFAULT 0,
    note TEXT DEFAULT '',
    created_at DATETIME DEFAULT (datetime('now')),
    FOREIGN KEY (collection_key) REFERENCES collections(key) ON DELETE CASCADE,
    UNIQUE(collection_key, prompt_key)
);
```

---

## 四、与 Prompt 集合逻辑的差异

| 特性 | Blog 集合 | Prompt 集合 |
|------|----------|------------|
| 内容类型 | 文章（Markdown） | 提示词（模板） |
| 主键 | `post_slug`（文件名） | `prompt_key`（数据库 key） |
| 创建方式 | 文件系统扫描 | 数据库插入 |
| 集合显示 | 需求2：全部文章列表显示集合标记 | 已有：全部提示词列表显示集合标记 |
| 创建时选择集合 | 需求3：新建时可选 | 需求3：新建时可选 |

**关键差异**：
- Blog 文章是文件系统驱动，集合关联是后加的
- Prompt 提示词是数据库驱动，集合关联是原生支持

---

## 五、实施计划

### Phase 1：Bug 修复（需求 1）

**时间**：0.5 天

**任务**：
1. [ ] 检查 `blog_collection_items` 表数据
2. [ ] 修复数据不一致问题
3. [ ] 验证集合详情页正常显示

### Phase 2：全部文章显示集合标记（需求 2）

**时间**：1 天

**任务**：
1. [ ] 实现 `get_posts_collections()` 批量查询函数
2. [ ] 修改 `pages.py` 的 `posts_list` 函数
3. [ ] 修改 `index.html` 模板
4. [ ] 测试多集合、空集合场景

### Phase 3：新建时选择集合（需求 3）

**时间**：1.5 天

**任务**：
1. [ ] Blog：修改 `admin.py` 和 `new.html`
2. [ ] Prompt：修改 `admin.py` 和 `new.html`
3. [ ] Blog API：修改 Service API 支持 `collection_keys`
4. [ ] Prompt API：修改 Service API 支持 `collection_keys`
5. [ ] 测试权限控制和边界场景

---

## 六、测试用例

### 需求 1 测试

| 编号 | 测试内容 | 预期结果 |
|------|---------|---------|
| T-001 | 访收录有文章的集合详情页 | 显示文章列表 |
| T-002 | 访问空集合详情页 | 显示「该集合暂无文章」 |
| T-003 | 文章排序 | 按 sort_order 升序 |
| T-004 | 草稿文章 | 不显示（公开页） |

### 需求 2 测试

| 编号 | 测试内容 | 预期结果 |
|------|---------|---------|
| T-010 | 已收录文章显示集合标记 | 显示蓝色标记 |
| T-011 | 未收录文章 | 不显示集合标记 |
| T-012 | 点击集合标记 | 跳转到集合详情页 |
| T-013 | 文章属于多个集合 | 显示多个标记 |
| T-014 | 搜索结果中显示 | 同样显示集合标记 |

### 需求 3 测试

| 编号 | 测试内容 | 预期结果 |
|------|---------|---------|
| T-020 | Blog 新建选择集合 | 自动关联到集合 |
| T-021 | Blog 新建不选集合 | 正常创建，不关联 |
| T-022 | Blog API 带 collection_keys | 自动关联 |
| T-023 | Prompt 新建选择集合 | 自动关联到集合 |
| T-024 | Prompt API 带 collection_keys | 自动关联 |
| T-025 | 集合 key 不存在 | 忽略，不报错 |
| T-026 | 权限不足 | 返回 403 |

---

## 七、风险与依赖

### 风险

1. **数据一致性**：Blog 文章删除后，`blog_collection_items` 中的关联记录可能成为孤立数据
2. **性能影响**：全部文章列表需要额外查询集合信息，可能增加数据库压力
3. **权限复杂性**：创建文章时选择集合需要同时检查文章和集合的权限

### 依赖

1. 需求 1 是需求 2 的前提（集合详情页必须能正常显示）
2. 需求 3 依赖现有集合 CRUD 功能
3. Blog 和 Prompt 服务的集合逻辑独立，可并行开发

---

## 八、相关代码位置

### Blog 服务

- 集合详情路由：`blog/src/routes/pages.py` 第 488-519 行
- 文章列表路由：`blog/src/routes/pages.py` 第 120-160 行
- Admin 新建路由：`blog/src/routes/admin.py` 第 431-497 行
- Service API 路由：`blog/src/routes/service_api.py`
- 集合服务层：`blog/src/services/blog_collections.py`
- 集合详情模板：`blog/templates/collection_detail.html`
- 文章列表模板：`blog/templates/index.html`
- Admin 新建模板：`blog/templates/admin/new.html`

### Prompt 服务

- Admin 新建路由：`prompt/src/routes/admin.py`
- Service API 路由：`prompt/src/routes/service_api.py`
- 集合服务层：`prompt/src/services/collections.py`
- Admin 新建模板：`prompt/templates/admin/new.html`

---

## 九、验收标准汇总

- [ ] 集合详情页正确显示已收录文章
- [ ] 全部文章列表显示集合标记
- [ ] 新建文章时可选择加入集合
- [ ] 新建提示词时可选择加入集合
- [ ] API 创建支持 `collection_keys` 参数
- [ ] 权限控制正确
- [ ] 边界场景处理（空集合、不存在的 key、重复关联）