一、产品只负责写 4 大块内容，不碰技术参数

1. 接口名称、业务用途说明
   ：这个接口解决用户什么问题、使用场景
2. 完整业务规则、限制条件
   ：各种允许 / 不允许的逻辑、会员 / 设备约束
3. 业务入参的业务含义
   ：只解释字段代表什么业务信息，不写长度、类型、加密
4. 业务成功 / 失败的业务结果
   ：出现不同情况用户会看到什么效果，不写错误码。

二、通用写作模板（产品固定写法）

标准模板

接口名称：XXX 业务接口

1. 使用场景：谁在什么终端、什么操作下会触发调用这个接口
2. 核心功能：调用接口后实现什么业务能力，给用户带来什么效果
3. 业务约束规则（逐条写清楚）

• 限制 1：xxx
• 限制 2：xxx
• 特殊拦截场景：xxx（什么情况操作不生效）

1. 输入业务信息说明（只讲含义）

• 用户设备标识：区分耳机 / 音箱 / 电动车的唯一机身编号
• 用户身份 ID：当前登录车主 / 耳机使用者账号

1. 业务返回结果说明

• 成功：页面展示 XX 提示，触发 XX 联动动作（推送消息 / 变更设备状态）
• 失败场景 1：设备被他人绑定 → APP 提示 “该设备已被其他账号绑定，无法操作”
• 失败场景 2：账号绑定设备已满 → APP 提示 “最多绑定 2 台设备，请先解绑旧设备”

三、3 套实操完整示例（纯产品撰写内容，无任何后端技术内容）

示例 1：AI 蓝牙耳机 - 设备解绑接口（产品完整文稿）

接口名称：蓝牙耳机设备解绑接口

1. 使用场景：用户在耳机配套手机 APP，进入设备管理页面，点击解绑设备按钮时触发。
2. 核心功能：解除当前账号与蓝牙耳机的绑定关系，解绑后耳机可被其他新账号扫码绑定.
4. 业务约束规则：
5. ① 耳机处于售后维修锁定状态时，不允许解绑；
6. ② 用户账号注销前，必须解绑全部绑定耳机，否则无法提交注销申请；
7. ③ 解绑操作会永久留存解绑记录，用于售后设备溯源查询；
8. ④ 解绑完成后，耳机本地清除原账号降噪、快捷语音等自定义配置。
10. 输入业务信息说明：

• 耳机硬件标识：每台耳机唯一 MAC 编码，用来定位要解绑的耳机设备
• 当前操作人账号：登录用户身份，校验设备归属权

1. 业务返回结果：

• 成功：弹窗提示 “设备解绑成功”，设备列表移除该耳机；
• 失败 1：设备维修锁定 → 弹窗提示 “设备正在售后维修，暂不可解绑”；
• 失败 2：设备不属于当前账号 → 弹窗提示 “无该耳机操作权限”。

示例 2：蓝牙智能音箱 - 收藏歌曲接口（产品完整文稿）

接口名称：语音歌曲收藏接口。

1. 使用场景：用户对着音箱说出 “收藏这首歌” 语音指令，音箱自动上报音频信息调用接口。
2. 核心功能：将当前播放音频加入用户个人收藏列表，APP 可查看收藏曲目。
3. 业务约束规则① 普通用户收藏上限 200 首，会员用户无收藏数量限制；② 同一首歌重复收藏，不会重复生成多条收藏记录；③ 付费专辑试听片段无法加入收藏，需开通会员后才能收藏；④ 用户注销账号，收藏列表全部清空且不可恢复。
4. 输入业务信息说明

• 音频唯一标识：区分歌曲、有声书、电台节目的编号
• 音箱设备编号：区分是哪一台音箱发起的收藏指令
• 用户会员身份：判断收藏数量上限

1. 业务返回结果

• 成功：音箱语音播报 “已为你收藏当前歌曲”；
• 失败 1：普通用户收藏已满 → 音箱播报 “收藏数量已达上限，开通会员不限收藏”；
• 失败 2：付费试听内容 → 音箱播报 “开通会员即可收藏该音频”。

示例 3：智能两轮电动车 - 远程上锁设防接口（产品完整文稿）

接口名称：电动车远程设防上锁接口

1. 使用场景：车主在电动车微信小程序，点击 “远程上锁” 按钮触发接口调用。
2. 核心功能：车辆开启防盗设防，切断电机供电，车辆震动、移动时向车主推送报警提醒。
3. 业务约束规则① 车辆实时行驶状态下，禁止执行上锁操作；② 车辆离线无信号时，上锁指令暂存，上线后自动执行；③ 设防状态下骑行，必须先在小程序解锁才能正常行驶；④ 车辆过户变更车主后，原车主无法再远程上锁。
4. 输入业务信息说明

• 车辆车架编号：唯一标识电动车，校验车辆归属
• 当前车主账号：校验操作人是否为车辆绑定车主

1. 业务返回结果

• 成功：小程序提示 “设防上锁成功，车辆异动将推送提醒”；
• 失败 1：车辆正在行驶 → 弹窗提示 “车辆行驶中，无法远程上锁”；
• 失败 2：车辆离线 → 弹窗提示 “车辆当前无信号，上线后自动上锁”。

四、产品写接口文档的避坑要点

1. 不写技术内容：不写接口地址、POST/GET、JSON、加密、字段长度、错误码；
2. 聚焦用户与业务：全程站在用户使用、产品规则角度描述，不考虑代码实现；
3. 区分 “业务描述” 和 “技术实现”：只定义产品要达到什么效果，怎么实现交给后端；
4. 所有异常只写前端用户提示文案，不用数字编码。

五、用「蓝牙音箱收藏歌曲」场景给你讲明白

1、请求方式：POST

含义：客户端（音箱 / 手机 APP）向服务器传数据的传输方式，常见就两种 GET / POST。

• POST：专门用来提交、新增、修改数据（新增收藏、解绑设备、远程上锁都用它）；
• GET：只用来单纯查数据（查收藏列表、查车辆定位），不会改动后台数据。

对应你的场景

用户说 “收藏这首歌”，是新增一条收藏记录，会改变后台数据库，所以规定必须用 POST。

2、入参：userId、audioId、deviceMac

入参 = 发给服务器的参数（提交的数据），调用接口时必须一起带上这 3 个信息，缺一不可：

1. userId：当前登录用户的账号 ID，用来区分是谁收藏的歌曲；
2. audioId：正在播放这首歌的唯一编号；
3. deviceMac：音箱硬件唯一地址，区分是哪台音箱发起的收藏指令。

举个通俗例子：你去奶茶店填表下单，表格上要填「手机号、饮品编号、取餐码」，这三样就等同于入参。

3、字段约束：audioId 长度 16 位纯数字

约束 = 后台规定的数据格式硬性要求，不符合就直接拒绝处理。

• audioId 只能是数字，不能出现字母、符号；
• 不多不少刚好 16 个数字，15 位、17 位都会报错。

4、限流规则：单设备 1 分钟最多调用 10 次，超限返回报错码 6008

限流规则

防止有人疯狂重复发指令压垮服务器，做的访问限制。一台音箱，1 分钟内最多发 10 次收藏请求，第 11 次直接拦截。

报错码 6008

后端自定义数字代号，用来快速定位问题：程序收到 6008，就代表「调用太频繁，触发限流」，前端音箱可以播报提示：“操作过于频繁，请稍后再试”。

5、返回参数：collectId、collectTime、currentCollectCount

返回参数 = 服务器处理完后，还给 APP / 音箱的数据：

1. collectId：这条收藏记录的唯一编号；
2. collectTime：收藏成功的时间；
3. currentCollectCount：该用户现在一共收藏了多少首歌（用来判断是否达到收藏上限）。

整套流程串联举例

1. 用户对着音箱说 “收藏歌曲”；
2. 音箱用 POST 方式，把这三个入参传给服务器：userId=10001，audioId=1234567890123456，deviceMac=AA:BB:CC:DD:EE；
3. 后台先校验：audioId 是不是 16 位数字；
4. 再校验：这台音箱 1 分钟内有没有超过 10 次收藏；
• 超过 10 次 → 返回报错码 6008；
• 没超限 → 生成收藏记录；
5. 服务器把返回参数发回音箱：collectId=99876，collectTime=20260622153000，currentCollectCount=120；
6. 音箱播报 “收藏成功，你已收藏 120 首歌曲”。