# platform-studio **Repository Path**: newpc/platform-studio ## Basic Information - **Project Name**: platform-studio - **Description**: 多行业管理平台工程:682 个 Vue 3 前端项目 + 统一多租户 Go 后端 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-06 - **Last Updated**: 2026-11-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Platform Studio [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) 多行业管理平台工程。**一个统一 Go 后端 + 173 个独立 Vue 3 前端项目**, 覆盖 30 个行业族的后台管理系统、数据大屏与门户官网。 - 统一访问入口:`http://<服务器>:7802/index.html`(项目库);本地预览 `http://127.0.0.1:8090/` - 统一账号:`admin` / `admin123` 每个项目都是一套完整产品:**对外门户**(`/#/portal`)+ **运营大屏**(`/#/screen`)+ **后台管理**(登录、工作台、列表、详情、分析、设置),共用同一后端租户。 --- ## 当前状态(2026-11-10 实测) | 口径 | 数量 | 说明 | | --- | --- | --- | | 行业族 | **30** | 每族保留 3 个风格不同的实现,合计 90 个 | | 新增独立行业(不成族) | **68** | 单实现行业,如城市轨道交通、冷链物流、智能充电桩、医院后勤、城市公厕等 | | `projects/` 下的前端项目 | **173** | 全部可构建、可登录、可访问 | | 项目库 `shares/gallery/` 收录 | **173** | 全部可预览 | | 统一后端租户目录 | **174** | `platform-api/internal/tenants/`(173 个项目 + `demo` 范例) | | 统一后端**实际挂载**租户 | **174** | 启动日志「已挂载 174 个租户」,零失败 | | 门户页(`/#/portal`) | **173** | 每项目一个对外门户,项目库卡片上直接带「进入门户」按钮 | | 大屏项目(`/#/screen`) | **166** | 按行业分多种版式,含统一体系与定制实现 | | 同时具备门户 + 大屏 + 后台三件套 | **165** | — | | 前端页面总数 | **2939** | 平均 17 页/项目 | | 路由引用不存在的组件 | **0** | — | | `src/views/` 完全为空的目录 | **0** | — | 回归验证(2026-11-10 实测): | 检查项 | 结果 | | --- | --- | | 后端登录 `admin`/`admin123` | **174 / 174** 返回 `code=0` 且有 token | | 业务接口全量探测 | **173 / 173** 项目返回 `code=0` 且有数据 | | 前端 `tsc --noEmit` | 通过 | | 前端 `node scripts/frontend.mjs build` | **173 / 173** 成功 | | 接口基址合规 | 全部绝对路径 `/api/v1/<项目名>`,0 个纯相对路径 | | 每族实现数 | 30 族 × 3,无超限 | | 租户挂载失败 | 0 | | `verify.json` 覆盖率 | **173 / 173** | > 各项目 `verify.json` 的 `status`:**140 个 `success`**、**33 个 `partial`**。 > `partial` 的项目均已在各自 `verify.json` 的 `issues` 中写明缺口(多为未做浏览器视觉验证 > 或少数页面交互待补),不做美化。 > **数据质量是怎么验的**:只看接口 `code=0` 不够——接口成功但返回 > `{"category":""}` 这类空分组,图表照样会画出无名扇区。 > 因此额外遍历各项目的看板/统计接口,递归检查 > `name`/`category`/`region`/`status`/`level`/`channel` 等分组字段是否为空, > 再回溯到数据库把垃圾行删掉、缺失字段按行业语义补中文值、 > 分组查询加空值过滤。首轮查出 119 处,现已全部清零。 > **为什么是「30 族 × 3 + 68 个独立行业」**:仓库一度有 683 个前端项目、704 个租户, > 其中大量版本之间**完全重复**。2026-11-08 按四项指纹做了两轮去重清理, > 最终每族保留 3 个差异最大的实现,详见[项目精简说明](#项目精简说明)。 --- ## 效果预览 以下截图全部从本地 8090 预览站**实际渲染后截取**(1600×900), 图注中的项目名即 `projects/` 下的目录名,可直接对照源码。分三类: | 类别 | 数量 | 说明 | | --- | --- | --- | | 行业后台工作台 | 31 | 每个行业族一张,覆盖浅色商务风与深色科技风 | | 门户版式 | 6 | 6 种结构完全不同的门户版式各一个代表 | | 项目库首页 | 1 | 173 张项目卡片的索引页 | 采集结果:**31/31 打开成功、0 个 JS 报错、正文均超过 700 字**。 其中 30 张是登录后的后台工作台;`retail-pos` 族按其产品设计呈现为官网门户首页。 > **截图缺口(如实说明)**:数据大屏(`/#/screen`)目前**没有收录截图**, > 原因是采集需要 Playwright + Chromium,而当前开发环境未安装且被约束禁用。 > 大屏的实际效果请起预览站后访问 `http://127.0.0.1:8090/<项目名>/index.html#/screen` 查看。 | 零售连锁 · `retail-pos-v5` | 酒店 PMS · `hotel-pms` | | --- | --- | | ![零售连锁](docs/screenshots/01-retail.jpg) | ![酒店 PMS](docs/screenshots/02-hotel.jpg) | | 电力电网 · `power-grid-v20` | 博物馆 VR · `museum-vr` | | --- | --- | | ![电力电网](docs/screenshots/03-power.jpg) | ![博物馆 VR](docs/screenshots/04-museum.jpg) | | 农业溯源 · `agri-trace` | 人力招聘 · `hr-recruit` | | --- | --- | | ![农业溯源](docs/screenshots/05-agri.jpg) | ![人力招聘](docs/screenshots/06-hr.jpg) | | 物流调度 · `logistics-dispatch` | 水务公用 · `water-utility` | | --- | --- | | ![物流调度](docs/screenshots/07-logistics.jpg) | ![水务公用](docs/screenshots/08-water.jpg) | | 医药 GSP · `pharma-gsp` | 矿山安全 · `mining-safety` | | --- | --- | | ![医药 GSP](docs/screenshots/09-pharma.jpg) | ![矿山安全](docs/screenshots/10-mining.jpg) | | 教育校园 · `edu-campus` | 金融风控 · `fin-risk` | | --- | --- | | ![教育校园](docs/screenshots/11-edu.jpg) | ![金融风控](docs/screenshots/12-fin.jpg) | | 法律服务 · `legal-case` | 保险理赔 · `insurance-claim-v23` | | --- | --- | | ![法律服务](docs/screenshots/13-legal.jpg) | ![保险理赔](docs/screenshots/14-insurance.jpg) | | 能源监测 · `energy-monitor` | 森林防火 · `forest-fire` | | --- | --- | | ![能源监测](docs/screenshots/15-energy.jpg) | ![森林防火](docs/screenshots/16-forest.jpg) | | 环境监测 · `env-monitor` | 医疗诊所 · `health-clinic` | | --- | --- | | ![环境监测](docs/screenshots/17-env.jpg) | ![医疗诊所](docs/screenshots/18-health.jpg) | | 制造 MES · `manufacture-mes` | 汽车经销 · `auto-dealer` | | --- | --- | | ![制造 MES](docs/screenshots/19-mes.jpg) | ![汽车经销](docs/screenshots/20-auto.jpg) | | 体育赛事 · `sports-league` | 餐饮连锁 · `food-chain` | | --- | --- | | ![体育赛事](docs/screenshots/21-sports.jpg) | ![餐饮连锁](docs/screenshots/22-food.jpg) | | 机场运营 · `airport-ops` | 政务事件 · `gov-event` | | --- | --- | | ![机场运营](docs/screenshots/23-airport.jpg) | ![政务事件](docs/screenshots/24-gov.jpg) | | 港口码头 · `ports-terminal` | 园区物业 · `park-property` | | --- | --- | | ![港口码头](docs/screenshots/25-ports.jpg) | ![园区物业](docs/screenshots/26-park.jpg) | | 传媒融媒 · `media-content` | 交通信号 · `traffic-signal` | | --- | --- | | ![传媒融媒](docs/screenshots/27-media.jpg) | ![交通信号](docs/screenshots/28-traffic.jpg) | | 电信用户 · `telecom-subscriber` | 工地建造 · `construction-site` | | --- | --- | | ![电信用户](docs/screenshots/29-telecom.jpg) | ![工地建造](docs/screenshots/30-construction.jpg) | | 驾驶培训 · `driving-school` | | | --- | --- | | ![驾驶培训](docs/screenshots/31-driving.jpg) | | > 深色科技风(电力、能源、矿山等)与浅色商务风(酒店、医药、法律等)并存, > 各项目按行业语义自行设计视觉语言,不使用 Element Plus 默认外观。 > 想自己复现截图:起预览站后访问 > `http://127.0.0.1:8090/<项目名>/index.html`,用 `admin` / `admin123` 登录即可。 ### 门户版式预览 同一个仓库里的门户**不是套模板换文案**,而是按行业族分 6 种结构完全不同的版式。 下面 6 张是各组的一个代表(1600×900,实际渲染截取): | 控制台式 · `data-center-ops` | 旅程式 · `agri-trace` | | --- | --- | | ![控制台式门户](docs/screenshots/31-portal-console.jpg) | ![旅程式门户](docs/screenshots/32-portal-journey.jpg) | | 矩阵式 · `construction-site` | 编辑式 · `edu-campus` | | --- | --- | | ![矩阵式门户](docs/screenshots/33-portal-grid.jpg) | ![编辑式门户](docs/screenshots/34-portal-editorial.jpg) | | 展示式 · `food-chain` | 分屏式 · `health-clinic` | | --- | --- | | ![展示式门户](docs/screenshots/35-portal-showcase.jpg) | ![分屏式门户](docs/screenshots/36-portal-split.jpg) | ### 项目库首页 ![项目库首页](docs/screenshots/37-gallery.jpg) 行业分类默认只占一行,右侧「展开全部 ▾」铺开全部 40+ 个行业标签; 每张卡片都带绿色「进入门户 →」和蓝色「进入大屏 →」两个入口。 --- ## 项目精简说明 仓库一度膨胀到 683 个前端项目、704 个后端租户,其中大量版本只是同一份代码换个目录名。 2026-11-08 做了一次系统性去重。 ### 判断依据 为每个项目计算四项指纹,两两做 Jaccard 相似度: | 维度 | 取数来源 | | --- | --- | | 页面清单 | `frontend/src/views/**/*.vue` 的相对路径集合 | | 前端路由 | `frontend/src/router/index.ts` 中的 `path` 集合 | | 后端接口 | 租户目录下 `*.go` 里注册的 `METHOD + path` 集合 | | 数据表 | `model.go` 中 `TableName()` 返回的表名集合 | 结果:**30 个族中有 28 个存在相似度 = 1.000 的完全重复版本** (如 `edu-campus` 有 21 对、`insurance-claim` 有 21 对、`airport-ops` 有 15 对完全相同)。 ### 保留算法 每族保留 K = 4: 1. 先保留**无版本后缀的主项目**(如 `retail-pos`)作为种子 2. 反复挑选「与已选集合相似度最低」的成员,使 4 个之间风格差异最大 3. 相似度 ≥ 0.999 的成员视为重复,优先级降低 ### 结果 | 项 | 清理前 | 清理后 | | --- | --- | --- | | 前端项目 | 683 | **134** | | 后端租户 | 704 | **135** | | `registry.go` 登记 | 704 | **135** | | gallery 静态副本 | 682 | **134** | > 上表是 2026-11-08 去重当日的快照。此后又持续新增独立行业项目, > 当前已增长到 **173 个项目 / 174 个租户**(见[当前状态](#当前状态2026-11-10-实测))。 清理过程用 `git rm` 提交,被删内容全部保留在 Git 历史中,可随时检出恢复。 ### 保留清单 | 行业族 | 保留的 3 个实现 | | --- | --- | | agri-trace | `agri-trace` `agri-trace-v16` `agri-trace-v3` | | airport-ops | `airport-ops` `airport-ops-v24` `airport-ops-v8` | | auto-dealer | `auto-dealer` `auto-dealer-v17` `auto-dealer-v27` | | construction-site | `construction-site` `construction-site-v29` `construction-site-v3` | | edu-campus | `edu-campus` `edu-campus-v18` `edu-campus-v28` | | energy-monitor | `energy-monitor` `energy-monitor-v22` `energy-monitor-v3` | | env-monitor | `env-monitor` `env-monitor-v2` `env-monitor-v24` | | fin-risk | `fin-risk` `fin-risk-v10` `fin-risk-v19` | | food-chain | `food-chain` `food-chain-v3` `food-chain-v9` | | forest-fire | `forest-fire` `forest-fire-v17` `forest-fire-v19` | | gov-event | `gov-event` `gov-event-v10` `gov-event-v5` | | health-clinic | `health-clinic` `health-clinic-v19` `health-clinic-v24` | | hotel-pms | `hotel-pms` `hotel-pms-v17` `hotel-pms-v4` | | hr-recruit | `hr-recruit` `hr-recruit-v10` `hr-recruit-v26` | | insurance-claim | `insurance-claim` `insurance-claim-v2` `insurance-claim-v9` | | legal-case | `legal-case` `legal-case-v17` `legal-case-v23` | | logistics-dispatch | `logistics-dispatch` `logistics-dispatch-v20` `logistics-dispatch-v24` | | manufacture-mes | `manufacture-mes` `manufacture-mes-v29` `manufacture-mes-v5` | | media-content | `media-content` `media-content-v19` `media-content-v4` | | mining-safety | `mining-safety` `mining-safety-v16` `mining-safety-v24` | | museum-vr | `museum-vr` `museum-vr-v17` `museum-vr-v26` | | park-property | `park-property` `park-property-v10` `park-property-v2` | | pharma-gsp | `pharma-gsp` `pharma-gsp-v19` `pharma-gsp-v6` | | ports-terminal | `ports-terminal` `ports-terminal-v20` `ports-terminal-v26` | | power-grid | `power-grid` `power-grid-v20` `power-grid-v4` | | retail-pos | `retail-pos` `retail-pos-v13` `retail-pos-v5` | | sports-league | `sports-league` `sports-league-v3` `sports-league-v6` | | telecom-subscriber | `telecom-subscriber` `telecom-subscriber-v14` `telecom-subscriber-v21` | | traffic-signal | `traffic-signal` `traffic-signal-v13` `traffic-signal-v28` | | water-utility | `water-utility` `water-utility-v11` `water-utility-v5` | --- ## 目录结构 ``` platform-api/ 统一 Go 后端(单进程、多租户) ├── main.go 入口 ├── registry.go 租户登记表(174 条) ├── internal/kernel/ 框架内核:认证 / 响应 / 错误码 / 中间件 / 租户上下文 ├── internal/tenants/ 每租户一个目录,内部再分 legacy 与原生实现 └── data/ 每租户独立 SQLite(不入库) projects/ 173 个前端项目 └── <项目名>/ ├── README.md 项目说明 ├── verify.json 验收记录 └── frontend/ Vue 3 + Vite + Element Plus + ECharts 源码 (依赖统一取仓库根 node_modules,本目录不再安装) docs/screenshots/ README 引用的 38 张截图(31 张行业后台 + 6 张门户版式 + 1 张项目库) 注:大屏截图未收录,原因见「效果预览」 package.json 全仓唯一的前端依赖清单 node_modules/ 全仓唯一的前端依赖(不入库) scripts/frontend.mjs 统一构建 / 启动 / 预览站脚本 shares/ 项目库首页与 nginx 配置 ``` --- ## 快速开始 ### 1. 安装依赖(全仓只需一次) 173 个前端**不各自安装依赖**,统一使用仓库根目录的 `node_modules`: ```bash cd <仓库根> npm install # 只装这一次,173 个前端共用 ``` 新增依赖时改根 `package.json` 后重新 `npm install`,不要在 `projects/*/frontend` 下装。 机制细节见 [`DEPENDENCIES.md`](DEPENDENCIES.md)。 ### 2. 启动后端 ```bash cd platform-api go mod download go build -o ../bin/platform-api-server . ../bin/platform-api-server # 默认监听 :4500 ``` 首次启动会自动创建 `platform-api/data/<租户>.db` 并写入种子数据与 `admin` 账号。 启动约需 90–150 秒(174 个租户依次建表、写种子)。 > **验证启动成功**:日志里出现 `已挂载 174 个租户` 且**没有** `挂载失败已跳过`。 > 若出现后者,说明该租户路由重复注册导致 Gin panic,整个租户被跳过。 端口被占用时用 `PORT` 覆盖: ```bash PORT=4520 ./bin/platform-api-server ``` > **Windows 注意**:本机存在系统保留端口段(`netsh interface ipv4 show excludedportrange protocol=tcp` > 可见 `4412-4511` 等),若启动报 `bind: An attempt was made to access a socket in a way forbidden`, > 说明目标端口落在保留段内,换个端口即可,不必改代码。 ### 3. 构建与预览 ```bash node scripts/frontend.mjs list # 列出全部项目与构建状态 node scripts/frontend.mjs build agri-trace # 构建单个项目(省略项目名则全部构建) node scripts/frontend.mjs dev agri-trace hotel-pms # 启动开发服务器 node scripts/frontend.mjs gallery # 汇总已构建项目到 shares/gallery node scripts/frontend.mjs preview # 预览站 http://127.0.0.1:8090/ ``` 也可在单个项目里执行 `npm run dev` / `npm run build`,效果相同。 > **重要**:8090 预览服务提供的是 `shares/gallery/` 的静态副本,**不是** `dist/`。 > 每次 `build` 之后必须再跑一次 `gallery`,否则预览站看到的仍是旧产物。 `preview` 会把 `/api/*` 反代到统一后端,本地没有 nginx 也能登录: ```bash API_TARGET=http://127.0.0.1:4520 node scripts/frontend.mjs preview # 后端不在默认 4500 时 PREVIEW_PORT=8099 node scripts/frontend.mjs preview # 换预览端口 ``` > **预览站路径约定(容易踩坑)**:8090 预览服务**不支持目录式访问**, > `http://127.0.0.1:8090/<项目名>/` 会返回 404,必须请求 `http://127.0.0.1:8090/<项目名>/index.html`。 > 项目库首页在根路径 `http://127.0.0.1:8090/`。 --- ## 架构要点 **一个后端,多租户隔离。** 所有项目共用 `platform-api` 一个 Go 进程(默认端口 4500), 通过 URL 中的项目名区分:`/api/v1/<项目名>/...`。 每个租户的数据落在独立的 SQLite 文件里,JWT 中带 `tenant` 字段,跨租户使用 token 会被拒绝。 **认证、用户、日志、响应封装、CORS、panic 恢复全部由框架提供**, 业务代码只写模型、仓储、服务、路由四层。 ### 新增一个租户 1. 建目录 `platform-api/internal/tenants/<项目名>/` 2. 写 `model.go` / `repository.go` / `service.go` / `handler.go` / `router.go` 3. 在 `registry.go` 的 `Entries()` 加一行(同时补 import) 4. `cd platform-api && go build -o ../bin/platform-api-server .` 5. 重启后端,框架自动建库、建表、写默认账号 6. 重启后检查日志:`已挂载 N 个租户`、零 `挂载失败已跳过` 参考范例:`platform-api/internal/tenants/demo/`。设计说明见 [`ARCH-platform-api.md`](ARCH-platform-api.md)。 ### 前端硬性约定 - `vite.config.ts` 必须 `base: './'` - 路由必须 `createWebHashHistory()` - 接口基址必须是 `/api/v1/<项目名>`(不能写成 `./api/v1` 或 `http://localhost:端口`) 因为项目部署在 `http://<服务器>:7802/<项目名>/` 子目录下,违反任一条都会导致白屏或接口 404。 ### 前端依赖解析 每个 `vite.config.ts` 里的关键片段(自动生成,勿删): ```ts resolve: { modules: [ fileURLToPath(new URL('../../node_modules', import.meta.url)), fileURLToPath(new URL('./node_modules', import.meta.url)), ], }, server: { fs: { allow: [fileURLToPath(new URL('../..', import.meta.url))] } }, ``` `resolve.modules` 让 Vite 去根 `node_modules` 找依赖;`server.fs.allow` 允许开发服务器读取根目录依赖。 ### 前端契约补齐层(compat.go) 部分历史租户的原生接口与前端字段约定不一致(前端要 `/inspections`,后端只有 `/audits`)。 这类缺口不靠改前端,而是在租户目录下加一个 `compat.go` 做**运行时列探测**补齐: - 启动时读 `sqlite_master` 与 `pragma table_info()`,按候选列名挑出真实存在的列 - 用 `pick(cols, ...)` 选列,`pickQ(cols, fallback, ...)` 在列缺失时退化为字面量 - 查询统一 `db.Raw(...).Scan(&[]map[string]interface{})`,避开历史文本列扫进 `time.Time` / `float64` 的失败 - `Create*` 用 `_ = ctx.ShouldBindJSON(&in)`,只写存在的列,容忍前后端字段名漂移 **红线**:compat 绝不能注册租户已经注册过的路径——Gin 会 `panic: handlers are already registered`, 整个租户被跳过(`已挂载` 计数会直接减少)。补路由前必须先扫描租户真实注册的路径。 --- ## 项目库首页 `gallery` 生成的 `shares/gallery/index.html` 每张卡片展示: - **中文名称**:优先取 `verify.json` 的 `title`,其次取 `registry.go` 的 `Title`, 再取 `frontend/index.html` 的 ``,最后按行业给默认名;同名项目追加版本号 - **项目标识**:卡片第二行的英文项目名,即 URL 中的目录名 - **行业与页面数**:行业取自 `verify.json`,缺失时按项目名前缀推断 - **大屏角标**:源码或产物中出现 `大屏` / `screen` / `bigscreen` / `visual` 命名的文件即判定为大屏项目 - **门户角标**:`router/index.ts` 里有指向 PortalView / LandingPage 等落页组件的路由即判定为有门户 - **门户入口**:卡片上的绿色「进入门户 →」按钮,跳到该项目门户路由 (门户挂在 `/` 的项目直接打开 base,挂在 `/portal` 的拼 `#/portal`) - **大屏入口**:卡片上的蓝色「进入大屏 →」按钮,跳到该项目的大屏路由 (从 `router/index.ts` 中组件名命中大屏特征的那条路由解析,不固定是 `#/screen`; 如 `airport-ops` 为 `#/panorama`、`energy-monitor` 为 `#/operation`) - 顶部提供关键字搜索(名称 / 中文名 / 行业)、行业分类筛选、「只看门户」「只看大屏」开关 - 行业分类默认**只显示一行**,点右侧「展开全部 ▾」铺开,再点「收起 ▴」折回 --- ## 门户版式 门户**不是同一套模板换文案**。按行业族分 6 种结构完全不同、视觉语言完全不同的版式, 由 `scripts/frontend.mjs` 之外的生成器产出(源码在 `.node-modules-cache/audit-run/`): | 版式 | 结构特征 | 视觉语言 | 覆盖行业 | 项目数 | | --- | --- | --- | --- | --- | | `console` 控制台式 | 左侧竖向指标条 + 中央 270° 环形仪表 + 右侧能力清单 + 底部数据流 | 深色夜蓝、网格、扫描线、青紫渐变 | 能源/电力/水务/环保/制造/矿业/数据中心/充电/森林防火 | 21 | | `journey` 旅程式 | 顶部横向步骤轴(自动推进高亮)+ 节点卡片 + 数据条 | 浅灰底、青绿主色、圆角胶囊按钮 | 物流/冷链/航空/机场/港口/轨交/交通/汽车/农业/食品/医药流通 | 23 | | `grid` 矩阵式 | 超大标题 + 1px 分隔的能力矩阵 + 编号索引 | 纯白、靛蓝、细线分割、无阴影 | 金融/保险/通信/人力/物业/建筑/政务 | 22 | | `editorial` 编辑式 | 超大衬线标题 + 双栏正文 + 首字下沉 + 引言块 | 米色纸感、赭石红、Georgia 衬线 | 教育/法律/文博/传媒/体育 | 13 | | `showcase` 展示式 | 居中大标题 + 交错场景大卡(左右交替)+ 深色数据条 | 纯白、玫红橙渐变、超大圆角 | 零售/餐饮/酒店 | 4 | | `split` 分屏式 | 左侧固定品牌栏(100vh)+ 右侧独立滚动内容区 | 深墨蓝左边栏、青色高亮、情景化列表 | 医疗 | 3 | 另外 **45 个项目是自写门户**,风格各异(如 `retail-pos` 的深色官网首页),不做统一改写。 全仓 **173 个项目,173 个门户**,6 种统一版式 + 自写风格共 7 类以上视觉呈现。 ### 门户数据层 6 种版式共用同一套数据逻辑,换版式不影响取数: - 各项目的 `screenApi.ts` 导出形态并不统一,门户里先做一层**适配**再取数: - `{ request: { get, ensureToken } }` —— 最常见形态,直接用 - 只导出 `fetchScreen()` —— 包成 `get()`,多次调用只请求一次(结果缓存) - 都没有 —— 兜底返回空,页面降级到占位指标而不是白屏 - `ensureToken` 是**可选**的:部分项目的大屏接口公开只读,没有这个方法,不能硬调 - 并发拉 `screenConfig.ts` 里 `apis` 的前 4 个接口;未配置 `apis` 的项目至少拉一次聚合接口 - 标量字段**递归展开**(支持 `{kpi:{batchTotal:44}}` 这类嵌套),深度上限 2 层,跳过数组 - 自动挑选 KPI 时:纯泛化字段(avg / total / sum / count / score)**直接排除**, 带业务名词的(bedTotal / orderCount / farmTotal)优先;再用词表 + 驼峰拆词翻成中文 - 内置 200+ 行业词条(溯源/医疗/物流/制造/能源/金融/教育/酒店/零售等) --- ## 数据大屏 30 个行业族**全部有大屏**,全仓共 **166 个**大屏项目,其中 165 个项目同时具备**门户 + 大屏 + 后台**三件套: | 入口 | 路径 | 免登录 | 定位 | | --- | --- | --- | --- | | 门户 | `/#/portal` | 是 | 对外官网式首页:品牌、主张、能力、实时数据 | | 大屏 | `/#/screen` | 是 | 运营指挥大屏,1920×1080 固定舞台等比缩放 | | 后台 | `/#/` | 否 | 登录后的管理工作台(`admin` / `admin123`) | ### 大屏按行业版式差异化 大屏**不是一个模板换配色**,而是按行业语义选了 6 种不同的主视觉版式,每种有独立的 栅格结构、主图形和容器样式: | 版式 | 主视觉 | 适用行业族 | | --- | --- | --- | | `topology` | 分层网络拓扑,带流动光点动画 | 电力、港口、轨交、充电、机房 | | `grid-map` | 区域网格热力(L1–L4 分级) | 交通、园区、政务、环保、水务、矿山 | | `flow` | 泳道流转,令牌沿工序推进 | 物流、冷链、制造、餐饮、建筑、医药 | | `funnel` | 转化漏斗,逐级收窄 | 招聘、保险、租赁、汽车、金融、电信、零售 | | `timeline` | 时间轴排程,含当前时刻线 | 医疗、酒店、教育、赛事、机场 | | `radial` | 放射关系图,中心到分支 | 媒体、博物馆、法律、农业、林业 | 配色、行业术语(如「站房」「泊位」「候选人」)、面板标题都跟随行业族配置。 ### 数据适配 页面不写死字段名,而是在 `utils/screenConfig.ts` 里声明接口清单,运行时按返回结构识别: - 标量字段 → KPI 卡片(英文键名按词表自动译成中文) - `{date, ...}` 数组 → 趋势折线 - `[{name, value}]` 数组 → 分布条形 / 漏斗 / 热力网格 / 放射节点 - 含实体名与状态字段的对象数组 → 明细列表 这样新增项目只需配 `apis` 和行业文案,版式与解析逻辑由生成器统一生成。 > **安全注意(仅用于演示,勿直接上线)**:大屏与门户把默认口令 `admin` / `admin123` 写在了前端代码里, > 任何人打开 `/#/screen` 都能拿到该租户的完整 token,等于把后台权限公开。 > 生产部署前必须改成独立的只读凭证(单独账号 + 只读角色,或后端提供免鉴权的聚合接口)。 每个项目的 `frontend/src/` 下相关文件: | 文件 | 作用 | | --- | --- | | `views/PortalView.vue` | 官网式门户首页 | | `views/ScreenView.vue` | 按行业版式生成的大屏页 | | `utils/screenConfig.ts` | 标题、行业、接口清单、门户文案、KPI 定义 | | `api/screenApi.ts` | 请求封装(自动登录取 token、401 重登) | - 中间大面板没有构成数据时改用趋势大图,不留空白 --- ## 不入库的内容 `.gitignore` 已排除以下内容,克隆后需自行重新生成: | 内容 | 原因 | 恢复方式 | |---|---|---| | `node_modules/` | 全仓共享一份,体积巨大,可由 lockfile 还原 | 根目录 `npm install` | | `dist/` | 构建产物 | `node scripts/frontend.mjs build` | | `**/*.db` 及 WAL/SHM | 运行时数据,含业务数据 | 首次启动自动重建 | | `bin/platform-api-server*` | Go 二进制 | `go build` | | `shares/gallery/<项目名>/` | 已发布静态站点 | `node scripts/frontend.mjs gallery` | | `state/` `cache/` `.node-modules-cache/` | 运行时状态、缓存与本地脚本 | 自动生成 | | `*.log` `*.bak` | 日志与备份 | — | | `.env*` `.ssh/` `*.pem` `*.key` | 配置、密钥 | 自行配置 | | `*.png` `*.jpg`(除下列例外) | 图片产物 | — | | **例外:`docs/screenshots/*.jpg`** | **README 引用的行业截图,需要入库** | 已在库中 | --- ## 迁移背景 `platform-api/internal/tenants/*/legacy/` 下是历史遗留的独立后端代码, 已从「每项目一套 Gin + JWT + SQLite」合并进统一框架。 合并过程中的系统性问题及修法记录在 [`MIGRATION-legacy.md`](MIGRATION-legacy.md), 框架设计说明见 [`ARCH-platform-api.md`](ARCH-platform-api.md)。 老项目结构约定:`projects/<项目名>/` 下只保留 `frontend/`。 | 项 | 数值 | |---|---| | 曾经有独立 `backend/` 的项目 | 105 | | 仍在 `projects/*/backend/` 下的后端 | **0** | | 独立后端进程数 | **0**(只有 `platform-api` 一个进程) | 各项目通过 URL 前缀 `/api/v1/<项目名>/` 区分租户, 数据分别落在 `platform-api/data/<项目名>.db`,统一账号 `admin` / `admin123`。 **所有项目的登录页都只认这一组账号口令**:历史项目里「演示账号 `ops`/`doctor`/`chen`」、 「口令均为 123456」这类文案已统一改成 `admin` / `admin123`, 后端不为这些虚构账号建号(原因见 `MIGRATION-legacy.md` 第三批第 6 节)。 ### 统一登录响应的兼容字段 历史项目的前端登录逻辑各不相同,框架的 `POST /auth/login` 与 `GET /auth/profile` 在返回时同时给出多个别名,迁移项目无需改前端: | 字段 | 用途 | |---|---| | `token` | JWT,前端放进 `Authorization: Bearer` | | `userInfo` | 新项目约定 | | `user` / `profile` | 老项目分别读 `data.user`、`data.profile` | | `menus` / `permissions` | 老项目写进 `localStorage` 再做 `JSON.parse`;缺失会存成字符串 `"undefined"` 导致白屏 | | `dept` / `department` | 同一含义的两种拼写 | | `roleName` | 角色编码的中文名(`admin` → 系统管理员) | | `lastLogin` / `lastLoginAt` | 最近登录时间 | --- ## 常见问题 **页面白屏 / 接口 404** 检查该项目 `vite.config.ts` 是否为 `base: './'`、路由是否 `createWebHashHistory()`、 `api/index.ts` 的 `BASE` 是否为 `/api/v1/<自己的项目名>`。三者错一个都会白屏。 **登录了但列表全空** 先用 `curl` 确认后端有该租户: ```bash curl -X POST http://127.0.0.1:4500/api/v1/<项目名>/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"admin123"}' ``` 返回 `code:0` 说明租户正常;若列表仍空,多半是种子数据判定逻辑有问题。 **启动后 `已挂载` 的数量少于 `registry.go` 的登记数** 看日志里有没有 `挂载失败已跳过`。常见原因是路由重复注册(Gin panic)或 同一个前缀下 `/:id` 与 `/:mineId` 这类**通配符名冲突**。注意 Gin 还要求静态段 (`/stocks/summary`)注册在其 `/:id` 兄弟路由**之前**。 **构建产物变了但预览站没变** 8090 提供的是 `shares/gallery/`。`build` 之后必须再跑 `node scripts/frontend.mjs gallery`。 **直接读 SQLite 看到的是旧数据** 数据库开了 WAL,用只读方式(`?mode=ro`)打开拿到的是快照。用普通连接读取。 **8090 访问 `/<项目名>/` 返回 404** 预览服务不支持目录式访问,必须走 `/<项目名>/index.html`。 **后端启动报 `bind: ... forbidden by its access permissions`** 目标端口落在 Windows 系统保留端口段内(`netsh interface ipv4 show excludedportrange protocol=tcp` 可查)。 换端口即可:`PORT=4520 ./bin/platform-api-server`,预览站用 `API_TARGET=http://127.0.0.1:4520` 对齐。 **重新采集 README 截图** `.node-modules-cache/shoot.py` 依赖 Playwright。注意两点: ① 该目录下存在 `inspect.py`,会遮蔽标准库,必须用 `python -P` 运行; ② 需先 `pip install playwright` 并 `python -m playwright install chromium`。 --- ## 许可证 本项目采用 [MIT License](LICENSE) 开源。 这是最宽松的常见开源许可之一,你可以自由地: - **商用** —— 用于商业项目、对外交付 - **修改** —— 任意改动源码 - **分发** —— 复制、再发布 - **再许可 / 闭源** —— 可以把代码并入采用其他许可证甚至闭源的项目 唯一义务是:**保留原始版权声明与许可声明**(在副本或实质性部分中附带本 `LICENSE` 文本)。 软件按「原样」提供,不含任何明示或暗示担保。 > 若你更需要「公共领域放弃」式授权(无任何署名义务),可考虑 `Unlicense` 或 `CC0-1.0`; > 但它们不属于 OSI 认可的开源许可,企业法务审核时反而更容易被提问,所以此处选用 MIT。 ### 依赖与第三方资产 本仓库仅对自身的源码与文档(含 `docs/screenshots/` 下的截图)授予上述许可。 通过 npm / Go module 引入的第三方依赖(Vue、Vite、Element Plus、ECharts、Gin、GORM 等) 各自遵循其原有许可证,**不受本 LICENSE 约束**,分发时请一并保留其许可与版权声明。