# 待办监控 - 需求文档

## 一、项目概述

**项目名称**：待办监控（Todo Monitor）

**核心定位**：一个双视图的待办管理工具——在无限画布上用 Markdown 便签自由记录，一键切换为结构化的监控大屏，自动将便签整理为监控卡片。

**技术栈**：
- **前端**：Web 应用（单页应用 SPA）
- **后端**：轻量后端服务（Node.js / Python 任选）
- **数据库**：SQLite（本地文件型数据库，零配置）

---

## 二、核心功能模块

### 2.1 双视图切换

应用包含两种核心视图，用户可一键切换：

| 视图 | 名称 | 用途 |
|------|------|------|
| 视图 A | **无限画布** | 自由创作区，添加便签、画框、拖拽布局 |
| 视图 B | **监控大屏** | 自动生成的结构化监控面板，展示所有待办项 |

**切换方式**：顶部导航栏提供「画布 / 大屏」切换按钮，切换时保留当前数据状态。

---

### 2.2 无限画布（Canvas View）

#### 2.2.1 便签（Sticky Note）
- **添加方式**：双击画布空白处 → 创建一张新便签
- **内容格式**：Markdown 语法支持
  - 标题（# ## ###）
  - 列表（- / 1.）
  - 复选框（- [ ] / - [x]）
  - 粗体、斜体、代码块等基础 Markdown
- **交互操作**：
  - 拖拽移动位置
  - 拖拽右下角调整大小
  - 双击进入编辑模式
  - 右键菜单：删除、复制、修改颜色
- **便签解析引擎**（核心，用于生成监控卡片）：

  系统支持 **三种解析模式并存兼容**，按优先级自动识别：

  **模式一：YAML Front Matter（最灵活，推荐）**
  便签顶部用 `---` 包裹的 YAML 元数据块，适合结构化管理：
  ```markdown
  ---
  title: 登录模块开发
  status: 进行中
  priority: 高
  progress: 65
  deadline: 2026-08-15
  owner: 张三
  tags: [前端, 核心模块]
  type: task
  ---
  正文内容...
  ```

  **模式二：约定式 Markdown（最直观）**
  无需学习语法，按约定结构书写自动识别：
  - 第一行 `# 标题` → 卡片标题
  - 二级标题 `## 子标题` → 卡片副标题
  - `**状态：** 进行中` → 状态字段
  - `**进度：** 60%` → 进度字段
  - `**优先级：** 高` → 优先级字段
  - `**截止：** 2026-08-15` → 截止日期
  - `**负责人：** 张三` → 负责人字段
  - `**标签：** #前端 #核心` → 标签字段
  - `- [ ]` / `- [x]` 列表项 → 子任务列表
  - 其他段落 → 卡片描述区

  **模式三：行内快捷字段（最轻量）**
  适合快速记录，直接在行内用特殊语法标记：
  - `@状态(进行中)` → 状态字段
  - `@进度(65%)` → 进度字段
  - `@优先级(高)` → 优先级字段
  - `@截止(2026-08-15)` → 截止日期
  - `#标签名` → 标签（行内任意位置）

  ---

  **支持的完整字段清单**：

  | 字段 | 类型 | 说明 | 卡片展示方式 |
  |------|------|------|-------------|
  | `title` | 字符串 | 卡片标题 | 卡片顶部大标题 |
  | `subtitle` | 字符串 | 副标题 | 标题下方小字 |
  | `status` | 枚举 | 待办/进行中/已完成/阻塞/延期 | 彩色状态标签 |
  | `progress` | 数字 0-100 | 进度百分比 | 进度条 + 数字 |
  | `priority` | 枚举 | 紧急/高/中/低 | 优先级角标 |
  | `deadline` | 日期 | 截止日期 | 剩余天数/逾期提醒 |
  | `startDate` | 日期 | 开始日期 | 时间线展示 |
  | `owner` | 字符串 | 负责人 | 头像/名字标签 |
  | `tags` | 数组 | 标签列表 | 底部标签云 |
  | `type` | 枚举 | task/milestone/metric/countdown | 卡片类型 |
  | `metric` | 数字 | 指标数值 | 大数字展示 |
  | `target` | 数字 | 目标值 | 指标对比 |
  | `link` | URL | 关联链接 | 跳转按钮 |

  ---

  **卡片类型自动识别**（根据字段组合自动切换卡片样式）：

  - **任务卡（task）**：默认类型，含标题/状态/进度/子任务
  - **里程碑卡（milestone）**：含截止日期，展示倒计时圆环
  - **指标卡（metric）**：含 metric + target 字段，展示大数字和达成率
  - **倒计时卡（countdown）**：仅含截止日期，大号数字倒计时展示
  - **项目卡（project）**：含多个子任务时，自动计算整体进度

  ---

  **智能推断规则**（无需手动填写，系统自动计算）：

  1. **进度自动计算**：若存在子任务列表但未写 progress，自动按「已完成数/总数」计算进度百分比
  2. **状态自动推断**：
     - 所有子任务已勾选 → 自动设为「已完成」
     - 存在阻塞关键词（blocked/阻塞/卡壳）→ 自动设为「阻塞」
     - 截止日期已过且未完成 → 自动标为「延期」
  3. **剩余天数自动计算**：根据 deadline 自动计算还剩多少天，逾期显示红色
  4. **状态颜色映射**：
     - 待办 → 灰色
     - 进行中 → 蓝色
     - 已完成 → 绿色
     - 阻塞 → 橙色
     - 延期 → 红色
  5. **优先级颜色映射**：
     - 紧急 → 红色角标
     - 高 → 橙色角标
     - 中 → 蓝色角标
     - 低 → 灰色角标
  6. **标签自动提取**：正文中所有 `#标签` 自动提取为标签字段

#### 2.2.2 分组框（Group Frame）
- **添加方式**：工具栏选择「画框」工具 → 在画布上拖拽绘制矩形区域
- **功能**：框内的所有便签自动归为一组
- **交互操作**：
  - 拖拽移动整个框（框内便签跟随移动）
  - 拖拽边角调整大小
  - 双击框标题修改分组名称
  - 右键菜单：删除分组、修改颜色
- **规则**：
  - 便签中心落在框内 → 属于该组
  - 一个便签只能属于一个组（以最上层框为准）
  - 便签可拖出框 → 自动解除分组

#### 2.2.3 画布基础操作
- 滚轮缩放（Zoom in / out）
- 按住空格 + 拖拽 → 平移画布
- 框选多个元素 → 批量移动/删除
- 撤销 / 重做（Ctrl+Z / Ctrl+Y）

---

### 2.3 监控大屏（Dashboard View）

#### 2.3.1 监控卡片（Monitor Card）
- 每张便签对应一张监控卡片，卡片类型根据解析结果自动切换
- 卡片内容从 Markdown 智能解析生成，支持以下类型：

**通用卡片结构**（所有类型共有）：
- **标题区**：卡片标题 + 副标题
- **状态标签**：彩色状态徽章（左上角）
- **优先级角标**：优先级标识（右上角）
- **底部标签云**：自动提取的标签
- **更新时间**：最后编辑时间

**任务卡（task）**：
- 进度条 + 百分比数字
- 可折叠子任务列表（支持直接勾选，勾选后自动同步回便签 Markdown）
- 描述区 Markdown 渲染
- 截止日期 + 剩余天数

**里程碑卡（milestone）**：
- 大号倒计时圆环（剩余天数）
- 截止日期完整显示
- 里程碑描述
- 关联任务数（同组内任务数）

**指标卡（metric）**：
- 超大号数字展示（当前值）
- 目标值对比（达成率百分比）
- 迷你趋势图（如有历史数据）
- 指标说明文字

**倒计时卡（countdown）**：
- 全屏式大号倒计时数字
- 目标日期与事件名称
- 进度条（从开始日期到截止日期）

**项目卡（project）**：
- 整体进度条（子任务自动汇总）
- 子任务完成数 / 总数
- 关键节点列表
- 项目描述

#### 2.3.2 分组展示
- 有分组的卡片 → 按分组排列，每组有标题栏
- 无分组的卡片 → 归入「未分组」区域
- 分组可折叠 / 展开

#### 2.3.3 大屏布局与交互
- 响应式卡片网格布局，卡片宽度自适应
- **排序维度**：状态 / 进度 / 优先级 / 截止日期 / 更新时间
- **筛选维度**：
  - 按状态筛选（多选）
  - 按优先级筛选
  - 按标签筛选（点击标签过滤）
  - 按负责人筛选
  - 按分组筛选
- **搜索功能**：标题/内容全文搜索
- **视图切换**：
  - 网格视图（默认，卡片网格）
  - 列表视图（紧凑列表）
  - 看板视图（按状态分列）
- **统计概览栏**：顶部展示全局统计
  - 总任务数
  - 进行中数量
  - 已完成数量
  - 逾期数量
  - 整体完成率

---

## 三、数据模型设计

### 3.1 便签表（notes）
```
- id: 唯一标识
- content: Markdown 内容（文本）
- x: 画布 X 坐标
- y: 画布 Y 坐标
- width: 宽度
- height: 高度
- color: 便签颜色
- group_id: 所属分组 ID（可为空）
- created_at: 创建时间
- updated_at: 更新时间
```

### 3.2 分组表（groups）
```
- id: 唯一标识
- name: 分组名称
- x: 框 X 坐标
- y: 框 Y 坐标
- width: 框宽度
- height: 框高度
- color: 框颜色
- created_at: 创建时间
- updated_at: 更新时间
```

### 3.3 元数据表（meta）
```
- key: 配置键
- value: 配置值
（用于存储画布缩放比例、当前视图等全局设置）
```

---

## 四、后端 API 设计

### 便签相关
- `GET /api/notes` — 获取所有便签
- `POST /api/notes` — 创建新便签
- `PUT /api/notes/:id` — 更新便签（内容/位置/大小）
- `DELETE /api/notes/:id` — 删除便签

### 分组相关
- `GET /api/groups` — 获取所有分组
- `POST /api/groups` — 创建新分组
- `PUT /api/groups/:id` — 更新分组（位置/大小/名称）
- `DELETE /api/groups/:id` — 删除分组

### 批量操作
- `POST /api/batch` — 批量更新（便签位置、分组归属等）

---

## 五、关键交互流程

### 流程 1：创建待办项
1. 用户切换到「无限画布」视图
2. 双击画布空白处 → 创建便签
3. 输入 Markdown 内容（标题、状态、进度、子任务）
4. 点击空白处保存 → 自动同步到后端
5. 切换到「监控大屏」→ 看到新生成的监控卡片

### 流程 2：创建分组
1. 在画布上选择「画框」工具
2. 拖拽绘制一个矩形区域
3. 将已有便签拖入框内（或在框内新建便签）
4. 切换到大屏 → 这些便签自动归为一组展示

### 流程 3：更新进度
- **方式 A**：在画布上编辑便签 Markdown 中的进度数字
- **方式 B**：在大屏上直接勾选子任务 → 自动计算进度并回写便签内容

---

## 六、技术实现要点

### 前端
- **画布渲染**：建议使用 Konva.js / Fabric.js 等 Canvas 库实现无限画布
- **Markdown 解析**：marked.js + DOMPurify（防 XSS）
- **状态管理**：本地状态 + 实时同步到后端
- **拖拽交互**：原生拖拽或库实现

### 后端
- 轻量 Web 框架（Express / FastAPI / Flask）
- SQLite 数据库（better-sqlite3 / sqlite3）
- RESTful API
- 简单的错误处理和数据校验

### 数据同步
- 编辑便签时防抖保存（输入停止 500ms 后自动保存）
- 拖拽位置实时更新（节流处理）
- 视图切换时从后端拉取最新数据

---

## 七、优先级建议

**P0（核心必做）**：
1. 双视图切换框架
2. 便签的增删改查 + Markdown 渲染
3. 无限画布基础操作（拖拽、缩放、平移）
4. 便签解析引擎（约定式 Markdown 模式 + 基础字段）
5. 监控大屏 - 任务卡自动生成
6. 子任务勾选双向同步
7. SQLite 持久化存储

**P1（重要功能）**：
1. 分组框功能 + 大屏分组展示
2. YAML Front Matter 解析模式
3. 行内快捷字段解析模式
4. 智能推断规则（进度自动计算、状态自动推断）
5. 状态/优先级颜色映射
6. 标签系统 + 标签筛选
7. 里程碑卡 / 指标卡 类型
8. 截止日期 + 剩余天数计算
9. 便签颜色自定义

**P2（锦上添花）**：
1. 倒计时卡 / 项目卡 类型
2. 看板视图 / 列表视图
3. 统计概览栏
4. 撤销 / 重做
5. 高级筛选与搜索
6. 批量操作
7. 便签复制
8. 负责人字段
9. 关联链接跳转

**P3（自定义扩展）**：
1. **自定义主题**：
   - 内置多套主题（亮色/暗色/护眼等）
   - 支持自定义配色方案（主色、背景色、卡片色、文字色等）
   - 主题可保存、切换、导入导出
   - 便签颜色、分组框颜色均可自定义
2. **自定义 CSS**：
   - 提供全局自定义 CSS 输入框
   - 支持针对特定元素（卡片、便签、大屏等）的样式覆盖
   - CSS 实时预览，保存后立即生效
   - 样式持久化存储到 SQLite
3. **自定义 JS**：
   - 提供用户脚本注入入口
   - 支持编写自定义逻辑（如自动化规则、数据处理、第三方集成）
   - 提供安全沙箱环境，限制危险 API 访问
   - 脚本可启用/禁用，支持多个脚本管理
   - 提供事件钩子（便签创建/更新/删除、视图切换等）供脚本监听