12 KiB
12 KiB
待办监控 - 需求文档
一、项目概述
项目名称：待办监控（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 元数据块，适合结构化管理：--- 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数字 目标值 指标对比 linkURL 关联链接 跳转按钮
卡片类型自动识别（根据字段组合自动切换卡片样式）：
- 任务卡（task）：默认类型，含标题/状态/进度/子任务
- 里程碑卡（milestone）：含截止日期，展示倒计时圆环
- 指标卡（metric）：含 metric + target 字段，展示大数字和达成率
- 倒计时卡（countdown）：仅含截止日期，大号数字倒计时展示
- 项目卡（project）：含多个子任务时，自动计算整体进度
智能推断规则（无需手动填写，系统自动计算）：
- 进度自动计算：若存在子任务列表但未写 progress，自动按「已完成数/总数」计算进度百分比
- 状态自动推断：
- 所有子任务已勾选 → 自动设为「已完成」
- 存在阻塞关键词（blocked/阻塞/卡壳）→ 自动设为「阻塞」
- 截止日期已过且未完成 → 自动标为「延期」
- 剩余天数自动计算：根据 deadline 自动计算还剩多少天，逾期显示红色
- 状态颜色映射：
- 待办 → 灰色
- 进行中 → 蓝色
- 已完成 → 绿色
- 阻塞 → 橙色
- 延期 → 红色
- 优先级颜色映射：
- 紧急 → 红色角标
- 高 → 橙色角标
- 中 → 蓝色角标
- 低 → 灰色角标
- 标签自动提取：正文中所有
#标签自动提取为标签字段
- 第一行
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：创建待办项
- 用户切换到「无限画布」视图
- 双击画布空白处 → 创建便签
- 输入 Markdown 内容（标题、状态、进度、子任务）
- 点击空白处保存 → 自动同步到后端
- 切换到「监控大屏」→ 看到新生成的监控卡片
流程 2：创建分组
- 在画布上选择「画框」工具
- 拖拽绘制一个矩形区域
- 将已有便签拖入框内（或在框内新建便签）
- 切换到大屏 → 这些便签自动归为一组展示
流程 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（核心必做）：
- 双视图切换框架
- 便签的增删改查 + Markdown 渲染
- 无限画布基础操作（拖拽、缩放、平移）
- 便签解析引擎（约定式 Markdown 模式 + 基础字段）
- 监控大屏 - 任务卡自动生成
- 子任务勾选双向同步
- SQLite 持久化存储
P1（重要功能）：
- 分组框功能 + 大屏分组展示
- YAML Front Matter 解析模式
- 行内快捷字段解析模式
- 智能推断规则（进度自动计算、状态自动推断）
- 状态/优先级颜色映射
- 标签系统 + 标签筛选
- 里程碑卡 / 指标卡 类型
- 截止日期 + 剩余天数计算
- 便签颜色自定义
P2（锦上添花）：
- 倒计时卡 / 项目卡 类型
- 看板视图 / 列表视图
- 统计概览栏
- 撤销 / 重做
- 高级筛选与搜索
- 批量操作
- 便签复制
- 负责人字段
- 关联链接跳转
P3（自定义扩展）：
- 自定义主题：
- 内置多套主题（亮色/暗色/护眼等）
- 支持自定义配色方案（主色、背景色、卡片色、文字色等）
- 主题可保存、切换、导入导出
- 便签颜色、分组框颜色均可自定义
- 自定义 CSS：
- 提供全局自定义 CSS 输入框
- 支持针对特定元素（卡片、便签、大屏等）的样式覆盖
- CSS 实时预览，保存后立即生效
- 样式持久化存储到 SQLite
- 自定义 JS：
- 提供用户脚本注入入口
- 支持编写自定义逻辑（如自动化规则、数据处理、第三方集成）
- 提供安全沙箱环境，限制危险 API 访问
- 脚本可启用/禁用，支持多个脚本管理
- 提供事件钩子（便签创建/更新/删除、视图切换等）供脚本监听