it-architecture/README.md

14 KiB
Raw Permalink Blame History

公司 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、latency
  • settings 平台配置(含 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 的写入方