# 推荐理由反馈契约（设计稿，未实现）

状态：网站提供接手方案；Z1Space 产品端未实现，不收集访问者数据。无真实用户样本、无赞率结论。

## 数据与行为

字段：feedback_id、recommendation_id、reason_codes、recommendation_version、verdict（useful/not_useful）、subject_id（服务端生成的站内匿名标识）、created_at、updated_at。

服务端验证推荐归属、有效版本和登录状态；以 subject_id + recommendation_id + version 唯一约束去重。重复提交同一值幂等，改判更新旧记录，不累计两次。reason_codes 来自服务端推荐快照，不信任客户端任意标签。

客户端提供有用/没用两按钮，呈现未选、提交中、成功、失败可重试和改判状态；结果使用 aria-live 通知，错误时不假装保存，成功值与服务端返回一致。明确告知收集目的和保留期限，默认不落查询正文、聊天内容、IP 或公开个人资料。

## 统计定义

按推荐版本、固定时间窗和 reasonCode 统计有用数 / 有效去重反馈数，同时显示分母。一个推荐含多个 reasonCode 时会进入多个分组，分组数量不能相加当作独立用户数。它衡量反馈者评价，不能替代整体用户满意度、转化或推荐准确率。

## 验收用例（计划，未执行）

1. 合法归属和有效版本可提交；不属于本人、过期推荐、非法 verdict 拒绝。
2. 重复提交和网络重试不增加样本；改判仅更新一次。
3. API 错误保留选择并提示重试；刷新读取服务端最终值。
4. 小样本显示分母；无反馈显示“暂无反馈”，不显示 0% 质量结论。
5. 删除/撤回与保留策略可执行；日志不落敏感正文。

实施应在 Z1Space 源码仓库进行。本文件不新增网站后端，也不把演示记录伪装成真实运营数据。