|
|
||
|---|---|---|
| .idea | ||
| backend | ||
| frontend | ||
| .gitignore | ||
| README.md | ||
| dev.sh | ||
| start.sh | ||
README.md
公司 IT 系统全景与数据流向平台
把原来那份单文件 index.html(公司 IT 系统全景图)升级成一个真正可运行的系统:
Python 后端 + SQLite 持久化 + 可配置前端,多人访问同一份数据,不再依赖浏览器 localStorage。
与原版页面的对应关系
| 原版页面 | 现在的去向 |
|---|---|
| ① 系统全景总览 | 保留为「系统全景总览」,字段编辑改为写库,所有人共享;新增「快捷入口」直达各系统 |
| ② 系统关系与业务链路 | 按要求删除,其信息已并入数据流向图 |
| ③ 目标架构与迁移规划 | 改为数据流向图:带流动动画,且可直接拖拽摆放、拉线建流 |
| 系统交换明细 | 按要求移除,该位置改为「Agent 布局总览图」占位页 |
| localStorage + 导出离线 HTML | 改为 SQLite + 配置备份 JSON 导入/导出 |
| 乐观锁单文档同步 | 改为按行 CRUD,附变更审计(谁在什么时候改了什么) |
目录结构
backend/ FastAPI + 标准库 sqlite3(无 ORM)
app/db.py 连接、建表、显式事务
app/seed.py 内置清单:3 层级 / 18 系统 / 6 数据类型 / 36 条数据流
app/services/ 指标生成(metrics)与图布局(graph)
app/routers/ content(层级/系统/类型/配置)、flows、graph、backup
tests/ 63 条 pytest
frontend/ Vue 3 + Vite + TS + Tailwind + Pinia(组件风格取自 sub2api)
src/components/ common / icons / layout / panorama / flow
src/views/ 全景、数据流向图、Agent 布局总览图(占位)、配置、审计
启动
./start.sh # 生产式:单进程提供 API + 页面,http://localhost:8787
./dev.sh # 开发式:后端 8787 热重载 + 前端 5273 HMR
python3 -m pytest -q # 后端测试(在 backend/ 目录下)
npm run typecheck # 前端类型检查(在 frontend/ 目录下)
数据库默认 backend/panorama.db,用 DB_PATH=/path/to.db 可改位置。直接复制该文件即整库备份。
数据模型
layers层级(通用 / 部门业务 / 底座),决定全景图分区systems系统清单:状态、技术栈、地址、域名、负责人、说明、impl_time(实现时间)、entry_enabled(是否展示快捷入口),tier决定数据流向图所在列flow_types数据类型:决定连线颜色与线型,取值遵循下面「一眼看出主流向」一节的统一图例data_flows数据流:起止系统、传输内容、方向、触发间隔 / 单次条数 / 单批体积 / 时延 / 同步异步 / 高峰时段flow_metrics按小时聚合的 batches、records、bytes、errors、latencysettings平台配置(含editing_enabled全站编辑开关、flow_route_style连线线型),audit_logs变更审计
系统跳转入口与实现时间
「系统配置 · 系统跳转入口」是一行一个系统的编辑表:跳转地址、是否展示快捷入口、实现时间。
保存后「系统全景总览」顶部出现「快捷入口」一排按钮,点中系统卡片时右侧也会出现「访问系统」。
地址留空则退回用域名打开,两者都没填时这一排会给出填写指引而不是整排消失。
地址不带协议前缀(如 oa.example.com)时自动补 http://,否则浏览器会当成本站相对路径跳错页面。
「实现时间」是自由文本(2024-06 上线、2023 Q4 立项 / 2024-08 验收 都行),
在系统详情栏和跳转入口表两处都能填,同一个字段。
系统名称随时可改
名称是普通字段,不是建档后就锁死的表头:全景总览选中系统后,右侧详情栏第一个输入框就是「系统名称」;
「系统配置 · 系统跳转入口」那一行的系统名也能直接改,回车或失焦即保存。
改名只动展示名,key 作为主键不变,数据流的起止点、画布上的摆放位置都不受影响;
全景图、数据流向图、快捷入口、汇报清单读的都是改名后的名字。
空白名称前端不提交、后端返 422,超长名称截到 80 字,改动照旧进变更审计。
汇报模式与图片导出
数据流向图工具条上的「汇报模式」把画布换成整屏演示视图(components/flow/FlowPresentation.vue):
- 图占满整屏,卡片、连线、层级列头按可用空间放大,不再有统计卡与工具条抢位置
- 「线型」三选一(折线 / 曲线 / 直线,默认折线),当场切给听众看,选中的存进
flow_route_style - 「突出主流向」默认打开:自右向左的回流链路压到很淡,先看清 ①→②→③→④ 这条主干
- 「流向」分步按钮 ①→② / ②→③ / ③→④ / 跨列,一次只讲一跳,其余链路退到底色, 右侧清单同步只列这一跳的链路,讲完点「全部」回到整图
- 关系名称默认不显示(挑中一跳、悬停或选中卡片时才出现),要逐条念就勾「显示全部关系名称」
- 右侧「汇报清单」两个标签页:「业务链路」按数据类型分组编号,从上往下念就是一条条业务线, 点一条即在画布上聚焦;「系统清单」按层级列分组,附每个系统的入向 / 出向链路数与尚未接入的系统
- 顶部图例可点(只看某一类链路),可关流动动画、切速度;
Esc或「退出」回到编辑视图 - 「导出图片」出 2× PNG(可直接贴 PPT),「SVG」出矢量图:导出的就是屏幕上这套几何,
含标题、统计、图例、层级列与生成时间,走线与线型跟着屏幕上选的来(
components/flow/flowExport.ts)
一眼看出主流向
四十条链路挤在一张图上,靠的是四件事(都在 components/flow/flowLayout.ts):
- 三种线型:
折线(默认,直角走线,线段走列与列之间的走廊,交叉最少)、曲线(弧线,画面柔和)、直线(两点直线,最短最直接,链路多时交叉会变多)。走线偏好存settings.flow_route_style - 走廊走线:每条链路只走它终点前面那条走廊,同走廊的链路按高度排槽位,走廊内部不再互相交叉; 同列互传的链路走列旁的水沟,不从中间卡片上压过去
- 边绑定:汇入同一个系统的同类链路(例如十来个系统都去 UniHub 做 SSO 票据校验)共用走廊里同一条 干线,到卡片前才散成各自的接入点,画面上先看到一股粗绳、再看到十几条支线;折线共用干线, 曲线在干线上的同一点汇聚,直线保持一对一。干线只在两条以上链路真正重叠的那一段画出来
- 列内重心排序:卡片按与它通信的卡片的平均高度来回微调(左右各扫三轮),互相调用的系统自然对上, 大部分链路变成短横跳而不是斜穿四列;排序种子与并列规则固定,每次打开都是同一张图
主次靠墨量分:线条宽 1~3.4px、不透明度 32%~92% 都由同步节奏换算,分钟级高频链路粗而实, 夜间批量细而淡;汇报模式的「突出主流向」再把回流链路压到 18%。
颜色与线型是一套统一图例(components/flow/flowStyle.ts,种子数据与配置页都按它取值):
| 编码 | 含义 | 线型 |
|---|---|---|
| 蓝 | API / 同步调用(核心业务链路、底座能力调用) | 实线 |
| 紫 | 鉴权 / MCP 取数(统一认证、智能体取数) | 实线 / 点划线(定时) |
| 绿 | 异步消息 / 事件推送 | 虚线 |
| 灰 | 定时任务 / 归档沉淀 | 点划线 |
| 红 | 人工操作 / 线下流程 | 点划线 |
线型本身即节奏:实线同步调用、虚线异步消息、点划线定时任务或人工、点线低频参考链路。
图例在编辑视图、汇报模式和导出的 SVG 里都由同一个组件画(components/flow/FlowLegend.vue),
颜色前面带真实线型的小样,不会出现图例和画面对不上。
卡片也按层级上色:入口青、中枢绿、业务蓝、底座橙,列带只包到自己卡片的高度, 两系统的入口层不再拖出一条空白长条;入向 / 出向数量挪到卡片右上角的小角标,卡面只剩系统名和归属。
只读模式
「系统配置 · 平台配置」里的「允许编辑」是全站开关。关掉后:
- 各页面隐藏新增 / 编辑 / 删除入口,表单只读,顶部出现「只读模式」标记
- 后端所有写接口返回
423,被拒绝的请求不会写入任何数据,也不会留下审计记录 - 数据流向图的拖拽摆放、拉线建流、恢复自动排列同样被锁住(画布仍可查看与播放动画)
- 读取与指标接口不受影响;
PATCH /api/settings始终开放,否则就无法解锁
数据流动情况是怎么定出来的
初始 36 条链路按业务语义分为 6 类,节奏取自真实系统常见形态,可在界面上随时改:
| 类型 | 典型链路 | 节奏设定 |
|---|---|---|
| 核心业务链路 | PMS 预算闸门 ⇄ OA、OA 合同→OMS、SCC 归档转订单、报销→财务助理→金蝶 | 10~60 分钟批量,同步为主 |
| 移动端入口 / 消息 | OA→企微 待办与收款群通知、企微→财务助理 PDF 报销、企微→EDRS 填报提醒 | 5 分钟级高频小包 |
| MCP 取数(Agent) | unibot ⇄ PMS / OMS / SCC / EDRS、unibot ⇄ UniTensor 算力 | 小时级取数,单次数据量大 |
| 底座能力调用 | 财务助理→k3s OCR/对象存储、docs→UniTensor 推理、DMS→镜像仓库 | 分钟级,单批体积跨度大 |
| 统一认证 SSO | 各业务系统→UniHub 票据校验 | 高频极小包(约 4 KB) |
| 归档 / 知识沉淀 | OA→NAS 盖章合同原件、docs→ekb 知识沉淀、unibot→ekb 检索 | 低频大文件 |
历史流量不是写死的常量:services/metrics.py 用每条链路的节奏乘以一条工作时段曲线(含午休回落、夜间低谷、周末系数)生成 30 天逐小时记录,并按固定随机种子加抖动,因此重跑结果稳定;POST /api/metrics/tick 再往当前小时累加增量,让看板上的数字持续变化。
数据流向图是可以直接编辑的画布
图上的东西就在图上改,不用绕去配置页:
- 「选择 / 摆放」模式下按住系统卡片就能拖,松手即落位;拖到别的列会同时改掉它的层级,列带高亮提示会落到哪一列
- 「连线」模式下从一张卡片拖到另一张卡片,松手后弹出已填好起止点的数据流表单,补一个关系名称就建好这条链路;不想拖也行,先点起点卡片再点终点卡片
- 工具条上的「新增系统」在当前列补一张卡片;「自动整理」清掉全部手动位置回到自动排列
- 位置存在
systems.flow_x / flow_y,刷新与换人打开都是同一张图;PUT /api/graph/layout一次拖拽记一条审计,POST /api/graph/layout/reset恢复自动
流动感是怎么实现的
这一屏只回答"谁在什么时候往哪儿传什么",因此画面上没有任何流量数字(条数、体积、时延、本小时都在「系统配置 · 数据流」和历史趋势页看):
- 粒子密度与速度取自链路节奏:
cadence = √(1 - log(间隔秒) 映射到 30 秒~6 小时),分钟级链路密而快,夜间批量疏而慢,同步调用再加一点 - 动画时长按路径长度与强度反比计算,再除以全局速度倍率;每条链路的粒子用负
begin偏移错开,均匀铺在路径上而不是首尾相接 - 连线标签只显示关系名称,卡片上只显示入向 / 出向链路数
- 顶部可关动画(投屏/低配设备)、调 0.25×~3× 速度、按数据类型筛选
图本身是自适应的(components/flow/flowLayout.ts),换窗口大小不会把系统卡片切掉:
- 列间距按面板宽度分配,行间距按面板高度分配;装不下时整图等比缩小(下限 0.68),省出来的宽度回补给列间距
- 同一侧的多条连线在卡片边缘按对端位置排槽位,八条 SSO 链路各走各的接入点,不会挤成一团
- 连线说明逐条摆放:先按序号在本条曲线上取位,再依次试其他位置,避开系统卡片与已放好的说明;实在放不下就先隐藏,鼠标移到连线或选中对应系统时再出现
- 右侧详情栏只在选中连线/系统时出现,平时让图占满整宽;选中系统时给出上下游链路清单,可直接点进某一条
- 每列顶部标出层级名与该列的系统数,卡片上的状态点含义写在图例行右侧,不用回全景图对照
- 没有任何筛选时,还没接上链路的系统也会留在画布上(它们正是等着被连线的对象);一旦筛选就只显示命中子图
接口一览
/api/layers /api/systems /api/flow-types /api/flows 均为标准 REST;
读模型 /api/graph(含拓扑计数 counts)/api/metrics/summary|hourly|live|flows/{id} /api/audit;
画布布局 PUT /api/graph/layout POST /api/graph/layout/reset;
配置 /api/settings;备份 /api/backup(mode 支持 replace / merge)。
写请求通过 X-Editor 请求头记录编辑者(含中文时前端自动百分号编码,后端解码)。
交互文档:启动后访问 /docs。
已知边界
- 单文件 SQLite + WAL,适合部门级内部工具;更高并发请换 PG/MySQL
- 数据流向图以桌面屏为主,窄屏下侧栏收成图标栏,图区内可横向拖动查看
- 指标由链路配置推导而来,不是真实采集数据;接入真实埋点时只需改写
flow_metrics的写入方