# 订单管理页面构建实战（2026-07-24）

## 新增模式

### 1. 时间范围分析（本周/月/季/年切换）

用 `.seg-control` 按钮组切换分析周期，动态计算时间范围并统计：

```javascript
var orderState = { analysisPeriod: 'week' };
// 本周=周一至周日，本月=1日至今日，本季=季度首日至今日，本年=1月1日至今日
// 统计卡片自动切换标签（"本周发货"→"本月发货"等）
// 金额用 fmtW() 格式化为万元
```

### 2. 三栏分析布局

```html
<div style="display:grid;grid-template-columns:1fr 1fr 1fr;gap:16px">
  <div>🏆 客户Top5（按金额排名）</div>
  <div>📋 订单类型（进度条百分比）</div>
  <div>⚠️ 物流异常（未签收明细，最多10条）</div>
</div>
```

### 3. 金额字段灰底高亮行

展开详情时，数量/单价/含税单价/金额/价税合计独立灰底行。只有非零非空字段才显示。

### 4. 下单人：用 MCP 角色字段而非创建者

- ❌ `创建者` → 系统记录创建人（全指向殷士海）
- ✅ `__下单人` → MQL角色语法，返回真实业务人员（22人）
- 返回值类型: `user_value_list` → 取 `name_cn`

### 5. 合同编号列

MCP字段 `合同编号#` (field_4a1b47)，在表格中独立一列。

### 6. 浏览器缓存：服务器端 no-cache

```python
def end_headers(self):
    if path.endswith('.html'):
        self.send_header('Cache-Control', 'no-store, no-cache, must-revalidate')
```
仅 HTML meta 标签不够，必须服务器端设置——否则用户反复看到旧版。

## 顺丰API关键要点

- **checkPhoneNo 必传**：不传返回空路由
- **trackingNumber 必须数组** `["SFxxx"]`
- **生产用 accessToken**：msgDigest 返回 A1006
- **签收判断用多关键词**：`派送至本人/派送成功/签收/已通知客户取件/放入快递柜/门卫代收等19个`
- **派送中判断**：`正在派/派送中/派件中`（注意与签收区分）

## MCP管道保护

- 大数据量（>20页）用 terminal 直跑 Python 脚本，不要用 delegate
- MCP session 每20页重建，防止过期
- 写入 JSON 前备份现有文件
- 金额字段需从 MCP 额外拉取（不在基础字段集中）

## H1/H2 数据分层归档（2026-07-24 实战）

### 归档规则
- **H1（≤6/30）**：全部归档，仅保留月度/客户/部门汇总指标（3KB）
- **H2 已签收＞7天**：自动归档至H1，从实时数据移除
- **H2 在途/未签收**：保留实时，cron每日刷新

### 前端本年合并防坑
```javascript
// ❌ h1Summary.delivered — 不存在！字段名是中文
var h1Delivered = data.h1Summary.delivered || 0;

// ✅ 正确读取
var h1Status = data.h1Summary.status || {};
var h1Delivered = h1Status['已签收'] || 0;
var h1NoTracking = h1Status['无物流'] || 0;

// 本年发货 = H2有物流 + H1有物流（排除无物流订单）
ps.total += (h1Total - h1NoTracking);

// H2统计也要排除no_tracking
if (s !== 'no_tracking') ps.total++;
```

### 金额聚合：按单据编号（非物流单号）
同一单据编号的多行物料，价税合计需累加。去重按 `单据编号`，金额按 `价税合计` 字段求和。

## 客户Tab MCP切换

- 客户数/联系人：用 `客户` 表 `联系人数量` 字段汇总（1678客户/7723联系人），不用订单收货人去重
- 2026累计采购：H1（从订单MCP拉取客户维度汇总）+ H2（从h2_live.json按客户汇总）
- 部门筛选：从客户表 `所属人部门/区域` 字段生成下拉
- 飞书链接：`https://project.feishu.cn/xsguanli/workObjectView/65ae1e403c87b152f3365ca6/{work_item_id}`

## 数据管道脚本模式

```python
# 直连MCP streamable HTTP（不经过Hermes MCP工具，更快）
URL = "https://project.feishu.cn/mcp_server/v1"
TOKEN = "m-abfb29e8-3104-434f-9944-8d0bb592f8cd"

# 用 JSONDecoder.raw_decode 代替 regex — regex匹配 {.*} 会失败
from json.decoder import JSONDecoder
decoder = JSONDecoder()
inner, _ = decoder.raw_decode(content.strip())

# 字段提取：注意value_type映射
# string_value → .string_value
# key_label_value → .label
# user_value_list → .name_cn 逗号连接
# double_value → .double_value
# long_value → .long_value

# 翻页：每20页重建MCP session，防止过期
```