甘特视图（GanttView）设计方案¶

甘特视图用于在模块中以时间轴方式展示表单任务数据：横轴为时间、纵轴为任务，通过列映射绑定任务名、起止日期、完成度等字段；PC 端基于 dhtmlx-gantt 渲染任务条，支持时间粒度切换、多选删除、点击打开文档，以及（在配置拖拽事件时）拖动任务条回写起止日期。

层次	实现位置
后端 / Java	`cn.myapps.core.common.model.view.GanttView`（`obpm-core/.../view/GanttView.java`）
	`cn.myapps.core.common.model.view.type.GanttType`（视图类型实现、列映射约定）
	`cn.myapps.core.common.model.view.dto.builder.GanttViewBuilder`（保存时专有属性钩子，当前为空）
视图设计器	`ViewBasic.vue`、`ViewColumnDialog.vue`（`obpm-designer-vue3/src/components/modulesDetail/`）
	`config.js` → `ganttData()`、`options()` 中 `config.gantt_view`
前端运行时（PC）	`view_gantt.vue`（`obpm-runtime-web/portal/vue3/src/components/view/view_gantt.vue`）
	`view_delegate.vue`（按 `simpleClassName == 'GanttView'` 路由）
前端运行时（移动端）	无完整甘特组件（H5 未实现 `view_gantt`）

本文档 甘特视图 对应后端 ViewConstant.VIEW_TYPE_GANTT（0x0000013，十进制 19）；设计器 intValue == 19 与之一致。XML 根元素为 <GanttView>。

与地图视图不同：GanttView 无模型专有属性，能力几乎全部由列的 mappingField 与 PC 运行时组件决定。总览见 view-designer.md；地图对照见 map-view.md。

后端定义（Java）¶

GanttView 模型¶

GanttView 继承 AbstractView，通过 JAXB 序列化为 XML 根元素 <GanttView>，JSON 序列化时忽略空字段（@JsonInclude(NON_EMPTY)）。

视图类型常量：ViewConstant.VIEW_TYPE_GANTT = 0x0000013（十进制 19）。

getViewTypeImpl() 返回 new GanttType(this)。类本身 不增加 除继承外的字段。

专有属性¶

无。GanttViewBuilder.buildViewSpecialPortal() 为空实现。

继承自 AbstractView 的常用属性¶

属性	说明
`name` / `description`	视图名称与描述
`formId` / 关联表单	数据来源表单（设计器 `relatedForm`）
`columns`	视图列定义（含映射字段 `mappingField`）
`filterScript` / `searchFormId`	筛选脚本与查询表单
`activitys` / `events`	视图操作按钮与事件（拖拽改期依赖 drag 类事件）
`showTotalRow`	是否显示总记录数（设计器对甘特隐藏该配置项）
`readonly`	视图只读
`pagination` / `pageLines`	分页配置（设计器对甘特隐藏分页；运行时由前端固定 `lines=1000`）
`openType` / `displayType` / `templateForm`	打开方式与模板表单
`isDrag`	为真时运行时允许点击任务条打开文档
`styleId` / `orderno`	样式库与排序号

视图类型（GanttType）¶

GanttType 实现 ViewType，intValue() 返回 VIEW_TYPE_GANTT。

列映射字段¶

mappingField	类别	含义	运行时使用情况
`name`	必填（DEFAULT）	任务名称	→ dhtmlx `text`；缺省时左侧网格 `grid_width = 0`
`start`	必填	开始日期	列须为日期类型 → `start_date`（`dd-MM-yyyy`）
`end`	必填	结束日期	列须为日期类型 → `end_date`
`complete`	必填	完成度	支持 `80%` 或纯数字，运行时除以 100 → `progress`
`color`	可选（ALL）	任务条颜色	→ `color`
`parent`	可选	上级任务 ID	设计器可选；PC 未映射到 dhtmlx `parent`
`dependency`	可选	依赖任务	设计器可选；PC 未映射到 dhtmlx links
`caption`	可选	标题	无专项模板，可能进入 `otherVals` / tooltip
`description`	可选	描述	同上

静态表定义于 GanttType：

DEFAULT_KEY_FIELDS = {"name", "start", "end", "complete"}
ALL_FIELDS 在 DEFAULT 之上增加 color、parent、dependency、caption、description
源码中仍注释保留但未启用：group、milestone、resource、open

getColumnMapping()：遍历 view.columns，以 column.getMappingField() 为键得到 Map<String, Column>。

addField(key_Field, name_Field)：若键不存在则可动态扩展 ALL_FIELDS / ALL_KEY_FIELDS。

分页行为¶

GanttType **未**像 MapType 那样重写为「不分页拉全量」。运行时走通用视图文档接口；PC 前端请求时写死 currpage=1、lines=1000。

构造器（GanttViewBuilder）¶

GanttViewBuilder 仅提供 getNewView() → new GanttView()；buildViewSpecialPortal() 无额外写入。设计器 REST 保存主路径仍是 viewType + json2obj，不依赖该 Builder 写入专有字段。

保存选型与校验¶

新建 / 更新：@RequestParam int viewType + Body JSON，viewType == VIEW_TYPE_GANTT 时：

json2obj(json, GanttView.class)

ViewController.validate：已配置 mappingField 的列数须 ≥ 4（按数量校验，不强制四角色键名齐全）。

读盘：DesignTimeModelRootElementMapper 注册 GanttView.class；按 XML 根元素名选型。ViewDirector.construct 在 VIEW_TYPE_GANTT 分支使用甘特构造路径。

Workspace 路径与其他视图相同：

/{应用名}.application/module/{模块名}.module/{视图名}.view

设计器配置¶

视图设计器入口为模块详情页视图编辑；甘特视图对应 intValue == 19。视图 XML 根标签名为 GanttView。

基本信息（ViewBasic.vue，`intValue == 19`）¶

无甘特专有表单项（对比地图的 mapType / mapDisplayType / ViewCity）。通过 showgantt（intValue == 19）控制通用项显隐：

配置项	甘特下行为
分页	隐藏（`showPagination` 排除 19）
水印脚本	隐藏
数据类型呈现方式	隐藏（与树、地图相同）
总行数 / 选择复选框	隐藏（与日历相同）
展开查询表单	显示
只读	仍可配置（未列入只读隐藏列表）

类型选项：config.js → options()，标签键 config.gantt_view（「甘特视图」），值为 19。

视图列映射（config.js → ganttData）¶

列编辑弹窗（ViewColumnDialog.vue）在 intValue == 19 时展示甘特映射下拉，旁注红色文案 (甘特视图)。

设计器文案（zh-CN）	mappingField
(必填)任务名称	`name`
(必填)开始日期	`start`
(必填)结束日期	`end`
(必填)完成度	`complete`
颜色	`color`
上级任务ID	`parent`
依赖任务	`dependency`
标题	`caption`
描述	`description`

建议：start / end 绑定表单日期字段，否则运行时按日期分支格式化可能异常。完成度字段可用带 % 的文本或数值。

前端运行时（PC）¶

组件路由¶

view_delegate.vue 根据后端 simpleClassName == 'GanttView' 渲染 view_gantt。

图表引擎¶

依赖：dhtmlx-gantt（样式 dhtmlxgantt.css）。
入口：将模块导出挂到 window.gantt / window.Gantt，组件内调用全局 gantt API。
本地化：gantt.i18n.setLocale('cn')。
插件：tooltip: true。

数据加载¶

getViewData 调用运行时视图文档接口（与列表相同）。
请求参数：currpage: 1，lines: 1000，可带查询表单 searchData。
将每条文档的 items 摊平为「列 id → 值」，再按列的 mappingField 组装 dhtmlx tasks.data。
gantt.clearAll() → gantt.init → gantt.parse(tasks)。

无权限数据时走 openInCurrentContainer({ linkType: '100' })。

任务对象映射¶

文档 / 列	dhtmlx 任务字段
文档 `id`	`id`
`mappingField == name`	`text`
`mappingField == start` 且 `columnField == DateField`	`start_date`（`DD-MM-YYYY`）
`mappingField == end` 且日期列	`end_date`；并在 `otherVals` 记 `customEndTime` → 表单字段名
`mappingField == complete`	`progress`（去 `%` 后 `/ 100`）
`mappingField == color`	`color`
其余有映射的列	`otherVals[{ name, value }]`，供 tooltip / 拖拽回写

固定展示：row_height = 40，bar_height = 24。

左侧网格列：

复选框列（staff）：表头全选用视图 id，行选用文档 id → selectedDocId
text：标签「项目」，tree: true，宽 280
add：占位列

时间刻度¶

工具栏提供日 / 周 / 月 / 季 / 年（currentTimeType，默认 month）。onChange 时重设 gantt.config.scales 并重新 parse。

粒度	scales 要点
year	仅年
day	年 + 月 + 日
week	年 + 月 + 周（自定义周区间文案）
month / quarter 等	年 + 月（默认）

切换粒度时会将 gantt.config.readonly = true。

用户操作¶

功能	说明
活动按钮	创建、载入视图、导入/导出 Excel 等委托父级 `doAction`；删除走本地 `doRemove`（需勾选）
多选删除	左侧 checkbox 收集 `selectedDocId`，确认后 `doAction(act, docIds)`
点击打开	`view.isDrag` 为真时挂 `onTaskClick`，`addTab` 打开对应表单文档
拖拽改期	视图 `events` 中存在 drag 类事件时：启用 `drag_project`、`fit_tasks`；`onAfterTaskDrag`（`move`）后组装 `items` 调用 `saveDocument`
Tooltip	开始/结束时间 + `otherVals` 中非起止标记字段

只读与事件¶

未配置 drag 事件时，不启用项目拖放与回写（代码中 readonly 全量只读曾注释掉）。
created 时将视图 events 标记为 type: 'drag' 并挂到 eventData.drag（当前实现按「有事件即拖拽」处理，需与事件配置约定一致）。

前端运行时（移动端）¶

obpm-runtime-mobile-vue3 没有与 PC 对等的 view_gantt 组件。移动端视图委托对甘特类型无完整分支（与 Sheet 类似，见 view-designer.md 运行时对照表）。

维度	说明
组件	无
建议	移动端勿依赖甘特展示；或降级为列表/其他已支持类型

Workspace XML 约定¶

视图根¶

<?xml version="1.0" encoding="UTF-8"?>
<GanttView id="view-uuid">
  <name>TaskGantt</name>
  <parentId>module-uuid</parentId>
  <applicationid>app-uuid</applicationid>
  <description></description>
  <editMode>00</editMode>
  <relatedForm>form-uuid</relatedForm>
  <!-- 筛选、活动、事件等与其他视图相同 -->
</GanttView>

改类型 = 改根标签**为 GanttView（内部类型值文档用 **19）。

列示例（`mappingField`）¶

四列必填角色示例（各为独立 .column 文件，parentId / parentView / applicationid 指向视图）：

mappingField	建议绑定
`name`	任务名称文本字段
`start`	开始日期 `DateField`
`end`	结束日期 `DateField`
`complete`	完成度文本/数值字段

可选：color、parent、dependency、caption、description（后四者运行时支持不完整，见下文）。

Agent 生成视图文件时参见 agent-skills-usage/skills/generate-view-file/SKILL.md（甘特 ≥4 列映射）。

运行时 API 汇总¶

方法	路径 / 接口	用途
POST	`/runtime/{appId}/views/{viewId}/documents`	加载视图文档（前端 `lines=1000`）
—	`saveDocument`	拖拽改期后回写表单字段
—	活动删除等	经 `view_delegate.doAction` / 批量删除

设计器保存视图：ViewController 按 viewType=19 反序列化为 GanttView。

与列表 / 地图视图的对比¶

维度	ListView	MapView	GanttView
类型值	1	18	19
模型专有属性	较少 / 网格相关	多（地图引擎、展示类型、中心等）	无
核心配置	列、筛选、活动	列映射 + 地图专有字段	列 mappingField
PC 组件	`view_listview` 等	`view_mapview`	`view_gantt`
移动端	有	有（简化）	无
数据量	分页	后端一次拉全	前端 `lines=1000`
保存校验 mapping 列数	不强制	不强制	≥ 4

已知限制与注意事项¶

父子与依赖未接线：设计器提供 parent、dependency，PC view_gantt.vue 未写入 dhtmlx 的 parent / links，树形父子与依赖箭头基本不可用。
caption / description：无专用列或提示模板逻辑，仅可能进入通用 otherVals。
GanttType 注释字段：group / milestone / resource / open 未启用。
数据上限：前端固定最多约 1000 条；超大数据集需改请求或后端策略。
起止列类型：映射逻辑依赖 columnField == 'DateField'；非日期列可能无法正确生成 start_date / end_date。
切换时间粒度：会设置 readonly = true，可能影响后续拖拽。
移动端：无完整实现。
校验宽松：后端只检查 mapping 列数量 ≥ 4，不保证 name/start/end/complete 四角色都存在。
事件与拖拽：当前将视图 events 一律当作 drag 启用拖放，事件类型约定需与实现保持一致，避免误开拖拽回写。

源码索引（核对用）¶

文件	说明
`java/obpm-core/.../view/GanttView.java`	模型
`java/obpm-core/.../view/type/GanttType.java`	映射常量与 `getColumnMapping`
`java/obpm-core/.../view/constant/ViewConstant.java`	`VIEW_TYPE_GANTT`
`java/obpm-core/.../view/dto/builder/GanttViewBuilder.java`	空专有构建
`java/obpm-designer/.../view/controller/ViewController.java`	保存选型与 ≥4 校验
`web/obpm-designer-vue3/src/assets/js/config.js`	`ganttData` / 类型选项
`web/obpm-designer-vue3/.../ViewBasic.vue`	`showgantt` 显隐
`web/obpm-designer-vue3/.../ViewColumnDialog.vue`	映射下拉
`web/obpm-runtime-web/.../view/view_gantt.vue`	PC 运行时
`web/obpm-runtime-web/.../view/view_delegate.vue`	路由与刷新