eryao/.trellis/tasks/05-09-manual-divination-shuffle-animation/prd.md

手动起卦处理蒙版与解卦结果页面

背景

用户在手动起卦页面点击"开始解卦"后，需要一个加载等待蒙版，等待后端 agent 传输完成后进入结果页面。

已完成

1. 处理蒙版层 (DivinationProcessingOverlay) ✅

组件文件: web/src/components/DivinationProcessingOverlay.tsx

实现内容:

• 全屏蒙版覆盖，高斯模糊背景
• 暗色调遮罩层阻止点击穿透
• Y轴翻转动画（以中间为对称轴翻转180度）
• 8张八卦卡片循环展示
• 三种状态：preparing → deriving → done
• 后端 API 对接（SSE 事件流）

i18n 文本 (使用 Flutter 已有文本):

• transitionPreparing: 天机推演中 / 天機推演中 / Deriving...
• transitionDeriving: 正在解卦 / 正在解卦 / Analyzing...
• transitionDone: 解卦完成\n点击查看 / 解卦完成\n點擊查看 / Complete\nTap to view
• processingCard*: 八卦卡片标题和爻辞（简中/繁中/英文三语）

动画参数:

• 翻牌间隔: 2000ms
• 翻转动画时长: 600ms
• 3D 透视: perspective: 1000px

2. ManualDivinationPage 集成 ✅

修改内容:

• 添加 showProcessing 状态
• 点击"开始解卦"显示蒙版
• 传递起卦参数和六爻状态
• 完成后导航到解卦结果页面

3. 后端 API 层 ✅

新增函数: web/src/lib/api.ts

• enqueueDivinationRun() - 提交起卦请求
• streamDivinationEvents() - SSE 事件流

新增类型:

• YaoType - 爻类型
• DivinationParams - 起卦参数
• DivinationResultData - 解卦结果数据
• GanzhiData - 干支信息
• YaoLineData - 爻线数据

API 路由: web/src/lib/api-routes.ts

• agent.runs - POST /api/v1/agent/runs
• agent.runEvents - GET /api/v1/agent/runs/{threadId}/events

4. 解卦结果页面 ✅

组件文件: web/src/components/DivinationResultPage.tsx

子组件:

• SignCard - 签文图片和标题
• KeywordCard - 关键词卡片
• AnalysisCard - 分析卡片（结论、建议、解析）
• FocusPointsCard - 关注要点卡片
• WarningCard - AI 警告提示
• InfoCard - 基础信息卡片
• GanzhiCard - 干支信息卡片（月建、日辰、月破、日冲、五行旺衰表、空亡表）
• HexagramDetailCard - 卦象详情卡片（本卦/变卦六爻详情）
• FollowUpPanel - 追问入口面板

路由文件:

• web/src/pages/zh/divination/result.astro
• web/src/pages/zh_Hant/divination/result.astro
• web/src/pages/en/divination/result.astro

5. i18n 扩展 ✅

修改文件: web/src/i18n/utils.ts

• 添加 result 翻译类型定义
• 添加简中、繁中、英文的解卦结果页面翻译

修改文件: web/src/components/DashboardApp.tsx

• 导入 DivinationResultPage 组件
• 添加 result 翻译类型
• 添加 /divination/result 路由

修改文件: web/src/components/DashboardAppPage.astro

• 传递 result 翻译到 DashboardApp

技术约束

前端

• React 19 + Tailwind CSS
• SSE 使用原生 fetch + ReadableStream
• 遵循 web/src/i18n/utils.ts 的 i18n 模式

后端契约

• 参考 Flutter apps/lib/features/divination/data/apis/divination_api.dart
• 参考 Flutter apps/lib/features/divination/data/models/divination_result.dart

验收标准

1. ✅ 点击"开始解卦"显示处理蒙版
2. ✅ 翻牌动画流畅，卡片文本正确显示
3. ✅ 后端 API 对接成功，正确处理 SSE 事件
4. ✅ 解卦结果页面正确渲染后端返回数据
5. ✅ 简中/繁中/英文三种语言切换正常