58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# 个人反馈后端接入方案
|
||
|
||
更新时间：`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 认证测试通过。
|