379 lines
12 KiB
Markdown
379 lines
12 KiB
Markdown
# 待办监控 - 需求文档
|
||
|
||
## 一、项目概述
|
||
|
||
**项目名称**：待办监控（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 访问
|
||
- 脚本可启用/禁用，支持多个脚本管理
|
||
- 提供事件钩子（便签创建/更新/删除、视图切换等）供脚本监听
|