NovalRedot/.claude/plan.md

大纲管理功能实现计划

概述

为小说添加大纲管理功能，大纲属于小说的子资源，支持增删改查。前端采用卷轴时间线可视化展示，契合"墨韵书斋"设计风格。

视觉设计方向

不做传统列表，而是做一条竖向卷轴时间线：

• 中央一条细线作为"墨线"，串联所有大纲节点
• 每个节点是一张展开的"纸笺"卡片，左右交替排列
• 卡片显示序号、一句话描述；hover展开详情
• 点击卡片可编辑、删除
• 底部有"添加新节点"按钮，点击弹出模态框
• 空状态：一卷未展开的空白卷轴动画
• 节点间可拖拽排序（用sort_order字段）

---

一、后端

1. 数据模型 (backend/app/models.py)

在现有Novel模型同文件新增Outline模型：

class Outline(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    novel_id: int = Field(foreign_key="novel.id", index=True)
    sort_order: int = Field(default=0)          # 排序序号
    summary: str = Field(max_length=200)        # 一句话描述
    detail: str = Field(default="", max_length=1000)  # 详情（100-300字）
    created_at: datetime = Field(default_factory=_now_utc)
    updated_at: datetime = Field(default_factory=_now_utc)

2. 请求/响应模式 (backend/app/schemas.py)

新增：

• OutlineCreate — summary(必填), detail(可选)
• OutlineUpdate — summary, detail, sort_order 均可选
• OutlineRead — 全字段
• OutlineList — items + total
• OutlineReorder — 接收排序后的id列表

3. API路由 (backend/app/routers/outlines.py)

新建路由文件，前缀 /api/novels/{novel_id}/outlines：

• GET / — 列出该小说所有大纲（按sort_order排序）
• POST / — 创建大纲（自动设置sort_order为最大值+1）
• GET /{outline_id} — 获取单个大纲
• PATCH /{outline_id} — 更新大纲
• DELETE /{outline_id} — 删除大纲
• PUT /reorder — 批量更新排序

4. 注册路由 (backend/app/main.py)

引入并挂载outlines_router。

---

二、前端

5. TypeScript类型 (frontend/src/types/outline.ts)

export interface Outline {
  id: number
  novel_id: number
  sort_order: number
  summary: string
  detail: string
  created_at: string
  updated_at: string
}
export interface OutlineCreate { summary: string; detail?: string }
export interface OutlineUpdate { summary?: string; detail?: string; sort_order?: number }
export interface OutlineList { items: Outline[]; total: number }

6. API调用 (frontend/src/api/outlines.ts)

跟随novels.ts的模式，所有请求挂在 /novels/{novelId}/outlines 下。

7. 路由 (frontend/src/router/index.ts)

新增路由：

• /novels/:id/outlines → OutlineView（大纲页面，从小说详情页进入）

8. 小说详情页更新 (NovelDetailView.vue)

添加"查看大纲"按钮/入口，链接到大纲页面。

9. 大纲视图页面 (frontend/src/views/OutlineView.vue)

主页面，包含：

• 返回小说详情的导航
• 小说标题显示
• 卷轴时间线组件
• 添加大纲的按钮

10. 卷轴时间线组件 (frontend/src/components/outline/OutlineTimeline.vue)

核心可视化组件，设计要点：

• 中央竖向墨线（2px，渐变从墨色到透明）
• 大纲节点左右交替排列（odd左even右）
• 每个节点通过横向短线连接到中央墨线
• 节点连接点有一个圆形墨点装饰
• 入场动画：依次从上到下淡入，配合墨线延伸

11. 大纲节点卡片 (frontend/src/components/outline/OutlineNode.vue)

单个大纲节点：

• 纸笺风格卡片（paper-50背景，细边框，微阴影）
• 顶部显示序号标记（朱砂红圆圈内数字）
• 一句话summary作为标题
• 默认折叠状态，hover或点击展开detail
• 展开状态下显示编辑/删除按钮
• hover微抬效果（与NovelCard一致的动效）

12. 大纲表单弹窗 (frontend/src/components/outline/OutlineFormModal.vue)

复用BaseModal + BaseInput + BaseTextarea：

• 新建/编辑共用一个组件
• summary输入框（单行，必填，max 200字）
• detail文本域（多行，100-300字建议）
• 字数统计提示

13. 大纲空状态 (frontend/src/components/outline/OutlineEmptyState.vue)

空白卷轴SVG动画 + "展开你的故事脉络"文案 + 创建按钮。

---

实施顺序

1. 后端模型 + schemas + API路由（步骤1-4）
2. 前端类型 + API层（步骤5-6）
3. 路由 + 详情页入口（步骤7-8）
4. 大纲视图页面 + 时间线组件 + 节点卡片（步骤9-11）
5. 表单弹窗 + 空状态（步骤12-13）
6. 启动后端+前端验证全流程