[{"id":"overview","title":"1. 设备组成与工作原理","shots":["status","target","setup"],"body":["本系统由两个硬件组成：一个是安装在咖啡机内部或控制线路附近的“定量萃取芯片”，核心为 ESP32-C3；另一个是带圆角方屏的“辣妈无线遥控器”，核心为 ESP32-S3。定量萃取芯片负责最关键的实时控制链路，包括连接蓝牙秤、读取实时重量、保存目标克重、识别萃取拨杆状态、在达到目标重量时向咖啡机控制电路输出停止萃取信号。辣妈无线遥控器负责用户界面、Wi-Fi 联网、La Marzocco 云端账户、机器状态同步、锅炉和预浸泡设定、萃取曲线显示、反冲洗入口、官方固件检测、系统 OTA 与后台门户。","两者的职责边界非常重要。定量萃取芯片是“闭环控制端”，它必须在辣妈无线遥控器关机、离线、重启或正在升级时仍然能够独立完成定量萃取；辣妈无线遥控器是“显示与配置端”，负责把用户设置写入 C3，并把 C3 和咖啡机状态用更友好的方式呈现出来。正常情况下，蓝牙秤数据先进入 C3，再由 C3 透传给 S3。这样做的目的，是保证停止萃取这一动作不会依赖触屏、Wi-Fi 或云端响应速度。","咖啡机自身状态主要来自两条链路：一条是 La Marzocco 官方云端，用于读取账户下的机器列表、挂载指定机器、读取或设置锅炉、预设、维护统计、反冲洗和官方固件版本；另一条是咖啡机蓝牙，用于更及时地获取机器在线状态和冲煮锅炉实时温度。两条链路并不是互相替代，而是互为补充。云端提供完整控制能力，蓝牙提供更快的现场状态反馈。","在理解故障时也应按这个架构分层判断：如果只有云端机器未加载，定量萃取仍可能正常；如果 C3 和蓝牙秤断开，萃取曲线和自动停杯才会失效；如果 S3 只是黑屏或息屏，后台链路和 C3 控制不应被影响。日常排查时先看屏幕顶部图标，再看后台门户诊断，再看 C3 指示灯和蓝牙秤状态，通常能快速定位问题属于 Wi-Fi、云端、咖啡机蓝牙、C3-S3 通讯还是蓝牙秤连接。"],"notice":"术语约定：本说明书中“定量萃取芯片”指 ESP32-C3 PCBA；“辣妈无线遥控器”指 ESP32-S3 触屏设备。两者可以协同工作，但定量萃取芯片必须具备独立完成按重量停止萃取的能力。"},{"id":"before-use","title":"2. 使用前准备","shots":["setup","status"],"body":["首次使用前，请确认咖啡机已经正确安装定量萃取芯片，并且芯片的输出线路与咖啡机控制电路匹配。对于采用自锁拨杆逻辑的机型，正常流程通常是拨杆向左启动萃取，约 3 秒后拨回，随后由 PCBA 保持萃取通路，最终由 C3 在达到目标克重后停止萃取。若安装或拨杆逻辑不正确，设备看起来可能仍能手动萃取，但自动停杯不会生效。","请准备稳定的 2.4GHz Wi-Fi。ESP32 系列通常只连接 2.4GHz 网络，不建议使用只开启 5GHz 或路由器隔离策略很强的网络。建议把手机、电脑、辣妈无线遥控器放在同一局域网内完成初始配置。若路由器开启 AP 隔离、访客网络隔离或特殊 DNS 劫持，后台门户可能能打开，但云端机器加载、OTA 或时间同步会失败。","请准备 La Marzocco 官方 App 使用的云账户邮箱和密码，并确认官方 App 内已经能够看到咖啡机。S3 并不是凭空发现云机器，它需要使用同一账号请求官方云端机器列表。若官方账号下有多台机器，后续需要在门户中手动选择本机对应的机器，否则会出现状态和控制对象不一致的情况。","蓝牙秤请提前充电并确认能正常开机。若蓝牙秤曾经连接手机 App、手冲 App 或其他设备，建议先在手机端断开连接，再重启蓝牙秤。蓝牙秤同一时间通常只应被一个主机稳定连接；如果手机 App 抢先连接，C3 就无法读取实时重量，也无法在目标克重处发出停止信号。","S3 设备首次配置、OTA、反冲洗和长时间后台设置时建议接入 USB-C 供电。虽然设备可以依靠电池工作，但在写入设置、系统升级或网络复位阶段突然断电，可能导致配置未保存或需要重新配网。若设备处于息屏状态，后台仍会运行；息屏不是关机。"],"table":[["准备项","建议"],["Wi-Fi","使用 2.4GHz，关闭访客隔离，确保能访问互联网。"],["云账户","使用官方 App 可正常看到咖啡机的账号。"],["蓝牙秤","避免被手机 App 占用，必要时重启蓝牙秤。"],["供电","配置、OTA、反冲洗时建议保持 S3 充电。"]]},{"id":"micra-pcba-install","title":"3. Micra 定量萃取 PCBA 无损安装","shots":["pcba-install-1","pcba-install-2","pcba-install-3"],"body":["本章对应 La Marzocco Micra 定量萃取 PCBA 转接板的安装资料。它不是普通的软件设置，而是涉及机器内部线束接入的步骤。安装前请完全断电，确认手部和机器内部干燥，避免工具碰到电路板或锅炉高温区域。没有拆机经验时，建议联系熟悉 Micra 结构的人员协助。","准备工作包括：IRIS4 定量萃取 PCBA 转接板、4pin 转 4pin 信号线、2pin 转 4pin 电源线、BOOKOO 或 Acaia 蓝牙秤，以及已经安装好的 IRIS4 遥控器或 SHOTSTOPPER Companion App。蓝牙秤建议先升级到最新固件，BOOKOO 秤请切换到两点模式，也就是计时模式。","拆开机器后先找到原机黑白色拨杆信号线。拔出该插头后，把机器原来的黑白排线插入转接板靠近 Type-C 的接线桩；转接板下方接入 4pin 转 4pin 信号线；左侧接入 2pin 转 4pin 电源线的 2pin 端。随后把电源线 4pin 端和信号线另一端插回机器侧对应位置。","所有插头都要压紧，确认线束方向无误。通电后打开蓝牙秤，PCBA 与秤连接后板载 LED 会出现状态变化。目标克重可以优先在 IRIS4 遥控器定量萃取页设置，也可以通过 SHOTSTOPPER Companion App 作为备用入口设置。App 下载：Android https://play.google.com/store/apps/details?id=com.icapurro.shotStopperCompanion&hl=cn ，iOS https://apps.apple.com/cn/app/shotstopper-companion/id6743770334 。","一次标准测试应装粉扣上手柄，不建议用空碗和清水模拟。拨杆拨到左侧后，秤会自动清零并计时约 3 秒；3 秒内如果秤发生额外去皮动作，本次自动称重流程会作废。预浸泡开启时，请在预浸泡时间结束后再把拨杆拨回右侧。达到目标克重后，PCBA 会自动停止萃取。","萃取过程中请保持秤面干燥，避免水触发触摸开关。若秤模式设置错误，设备会在萃取状态下最多运行约 50 秒后停止；等待保护流程结束后，把秤切回正确模式再试。萃取完成后建议等待约 3 秒再移走浓缩杯，让秤完成短暂校准。","确认拨杆识别、蓝牙秤连接、目标克重停止和 50 秒保护逻辑都正常后，再把转接板固定在机器内部合适位置。固定时不要压住活动线束，不要贴近高温区域，也不要让外壳复原时夹住线缆。完整图文文章见 https://lm.iris4.com/article/micra-pcba-install 。"],"table":[["检查点","通过标准"],["断电拆机","机器完全断电，线束和工具保持干燥。"],["信号线接入","原机黑白拨杆信号线正确接入转接板。"],["电源与信号","2pin/4pin 线束方向正确并插紧。"],["蓝牙秤模式","BOOKOO 或 Acaia 秤处于适合意式萃取的模式。"],["保护逻辑","目标克重停止、曲线紧急停止和 50 秒保护均能触发。"]],"notice":"PCBA 安装属于硬件接线步骤。任何不确定的插头方向、线束位置或机器状态，都应先停下确认，不要带电反复试插。"},{"id":"language","title":"4. 首次开机与语言选择","shots":["setup"],"body":["全新设备或恢复出厂后，S3 会先进入语言选择界面。当前固件支持中文、英文、德文、西班牙语、日语、葡萄牙语、法语、韩语、阿拉伯语和印地语。上下滑动可以切换语言，选中后点击 OK 按钮确认。为了避免误触，确认区域应限制在 OK 按钮附近，普通滑动不应直接确认语言。","语言选择会影响 S3 屏幕和后台门户。完成选择后，设备进入 Wi-Fi 配置流程。后续如果想换语言，可以进入后台门户的语言设置；如果想回到首次语言选择界面，则需要恢复出厂设置。由于不同语言长度差异较大，屏幕界面会使用较短标题和自适应字号，说明书页面则会使用更完整的翻译。","阿拉伯语属于从右向左书写的语言，但本项目的 S3 小屏为了避免控件镜像导致触控区域混乱，界面布局仍保持与其他语言一致，只对文本内容做本地化。网页版说明书也保持同一布局方向，避免截图和文字说明左右相反，让用户对照屏幕时产生误解。","如果语言选择后发现屏幕仍混杂其他语言，优先检查固件是否为最新版本。早期版本曾存在部分固定文案没有进入翻译表、某些页面回退英文、部分字体缺字导致方框的问题。新版通过统一字库和翻译键值减少这些情况，但用户设备系统字体也会影响网页版说明书的显示效果。"]},{"id":"first-setup","title":"5. 首次联网与后台门户","shots":["setup"],"body":["设备未配置 Wi-Fi 时会启动本地 AP 热点，并在屏幕上显示热点名称、密码和配置地址。请用手机或电脑连接这个热点，再用浏览器打开屏幕显示的地址。常见初始化地址是 192.168.4.1；设备接入家庭网络后，应改用设置页显示的红色局域网 IP 访问门户。","在后台门户中选择家庭 Wi-Fi，输入密码并保存。提交后设备需要断开 AP、切换到 STA、连接路由器、获取 DHCP 地址、启动本地服务并刷新屏幕状态，这个过程可能需要几十秒。请不要在这段时间反复点击保存，也不要过早认为失败。若超过两分钟仍无 IP，再检查密码、路由器兼容性和 2.4GHz 网络。","联网成功后，设置页面会显示红色内网 IP，并提示请在局域网访问该地址进行设定。这个 IP 应位于“密码”和说明文字之间，用户需要记住它，因为之后所有后台功能都通过这个地址进入。若路由器重启或 DHCP 租约变化，IP 可能改变，请以屏幕实时显示为准。","后台门户包括 Wi-Fi、语言、La Marzocco 云账户、机器选择、Logo、配方预设、萃取计时开关、息屏时间、自动升级、固件升级、诊断、说明书等功能。已安装定量萃取芯片的机型，门户中的云端萃取计时应默认强制关闭，避免和 C3 萃取曲线同时弹出两个萃取界面。","如果设备进入 AP 后手机提示密码错误，请先确认不是手机缓存了旧密码。网络复位应清理 NVS、OTA 数据和存储中与网络相关的缓存，避免设备使用旧 AP 配置。若仍无法加入 AP，请使用电脑或另一部手机测试，排除手机系统自动切换蜂窝网络、随机 MAC 或保存旧热点配置的影响。"],"notice":"首次联网阶段最容易误判。请以屏幕是否显示新的局域网 IP 为准，不要仅凭手机是否还连着 AP 判断成功与否。"},{"id":"cloud","title":"6. 绑定 La Marzocco 云端咖啡机","shots":["setup","status"],"body":["S3 要控制咖啡机，必须先在后台门户保存 La Marzocco 官方云账户。输入邮箱和密码后点击保存，设备会在后台完成验证、创建会话、请求机器列表、保存机器选择和刷新前端状态。这个流程涉及外网访问，因此速度取决于路由器、DNS、官方云端响应和设备内存状态。","如果账户下只有一台咖啡机，设备可以自动挂载；如果账户下有多台机器，必须在列表中选择当前安装的机器。绑定成功后，机器状态页、锅炉页、预设页、官方固件页和反冲洗页才会显示真实数据。若门户显示机器列表为 1、挂载为是，但 S3 前端仍为空，通常是前端状态同步或云端会话刷新没有完成，需要等待或重启 S3。","云端状态中“等待验证”表示账号保存后会话仍未完全可用；“机器列表加载中”表示后台正在请求机器列表；“机器在线未知”表示云端尚未返回可靠在线状态或咖啡机本身处于长期待机。不要在这些中间状态频繁重复提交账号，否则容易造成旧请求和新请求互相覆盖。","咖啡机蓝牙和云端挂载是两件事。S3 可能已经连上咖啡机蓝牙并能读取实时温度，但云端机器尚未挂载；也可能云端挂载成功，但咖啡机蓝牙暂时掉线。最佳状态是顶部同时显示 Wi-Fi、机器挂载图标，并且锅炉、机器状态、预设、维护统计都能正常显示。","若长时间加载失败，请先在官方 App 中确认账号和机器状态，再检查路由器是否允许设备访问互联网。某些家庭网络会拦截国外域名、强制 DNS、或对低功耗设备的长连接不友好。此时可尝试换手机热点测试，如果手机热点正常，说明根因更可能在家庭网络环境而非设备本身。"]},{"id":"icons","title":"7. 主界面图标与状态判断","shots":["status"],"body":["S3 顶部图标是快速判断系统状态的入口。Wi-Fi 图标表示设备已接入局域网；机器图标表示 La Marzocco 云端机器已经挂载且状态可用；电池图标显示 S3 电量；当检测到定量萃取芯片并完成订阅时，萃取定量页面会自动出现在主页面队列中。","如果咖啡机图标消失，锅炉和机器状态可能显示空值，但这不必然代表 C3 不工作。定量萃取链路主要依赖 C3 和蓝牙秤。用户应区分“咖啡机云端状态不可用”和“定量萃取不可用”：前者影响远程控制和显示，后者才影响自动停杯。","机器状态页面用于开启或待机咖啡机。当前提示逻辑为“点击右侧开启，点击左侧待机”。蒸汽锅炉页面用于在关闭、1、2、3 档之间循环，提示为左右点击设定锅炉档位。冲煮锅炉页面显示设定温度和咖啡机蓝牙获取的实时温度，实时温度单位应显示为 ℃。","若页面文字出现空方框、标题大小不一、同一行文字高低不平，通常和固件字库或当前语言翻译键有关。当前固件已经引入更完整的字体策略，但说明书截图仍以采集时的设备状态为准。如果用户看到的实机界面与说明书截图略有差异，应以设备当前固件为准。","蓝牙秤图标用于判断 C3 是否已经接管并连接蓝牙秤。图标亮起或显示已连接时，表示实时重量会进入定量萃取逻辑；图标消失或提示未连接时，可以先检查秤是否被手机 App 占用，再进入萃取定量页长按 3 秒手动启用扫描。","自动待机图标或息屏状态只表示屏幕进入省电显示，Wi-Fi、BLE、云端状态和 C3 定量控制仍会继续运行。萃取、OTA、反冲洗和错误告警过程中，设备应保持亮屏或自动唤醒。"],"table":[["图标或页面","含义","异常时检查"],["Wi-Fi 图标","S3 已接入局域网","路由器、密码、网络复位"],["机器图标","云端机器已挂载","云账号、机器列表、官方 App"],["萃取定量页","C3 已订阅","C3 供电、距离、BLE 状态"],["电池图标","S3 电量","OTA 或长时间使用时保持充电"],["蓝牙秤图标","C3 已连接秤并可读取重量","秤模式、手机占用、C3 扫描开关"],["自动待机","屏幕按设定时间息屏","0/30/60/120 分钟设置、PWR 短按"]]},{"id":"pages","title":"8. 六个控制页面说明","shots":["status","coffee","steam","target","infuse","pause"],"body":["主界面通过左右滑动切换页面。常规页面包括机器状态、冲煮锅炉、蒸汽锅炉、预浸泡开启、预浸泡关闭；当 S3 检测到 C3 并完成订阅后，会自动加入萃取定量页面。页面切换应像设置页和预设页一样顺畅，若滑动延迟很大，通常是后台云请求、BLE 扫描或 UI 任务被阻塞。","所有数值调整页面都应采用大触控区域：左半屏降低，右半屏提高，高度覆盖数值操作区域。这样用户不需要用手指精确点一个很小的按钮，降低误触概率。滑动手势只用于换页，不应触发数值变化；这对预浸泡尤其重要，因为加载关闭预浸泡预设后，滑动误改会导致云端重新覆盖为非零值。","冲煮锅炉页面显示设定温度和实时温度。设定值应居中，单位吸附在数值右侧，单位字号小于主数值并使用紫色。实时温度来自咖啡机蓝牙特征值，连接成功后自动显示。若实时温度长期不更新，检查咖啡机蓝牙是否在线，而不是只看云端状态。","蒸汽锅炉页面可在关闭、1、2、3 之间循环。中文界面显示“关闭”，其他语言使用各自语言的短词。英文、德文、西班牙语等标题较长时会自动缩写，避免标题伸出屏幕。页面说明文字应铺满可用宽度后再换行，不能被限制在很窄的列里。","预浸泡开启和预浸泡关闭同时为 0 时表示关闭预浸泡，界面应显示 OFF 或相应语言的关闭状态。加载预设后，如果云端稍后又覆盖回旧值，通常说明本地显示变化没有同步提交到云端，或滑动误触改动了数值。正确逻辑是加载关闭预浸泡预设时同时提交开启 0 和关闭 0。"]},{"id":"shot-goal","title":"9. 定量萃取目标设置","shots":["target","scale"],"body":["萃取定量页面是 C3 与 S3 联动的核心页面。C3 当前暴露目标克重 BLE 特征，S3 订阅后读取并显示当前值。用户在 S3 上点击左半屏或右半屏可按 0.5g 调整目标克重，长按可快速连续增加或减少。数值需要显示一位小数，例如 36.5g，而不是只显示整数。","目标克重修改后会写入 C3 并持久化。手机第三方 App 修改目标克重时，S3 也应能读取到变化并刷新显示。目标克重属于配置值，应允许第三方读取和写入；安全鉴权不应把目标克重完全锁死，否则会破坏原本手机 App 设置目标重量的使用场景。","C3 与 S3 正常通讯时，S3 会自动显示萃取定量页面。若页面消失，说明 S3 未检测到 C3 或订阅失败。此时应检查 C3 供电、距离、BLE 状态以及 S3 是否处于 OTA、重启或内存紧张状态。不要把云端咖啡机未加载和 C3 未连接混为一谈。","在蓝牙秤已经连接 C3 的情况下，C3 仍应同时允许 S3 和手机 App 对目标克重进行读取和写入。历史迭代中曾因写入鉴权过强导致手机 App 难以连接或无法修改目标克重，这类改动后续应避免反复引入。","如果用户实际萃取结果与目标克重存在偏差，需要区分停止瞬间重量、蓝牙秤最终稳定重量和滴液后的杯中重量。Bookoo 两点模式下，S3 曲线更接近停止瞬间值，而秤面最终显示可能包含后续滴液重量。三点模式通常更稳定，但需要等待秤自动清零。用户可根据机器、秤模式和豆子流速微调目标克重。"]},{"id":"scale-manual","title":"10. 蓝牙秤手动设置","shots":["scale"],"body":["蓝牙秤手动设置用于解决一个非常实际的场景：蓝牙秤有时会被临时拿去连接手机 App 做手冲或称重，但只要 C3 主动扫描，蓝牙秤一开机就可能被 C3 抢先连接。为了让用户能临时把秤交给手机使用，S3 在萃取定量页隐藏了一个长按入口。","进入方式是切换到萃取定量页面，长按 3 秒。若蓝牙秤已配对，界面显示“蓝牙秤已配对”，按钮为“断开蓝牙秤”；点击后 C3 应立刻断开秤并关闭主动扫描，C3 指示灯也应反映状态变化。若蓝牙秤功能已关闭，界面显示“蓝牙秤功能已关闭”，按钮为“启用蓝牙秤”；点击后恢复扫描和配对。","启用或断开后都建议重启蓝牙秤。原因是很多蓝牙秤在已连接、断开、自动模式切换后，广播状态不会立即回到最干净的初始状态。重启秤能让 C3 更快重新发现并连接，也能减少手机 App 和 C3 同时争抢连接的情况。","手动设置弹窗可以通过任意滑动退出，也可以点击按钮以外区域退出。按钮尺寸应足够大，避免用户明明点到按钮却没有触发。界面标题、说明和按钮之间要保持足够间距，不能因为多语言文字变长而重叠。","如果 S3 显示蓝牙秤已配对，但 C3 实际仍处于断开状态，通常是 S3 使用了旧的状态缓存。此时应以 C3 指示灯和实际重量数据为准，并等待下一次 C3 状态上报刷新。后续逻辑应避免只根据上一次 paired 字段判断真实连接状态。"]},{"id":"standard-shot","title":"11. 一次标准萃取流程","shots":["target","status"],"body":["标准流程从准备咖啡机和蓝牙秤开始。先确认咖啡机已完成预热，冲煮锅炉温度稳定；确认 S3 顶部 Wi-Fi 和机器图标状态正常；确认 C3 已连接蓝牙秤，萃取定量页能够显示目标克重；确认杯子放在秤上，并且秤处于适合意式萃取的模式。","在三点模式下，放上杯子后通常需要等待蓝牙秤自动清零，然后再拨动萃取拨杆。这种方式稳定性较好，但等待清零会消耗时间。在两点模式下，C3 可在拨杆触发瞬间发送清零和计时逻辑，操作更快，但如果 3 秒内已经滴液，部分秤会进入特殊扫描或自动计时状态，导致重量上报行为变化。","对于自锁拨杆机型，用户拨动拨杆启动萃取后，约 3 秒需要把拨杆拨回。此后咖啡机是否继续运行，不是靠拨杆机械位置，而是靠 PCBA 控制电路保持。C3 读取实时重量，当预测或实际达到目标重量时发出停止信号。若 C3 未连秤，咖啡机启停应完全回到人工拨杆控制。","萃取开始后，S3 会弹出萃取曲线。曲线出现不应依赖云端机器是否已加载，因为定量萃取数据来自 C3。若没有联网或云端未挂载，但 C3 与蓝牙秤正常，曲线仍应显示。反之，云端加载成功并不能替代蓝牙秤连接。","萃取结束后，曲线保留约 15 秒自动退出。如果在这 15 秒内开始第二杯，应立即清屏并开始显示新曲线，而不是继续叠加上一杯数据。若第二杯曲线从屏幕中间开始、贴着顶部生成或延迟明显，说明新旧 shot 状态清理不彻底或开始事件识别太晚。"]},{"id":"curve","title":"12. 萃取曲线界面","shots":["target"],"body":["萃取曲线界面用于把一次萃取过程用更直观的方式呈现出来。顶部保留 La Marzocco 标识；中部显示流速、用时、萃取日期和时间；下方显示实时克重和目标克重；坐标区域同时绘制重量曲线和流速曲线。X 轴代表时间，从左向右推进；Y 轴代表重量，从下向上增长。","曲线的动态变化应平滑展开，而不是前半段压缩在左侧、结束后突然拉满。实时绘制时可以使用当前预计窗口，结束后再按总用时重新归一化，但视觉上要避免突然跳变。箭头用于显示当前时间和当前重量位置，X 轴箭头朝右，Y 轴箭头朝上，结束后停留在轴顶端。","萃取中任意滑动曲线界面，会向 C3 发送紧急停止命令。成功后显示“已紧急停止”，颜色为紫红色，并尽量使用统一字体，避免大小不一。萃取已经结束后再滑动，只能关闭曲线界面，不能再显示“已紧急停止”，也不能再次弹出一张新的曲线。","若蓝牙秤未连接但检测到萃取状态，曲线中央应持续显示“蓝牙秤未连接”，而不是只闪现一次。这个提示应基于可靠的 C3 秤连接状态和实时重量数据判断，不能因为瞬间状态包丢失就误报。反冲洗页面打开或反冲洗流程进行中时，应屏蔽萃取曲线弹窗。","BOOT 短按用于调出或退出最近一次曲线；BOOT 长按 2 秒以上用于动态复现最近一次萃取。回放时不仅曲线要变化，实时克重、流速、用时也要同步变化。回放结束后应停留足够时间再自动退出，中途任意滑动可以退出。"]},{"id":"presets","title":"13. 配方预设与预浸泡","shots":["presets","infuse","pause"],"body":["配方预设用于保存常用温度和预浸泡方案。默认预设 1 应为“关闭预浸泡”、冲煮温度 93.0、预浸泡开启 0、预浸泡关闭 0。加载该预设后，预浸泡开启和关闭页面都应显示 OFF，并且这两个 0 值必须同步提交到云端，不能只在本地临时显示。","预浸泡开启和关闭同时为 0 时表示关闭预浸泡。若加载预设几秒后又被云端旧值覆盖，说明本地提交没有真正生效，或者用户滑动页面时误触了数值调整。当前触控逻辑应屏蔽滑动造成的数值误调整，只有明确点击左半屏或右半屏才修改数值。","预设页的加载和保存按钮要与上方文字保持间距，不能叠在一起。多语言环境下按钮文字长度不同，布局必须按最长语言考虑。说明书截图中如果某个语言显示略有缩写，是为了适配 240×284 的小屏宽度。","预设页向下滑动进入官方固件页面。这个手势应与设置页上滑进入反冲洗一样灵敏，不应出现需要滑动多次才进入的情况。若进入页面明显卡顿，通常是每次打开都重新发起云端请求，应改为缓存每日结果，只在必要时刷新。"]},{"id":"firmware-page","title":"14. 官方固件页面","shots":["firmware"],"body":["官方固件页面用于检测 La Marzocco 咖啡机和网关官方固件版本，不是 S3/C3 自身 OTA 页面。页面入口在预设页下滑。进入后应显示本地咖啡机或网关版本、云端版本以及当前状态。若本地与云端一致，状态显示“当前无需更新”；若存在代差，才显示升级按钮。","页面副标题固定为“仅用于检测并手动升级 / Lamarzocco 咖啡机固件版本”。这句话的作用是避免用户把它和 S3/C3 的系统 OTA 混淆。S3/C3 固件升级在后台门户的固件升级栏目和自动 OTA 中完成；咖啡机官方固件升级则是云端对咖啡机自身发起的流程。","官方固件状态不应在还未请求完成时先显示“当前无需更新”。正确流程是先显示正在加载，拿到云端比对结果后再显示最终状态。若云端返回英文 updated，应按系统语言翻译为对应状态，而不是直接显示英文。","升级按钮需要长按 3 秒触发并显示进度，避免误触。若云端没有提供新版本，按钮不显示。升级期间请确保咖啡机通电、网络稳定、S3 电量充足，并避免同时执行网络复位或系统 OTA。"]},{"id":"backflush","title":"15. 反冲洗与维护统计","shots":["maintenance"],"body":["反冲洗页面入口在设置页上滑。页面标题为“反冲洗”，内容显示制作总数、冲洗总数，并提供反冲洗启动按钮。制作总数前使用咖啡杯图标，冲洗总数前使用水滴图标。若图标显示为空框，说明当前字体或图标资源未覆盖，需要使用位图或已存在图标替代。","页面提示应清楚说明“启动前请确保拨杆关闭”。长按底部反冲洗按钮 3 秒后，按钮本身通过左右变色显示进度，不再使用额外进度条，避免进度条与说明文字重叠。按钮文字应为白色，因为按钮背景多数时间接近黑色。","La Marzocco 官方 App 的反冲洗逻辑并不是简单发一个清洗命令就立即开始，而是先进入一个 15 秒倒计时窗口，提示用户在 15 秒内拨动拨杆。云端检测到拨杆信号后，咖啡机进入反冲洗模式。S3 应复刻这个流程：长按后显示 15 秒倒计时和拨杆提示，检测到成功后显示清洗中，并用动态省略号表示流程仍在进行。","如果用户在第一次倒计时前半段拨杆没有生效，而第二次倒计时才生效，说明 S3 本地倒计时与云端真实反冲洗窗口没有对齐。正确做法是以云端确认或机器状态变化为准，避免本地先显示失败。反冲洗期间即使 S3 没有及时检测到拨杆信号，只要咖啡机已进入反冲洗，就不应回退到“未检测到拨杆信号”。","反冲洗页面的维护统计不需要每次打开都实时请求云端。若当天已经加载成功，应优先显示缓存数据，减少卡顿和崩溃风险。只有用户手动刷新、日期变化或云端账号变化时才重新请求。反冲洗进行中应屏蔽萃取曲线弹窗，避免蓝牙秤开机造成界面冲突。"]},{"id":"portal","title":"16. 后台门户功能","shots":["setup"],"body":["后台门户是 S3 的完整设置中心。用户通过同一局域网访问屏幕显示的 IP，就能进入门户。门户必须保持多语言一致性，不能只有中文和英文可用，其他语言仍显示英文或中文。语言切换后，设置说明、按钮、错误提示、固件升级结果、自动升级说明、线刷入口都应同步翻译。","Wi-Fi 页面用于保存网络凭据。云端页面用于保存 La Marzocco 账户、加载机器列表并选择机器。配方页面用于编辑预设。Logo 页面用于上传或恢复品牌图。固件升级页面用于检查 S3/C3 版本和执行 OTA。说明书按钮应链接到内置说明书页面。","息屏设置提供 0、30、60、120 分钟档位，默认 30 分钟。0 表示常亮。该设置只影响屏幕和背光，不影响 C3 控制、咖啡机状态同步、云端心跳或后台 OTA 检查。PWR 短按也属于同一套息屏逻辑。","自动升级默认开启。提示文案为“本功能开启后请确保咖啡机通电并至少处于待机状态，同时确保小方块遥控器处于充电状态”。后台门户应允许用户关闭自动升级，但不建议普通用户关闭，因为 OTA 是远程召回和修复的重要通道。","诊断页面应显示 Wi-Fi、云端、机器挂载、咖啡机蓝牙、C3 连接、C3 版本、S3 版本等信息。若出现“云端状态等待验证、机器列表 0、挂载否”等问题，诊断页比主屏更适合判断根因。","自动待机设置提供 0、30、60、120 分钟档位，默认 30 分钟。0 表示常亮；其他档位只关闭屏幕和背光，不会停止 C3 定量萃取、蓝牙秤连接、云端同步或自动 OTA 检查。"]},{"id":"sleep","title":"17. 自动待机、实体按钮与电源管理","shots":["setup"],"body":["息屏只是屏幕管理，不是整机断电。待机状态无操作达到设定时间后，S3 关闭屏幕和背光，但 Wi-Fi、BLE、云端状态、C3 通讯和后台任务仍可继续运行。用户也可以短按 PWR 立即息屏；息屏后触摸屏幕或再次短按 PWR 唤醒。","触摸唤醒时，第一下触摸只用于唤醒，不触发该位置下的按钮。这一点非常重要，否则用户在黑屏时随手点一下，可能直接触发数值调整、反冲洗或网络复位。长按 PWR 保持原有电源逻辑，不应被短按息屏功能覆盖。","并非所有状态都允许息屏。萃取中、OTA 安装中、反冲洗确认中、错误告警中、网络复位确认中，系统应保持亮屏或自动亮屏。后台 OTA 检查和下载可以静默进行，但真正开始写入、失败或即将重启时必须亮屏提示用户。","如果用户反馈关机后无法开机、插电后黑屏只有背光、线刷后必须通过门户恢复出厂才能点亮屏幕，需要重点检查屏幕电源管理、背光状态、语言选择流程和首次启动状态机。息屏逻辑绝不能把设备带入一种 UI 不绘制但后台仍运行的假死状态。","自动待机触发后，第一次触摸只负责唤醒屏幕，不会触发被触摸位置的按钮。这样可以避免黑屏状态下误改目标克重、误进反冲洗或误触网络复位。"]},{"id":"ota","title":"18. S3/C3 OTA、自动升级与浏览器线刷","shots":["setup"],"body":["S3/C3 系统 OTA 与咖啡机官方固件升级是两套不同系统。S3/C3 OTA 从 ota.iris4.com 获取 manifest 和加密固件包，S3 负责自升级，也负责把 Wi-Fi 凭据和升级指令传给 C3。C3 联网后应自行下载升级包、写入 OTA 分区并重启生效。","自动 OTA 每天只允许执行一次。凌晨 02:00 左右，在设备已联网并完成时间同步后，先静默检查 manifest；只有确实存在 S3 或 C3 更新时，才弹出 OTA 界面并进入维护模式。若 02:00-03:00 内检查失败，可以每 10 分钟重试。没有更新时不应显示升级完成界面，否则用户会误以为夜间发生了升级。","升级状态必须细分：S3 有更新 C3 无更新、C3 有更新 S3 无更新、两者都有更新、两者都无更新；结果也要分别显示成功或失败。C3 升级成功后，S3 应退出维护模式并强制刷新 C3 BLE 连接，避免 GATT 状态卡死造成升级后断连。","浏览器线刷用于 OTA 失败后的售后维护。用户使用 Chrome 或 Edge，通过 TYPE-C 数据线连接已启用加密固件的 S3，输入管理员提供的一次性激活码后刷机。线刷页面应显示当前最新固件版本和更新日期，刷机完成后尝试自动重启；若自动重启失败，应明确提示用户手动重启。","加密固件不能直接当作公开下载资源。后台通过激活码、MAC 黑名单、一次性授权和服务端记录进行控制。线刷资源也要随 OTA 版本同步更新并做 CDN 预热，避免用户刷完仍是旧版本。"]},{"id":"network-reset","title":"19. 网络复位与恢复出厂","shots":["setup"],"body":["已联网的设置页支持网络复位。用户长按设置页 3 秒进入网络复位界面，再继续长按 8 秒确认。确认过程中应显示稳定进度，不应频闪，标题和说明文字要保持同一字号和基线。初始化 AP 模式下不显示长按 3 秒进入网络复位的提示，也不启用该功能。","网络复位至少应清理三类内容：NVS 中的 Wi-Fi 和云端配置、OTA data 中可能导致启动分区混乱的状态、storage 中可能缓存的门户或网络状态。若只清理 Wi-Fi SSID 和密码，可能出现 AP 密码缓存、手机提示密码错误、设备重启后仍读取旧配置等问题。","复位完成后设备应回到初始化设置界面或新密码设置界面，而不是停留黑屏、无限重启或仍显示旧 IP。若恢复出厂后进入无限重启，需要优先检查首次启动状态机、语言选择状态、云端任务启动时序和 LVGL 内存，而不是简单禁止 BLE 扫描，因为禁止扫描会让 C3 页面和咖啡机 BLE 永远无法自动启动。","用户执行网络复位前应了解：Wi-Fi、云账户、机器选择、部分本地缓存会被清除。C3 的目标克重和蓝牙秤配对状态是否清除取决于 C3 自身存储逻辑，通常不应因为 S3 网络复位而破坏 C3 独立定量能力。"]},{"id":"troubleshooting","title":"20. 常见问题排查","shots":["status","scale","maintenance"],"body":["无法进入后台门户时，先确认手机或电脑与 S3 在同一局域网。初始化 AP 模式下访问 192.168.4.1；联网后访问设置页红色 IP。若手机提示网络不可用并自动切换蜂窝网络，请关闭自动切换或用电脑访问。若门户一打开就导致设备重启，优先检查 HTTPD 任务栈、PSRAM 分配和门户页面生成内存峰值。","云端机器加载失败时，先看官方 App 是否能看到机器，再看 S3 门户是否保存了正确账号。若提示 Machine lookup failed、Cloud registration request failed、Machine list is loading in the background，通常涉及云端会话、机器选择或后台加载时序。等待后台完成比反复点击更有效。","C3 与 S3 断连时，检查两者距离、C3 是否正在 OTA、S3 是否处于维护模式、BLE 扫描是否被错误暂停。手动升级时，S3 必须能通过 BLE 给 C3 传 Wi-Fi 凭据和升级指令；不能为了减少干扰而直接断开 C3 BLE，否则升级指令本身也无法送达。","蓝牙秤连接慢时，先确认秤没有被手机 App 占用，再确认 C3 扫描功能开启。Bookoo 两点模式和三点模式有不同取舍：两点模式启动快但可能受早期滴液和自动计时影响；三点模式更稳定但需要等待自动清零。若最终杯重与 S3 曲线不同，要区分停止瞬间值与滴液后稳定值。","萃取曲线没有弹出时，不要只看云端机器是否加载。曲线主要依赖 C3 的萃取状态和重量数据。若 C3 正常连秤但 S3 不弹曲线，检查 C3-S3 订阅、状态包、overlay 过滤条件以及是否被反冲洗页面屏蔽。","页面出现方框、标点缺失或同一行文字高低不一，通常是字库覆盖不足或语言回退错误。当前固件已尝试通过更完整的开源字体和统一字库解决，但如果用户设备仍显示异常，建议升级到最新固件并重新加载说明书截图。"],"table":[["现象","优先检查"],["云端状态等待验证","账号会话、网络、官方 App 可见性"],["锅炉页面空值","云端挂载、咖啡机 BLE、前端状态同步"],["萃取定量页消失","C3 供电、BLE 订阅、S3 是否维护状态"],["曲线误报蓝牙秤未连接","C3 秤连接状态、状态包缓存、overlay 条件"],["线刷后黑屏","自动重启、背光状态、首次启动状态机"]]},{"id":"safety","title":"21. 安全注意事项与日常维护","shots":["status"],"body":["定量萃取芯片参与咖啡机控制电路，安装和维护应由熟悉咖啡机电气结构的人完成。首次安装后，应在低风险状态下测试拨杆启动、3 秒拨回、自动保持、达到目标重量停止、手动介入等关键动作，确认逻辑可靠后再投入日常使用。","萃取过程中如果出现异常，不要只依赖 S3 触屏。优先使用咖啡机原始拨杆、电源或其他硬件方式人工介入。S3 的紧急停止是辅助功能，不能替代机器本身的安全操作。若 C3 未连接蓝牙秤，自动停杯不应被视为可用。","OTA、线刷、网络复位、反冲洗启动前保持设备供电稳定。不要在写入固件或清理配置时断电。客户线刷时应使用数据线而不是只能充电的 Type-C 线，并使用 Chrome 或 Edge 浏览器。","日常使用建议每天第一次开机后等待蓝牙秤、C3、S3 和咖啡机状态都稳定，再开始第一杯。长时间不用时可以长按 PWR 关机；插电关机状态下默认只充电，需要长按 PWR 才开机。若设备长期待机导致云端掉线，先尝试在门户刷新状态或重启 S3。","本说明书按当前固件和实际迭代经验编写。由于 La Marzocco 云端接口、咖啡机官方固件、蓝牙秤协议和路由器环境都可能变化，若实际界面或行为与说明书不同，请优先以设备当前固件、后台诊断和官方 App 状态为准。"]},{"id":"acceptance","title":"22. 安装后验收、交付与记录","shots":["status","target","setup"],"body":["安装完成后不要只看屏幕能否点亮，应按完整链路做一次验收。第一步确认 S3 能正常开机、语言选择能正常进入、触摸滑动和 OK 按钮响应准确；第二步确认能够进入 AP 配网，手机或电脑能连接热点，保存家庭 Wi-Fi 后能在合理时间内获得局域网 IP；第三步确认后台门户能打开，语言切换、说明书入口、固件版本显示、息屏设置和自动升级开关都能正常显示。","云端验收应确认 La Marzocco 账号保存后能加载机器列表，并且选择机器后 S3 主界面可以显示机器状态、冲煮锅炉、蒸汽锅炉、预设、官方固件和反冲洗页面。若官方 App 中有多台机器，交付时要把已绑定机器的名称或蓝牙串号记录下来，避免用户后续换机或重置后选错设备。若云端加载较慢，应向用户说明首次验证可能需要等待后台完成，不要连续快速点击保存。","定量萃取验收应至少做三组测试：第一组只验证 C3 与蓝牙秤连接，观察 S3 萃取定量页是否自动出现、目标克重是否可读写；第二组不出咖啡，只用手按压蓝牙秤模拟重量达到目标，确认 C3 能触发停止输出；第三组做真实萃取，记录目标克重、停止瞬间 S3 曲线值、蓝牙秤最终显示值和杯中滴液后的稳定值。三组数据能帮助判断偏差来自停止预测、秤模式、滴液还是机械通路。","反冲洗验收应确认设置页上滑能顺畅进入反冲洗，维护统计可以显示或使用缓存显示，长按按钮 3 秒后出现 15 秒拨杆提示。测试时应确保拨杆初始关闭，在倒计时窗口内拨动拨杆，观察咖啡机是否进入官方反冲洗流程。若咖啡机已经清洗中，S3 不应错误显示未检测到拨杆信号，也不应在反冲洗期间弹出萃取曲线。","OTA 验收分为手动检查和自动检查。手动检查时门户应显示当前 S3 版本、在线 S3 版本、当前 C3 版本、在线 C3 版本，并能正确判断已是最新或建议更新。自动检查不应在无更新时显示升级完成。若 C3 升级成功，S3 应刷新 C3 连接状态；若 S3 升级成功，设备重启后设置页版本号应更新。线刷验收则应确认页面显示最新版本和更新日期，刷机完成后设备能自动或手动重启进入正常界面。","交付给用户时建议明确说明三件事：第一，S3 是无线遥控和显示终端，C3 才是定量萃取控制核心，所以 S3 关机不等于定量功能失效；第二，蓝牙秤如果要给手机 App 使用，需要先在 S3 蓝牙秤设置里断开或关闭扫描；第三，任何升级、网络复位、反冲洗操作都应保持咖啡机通电、S3 充电，并等待页面流程结束。把这些说明讲清楚，能减少大多数售后误判。","建议售后交付时同时记录用户邮箱、绑定机器、安装日期、当前 S3 和 C3 版本、蓝牙秤型号、默认目标克重、是否开启自动升级以及最后一次真实萃取测试结果。后续如果用户反馈断连、停杯偏差、云端加载慢或线刷黑屏，完整记录能帮助快速复现环境，避免每次都从零开始排查。"],"table":[["验收项目","通过标准"],["开机与触摸","语言选择、滑动、OK、PWR、BOOT 均正常。"],["联网与门户","可获取局域网 IP，门户各栏目可访问。"],["云端挂载","机器列表、锅炉、预设、维护页可加载。"],["C3 与蓝牙秤","萃取定量页出现，目标克重可读写。"],["真实萃取","达到目标附近自动停止，曲线记录完整。"],["反冲洗","15 秒拨杆窗口与咖啡机实际流程一致。"],["OTA 与线刷","版本判断准确，升级后版本真实变化。"]]}]