ai-chatbot/docs/canvas-feedback.md

39 lines
3.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 画布问题反馈
画布顶部提供“问题反馈”;小窗口及视频画布在对话顶部提供入口。用户确认关联请求、补充说明后发送。反馈不调用画布保存或生成接口。
## 资料与权限
- 用户身份由登录会话及服务端用户表确定;收件人固定为准确花名“魔礼红”。
- 请求按当前用户、画布及对话查询。图片任务通过当前对话请求号或画布节点任务号关联,不查询账号下任意最近任务。
- 服务端只读取任务表,不调用带恢复、执行或状态变更副作用的任务查询接口。
- 自动采集当前对话最近 12 条公开消息(文字总量最多 48,000 字符)、最多 20 个节点的编号、尺寸及任务号,以及页面版本、窗口、网络和最近脚本错误。截图、图片二进制、内部提示词、Cookie 和认证头不采集。
- 用户可以切换关联请求或选择页面问题。尚未持久化的消息标记为浏览器来源;缺少请求号时保留消息或任务编号,不推测编号。
- 完整反馈保存在 `CanvasFeedback`;通知正文为限长摘要,按钮打开 `/feedback/{id}`。详情仅反馈本人及平台管理员可读。画布删除后反馈仍可查看,账号删除会级联删除其反馈。
## 提交和投递
- 浏览器在首次提交时固定反馈 UUID 和请求内容,在当前标签页保留提交资料。重复点击、响应丢失后的重试和刷新恢复均沿用原 UUID。
- 服务端按 UUID 插入一次,持久化的通知内容保持不变。通知中心幂等键为 `canvas-feedback:{id}:v1`;每次 HTTP 请求生成新 nonce。
- 保存成功后异步提交通知。节点运行时每分钟继续处理尚未入队的反馈,最多尝试 5 次;连接异常、5xx 和 429 按 1、5、15、30 分钟间隔重试,其他明确拒绝停止重试。
- 通知中心返回投递 ID 后只查询该单,不重新发送。中心负责实际投递及其重试;`DELIVERY_OUTCOME_UNKNOWN` 不自动补发。
- `pending`(本地保存)、`accepted`(中心受理)、`sent/unread/read`(钉钉接受或阅读)、`failed` 分别显示,不把受理当作送达。
## 服务端配置
```dotenv
YYD_NOTIFICATION_CENTER_URL=https://sc.jiansun.vip/notification-center
YYD_NOTIFICATION_CENTER_PROJECT_CODE=
YYD_NOTIFICATION_CENTER_PROJECT_SECRET=
```
项目代码及密钥使用通知中心分配值,仅配置到服务端。消息签名沿用通知中心 HMAC 契约,签名路径不含公网 `/notification-center` 前缀。
上线前先备份生产环境配置,并单独执行加表迁移 `0105_add_canvas_feedback.sql`;本次迁移仅新增反馈表和索引,不修改任务、画布、计费或原通知表。应用发布仍使用既有构建机直传流程。回滚应用可保留新增表,尚未入队的反馈在恢复新版后继续处理。
## 验证
`tests/routes/canvas-feedback.test.ts` 覆盖错误与原消息关联、固定收件人及摘要长度、受理状态、签名和重试边界;`tests/e2e/canvas-issue-feedback.test.ts` 覆盖自动采集、重复点击、丢失响应后刷新恢复和窄屏操作。
生产验收使用维护者自己的独立测试画布及已失败的测试记录,不提交模型任务。核对反馈与通知各只有一条、原任务 attempts 不变;查询通知中心最终状态,并核对完整反馈页面权限。