# 个人反馈后端接入方案

更新时间：`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 认证测试通过。