# 移动端交接班摘要模块（iAOP-Core / shift-handover）

对齐 PRD **场景C（辅助）** 与 **5.4「④ LLM 网关」**：

> 交接班 → LLM 汇总本班关键事件/能耗/待办 → 生成交接班报告 → 推送下一班。

以及 PRD 验收口径：交接班报告生成 ≤ 2 分钟（line 350）、移动端交接班摘要可用（line 284/351）。

## 模块状态

| 能力 | Issue | 状态 |
| --- | --- | --- |
| **移动端交接班摘要生成（NL）** | **#53** | **本分支 feature/issue-53** |

`#53` 把"本班原始数据 → 移动端交接班摘要"这条链路**模板化、可配置、可测试**：
班次数据归一化（`ShiftRecord`）→ 按 `HandoverBriefConfig` 经 LLM（或离线确定性降级）
生成摘要 → 编译成移动端只读卡片可直接消费的 props。

## 设计要点

- **零运行时依赖**：与 cockpit / data-bus / llm-gateway 一致，只用标准库；LLM 调用以
  **依赖注入**形式传入（`llm_generate: Callable[[str], str]`），内核不绑定云端 SDK，
  便于本地闭环与离线降级。
- **离线/故障自动降级**：未注入 LLM 或调用失败时回落到 `render_deterministic_brief`
  （PRD「模型服务故障自动降级」「可用性 ≥ 99.8%」），保证交接班链路不中断。
- **声明式 + 强校验**：`validate_handover_config` 收集全部字段级错误（沿用 #50/#52
  风格），`load_handover_config` 校验失败抛 `HandoverConfigError` 并携带错误清单。
- **与未合并分支解耦**：不 import `llm-gateway` 的 `PromptRegistry`；仅按约定的
  `prompt_template` 名字产出 LLM 输入文本，待 llm-gateway 合入后由调用方注入真正的
  LLM 生成函数。

## 配置点（外置为模板资产，切换模板零改码）

| 配置点 | 字段 | 说明 |
| --- | --- | --- |
| 提示词模板 | `promptTemplate` / `promptVersion` | 绑定 `shift_handover` v1.0.1（current） |
| 章节 | `sections` | overview/abnormal/safety/energy/todos |
| 展示策略 | `maxEvents` / `maxTodos` / `collapseThreshold` | 移动端折叠与截断 |
| 字号 | `fontSize` | sm/md/lg |
| 高利害确认 | `requireConfirm` | 默认 false；含 P0/安全事件时内核强制 true |

## 用法

```python
import sys, types, os
# 含连字符目录挂载为 shift_handover 包（同 core/data-bus 的做法）
_d = os.path.join("core", "shift-handover")
if "shift_handover" not in sys.modules:
    _p = types.ModuleType("shift_handover"); _p.__path__ = [_d]; sys.modules["shift_handover"] = _p

from shift_handover.handover import (
    normalize_shift_record, render_handover_brief, generate_handover_brief,
)

# 1) 班次数据（来自驾驶舱/总线/告警面板聚合）
record = normalize_shift_record({
    "shift": "夜班 2026-08-05 00:00~08:00", "operator": "张工",
    "overview": "TiCl4 产量 36.2t。",
    "events": [{"time": "01:20", "title": "炉层温度越上限", "severity": "P1"}],
    "todos": [{"title": "白班复测 3 层温度", "priority": "high"}],
    "safety": "注意 3 层高温区巡检。",
})

# 2) 生成摘要（llm_generate=None 时离线降级；注入则用 LLM 输出）
summary = generate_handover_brief(record, llm_generate=my_llm_fn)

# 3) 编译移动端只读卡片 props
props = render_handover_brief(record, summary=summary)
```

## 测试与验收

```bash
# 单元测试（在 core/shift-handover 目录下）
python -m unittest discover -s tests -v          # 32 用例全通过

# 验收脚本（4 能力点：配置合法 / LLM+降级 / 配置点驱动展示 / ≤2 分钟）
python scripts/verify_handover_brief.py
```