# 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. 总体结构 ~~~text 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 约定: ~~~json { "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 已发布项目访问链接 编辑器继续使用: ~~~text /#/chart/home/{projectId} ~~~ 发布后的用户访问链接使用原有预览路由: ~~~text /#/chart/preview/{projectId} ~~~ 为了让链接在没有登录态时可直接访问,新增只读接口: ~~~text 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 本地资源目录 上传的图片、缩略图和模板封面保存到运行时可持久化目录,例如: ~~~text {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 组件: ~~~text src/packages/components/Business/Maps/LeafletTileBackground/ config.ts index.vue config.vue ~~~ 依赖使用 Leaflet 1.9,并在 GoView 入口加载 Leaflet CSS。组件作为普通 GoView 图层,可调整位置、尺寸、层级、边框、透明度和隐藏状态。 配置面板只暴露: - 底图样式:默认离线底图、管理员配置的其他离线底图; - 初始中心点和缩放级别; - 最小和最大缩放; - 是否允许鼠标缩放和拖拽; - 明暗遮罩、透明度和灰度效果。 不允许用户输入任意瓦片 URL,避免离线部署失效、内网地址泄漏和任意外部请求。 ### 8.3 瓦片服务 Gateway 新增受控瓦片路由: ~~~text GET /api/goview/map-tiles/{style}/{z}/{x}/{y}.png ~~~ 瓦片数据位于部署的可持久化目录或只读地图资源卷。路由严格校验 style、z、x、y 范围并阻止路径穿越。 第一期配置一个默认样式,对接部署时挂载的 XYZ 瓦片目录。GoView 组件始终只使用 Gateway 的受控地址。 编辑器内默认关闭地图拖拽,避免和画布选择、移动组件冲突;预览页可按组件配置开启交互。组件卸载时必须调用 map.remove(),避免切换项目时保留 DOM、瓦片和事件监听。 ## 9. 后端代码落点 建议新增: ~~~text 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. 无公网网络下,项目缩略图、模板封面和默认瓦片可正常加载。