trae生成的接口文档需真实反映业务意图，明确标注触发主体与上下文、角色权限与状态边界、失败路径与用户反馈。例如【适用场景】巡检员离线检查后联网提交；（仅管理员，工单状态为“待分配”）；400提示高亮缺失字段，超时8秒重试2次并缓存补发。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要让Trae生成的接口文档能真实反映业务意图，而不是堆砌技术字段——比如“用户登录”不能只写POST /user/login，而要说明这个接口在什么业务环节被调用、由谁触发、失败后前端如何引导用户。
明确标注触发主体与上下文
在提示词开头直接定义该接口所处的真实业务链路。例如：“【适用场景】巡检员在离线状态下完成现场检查后，通过‘提交巡检结果’按钮触发此接口，此时设备已恢复联网，需将本地缓存的JSON数据一次性上报至中心服务。”
这一步必须写清楚，否则Trae可能默认生成“Web端表单提交”风格的文档，忽略移动端重试、断网续传、批量合并等关键约束。
区分角色权限与状态边界
方法一：用括号标注角色和前置状态
在接口描述中嵌入权限与状态条件，例如：“（仅限管理员角色，在工单状态为‘待分配’时可用）分配工单给指定处理人”。
方法二：单独列出“准入条件”段落
在提示词末尾追加：【准入条件】必须包含：当前用户角色、所在页面路径、关联业务对象状态、是否需前置操作（如先调用获取token接口）。
不写清楚这些，Trae生成的文档会缺失权限校验说明，导致前端盲目调用后收到403却不知原因。
绑定失败路径与用户反馈
第一步：列出所有可能的HTTP状态码及对应业务含义
例如：400 → “检查项填写不全，需高亮缺失字段”；409 → “该巡检任务已被他人提交，当前页面自动跳转至详情页只读模式”。
第二步：为每个错误响应补充前端动作建议
不要只写“返回错误信息”，要写“前端应拦截该响应，弹出Toast提示‘网络异常，请稍后重试’，并启用本地草稿自动保存机制”。
第三步：注明超时与重试策略
明确写入提示词：“此接口超时设为8秒，失败后前端最多重试2次，第二次失败后进入离线缓存队列，下次联网时自动补发”。【不写这条，Trae默认不生成重试说明】
