next-tjwater-drainage-frontend/ACRYLIC_DESIGN_INVENTORY.md

# 亚克力设计类别与组件使用清单

本文档记录当前前端的亚克力材质体系及实际使用位置。样式定义以 `src/styles.css` 为准，组件映射以 `src/features/` 下的现有代码为准。

## 总览

当前材质体系分为 3 组，共 13 个语义类：

| 分组 | 数量 | 类别 | 是否使用背景模糊 |
|---|---:|---|---|
| 外层亚克力与临时玻璃 | 4 | 导航、面板、独立控件、临时任务浮层 | 是 |
| 内部实体表面 | 4 | Dock、控件面、内容凹槽、阅读面 | 否 |
| 语义状态表面 | 5 | 信息、正常、警告、危险、Agent 推理 | 否 |

只有第一组属于真正的亚克力或玻璃外壳。第二组用于亚克力壳层内部，保证文字、表单和密集数据不受底图干扰。第三组只表达业务状态，不承担界面层级。

## 1. 外层亚克力与临时玻璃

这组样式包含冷色半透明底色、饱和度、明度混合、细噪点、边框和阴影，并使用 `backdrop-filter`。同一区域只应保留一个带模糊的外层壳体，内部子元素应改用实体表面。

### `acrylic-navigation`

- 用途：全局导航栏。
- 模糊：使用面板级模糊，默认 22px，浅色底图 24px，卫星底图 20px。
- 特征：保留底部分隔和下投影，不使用顶部高光。
- 当前组件：
  - `WorkbenchTopBar`，工作台顶部 Header。
- 文件：`src/features/workbench/components/workbench-top-bar.tsx`。

### `acrylic-panel`

- 用途：承载持续显示或需要集中阅读的主要浮动面板。
- 模糊：使用面板级模糊，20px 至 24px。
- 当前组件：
  - `AgentCommandPanel`，Agent 命令面板外壳。
  - `AgentCollapsedRail`，Agent 收起状态侧栏。
  - `ScheduledConditionFeed`，预约任务与工况面板，通过 `MAP_TOOL_PANEL_SURFACE_CLASS_NAME` 间接使用。
  - `LayerControl`、`ControlPanel`、`Legend`、`BaseLayersControl`，地图工具面板，通过共享材质常量间接使用。
  - `FeaturePopover`，要素详情浮层，通过 `MAP_FOCUS_SURFACE_CLASS_NAME` 间接使用。
  - `FeatureInsightPanel`，要素洞察面板。
  - `MapDevPanel`，地图开发调试面板。
  - `AlertMenu`、`ScenarioMenu`、`UserMenu`，顶部导航下拉菜单。
  - `MapNotice`，地图通知。
- 直接或间接涉及文件：
  - `src/features/agent/components/agent-command-panel.tsx`
  - `src/features/agent/components/agent-collapsed-rail.tsx`
  - `src/features/map/core/components/map-control-styles.ts`
  - `src/features/map/core/components/notice.tsx`
  - `src/features/workbench/components/scheduled-condition-feed.tsx`
  - `src/features/workbench/components/feature-popover.tsx`
  - `src/features/workbench/components/feature-insight-panel.tsx`
  - `src/features/workbench/components/map-dev-panel.tsx`
  - `src/features/workbench/components/workbench-top-bar-menus.tsx`

### `acrylic-control`

- 用途：始终悬浮在地图上的紧凑型独立控件。
- 模糊：使用控件级模糊，默认 18px，浅色底图 20px，卫星底图 16px。
- 当前组件：
  - `Toolbar`，地图主工具栏。
  - `DrawToolbar`，绘制工具栏。
  - `ZoomControl`，缩放控件。
  - `ScaleLine`，比例尺。
  - `BaseLayersControl`，底图切换入口与预览控件。
  - `map-workbench-page.tsx` 中的浮动地图控制入口。
- 使用方式：上述组件主要通过 `MAP_CONTROL_SURFACE_CLASS_NAME` 间接引用。
- 共享定义：`src/features/map/core/components/map-control-styles.ts`。

### `glass-transient`

- 用途：短时出现、需要突出当前任务状态的玻璃浮层。
- 模糊：沿用控件级模糊，16px 至 20px。
- 当前组件：
  - `AgentTaskTicker` 的活动任务卡片。
- 文件：`src/features/workbench/components/agent-task-ticker.tsx`。
- 约束：仅用于活动任务浮条，非活动堆叠卡改用 `surface-control`。

## 2. 内部实体表面

这组样式不使用 `backdrop-filter`。它们用于亚克力外壳内部，通过不透明度和背景层级提高可读性，避免出现嵌套模糊。

### `surface-dock`

- 用途：预留给固定 Dock 或侧边停靠区域。
- 当前状态：已在 `src/styles.css` 中定义，暂无组件直接使用。
- 适用组件：
  - 桌面端固定展开的 Agent 侧栏，前提是它从地图浮层改为占据稳定布局宽度的 Dock。
  - 固定展开的预约工况详情侧栏或图层管理侧栏，前提是侧栏长期贴边并参与工作区布局。
  - 后续可能增加的对象目录、调度队列等常驻侧栏。
- 不适用：临时弹层、悬浮工具面板、下拉菜单和可覆盖地图的短时侧栏。这些组件仍应使用 `acrylic-panel`。

### `surface-control`

- 用途：面板内部的 Header、输入区域、筛选器、按钮、紧凑控制区和任务堆叠卡。
- 当前组件范围：
  - Agent 收起侧栏条目、Agent 操作摘要按钮、命令面板快捷入口。
  - 图层、量测和通用控制面板中的交互控件。
  - 预约任务面板与工况详情中的筛选器、元信息块和次级操作。
  - 任务浮条的非活动卡片。
  - 要素洞察面板的内部按钮。
  - Header 下拉菜单的内部控制区。
  - 通用 `IconButton`。
- 主要文件：
  - `src/features/agent/components/agent-collapsed-rail.tsx`
  - `src/features/agent/components/agent-command-panel.tsx`
  - `src/features/agent/components/agent-operational-brief.tsx`
  - `src/features/map/core/components/control-panel.tsx`
  - `src/features/map/core/components/layer-control.tsx`
  - `src/features/map/core/components/measure-panel.tsx`
  - `src/features/workbench/components/agent-task-ticker.tsx`
  - `src/features/workbench/components/scheduled-condition-feed.tsx`
  - `src/features/workbench/components/scheduled-condition-detail-panel.tsx`
  - `src/features/workbench/components/feature-insight-panel.tsx`
  - `src/features/workbench/components/workbench-top-bar-menus.tsx`

### `surface-well`

- 用途：低密度内容区、空白支撑区、未选中的面板条目和内部凹槽。
- 当前组件：
  - `LayerPanel`、`LayerControl` 的未激活条目。
  - `MeasurePanel`、`DrawToolbar`、`AnnotationPanel` 的内部区域。
  - `ControlPanel`、`Legend`、`BaseLayersControl` 的分组与空白区域。
  - Header 下拉菜单的普通菜单项。
- 使用方式：部分组件直接引用，部分通过 `MAP_READABLE_SURFACE_CLASS_NAME` 间接引用。

### `surface-reading`

- 用途：消息、报告、表单、属性列表、时间线内容和其他密集阅读区域。
- 当前组件范围：
  - Agent 消息详情、操作摘要、UI Envelope 内容和命令面板空状态。
  - 预约任务列表、工况详情、KPI、报告内容与下拉列表。
  - 要素洞察、属性列表和底图名称标签。
  - Header 下拉菜单中的详情块与空状态。
- 主要文件：
  - `src/features/agent/components/agent-command-panel.tsx`
  - `src/features/agent/components/agent-message-details.tsx`
  - `src/features/agent/components/agent-operational-brief.tsx`
  - `src/features/agent/components/agent-ui-envelope-renderer.tsx`
  - `src/features/workbench/components/scheduled-condition-feed.tsx`
  - `src/features/workbench/components/scheduled-condition-detail-panel.tsx`
  - `src/features/workbench/components/feature-insight-panel.tsx`
  - `src/features/workbench/components/feature-property-list.tsx`
  - `src/features/workbench/components/workbench-top-bar-menus.tsx`
  - `src/features/map/core/components/base-layers-control.tsx`

## 3. 语义状态表面

语义状态表面不使用模糊，只表达业务含义。它们不能替代 `acrylic-panel`、`surface-control` 或 `surface-reading` 来建立界面层级。

| 类名 | 含义 | 当前使用位置 |
|---|---|---|
| `material-tone-info` | 信息、液位等蓝色状态 | `FeatureInsightPanel` 的雷达液位区块 |
| `material-tone-normal` | 正常、健康、流量或水质状态 | `FeatureInsightPanel` 的水质、综合监测等区块 |
| `material-tone-warning` | 风险、告警、超声流量等橙色状态 | `FeatureInsightPanel` 的告警与超声流量区块 |
| `material-tone-danger` | 严重故障或事故状态 | 已定义，建议用于严重事故、关键设备故障和高风险工况内容块 |
| `material-tone-agent` | Agent 推理或模型建议 | 已定义，建议用于 Agent 解释、推理结论和建议动作内容块 |

## 未使用样式的建议落点

### `surface-dock`

建议用于参与页面布局的常驻停靠区，而不是覆盖在地图上的浮层。现有组件中，以下场景适合在布局调整后使用：

- `AgentCommandPanel` 的桌面常驻模式。只有当面板固定贴左、占据稳定宽度并推动地图安全区时才使用。
- `ScheduledConditionFeed` 或 `ConditionDetailPanel` 的常驻右侧模式。适用于调度员持续对照地图与工况详情的工作流。
- `LayerPanel` 的常驻图层目录模式。适用于图层较多、需要持续管理的专业工作台。

如果组件仍然悬浮在地图上、可以随时关闭或与其他浮层替换，应继续使用 `acrylic-panel`。

### `material-tone-danger`

建议用于已经确认的严重业务状态，不用于普通校验失败或短暂接口错误。现有组件中适合的落点包括：

- `FeatureInsightPanel`：要素状态为 `critical`、严重故障、爆管或关键设备失效时的状态说明区块。
- `ScheduledConditionDetailPanel`：工况风险等级为 `critical`，或任务状态为 `error` 且代表真实运行事故时的风险摘要和影响范围区块。
- `MapNotice`：仅在需要持续强调严重运行事故时用于通知内容区，不替换通知最外层的 `acrylic-panel`。
- Agent 权限或确认卡片：仅当待执行动作具有明确的高风险业务后果时使用，不能仅因提交失败就使用。

不应使用在网络请求失败、加载失败、表单校验错误等通用技术错误上。这类错误继续使用局部红色图标、边框或文字即可，避免把技术故障误读为管网事故。

### `material-tone-agent`

建议用于明确由 Agent 或模型生成的内容，帮助用户区分事实数据、业务状态与机器推理。现有组件中适合的落点包括：

- `FeatureInsightPanel` 的“Agent 解释”区块。该区块目前使用 `material-tone-warning`，如果内容只是解释或推理而非风险告警，更适合改用 `material-tone-agent`。
- `AgentOperationalBrief`：Agent 生成的任务判断、建议动作或需要人工确认的结论区块。
- `AgentMessageDetails`：推理摘要、模型结论、建议方案等非原始证据内容。
- `AgentUiEnvelopeRenderer`：由 Agent 返回的建议面板或注册组件中的结论区块。
- `ScheduledConditionDetailPanel`：Agent 针对工况生成的处置建议区块。

原始监测值、设备属性、人工录入内容和系统事实不应使用该样式。即使这些内容出现在 Agent 面板内，也应继续使用 `surface-reading` 或对应的业务状态色。

## 共享类映射

地图核心组件通过 `src/features/map/core/components/map-control-styles.ts` 复用材质类，避免在各组件中重复写样式值。

| 共享常量 | 实际材质类 | 典型用途 |
|---|---|---|
| `MAP_CONTROL_SURFACE_CLASS_NAME` | `acrylic-control border` | 工具栏、缩放、比例尺、底图入口 |
| `MAP_TOOL_PANEL_SURFACE_CLASS_NAME` | `acrylic-panel border` | 图层、图例、控制和预约任务面板 |
| `MAP_FOCUS_SURFACE_CLASS_NAME` | `acrylic-panel border` | 要素详情等焦点浮层 |
| `MAP_READABLE_SURFACE_CLASS_NAME` | `surface-well border` | 面板内部低密度区域 |
| `MAP_READABLE_SURFACE_STRONG_CLASS_NAME` | `surface-control border` | 面板内部高可读控制区 |

## 自适应与无障碍规则

- `data-basemap-tone="light"` 会提高部分面板模糊强度，并降低导航、控件和任务浮条的背景不透明度。
- `data-basemap-tone="satellite"` 会提高背景不透明度、轮廓和阴影强度，压制卫星底图纹理。
- `prefers-reduced-transparency: reduce` 下，亚克力和玻璃表面会切换到接近不透明的背景并关闭模糊。
- 不支持 `backdrop-filter` 的浏览器使用同样的高不透明度回退。
- `forced-colors: active` 下，材质背景和边框改用系统颜色，并关闭背景图与阴影。

## 使用约束

1. 一个浮动区域只允许最外层使用 `acrylic-*` 或 `glass-transient`。
2. 外层亚克力内部使用 `surface-control`、`surface-well` 或 `surface-reading`，不要叠加第二层模糊。
3. 密集文字、表格、属性和值必须落在 `surface-reading` 等高可读表面上。
4. `material-tone-*` 只表达状态，不表达层级，也不添加模糊。
5. 新增地图控件时优先复用 `map-control-styles.ts` 中的共享常量。
6. 组件只负责布局、圆角和交互状态，材质颜色、边框和阴影由全局语义类统一维护。

## 当前待清理项

- `surface-dock` 可在固定 Dock 落地时启用。如果产品不计划引入参与布局的常驻侧栏，可以移除该样式。
- `material-tone-danger` 应等待明确的严重业务状态落点，不要为了消除未使用状态而套用到通用错误提示。
- `material-tone-agent` 可优先用于 `FeatureInsightPanel` 的“Agent 解释”和 Agent 建议内容，替代不准确的警告语义。
- Agent 面板仍有少量局部类直接使用 `--surface-control`、`--surface-reading` 或自定义透明背景。后续统一材质语义时，应评估是否迁移到对应的 `surface-*` 类。