` 即可，组件自建卡片+表格+分页
10. **v2.0徽章**: `.ht-badge-ok`(绿) / `.ht-badge-warn`(橙) / `.ht-badge-bad`(红) / `.ht-badge-info`(蓝)
11. **v2.0加载态**: 自动显示旋转spinner，数据就绪后淡出
## HermesTable v2.2 聚合模式（2026-07-09）
- v2.2修复：聚合时自动切换列定义 → 期间 | 笔数 | sumKeys列
- `renderCols` 动态替换，聚合行用专用列，非聚合行用原始列
- `sumKeys` 空数组时只显示期间+笔数（无数值聚合）
- 聚合行class `.ht-aggr-row` 自动加灰底+粗体
- **dateKey**: 设置后出现日期范围筛选 + 日/周/月/季/年按钮
- **period**: 默认'day'，切换后自动分组聚合
- **sumKeys**: 聚合时求和的列名，如 `['amount','unit_price']`
### v2.2 聚合模式Pitfall
聚合时 tbody 渲染用聚合列（期间/笔数/sumKeys），但表头不变（仍显示明细列名）。
切换回「日」时恢复明细列+原始表头。
设计原因：避免 `rebuild()` 重渲染整个表头导致排序状态丢失。
### 外部控件移除规则（v2.2+）
HermesTable v2.2 自带了：搜索、每列筛选、日期范围、周期折叠、排序、分页、导出。
**所有外部工具栏控件必须移除**——包括但不限于：pivot选择器、部门下拉、搜索框、周期按钮、筛选输入框。
这些控件的 `oninput`/`onchange` 回调会覆盖 HermesTable 的 DOM，导致渲染错误。
页面只需要：KPI卡片 + info-bar + `
`。
## 铁律（用户明确要求，2026-07-09）
1. **不得估算**：所有数据必须真实。未经验证的数字不得写入页面。不确定就说不确定。
2. **输出前质检**：页面改动后必须 `node --check` 验证JS语法，必须确认JSON字段存在，必须确认数据格式匹配。
3. **功能完成才算完成**：用户说"要排序+筛选+周期折叠"，加了 dateKey 但没加 sumKeys/聚合列渲染 = 偷工减料 = 用户骂"什么原因？老老实实做好我的需求"。
4. **改完立即验证**：不要输出"刷新试试"然后等用户反馈。改完先用 `curl` 测API、用 `node --check` 验JS、确认每个 `render()` 调用的参数齐全。
## ⚠️ 铁律（用户明确要求）
1. **不得估算**：所有数据必须真实。未经验证的数字不得写入页面。不确定就是不确定。
2. **输出前质检**：页面改动后必须 `node --check` 验证JS语法，必须 `curl` 确认JSON字段存在，必须确认数据格式匹配。
3. **功能完成才算完成**：用户提出排序+筛选+周期折叠，只加 dateKey 不补 sumKeys/聚合列渲染是偷工减料。每个 `render()` 调用必须覆盖所有声明的功能。
## HermesTable v2.2 参数速查
| 参数 | 必需 | 说明 |
|------|:--:|------|
| `container` | ✅ | CSS选择器 |
| `columns` | ✅ | `[{key,label,sortable,type,format}]` |
| `data` | ✅ | 数据数组 |
| `id` | ✅ | 唯一ID |
| `dateKey` | — | 设置后出现日期筛选+周期按钮 |
| `sumKeys` | — | 聚合时求和的列名数组 |
| `period` | — | 默认'day' |
| `dateFrom/dateTo` | — | 默认日期范围 |
| `pageSize` | — | 默认20 |
| `dataSource` | — | 原始JSON路径 |
## 已改造页面
| 页面 | 表格 | 版本 |
|------|------|:--:|
| 宝锐统一工作平台 — 📋 活动明细 | 日期/部门/客户/销售员/类型/摘要 + 日期筛选+周期折叠 | v2.2 |
| 宝锐统一工作平台 — 📦 销售明细 | 日期/单号/客户/货号/单价/价税合计 + KPI目标+达成率 + 日期筛选+周期折叠 | v2.2 |
| 宝锐统一工作平台 — 🧪 测试明细 | 日期/客户/产品/数量/金额/销售员 + 日期筛选+周期折叠 | v2.2 |
| 宝锐统一工作平台 — 💬 客诉跟进 | 天数/客诉/等级 + 徽章 | v2.0 |
| 宝锐统一工作平台 — 🚦 审批阻塞 | 等级/天数/工作项/节点 + 徽章 | v2.0 |
| 宝锐测试反馈中心 | 6个表格 | v1.1 |
| 宝锐客户综合管理工作台 | 5个表格 | v1.1 |
## 数据管道模式
| 文件 | 说明 |
|------|------|
| `references/mcp-feishu-pipeline.md` | MCP→飞书项目管道（拉取/客户解析/Prefect/缓存） |
| `references/mcp-feishu-pipeline.md` | MCP→飞书项目数据管道模式（销售/活动/客诉拉取、客户名解析、Prefect管道） |
## 数据增强模式（Data Enrichment）
### 模式1: 多数据源并行加载
当页面需要多个JSON（主数据+采购转化+月度统计等），用 `Promise.all`：
```javascript
Promise.all([
fetch('/数据/main.json?v=2').then(function(r){return r.json();}),
fetch('/数据/extra.json?v=2').then(function(r){return r.json();}).catch(function(){return null;})
]).then(function(results){
D=results[0]; DExtra=results[1];
if(DExtra) enrichData(); // 辅助数据加载失败不阻塞主流程
initAll();
});
```
- 辅助数据用 `.catch(function(){return null;})` 兜底，不阻塞主流程
- 每个JSON加 `?v=N` 破缓存
### 模式2: 跨数据集交叉引用
当两个数据集使用不同的编码体系（如测试反馈用短码 "AS412-9"，ERP用层级码 "2.04.02.0496"），通过**名称模糊匹配**建立映射：
```python
# Python端生成映射表
def norm(s):
s = s.lower().strip()
s = re.sub(r'[（(][^)）]*[)）]', '', s) # 去括号内容
s = re.sub(r'[\s\-_/]+', '', s) # 去空格/横线
return s
```
> 匹配率通常80-90%，未匹配产品需人工核验。
### 模式3: 客户端动态聚合（aggregateFromRaw）
当JSON缺少聚合维度（如 `salespeople`、`customers`），在浏览器端从 `raw` 记录动态计算：
```javascript
function aggregateFromRaw(){
var raw=D.raw||[], spMap={};
raw.forEach(function(r){
var key=r.salesperson||'未知';
if(!spMap[key])spMap[key]={name:key,total:0,positive:0,negative:0,neutral:0,mild:0,prods:{}};
spMap[key].total++;
var s=r.sentiment||'neutral';
if(s==='positive')spMap[key].positive++;
else if(s==='negative')spMap[key].negative++;
else if(s==='mild')spMap[key].mild++;
else spMap[key].neutral++;
// ... top products
});
D.salespeople=Object.values(spMap).map(function(s){
s.pos_pct=Math.round(s.positive/s.total*100);
s.neg_pct=Math.round(s.negative/s.total*100);
s.other=s.total-s.positive-s.negative;
return s;
});
}
```
### 模式4: 采购数据→正反馈加权
将ERP采购记录作为正向信号融入产品评级：
```javascript
// 加载采购转化数据后
prodData.forEach(function(p){
if(p._purchCount>0){
var adjPos=(p.positive||0)+p._purchCount; // 采购=额外正向
p.pos_pct=Math.round(adjPos/p.total*100);
// 重算评级
if(p.total>=10&&p.pos_pct>=60){p.rating='green';p.is_star=true;}
}
});
```
- 表格增加"曾采购"列显示 `✓ 100%` 或 `-`
- 总览KPI增加"💰 曾采购"卡
- 有采购记录但未达⭐阈值的标记 `💰 采购验证`
### 模式5: 月度趋势数据独立生成
当JSON不含月度统计，从源Excel单独提取为轻量JSON：
- 源文件：飞书活动导出 Excel
- 按"创建时间"列 → `YYYY-MM` 分组计数
- 输出：`/数据/test_feedback_monthly.json`（<1KB）
- 页面用 `Promise.all` 并行加载，注入 `D.monthly`
- 数据密集型表格优先（仪表盘、价格查询）
- CRUD操作型表格可保留原样（订单列表含选中/发货等交互）
## IMA风格工作台设计模式（2026-07-10）
宝锐工作台已全面改为IMA参考设计语言，不再使用HermesTable组件。
### 视觉标准
- **顶栏**: 暗色渐变 `linear-gradient(135deg,#1a1a2e,#16213e,#0f3460)` + 白色文字, 56px高
- **角色切换**: `rgba(255,255,255,.1)` 背景按钮组，`.active` → `#e94560` 玫红
- **统计卡片**: `.stat-card` 白底圆角 + 左侧4px彩色边框
- **维度面板**: `.dim-panel` 白底 + `.dim-header` 暗色（#1a1a2e）
- **徽章**: `bg-green`/`bg-red`/`bg-yellow`/`bg-blue` 四色
- **页面背景**: `#f0f2f5`
### 架构原则
- 单DATA对象 + Promise.all一次性加载
- 角色分权：ROLE='ceo'|'dir'|'sales'
- 纯innerHTML，零外部依赖
- 数据源优先手动Excel（准确），MCP API补充
- 每个面板底部tooltip-info引用管理规程
### Excel管道
```python
# 跳过标题行，过滤NaN，按列名索引
df = pd.read_excel(path, header=None, skiprows=2)
# 关键列: [0]单据编号 [2]价税合计 [6]合同日期 [3]客户 [21]货号 [30]含税单价
```