蓝牙调试助手开发（02）：需求导入——这篇我们跳过"新建空白工程"的兴奋感，直接聊一个大多数人都容易偷懒的环节。别急着写代码，先想清楚这个App到底给谁用、要解决什么。作为系列续篇，上一篇我们把项目全景和基础环境跑通了，这篇如果需求导入做得扎实，后面的代码几乎是被需求推着走；要是这一步划水，返工成本比写代码还高。
开门见山说个核心判断：蓝牙调试助手不是普通App。它不会上架应用商店被大众拿来扫一扫，它是给开发者、硬件工程师、测试员、产线人员和现场维修师傅用的"手术刀"。这个定位一旦确认，后面所有功能取舍、界面设计、日志格式全都会被它带着走。
1. 调试工具不是普通App：需求导入前先确认它到底为谁而做
1.1 调试助手的真实用户画像
做任何产品，第一步都是搞清楚用户是谁。蓝牙调试助手的用户不是"手机用户"，而是"被设备折腾的人"。具体分三类：
- 嵌入式工程师：正在调试传感器模块、电机控制器、穿戴设备主板。他们要反复发指令、看返回数据，找协议栈里的Bug。对他们来说，界面上能不能显示原始hex报文，比按钮好不好看重要一百倍。
- 测试人员：在产线上抽检蓝牙模块，或做兼容性测试。他们要批量连接设备、记录连接成功率、确认不同手机上信号表现是否一致。这类人需要的是"信息密度高、能导出记录"。
- 现场维修技术人员：拎着手机去修一个蓝牙控制的设备，比如泵站控制器、智能门锁。他们要快速连上目标设备，发一条标准指令，看设备是否正常应答。这类用户讨厌繁琐流程，喜欢"扫到就能连，连上就能发"。
这三种人的共同点是：他们不需要引导教学，而是需要快速、精确、完整的底层数据。
我曾经接过一个需求，对方开口就说"做个一键配对、扫码连接的蓝牙工具"，听起来很用户友好。但细问之后发现，他要的是给自家产线员工用的检测工具，设备有固定MAC前缀，员工需要批量验证。最后我们做的是一打开就自动按前缀过滤、微微微延迟高亮异常设备的面板。如果按最初"扫码连接"的思路做，员工每次都要掏出手机扫码，测试效率直接下降一半。需求导入的第一件事，不是列功能，是列清楚用户的双手在做什么、眼睛在看什么。
1.2 用户故事驱动需求取舍
用户画像定下来后，用"用户故事"来筛需求非常有效。每个功能都写成一个三要素句子：
- 角色：谁遇到这个问题
- 需求：希望App做什么
- 收益：这能帮他解决什么
例如：
- "作为嵌入式工程师，我希望查看特征值完整UUID，以便在固件代码里定位对应的服务定义。"
- "作为产线测试员，我希望扫描结果按信号强度排列，以便快速锁定离工位最近的那台模块。"
- "作为现场维修工，我希望连接失败时能看到错误码，以便判断是天线问题还是配对冲突。"
把这些故事铺开，你会发现很多"想当然的功能"根本站不住脚。举个例子，"深色模式"在调试工具场景里其实很重要，因为野外维修、产线环境常遇强光，但"新手引导动画"就没必要——真正的用户一看界面就知道怎么用。需求导入就是做减法：先写出理想中的完整功能清单，然后用用户故事逐条验证，没有故事支撑的一律砍掉。
2. 从典型工作流倒推功能清单：需求不是拍脑袋堆出来的
2.1 核心工作流拆解
蓝牙调试助手的核心价值，其实是帮用户走完一条完整的调试链路。我把它总结成七个步骤：
- 发现问题，比如"设备为什么收不到数据"。
- 打开App，扫描周围的蓝牙设备。
- 锁定目标设备，建立连接。
- 浏览设备的服务与特征值，找到要读写的那一个。
- 写入测试数据，或订阅通知，观察实时交互。
- 从交互结果判断问题原因，比如设备没返回应答应答、报文格式错误。
- 把会话记录保存下来，做后续分析或交给同事。
按这条链路倒推功能，比对着竞品抄清单更靠谱。扫描对应的是"灵活过滤与排序"，连接对应的是"连接状态可见与稳定重连"，浏览服务对应的是"GATT树完整呈现"，读写对应的是"hex/ASCII双模式输入与发送"，而整个过程的每一步，都应该落在日志里。
我们第一版规划了这样一张需求卡片表：
| 需求编号 | 功能点 | 直接场景 | 验收标准 |
|---|---|---|---|
| R01 | 扫描与过滤 | 在满屋子设备里找到目标模块 | 支持按名称模糊搜索、按MAC精确过滤，扫描结果1秒内展示 |
| R02 | 连接管理 | 连上设备并保持稳定会话 | 点击设备后2秒内发起连接，失败提示具体错误码分类 |
| R03 | 服务特征浏览 | 查看GATT服务层级并定位操作对象 | 正确解析所有Primary Service、Characteristic、Descriptor，支持复制UUID |
| R04 | 数据收发 | 发出测试指令并观察响应 | 支持ASCII和hex两种模式，发送历史保留可回放 |
| R05 | 通知监听 | 实时观察设备主动上报的数据 | 高频通知不丢包，界面滚动不卡死，方向标记清晰 |
| R06 | 会话日志 | 保存现场证据并导出 | 每条记录有时间戳、收发方向、耗时，导出文件格式可读 |
这套表格是需求导入阶段的核心产物。到开发阶段，每个需求卡片都有验收标准，测试再做一遍就形成了用例，不会出现"开发做完了但不知道算不算完成"的尴尬。工作流倒推的好处是：每个功能都长在用户的实际操作上，而不是长在产品经理的想象里。
2.2 边界场景与用例补全
需求阶段最容易被忽略的是"半正常"情况。比如扫描到一台设备，绑定了但连接失败；或者设备在数据传输过程中突然断开。这些边界场景必须在需求阶段就写清楚，否则开发面临的是无尽的原生回调错乱。
结合调试场景，我建议至少补充以下用例：
- 设备不断广播但不接受连接，要给出明确的"连接请求超时"提示。
- 设备连接成功后，服务发现失败，要提示"该设备可能不符合标准GATT规范"。
- 有的设备特征值需要先使能通知才能接收数据，需求文档里必须注明等待使能的交互反馈。
- 低电量设备信号弱，扫描列表应该能显示RSSI数值，而不是简单隐藏。
实际上，蓝牙开发的大部分Bug，都发生在这些边界条件里。需求导入阶段提前把这些写进卡片，后续开发就不是靠临场发挥，而是按图索骥。
3. 需求阶段就要暴露的底层硬约束：权限、兼容、MTU、扫描策略
蓝牙调试和写常规App最大的不同在于，它绕不开一大堆系统底层约束。这些约束不是代码写完再适配的，而是需求阶段就必须识别并转成硬需求的。
3.1 系统权限不是事后补的
Android 12以后，蓝牙权限拆成了"扫描、连接、广播"三部分，iOS也要求蓝牙使用说明文案，这些都是硬门槛。需求阶段就要明确：
- 首版支持的Android版本范围（建议是当前主流版本的覆盖区间，而不是全版本）。不同安卓厂商对后台扫描的管控差异很大，有些系统要求应用在前台运行或启动前台服务，否则扫描到一半就被系统杀掉。研发老手都知道这个坑：明明是同一个蓝牙API，在不同定制系统上的行为却千差万别。
- iOS的授权说明文案。蓝牙使用说明不是随便填一句就行，审核时会被检查，提审前就该准备好。
- 定位权限虽然听起来无关，但在部分Anroid版本上，蓝牙扫描行为其实依赖于位置权限的授予。需求卡片里要明确"不授予定位权限时应降级为经典蓝牙模式"或"给出引导说明"。
如果不把这些写进需求，开发做到一半才发现权限模型影响整个扫描流程，再回头改架构，就不是加一个弹窗那么简单了。
3.2 经典蓝牙与BLE的双模支持
蓝牙调试助手面对的硬件大致分两类：一类是低功耗蓝牙设备，用GATT协议，这是目前智能硬件的主流；另一类是经典蓝牙蓝牙串口模块，走SPP协议，很多老工业设备、调试工具还在用。两种协议的开发接口完全不同，界面交互也有差异。
需求导入阶段必须决定首版做"双模"还是"单BLE"。我的建议是：首版先在代码架构上实现协议抽象层，但UI只开放BLE模式，SPP先不对外暴露。简单说，就是底层把"扫描、连接、服务发现、收发数据"这些动作统一成一套接口，后续加SPP只是增加一个实现类。如果一上来就双模并行，扫描引擎、连接状态机、日志系统都要维护两套，工程量翻倍。
现实中很多调试助手App的开发灾难，都是因为"先做BLE版本，后面再补SPP"，结果BLE分支里到处写死GATT方法，加SPP时等于重构。需求阶段辛苦一点，把抽象层想清楚，能省后面半个月的返工。
3.3 MTU协商与数据分包
BLE通信里有一个关键参数，最大传输单元，直接影响一次能发多少字节。系统默认MTU是23字节，去掉协议头，实际只够发20字节的用户数据。如果要传输大块数据，必须和设备协商更大的MTU，很多设备支支持提升到185、247甚至512字节。
这个参数在需求阶段绝对不能忽视，原因有两个。第一，不同设备的协商时机不一样，有些需要连接后立刻协商，有些允许在写入前动态协商。第二，开发者调试大包传输时，往往需要手动改变MTU来看设备表现。
所以需求卡片上要加两条：连接成功后必须进行一次MTU协商，并在界面上展示协商结果；提供手动修改MTU的入口。很多第一版调试助手表都会忽略这个，等到用户发现"我明明发了256字节，为什么设备只收到20字节"才想起来，那已经是上线后的事了。
3.4 扫描结果不是越多越好
不加任何过滤条件的原始扫描，会把周围两三台手机、耳机、手表全扫进来，结果列表乱七八糟。但过滤逻辑也不是越强越好——过滤太死，真设备被误伤；过滤太松，假设备干扰判断。
需求阶段就要把扫描策略定下来，至少包括四个维度：
- 扫描时长：建议默认3~5秒，太一点点扫不全，太长了界面上用户会失去耐心。
- 过滤条件：名称关键字、MAC地址、服务UUID三种，至少要支持一种且可组合。
- 排序规则：按RSSI强弱排还是按信号稳定度排，界面需要提供切换。
- 去重逻辑：同一台设备不要重复出现在结果里，但广播通道切换时应该能感知到。
这里顺便说个经验：过滤条件必须在界面上拉一个明显的入口，而不是藏在深层的设置页。真正调设备的人随时要换过滤条件，你把它藏在二级菜单，用户会觉得这个工具"不好用但说不出哪里不好用"。
4. 把需求拆成可认领的开发任务：用户故事、粒度与优先级排期
4.1 用户故事统一语言
需求卡片出来后，下一步是把它转成开发可认领的任务。我用的是"用户故事+任务拆分"组合法。
用户故事的作用是让所有人（产品、开发、测试）对需求的理解对齐。还是用表格来说明：
| 用户故事 | 涉及模块 | 可验收成果 |
|---|---|---|
| 作为嵌入式工程师，我希望扫描窗口达到10秒，以便在海量设备中找到目标 | 扫描引擎 | 扫描时长可配置，默认5秒，最大30秒 |
| 作为测试员，我希望连接失败时显示错误码，以便判断是权限、超时还是设备拒绝 | 连接状态机 | 错误码映射表完整，界面有明确文案提示 |
| 作为现场维修工，我希望历史日志能按设备分组导出，以便回公司写检修报告 | 日志模块 | 导出文件按设备名建文件夹，内部包含CSV和TXT |
每个用户故事都对应一张可确认的成果，开发拿到后不需要猜产品意图，测试也可以照着验收。
4.2 任务颗粒度怎么定
写任务时最容易走极端。任务写太大容易有含糊地方，比如"实现扫描页"——到底包不包含权限引导？包不包含过滤面板？任务写得太小又变成机器人搬砖，比如"在按钮上增加半圆角"这种。
我自己的标准是：一个任务应该半天到一天内能完成，并且可以独立验收。"实现扫描页"太大，得拆成：
- 权限申请与预处理流程
- 扫描服务接口与回调
- 扫码结果列表适配器
- 过滤条件面板
- 扫描自动化测试用例
这样每个任务结束后都能交给测试跑一轮，不会出现"全部完成再一起测"然后一起爆雷的情况。蓝牙调试类应用尤其如此——底层回调多、异步多，每单元提前验证比集中验证省力得多。
4.3 优先级与迭代切片
需求导入阶段不是要把所有功能都排进第一版。我给蓝牙调试助手定义了三档优先级：
- P0（第一版必做）：权限流程、扫描与过滤、连接与断开、GATT服务浏览、特征值读写、通知监听、带时间戳的基础日志。这些构成一个能用的调试工具骨架，缺任何一个都走不通闭环。
- P1（第二版前后补上）：MTU手动修改、日志导出、极端边界状态提示、信号RSSI排序。这些是提升效率但不影响核心闭环。
- P2（后续迭代）：脚本回放、CRC校验计算器、JSON格式化查看、深色模式、多语言。
排期上有一个依赖链：权限层先于扫描层、扫描层先于连接层、连接层先于服务发现层、服务发现层先于数据读写层、数据读写层依赖日志层。这不代表先做权限就能完全不管别的，而是每一层都要在上一层稳定后再往下走，避免底层不稳导致上层全部返工。
5. 需求阶段就按下"砍"和"留"的开关：MVP边界与后续迭代
5.1 MVP到底包含什么
MVP不是"完整体缩小版"，而是一个能体现核心价值的最小闭环。对蓝牙调试助手来说，核心价值只有一句话：让工程师能快速连接到设备，并看到设备在往返回什么。
基于这个定义，MVP必须包含：扫描识别目标设备、建立连接、查看GATT服务列表、向某个特征值写数据、订阅通知并实时展示返回数据、记录带时间戳的历史会话。这六个动作是一个调试人员完成一次"发现问题→定位问题"的最小路径。
日志导出去掉行不行？如果项目非常赶，可以先用"复制到剪贴板"暂时代替。但我建议哪怕是最简单的"复制文本"也要纳入MVP，因为调试结果的沉淀往往是复盘时才发现的，没有导出能力，一次会话结束时现场证据就全丢了。
5.2 砍掉什么，以及为什么砍掉
我在需求导入阶段砍过这些功能：
- 图形化信号仪表盘：看起来很酷，但实际调设备时看RSSI数值就够了，画一条随时间变化的信号曲线并不会让分析更高效，还浪费时间。
- 脚本自动化：把固定指令集录制成脚本批量执行很有吸引力，但它需要单独的调度引擎和失败重试机制，影响核心稳定性，放到P2。
- 多设备同时管理：BLE本身支持同时连接多台设备，但交互上"多个设备切换查看"的数据结构设计要复杂很多，MVP不做不代表底层禁用，后面做连接池扩展时再加UI。
- 云端数据同步：完全走偏了，调试数据是私有的，放到几台云服务器上用户第一个不答应。
砍需求不是目的，砍掉是为了让核心功能更快更稳。蓝牙调试工具的核心从来不是功能多，而是每一步操作反馈准确、可重复、不崩溃。功能越多，回调越多，状态机越复杂，崩溃概率越大。
5.3 为砍掉的东西预留接口
砍需求≠不思考未来。在代码结构上，要提前预留扩展点。举三个我比较看重的例子：
- 协议解析器：MVP阶段只需要实现最基本的hex/ASCII两种模式。但需求里应该定义一个抽象接口，比如"解析器输入原始字节数组，输出可展示的字符串"，未来加CRC校验、JSON视图、浮点解析都是增加一个实现类的事。
- 日志存储层：MVP阶段可以只写文件，但接口要定义为"追加一条会话记录、按条件查询、导出"，未来切换数据库才用不着动UI层。
- 扫描过滤参数：MVP可以写死名字过滤和RSSI排序，但结构上应设计成过滤器链，未来加"按服务UUID过滤""按厂商特定数据过滤"时，只是往链上加一环。
这些"接口预留"的成本初期极低，可能只是多想一下类名和函数签名，但后续迭代时不重构核心的收益回报非常可观。砍掉的是用户能感知的功能边界，留下的是面向未来的扩展缝隙。
最后说一个真实体会。我第一次做这类项目的时候，对"需求导入"完全轻视，拿到需求第一反应是"这有什么好想的，直接写代码"。结果扫描列表做出来之后才发现没有时间戳的日志，后面补一个时间戳，要把整个日志数据结构重写一遍；再后面发现过滤条件是硬编码，改起来又要动整个扫描模块。那时候才明白，需求导入不是写文档，而是把所有返工提前到动手之前。它不会让代码总量变少，但能让每一次返工都发生在纸上，而不是发生在编译器和真机测试里。
如果你想做或者正在做蓝牙调试助手，我的建议很朴素：拿一张纸把三行字写清楚——给谁用、在什么场景用什么流程、怎么验收。三行字写完了，再打开IDE，那才是开发真正开始的时候。
