362 lines
9.7 KiB
Markdown
362 lines
9.7 KiB
Markdown
# Phase F.1：数据模型升级
|
||
|
||
日期：2026-04-04
|
||
状态：待开始
|
||
依赖：F.0（已完成）
|
||
前置：models/forum.py
|
||
|
||
---
|
||
|
||
## 1. 本阶段目的
|
||
|
||
升级 Jarvis Forum 的数据模型，支持：
|
||
- 多板块系统（指令/讨论/任务等）
|
||
- 标签系统（细粒度分类）
|
||
- 帖子元数据扩展（阅读量、点赞、收藏等）
|
||
- 层级回复结构
|
||
|
||
---
|
||
|
||
## 2. 目标模型
|
||
|
||
### 2.1 ForumBoard（板块）
|
||
|
||
```python
|
||
class ForumBoard(BaseModel):
|
||
__tablename__ = "forum_boards"
|
||
|
||
id: str = Field(default_factory=lambda: str(uuid.uuid4()))
|
||
name: str # 板块名称，如 "指令广场"
|
||
slug: str # URL 友好名称，如 "instruction"
|
||
description: Optional[str]
|
||
icon: Optional[str] # emoji 或图标名
|
||
sort_order: int = 0
|
||
is_active: bool = True
|
||
min_role: str = "user" # 查看权限：guest/user/moderator/admin
|
||
|
||
parent_id: Optional[str] # 父板块，支持层级
|
||
color: Optional[str] # 板块颜色
|
||
```
|
||
|
||
### 2.2 ForumPost（帖子）扩展
|
||
|
||
```python
|
||
class ForumPost(BaseModel):
|
||
__tablename__ = "forum_posts"
|
||
|
||
# === 现有字段 ===
|
||
user_id: str
|
||
title: str
|
||
content: str
|
||
reply_count: int = 0
|
||
|
||
# === 新增字段 ===
|
||
board_id: Optional[str] = None # 所属板块
|
||
parent_id: Optional[str] = None # 父帖子（支持回复嵌套）
|
||
|
||
# 分类与标签
|
||
category: Optional[str] # instruction/discussion/question/praise/bug
|
||
tags: Optional[str] = "" # JSON 数组 ["python", "api"]
|
||
|
||
# 状态与权限
|
||
is_pinned: bool = False # 置顶
|
||
is_locked: bool = False # 锁定（禁止回复）
|
||
is_deleted: bool = False # 软删除
|
||
is_executed: bool = False # 指令已执行
|
||
execution_result: Optional[str]
|
||
|
||
# 统计与互动
|
||
view_count: int = 0
|
||
like_count: int = 0
|
||
favorite_count: int = 0
|
||
share_count: int = 0
|
||
|
||
# 时间戳
|
||
last_reply_at: Optional[datetime] = None # 最后回复时间
|
||
last_activity_at: Optional[datetime] = None
|
||
|
||
# === 关系 ===
|
||
board = relationship("ForumBoard", back_populates="posts")
|
||
replies = relationship("ForumReply", back_populates="post", cascade="all, delete-orphan")
|
||
post_tags = relationship("ForumPostTag", back_populates="post", cascade="all, delete-orphan")
|
||
likes = relationship("ForumLike", back_populates="post", cascade="all, delete-orphan")
|
||
```
|
||
|
||
### 2.3 ForumReply（回复）扩展
|
||
|
||
```python
|
||
class ForumReply(BaseModel):
|
||
__tablename__ = "forum_replies"
|
||
|
||
# === 现有字段 ===
|
||
post_id: str
|
||
user_id: Optional[str]
|
||
agent_id: Optional[str]
|
||
content: str
|
||
is_ai_reply: bool = False
|
||
|
||
# === 新增字段 ===
|
||
parent_id: Optional[str] = None # 父回复（支持嵌套）
|
||
floor: int = 1 # 楼层号
|
||
is_pinned: bool = False # 置顶
|
||
is_best: bool = False # 最佳回复
|
||
is_deleted: bool = False # 软删除
|
||
like_count: int = 0
|
||
edited_at: Optional[datetime] = None # 编辑时间
|
||
|
||
# === 关系 ===
|
||
post = relationship("ForumPost", back_populates="replies")
|
||
parent = relationship("ForumReply", remote_side=[id], backref="children")
|
||
likes = relationship("ForumLike", back_populates="reply", cascade="all, delete-orphan")
|
||
```
|
||
|
||
### 2.4 ForumTag（标签）
|
||
|
||
```python
|
||
class ForumTag(BaseModel):
|
||
__tablename__ = "forum_tags"
|
||
|
||
id: str = Field(default_factory=lambda: str(uuid.uuid4()))
|
||
name: str # 标签名，如 "python"
|
||
slug: str # URL 友好名
|
||
color: str = "#666666" # 标签颜色
|
||
post_count: int = 0 # 帖子数量（缓存）
|
||
is_official: bool = False # 官方标签
|
||
board_id: Optional[str] = None # 限定板块
|
||
|
||
posts = relationship("ForumPostTag", back_populates="tag")
|
||
|
||
|
||
class ForumPostTag(BaseModel):
|
||
"""帖子-标签关联"""
|
||
__tablename__ = "forum_post_tags"
|
||
|
||
post_id: str
|
||
tag_id: str
|
||
|
||
post = relationship("ForumPost", back_populates="post_tags")
|
||
tag = relationship("ForumTag", back_populates="posts")
|
||
```
|
||
|
||
### 2.5 ForumLike（点赞）
|
||
|
||
```python
|
||
class ForumLike(BaseModel):
|
||
__tablename__ = "forum_likes"
|
||
|
||
user_id: str
|
||
post_id: Optional[str] = None
|
||
reply_id: Optional[str] = None
|
||
created_at: datetime = Field(default_factory=datetime.utcnow)
|
||
|
||
post = relationship("ForumPost", back_populates="likes")
|
||
reply = relationship("ForumReply", back_populates="likes")
|
||
```
|
||
|
||
### 2.6 ForumStats（用户统计）
|
||
|
||
```python
|
||
class ForumStats(BaseModel):
|
||
"""用户论坛统计"""
|
||
__tablename__ = "forum_stats"
|
||
|
||
user_id: str = Field(primary_key=True)
|
||
post_count: int = 0
|
||
reply_count: int = 0
|
||
like_received: int = 0 # 收到的赞
|
||
best_reply_count: int = 0 # 最佳回复数
|
||
score: int = 0 # 积分
|
||
|
||
last_post_at: Optional[datetime] = None
|
||
last_reply_at: Optional[datetime] = None
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 数据库迁移
|
||
|
||
### 3.1 新增表
|
||
|
||
```sql
|
||
-- 板块表
|
||
CREATE TABLE forum_boards (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
slug TEXT UNIQUE NOT NULL,
|
||
description TEXT,
|
||
icon TEXT,
|
||
sort_order INTEGER DEFAULT 0,
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
min_role TEXT DEFAULT 'user',
|
||
parent_id TEXT,
|
||
color TEXT
|
||
);
|
||
|
||
-- 帖子-标签关联表
|
||
CREATE TABLE forum_post_tags (
|
||
post_id TEXT NOT NULL,
|
||
tag_id TEXT NOT NULL,
|
||
PRIMARY KEY (post_id, tag_id)
|
||
);
|
||
|
||
-- 标签表
|
||
CREATE TABLE forum_tags (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL UNIQUE,
|
||
slug TEXT UNIQUE NOT NULL,
|
||
color TEXT DEFAULT '#666666',
|
||
post_count INTEGER DEFAULT 0,
|
||
is_official BOOLEAN DEFAULT FALSE,
|
||
board_id TEXT
|
||
);
|
||
|
||
-- 点赞表
|
||
CREATE TABLE forum_likes (
|
||
user_id TEXT NOT NULL,
|
||
post_id TEXT,
|
||
reply_id TEXT,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (user_id, post_id, reply_id)
|
||
);
|
||
|
||
-- 用户论坛统计表
|
||
CREATE TABLE forum_stats (
|
||
user_id TEXT PRIMARY KEY,
|
||
post_count INTEGER DEFAULT 0,
|
||
reply_count INTEGER DEFAULT 0,
|
||
like_received INTEGER DEFAULT 0,
|
||
best_reply_count INTEGER DEFAULT 0,
|
||
score INTEGER DEFAULT 0,
|
||
last_post_at TIMESTAMP,
|
||
last_reply_at TIMESTAMP
|
||
);
|
||
|
||
-- 扩展 forum_posts 表
|
||
ALTER TABLE forum_posts ADD COLUMN board_id TEXT;
|
||
ALTER TABLE forum_posts ADD COLUMN parent_id TEXT;
|
||
ALTER TABLE forum_posts ADD COLUMN tags TEXT DEFAULT '';
|
||
ALTER TABLE forum_posts ADD COLUMN is_pinned BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_posts ADD COLUMN is_locked BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_posts ADD COLUMN is_deleted BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_posts ADD COLUMN view_count INTEGER DEFAULT 0;
|
||
ALTER TABLE forum_posts ADD COLUMN like_count INTEGER DEFAULT 0;
|
||
ALTER TABLE forum_posts ADD COLUMN favorite_count INTEGER DEFAULT 0;
|
||
ALTER TABLE forum_posts ADD COLUMN share_count INTEGER DEFAULT 0;
|
||
ALTER TABLE forum_posts ADD COLUMN last_reply_at TIMESTAMP;
|
||
ALTER TABLE forum_posts ADD COLUMN last_activity_at TIMESTAMP;
|
||
|
||
-- 扩展 forum_replies 表
|
||
ALTER TABLE forum_replies ADD COLUMN parent_id TEXT;
|
||
ALTER TABLE forum_replies ADD COLUMN floor INTEGER DEFAULT 1;
|
||
ALTER TABLE forum_replies ADD COLUMN is_pinned BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_replies ADD COLUMN is_best BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_replies ADD COLUMN is_deleted BOOLEAN DEFAULT FALSE;
|
||
ALTER TABLE forum_replies ADD COLUMN like_count INTEGER DEFAULT 0;
|
||
ALTER TABLE forum_replies ADD COLUMN edited_at TIMESTAMP;
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Schema 扩展
|
||
|
||
### 4.1 ForumBoardSchema
|
||
|
||
```python
|
||
class ForumBoardCreate(BaseModel):
|
||
name: str = Field(..., max_length=100)
|
||
slug: str = Field(..., max_length=50, pattern=r"^[a-z0-9-]+$")
|
||
description: Optional[str] = None
|
||
icon: Optional[str] = None
|
||
sort_order: int = 0
|
||
min_role: str = "user"
|
||
parent_id: Optional[str] = None
|
||
color: Optional[str] = None
|
||
|
||
|
||
class ForumBoardOut(BaseModel):
|
||
id: str
|
||
name: str
|
||
slug: str
|
||
description: Optional[str]
|
||
icon: Optional[str]
|
||
sort_order: int
|
||
post_count: int = 0 # 动态计算
|
||
|
||
|
||
class ForumPostCreate(BaseModel):
|
||
title: str = Field(..., max_length=200)
|
||
content: str = Field(..., max_length=50000)
|
||
board_id: Optional[str] = None
|
||
category: Optional[str] = None
|
||
tags: List[str] = []
|
||
|
||
|
||
class ForumPostOut(BaseModel):
|
||
id: str
|
||
user_id: str
|
||
title: str
|
||
content: str
|
||
board_id: Optional[str]
|
||
board_name: Optional[str] = None
|
||
category: Optional[str]
|
||
tags: List[str] = []
|
||
reply_count: int
|
||
view_count: int
|
||
like_count: int
|
||
is_pinned: bool
|
||
is_locked: bool
|
||
created_at: datetime
|
||
last_reply_at: Optional[datetime]
|
||
user_liked: bool = False # 当前用户是否点赞
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 实现步骤
|
||
|
||
| 步骤 | 任务 | 优先级 |
|
||
|------|------|--------|
|
||
| 1 | 创建数据库迁移脚本 | 🟢 高 |
|
||
| 2 | 扩展 models/forum.py | 🟢 高 |
|
||
| 3 | 创建 ForumBoard 模型 | 🟢 高 |
|
||
| 4 | 创建 ForumTag/ForumPostTag 模型 | 🟡 中 |
|
||
| 5 | 创建 ForumLike 模型 | 🟡 中 |
|
||
| 6 | 创建 ForumStats 模型 | 🟡 中 |
|
||
| 7 | 扩展 schemas/forum.py | 🟢 高 |
|
||
| 8 | 编写单元测试 | 🟡 中 |
|
||
|
||
---
|
||
|
||
## 6. 核心文件变更
|
||
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `models/forum.py` | 新增 ForumBoard, ForumTag, ForumPostTag, ForumLike, ForumStats；扩展 ForumPost, ForumReply |
|
||
| `schemas/forum.py` | 新增 ForumBoardCreate/Out；扩展 ForumPostCreate/Out |
|
||
| `database.py` | 注册新模型 |
|
||
|
||
---
|
||
|
||
## 7. 工作量估算
|
||
|
||
| 任务 | 工作量 |
|
||
|------|--------|
|
||
| 数据库迁移脚本 | 0.5 天 |
|
||
| 模型扩展 | 0.5 天 |
|
||
| Schema 扩展 | 0.5 天 |
|
||
| 单元测试 | 0.5 天 |
|
||
| **总计** | **2 天** |
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
- [ ] ForumBoard 模型可创建/查询板块
|
||
- [ ] ForumPost 可关联板块和标签
|
||
- [ ] ForumTag 可创建/查询标签
|
||
- [ ] ForumLike 支持点赞功能
|
||
- [ ] ForumStats 正确统计用户数据
|
||
- [ ] 所有新模型有对应的 Pydantic Schema
|
||
- [ ] 迁移脚本可回滚
|
||
- [ ] 单元测试覆盖新增功能
|