Genarrative/.hermes/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md

帮助与反馈入口案例（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。
• 上传凭证：最多四张，上传占位显示 上传凭证 和 (最多四张)。
• 联系电话：选填。
• 主按钮：蓝色圆角 提交。
• 底部链接：查看反馈与投诉记录。

验证命令

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 中可接受，但复杂化时考虑拆出具体字段依赖。