Files
deerflow-code/docs/GoView-第一阶段离线项目模板与发布实施方案.md
T

15 KiB
Raw Blame History

GoView 第一阶段离线项目模板与发布实施方案

1. 阶段目标

第一阶段只解决 GoView 的离线可用和内容管理闭环。

用户在保留原有画布编辑器的前提下,能够完成:

  1. 我的项目:新建、编辑、重命名、删除、保存、预览和发布;
  2. 我的模板:把自己的项目保存为模板、查看、编辑模板信息和用模板创建项目;
  3. 模板市场:查看内置模板、用模板创建个人项目;
  4. 离线部署:项目 JSON、缩略图、模板封面和地图瓦片均由本地部署提供;
  5. 发布链接:项目发布后获得可直接访问的只读预览链接;
  6. 地图瓦片背景:在原有画布的组件库中增加一张可离线使用的 Leaflet 瓦片地图背景组件。

现有画布的拖拽、缩放、分组、样式、数据面板和事件面板不在本阶段改造范围内。

原生数据面板完整保留

截图中的“数据”标签页属于每个 GoView 组件自身的画布配置,不属于项目、模板或发布后台。第一阶段必须完整保留:

  • 静态数据和 JSON 在线编辑;
  • JSON 或 TXT 导入、下载;
  • 动态请求;
  • 公共接口和数据池;
  • 数据字段映射及匹配状态;
  • 组件原有的刷新与轮询配置。

项目保存接口把整份 ChartEditStorage 作为 content_json 原样保存,其中已包含组件的 request、filter、option.dataset、字段映射和其它数据配置。模板创建和“使用模板”也只深拷贝同一份 JSON,不能删除、重置或改写这些数据配置。

后续如要增加新的数据来源,只能在这个数据面板中新增选项或适配器,不能替换、收窄或移除现有的静态数据、动态请求和公共接口能力。

2. 已核实的 GoView 基线

前端基线使用 H:\code\go-view 的官方 origin/master-fetch 分支。

功能 开源现状 第一阶段处理
我的项目 已有项目卡片、创建、保存、删除、发布和预览请求 本地 Gateway 实现兼容接口
我的模板 页面仅显示“暂时还没有东西呢” 新增模板列表和模板操作
模板市场 页面只展示 GoView Pro 宣传图和外链 替换为本地模板卡片列表
新建弹窗模板入口 “我的模板”和“模板市场”按钮处于禁用状态 启用并跳转到可用模板页
项目发布 已有 state 字段和发布按钮 保存状态,并生成公开预览链接
地图组件 有 ECharts 和高德地图组件,无离线 XYZ 瓦片背景组件 新增 Leaflet 瓦片背景组件

因此,项目画布本身不需要重写;模板中心不是“补一个后端开关”即可完成,必须同时补前端页面和接口。

3. 总体结构

GoView master-fetch 前端
   |
   | /api/goview/*
   v
DeerFlow Gateway
   |
   +-- 项目和项目内容
   +-- 个人模板和市场模板
   +-- 本地图片与缩略图
   +-- 已发布项目的只读数据
   +-- 离线地图瓦片

GoView 保持为独立的 Vue 前端。其他现有前端工程不参与第一阶段改造。

4. 接口兼容策略

4.1 保留现有项目接口前缀

GoView master-fetch 的请求前缀是 /api/goview,项目页和画布保存逻辑已经依赖下面的路径。Gateway 应优先兼容这些接口,避免改动画布同步逻辑。

方法和路径 请求 响应用途
GET /api/goview/project/list page、limit 我的项目卡片和分页
POST /api/goview/project/create JSON:projectName、remarks、indexImage 新建项目,返回 id
GET /api/goview/project/getData projectId 编辑器读取项目元信息和 content
POST /api/goview/project/save/data 表单:projectId、content 自动保存画布 JSON
POST /api/goview/project/edit JSON:id 和可编辑元信息 修改名称、说明或封面
POST /api/goview/project/rename JSON:id、projectName 快速重命名
DELETE /api/goview/project/delete ids 删除自己的项目
PUT /api/goview/project/publish JSON:id、state 发布或取消发布
POST /api/goview/project/upload multipart:object 上传本地缩略图或图片

响应保持 GoView 的 ResultEnum 约定:

{
  "code": 200,
  "msg": "获取成功",
  "data": {},
  "count": 0
}

项目列表的 count 与 data 同级,保持现有项目页的读取方式。项目详情使用现有字段 id、projectName、state、createTime、indexImage、createUserId、remarks 和 content。

4.2 新增模板接口

模板页面当前没有可复用接口,因此新增清晰的模板 API,不伪装成项目接口。

方法和路径 权限 用途
GET /api/goview/templates/mine 登录用户 我的模板列表和分页
POST /api/goview/templates/from-project 项目所有者 从一个项目创建个人模板
GET /api/goview/templates/{id} 模板所有者或市场可见 读取模板详情与 canvas JSON
PUT /api/goview/templates/{id} 模板所有者 修改名称、说明、封面
DELETE /api/goview/templates/{id} 模板所有者 删除个人模板
GET /api/goview/templates/market 登录用户或公开读取 模板市场列表
POST /api/goview/templates/{id}/create-project 登录用户 深拷贝模板为新项目并返回项目 id
POST /api/goview/templates/admin/seed 管理员或启动期内部调用 导入内置模板,不在普通 UI 展示

市场模板只能“使用并创建项目”,不能直接编辑模板内容。个人模板只能由模板创建者编辑或删除。管理员维护市场模板不需要引入租户、空间和成员模型。

4.3 已发布项目访问链接

编辑器继续使用:

/#/chart/home/{projectId}

发布后的用户访问链接使用原有预览路由:

/#/chart/preview/{projectId}

为了让链接在没有登录态时可直接访问,新增只读接口:

GET /api/goview/project/published/{projectId}

该接口仅当项目 state 为 1 时返回项目元信息和 content;未发布、已取消发布或不存在的项目统一返回 404。编辑器接口 getData 保持登录和所有者校验,不能为了预览方便而开放草稿。

预览页面启动时根据路由判断:

  1. 编辑预览或已登录所有者预览,读取 getData;
  2. 直接打开已发布链接,读取 published/{projectId};
  3. published 接口返回 404 时显示“项目未发布或不存在”页面。

发布接口成功后返回 relative_view_url,例如 /#/chart/preview/id_38xq54e9uoo000。前端用当前站点 origin 拼成完整链接并提供“复制链接”按钮,不在后端写死域名、端口或部署前缀。

5. 持久化设计

第一阶段只需要项目、项目内容、模板和本地资源存储。

5.1 goview_projects

字段 说明
id 字符串主键,兼容 GoView 的 id 路由参数
project_name 项目名
remarks 说明
state -1 未发布,1 已发布
index_image 缩略图资源地址
owner_id 当前登录用户 ID
created_at / updated_at 创建和更新时间

5.2 goview_project_contents

字段 说明
project_id 一对一关联项目,唯一
content_json GoView ChartEditStorage 的完整 JSON,使用 PortableLongText
updated_at 最后保存时间

列表查询不读取 content_json,只有编辑器和预览页读取,避免大画布 JSON 进入列表响应。

5.3 goview_templates

字段 说明
id 模板主键
name / description 模板名称和描述
cover_image 模板封面资源地址
content_json 可直接复制为项目内容的 GoView JSON
owner_id 个人模板的创建者;内置市场模板可为空
scope personal 或 market
is_builtin 内置模板标记;内置模板不可由普通用户删除
sort_order 市场排序
created_at / updated_at 创建和更新时间

5.4 本地资源目录

上传的图片、缩略图和模板封面保存到运行时可持久化目录,例如:

{runtime_dir}/goview-assets/

上传服务校验文件类型、大小、文件名和真实图片格式,使用服务端生成的随机文件名,禁止保留用户路径。资源通过 Gateway 的受控 GET 接口提供,不依赖 OSS、CDN 或公网地址。

离线发版的镜像、离线依赖和部署脚本与业务源码分开维护;业务源码仓库只保留接口、数据库迁移、内置模板定义和前端源码。

6. 身份与权限

不新建 GoView 用户系统。项目和模板直接复用平台现有登录态。

场景 规则
我的项目 只列出 owner_id 为当前用户的项目
我的模板 只列出 owner_id 为当前用户且 scope 为 personal 的模板
模板市场 所有登录用户可读 market 模板
创建项目 当前用户成为 owner
发布、保存、删除、重命名 仅项目 owner;无鉴权单用户部署按单管理空间规则处理
维护市场模板 管理员
发布项目预览 无需登录,但只读且仅返回已发布 content

GoView 现有 axios 登录逻辑依赖自己的 GO_SYSTEM_STORE 和 /login。第一阶段替换为平台现有 Bearer Token 与 Cookie 逻辑;这个改动只影响网络层和路由守卫,不改编辑器画布。

7. 前端最小改造清单

7.1 保持不动的部分

  • /chart/home/:id 的画布、左侧组件库、右侧样式/动画/数据/事件面板;
  • ChartEditStorage 的序列化结构;
  • useSync 中动态注册组件、恢复画布和自动保存机制;
  • 现有项目卡片布局和发布状态展示。

7.2 项目页

项目页继续调用现有 project.api.ts。适配 axios 的平台鉴权后,项目列表、新建、保存、删除、发布和缩略图上传可直接对接 Gateway。

项目卡片新增两个轻量操作:

  1. 复制发布链接:仅已发布时显示;
  2. 保存为模板:把当前项目的最新 content 创建为个人模板。

7.3 我的模板

替换 src/views/project/mtTemplate/index.vue 的空状态页。

页面提供模板卡片列表、分页、预览、编辑名称/描述/封面、删除和“使用模板”按钮。点击使用模板调用 create-project,成功后直接跳转 /chart/home/{newProjectId}。

新建弹窗中“我的模板”按钮解除禁用,跳转到该页面或直接打开模板选择抽屉。

7.4 模板市场

替换 src/views/project/templateMarket/index.vue 的 Pro 宣传图和外链。

页面读取 market 接口,以与项目卡片相同的视觉语言展示内置模板。市场模板至少准备:

  1. 深色通用数据驾驶舱;
  2. 地图基础概览大屏;
  3. 指标总览与趋势分析大屏;
  4. 时间轴与进度概览大屏。

模板内容作为版本化的内置 seed 文件随 Gateway 发布。首次启动只插入不存在的内置模板,后续升级不覆盖管理员已修改或新增的模板。

新建弹窗中“模板市场”按钮解除禁用,跳转到该页面或打开市场模板选择抽屉。

7.5 公开预览

预览页保留现有 /chart/preview/:id 和原始画布渲染。只修改加载项目数据的入口:未登录时走 published 接口,已登录编辑场景继续走 getData。预览页不显示编辑、保存、删除、模板和管理员操作。

8. 离线地图瓦片背景组件

8.1 目标

新增一个“地图瓦片背景”组件。第一阶段只提供离线底图和通用显示配置。

8.2 实现方式

在 GoView 组件库新增 Leaflet 组件:

src/packages/components/Business/Maps/LeafletTileBackground/
  config.ts
  index.vue
  config.vue

依赖使用 Leaflet 1.9,并在 GoView 入口加载 Leaflet CSS。组件作为普通 GoView 图层,可调整位置、尺寸、层级、边框、透明度和隐藏状态。

配置面板只暴露:

  • 底图样式:默认离线底图、管理员配置的其他离线底图;
  • 初始中心点和缩放级别;
  • 最小和最大缩放;
  • 是否允许鼠标缩放和拖拽;
  • 明暗遮罩、透明度和灰度效果。

不允许用户输入任意瓦片 URL,避免离线部署失效、内网地址泄漏和任意外部请求。

8.3 瓦片服务

Gateway 新增受控瓦片路由:

GET /api/goview/map-tiles/{style}/{z}/{x}/{y}.png

瓦片数据位于部署的可持久化目录或只读地图资源卷。路由严格校验 style、z、x、y 范围并阻止路径穿越。

第一期配置一个默认样式,对接部署时挂载的 XYZ 瓦片目录。GoView 组件始终只使用 Gateway 的受控地址。

编辑器内默认关闭地图拖拽,避免和画布选择、移动组件冲突;预览页可按组件配置开启交互。组件卸载时必须调用 map.remove(),避免切换项目时保留 DOM、瓦片和事件监听。

9. 后端代码落点

建议新增:

offline-backend-20260512/backend/
  app/gateway/routers/goview_projects.py
  app/gateway/routers/goview_templates.py
  app/gateway/routers/goview_assets.py
  app/gateway/routers/goview_map_tiles.py
  packages/harness/deerflow/persistence/goview/
    __init__.py
    models.py
    project_store.py
    template_store.py
  packages/harness/deerflow/persistence/migrations/versions/
    YYYYMMDD_NN_goview_projects_and_templates.py
  app/gateway/goview_builtin_templates.py
  tests/test_goview_projects.py
  tests/test_goview_templates.py
  tests/test_goview_assets.py

并在 app/gateway/deps.py 创建 Store,在 app/gateway/app.py 注册路由,在 persistence/models/__init__.py 导入 ORM 模型。Harness 只保存数据和仓储,HTTP 表单解析、上传、鉴权、公开预览和瓦片文件响应只放在 app/gateway。

10. 实施顺序

A. 项目闭环

  1. 实现 goview_projects 和 goview_project_contents;
  2. 兼容 project/list、create、getData、save/data、edit、rename、delete、publish、upload;
  3. 替换 GoView axios 登录逻辑为 DeerFlow 登录态;
  4. 实现 published 接口和复制发布链接。

验收:用户在当前画布编辑页保存,回到“全部项目”可以看到项目;发布后,无登录浏览器可通过 /#/chart/preview/{id} 查看同一画布。

B. 模板闭环

  1. 实现模板表和模板接口;
  2. 完成“保存为模板”和“我的模板”页面;
  3. 替换模板市场宣传页;
  4. 内置至少四套离线模板;
  5. 从任意模板创建独立项目。

验收:模板市场的模板不会被用户编辑;点击“使用模板”后生成新项目,修改新项目不会改变模板或其他用户的项目。

C. 地图瓦片背景

  1. 接入 Leaflet;
  2. 实现受控瓦片路由和默认离线瓦片配置;
  3. 新增 LeafletTileBackground 组件;
  4. 把地图背景加入至少一套内置模板。

验收:断开公网后,地图背景仍能显示;编辑器与预览页都不会因地图组件引发拖拽冲突或内存泄漏。

11. 测试清单

  1. 项目列表只返回当前用户的项目;
  2. 项目所有者外的登录用户不能读取、保存、删除或发布草稿;
  3. 已发布预览只返回 state 为 1 的项目;
  4. 取消发布后原公开链接返回 404;
  5. 项目 content 为大 JSON 时能完整保存和恢复;
  6. 模板创建项目为深拷贝,模板 content 不被后续项目保存覆盖;
  7. 内置模板重复启动不重复插入,不覆盖已存在记录;
  8. 上传拒绝非图片、超大文件和路径穿越文件名;
  9. 瓦片路由拒绝非法 style、缩放层级和路径穿越;
  10. 无公网网络下,项目缩略图、模板封面和默认瓦片可正常加载。