eHome App 端详细需求设计文档

M07 传感器校准（对应需求：FR-1601~1606）

项目	内容
所属项目	eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据	《eHome智能家居项目需求文档（PRD V1.1）》传感器校准章节、第8章、NFR-02（指令下发时延）/NFR-06（兼容性）；《eHome项目页面功能工时费用明细表》M07模块
范围说明	本模块覆盖传感器类设备（温湿度/光照/空气质量/人体存在等）的校准向导、偏移量/两点校准、校准记录与撤销、固件级校准参数下发与验证、校准有效期管理；不包含阈值告警配置（属 M04-R03）、历史趋势图表（属 M04-R02）、OTA 升级流程（属 M09）
优先级	P0（MVP必须；传感器精度是监测/告警/数据分析三大模块的数据可信度基石，出厂漂移与安装环境差异必须可通过校准修正）
里程碑	M2 完整功能期开发（依赖 M01 账号、M02 家庭/设备数据、M03 配网绑定、M04 实时数据流；固件侧校准协议须 M1 冻结）
文档用途	直接交付 UI 设计、Flutter 开发（APP端）、云端开发、固件联调、测试QA

需求编号映射（以工时表 M07 功能项为准）：

需求编号	功能项
FR-1601	校准入口与状态总览（校准状态徽标、有效期提醒、可校准能力检测）
FR-1602	单点偏移校准向导（参考值输入、实时读数对比、偏移量计算与确认）
FR-1603	两点线性校准向导（低温/高温两点采样、斜率截距计算、精度预览）
FR-1604	校准参数下发与生效验证（固件写入、回读校验、失败回滚）
FR-1605	校准记录管理（历史记录、当前参数查看、恢复出厂校准、有效期管理）
FR-1606	传感器校准流程 UI 设计（向导组件、双主题、7语种、无障碍）

1. 模块概述与设计原则

1.1 模块范围

序号	页面/功能项	需求编号	类型	优先级
1	校准状态总览区（设备详情页内嵌+校准中心页）	FR-1601	APP+云端	P0
2	单点偏移校准向导页	FR-1602	APP+云端+固件	P0
3	两点线性校准向导页	FR-1603	APP+云端+固件	P0
4	下发与验证流程（进度态/回读校验/回滚）	FR-1604	云端+固件	P0
5	校准记录页	FR-1605	APP+云端	P0
6	校准 UI 规范	FR-1606	UI	P0

边界与衔接说明：

入口A：M04-R01 传感器设备详情页【校准传感器】→ 本模块 C01；
入口B：「我的」Tab →【设备管理】→ 选择传感器 → C01（设备未选定时先进 M02 设备列表筛选传感器品类）；
入口C：M04-R01 数据异常横幅【排查数据问题】→ 排查结论指向漂移时引导 C01；
出口：校准完成回 R01（数值即时应用新校准参数）；C05 恢复出厂校准后提示重新核对 M04-R03 告警阈值；固件版本不支持校准时引导 M09 OTA。

1.2 设计原则

数据链路一致：校准参数在设备固件端生效（边缘校准），云端与 APP 不另做软件修正层——保证语音生态（M11）、第三方生态、APP 三端读到同一校准后数值，避免多端不一致。
引导式低门槛：默认推荐单点偏移校准（覆盖80%场景，2分钟完成）；两点校准仅对温度类高精度需求开放，向导明确说明差异与适用场景，不强迫用户理解斜率/截距概念。
参考值可信提示：单点校准依赖用户提供可信参考值（标准温度计/权威气象数据），向导必须明示参考值来源建议与误差风险；参考值明显异常（偏离当前读数超量程50%）时强确认拦截。
可撤销可追溯：每次校准写入记录（操作人/时间/前后参数/参考值来源）；任意时刻可恢复出厂校准；下发失败自动回滚至上一有效参数，设备永不难用。
有效期管理：校准有效期默认12个月（云端可按品类配置）；到期前7天推送提醒（复用 M06 通知渠道）；过期不强制失效，仅降级展示"建议重新校准"。
安全红线：校准仅家庭管理员或有设备编辑权限成员可操作（联动 M02 权限）；参数下发需设备在线且非 OTA 升级中（联动 M09 升级锁定）；下发指令走签名 MQTT 通道防伪造。
双主题 + 7语种：向导步骤文案、单位（℃/℉ 跟随 M04 设置）、记录字段全部资源文件；数值输入键盘类型按语种地区适配（小数点/逗号）。

1.3 用户与前置条件

用户状态：必须已登录（M01）；未登录拦截跳转登录页，成功回跳 C01。
设备前置：目标传感器已绑定当前家庭、在线、电量 ≥20%（低电量校准失败风险高，强提示先换电池）；固件版本 ≥ 最低校准支持版本（云端配置下发，不满足→引导 M09 OTA）。
能力前置：设备能力模型声明 calibration 能力（支持的校准类型：offset/two_point、指标：温度/湿度/光照等、量程与步进精度）；无该能力的品类（如门窗磁）不展示校准入口。
权限前置：家庭管理员或具备设备编辑权限的成员；普通成员进入 C01 为只读态（可见状态与记录，按钮置灰+提示）。
环境前置：向导内提示"校准前请将设备置于稳定环境≥30分钟"（温湿度类），光照类提示"准备已知照度参考环境"。

2. 页面结构与流程图

2.1 页面导航结构

入口A：M04-R01[校准传感器] ──► C01
入口B：我的→设备管理→[传感器] ──► C01
入口C：R01数据异常横幅[排查]──(结论=漂移)──► C01

C01 校准状态总览页
 ├─ 校准状态卡（未校准/已校准+偏差预览/校准过期/固件不支持）
 ├─ 当前参数摘要（偏移量/校准类型/校准时间/剩余有效期）
 ├─ [开始校准] ──► C02 校准方式选择
 │     ├─ [单点偏移校准·推荐] ──► C03 单点校准向导（4步）
 │     └─ [两点线性校准] ──► C04 两点校准向导（6步）
 ├─ [校准记录] ──► C05
 └─ [恢复出厂校准] ──► C05（危险操作区）

C03 单点校准向导（步骤条 1/4~4/4）
 ├─ Step1 准备与环境确认（checklist勾选）
 ├─ Step2 稳定读数采集（30s采样窗口+波动检测）
 ├─ Step3 参考值输入（单位切换+异常强确认）
 └─ Step4 确认与下发 ──► C06 下发进度页 ──(成功)──► 完成页[查看效果]回R01

C04 两点校准向导（步骤条 1/6~6/6）
 ├─ Step1 准备与环境确认
 ├─ Step2 低点采样（低温环境+参考值）
 ├─ Step3 高点采样（高温环境+参考值）
 ├─ Step4 精度预览（校准前后误差对比图）
 ├─ Step5 确认参数（斜率/截距可视化解读）
 └─ Step6 下发 ──► C06

C06 下发与验证页
 ├─ 进度步骤：参数写入→设备重启采样→云端回读校验
 ├─ 成功：✓+新参数摘要+[完成]
 └─ 失败：原因+自动回滚提示+[重试]/[联系客服]

C05 校准记录页
 ├─ 当前生效参数卡
 ├─ 历史记录时间线（操作人/时间/类型/前后值/来源）
 ├─ [恢复出厂校准]（红色危险按钮+身份验证）
 └─ 有效期进度条+到期提醒开关

2.2 核心状态机一：设备校准状态（设备×指标维度）

[未校准]（出厂默认参数）
   │
   ├──(完成校准向导并下发成功)──► [已校准]
   │        │
   │        ├──(有效期内)──► 正常展示"校准有效 · 剩余N天"
   │        ├──(到期前7天)──► [临期] ──► M06通知渠道推送提醒 ──► [已校准·建议重校]
   │        ├──(超过有效期)──► [校准过期]（参数仍生效，状态徽标橙色，R01/C01提示重校）
   │        │
   │        ├──(再次校准成功)──► [已校准]（有效期重置，旧记录归档）
   │        └──(恢复出厂校准)──► [未校准]（清空偏移参数，记录归档）
   │
   ├──(下发失败)──► [校准失败] ──► 自动回滚至上一有效参数
   │        ├──(回滚成功)──► 恢复之前状态（未校准/已校准）
   │        └──(回滚失败·罕见)──► [参数异常] ──► 云端告警运维 + APP强提示联系客服
   │
   └──(固件升级后校准能力变化·M09联动)──► 重新拉取能力模型刷新可用校准类型

2.3 核心状态机二：校准下发事务（云端-固件）

[APP提交校准参数]
   │
   ├──(前置校验：设备在线/非OTA中/权限/签名)──► [事务创建·参数暂存云端]
   │        │
   │        ├──(MQTT下行 calibrate/set {params, txId, signature})──► [等待固件ACK]
   │        │        │
   │        │        ├──(固件写入Flash成功→ACK)──► [等待验证采样]
   │        │        │        │
   │        │        │        ├──(固件应用新参数上报≥3条数据)──► [云端回读校验]
   │        │        │        │        │
   │        │        │        │        ├──(回读参数一致+数据合理性通过)──► [事务成功] ──► 更新校准状态+写记录+APP完成页
   │        │        │        │        └──(校验失败)──► [事务失败]
   │        │        │        │
   │        │        │        └──(超时120s无有效数据)──► [事务失败·超时]
   │        │        │
   │        │        └──(固件写入失败→NACK/超时60s)──► [事务失败]
   │        │
   │        └──(校验不通过)──► [拒绝提交] ──► APP展示具体原因
   │
   └──[事务失败]──► (MQTT下行 calibrate/rollback {lastValidParams})──► [自动回滚]
            ├──(回滚ACK成功)──► 状态恢复 + APP提示"已回滚，设备可正常使用"
            └──(回滚失败)──► [参数异常] 运维告警 + 工单入口

3. 页面级详细需求

C01 校准状态总览页（FR-1601）

页面目标：一屏看清该传感器校准健康度，低门槛进入校准流程。

页面元素：

元素	规格与规则
顶部导航	返回箭头 + 标题"传感器校准"；设备名+房间名副标题
状态徽标卡	四态：未校准(灰"使用出厂参数")/已校准(绿"校准有效·剩余N天")/校准过期(橙"已超有效期，建议重校")/固件不支持(蓝"升级固件后可校准")；徽标含图标+文字不只靠颜色
当前偏差预览卡	已校准态展示：当前偏移量/校准类型/校准时间/操作人；未校准态展示引导文案"校准可修正安装环境导致的读数偏差"
可校准指标列表	按设备能力模型动态生成（温度/湿度/光照…）；每指标：当前状态+精度规格（如±0.3℃）；多指标设备逐指标独立校准
[开始校准]	主按钮；固件不支持时替换为[升级固件]→M09；设备离线时置灰+提示"设备离线，请先恢复连接"→M02-Q04
[校准记录]	次按钮 → C05
低电量提示条	电量<20%时黄色横幅"电量较低，校准可能失败，建议先更换电池"+[仍要继续]
权限只读态	普通成员：按钮全部置灰+顶部提示"仅管理员可执行校准"

逻辑规则：

数据来源：GET /calibration/{deviceId}/status（返回各指标校准状态、当前参数、有效期、能力声明、电量、固件支持版本）；进入页面拉取+下拉刷新；
有效期倒计时：云端存储校准时间+品类有效期配置（默认365天）；剩余天数客户端按本地时区计算展示；
能力检测：能力模型无 calibration 声明 → 页面整体替换为"该设备不支持校准"说明态（含品类原因，如门窗磁为开关量无校准概念）；
固件版本比对：当前版本 < calibration_min_firmware → 状态徽标"固件不支持"+[升级固件]按钮（携带目标版本跳转 M09）；
与 R01 联动：校准完成后返回 R01，实时数值立即反映新参数（固件端已生效，无需APP处理）；
埋点：页面曝光、开始校准点击、各拦截态（离线/低电量/固件/权限）曝光与转化。

异常与边界：状态接口失败→展示缓存+重试按钮；设备校准中被移除（M02）→Toast"设备已移除"返回列表；多指标设备部分指标不可校准→逐项独立展示状态。

验收要点：四态徽标与云端一致；能力/固件/电量/权限/离线五重前置拦截正确；多指标独立状态展示；只读态无操作入口。

C02 校准方式选择页

页面目标：帮助用户按需求选择合适校准方式，明示差异与成本。

页面元素：

元素	规格与规则
方式卡片：单点偏移	"推荐"角标；说明"修正整体读数偏高/偏低，约2分钟，适合绝大多数场景"；适用指标标签（全部可校准指标）
方式卡片：两点线性	说明"修正全量程线性偏差，需准备两个不同温度环境，约15~30分钟"；仅温度类指标可选（能力模型 two_point 声明）；不可用时置灰+原因
对比说明折叠面板	表格对比：耗时/所需准备/修正能力/适用场景
准备清单	通用清单：设备在线、电量充足、参考工具（标准温度计/权威气象App数据）、稳定环境≥30min
[下一步]	进入对应向导；[返回]回C01

逻辑规则：两点校准入口仅当能力模型声明支持且指标=温度时可用；已有两点校准记录的设备再次单点校准会覆盖为单点参数——选择时弹窗告知"将替换现有两点校准参数"。

验收要点：方式可用性按能力模型动态正确；覆盖告知弹窗触发；准备清单多语言完整。

C03 单点偏移校准向导（FR-1602）

页面目标：4步引导完成偏移校准，采样稳定性与参考值可信度双保障。

步骤流程：

步骤	内容	交互与校验
Step1 准备确认	checklist：①设备已置于稳定环境≥30分钟 ②已准备可信参考值来源 ③设备电量充足；逐项勾选后[下一步]激活	勾选状态仅本次会话有效；[查看参考值来源建议]展开H5说明（标准温度计/当地气象局数据/同房间已校准设备）
Step2 稳定采样	实时读数大字展示+30s采样窗口；波动检测：30s内极差>阈值（温度0.5℃/湿度3%）判定不稳定，提示"环境波动较大"→[重新采样]/[强制继续]（记录标记forced）	MQTT订阅实时数据；采样进度环形动画；强制继续需二次确认且写入记录
Step3 参考值输入	数值输入框+单位切换（℃/℉联动M04设置）；键盘类型按locale（德/法小数逗号自动转换）；输入即预览"当前读数 vs 参考值 → 偏差 X"	校验：参考值在设备量程内；偏差超量程50%→红色强确认弹窗"参考值与当前读数差异过大（X），请确认输入正确"；必填
Step4 确认下发	汇总卡：设备/指标/稳定读数均值/参考值/计算偏移量/校准后预览读数；[确认并下发]→C06；[返回修改]回Step3	偏移量=参考值-采样均值（保留设备精度位数）；确认页明示"参数将写入设备固件"

逻辑规则：

采样均值计算：30s窗口内剔除异常标记数据（M04 anomaly）后取均值；有效样本<10条→提示采样失败重试；
向导中断保护：任意步骤退出弹窗"校准未完成，进度将不保留"；Step2采样数据本地暂存防APP闪退丢失（恢复仅限同一会话5分钟内）；
计算与下发：APP将偏移量提交 POST /calibration/{deviceId}/apply（云端二次校验量程/精度步进后进入下发事务）；APP不直接下发MQTT；
埋点：各步骤到达率/流失率、波动强制继续占比、参考值异常拦截次数、全流程耗时。

异常与边界：Step2期间设备离线→中断向导提示恢复连接后重来；Step3切换单位自动换算已输入值；提交瞬间设备进入OTA（M09锁定）→云端拒绝返回错误码，APP提示稍后再试。

验收要点：四步流转+中断保护；波动检测阈值触发与强制继续标记；参考值强确认拦截；单位换算与locale键盘正确；偏移量计算精度正确。

C04 两点线性校准向导（FR-1603）

页面目标：6步完成温度类传感器全量程线性校准，向普通用户屏蔽数学概念。

步骤流程：

步骤	内容	交互与校验
Step1 准备确认	checklist：①可制备低温环境（如冰水混合物0℃附近）②可制备高温环境（如恒温40℃附近，勿超设备量程）③两点间隔建议≥20℃；附安全提示（勿将设备浸入液体除非IP等级允许）	展开[为什么需要两个点]图文说明
Step2 低点采样	设备置于低温环境→实时读数+30s采样窗口（同C03波动检测）→输入低点参考值	参考值需处于量程下1/3区间，否则提示"低点建议靠近量程下限"
Step3 高点采样	设备移至高温环境→提示"等待读数稳定（通常需10~20分钟）"→用户点击[读数已稳定]后开始30s采样→输入高点参考值	高点参考值需处于量程上1/3区间；高低点差<15℃→警告"两点间距过小将放大误差，建议重新制备环境"+[仍要继续]
Step4 精度预览	图表对比：校准前（两点实测偏差连线）vs 校准后（理论归零）；文案"校准后全量程最大误差预计从 ±X℃ 降至 ±Y℃"	计算斜率k=(高参考-低参考)/(高采样-低采样)、截距b；k超出合理区间[0.8,1.25]→提示传感器可能存在硬件异常，建议联系售后+可强制继续（记录标记suspect）
Step5 确认参数	通俗化展示："读数将被按比例修正"；专业参数折叠面板（k/b值、采样原始数据）供高级用户核对；[确认并下发]→C06	覆盖既有校准参数的告知（若有）
Step6 下发	直接进入C06事务	—

逻辑规则：

两点采样数据全程本地暂存+云端草稿保存（POST /calibration/draft），支持24h内断点续做（向导页展示"继续上次未完成的校准"入口）；
k/b计算在APP端预览、云端提交时重算校验（双端一致性）；
硬件异常判定（k越界）仅提示不阻断，标记 suspect 写入记录供售后排查；
环境制备指引为建议性质，免责声明"请参考设备说明书操作，因不当操作造成的损坏不在保修范围"（H5链接）。

验收要点：六步流转+草稿续做；高低点区间校验与间距警告；k越界suspect标记；精度预览图表与计算一致；覆盖告知。

C06 下发与验证页（FR-1604）

页面目标：透明展示"写入-验证-生效"事务过程，失败可回滚可解释。

页面元素：

元素	规格与规则
进度步骤条	三步：①参数写入设备 ②设备应用新参数（重启采样，约30~60s）③云端验证；每步loading/✓/✘
实时状态文案	"正在写入校准参数…"/"设备正在应用新参数，请稍候"/"正在验证校准效果…"
成功态	绿色✓+新参数摘要卡（类型/偏移量或k,b/生效时间/有效期至）+[完成]回C01、[查看实时数据]回R01
失败态	红色✘+失败原因（写入失败/验证超时/回读不一致）+回滚状态提示"设备已自动恢复上一校准参数，可正常使用"+[重试]/[联系客服]（携带txId上下文→M10工单）
超时兜底	全事务120s超时判定；进度页轮询+MQTT双通道监听

逻辑规则：

事务状态来源：MQTT calibrate/tx/{txId} 推送（写入ACK/验证进度/最终结果）+ HTTP GET /calibration/tx/{txId} 轮询兜底（2s间隔）；
验证标准：云端回读固件参数与提交一致 + 新参数生效后连续3条上报数据合理性校验（与参考值偏差在预期精度内）；
回滚自动化：失败后云端自动下发 rollback（状态机2.3），APP展示回滚结果；回滚失败转"参数异常"态强提示联系客服；
事务幂等：同 txId 重复提交去重；事务进行中禁止发起新校准（C01按钮置灰"校准进行中"）；
期间设备离线：事务标记失败并回滚，恢复在线后云端校验固件实际参数与云端记录一致性（对账），不一致自动修复+告警运维。

验收要点：三步进度真实反映事务状态；失败三原因注入测试；自动回滚真机验证（失败后设备读数恢复）；事务幂等与并发锁定；断网/离线场景对账修复。

C05 校准记录页（FR-1605）

页面目标：完整追溯校准历史，支持一键恢复出厂与有效期管理。

页面元素：

元素	规格与规则
当前生效参数卡	指标+校准类型+参数值（偏移量或k/b）+校准时间+操作人+有效期至；[到期提醒]开关（默认开，到期前7天经M06渠道推送）
历史时间线	每条：时间+类型（单点/两点/恢复出厂/云端对账修复）+前后参数对比+操作人+标记（forced强制采样/suspect硬件疑似异常/rollback回滚）；点击展开详情（采样原始数据摘要）
[恢复出厂校准]	红色危险按钮（危险操作区）；弹窗告知："将清除所有校准参数，恢复出厂精度（±规格值）；已配置的告警阈值（M04-R03）建议校准后重新核对"→身份验证（复用M01验证服务）→POST /calibration/`{deviceId}`/factory-reset→走C06同款下发事务
有效期进度条	可视化剩余有效期占比；过期段橙色
空态	"暂无校准记录，当前使用出厂参数"+[开始校准]

逻辑规则：

记录来源：用户校准/恢复出厂/云端对账自动修复三类均写入，操作人字段区分（用户昵称/系统）；
记录保留：云端永久保留（设备生命周期内）；APP分页拉取每页20条；
恢复出厂权限：仅家庭管理员；需身份验证（短信/邮箱验证码或密码）；
suspect记录售后联动：详情页[联系售后]→M10工单自动携带suspect参数上下文；
到期提醒去重：同一校准周期仅提醒1次（提醒后记录已提醒标记）。

验收要点：三类记录完整可追溯；恢复出厂身份验证+下发事务+R01数值回退验证；标记体系（forced/suspect/rollback）正确；到期提醒单次触发。

4. 通用交互与视觉规范（UI设计输入，FR-1606）

双主题：浅色/深色两套；状态徽标四色（灰/绿/橙/蓝）深色模式调整亮度满足WCAG AA；向导步骤条、精度预览图表双主题适配。
组件清单：状态徽标卡、指标列表项、方式选择卡片（推荐角标/置灰态）、向导步骤条（横向4~6步）、checklist勾选项、采样实时读数卡（大数值+波动检测动画）、参考值输入框（单位切换/异常强确认弹窗）、精度对比图（校准前后双折线）、参数汇总卡、事务进度步骤条（三步态）、记录时间线条目（标记徽章）、危险操作区（红色按钮+确认弹窗，复用M02移除设备样式）、有效期进度条。
动效：采样窗口环形进度+读数实时跳动（300ms节流）；波动超标时读数卡抖动提示1次；事务步骤切换渐入；成功态✓打勾动画；徽标状态切换渐变。
多语言：向导全部步骤文案、checklist、单位（℃/℉/lux/%RH）、免责声明、记录字段资源文件；德/法预留1.4倍空间；数值输入locale适配（小数逗号）；免责声明法务多语言审定。
无障碍：步骤条支持读屏播报当前步骤/总步骤；checklist焦点顺序正确；状态不仅靠颜色（图标+文字）；强确认弹窗焦点锁定在弹窗内；采样动画提供"减弱动效"模式。
响应式：平板/折叠屏宽屏下向导采用左步骤条+右内容区布局；精度对比图宽屏全幅展示。

5. 客户端技术要求（Flutter）

MQTT 订阅：复用 M02/M04 连接层；订阅 sensor/realtime/{deviceId}（采样用）、calibrate/tx/{txId}（事务进度）；断连重连期间采样步骤自动暂停并提示（采样窗口顺延，超3次断连判定采样失败）。
状态管理：Riverpod/BLoC；向导多步骤用 StateNotifier 管理步骤状态机+本地暂存（C04草稿同步云端）；事务进度 StreamProvider(MQTT)+Timer轮询兜底；采样滑动窗口计算（30s、极差、均值、异常剔除）封装 SamplingEngine 工具类，单元测试覆盖。
数值处理：单位换算（℃↔℉）统一走 UnitConverter（与M04/M05共用）；精度按能力模型步进round；locale数值解析（逗号/点小数）用 intl 包 NumberFormat；k/b浮点计算注意精度（double，保留6位有效）。
本地暂存：Hive 存储向导草稿（C04两点数据，TTL 24h，键=deviceId+userId+draftVersion）；闪退恢复同会话5分钟内C03数据；草稿含采样原始序列（脱敏无PII）。
深链路由：注册 ehome://calibration/{deviceId}?metric= 路由；入口A/B/C携带上下文；事务完成深链回跳R01携带refresh标记。
性能：采样实时渲染节流300ms；精度预览图表复用 EhomeChartWidget（M05组件库）；向导页预加载下一步资源。
安全：校准提交走HTTPS；MQTT下行签名由云端生成（APP不接触签名密钥）；本地草稿不加密敏感级（无PII）但随账号数据清除（M01注销联动）；Sentry上报脱敏。
埋点：漏斗（C01曝光→开始→各步骤→提交→成功）、失败原因分布、forced/suspect标记率、恢复出厂使用率、全流程耗时P50/P90；支撑校准成功率运营监控（目标≥95%）。

6. 云端需求（校准服务）

6.1 接口清单

接口	方法	说明
/calibration/`{deviceId}`/status	GET	校准状态总览（各指标状态/当前参数/有效期/能力声明/固件支持版本/电量/OTA锁定状态）
/calibration/`{deviceId}`/apply	POST	提交校准参数（offset或k,b）；云端二次校验（量程/步进/事务冲突/设备状态）→创建下发事务→返回txId
/calibration/tx/`{txId}`	GET	事务状态查询（步骤进度/结果/失败原因码）；MQTT推送优先，本接口轮询兜底
/calibration/`{deviceId}`/factory-reset	POST	恢复出厂校准（身份验证凭证校验→下发事务）
/calibration/draft	POST/GET/DELETE	两点校准草稿云端暂存（24h TTL）
/calibration/`{deviceId}`/records	GET	校准记录分页查询（含标记/操作人/前后参数）
/calibration/`{deviceId}`/reminder	PUT	到期提醒开关设置
（MQTT下行）calibrate/set	—	参数写入指令（params+txId+签名）；QoS1；固件ACK/NACK回报
（MQTT下行）calibrate/rollback	—	回滚指令（lastValidParams+txId+签名）
（MQTT上行）calibrate/tx/`{txId}`	—	事务进度推送（写入ACK/验证数据/最终结果）→转发APP
（内部）校准事务管理器	—	事务状态机、超时控制（ACK 60s/全事务120s）、幂等去重、自动回滚、结果落库
（内部）参数对账任务	—	每日全量比对固件回读参数与云端记录；漂移自动修复（走静默下发事务）+告警运维；对账修复写入记录（操作人=系统）

6.2 关键策略

事务一致性：以 txId 为主键的分布式事务记录（暂存参数→ACK→验证→提交/回滚全状态落库）；任一环节失败自动回滚至 lastValidParams；回滚失败升级运维告警+工单；事务进行中锁定该设备校准操作。
双重校验：APP端预校验（体验快速反馈）+云端强校验（量程/步进精度/k合理区间/权限/设备在线/非OTA锁定/固件版本支持）；校验规则云端配置热更新（新品类接入不改代码）。
参数安全存储：生效参数与历史记录永久存储（设备生命周期）；参数下发指令签名（HMAC，密钥云端KMS管理），固件验签防伪造指令。
有效期管理：品类级有效期配置表（默认365天，云端可调）；到期提醒任务扫描（提前7天）→经M06通知渠道分发（尊重免打扰策略，但校准提醒为提示级P3）；过期不失效仅标记。
对账与自愈：每日对账任务（固件参数回读 vs 云端记录）；不一致自动静默修复并写记录；连续对账失败3次转人工工单。
性能SLA：status接口P99≤300ms；apply创建事务≤500ms；事务全程（写入→验证）P90≤90s；记录查询P99≤500ms。
运营监控看板：校准成功率（目标≥95%）、失败原因分布（写入失败/验证超时/回读不一致/回滚失败）、forced/suspect标记率（硬件质量信号反馈供应链）、恢复出厂率；suspect率超阈值自动告警硬件团队。

7. 验收标准核对表

需求	验收标准	本设计落点
FR-1601	四态徽标准确；能力/固件/电量/权限/离线五重拦截；多指标独立状态	C01；status接口；状态机2.2
FR-1602	四步向导闭环；波动检测+强制标记；参考值强确认；单位/locale正确	C03；SamplingEngine；UnitConverter
FR-1603	六步向导+草稿续做；高低点区间校验；k越界suspect；精度预览准确	C04；draft接口；双端计算一致性
FR-1604	事务三步透明；失败自动回滚真机验证；幂等与锁定；对账自愈	C06；事务管理器；回滚指令
FR-1605	三类记录可追溯；恢复出厂身份验证+数值回退；到期提醒单次	C05；records接口；提醒任务
FR-1606	双主题/7语种/无障碍/响应式全达标	第4章；组件清单；无障碍规范

QA测试要点（专项）：

校准全链路真机验证：单点/两点校准→下发→固件生效→R01数值变化符合偏移量→语音生态（M11）读数同步一致（边缘校准三端一致性核心验证）；
事务失败注入：固件写入NACK/验证超时/回读不一致三类注入→自动回滚→设备读数恢复上一参数；回滚失败→参数异常态+运维告警；
采样引擎：波动数据注入（极差超阈值）触发不稳定提示；异常标记数据剔除正确；有效样本不足判定；断连顺延与3次判定；
参考值校验：量程外/偏差>50%强确认拦截；单位切换换算；德/法小数逗号输入解析；
两点校准边界：高低点差<15℃警告；k超出[0.8,1.25]suspect标记；草稿24h续做与过期清理；断点闪退恢复；
前置拦截矩阵：离线/低电量/OTA中/固件过旧/无权限/事务进行中六种状态逐项验证按钮态与引导跳转；
恢复出厂：身份验证失败拦截；下发事务；R01数值回退出厂；M04-R03阈值核对提示；记录归档完整；
对账自愈：人为篡改固件参数→次日对账修复+记录（操作人=系统）；连续3次失败转工单；
多语言与无障碍：7语种向导文案无截断；读屏步骤播报；减弱动效模式；深色模式徽标对比度；
兼容与性能：iOS 13+/Android 7.0+真机；status接口100并发P99≤300ms；采样渲染节流帧率≥55fps。

8. 依赖与风险

项	说明	责任/时点
固件校准协议	calibrate/set、rollback指令格式、Flash参数区、验签实现、回读接口——本模块基石	固件团队M1冻结协议；M2联调（最大联调风险项，预留2周缓冲）
设备能力模型	calibration能力声明（类型/指标/量程/步进/最低固件版本）由M02能力模型扩展	M1能力模型评审纳入
M04 实时数据流	采样窗口依赖实时推送稳定性；异常标记数据剔除联动	M1接口契约；M2联调
M09 OTA	校准最低固件版本引导升级；OTA锁定期间禁止校准事务	M2联调
M06 告警通知	到期提醒经M06渠道分发（P3提示级）；校准后阈值核对提示	M2并行
M01 账号/权限	恢复出厂身份验证；管理员/成员权限角色	M1已交付
M02 权限体系	设备编辑权限判定	M1已交付
参考值可信度	用户参考值不准导致"越校越偏"——向导强提示+异常拦截缓解，仍存在客诉风险	帮助文档（M10 FAQ）明确参考值来源建议；客服话术培训
传感器硬件个体差异	suspect标记率若超预期需反馈供应链/固件滤波调优	运营期监控看板跟踪
低功耗设备约束	电池设备校准期间高频采样增加功耗；固件侧限定校准会话最长时长	固件团队评估；向导提示校准期间耗电

以上为 M07 传感器校准（FR-1601~1606）完整详细需求设计：单点/两点双向导、边缘校准三端一致、下发事务与自动回滚、记录追溯与恢复出厂、有效期管理均已落点；与 M01/M02/M04/M06/M09/M10/M11 文档格式及衔接协议一致（能力模型同源、MQTT复用、权限与身份验证联动），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出其余模块（如 M08 OTA升级、M09 定时任务等）。

M07 传感器校准（对应需求：FR-1601~1606）​

1. 模块概述与设计原则​

1.1 模块范围​

1.2 设计原则​

1.3 用户与前置条件​

2. 页面结构与流程图​

2.1 页面导航结构​

2.2 核心状态机一：设备校准状态（设备×指标维度）​

2.3 核心状态机二：校准下发事务（云端-固件）​

3. 页面级详细需求​

C01 校准状态总览页（FR-1601）​

C02 校准方式选择页​

C03 单点偏移校准向导（FR-1602）​

C04 两点线性校准向导（FR-1603）​

C06 下发与验证页（FR-1604）​

C05 校准记录页（FR-1605）​

4. 通用交互与视觉规范（UI设计输入，FR-1606）​

5. 客户端技术要求（Flutter）​

6. 云端需求（校准服务）​

6.1 接口清单​

6.2 关键策略​

7. 验收标准核对表​

8. 依赖与风险​

M07 传感器校准（对应需求：FR-1601~1606）

1. 模块概述与设计原则

1.1 模块范围

1.2 设计原则

1.3 用户与前置条件

2. 页面结构与流程图

2.1 页面导航结构

2.2 核心状态机一：设备校准状态（设备×指标维度）

2.3 核心状态机二：校准下发事务（云端-固件）

3. 页面级详细需求

C01 校准状态总览页（FR-1601）

C02 校准方式选择页

C03 单点偏移校准向导（FR-1602）

C04 两点线性校准向导（FR-1603）

C06 下发与验证页（FR-1604）

C05 校准记录页（FR-1605）

4. 通用交互与视觉规范（UI设计输入，FR-1606）

5. 客户端技术要求（Flutter）

6. 云端需求（校准服务）

6.1 接口清单

6.2 关键策略

7. 验收标准核对表

8. 依赖与风险