# Plan B: TopFans-activity-admin 后台 FastAPI + Vue3

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**父计划:** `docs/superpowers/plans/2026-06-17-moderation-report-feedback-system.md`

**Goal:** 在 TopFans-activity-admin 仓库完成审核员后台的 FastAPI 后端 + Vue3 前端

**Architecture:**
- FastAPI 路由层 `/api/admin/moderation/*`（**不依赖** topfans moderationService RPC）
- 通过共享 PostgreSQL `top-fans` 库直读写所有 moderation_* 表
- 复用现有 `verify_token` 中间件
- 业务下架/封禁：事务内双重写入（业务表软删除 + moderation_target_status UPSERT）
- 错误码 50008 vs 50009 vs 50014 在 handler 层区分

**Tech Stack:** Python 3.11+ / FastAPI / SQLAlchemy / Pydantic / pytest / Vue3 + Element Plus

**仓库:** `/Users/liulujian/Documents/code/TopFans-activity-admin`

**前置：** Plan A 阶段 1 的 9 张表已迁移到 `top-fans` 库

---

## 阶段 B.1：模型 + Schema + CRUD

### Task B.1.1: 创建 ORM 模型

**Files:**
- Create: `backend/models/moderation.py`

按 spec §3 表结构写 9 个 SQLAlchemy ORM（ReportCategory / FeedbackCategory / Report / ReportEvidence / Feedback / FeedbackEvidence / ModerationAction / ModerationTargetStatus / AdminAuditLog）。

```python
from sqlalchemy import Column, BigInteger, String, Integer, Boolean, DateTime, Text, ForeignKey, JSON
from sqlalchemy.dialects.postgresql import JSONB
from .base import Base

class Report(Base):
    __tablename__ = "reports"
    id = Column(BigInteger, primary_key=True)
    reporter_id = Column(BigInteger, nullable=False)
    star_id = Column(BigInteger)
    target_type = Column(String(30), nullable=False)
    target_id = Column(BigInteger, nullable=False)
    target_snapshot = Column(JSONB, nullable=False)
    triggered_auto_hide = Column(Boolean, default=False, nullable=False)
    category_code = Column(String(50), ForeignKey("report_categories.code", ondelete="RESTRICT", onupdate="CASCADE"), nullable=False)
    description = Column(String(500))
    is_anonymous = Column(Boolean, default=False, nullable=False)
    status = Column(String(20), default="pending", nullable=False)
    is_auto_hidden = Column(Boolean, default=False, nullable=False)
    claimed_by = Column(BigInteger)
    claimed_at = Column(BigInteger)
    resolved_action = Column(String(20))
    resolved_by = Column(BigInteger)
    resolved_at = Column(BigInteger)
    resolution_note = Column(String(500))
    created_at = Column(BigInteger, nullable=False)
    updated_at = Column(BigInteger, nullable=False)
```

**同模式**：ReportCategory / FeedbackCategory / ReportEvidence / Feedback / FeedbackEvidence / ModerationAction / ModerationTargetStatus / AdminAuditLog

### Task B.1.2: 创建 Pydantic Schema

**Files:**
- Create: `backend/schemas/moderation.py`

```python
from pydantic import BaseModel, Field
from typing import Optional, List

class ReportListItem(BaseModel):
    id: int
    target_type: str
    target_id: int
    category_code: str
    status: str
    reporter_id: int
    created_at: int
    resolved_at: Optional[int] = None
    resolved_action: Optional[str] = None

class ReportDetail(BaseModel):
    report: ReportListItem
    description: Optional[str]
    target_snapshot: dict
    evidence: List[dict]
    actions: List[dict]
    claimed_by: Optional[int]
    claimed_at: Optional[int]

class ClaimRequest(BaseModel):
    pass

class ActionRequest(BaseModel):
    action: str = Field(..., regex="^(takedown|ban|warn|dismiss|restore)$")
    note: str = Field(..., max_length=500)
    send_notification: bool = True
    restore: Optional[bool] = None  # 仅 dismiss path C 用

class BulkDismissRequest(BaseModel):
    report_ids: List[int] = Field(..., min_items=1, max_items=500)
    reason: str = Field(..., max_length=200)

class ForceReleaseRequest(BaseModel):
    reason: str = Field(..., max_length=200)
```

### Task B.1.3: 创建 CRUD 函数

**Files:**
- Create: `backend/crud/moderation_crud.py`

**关键函数**（按 spec §5.2 端点）：
```python
async def list_reports(db: AsyncSession, *, status: Optional[str], category: Optional[str],
                       target_type: Optional[str], keyword: Optional[str],
                       page: int = 1, page_size: int = 20) -> Tuple[List[Report], int]:
    q = select(Report)
    if status: q = q.where(Report.status == status)
    if category: q = q.where(Report.category_code == category)
    if target_type: q = q.where(Report.target_type == target_type)
    if keyword: q = q.where(or_(
        Report.description.ilike(f"%{keyword}%"),
        Report.target_id == int(keyword) if keyword.isdigit() else False,
    ))
    total = await db.scalar(select(func.count()).select_from(q.subquery()))
    rows = (await db.execute(q.order_by(Report.created_at.desc()).offset((page-1)*page_size).limit(page_size))).scalars().all()
    return rows, total

async def claim_report(db: AsyncSession, *, report_id: int, admin_id: int, now: int) -> int:
    """返回 affected rows（0/1）"""
    res = await db.execute(
        update(Report)
        .where(Report.id == report_id, Report.status.in_(["pending", "auto_hidden"]))
        .values(status="reviewing", claimed_by=admin_id, claimed_at=now, updated_at=now)
    )
    await db.commit()
    return res.rowcount

async def execute_action(db: AsyncSession, *, report_id: int, action: str, admin_id: int,
                         note: str, now: int, send_notification: bool, restore: Optional[bool] = None) -> Dict:
    """事务内三重写入：业务表软删除/恢复 + mts UPSERT + reports UPDATE
       返回：{affected: int, target_type, target_id, action_log_id}"""
    # 1. SELECT report 取 target_type/target_id/origin_status
    report = await db.get(Report, report_id)
    if report.status != "reviewing" or report.claimed_by != admin_id:
        return {"affected": 0, "error": "not_claimed"}  # handler 转 50008/50009

    target_type = report.target_type
    target_id = report.target_id
    origin_is_auto_hidden = report.is_auto_hidden

    # 2. 业务表软删除/恢复
    affected = 0
    if action == "takedown":
        if target_type == "asset":
            res = await db.execute(update(Asset).where(Asset.id == target_id, Asset.is_active == True)
                                    .values(is_active=False, deleted_at=now))
        else:
            res = await db.execute(update(User).where(User.id == target_id, User.is_active == True)
                                    .values(is_active=False, deleted_at=now))
        affected = res.rowcount
    elif action == "ban":
        # 仅 user_profile
        res = await db.execute(update(User).where(User.id == target_id, User.is_active == True)
                                .values(is_active=False, deleted_at=now))
        affected = res.rowcount
    elif action == "warn":
        # 不软删除 user，仅更新 mts
        affected = 0  # warn 不影响业务表
    elif action == "dismiss":
        # path C: dismiss 且曾 auto_hidden 且 restore=True → 恢复业务表
        if origin_is_auto_hidden and restore:
            if target_type == "asset":
                res = await db.execute(update(Asset).where(Asset.id == target_id, Asset.is_active == False)
                                        .values(is_active=True, deleted_at=None))
            else:
                res = await db.execute(update(User).where(User.id == target_id, User.is_active == False)
                                        .values(is_active=True, deleted_at=None))
            affected = res.rowcount
    elif action == "restore":
        # v2.2 B6 + v2.5 W6: ban/takedown 误判恢复；用 CTE 条件写 mts
        # 仅当 user_unbanned=1 时写 mts last_action_type='restore'
        if target_type == "user_profile":
            res = await db.execute(update(User).where(User.id == target_id, User.is_active == False)
                                    .values(is_active=True, deleted_at=None).returning(User.id))
            unbanned = res.fetchone()
            if unbanned:
                # UPSERT mts with last_action_type='restore'
                stmt = pg_insert(ModerationTargetStatus).values(
                    target_type=target_type, target_id=target_id, last_action_type="restore",
                    source="admin", operator_admin_id=admin_id, reason=f"unban: {note}",
                    created_at=now, updated_at=now,
                ).on_conflict_do_update(
                    index_elements=["target_type", "target_id"],
                    set_=dict(last_action_type="restore", source="admin",
                              operator_admin_id=admin_id, reason=f"unban: {note}", updated_at=now)
                )
                await db.execute(stmt)
        # 同步更新 reports.resolved_action='restore'
        await db.execute(update(Report).where(Report.id == report_id)
                        .values(resolved_action="restore", resolution_note=f"unban: {note}",
                                resolved_by=admin_id, resolved_at=now, updated_at=now))

    # 3. UPSERT mts
    last_action_type = action if action != "dismiss" else ("restore" if (origin_is_auto_hidden and restore) else "dismiss")
    mts = ModerationTargetStatus(
        target_type=target_type, target_id=target_id,
        last_action_type=last_action_type, source="admin",
        operator_admin_id=admin_id, reason=note,
        created_at=now, updated_at=now,
    )
    stmt = pg_insert(ModerationTargetStatus).values(**mts.__dict__).on_conflict_do_update(
        index_elements=["target_type", "target_id"],
        set_=dict(last_action_type=last_action_type, source="admin",
                  operator_admin_id=admin_id, reason=note, updated_at=now,
                  is_warned=case(... if action == "warn" else ...),
                  warn_count=case(... if action == "warn" else ModerationTargetStatus.warn_count + 0),
                  last_warned_at=case(... if action == "warn" else ...))
    )
    await db.execute(stmt)

    # 4. UPDATE reports.status = 'resolved' or 'dismissed'
    new_status = "resolved" if action in ["takedown", "ban", "warn", "restore"] else "dismissed"
    await db.execute(update(Report).where(Report.id == report_id)
                    .values(status=new_status, resolved_action=action, resolved_by=admin_id,
                            resolved_at=now, claimed_by=None, claimed_at=None, resolution_note=note, updated_at=now))

    # 5. 写 moderation_actions
    await db.execute(insert(ModerationAction).values(
        report_id=report_id, admin_id=admin_id, action_type=action,
        target_type=target_type, target_id=target_id, note=note,
        success=True, created_at=now,
    ))

    await db.commit()

    # 6. 通知（异步，失败不影响主流程）
    if send_notification:
        try:
            await send_notification_internal(target_type, target_id, action, note)
        except Exception as e:
            logger.warning(f"notification failed: {e}")

    return {"affected": affected, "target_type": target_type, "target_id": target_id}
```

**注意：**
- **warn** 流程：UPSERT mts SET is_warned=true, warn_count=warn_count+1, last_warned_at=now
- **dismiss path D**：不恢复业务表，mts.last_action_type='dismiss' 覆盖原 autohide
- **dismiss path C**：恢复业务表 + mts.last_action_type='restore' + 批量清理同 target 老 auto_hidden 工单

### Task B.1.4: 写其余 CRUD 函数

- `release_report` / `dismiss_path_a` (pending → dismissed) / `bulk_dismiss` / `force_release` / `withdraw_report` / `clear_warn` / `list_categories` / `upsert_category` / `delete_category` / `get_stats`

---

## 阶段 B.2：FastAPI Handler

### Task B.2.1: 写 handlers

**Files:**
- Create: `backend/handlers/moderation_admin.py`

```python
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession

from .verify_token import verify_token
from ..crud import moderation_crud
from ..schemas.moderation import *

router = APIRouter(prefix="/api/admin/moderation", tags=["moderation"])

@router.get("/reports")
async def list_reports(
    status: Optional[str] = None,
    category: Optional[str] = None,
    target_type: Optional[str] = None,
    keyword: Optional[str] = None,
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    db: AsyncSession = Depends(get_db),
    admin: dict = Depends(verify_token),
):
    rows, total = await moderation_crud.list_reports(db, status=status, category=category,
                                                      target_type=target_type, keyword=keyword,
                                                      page=page, page_size=page_size)
    return {"code": 200, "data": {"reports": [ReportListItem.from_orm(r).dict() for r in rows], "total": total}}

@router.post("/reports/{report_id}/claim")
async def claim_report(
    report_id: int,
    db: AsyncSession = Depends(get_db),
    admin: dict = Depends(verify_token),
):
    affected = await moderation_crud.claim_report(db, report_id=report_id, admin_id=admin["admin_id"], now=now_ms())
    if affected == 0:
        # handler 区分 50007/50008/50009
        report = await db.get(Report, report_id)
        if report is None:
            raise HTTPException(404, detail={"code": 50007, "message": "工单不存在"})
        if report.status == "reviewing" and report.claimed_by != admin["admin_id"]:
            raise HTTPException(409, detail={
                "code": 50008, "message": "工单已被他人认领",
                "claimed_by": report.claimed_by, "claimed_at": report.claimed_at,
            })
        if report.status in ["resolved", "dismissed"]:
            raise HTTPException(400, detail={"code": 50009, "message": "工单已结案"})
        # pending 状态但 claim 失败（异常情况）
        raise HTTPException(409, detail={"code": 50014, "message": "工单已被释放或结案，请刷新"})
    return {"code": 200, "data": {"claimed": True}}

@router.post("/reports/{report_id}/actions")
async def execute_action(
    report_id: int,
    payload: ActionRequest,
    db: AsyncSession = Depends(get_db),
    admin: dict = Depends(verify_token),
):
    result = await moderation_crud.execute_action(
        db, report_id=report_id, action=payload.action,
        admin_id=admin["admin_id"], note=payload.note,
        now=now_ms(), send_notification=payload.send_notification,
        restore=payload.restore,
    )
    if "error" in result:
        raise HTTPException(409, detail={"code": 50008, "message": "工单已被他人认领或结案"})
    return {"code": 200, "data": result}
```

### Task B.2.2: 注册路由

**Files:**
- Modify: `backend/router/__init__.py`

```python
from .moderation_admin import router as moderation_admin_router
admin_router.include_router(moderation_admin_router)
```

### Task B.2.3: 启动 + curl 验证

```bash
cd /Users/liulujian/Documents/code/TopFans-activity-admin
uvicorn backend.main:app --reload
curl http://localhost:8000/api/admin/moderation/reports -H "Authorization: Bearer $ADMIN_TOKEN"
```

---

## 阶段 B.3：单元测试

### Task B.3.1: 写测试

**Files:**
- Create: `backend/handlers/test_moderation_admin.py`

**关键测试**：
- 列表/详情/认领 happy path
- dismiss 4 路径分支
- 50008 vs 50009 vs 50014 区分
- 鉴权（无 token → 401）
- bulk_dismiss / force_release / clear_warn

---

## 阶段 B.4：Vue3 前端

### Task B.4.1: API 封装

**Files:**
- Create: `frontend/src/api/moderation.js`

按 spec §5.2 端点封装。

### Task B.4.2: 举报工单列表

**Files:**
- Create: `frontend/src/views/moderation/ReportList.vue`

Element Plus 组件：
- el-form 筛选栏（status select / category select / target_type select / keyword input）
- el-table 列表（id/target_type/target_id/category/status[el-tag]/created_at）
- el-pagination 分页
- 详情按钮 → 跳转 `/moderation/reports/:id`

### Task B.4.3: 举报详情

**Files:**
- Create: `frontend/src/views/moderation/ReportDetail.vue`

- el-descriptions 信息卡片（target_snapshot JSON 格式化展示）
- el-image preview 证据图
- el-timeline 流水
- 动作按钮组（按 status 显隐）：
  - pending / auto_hidden：认领
  - reviewing（本人）：下架 / 封禁 / 警告 / 驳回（path B/C/D 选项）/ 释放
- el-dialog 输入 action/note/send_notification/restore

### Task B.4.4: 反馈列表/详情

按举报同模式。

### Task B.4.5: 分类 CRUD 页面

- `ReportCategoryConfig.vue` / `FeedbackCategoryConfig.vue`
- el-table 列出 + el-dialog 新增/编辑 + 删除确认

### Task B.4.6: 路由 + 菜单

**Files:**
- Modify: `frontend/src/router/index.js`
- Modify: `frontend/src/layout/Layout.vue`

注册 6 个路由 + 菜单项。

---

## 自审检查清单（Plan B）

- [ ] FastAPI `/api/admin/moderation/*` 路由全部注册
- [ ] 错误码 50007/50008/50009/50014 在 handler 区分正确
- [ ] 事务内三重写入（业务表 + mts + reports）原子性
- [ ] dismiss 4 路径全覆盖
- [ ] warn 流程不软删除 user，仅更新 mts
- [ ] restore 流程用 CTE 条件写 mts（v2.5 W6）
- [ ] Vue3 路由 + 菜单注册
- [ ] pytest 全部 PASS