机房控制台

---
name: control-room
description: 用一个离线 HTML 文件做出一套可信、真能操作的产品后台，风格是老式模拟机房：琥珀色读数、SVG 指针仪表、拨动开关。内置命令面板、能重算指标和图表的日期范围、可排序可筛选的表格、可撤销的批量操作、详情抽屉和拖放看板。需要为演示、路演、需求文档或原型做管理后台、运营控制台、仪表盘时使用，或者对方点名要这个风格时使用。
version: 1.0.0
---

# 机房控制台

外观和全部功能都在 `assets/template.html` 里。你要做的只是写一个 JSON 文件。不要改样式和引擎，`scripts/check.mjs` 会检查这一点。

精确的色值和字体见 `references/style.md`。所有数据字段和长度限制见 `references/data.md`，写数据前先读它。

下面命令里的 `$SKILL` 指本文件所在的文件夹。请在你自己的项目文件夹里运行，`data.json`、输出文件和 `shots/` 都放在那里，不要写进技能文件夹。

## 需要问清楚的信息

简报里没有的，一次问完，放在同一条消息里。

必需：
1. 产品或机构的名称，以及这个控制台管什么。
2. 最多四个核心数字、单位，以及它们随时间怎么累计：求和、平均，还是取最新值。
3. 被管理的主要对象，比如会员、订单、站点，以及它的列和状态。
4. 看板的流程阶段。
5. 用真实数据还是示例数据。如果是真实数据：要文件，也要来源。

可选：
6. 每日历史数据、目标和告警线。
7. 电平表用的拆分维度，比如按地区的产量。
8. 语言：中文或英文。一个版本只用一种语言。

## 步骤

1. 按 `references/data.md` 写 `data.json`，如实填写 `meta.dataStatus`。中文版把 `meta.lang` 和 `meta.locale` 都设为 `zh-CN`。
2. 生成：`node $SKILL/scripts/set-data.mjs $SKILL/assets/template.html data.json console.html`。界面文字会自动从 `assets/ui.zh.json` 补上。
3. 检查：`node $SKILL/scripts/check.mjs console.html`。按提示修改，重跑到通过为止。
4. 实测：`node $SKILL/scripts/drive.mjs console.html shots/`。它在桌面、减弱动效和 375 宽度触屏下运行，覆盖：预设范围、自选和颠倒的日期、指标与自算结果对比、电平表文字、开关、命令面板、排序、文字和状态筛选、只看需处理、批量操作、三种撤销、抽屉编辑、示例标签、鼠标和触屏拖动、箭头按钮、换挡键加方向键、联动指标、日志、说明和导出。数据无法覆盖的项目会打印 SKIP。真机、Safari、Firefox 和读屏软件不在其中，交付时要说明。
5. 打开并逐张查看截图：总览（默认范围）、表格、记录抽屉、卡片抽屉、看板和日志。手机截图中带 `-full` 的长图有意隐藏了固定底栏和提示条，其余截图显示它们的实际位置。留意读数被截断、名牌折行、指针顶到一头、图表空白、数量单位不对。脚本判断不了含义，数字要亲自读。改数据或缩短文字，不要动样式。
6. 交付这一个 HTML 文件，并附上“交付物”里的说明。

耗时：大部分时间花在写数据上。生成和检查不到一秒，实测约三十秒。

只有第 4 步需要 Playwright：先运行 `npm install playwright`，再运行 `npx playwright install chromium`。如果它装在别处，把 `NODE_PATH` 指向那个 `node_modules` 文件夹。交付的控制台本身不用安装任何东西。

## 内容槽

真正要填的只有一处：标记为 `data-slot="console-data"` 的 JSON 块。屏幕上所有文字都来自它。`set-data.mjs` 还会同步写入 `<title>`、`lang` 属性和 `<noscript>` 文字。名牌、副标题和数据标签带有 `data-slot` 属性，内容从数据块读取，长度限制写在模板和 `references/data.md` 里。

## 容易填错的字段

完整定义见 `references/data.md`。

- `meters.unit` 是被加总的数量单位，比如 `千瓦时`。绝不能写 `%`，占比由页面自己加。
- `metrics[].live` 把指标和看板或表格联动。凡是数卡片或行数的指标都要用它，同时设 `agg:"last"`，序列最后一个值要等于当前数量。撤销时指标会恢复。
- `board.columns[].done` 标记已完成的列。这些列不显示逾期，也不计入 `live`。都没设时，最后一列算已完成。
- `agg:"last"` 的指标，只要范围结束于最后一天，数值就不变，只有旁边的变化量会动。这是正常的。
- `perDay` 用于范围内的总量。仪表上限会取整到好看的数字，所以指针位置要在屏幕上确认。想显示日均值，用 `avg`，单位写成 `/天` 之类。
- `dataStatus`：机构本身是编的用 `fictional`，只有数字是占位用 `sample`，真实数字用 `real` 并填 `dataSource`。
- 状态列的键必须是 `status`。`details` 的类型是 `text` 或 `num`。`mobile:false` 在手机宽度下把该列收进抽屉。

## 必须真能用的功能

- 按 Ctrl K 或 Cmd K 打开命令面板：跳转、改日期范围、筛选、打开任意记录或卡片、撤销、导出。
- 日期范围能重算仪表、电平表和记录仪，包括自选日期和上一周期对比。
- 表格能排序，能按文字和状态筛选，还有“只看需处理”开关。
- 批量选择后能改状态或归档，提示条、撤销按钮和 Ctrl 或 Cmd Z 都能撤销。
- 详情抽屉能改状态、开关和备注，焦点不会跑出抽屉，示例标签始终可见。
- 看板支持鼠标拖动、触屏按住把手拖动、箭头按钮，以及换挡键加方向键。

## 情况不理想时怎么办

- **简报信息太少。** 先用自己的话复述对方给的事实。绝不编造客户、收入、人物或资质并当成真的。缺的部分用明确标注的示例数据补上，把 `dataStatus` 设为 `sample`（机构本身是编的就用 `fictional`），并列出每一条推断内容请对方确认。
- **没人能回答问题。** 直接做。按上面的规则用 `sample` 或 `fictional`，在交付说明开头列出所有假设。
- **对方想要更多或更少。** 行数、卡片、指标和列都能在 `references/data.md` 的限制内增减。仪表少于四个没问题。超过四个时，其余的设 `gauge:false` 放到记录仪。想加新页面时，说明模板固定四个视图，提供最接近的方案，不要硬加。
- **没有真实链接。** 控制台离线运行，按设计不放外部链接。需要时把地址以纯文字写进备注，并告诉对方。
- **数据是真的。** 把 `dataStatus` 设为 `real` 并填写 `dataSource`。这样示例标签会消失，所以要先确认。
- **对方想保留改动。** 改动只保留到刷新页面为止。用导出命令下载当前数据，再用 `set-data.mjs` 写回。

## 交付物

- 一个独立的 `.html` 文件。
- 一段简短说明：哪些是真实的，哪些是示例，每条推断内容，以及没有测试到的部分。

## 交付前检查

- [ ] 最终文件通过 `check.mjs`。
- [ ] 通过 `drive.mjs`，打印出的每个 SKIP 都在交付说明里解释了。
- [ ] 保存的每个视图，包括抽屉和日志，都在桌面宽度和 375 宽度下看过。
- [ ] 示例或虚构数据在每个视图和两种抽屉里都有标注，`dataStatus` 设置正确。
- [ ] 凡是数卡片或行数的指标都用了 `live`，电平表数量的单位正确。
- [ ] 没有把编造的数字或人物当成真实内容。
- [ ] 通篇只有一种语言，单位和状态名也一样。
- [ ] 仪表刻度适合数据：默认范围下指针不顶在两端。
- [ ] 默认范围之前有足够的历史数据，对比才有意义。

## 不适用的情况

- 正式上线的管理后台：它没有登录、服务器、数据库，也不保存状态。
- 公开的营销页面，或者要阅读、打印的报告。
- 品牌必须用自己的外观时：这个风格是锁定的。
- 不宜外传的数据：所有内容都以明文存放在这一个文件里。

## 运行要求

现代浏览器即可，不需要网络、服务器或构建步骤。脚本需要 Node 18 或以上。只有 `drive.mjs` 需要 Playwright。