1.1 页面结构#

1
┌─────────────────────────────────────────────────────────┐
2
│ Header: Logo + 标题 + 筛选栏 + 用户信息                │
3
├─────────────────────────────────────────────────────────┤
4
│                                                         │
5
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
6
│  │ 待处理   │ │  待办    │ │ 进行中   │ │ 已完成   │  │
7
│  │   (3)    │ │   (5)    │ │   (2)    │ │   (8)    │  │
8
│  ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤  │
9
│  │          │ │          │ │          │ │          │  │
10
│  │ [卡片1]  │ │ [卡片4]  │ │ [卡片9]  │ │ [卡片12] │  │
11
│  │ [卡片2]  │ │ [卡片5]  │ │ [卡片10] │ │ [卡片13] │  │
12
│  │ [卡片3]  │ │ [卡片6]  │ │          │ │ [卡片14] │  │
13
│  │          │ │ [卡片7]  │ │          │ │ [卡片15] │  │
14
│  │          │ │ [卡片8]  │ │          │ │   ...    │  │
15
│  │          │ │          │ │          │ │          │  │
16
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
17
│                                                         │
18
└─────────────────────────────────────────────────────────┘

1.2 响应式布局#

• 桌面端（>1024px）：横向看板视图
• 平板端（768-1024px）：横向滚动看板
• 移动端（<768px）：纵向列表视图

2.1 Header 组件#

位置：页面顶部固定

内容：

1
┌─────────────────────────────────────────────────────────┐
2
│ [Logo] 任务看板      [搜索框] [筛选] [添加]    [头像]  │
3
└─────────────────────────────────────────────────────────┘

样式要求：

• 高度：64px
• 背景：白色
• 阴影：box-shadow: 0 1px 3px rgba(0,0,0,0.1)
• 内边距：0 24px

2.2 BoardColumn（看板列）组件#

尺寸：

• 宽度：320px
• 最小高度：calc(100vh - 64px)
• 列间距：24px

结构：

1
┌────────────────┐
2
│ 标题 + 数量      │
3
├────────────────┤
4
│                │
5
│ [任务卡片]      │
6
│ [任务卡片]      │
7
│ [任务卡片]      │
8
│                │
9
│ [+ 新建任务]    │
10
└────────────────┘

列标题：

• 字体：14px, semibold
• 颜色：gray-700
• 圆角：8px

新建按钮：

• 显示在列底部
• 虚线边框
• hover 时填充背景色
• 图标：+

2.3 TaskCard（任务卡片）组件#

尺寸：

• 宽度：280px
• 最小高度：120px
• 圆角：8px
• 内边距：16px

结构：

1
┌──────────────────────────┐
2
│ 🔴 🔵                    │
3
│ 任务标题                  │
4
│                          │
5
│ 🏷️ 设计 🔖 开发         │
6
│                          │
7
│ 👤 张三   📅 1月15日     │
8
└──────────────────────────┘

内容层级：

1. 顶部：优先级标签 + 更多操作（三点菜单）
2. 标题：最多 2 行，超出省略
3. 标签：最多显示 3 个，超出显示 “+N”
4. 底部：指派人头像 + 截止日期

样式：

• 背景：白色
• 边框：1px solid gray-200
• 阴影：hover 时 box-shadow: 0 4px 12px rgba(0,0,0,0.1)
• 过渡：all 0.2s ease

优先级颜色：

• critical：red-500
• high：orange-500
• medium：yellow-500
• low：green-500

标签样式：

• 背景：gray-100
• 文字：gray-600
• 字号：12px
• 圆角：4px
• 内边距：2px 8px

2.4 FilterBar（筛选栏）组件#

位置：Header 右侧

筛选条件：

• 指派人（下拉选择）
• 优先级（下拉选择）
• 标签（下拉多选）

样式：

• 按钮高度：36px
• 圆角：6px
• 间距：8px

2.5 SearchInput（搜索框）组件#

位置：Header 中间偏左

样式：

• 宽度：300px
• 高度：36px
• 圆角：6px
• 占位符：“搜索任务…”

行为：

• 防抖：300ms
• 清除按钮

2.6 TaskDetailDrawer（任务详情抽屉）组件#

位置：页面右侧滑出

宽度：480px

结构：

1
┌─────────────────────────────┐
2
│ 任务详情              [×]   │
3
├─────────────────────────────┤
4
│ 标题                        │
5
│ 描述                        │
6
│ 状态、优先级、指派人        │
7
│ 标签                        │
8
│ 截止日期                    │
9
│                             │
10
│ [编辑] [删除]               │
11
└─────────────────────────────┘

3.1 拖拽交互#

视觉反馈：

• 拖拽时：卡片透明度 0.8，阴影增强
• 悬停在列上时：列高亮显示
• 放置预览：显示虚线框

动画：

• 平滑移动：0.2s ease
• 位置调整：spring animation

3.2 Hover 状态#

卡片 hover：

• 阴影增强
• 更多操作按钮出现

按钮 hover：

• 背景色变化
• 轻微放大

3.3 点击交互#

点击卡片：

• 打开详情抽屉

点击更多：

• 显示菜单（编辑、删除、移动）

点击新建：

• 打开创建弹窗（内联或弹窗）

3.4 空状态#

空列：

• 显示虚线占位
• 提示文字：“暂无任务，点击创建”

无搜索结果：

• 显示空状态插画
• 提示文字：“未找到匹配的任务”

3.5 Loading 状态#

首次加载：

• 显示骨架屏
• 4 列各 3 个卡片骨架

操作中：

• 按钮显示 loading 图标
• 禁用其他操作

4.1 主题色#

• Primary：blue-600 (#2563eb)
• Success：green-600 (#16a34a)
• Warning：yellow-600 (#ca8a04)
• Danger：red-600 (#dc2626)

4.2 中性色#

• gray-50: #f9fafb
• gray-100: #f3f4f6
• gray-200: #e5e7eb
• gray-300: #d1d5db
• gray-400: #9ca3af
• gray-500: #6b7280
• gray-600: #4b5563
• gray-700: #374151
• gray-800: #1f2937
• gray-900: #111827

4.3 语义色#

• Info：blue-500
• Success：green-500
• Warning：yellow-500
• Error：red-500

5.1 字体家族#

• 中文：-apple-system, “PingFang SC”, “Microsoft YaHei”
• 英文/数字：SF Pro Text, Inter, system-ui

5.2 字体大小#

• 12px：辅助信息（标签、日期）
• 14px：正文、按钮
• 16px：卡片标题
• 18px：二级标题
• 20px：一级标题
• 24px：大标题

5.3 字重#

• regular：400
• medium：500
• semibold：600
• bold：700

约定说明#

优先级映射

• P0：规格中明确标注 P0 的部分 —— 数据模型、API 2.1~2.4、基础功能 3.1、UI 核心组件与拖拽
• P1：规格中明确标注 P1 的部分 —— DELETE 接口 2.5、增强功能 3.2、体验优化 3.3
• P2：规格 P1 列表中可延后的可选项（自定义列、批量操作、键盘快捷键）。若团队希望严格对齐 spec，可整体上调为 P1

工作量单位：1 轮 = 一次完整的「需求理解 → AI 代码生成 → 自检/修复（lint、冒烟）」循环。0.5 轮 = 单点小改动。

执行顺序：按阶段从上到下执行（先做排最前），同阶段任务可并行。任务间的硬依赖见每项「依赖」字段。

阶段 0：数据模型与设计基础（无依赖，最先做）#

• T1｜定义数据模型与 TS 类型（P0｜0.5 轮）

  • 依赖：无
  • 内容：实现 spec §1 的 Task、TaskStatus、Priority、User 类型
  • 验收标准：
    • Task 含 id / title / description? / status / priority / assignee? / tags / dueDate? / createdAt / updatedAt 全字段
    • TaskStatus 精确为 backlog | todo | in-progress | done 四种取值
    • Priority 精确为 critical | high | medium | low 四种取值
    • 类型文件可被前后端共享引用，编译零错误

• T2｜搭建项目脚手架与设计系统 Token（P0｜1 轮）

  • 依赖：无
  • 内容：按 UI spec §4~§7 落地颜色 / 字体 / 间距 / 圆角设计变量，建立基础样式层
  • 验收标准：
    • 主题色 4 个（blue-600 #2563eb、green-600 #16a34a、yellow-600 #ca8a04、red-600 #dc2626）已配置
    • 中性色 gray-50~900 共 10 档值全部按 spec 落地
    • 语义色 Info/Success/Warning/Error 4 个已配置
    • 字号 12/14/16/18/20/24px 六档、字重 400/500/600/700 可复用
    • 间距 4/8/12/16/24/32px、圆角 4/6/8/12/16px 已定义为可复用变量（CSS 变量或主题对象）
    • 默认字体栈包含 PingFang SC / Microsoft YaHei 中文回退

阶段 1：后端 API 层（依赖 T1；如需可先以 Mock 驱动阶段 2/3）#

• T3｜GET /api/tasks 列表接口（含筛选与排序）（P0｜1 轮）

  • 依赖：T1
  • 内容：实现 spec 2.1，支持 status / assignee / search 三个可选 query，并落地业务规则 2（列内排序）
  • 验收标准：
    • 响应结构为 { tasks: Task[] }
    • status 过滤只接受合法 TaskStatus 值，非法值返回 400
    • assignee 按指派用户 id 精确过滤；search 匹配标题/描述关键词
    • 三参数可任意组合使用
    • 同状态内任务默认排序：critical > high > medium > low，同优先级按 createdAt 升序
    • 全部条件省略时返回全量任务

• T4｜POST /api/tasks 创建接口（P0｜1 轮）

  • 依赖：T1、T3
  • 内容：实现 spec 2.2，落地业务规则 3（标签限制）
  • 验收标准：
    • title、priority 必填，缺失返回 400
    • assigneeId 若提供则必须存在对应用户，否则 400
    • 标签校验：自动去重后数量 ≤ 5，单项长度 ≤ 20 字符，超限返回 400
    • 服务端自动生成 id，设置 status = backlog、createdAt/updatedAt = 当前时间
    • 响应为 { task: Task }，回显字段完整
    • 可选 dueDate 以 ISO 日期存储

• T5｜PATCH /api/tasks/ 更新接口（P0｜1 轮）

  • 依赖：T3、T4
  • 内容：实现 spec 2.3 的部分字段更新，落地业务规则 1（时间戳自动更新）
  • 验收标准：
    • 支持 title / description / status / priority / assigneeId / tags / dueDate 任一或组合更新
    • 标签字段被更新时同样执行 ≤5 个、≤20 字符校验
    • status 被置为 done 时，updatedAt 自动刷新为当前时间；其他更新同样刷新 updatedAt
    • 目标任务不存在返回 404；非法枚举值返回 400
    • 响应为 { task: Task }

• T6｜POST /api/tasks//move 移动接口（P0｜0.5 轮）

  • 依赖：T3、T5
  • 内容：实现 spec 2.4 的跨列移动与列内排序
  • 验收标准：
    • Body 接收 status（必填）与 position?（目标索引）
    • 跨列移动：任务状态更新为新列，并正确插入 position 指定位置
    • 同列移动：仅调整该任务在列内的位置
    • 目标任务不存在返回 404；position 越界时按边界值安全处理（不报 500）
    • 响应为 { task: Task }，且后续 GET 返回的顺序与移动结果一致

• T7｜DELETE /api/tasks/ 删除接口（P1｜0.5 轮）

  • 依赖：T3
  • 内容：实现 spec 2.5，落地业务规则 4
  • 验收标准：
    • 删除成功返回 { success: true }
    • 已删除/不存在任务再次删除返回 404
    • 若启用「仅已完成可删除」可选规则：非 done 状态任务删除返回 403（规则开关需在配置中可切换）
    • 删除后 GET 列表不再返回该任务

阶段 2：UI 基础组件（依赖 T2；联调 T3）#

• T8｜Header 全局头部组件（P0｜0.5 轮）

  • 依赖：T2
  • 内容：实现 UI spec §2.1 页面顶部栏
  • 验收标准：
    • 高度 64px、背景白色、box-shadow: 0 1px 3px rgba(0,0,0,0.1)、内边距 0 24px
    • 左侧为 Logo + 「任务看板」标题
    • 预留搜索框 / 筛选 / 添加按钮 / 用户头像的插槽或占位，便于 T17/T18 与创建入口接入

• T9｜BoardColumn 看板列组件（P0｜1 轮）

  • 依赖：T2
  • 内容：实现 UI spec §2.2 单列容器
  • 验收标准：
    • 宽度 320px、最小高度 calc(100vh - 64px)、列间距 24px
    • 列标题：14px semibold、gray-700、圆角 8px，右侧显示该列任务数量徽标
    • 列底部的「+ 新建任务」按钮：虚线边框，hover 填充背景色
    • 内容区可横向容纳 280px 卡片
    • 空列状态下显示虚线占位与提示「暂无任务，点击创建」（UI spec §3.4）

• T10｜TaskCard 任务卡片组件（P0｜1 轮）

  • 依赖：T2
  • 内容：实现 UI spec §2.3 卡片渲染与视觉状态
  • 验收标准：
    • 尺寸 280px 宽 / 最小高度 120px / 圆角 8px / 内边距 16px，白底 + 1px gray-200 边框
    • 顶部：优先级色点（critical=red-500、high=orange-500、medium=yellow-500、low=green-500）+ 更多操作（三点菜单）
    • 标题最多显示 2 行，超出省略号截断
    • 标签：gray-100 背景、gray-600 文字、12px、圆角 4px、内边距 2px 8px，最多显示 3 个，超出显示「+N」
    • 底部：指派人头像 + 截止日期（12px 辅助信息样式）
    • hover：阴影增强为 0 4px 12px rgba(0,0,0,0.1)，过渡 all 0.2s ease，三点菜单浮现

• T11｜看板主页面：4 列数据渲染与排序（P0｜1 轮）

  • 依赖：T3、T8、T9、T10
  • 内容：组装页面结构（Header + 4 列），首次拉取数据并按规则分组排序展示
  • 验收标准：
    • 页面结构匹配 UI spec §1.1（Header 顶部 + 横向 4 列）
    • 4 列依次为：待处理(backlog)、待办(todo)、进行中(in-progress)、已完成(done)
    • 每列数量徽标与任务数一致
    • 卡片在同一列内按优先级（critical>high>medium>low）与创建时间排序
    • 首次进入页面自动请求一次任务列表，数据加载完成后渲染

阶段 3：核心交互（依赖阶段 1 API + 阶段 2 组件）#

• T12｜创建任务交互（P0｜1 轮）

  • 依赖：T4、T9
  • 内容：实现「+ 新建任务」入口与创建弹窗（UI spec §3.3），对接 POST
  • 验收标准：
    • 点击列底或 Header「添加」按钮打开创建弹窗（弹窗圆角 12px）
    • 表单字段：标题（必填）、描述、优先级（默认 medium）、指派人、标签、截止日期
    • 标题为空或优先级缺失时给出校验提示，禁止提交
    • 标签输入限制：最多 5 个、每个 ≤20 字符，超限即时提示
    • 提交成功：关闭弹窗，新卡片出现在目标列正确排序位置；提交失败：弹窗内展示错误且保留输入

• T13｜TaskDetailDrawer 详情抽屉与查看（P0｜1 轮）

  • 依赖：T5、T10
  • 内容：实现 UI spec §2.6 详情抽屉（点击卡片打开）
  • 验收标准：
    • 点击卡片从右侧滑出抽屉，宽度 480px，含关闭按钮（点击 X / 遮罩 / Esc 可关闭）
    • 展示：标题、描述、状态、优先级、指派人、标签、截止日期（与 spec §2.6 结构一致）
    • 抽屉底部提供「编辑」「删除」操作位
    • 展示数据与看板卡片实时一致（同一数据源）

• T14｜编辑任务（抽屉内编辑）（P0｜1 轮）

  • 依赖：T5、T13
  • 内容：在详情抽屉中进入编辑态并保存（PATCH），落地状态流转规则
  • 验收标准：
    • 点击「编辑」后抽屉切换为可编辑表单，字段与创建表单一致且预填当前值
    • 可修改标题/描述/状态/优先级/指派人/标签/截止日期
    • 保存后：抽屉回到详情态，看板卡片与数量即时更新，无需整页刷新
    • 状态置为「已完成」保存成功后卡片移动至 done 列（updatedAt 已由后端刷新）
    • 保存失败时展示错误并保留编辑内容

• T15｜拖拽移动与排序（P0｜2 轮，最高风险项）

  • 依赖：T6、T11、T10
  • 内容：实现跨列拖拽 + 列内拖拽排序（UI spec §3.1），对接 move 接口
  • 验收标准：
    • 卡片可被拖起；拖拽中视觉：透明度 0.8、阴影增强（hover 阴影）
    • 拖过列时目标列高亮；悬停目标位置显示虚线放置预览
    • 可跨列拖拽（调用 move 接口切换状态）与列内拖拽（调整 position 顺序）
    • 释放后动画平滑移动（0.2s ease），位置调整带 spring 手感
    • 接口失败时卡片回弹至原位置并给出错误提示，不出现「幽灵卡片」
    • 拖动结束后列内顺序、列数量与服务端 GET 结果一致

• T16｜删除任务（含二次确认）（P1｜0.5 轮）

  • 依赖：T7、T13、T15
  • 内容：从详情抽屉/三点菜单触发删除，落地业务规则 4 二次确认
  • 验收标准：
    • 删除入口：详情抽屉「删除」按钮、卡片三点菜单（编辑/删除/移动）中的删除项
    • 点击删除弹出二次确认框，明确提示不可恢复
    • 确认后调用 DELETE 成功则卡片从看板移除、数量徽标更新
    • 取消时不发生任何变更；接口失败展示错误

阶段 4：筛选与搜索（P1，依赖阶段 3 完成后数据流稳定）#

• T17｜FilterBar 筛选栏（P1｜1 轮）

  • 依赖：T8、T11
  • 内容：实现 UI spec §2.4（Header 内），支持指派人 / 优先级 / 标签三组筛选
  • 验收标准：
    • 按钮高度 36px、圆角 6px、间距 8px，位于 Header 右侧
    • 指派人下拉（单选）、优先级下拉（单选）、标签下拉（多选）均可操作
    • 三个条件可组合过滤，看板即时只剩满足条件的任务，数量徽标随之更新
    • 优先级筛选映射为对应颜色/文案展示
    • 提供一键清除全部筛选；无任务命中时展示对应空态提示

• T18｜SearchInput 搜索框（P1｜0.5 轮）

  • 依赖：T8、T11
  • 内容：实现 UI spec §2.5 搜索，300ms 防抖，对接 GET 的 search
  • 验收标准：
    • 输入框宽 300px、高 36px、圆角 6px、占位符「搜索任务…」，位于 Header 中间偏左
    • 输入后 300ms 防抖触发搜索（避免每击键一次请求）
    • 右侧有清除按钮，点击清空并恢复全量列表
    • 无命中时看板显示空态（「未找到匹配的任务」）

阶段 5：体验优化（P1，可与阶段 4 并行）#

• T19｜Loading 骨架屏与操作中状态（P1｜0.5 轮）

  • 依赖：T11
  • 内容：实现 UI spec §3.5
  • 验收标准：
    • 首次加载时 4 列各显示 3 个卡片骨架屏（非闪烁文字/白屏）
    • 数据到达后骨架屏平滑切换为真实卡片
    • 创建/更新/删除等操作进行中：触发按钮显示 loading 图标并禁用，防止重复提交

• T20｜空状态完善（P1｜0.5 轮）

  • 依赖：T9、T11、T17/T18
  • 内容：覆盖列空、整板空、无搜索结果三类空态（UI spec §3.4）
  • 验收标准：
    • 空列：虚线占位 + 「暂无任务，点击创建」，点击可创建
    • 全局无任何任务：展示引导性空态插画/文案
    • 筛选/搜索无结果：展示空态插画 + 「未找到匹配的任务」

• T21｜响应式适配（平板/移动）（P1｜1 轮）

  • 依赖：T11、T15
  • 内容：实现 UI spec §1.2 三档布局
  • 验收标准：

    • 1024px：横向 4 列看板完整展示

    • 768~1024px：看板整体横向滚动（列宽 320px 保持）
    • <768px：切换为纵向列表视图，每行展示任务关键信息，可展开详情
    • 移动端隐藏/降级拖拽能力（通过详情/菜单完成状态变更），操作可用且无布局溢出

阶段 6：可选项增强（P2，建议最后排期）#

• T22｜键盘快捷键（P2｜0.5 轮）

  • 依赖：T13、T18
  • 内容：为高频操作提供快捷键
  • 验收标准：
    • 至少实现：Cmd/Ctrl+K 聚焦搜索、N（非输入态）新建任务、Esc 关闭抽屉/弹窗/菜单
    • 输入框/文本域聚焦时快捷键不误触发
    • 快捷键列表在界面可发现（如帮助提示），无快捷键冲突

• T23｜添加自定义列（P2｜1.5 轮）

  • 依赖：T6、T9、T11、T16
  • 内容：在默认 4 列外支持用户自定义列（spec 3.2）
  • 验收标准：
    • 提供「+ 添加列」入口，可自定义列名并持久化（刷新后仍存在）
    • 默认 4 列不可删除，自定义列可重命名/删除
    • 自定义列同样支持任务拖入、排序、数量徽标与创建按钮
    • 数据模型需扩展列配置存储并保持向后兼容

• T24｜批量操作（P2｜1.5 轮）

  • 依赖：T5、T7、T11、T16
  • 内容：批量变更状态 / 批量删除 / 批量指派（spec 3.2）
  • 验收标准：
    • 提供批量选择模式（列/全局全选、多卡片勾选）
    • 支持批量移动到指定列（逐条调用 move 或提供批量端点）
    • 批量删除前有二次确认；批量指派可选择目标用户
    • 批量操作完成后列表、徽标数量即时刷新；失败任务有明确提示与回滚提示

1. 数据模型#

1
interface Task {
2
  id: string;                    // 唯一标识
3
  title: string;                 // 任务标题
4
  description?: string;          // 任务描述
5
  status: TaskStatus;            // 状态
6
  priority: Priority;            // 优先级
7
  assignee?: User;               // 指派人
8
  tags: string[];                // 标签
9
  dueDate?: string;              // 截止日期
10
  createdAt: string;             // 创建时间
11
  updatedAt: string;             // 更新时间
12
}

1
type TaskStatus =
2
  | 'backlog'      // 待处理
3
  | 'todo'         // 待办
4
  | 'in-progress'  // 进行中
5
  | 'done';        // 已完成

1
type Priority =
2
  | 'critical'     // 紧急
3
  | 'high'         // 高
4
  | 'medium'       // 中
5
  | 'low';         // 低

1
interface User {
2
  id: string;
3
  name: string;
4
  avatar?: string;
5
}

2. API 接口#

1
GET /api/tasks
2
Query Parameters:
3
  - status?: TaskStatus    // 按状态筛选
4
  - assignee?: string      // 按指派人筛选
5
  - search?: string        // 搜索关键词
6

7
Response:
8
{
9
  tasks: Task[]
10
}

1
POST /api/tasks
2
Body:
3
{
4
  title: string;
5
  description?: string;
6
  priority: Priority;
7
  assigneeId?: string;
8
  tags?: string[];
9
  dueDate?: string;
10
}
11

12
Response:
13
{
14
  task: Task
15
}

1
PATCH /api/tasks/:id
2
Body:
3
{
4
  title?: string;
5
  description?: string;
6
  status?: TaskStatus;
7
  priority?: Priority;
8
  assigneeId?: string;
9
  tags?: string[];
10
  dueDate?: string;
11
}
12

13
Response:
14
{
15
  task: Task
16
}

1
POST /api/tasks/:id/move
2
Body:
3
{
4
  status: TaskStatus;
5
  position?: number;  // 新位置索引
6
}
7

8
Response:
9
{
10
  task: Task
11
}

1
DELETE /api/tasks/:id
2

3
Response:
4
{
5
  success: true
6
}

3. 功能需求#

4. 业务规则#

1. 状态流转限制：

   • 任务可以从任意状态移动到任意状态
   • 移动到 “已完成” 状态时，自动更新 updatedAt 时间

2. 优先级排序：

   • 同一列内，任务按优先级排序（critical > high > medium > low）
   • 相同优先级按创建时间排序

3. 标签限制：

   • 每个任务最多 5 个标签
   • 标签长度不超过 20 字符

4. 删除限制：

   • 已完成的任务才能删除（可选规则）
   • 删除操作需要二次确认

技术选型约束#

• 拖拽库：必须使用 @dnd-kit/core + @dnd-kit/sortable（不用 react-beautiful-dnd）
• 原因：更好的 TypeScript 支持和更小的包体积