367 lines
15 KiB
Markdown
367 lines
15 KiB
Markdown
# 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. 无公网网络下,项目缩略图、模板封面和默认瓦片可正常加载。
|