Genarrative/docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md

个人反馈后端接入方案

更新时间：2026-05-08

目标

/profile/feedback 不再停留在前端成功态，提交时必须经过 api-server 鉴权、spacetime-client facade、spacetime-module procedure，并持久化到 SpacetimeDB。

接口

• 路由：POST /api/profile/feedback
• 鉴权：必须登录，用户 ID 取 AuthenticatedAccessToken，前端不得上传或伪造 userId。
• 请求体：
  • description：必填，trim 后 10 至 200 字符。
  • contactPhone：选填，trim 后最多 40 字符。
  • evidenceItems：选填，最多 4 张图片。
  • 每张凭证包含 fileName、contentType、sizeBytes、dataUrl。
• 响应体：
  • feedback.feedbackId
  • feedback.status
  • feedback.createdAt
  • feedback.evidenceItems 只回传凭证元数据，不回显 Data URL。

表结构

新增私有表 profile_feedback_submission：

• feedback_id PK: String
• user_id: String
• description: String
• contact_phone: Option<String>
• evidence_json: String
• status: RuntimeProfileFeedbackStatus
• created_at: Timestamp
• updated_at: Timestamp
• 索引：user_id、(user_id, created_at)

evidence_json 保存首版图片凭证快照，后续如果迁移 OSS，应保持 HTTP 契约不变，仅替换内部 evidence 存储字段。

分层落点

• shared-contracts：冻结 HTTP DTO。
• module-runtime：负责输入归一化、长度限制、图片数量/大小/Data URL 前缀校验、反馈 ID 和 evidence ID 生成、响应记录组装。
• spacetime-module：新增 table 与 submit_profile_feedback_and_return procedure；只做事务写入和表到快照映射。
• spacetime-client：新增 submit_profile_feedback facade，不让 api-server 直接依赖生成绑定。
• api-server：新增鉴权 POST route，并对该 route 单独放宽 JSON body 上限。
• 前端：PlatformFeedbackView 只负责临时表单状态、图片预览和调用 profile client；正式提交结果以后端返回为准。
• 绑定生成：Windows 本地如遇 sccache 远端缓存被网络沙箱拦截，可临时使用仓库内短路径 GENARRATIVE_BINDGEN_TEMP_ROOT 并设置 CARGO_BUILD_RUSTC_WRAPPER 到本地 rustc passthrough wrapper 后重跑生成，不修改 server-rs/.cargo/config.toml。

验收

• 图片选择后能在页面看到缩略图。
• 有效表单调用 POST /api/profile/feedback 并写入 profile_feedback_submission。
• 未登录提交返回 401。
• 超过图片数量、单张大小、总大小或非法 Data URL 时返回清晰校验错误。
• migration.rs、SpacetimeDB 表目录、生成绑定同步更新。
• 定向前端测试、Rust 领域测试和 API 认证测试通过。