职教数据驾驶舱生成器
一、这个技能做什么
把一份「区县/地市/省份 × 职教指标」的数据表，生成一个能直接打开演示的 3D 数据大屏：
- 中间主视觉：3D 挤出地图 + 以核心区为枢纽的飞线动画 + 区位光点；
- 左右六面板：区县就业率排行、招生规模趋势、职业技能等级证书（人社部）获取率（仪表盘）、校企合作 TOP8、专业布点大类分布（玫瑰图）、双师队伍能力画像（雷达）；
- 底部八项 KPI：在校生总数、年招生数、专业布点、实训基地、校企合作企业、平均就业率、双师型占比、职业技能等级证获取率（大数自动转「万/亿」不裁切）；
- 三级地图切换：全国 ⇄ 省 ⇄ 市，一键切换，数据面板联动刷新；
- 合规底座（本技能相对通用开源大屏的核心差异）：
1. 全国地图内置南海诸岛与九段线要素（adcode 100000_JD），不会缺南海；
2. 右下角审图号角标（默认占位 GS(2024)0650 号，正式发布须替换为你实际取得的标准地图审图号）；
3. 底栏固定数据来源标注 + 示例数据声明。
二、快速开始（三步出屏）
- 装依赖（首次，可选）：执行
python _fetch_lib.py，把echarts/echarts-gl下载到lib/。
不执行也不影响——引擎engine/dep-loader.js会按 本地 lib/ → jsdelivr → bootcdn → baomitu → cdnjs 依次回退，
一路不通时页面会给明确提示而不是白屏。装完依赖后即完全离线可跑。 - 选层级：打开
index.html，左上角点「配色」可换配色，地图上切换 全国 / 河南省 / 洛阳市（默认洛阳市）。 - 换数据：只改
config.js——把levels.luoyang.regions里的示例数值换成你的真实数据，保存刷新即可，引擎代码零改动。 - 要单文件：运行
python _build_standalone.py，生成dist/职教数据驾驶舱_单文件离线版.html（约 2.4MB），拷到任何电脑双击就能放，内网/政务云/无网教室均可。
> 为什么依赖不随包下发：平台对单个上传文件约 1MB 有硬限制，echarts.min.js 压缩后约 1.03MB 越线，
> 强行随包会让发布接口直接返回 550 / 断连。故采用「引擎 + 地图 + 数据全随包（离线主体），图表库按需获取」。
> 也就是说：本技能在无网环境的正确姿势是先跑一次 _fetch_lib.py。
三、目录结构
voc-datav-cockpit/
├── index.html # 入口（引用 dep-loader + 本地数据，无外网也能跑）
├── config.js # ★ 唯一需要改的文件：标题/主题/配色/三级数据
├── engine/cockpit.css # 样式与配色变量（11 套主题由 config.js 注入）
├── engine/cockpit.js # 引擎：面板图表 + 3D/2D 地图 + 切换 + 缩放 + 配色抽屉
├── engine/dep-loader.js # 依赖加载：本地 lib/ 优先 → 公共 CDN 兜底
├── lib/ # 图表库（约 1.7MB，_fetch_lib.py 生成，不随包下发）
├── geo/geo-pack.js # 三级地图 GeoJSON 打包（window.COCKPIT_GEO）
├── _fetch_lib.py # 一键补齐 echarts / echarts-gl 到 lib/
├── _build_geo.py # 换地图/加层级时重新打包 geo-pack.js
├── _build_standalone.py # 打包单文件离线版（会把 lib/ 一起内联）
└── _verify_cockpit.py # 准确性 + 配色科研依据体检（55 项）
四、数据字段说明（config.js → levels.*.regions[]）
| 字段 | 含义 | 单位 | 用途 |
|---|---|---|---|
| name | 区域名 | — | 必须与地图 GeoJSON 的 properties.name 逐字一致 |
| enroll | 年招生数 | 人 | KPI、招生趋势 |
| students | 在校生数 | 人 | 地图着色主指标、KPI |
| employment | 毕业生就业率 | % | 就业率排行、KPI |
| majors | 专业布点数 | 个 | KPI |
| bases | 实训基地数 | 个 | KPI |
| dual | 双师型教师占比 | % | 双师画像、KPI |
| coop | 校企合作企业数 | 家 | 校企合作 TOP8、KPI、飞线密度 |
| cert | 职业技能等级证书（人社部）获取率 | % | 仪表盘、KPI（层级级配置） |
证书口径（全包统一，勿再出现其他证书制度提法）
- 口径名称：职业技能等级证书（全称「人社部职业技能等级证书」，本包一律简称「职业技能等级证」）。
- 政策依据：职业技能等级证书自 2025 年起由人力资源和社会保障部归口管理（人社厅函〔2025〕154 号）。
- 覆盖范围：模块名、图表标题、面板标题、KPI 指标名、数据字段说明、统计口径标注六处均按上表口径表述；
config.js → meta.certNote会在大屏底栏自动渲染该口径，换项目时改这一处即可全屏生效。 - 禁止项：不要在新项目里再引入历史遗留的其他证书制度（已并入本口径的原试点证书体系）作为独立指标或独立栏目。
已填示例：本包 config.js 即「洛阳市 14 区县 + 河南省 18 地市 + 全国 34 省级区」的完整已填模板，替换数字即可复用。
五、换地图 / 加层级（如换成你的城市）
- 到阿里云 DataV.GeoAtlas 取 GeoJSON：
https://geo.datav.aliyun.com/areas_v3/bound/<adcode>_full.json（市级 6 位码，如洛阳 410300；含下级区县用_full）。 - 下载后放入
geo/，在_build_geo.py的MAPS里加一行"xxx": "<文件名>.json"，运行它重新生成geo-pack.js。 - 在
config.js的levels里照抄一个层级块：改mapKey、mapName、hub（飞线枢纽区）、regions数据；并把层级 key 加进meta.levels与meta.levelLabels。 - 兜底：区县级 GeoJSON 若 404，改用该市
_full图（区县作色）；县级数据缺失时该区域显示底色，不影响其余区域。
六、配色方案（11 项 · 均附研究依据）
配色是可选项而非口径，与数据层完全解耦：改配色不影响任何指标定义。每套方案在 config.js → window.COCKPIT_THEMES 里就是一个对象，含 css（大屏 CSS 变量）与 pal（ECharts 调色板）两组色值，外加 ev / basis / source / scene / pre / diff 六项依据字段；引擎在启动时把这些色值注入为 html.theme-<id> 的 CSS 变量，点卡片即整屏换色，不需要改 CSS、也不需要刷新。
证据等级约定（写进每套方案的 ev 字段，界面上以徽章显示）：
- A = 同行评议文献或国际标准，可直接引用；
- B = 国家标准 / 强制规范；
- C = 工程经验与行业共识，没有单一对照试验支撑（界面与报告都会显式标注，不冒充文献）。
| ev | 配色 id | 方案名 | 研究来源 / 科学依据 | 适用场景 | 前提条件 | 与其余方案的差异 |
|---|---|---|---|---|---|---|
| A | gov-blue |
政务科技蓝 | W3C WCAG 2.2（2023-10 W3C Rec.）SC 1.4.3 / 1.4.11；sRGB IEC 61966-2-1。暗蓝底 + 青蓝主色，主色对白字 > 7:1（AAA），色相集中 200–220° | 政务/教育行政汇报、常设展厅、校级季度会（默认） | 中等以上照度；投影/LED 需实机验收色偏；不适合夜班值守 | 最通用、风险最低；代价是同质化严重、识别个性弱 |
| B | party-red |
党建红旗红 | GB 2893-2008《安全色》，红色为最高显著性警示色；红色处长波端，视锐度最高 | 党建活动、主题党日、思政成果展 | 大面积高饱和红会疲劳+后像，须压暗底降饱和（主色已降为 #ff6b57）；不宜 24h 常亮 | 政治语义最明确；但红色在同一国标里也是"危险/告警"义，混用削弱告警可信度 |
| C | police-dark |
公安黑金（低照值守） | WCAG 2.2 SC 1.4.11 暗底高亮达标设计；sRGB 基准。★视疲劳改善为工程经验（C 级） | 指挥中心、夜间值班、监控分屏、实训基地值守 | 环境照度宜 < 100 lx，明亮展厅会反光，需降亮度档 | 比政务蓝更能压住多屏噪声；代价是金+青蓝双主色，纪律更严 |
| A | park-green |
园区生态绿 | Harrower & Brewer (2003) ColorBrewer, IEEE TVCG 9(3)；绿系处于 deutan/protan 最不敏感色区 | 产业园区、生态/低碳、实训基地能耗、现代农业 | 只适合连续量着色；类别型多序列会区分不足 | 语义贴合度最高；不适合告警/风险位（绿色在 GB 2893 恒为"安全/通行"） |
| A | cvd-safe |
色觉障碍友好（Okabe–Ito） | Okabe & Ito (2008) Color Universal Design；Machado et al. (2009) IEEE TVCG 15(3):474–486 CVD 生理仿真模型 | 无障碍要求场景、公开对外大屏、教室/随班就读 | 上线前须用 Machado 模型做 deutan/protan/tritan 三模拟验收；分类色 ≤ 7 | 以"科技感"换可达性；它管分类色，与 ColorBrewer 顺序色阶分工不同 |
| A | cb-sequential |
ColorBrewer 顺序色阶 | 同上文献，本项专用于连续量：保证「数值→颜色」单调映射，色盲下仍保序 | 地图分层设色（在校生数、专业点密度）、热力面板 | 只适合有自然顺序的连续量；类别型会造"假等级感" | 可与 park-green 叠加：一个定业务语义，一个定数值梯度 |
| B | gb-safety |
安全色国标（GB 2893） | GB 2893-2008《安全色》+ GB 2894-2008；红=禁止/危险、黄=警告、蓝=指令、绿=安全/通行 | 实训车间、实习工厂安全生产看板、设备/危化品状态、风险分级 | 状态色只能四取一，不得加第 5 色；必须同配文字/符号标签（约 8% 男性 CVD） | 唯一"带强制规范"的方案；视觉弹性最小，红色与党建红语义会打架 |
| C | night-lowblue |
夜间低蓝光（哑光） | sRGB IEC 61966-2-1 + WCAG 2.2 对比度约束。★降眩光为工程经验（C 级） | 晚自习后/宿舍区、夜间值班室、低照度值守 | 必须另配亮度档（≤ 30%）；高对比+低照度会残像 | 比 police-dark 更哑光；它优先降亮度总量而非改色相 |
| A | hi-contrast |
高对比无障碍（浅底） | WCAG 2.2 SC 1.4.3 / 1.4.11；APCA（2021–2023，用于 WCAG 3 草案的感知对比模型）。浅底深字 > 7:1 达 AAA | 教室投影、老旧/低亮度 LED、强光直射、视障与老花受众 | 必须实机投影验收（屏达 AAA ≠ 投影达 AAA，灰阶与伽马会压对比）；浅底易显灰尘划痕 | 与全部暗色方案的根本差异是"明底暗墨"；桌面 > 300 lx 时显著优于暗底 |
| A | warm-classroom |
教学暖色（浅底暖调） | Tufte (1983) 数据墨水比；Sweller (1988) Cognitive Load Theory；Miller (1956) 7±2 短时记忆容量 | 课堂教学、公开课、学生正前方大屏、录播课 | 需防眩（磨砂）屏或拉窗帘，否则直射光下浅底反光 | 11 项中最适合学生正面观看；代价是失去科技感/未来感 |
| A | tufte-minimal |
数据墨水极简（Tufte） | Tufte (1983) The Visual Display of Quantitative Information——数据墨水比、去冗余装饰 | 教研汇报、课题结题与论文配图、板书式展板、要截图进 PPT 的场合 | 放弃科技感与动效（飞线/扫光建议关或降到最低）；不适合监控常亮屏 | 最"学术"；同为浅底，warm 偏教学亲和、tufte 偏数据严谨 |
怎么用：
- 默认
config.js → meta.theme = "gov-blue"，换默认就改这一个值； - 演示时点左上「配色」chip 打开右侧抽屉，11 张卡片每张都印着科学依据 + 研究来源 + 适用场景 + 前提条件 + 差异，点一下整屏即时换色（含 3D 地图、飞线、六面板、八 KPI）；
- 加一套自己的配色 = 往
COCKPIT_THEMES里加一个对象（照抄上面任一条目改色值即可，ev必须诚实填 A/B/C）； python _verify_cockpit.py会校验每套配色的色值合法性、调色板完整性，以及是否都还带着可追溯的研究来源——缺依据会被报黄/红，防止改配置时留下"来历不明的配色"。
七、错误码与自检（E0–E4）
| 码 | 触发条件 | 用户可见提示 | 修正动作 | 降级逻辑 |
|---|---|---|---|---|
| E0 | lib/ 下 echarts 或 echarts-gl 缺失、被改名 | 页面空白，控制台 Failed to load resource 指向 lib/*.js |
重新解压完整技能包，保持 index.html 与 lib/ 同级 | 无（依赖缺失不渲染） |
| E1 | geo-pack.js 缺失或未含目标 mapKey | 控制台 缺少 config.js 或 geo-pack.js 或地图区空白但面板正常 |
运行 _build_geo.py 重新打包；确认 config 的 mapKey 与 geo-pack 的 key 一致 |
面板照常渲染，仅地图缺失 |
| E2 | 浏览器不支持/禁用 WebGL | 引擎自动切换并正常显示 2D 平面地图+飞线 | 需 3D 时换 Chrome/Edge 最新版，或在设置里开启硬件加速 | 自动降级 2D，功能不缺失 |
| E3 | config.regions[].name 与 GeoJSON name 不一致（如「瀍河区」≠「瀍河回族区」） | 该区域不着色、飞线缺一条、排行少一行 | 打开 geo/ 源 JSON 对照 properties.name 逐字改名；或用 _build_geo.py 重新打包 | 其余区域正常显示 |
| E4 | regions 缺字段或写错字段名 | 对应 KPI 显示 -、对应面板为空 |
按「数据字段说明」表补齐字段名（区分大小写） | 缺失项显示占位，不崩溃 |
八、准确性保证（地图 + 数据，双轨自检）
8.1 地图准确性（几何层）
| 关口 | 校验规则 | 不通过的后果 |
|---|---|---|
| 数据源可信 | 边界取自阿里云 DataV.GeoAtlas（民政部区划代码），坐标系为 WGS84 | — |
| 要素完整 | 全国 ≥34 要素且含 adcode=100000_JD（九段线 + 南海诸岛）；河南 ≥17；市/县 ≥13 |
缺九段线 = 问题地图，政务项目会被通报 |
| 定位字段 | 每个行政区要素带 center（飞线起终点、标签锚点） |
缺 center 则该区无法飞线、标签错位 |
| 坐标合法 | 经度 0~180、纬度 0~60（中国全境） | 越界说明 GeoJSON 串层或张冠李戴错省 |
| 区划时效 | 每年复核一次行政区划调整（撤县设区/地市合并），geo-pack.js 记录版本与获取日期 | 用旧图会把已撤销区划当现状 |
红线：交互式 Web 地图与静态成果图（PPT/展板/截图）审核口径不同，政务、国企、公开发布前必须到自然资源部标准地图服务换取真实审图号并替换 meta.mapApproval；本包内置号为占位。若将来叠加高德/百度底图，必须统一为 GCJ-02，否则偏移 300~500 米（当前 ECharts 自绘无底图，无此问题）。
8.2 数据准确性（口径层）
四道关缺一不可：
- 来源关——只认三档：① 权威（教育部全国教育事业发展统计公报、省/市教育事业统计与统计年鉴）；② 一手（学校上报的教育管理信息系统、年度报表）；③ 佐证（行业/招聘平台，不得进 KPI）。示例数据只能用于内部演示。
- 口径关——每组指标写死分子分母与统计范围，最容易翻车的三组：
- 在校生：全日制 vs 含非全日制；中职 vs 高职/职业本科不得混加；
- 就业率：初次就业率 vs 年终就业率，升学不计就业，混算会虚高到 98%+；
- 双师型：教育部口径（教师资格 + 职业技能等级/行业经历）vs 学校自定，可差 10~30 个百分点。
- 职业技能等级证书：2025 年起由人社部归口（人社厅函〔2025〕154 号）；归并 2025 年前存量证书须注明，否则同比断裂。 - 校验关——
python _verify_cockpit.py自动跑（见 8.3）。 - 溯源关——每个指标挂「口径卡」：
指标名 / 定义 / 分子分母 / 来源文件 / 数据截止日 / 更新人；底栏meta.dataNote上的示例声明在换真实数据前不得删除。
8.3 一键体检（已内置）
python _verify_cockpit.py # 体检并生成 _verify_report.md
python _verify_cockpit.py --out=x.md # 指定报告路径
只读不改数据，覆盖 3 类共 40 项：
- 地图（M1–M5）：要素数、九段线要素、center 齐全、经纬度合法、名称唯一；
- 数据（D1–D9）：非空 / 类型 / 缺失 / 重名 / 百分比区间 / 就业率极值 / 数据区名与地图要素名交叉核对（错位直接暴露） / 上下级汇总一致（市合计 = 省对应市）/ 证书口径统一；
- 合规（C1–C4）：审图号非占位、数据来源标注、示例数据声明、证书口径说明。
输出红/黄/绿三态，红线项（红）为上线阻断项，黄项为人工确认项（如占位审图号在 DEMO 态属正常）。
九、高频问题（反模式 · 正确做法）
Q1：双击 index.html 打开是空白/只有外框？
反模式：用旧版浏览器或开启了严格本地文件策略的浏览器直接开，然后反复刷新。
正确做法：优先用 Chrome/Edge 直接双击（本包已全本地化，file:// 可跑）；若仍空白，按 F12 看控制台是否 E0/E1；或起本地服务 python -m http.server 后访问。
兜底：直接用 dist/ 里的单文件离线版，它不依赖目录结构。
Q2：能换成我们市/县吗？能接真实业务数据吗？
反模式：直接手改 geo-pack.js（80 万行压缩 JSON，手改必坏）。
正确做法：走「五、换地图/加层级」三步；真实数据只改 config.js。本引擎是纯前端静态渲染，不做数据接口。
兜底：需要 REST/数据库实时的版本，属于二次开发需求，在数据源头做好 JSON 后仍走 config.js 注入。
Q3：大屏数据可以直接对外发布吗？
反模式：拿示例数据截图宣称「我市官方职教数据」，或带占位审图号正式上线。
正确做法：正式使用前①替换 config.js 为教育行政部门核准数据；②到自然资源部标准地图服务换取并标注真实审图号；③保留底栏数据来源标注。
兜底：内部教学/路演演示可直接用示例数据，但角标声明不得删除。
十、边界纪律
- 本技能产出为演示与汇报工具，不替代官方统计年报、事业统计平台与年检诊改系统；
- 地图边界以自然资源部标准地图为准；本包内置审图号为占位示例，正式发布必须替换并自查国界、九段线、藏南等要素完整；
- 内置三级数据均为演示示例数据，非官方统计口径，因数据使用产生的对外发布责任在使用方；
- 不采集、不上传任何数据：全部渲染在本地浏览器完成，适合内网环境。
changelog
1.0.0（2026-10-01）
- 首版：三级地图（全国 34 省级区 / 河南 18 地市 / 洛阳 14 区县）3D 驾驶舱引擎；
- 六面板 + 八 KPI + 飞线 + 四主题 + 审图号合规角标 + 示例数据声明；
- WebGL 自动降级 2D；单文件离线打包脚本；E0–E4 自检表。
