# Phase F.3：权限系统

日期：2026-04-04
状态：待开始
依赖：F.2（待完成）
前置：models/user.py

---

## 1. 本阶段目的

实现 Jarvis Forum 的权限系统：

- 用户角色管理（user/moderator/admin）
- 板块权限控制
- 操作日志记录
- 积分/奖励系统

---

## 2. 用户角色系统

### 2.1 角色定义

```python
class UserRole(str, Enum):
    """用户角色枚举"""
    GUEST = "guest"      # 访客 - 只能浏览
    USER = "user"         # 普通用户 - 可发帖/回复
    MODERATOR = "moderator"  # 版主 - 可管理板块
    ADMIN = "admin"       # 管理员 - 全权限


class Permission(str, Enum):
    """权限枚举"""
    # 帖子权限
    POST_CREATE = "post:create"
    POST_EDIT_OWN = "post:edit:own"
    POST_EDIT_ANY = "post:edit:any"
    POST_DELETE_OWN = "post:delete:own"
    POST_DELETE_ANY = "post:delete:any"
    POST_PIN = "post:pin"
    POST_LOCK = "post:lock"
    POST_VIEW = "post:view"
    
    # 回复权限
    REPLY_CREATE = "reply:create"
    REPLY_EDIT_OWN = "reply:edit:own"
    REPLY_DELETE_OWN = "reply:delete:own"
    REPLY_DELETE_ANY = "reply:delete:any"
    REPLY_PIN = "reply:pin"
    REPLY_BEST = "reply:best"
    
    # 板块权限
    BOARD_CREATE = "board:create"
    BOARD_EDIT = "board:edit"
    BOARD_DELETE = "board:delete"
    
    # 标签权限
    TAG_CREATE = "tag:create"
    TAG_MANAGE = "tag:manage"
    
    # 用户权限
    USER_BAN = "user:ban"
    USER_ROLE = "user:role"
    
    # 积分权限
    SCORE_VIEW = "score:view"
    SCORE_MANAGE = "score:manage"
```

### 2.2 角色权限映射

```python
ROLE_PERMISSIONS: Dict[UserRole, Set[Permission]] = {
    UserRole.GUEST: {
        Permission.POST_VIEW,
    },
    UserRole.USER: {
        Permission.POST_VIEW,
        Permission.POST_CREATE,
        Permission.POST_EDIT_OWN,
        Permission.POST_DELETE_OWN,
        Permission.REPLY_CREATE,
        Permission.REPLY_EDIT_OWN,
        Permission.REPLY_DELETE_OWN,
        Permission.SCORE_VIEW,
    },
    UserRole.MODERATOR: {
        # 用户权限
        Permission.POST_VIEW,
        Permission.POST_CREATE,
        Permission.POST_EDIT_OWN,
        Permission.POST_DELETE_OWN,
        Permission.REPLY_CREATE,
        Permission.REPLY_EDIT_OWN,
        Permission.REPLY_DELETE_OWN,
        # 版主权限
        Permission.POST_PIN,
        Permission.POST_LOCK,
        Permission.POST_DELETE_ANY,
        Permission.REPLY_PIN,
        Permission.REPLY_BEST,
        Permission.TAG_MANAGE,
        Permission.SCORE_VIEW,
    },
    UserRole.ADMIN: set(Permission),  # 所有权限
}
```

---

## 3. User 模型扩展

### 3.1 新增字段

```python
# models/user.py 扩展
class User(BaseModel):
    __tablename__ = "users"
    
    # === 现有字段 ===
    id: str
    username: str
    email: str
    hashed_password: str
    avatar: Optional[str]
    created_at: datetime
    
    # === Forum 相关扩展 ===
    role: str = "user"  # guest/user/moderator/admin
    forum_score: int = 0  # 论坛积分
    
    # 论坛统计
    post_count: int = 0
    reply_count: int = 0
    like_received: int = 0
    best_reply_count: int = 0
    
    # 状态
    is_forum_banned: bool = False  # 论坛禁言
    forum_ban_until: Optional[datetime] = None  # 禁言截止时间
    
    # 板块版主关系
    moderated_boards: List[str] = []  # 管理的板块 ID 列表
```

---

## 4. Permission Service

### 4.1 服务实现

```python
class PermissionService:
    """权限服务"""
    
    def __init__(self, db: AsyncSession):
        self.db = db
    
    def has_permission(self, user: User, permission: Permission) -> bool:
        """检查用户是否拥有某权限"""
        if user.is_forum_banned:
            return False
        if user.forum_ban_until and user.forum_ban_until > datetime.utcnow():
            return False
        
        role = UserRole(user.role)
        return permission in ROLE_PERMISSIONS.get(role, set())
    
    def has_board_permission(
        self,
        user: User,
        permission: Permission,
        board_id: str,
    ) -> bool:
        """检查用户在特定板块的权限"""
        if not self.has_permission(user, permission):
            return False
        
        # 版主只能管理自己板块
        if role == UserRole.MODERATOR:
            return board_id in user.moderated_boards
        
        return True
    
    async def can_edit_post(self, user: User, post: ForumPost) -> bool:
        """检查用户是否可以编辑帖子"""
        if user.role == UserRole.ADMIN:
            return True
        if user.role == UserRole.MODERATOR:
            return post.board_id in user.moderated_boards
        return post.user_id == user.id
    
    async def can_delete_post(self, user: User, post: ForumPost) -> bool:
        """检查用户是否可以删除帖子"""
        if user.role == UserRole.ADMIN:
            return True
        if user.role == UserRole.MODERATOR:
            return post.board_id in user.moderated_boards
        return post.user_id == user.id
    
    async def ban_user(
        self,
        admin: User,
        target_user_id: str,
        reason: str,
        duration: Optional[timedelta] = None,
    ) -> None:
        """禁言用户"""
        if admin.role != UserRole.ADMIN:
            raise PermissionError("需要管理员权限")
        
        result = await self.db.execute(
            select(User).where(User.id == target_user_id)
        )
        target_user = result.scalar_one_or_none()
        
        if not target_user:
            raise ValueError("用户不存在")
        
        target_user.is_forum_banned = True
        target_user.forum_ban_until = (
            datetime.utcnow() + duration if duration else None
        )
        
        # 记录操作日志
        await self._log_action(
            admin=admin,
            action="ban_user",
            target_id=target_user_id,
            details={"reason": reason, "duration": str(duration)},
        )
```

### 4.2 依赖注入

```python
# 在 ForumService 中注入
class ForumService:
    def __init__(
        self,
        db: AsyncSession,
        lock_manager: ForumLockManager,
        permission_service: PermissionService,
    ):
        self.db = db
        self.lock = lock_manager
        self.perms = permission_service
```

---

## 5. 操作日志

### 5.1 日志模型

```python
class ForumLog(BaseModel):
    __tablename__ = "forum_logs"
    
    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
    user_id: str  # 操作者
    action: str  # 操作类型
    target_type: str  # post/reply/board/user/tag
    target_id: str  # 目标 ID
    details: Optional[str] = None  # JSON 详情
    ip_address: Optional[str] = None
    user_agent: Optional[str] = None
    created_at: datetime = Field(default_factory=datetime.utcnow)
```

### 5.2 日志记录

```python
async def _log_action(
    self,
    admin: User,
    action: str,
    target_id: str,
    details: Optional[dict] = None,
    request: Optional[Request] = None,
) -> None:
    """记录操作日志"""
    log = ForumLog(
        user_id=admin.id,
        action=action,
        target_type=action.split(":")[0],
        target_id=target_id,
        details=json.dumps(details) if details else None,
        ip_address=request.client.host if request else None,
        user_agent=request.headers.get("user-agent") if request else None,
    )
    self.db.add(log)
    await self.db.commit()


# 日志操作类型
class ForumAction(str, Enum):
    POST_CREATE = "post:create"
    POST_UPDATE = "post:update"
    POST_DELETE = "post:delete"
    POST_PIN = "post:pin"
    POST_LOCK = "post:lock"
    REPLY_CREATE = "reply:create"
    REPLY_UPDATE = "reply:update"
    REPLY_DELETE = "reply:delete"
    USER_BAN = "user:ban"
    USER_UNBAN = "user:unban"
    SCORE_CHANGE = "score:change"
    BOARD_CREATE = "board:create"
    BOARD_UPDATE = "board:update"
    BOARD_DELETE = "board:delete"
```

---

## 6. 积分系统

### 6.1 积分规则

```python
SCORE_RULES = {
    # 帖子相关
    "post_create": 5,         # 发帖
    "post_delete": -5,       # 删除帖子
    "post_liked": 2,          # 帖子被点赞
    "post_best": 10,          # 帖子被设为精华
    
    # 回复相关
    "reply_create": 2,         # 回复
    "reply_delete": -2,        # 删除回复
    "reply_liked": 1,          # 回复被点赞
    "reply_best": 5,          # 回复被设为最佳
    "reply_adopted": 10,      # 提问被采纳
    
    # 活跃相关
    "daily_login": 1,         # 每日登录
    "daily_post": 3,          # 每日首次发帖
    "daily_reply": 1,         # 每日首次回复
}


class ScoreService:
    """积分服务"""
    
    def __init__(self, db: AsyncSession):
        self.db = db
    
    async def add_score(
        self,
        user_id: str,
        action: str,
        reason: str,
    ) -> int:
        """增加积分"""
        score_delta = SCORE_RULES.get(action, 0)
        
        result = await self.db.execute(
            select(User).where(User.id == user_id)
        )
        user = result.scalar_one_or_none()
        
        if user:
            user.forum_score += score_delta
            
            # 更新统计
            if action.startswith("post_"):
                user.post_count += 1
            elif action.startswith("reply_"):
                user.reply_count += 1
            
            if action == "post_liked":
                user.like_received += 1
            elif action == "reply_liked":
                user.like_received += 1
            elif action == "reply_best":
                user.best_reply_count += 1
            
            await self.db.commit()
        
        return score_delta
    
    async def get_leaderboard(
        self,
        limit: int = 10,
        period: str = "all",  # all/month/week
    ) -> List[dict]:
        """获取积分排行榜"""
        query = select(User).where(User.forum_score > 0)
        
        if period == "month":
            # 本月排行
            pass
        elif period == "week":
            # 本周排行
            pass
        
        query = query.order_by(desc(User.forum_score)).limit(limit)
        result = await self.db.execute(query)
        
        return [
            {
                "rank": i + 1,
                "user_id": user.id,
                "username": user.username,
                "avatar": user.avatar,
                "score": user.forum_score,
            }
            for i, user in enumerate(result.scalars().all())
        ]
```

---

## 7. API 端点

### 7.1 管理端点

```python
@router.post("/admin/ban/{user_id}")
async def ban_user(
    user_id: str,
    reason: str,
    duration: Optional[int] = None,  # 天数
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    """禁言用户（仅管理员）"""
    if current_user.role != "admin":
        raise HTTPException(status_code=403, detail="需要管理员权限")
    
    perm_service = PermissionService(db)
    await perm_service.ban_user(
        admin=current_user,
        target_user_id=user_id,
        reason=reason,
        duration=timedelta(days=duration) if duration else None,
    )
    return {"success": True}


@router.post("/admin/unban/{user_id}")
async def unban_user(
    user_id: str,
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    """解除禁言"""
    if current_user.role != "admin":
        raise HTTPException(status_code=403, detail="需要管理员权限")
    
    perm_service = PermissionService(db)
    await perm_service.unban_user(current_user, user_id)
    return {"success": True}


@router.get("/admin/logs")
async def get_logs(
    target_id: Optional[str] = None,
    action: Optional[str] = None,
    page: int = 1,
    page_size: int = 50,
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    """查看操作日志（仅管理员/版主）"""
    if current_user.role not in ["admin", "moderator"]:
        raise HTTPException(status_code=403, detail="权限不足")
    
    # 查询日志...
    return {"logs": [], "total": 0}


@router.get("/leaderboard")
async def get_leaderboard(
    limit: int = 10,
    period: str = "all",
    db: AsyncSession = Depends(get_db),
):
    """获取积分排行榜"""
    score_service = ScoreService(db)
    return await score_service.get_leaderboard(limit, period)
```

---

## 8. 实现步骤

| 步骤 | 任务 | 优先级 |
|------|------|--------|
| 1 | 扩展 User 模型 | 🟢 高 |
| 2 | 创建 PermissionService | 🟢 高 |
| 3 | 实现权限检查装饰器 | 🟢 高 |
| 4 | 创建 ForumLog 模型 | 🟡 中 |
| 5 | 实现操作日志记录 | 🟡 中 |
| 6 | 创建 ScoreService | 🟡 中 |
| 7 | 实现积分规则 | 🟡 中 |
| 8 | 扩展管理 API | 🟡 中 |
| 9 | 单元测试 | 🟡 中 |

---

## 9. 核心文件变更

| 文件 | 变更 |
|------|------|
| `models/user.py` | 扩展角色和统计字段 |
| `models/forum.py` | 新增 ForumLog |
| `services/permission_service.py` | 新增 |
| `services/score_service.py` | 新增 |
| `services/forum_service.py` | 集成权限检查 |
| `routers/forum.py` | 扩展管理端点 |

---

## 10. 工作量估算

| 任务 | 工作量 |
|------|--------|
| User 模型扩展 | 0.5 天 |
| PermissionService | 0.5 天 |
| 操作日志 | 0.5 天 |
| ScoreService | 0.5 天 |
| API 端点 | 0.5 天 |
| 单元测试 | 0.5 天 |
| **总计** | **3 天** |

---

## 11. 验收标准

- [ ] User 模型正确存储角色和积分
- [ ] PermissionService 可正确检查权限
- [ ] 权限不足时返回 403
- [ ] 所有管理操作记录日志
- [ ] 积分根据规则正确增减
- [ ] 排行榜正确排序
- [ ] 禁言功能正常工作
- [ ] 单元测试覆盖核心逻辑