230 lines
7.1 KiB
Markdown
230 lines
7.1 KiB
Markdown
# PRD: 博客集合排序 & 文章生成时间记录
|
||
|
||
## 背景
|
||
|
||
### 问题一：集合内新文章排序异常
|
||
|
||
当前 AI-daily 集合中，新加入的文章排在第二位而非第一位。
|
||
|
||
**根因分析：**
|
||
|
||
`add_item_to_collection()` 默认 `sort_order=0`，而集合中第一篇文章的 sort_order 也是 0。当两条记录 sort_order 相同时，SQLite 按 ROWID（插入顺序）做 tie-break，导致先插入的老文章排在前面，新文章排到第二位。
|
||
|
||
**相关代码：**
|
||
|
||
- `blog/src/services/blog_collections.py` 第 170-192 行：`add_item_to_collection` 默认 `sort_order=0`
|
||
- `blog/src/routes/service_api.py` 第 247 行：创建文章时调用 `add_item_to_collection(col_key, slug)` 未传 sort_order
|
||
- `blog/src/services/blog_collections.py` 第 49 行：查询排序 `ORDER BY bci.sort_order`（升序）
|
||
|
||
### 问题二：同日期文章排序依赖文件系统时间
|
||
|
||
当前排序逻辑（最新代码 ff539d4）：
|
||
|
||
```python
|
||
posts.sort(key=lambda p: (not p.pinned, -p.date.toordinal(), -p.file_path.stat().st_mtime))
|
||
```
|
||
|
||
用 `st_mtime`（文件修改时间）做同日期 tie-break。问题：
|
||
- 文章被编辑后 mtime 会变，排序不再是「生成时间」而是「最后编辑时间」
|
||
- frontmatter 中只有 `date: YYYY-MM-DD`，不记录精确的生成时间
|
||
|
||
**相关代码：**
|
||
|
||
- `blog/src/services/posts.py` 第 325 行：`get_all_posts` 排序
|
||
- `blog/src/services/posts.py` 第 643 行：`search_posts` 排序
|
||
- `blog/src/services/posts.py` 第 837-839 行：`create_post` 只写入 `date.today().isoformat()`
|
||
|
||
---
|
||
|
||
## 需求
|
||
|
||
### 需求一：集合内新文章默认排在最前面
|
||
|
||
新加入集合的文章应自动排在集合内所有文章的最前面（sort_order 最小）。
|
||
|
||
### 需求二：记录文章精确生成时间
|
||
|
||
在 frontmatter 中新增 `created_at` 字段，记录文章创建的精确时间（东八区，精确到秒），用于同日期文章排序的 tie-break。
|
||
|
||
---
|
||
|
||
## 详细设计
|
||
|
||
### 一、集合排序修复
|
||
|
||
**修改文件：** `blog/src/services/blog_collections.py`
|
||
|
||
**修改函数：** `add_item_to_collection()`
|
||
|
||
**方案：** 插入前查询当前集合的最小 sort_order，新文章设为 `min_sort_order - 1`。
|
||
|
||
```python
|
||
def add_item_to_collection(
|
||
collection_key: str,
|
||
post_slug: str,
|
||
sort_order: int | None = None, # None 表示自动计算
|
||
note: str = "",
|
||
) -> bool:
|
||
"""向集合添加文章（新文章默认排在最前面）"""
|
||
try:
|
||
with get_connection() as conn:
|
||
cursor = conn.cursor()
|
||
|
||
# 自动计算 sort_order：取当前最小值 - 1
|
||
if sort_order is None:
|
||
cursor.execute(
|
||
"SELECT MIN(sort_order) FROM blog_collection_items WHERE collection_key = ?",
|
||
(collection_key,)
|
||
)
|
||
row = cursor.fetchone()
|
||
min_order = row[0] if row and row[0] is not None else 0
|
||
sort_order = min_order - 1
|
||
|
||
cursor.execute(
|
||
"""
|
||
INSERT OR REPLACE INTO blog_collection_items
|
||
(collection_key, post_slug, sort_order, note)
|
||
VALUES (?, ?, ?, ?)
|
||
""",
|
||
(collection_key, post_slug, sort_order, note)
|
||
)
|
||
conn.commit()
|
||
return True
|
||
except Exception as e:
|
||
print(f"Error adding item to blog collection: {e}")
|
||
return False
|
||
```
|
||
|
||
**对调用方的影响：**
|
||
|
||
| 调用方 | 是否需要修改 | 说明 |
|
||
|--------|-------------|------|
|
||
| `service_api.py` 第 247 行 | 不需要 | `add_item_to_collection(col_key, slug)` 不传 sort_order，自动走新逻辑 |
|
||
| `create_collection_with_items()` | 不需要 | 批量创建集合时 sort_order 由调用方显式传入，不受影响 |
|
||
| `update_collection_items()` | 不需要 | 手动排序时显式传入 sort_order，不受影响 |
|
||
| 前端拖拽排序 | 不需要 | 前端传 0,1,2,3... 显式值，不受影响 |
|
||
|
||
**与手动排序的交互：**
|
||
|
||
- 手动拖拽排序会将所有 sort_order 重置为 0, 1, 2, 3...（前端实现，不改）
|
||
- 手动排序后再有新文章加入 → 自动取 min(0) - 1 = -1 → 排在手动排序文章前面 ✅
|
||
- 不会与手动排序产生冲突
|
||
|
||
---
|
||
|
||
### 二、文章生成时间记录
|
||
|
||
**修改文件：** `blog/src/services/posts.py`
|
||
|
||
#### 2.1 新增 `created_at` 字段
|
||
|
||
**修改函数：** `create_post()`
|
||
|
||
在 frontmatter 中新增 `created_at` 字段，使用东八区时间，ISO 8601 格式，精确到秒：
|
||
|
||
```python
|
||
from datetime import date, datetime, timezone, timedelta
|
||
|
||
CST = timezone(timedelta(hours=8))
|
||
|
||
# create_post() 中：
|
||
frontmatter = {
|
||
"title": title,
|
||
"date": date.today().isoformat(),
|
||
"created_at": datetime.now(CST).isoformat(), # 新增
|
||
"views": 0,
|
||
"likes": 0,
|
||
"draft": draft,
|
||
...
|
||
}
|
||
```
|
||
|
||
**示例输出：**
|
||
|
||
```yaml
|
||
---
|
||
title: AI日报 · 2026-05-15
|
||
date: 2026-05-15
|
||
created_at: '2026-05-15T08:30:45+08:00'
|
||
---
|
||
```
|
||
|
||
#### 2.2 解析 `created_at` 字段
|
||
|
||
**修改位置：** `_parse_post_meta()` 函数
|
||
|
||
在 `PostMeta` dataclass 和解析逻辑中新增 `created_at` 字段：
|
||
|
||
```python
|
||
@dataclass
|
||
class PostMeta:
|
||
slug: str
|
||
title: str
|
||
date: date
|
||
created_at: datetime | None # 新增
|
||
tags: list[str]
|
||
# ... 其余字段不变
|
||
```
|
||
|
||
解析逻辑：
|
||
|
||
```python
|
||
# 在 _parse_post_meta() 中
|
||
created_at = None
|
||
created_at_raw = frontmatter.get("created_at")
|
||
if isinstance(created_at_raw, datetime):
|
||
created_at = created_at_raw
|
||
elif isinstance(created_at_raw, str):
|
||
try:
|
||
created_at = datetime.fromisoformat(created_at_raw)
|
||
except ValueError:
|
||
logger.warning(f"Invalid created_at format in {file_path}")
|
||
```
|
||
|
||
#### 2.3 修改排序逻辑
|
||
|
||
**修改位置：** `get_all_posts()` 和 `search_posts()` 的排序
|
||
|
||
将 `st_mtime` 替换为 `created_at`：
|
||
|
||
```python
|
||
# get_all_posts() 和 search_posts() 中
|
||
posts.sort(key=lambda p: (
|
||
not p.pinned,
|
||
-p.date.toordinal(),
|
||
-(p.created_at.timestamp() if p.created_at else p.file_path.stat().st_mtime)
|
||
))
|
||
```
|
||
|
||
**兼容性说明：**
|
||
|
||
- 历史文章没有 `created_at` 字段 → 回退到 `st_mtime`，行为与当前一致
|
||
- 新文章有 `created_at` → 用精确时间排序，不受编辑影响
|
||
|
||
#### 2.4 更新文章时保留 `created_at`
|
||
|
||
**修改函数：** `update_post()`
|
||
|
||
`update_post` 不应覆盖 `created_at`（它是首次创建时间，不是更新时间）。当前 `update_post` 只修改传入的字段，不传 `created_at` 就不会被覆盖，**无需额外修改**。
|
||
|
||
---
|
||
|
||
## 影响范围
|
||
|
||
| 模块 | 影响 |
|
||
|------|------|
|
||
| `blog_collections.py` | 修改 `add_item_to_collection` 一个函数 |
|
||
| `posts.py` | 修改 `PostMeta`、`_parse_post_meta`、`create_post`、`get_all_posts`、`search_posts` |
|
||
| 前端模板 | 无需修改 |
|
||
| `service_api.py` | 无需修改 |
|
||
| `admin.py` | 无需修改 |
|
||
| 数据库 | 无需迁移（集合表结构不变） |
|
||
| 历史文章 | 兼容，无 `created_at` 时回退到 `st_mtime` |
|
||
|
||
## 不做的事
|
||
|
||
- 不改集合表结构（不加 `added_at` 列）
|
||
- 不改前端拖拽排序逻辑
|
||
- 不改 `date` 字段格式（保持 `YYYY-MM-DD`）
|
||
- 不对历史文章批量补写 `created_at`
|