toolkit/docs/需求文档.md

产品需求文档 (PRD)：TierMaster 动态内容分级系统

文档版本	修改日期	修改人	修改内容
V1.0	2024-05-XX	PM	初始版本：包含核心拖拽、动态配置、导入导出功能

---

1. 项目概述 (Overview)

1.1 项目背景

在当前的互联网语境下，用户热衷于对各类事物（游戏角色、消费品、社会现象等）进行主观分级（如：T0/T1、人上人/下水道）。现有的分级工具大多模板固定，无法满足“梗”文化的快速更迭（如“夯”、“拉完了”等自定义标签），且缺乏高度的视觉定制能力和数据复用能力。

1.2 项目目标

构建一个 Web端动态内容分级工具。

• 高度可配置：用户可自定义分级层级数量、名称、颜色。
• 极致交互：支持流畅的拖拽排序、跨层级移动。
• 数据便携：支持配置数据的导入导出（JSON），支持生成图片分享。
• 视觉美感：具备沉浸式体验，能够自适应展示内容。

1.3 适用平台

• Web 端（PC 浏览器为主，兼容移动端查看与简单操作）。

---

2. 用户流程图 (User Flow)

进入页面 
  -> [默认加载初始模板(S/A/B/C)]
  -> 用户上传图片/输入文字 (进入待分类池)
  -> 用户调整分级设置 (增删改层级、改色)
  -> 拖拽物品进行分类/排序
  -> 导出图片 (分享)
  -> 导出配置 (JSON保存)

---

3. 功能详情 (Functional Requirements)

3.1 模块一：分级层级管理 (Tier Management)

支持用户对“容器”进行完全自定义。

功能点	详细描述	交互/逻辑说明
动态添加层级	支持在列表底部追加新的分级行。	点击底部大按钮 [+ 添加分级]。新增行默认使用随机预设颜色，名称默认为“新分级”。
层级排序	支持上下拖动调整层级顺序。	每行左侧/右侧设有拖拽手柄，拖动可交换整行位置。
层级配置	修改层级的名称和背景色。	点击层级左侧标签区域，弹出 Popover配置面板： 1. 输入框修改名称（如“顶尖”）。 2. 颜色选择器（预设色板+自定义Hex）。
删除层级	删除不再需要的层级。	在配置面板中点击 [删除]。 兜底逻辑：若该层级内有物品，必须将所有物品自动移动到“待分类池”，不可直接删除物品。
清空层级	快速移除某一层级的所有物品。	在配置面板中点击 [清空内容]，物品全部返回池子。

3.2 模块二：物品管理与待分类池 (Item & Pool)

待分类池是物品的“暂存区”。

功能点	详细描述	交互/逻辑说明
待分类池展示	页面底部固定的区域，存放未分类物品。	采用 Sticky Footer (吸底) 设计，确保页面滚动时该区域始终可见。支持折叠/展开。
添加物品	支持上传图片或添加纯文本。	1. 图片上传：支持批量选择本地图片，自动裁剪为正方形。 2. 文本添加：输入文字生成卡片。
删除物品	移除不需要的物品。	选中物品或右键点击，选择删除。

3.3 模块三：核心交互 (Interaction)

本项目的核心体验。

功能点	详细描述	交互/逻辑说明
跨域拖拽	物品可以在“池子”与“层级”之间、以及“层级”与“层级”之间自由移动。	拖拽过程中，目标区域高亮提示（Drop Zone Highlight）。
行内排序	同一层级内的物品可以左右拖动调整顺序。	拖动时其他物品自动让位（利用 Flip 动画算法）。
视觉反馈	拖拽时的动态效果。	1. 抓起 (DragStart)：卡片放大 1.05倍，阴影加深。 2. 放下 (Drop)：卡片带有弹簧回弹动画。

3.4 模块四：数据与持久化 (Data & I/O)

满足复用与分享需求。

功能点	详细描述	交互/逻辑说明
导出配置 (JSON)	将当前的分级定义和物品位置保存为文件。	点击 [导出配置]，浏览器下载 .json 文件。包含 tiers 结构和 items 数据。
导入配置 (JSON)	读取本地文件还原现场。	点击 [导入配置]，选择文件。解析成功后，立即重绘页面所有状态。
生成图片	将当前的分级榜单保存为图片。	点击 [保存图片]。利用 html2canvas 截图，注意：需包含完整的长列表，忽略底部的操作栏。

---

4. 界面与视觉规范 (UI/UX Specifications)

4.1 整体风格

• 主题：深色模式 (Dark Mode) 为主。背景色推荐 #121212 或深灰色。
• 配色：层级标签颜色需高饱和度，内容区域保持低调，确保内容突出。

4.2 布局结构

• Header：Logo、标题、工具栏（导入/导出/保存）。
• Main Body：垂直排列的分级行（Tier Rows）。
  • 左侧：标签块（Label），固定宽度，垂直居中文字。
  • 右侧：内容容器（Container），Flex 布局，自动换行。
• Footer (Sticky)：待分类池（Unranked Pool），横向排列，支持横向滚动。

4.3 响应式设计

• PC端：完整展示。
• 移动端：
  • 层级标签显示简化（如仅显示首字母或缩窄宽度）。
  • 待分类池默认为折叠状态，点击通过“抽屉 (Bottom Sheet)”浮层弹出。

---

5. 数据结构定义 (JSON Schema)

开发需严格遵守此结构，以保证导入导出的兼容性。

{
  "meta": {
    "appName": "TierMaster",
    "version": "1.0",
    "title": "2024互联网热词分级",
    "createdAt": 1715000000
  },
  "config": {
    "tiers": [
      {
        "id": "uuid-001", 
        "label": "顶尖", 
        "color": "#FF7F7F"
        // 顺序由数组索引决定
      },
      {
        "id": "uuid-002", 
        "label": "夯", 
        "color": "#FFBF7F"
      }
    ]
  },
  "items": [
    {
      "id": "item-001",
      "type": "image", // or 'text'
      "content": "https://base64-or-url...", // 图片地址或文本内容
      "tierId": "uuid-001" // 关联到具体的层级ID
    },
    {
      "id": "item-002",
      "type": "text",
      "content": "疯狂星期四",
      "tierId": "pool" // 特殊ID，代表在待分类池
    }
  ]
}

---

6. 技术栈推荐 (Technical Stack)

为了实现上述的高交互需求，推荐以下技术选型：

• 前端框架: React (更推荐) 或 Vue 3。
• 拖拽引擎:
  • React: @dnd-kit/core (搭配 @dnd-kit/sortable) —— 性能最佳，定制性最强。
  • Vue: vue-draggable-plus (基于 Sortablejs)。
• 样式库: Tailwind CSS (快速构建布局和配色)。
• 状态管理: Zustand (React) 或 Pinia (Vue)。
• 工具库:
  • uuid: 生成唯一ID。
  • html2canvas: 截图生成功能。
  • file-saver: 处理文件下载。

---

7. 异常处理与边缘情况 (Edge Cases)

1. 图片加载失败：显示默认占位符图标。
2. 层级过多：当层级超过 20 个，颜色循环使用预设色板。
3. JSON 格式错误：导入时若 JSON 校验失败，弹窗提示“文件格式已损坏”，不覆盖当前页面。
4. 空行截图：生成图片时，即便某一行是空的，也应当保留该行展示（除非用户在截图设置中选择“隐藏空行”）。

---

8. 验收标准 (Acceptance Criteria)

1. 用户能否顺利创建一个包含 10 个层级、50 个物品的榜单？
2. 删除一个包含物品的层级时，物品是否自动回到了底部池子？
3. 导出的 JSON 文件能否在另一台电脑的浏览器中完美还原？
4. 生成的图片是否清晰，且没有被滚动条遮挡？
5. 在手机浏览器上能否完成基本的拖拽操作？