Add backend feedback submission and image preview

docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md

@@ -0,0 +1,57 @@
+# 个人反馈后端接入方案
+
+更新时间：`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 认证测试通过。