# “我的”页签帮助与反馈入口 PRD

更新时间：`2026-05-08`

## 0. 目标

在平台“我的”页签新增“反馈”入口。用户点击后进入独立路由 `/profile/feedback`，看到移动端优先的“帮助与反馈”表单页面，用于提交问题描述、上传问题截图凭证并选填联系电话。

本次目标是补齐用户反馈入口、图片预览、后端提交接口和 SpacetimeDB 持久化闭环，不重新发明新的个人中心系统，不在“我的”页签当前面板下方展开表单。

## 1. 参考图

计划参考图保存在：

`../.hermes/plans/assets/profile-feedback-reference-2026-05-08.png`

页面结构以该参考图为准：

1. 页面顶部保留项目风格返回按钮和标题“帮助与反馈”，不保留无实际功能的仿客户端顶部栏。
2. 内容背景、卡片、按钮和状态色使用现有平台主题变量，避免硬编码成与主站不一致的蓝灰色页面。
3. 分区标题为“反馈问题”。
4. 第一张白色圆角卡片为“问题描述”。
5. 第二张白色圆角卡片为“上传凭证(提供问题截图)”。
6. 第三张白色圆角卡片为“联系电话”。
7. 底部为蓝色主按钮“提交”。
8. 提交按钮下方为蓝色文本入口“查看反馈与投诉记录”。

## 2. 首版范围

### 2.1 包含

- “我的”页签常用功能区新增“反馈”入口。
- 点击入口进入 `/profile/feedback` 独立路由。
- 反馈页标题显示“帮助与反馈”。
- 问题描述输入：
  - 最少 10 个字。
  - 最多 200 个字。
  - 实时显示 `当前字数/200`。
  - placeholder：`请填写10个字以上的问题描述以便我们提供更好的帮助，温馨提醒您请勿填写身份证号等个人隐私信息。`
- 上传凭证：
  - 展示虚线上传方块。
  - 支持选择图片时，最多 4 张。
  - 前端可预览已选图片。
  - 已选图片使用 Data URL 预览，并随提交请求作为首版反馈凭证入库。
- 联系电话：
  - 选填。
  - placeholder：`选填，如您填写则将会同步开发者与您联系`。
- 提交后通过 `POST /api/profile/feedback` 写入 SpacetimeDB，接口成功后显示成功态。
- 返回后回到平台首页并定位“我的”页签。

### 2.2 不包含

- 不新增后台反馈记录管理页。
- 不实现真实“反馈与投诉记录”列表。

后端接入细节以 [`docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md`](../technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md) 为准。

## 3. 入口设计

### 3.1 入口位置

入口放在“我的”页签常用功能区，和“每日任务 / 邀请好友 / 填邀请码 / 玩家社区”同级。

入口展示：

- 主标题：`反馈`
- 副标题：`问题与建议`
- 图标：可复用 `MessageCircle` 或类似消息图标。

### 3.2 未登录状态

首版默认未登录用户点击入口时触发登录弹窗，不进入反馈页。

原因：当前“我的”页签的数据与账号绑定，反馈如果未来接入后端，也应能关联提交账号。

## 4. 反馈页 UI

### 4.1 页面整体

- 移动端优先。
- 背景、表单容器、输入框、提示和按钮复用 `platform-*` 主题变量。
- 桌面端居中展示，最大宽度不超过移动表单阅读范围，避免横向拉满。

### 4.2 返回区

- 标题：`帮助与反馈`。
- 左侧返回按钮：点击返回平台首页“我的”页签。
- 不展示右侧胶囊控制区、假系统按钮或无实际功能顶部栏。

### 4.3 问题描述卡片

- 标题：`问题描述`。
- 输入框类型：textarea。
- 最小高度接近参考图的大文本区域。
- 右下角字数：`0/200`。
- 校验失败提示靠近卡片或提交按钮上方展示，不弹浏览器 alert。

### 4.4 上传凭证卡片

- 标题：`上传凭证(提供问题截图)`。
- 上传入口为虚线边框方块。
- 文案：
  - `上传凭证`
  - `(最多四张)`
- 支持图片选择时，只允许 `image/*`。
- 超过 4 张时提示：`最多上传四张凭证`。
- 单张图片最大 1MB，总大小最大 4MB。
- 选择图片后必须立即展示缩略图预览，删除后从待提交凭证中移除。

### 4.5 联系电话卡片

- 标题：`联系电话`。
- 输入框类型：text 或 tel。
- 联系电话选填，不阻塞提交。
- 最长 40 字符。

### 4.6 底部操作

- 主按钮：`提交`。
- 按钮为蓝色圆角，宽度接近容器宽度。
- 二级链接：`查看反馈与投诉记录`。
- 首版无记录页时，该链接可以：
  - 隐藏；或
  - 保留并点击后显示轻量提示“反馈记录暂未开放”。

## 5. 路由与状态

- 新增页面阶段：`profile-feedback`。
- 新增路由：`/profile/feedback`。
- 浏览器直接访问 `/profile/feedback` 时应显示反馈页。
- 点击页面返回时：
  - 设置平台 tab 为 `profile`。
  - 回到 `platform` 阶段。

## 6. 表单校验

提交时按以下顺序校验：

1. 问题描述去除首尾空白后少于 10 个字：提示 `请填写10个字以上的问题描述`。
2. 问题描述超过 200 个字：提示 `问题描述不能超过 200 字`。
3. 联系电话超过 40 字符：提示 `联系电话不能超过 40 字`。
4. 上传凭证超过 4 张：提示 `最多上传四张凭证`。

校验通过后调用 `POST /api/profile/feedback`，请求成功后进入成功态。

## 7. 验收标准

- “我的”页签可看到“反馈”入口。
- 已登录用户点击后进入 `/profile/feedback`。
- 未登录用户点击后弹登录。
- `/profile/feedback` 页面显示“帮助与反馈”。
- 问题描述字数统计实时变化。
- 空内容或少于 10 个字提交时显示校验错误。
- 有效内容提交后显示成功态。
- 上传凭证最多 4 张。
- 上传凭证选择后显示图片预览。
- 有效反馈提交后写入 `profile_feedback_submission` 表。
- 提交接口返回 `feedbackId`、状态、提交时间和凭证元数据。
- 联系电话为空时可以提交。
- 返回后回到“我的”页签。
- 页面在 390×844 移动端视口不横向溢出。
- `npm run check:encoding`、`npm run typecheck`、定向测试通过。

## 8. 文件落点

- PRD：`docs/prd/PROFILE_FEEDBACK_ENTRY_PRD_2026-05-08.md`
- 路由：`src/routing/appPageRoutes.ts`
- 阶段类型：`src/components/platform-entry/platformEntryTypes.ts`
- 反馈页：`src/components/platform-entry/PlatformFeedbackView.tsx`
- 前端 profile client：`src/services/rpg-entry/rpgProfileClient.ts`
- 我的页签入口：`src/components/rpg-entry/RpgEntryHomeView.tsx`
- 页面接入：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
- 共享契约：`packages/shared/src/contracts/runtime.ts`、`server-rs/crates/shared-contracts/src/runtime.rs`
- 后端 API：`server-rs/crates/api-server/src/runtime_profile.rs`
- SpacetimeDB：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
- 领域规则：`server-rs/crates/module-runtime/src/*`
- 测试：
  - `src/routing/appPageRoutes.test.ts`
  - `src/components/platform-entry/PlatformFeedbackView.test.tsx`
  - `src/services/rpg-entry/rpgProfileClient.test.ts`
  - `server-rs/crates/module-runtime`
  - `server-rs/crates/api-server/src/runtime_profile.rs`