81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# 帮助与反馈入口案例（2026-05-08）
|
||
|
||
本案例来自 Genarrative “我的”页签新增反馈入口与独立反馈页实现。
|
||
|
||
## 目标
|
||
|
||
- 在“我的”页签新增“反馈”快捷入口。
|
||
- 点击后进入独立路由 `/profile/feedback`。
|
||
- 页面按移动端参考图实现“帮助与反馈”表单：问题描述、上传凭证、联系电话、提交、查看反馈与投诉记录。
|
||
|
||
## 关键文件
|
||
|
||
- `docs/prd/PROFILE_FEEDBACK_ENTRY_PRD_2026-05-08.md`
|
||
- `src/components/platform-entry/platformEntryTypes.ts`
|
||
- `src/routing/appPageRoutes.ts`
|
||
- `src/components/platform-entry/PlatformFeedbackView.tsx`
|
||
- `src/components/rpg-entry/RpgEntryHomeView.tsx`
|
||
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||
- `src/routing/appPageRoutes.test.ts`
|
||
- `src/components/platform-entry/PlatformFeedbackView.test.tsx`
|
||
|
||
## 落地顺序
|
||
|
||
1. 先补 PRD，避免从参考图直接猜代码细节。
|
||
2. 在 `SelectionStage` 中新增 `'profile-feedback'`。
|
||
3. 在 `STAGE_ROUTE_ENTRIES` 添加：
|
||
- `['profile-feedback', '/profile/feedback']`
|
||
4. 新建 `PlatformFeedbackView`：
|
||
- `onBack: () => void`
|
||
- `onSubmit?: (payload) => void | Promise<void>`
|
||
- 内部维护描述、联系电话、上传图片预览、错误态、成功态。
|
||
- 首版没有后端接口时，`onSubmit` 为后续 API 接入点。
|
||
5. 在 `RpgEntryHomeViewProps` 添加 `onOpenFeedback?: () => void`。
|
||
6. 在“我的”页签快捷入口区新增 `ProfileShortcutButton`：
|
||
- `label="反馈"`
|
||
- `subLabel="帮助与反馈"`
|
||
- `onClick={onOpenFeedback}`
|
||
7. 在 `PlatformEntryFlowShellImpl`：
|
||
- import `PlatformFeedbackView`
|
||
- 新增 `openProfileFeedback`
|
||
- 未登录则 `authUi?.openLoginModal()`
|
||
- 已登录则 `setPlatformTab('profile')` + `setSelectionStage('profile-feedback')`
|
||
- 直达阶段时 `useEffect` 同步 `profile` tab
|
||
- 渲染 `selectionStage === 'profile-feedback'` 的独立 `<motion.div>`
|
||
8. 增加测试：
|
||
- 路由双向解析
|
||
- 页面字段渲染
|
||
- 描述低于 10 字不提交
|
||
- 提交时 trim payload
|
||
- 顶部返回按钮调用 `onBack`
|
||
|
||
## UI 参考要点
|
||
|
||
- 移动端优先，页面最大宽度约 30rem。
|
||
- 浅灰背景，白色圆角卡片。
|
||
- 顶部标题：`帮助与反馈`。
|
||
- 分区标题：`反馈问题`。
|
||
- 问题描述 placeholder：提示填写 10 字以上，勿填身份证号等隐私。
|
||
- 字数计数：`0/200`。
|
||
- 上传凭证：最多四张，上传占位显示 `上传凭证` 和 `(最多四张)`。
|
||
- 联系电话：选填。
|
||
- 主按钮：蓝色圆角 `提交`。
|
||
- 底部链接：`查看反馈与投诉记录`。
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
npm run check:encoding
|
||
npm run typecheck
|
||
npx vitest run src/routing/appPageRoutes.test.ts src/components/platform-entry/PlatformFeedbackView.test.tsx
|
||
# 或
|
||
npm run test -- --run src/routing/appPageRoutes.test.ts src/components/platform-entry/PlatformFeedbackView.test.tsx
|
||
```
|
||
|
||
## 已踩坑/经验
|
||
|
||
- `appPageRoutes.test.ts` 若已有历史内容，写入测试时注意不要误删旧用例；最终 commit 里出现 “insertions + deletions” 时要检查是否覆盖了既有测试。
|
||
- 页面组件里的图片预览需要在移除或卸载时 `URL.revokeObjectURL`，避免泄漏。
|
||
- 对隐藏 file input 的测试可以先不强行覆盖，首版覆盖表单字段、校验和 payload 更稳定。
|
||
- 如果用 `authUi` 对象作为 callback 依赖，需确认引用稳定性；现有 shell 中可接受，但复杂化时考虑拆出具体字段依赖。
|