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

367 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. 无公网网络下,项目缩略图、模板封面和默认瓦片可正常加载。