甘特图视图设计文档

一、功能概述

甘特图视图插件是基于 NocoBase 2.0 开发的项目管理扩展插件，为用户提供以甘特图形式展示任务和项目进度的能力。
通过时间轴布局、任务条、里程碑标记和依赖关系线，帮助用户直观了解项目时间安排、任务依赖关系和执行进度，特别适用于项目管理、任务规划、排期协同、资源调度等场景。

二、核心功能设计

2.1 数据展示

支持基于数据表字段映射生成甘特图视图
支持展示时间跨度、任务进度和父子任务结构
支持字段映射 标题、开始日期、结束日期、进度、任务类型，其中 标题、开始日期、结束日期、任务类型 为必填
任务类型可根据字段映射,如:
- 任务（Task）：常规任务项，显示为带进度的条形图
- 里程碑（Milestone）：重要时间节点，显示为菱形标记
- 缺陷（Bug）：突出显示的任务项，显示为圆形标记
- 需求（Requirement）：需求描述，显示为矩形标记
支持任务依赖关系展示，通过箭头连接前置任务与后置任务
支持自动排期，当任务开始日期或结束日期发生变化时，自动顺延其后置依赖任务的日期
支持按父子层级展示任务树结构
支持设置基线、基线可根据时间调整
支持显示法定节假日、休息日
支持大数据量场景下的虚拟滚动、分段渲染和懒加载

2.2 视图模式

甘特图视图采用左右分栏布局，由任务列表区和时间轴区共同组成：

任务列表区：
- 左侧展示标题、负责人、进度、开始日期、结束日期等字段，也可支持配置自定义字段显示
- 支持树形缩进展示父子任务结构
- 支持展开/折叠父任务
- 支持列宽调整和字段显示配置
时间轴区：
- 右侧按时间单位展示任务跨度和进度条
- 支持展示依赖关系连线
- 支持今日高亮和非工作日高亮（可选）
- 支持法定节假日、休息日高亮（可选）
- 支持横向、纵向滚动联动
支持多种时间跨度切换：
- 小时视图
- 日视图
- 周视图
- 月视图
- 季度视图
- 年视图

2.3 内容配置

支持配置任务条样式：
- 背景色
- 进度条颜色
- 选中态颜色
支持依赖线样式
支持配置任务列表区显示字段
支持多层级任务结构展示
根据任务类型配置不同类型任务条显示样式
支持配置默认展开层级
支持按条件筛选展示部分任务数据
支持配置拖拽提交模式：
- 实时保存
- 手动确认后保存（默认）
支持配置最近操作历史条数，用于展示最近若干次甘特图调整记录
支持配置工作日历：
- 每日标准工时
- 工作时间段
- 加班起算时间
- 非工作日/节假日规则

2.4 交互操作

拖拽任务条可调整任务开始日期和结束日期
拖拽任务条整体可平移任务排期
拖拽任务进度可调整完成百分比
拖拽任务条后默认先更新前端临时状态，不直接写回数据
甘特图顶部提供统一的 保存变更、放弃变更 操作入口，用于确认本次拖拽调整
甘特图右侧增加 最近操作 面板，展示最近若干条排期变更记录，并支持撤销最近一次操作
当任务日期被拖拽或编辑后，若存在后置依赖任务，则自动触发依赖任务排期联动
点击任务可查看详情或跳转详情页（可配置）
支持新增任务、编辑任务、删除任务
支持筛选、搜索、排序，快速定位特定任务
支持展开/折叠父子任务
支持任务条的双击、右键菜单等操作
- 双击任务条可跳转到任务详情页
- 右键菜单支持任务删除、任务编辑等操作
支持依赖线的创建、编辑和删除

2.5 插件配置项设计（Schema 映射）

2.5.1 字段映射（Field Mapping）

分组	字段	类型	说明
基础字段	title	String	标题字段（必填）
	startDate	Date	开始日期字段（必填）
	endDate	Date	结束日期字段（必填）
	progress	Number	任务进度字段（0-100，选填）
	taskType	String / Enum	任务类型字段（必填，task / milestone / bug / requirement …）

2.5.2 视图与排期配置（View & Schedule Settings）

配置项	类型	默认值	说明
barProgressColor	ColorPicker	#1890ff	任务进度条颜色
barProgressSelectedColor	ColorPicker	#096dd9	选中时进度条颜色
barBackgroundColor	ColorPicker	#e6f7ff	任务条背景色
barBackgroundSelectedColor	ColorPicker	#bae7ff	选中时任务条背景色
arrowColor	ColorPicker	#bfbfbf	依赖关系箭头颜色
todayColor	ColorPicker	rgba(252, 248, 227, 0.5)	今日高亮色
weekendColor	ColorPicker	rgba(0, 0, 0, 0.03)	非工作日高亮色
showToday	Boolean	true	是否显示今日高亮
showWeekend	Boolean	true	是否显示非工作日高亮
showDependencies	Boolean	true	是否显示依赖关系线
defaultViewMode	String	day	默认时间视图模式
editCommitMode	String	manual	编辑提交模式，支持 `manual` / `auto`
showRecentActions	Boolean	true	是否显示最近操作面板
recentActionLimit	Number	10	最近操作记录条数上限
standardDailyHours	Number	8	每个工作日的标准工时
workingTimeSegments	Array	`09:00-18:00`	标准工作时间段配置
overtimeStartTime	String	null	加班起算时间，如 `19:00`，为空表示不启用加班

三、数据模型与初始化

3.1 数据来源模式

基于已有业务表配置视图

用户在已有任务表、项目表等数据表上配置字段映射
系统不新增业务表，仅生成甘特图视图配置

四、规则设计与边界处理

4.1 任务类型规则

task：常规任务，必须具备开始日期和结束日期
milestone：里程碑，通常开始日期与结束日期相同，也可仅使用单一时间点渲染
bug：缺陷任务，沿用普通任务的时间渲染规则，可通过类型样式进行区分
requirement：需求任务，沿用普通任务的时间渲染规则，可通过类型样式进行区分

4.2 时间规则

开始日期不得晚于结束日期
任务无开始日期或结束日期时默认不可渲染
里程碑若仅有开始日期，可将结束日期视为同一时刻

4.3 工作日历与工时规则

小时视图下需区分 时间跨度 与 工时投入
默认以工作日历计算任务可排布时间，而不是按自然日 24 小时连续计算
每个工作日可配置标准工时，例如每天 8 小时
支持配置多个工作时间段，例如 09:00-12:00、13:00-18:00
支持配置加班起算时间，例如 19:00 之后计入加班
当任务排期落在加班起算时间之后时：
- 时间轴上正常展示
- 统计时单独计入加班工时
若任务持续时间按工时计算，则 1 天并不等于 24 小时，而是等于配置的标准工时，例如 8 小时
例如标准工作时间截至 18:00，加班起算时间为 19:00，则 18:00-19:00 属于非工作时间，19:00 之后计入加班
例如任务计划工时为 12 小时，在标准工时 8 小时、19:00 后允许记录 4 小时加班的配置下，可视为同一天内完成
若未配置加班起算时间，则超出标准工时的拖拽应提示超出工作日历范围，或自动吸附到下一个可工作时间段
该方案适用于常规白班场景；若后续需要支持跨天夜班、多段加班、不同日期不同加班规则，再扩展为更复杂的日历模型

4.4 层级规则

支持多级父子任务结构
父任务可折叠/展开其子任务
父任务日期可由最早子任务开始日期和最晚子任务结束日期自动汇总计算

4.5 依赖关系规则

支持基础前置依赖关系
默认支持完成-开始（Finish to Start, FS）类型
前置任务日期变化后，后置任务应自动调整到满足依赖约束的日期
当后置任务被自动调整时，默认保持自身工期不变，只同步移动开始日期和结束日期
后续可扩展支持：
- 开始-开始（SS）
- 完成-完成（FF）
- 开始-完成（SF）
不允许形成循环依赖
依赖任务删除后，应同步清理相关依赖记录或提示用户修复

4.6 进度规则

进度取值范围为 0-100
为空时默认按 0 处理
milestone 默认不展示进度条

4.7 编辑确认与操作历史规则

默认采用手动确认保存模式，拖拽、缩放、进度调整仅写入前端待提交状态
页面顶部应提供清晰的待提交提示，例如 有 3 项变更待保存
用户点击 保存变更 后，才批量写回任务字段及受影响的依赖任务
用户点击 放弃变更 后，恢复到上次保存状态
最近操作历史默认展示最近 10 条，也可作为配置项允许调整为 20 条或 50 条
最近操作至少记录：任务名称、操作类型、变更前时间、变更后时间、操作人、操作时间
历史记录区位于甘特图右侧抽屉或侧边栏，避免挤占主时间轴区域
若采用实时保存模式，则仍保留最近操作历史，便于审计与回退

4.8 异常与边界情况

开始日期晚于结束日期：禁止保存或提示修正
被依赖任务删除：需同步处理依赖关系
自动排期触发链式更新时，需避免重复计算与死循环，按拓扑顺序刷新后置任务
大量任务同时展示时：采用虚拟滚动和分层渲染优化性能
横向时间跨度过大时：默认限制初始渲染范围，避免首屏性能开销过高
小时视图下拖拽到非工作时间段：需根据配置决定是禁止、自动吸附，还是标记为加班
当存在 18:00 下班、19:00 后计加班这类配置时，18:00-19:00 这段需明确视为不可排期的空档时间
手动确认模式下存在未保存变更时：切换视图、刷新页面或离开页面前需提示用户确认

五、实现思路

5.1 设计原则

可视化排期： 通过时间轴和任务条直观展示任务计划与执行进度
灵活映射： 支持基于已有数据表快速配置字段映射，无需强绑定固定数据结构
交互友好： 支持拖拽、缩放、筛选、折叠等高频操作，降低使用门槛
性能可控： 在大数据量和长时间跨度场景下，提供虚拟滚动与懒加载能力

5.2 入口与配置流程

入口位于 创建区块 配置中，新增 甘特图视图
用户选择数据源后，进入甘特图视图配置面板
配置内容包括：
1. 基础字段映射
2. 任务类型字段映射
3. 进度字段映射
4. 时间范围
配置保存后，系统生成对应甘特图视图页面

5.3 编辑与拖拽逻辑

用户拖动任务条时：
1. 计算新的开始日期和结束日期
2. 更新前端临时状态，并标记该任务为 待保存
3. 若存在依赖关系，则根据依赖关系计算后置任务的新日期，并一并加入待保存列表
4. 在顶部操作区展示 保存变更、放弃变更 按钮及待保存数量
5. 用户确认后，将当前任务及受影响任务一并写回对应数据表字段
用户调整任务条左右边界时：
1. 保持未拖动边界不变
2. 更新被拖动边界对应时间
3. 若存在依赖关系，联动刷新后置依赖任务日期
用户修改进度时：
1. 校验进度范围是否合法
2. 写入前端待提交状态
3. 用户确认后再写回 progress 字段

5.4 最近操作历史设计

最近操作历史默认展示最近 10 条记录
每条记录包含：任务名称、操作类型、变更摘要、操作人、操作时间
操作类型可包含：移动任务、调整开始时间、调整结束时间、修改进度、创建依赖、删除依赖
当用户执行撤销时，优先针对当前未保存变更做前端回滚；已保存数据可结合后端操作日志再提供进一步回退能力

5.5 依赖关系处理逻辑

支持通过任务间交互创建依赖
保存依赖前需进行闭环校验
自动排期计算时按依赖链拓扑排序，逐个推导后置任务的最早可开始时间
后置任务日期更新时，默认不改变任务持续时长，只整体移动任务区间
例如某后置任务原计划为 2026-06-10 至 2026-06-12，若因前置任务变更需顺延 2 天，则自动调整为 2026-06-12 至 2026-06-14
删除任务时同步检查其作为前置或后置任务的依赖关系

5.6 列表区与时间轴联动

左侧任务列表区与右侧时间轴区按行高保持同步
垂直滚动时左右区域联动
横向滚动仅作用于时间轴区
展开/折叠父任务时同步刷新左右区域展示

5.7 小时视图与加班处理

小时视图基于工作日历渲染，而不是简单按自然时间连续铺满
任务排期计算时，优先以标准工时段作为可用时间窗口
若配置了加班起算时间，则允许任务拖拽到该时间之后，并单独统计加班工时
若未配置加班起算时间，则超出标准工时的部分自动顺延到下一工作时间段

六、性能与扩展性设计

6.1 性能优化

支持任务列表虚拟滚动
支持时间轴分段渲染，避免一次性渲染过宽时间范围
支持仅渲染当前可见任务行与附近缓冲区
在大数据量场景下优先保障滚动与拖拽流畅性

七、实现计划

阶段	里程碑	交付物
1	核心视图能力	支持字段映射、任务列表区、时间轴区、任务条渲染、时间粒度切换、视图与排期配置
2	交互与依赖联动	支持拖拽编辑、依赖关系展示与编辑、自动排期、后置任务日期联动
3	性能与高级扩展	支持虚拟滚动、懒加载、大数据量场景优化、导出等高级能力