夜雨聆风一、产品只负责写 4 大块内容，不碰技术参数
- 接口名称、业务用途说明
：这个接口解决用户什么问题、使用场景 - 完整业务规则、限制条件
：各种允许 / 不允许的逻辑、会员 / 设备约束 - 业务入参的业务含义
：只解释字段代表什么业务信息，不写长度、类型、加密 - 业务成功 / 失败的业务结果
：出现不同情况用户会看到什么效果，不写错误码。
二、通用写作模板（产品固定写法）
标准模板
接口名称：XXX 业务接口
使用场景：谁在什么终端、什么操作下会触发调用这个接口 核心功能：调用接口后实现什么业务能力，给用户带来什么效果 业务约束规则（逐条写清楚）
限制 1：xxx 限制 2：xxx 特殊拦截场景：xxx（什么情况操作不生效）
输入业务信息说明（只讲含义）
用户设备标识：区分耳机 / 音箱 / 电动车的唯一机身编号 用户身份 ID：当前登录车主 / 耳机使用者账号
业务返回结果说明
成功：页面展示 XX 提示，触发 XX 联动动作（推送消息 / 变更设备状态） 失败场景 1：设备被他人绑定 → APP 提示 “该设备已被其他账号绑定，无法操作” 失败场景 2：账号绑定设备已满 → APP 提示 “最多绑定 2 台设备，请先解绑旧设备”
三、3 套实操完整示例（纯产品撰写内容，无任何后端技术内容）
示例 1：AI 蓝牙耳机 - 设备解绑接口（产品完整文稿）
接口名称：蓝牙耳机设备解绑接口
使用场景：用户在耳机配套手机 APP，进入设备管理页面，点击解绑设备按钮时触发。 核心功能：解除当前账号与蓝牙耳机的绑定关系，解绑后耳机可被其他新账号扫码绑定. 业务约束规则： ① 耳机处于售后维修锁定状态时，不允许解绑； ② 用户账号注销前，必须解绑全部绑定耳机，否则无法提交注销申请； ③ 解绑操作会永久留存解绑记录，用于售后设备溯源查询； ④ 解绑完成后，耳机本地清除原账号降噪、快捷语音等自定义配置。 输入业务信息说明：
耳机硬件标识：每台耳机唯一 MAC 编码，用来定位要解绑的耳机设备 当前操作人账号：登录用户身份，校验设备归属权
业务返回结果：
成功：弹窗提示 “设备解绑成功”，设备列表移除该耳机； 失败 1：设备维修锁定 → 弹窗提示 “设备正在售后维修，暂不可解绑”； 失败 2：设备不属于当前账号 → 弹窗提示 “无该耳机操作权限”。
示例 2：蓝牙智能音箱 - 收藏歌曲接口（产品完整文稿）
接口名称：语音歌曲收藏接口。
使用场景：用户对着音箱说出 “收藏这首歌” 语音指令，音箱自动上报音频信息调用接口。 核心功能：将当前播放音频加入用户个人收藏列表，APP 可查看收藏曲目。 业务约束规则① 普通用户收藏上限 200 首，会员用户无收藏数量限制；② 同一首歌重复收藏，不会重复生成多条收藏记录；③ 付费专辑试听片段无法加入收藏，需开通会员后才能收藏；④ 用户注销账号，收藏列表全部清空且不可恢复。 输入业务信息说明
音频唯一标识：区分歌曲、有声书、电台节目的编号 音箱设备编号：区分是哪一台音箱发起的收藏指令 用户会员身份：判断收藏数量上限
业务返回结果
成功：音箱语音播报 “已为你收藏当前歌曲”； 失败 1：普通用户收藏已满 → 音箱播报 “收藏数量已达上限，开通会员不限收藏”； 失败 2：付费试听内容 → 音箱播报 “开通会员即可收藏该音频”。
示例 3：智能两轮电动车 - 远程上锁设防接口（产品完整文稿）
接口名称：电动车远程设防上锁接口
使用场景：车主在电动车微信小程序，点击 “远程上锁” 按钮触发接口调用。 核心功能：车辆开启防盗设防，切断电机供电，车辆震动、移动时向车主推送报警提醒。 业务约束规则① 车辆实时行驶状态下，禁止执行上锁操作；② 车辆离线无信号时，上锁指令暂存，上线后自动执行；③ 设防状态下骑行，必须先在小程序解锁才能正常行驶；④ 车辆过户变更车主后，原车主无法再远程上锁。 输入业务信息说明
车辆车架编号：唯一标识电动车，校验车辆归属 当前车主账号：校验操作人是否为车辆绑定车主
业务返回结果
成功：小程序提示 “设防上锁成功，车辆异动将推送提醒”； 失败 1：车辆正在行驶 → 弹窗提示 “车辆行驶中，无法远程上锁”； 失败 2：车辆离线 → 弹窗提示 “车辆当前无信号，上线后自动上锁”。
四、产品写接口文档的避坑要点
不写技术内容：不写接口地址、POST/GET、JSON、加密、字段长度、错误码； 聚焦用户与业务：全程站在用户使用、产品规则角度描述，不考虑代码实现； 区分 “业务描述” 和 “技术实现”：只定义产品要达到什么效果，怎么实现交给后端； 所有异常只写前端用户提示文案，不用数字编码。
五、用「蓝牙音箱收藏歌曲」场景给你讲明白
1、请求方式：POST
含义：客户端（音箱 / 手机 APP）向服务器传数据的传输方式，常见就两种 GET / POST。
POST：专门用来提交、新增、修改数据（新增收藏、解绑设备、远程上锁都用它）； GET：只用来单纯查数据（查收藏列表、查车辆定位），不会改动后台数据。
对应你的场景
用户说 “收藏这首歌”，是新增一条收藏记录，会改变后台数据库，所以规定必须用 POST。
2、入参：userId、audioId、deviceMac
入参 = 发给服务器的参数（提交的数据），调用接口时必须一起带上这 3 个信息，缺一不可：
userId：当前登录用户的账号 ID，用来区分是谁收藏的歌曲； audioId：正在播放这首歌的唯一编号； deviceMac：音箱硬件唯一地址，区分是哪台音箱发起的收藏指令。
举个通俗例子：你去奶茶店填表下单，表格上要填「手机号、饮品编号、取餐码」，这三样就等同于入参。
3、字段约束：audioId 长度 16 位纯数字
约束 = 后台规定的数据格式硬性要求，不符合就直接拒绝处理。
audioId 只能是数字，不能出现字母、符号； 不多不少刚好 16 个数字，15 位、17 位都会报错。
4、限流规则：单设备 1 分钟最多调用 10 次，超限返回报错码 6008
限流规则
防止有人疯狂重复发指令压垮服务器，做的访问限制。一台音箱，1 分钟内最多发 10 次收藏请求，第 11 次直接拦截。
报错码 6008
后端自定义数字代号，用来快速定位问题：程序收到 6008，就代表「调用太频繁，触发限流」，前端音箱可以播报提示：“操作过于频繁，请稍后再试”。
5、返回参数：collectId、collectTime、currentCollectCount
返回参数 = 服务器处理完后，还给 APP / 音箱的数据：
collectId：这条收藏记录的唯一编号； collectTime：收藏成功的时间； currentCollectCount：该用户现在一共收藏了多少首歌（用来判断是否达到收藏上限）。
整套流程串联举例
用户对着音箱说 “收藏歌曲”； 音箱用 POST 方式，把这三个入参传给服务器： userId=10001，audioId=1234567890123456，deviceMac=AA:BB:CC:DD:EE；后台先校验：audioId 是不是 16 位数字； 再校验：这台音箱 1 分钟内有没有超过 10 次收藏； 超过 10 次 → 返回报错码 6008； 没超限 → 生成收藏记录； 服务器把返回参数发回音箱： collectId=99876，collectTime=20260622153000，currentCollectCount=120；音箱播报 “收藏成功，你已收藏 120 首歌曲”。
