009.003.homepage-top-navigation.story.md 7.7 KB
Story 009.003: 首页顶部导航栏开发
Status
Ready for Review
Story
As a 用户, I want 在首页顶部看到清晰的导航菜单，包含所有主要服务类别, so that 快速找到所需的服务并浏览相关内容
Acceptance Criteria
- 首页顶部显示水平导航栏
- 导航菜单包含以下项目：首页、手机改运、八字详批、取名及改名、风水调整、职业规划、案例分享、行业资讯、道德经悟道、联系我们
- 导航栏在桌面端显示完整菜单项
- 移动端显示汉堡菜单，点击展开完整导航
- 当前页面高亮显示对应导航项
- 导航项点击后平滑跳转到对应页面或锚点
- 导航栏固定在页面顶部，滚动时保持可见
Tasks / Subtasks
- 创建导航栏组件 (AC: 1, 2)
- 在
src/client/home/components/创建Navigation.tsx组件 - 实现水平导航菜单，包含所有10个导航项
- 使用 Tailwind CSS 确保设计一致性
- 在
- 实现响应式设计 (AC: 3, 4)
- 桌面端显示完整水平导航
- 移动端实现汉堡菜单和侧边导航
- 汉堡菜单图标动画（三条线转X）
- 侧边导航滑入滑出动画（300ms ease-in-out）
- 点击外部区域关闭侧边导航
- ESC键关闭侧边导航
- 使用 Tailwind CSS 响应式断点（lg: 1024px 为桌面/移动分界）
- 添加导航交互功能 (AC: 5, 6)
- 实现当前页面高亮显示
- 添加平滑滚动到对应页面/锚点
- 集成现有路由系统
- 实现固定导航栏 (AC: 7)
- 使用 CSS
position: sticky实现固定导航 - 设置
top: 0固定在顶部 - 设置
z-index: 50确保在其他内容之上 - 添加半透明背景色增强可读性
- 确保滚动时导航栏保持可见
- 测试不同屏幕尺寸下的表现
- 使用 CSS
- 编写组件测试 (AC: 所有)
- 在
src/client/home/components/__tests__/创建Navigation.test.tsx - 测试桌面端和移动端导航显示
- 测试导航项点击行为
- 测试响应式切换
- 在
Dev Notes
技术栈信息 [Source: architecture/tech-stack.md#现有技术栈维护]
- 前端框架: React 19.1.0 + TypeScript
- 样式: Tailwind CSS 4.1.11
- UI组件库: shadcn/ui (基于Radix UI)
- 路由: React Router v7
- 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
- 构建工具: Vite 7.0.0
组件架构信息 [Source: architecture/component-architecture.md#前端组件架构]
- 组件位置:
src/client/home/components/Navigation.tsx - 共享组件位置:
src/client/components/ui/(shadcn/ui组件库) - 路由配置: 使用现有React Router v7系统
- 样式系统: 遵循现有Tailwind CSS配置
项目结构信息 [Source: architecture/source-tree.md#实际项目结构]
- 前端应用根目录:
src/client/ - 用户前台应用:
src/client/home/ - 共享组件:
src/client/components/ - 测试文件位置:
src/client/home/components/__tests__/
导航菜单项配置
需要实现的导航菜单项及路由路径：
- 首页 -
/(根路径) - 手机改运 -
/mobile-fortune - 八字详批 -
/bazi-analysis - 取名及改名 -
/naming-service - 风水调整 -
/fengshui-adjustment - 职业规划 -
/career-planning - 案例分享 -
/case-studies - 行业资讯 -
/industry-news - 道德经悟道 -
/taoism-wisdom - 联系我们 -
/contact-us
注意: 这些路由路径是临时占位符，实际实现时应与后端路由保持一致。
Testing
测试标准 [Source: architecture/testing-strategy.md#单元测试]
- 测试框架: Vitest + Testing Library
- 测试位置:
src/client/home/components/__tests__/Navigation.test.tsx - 覆盖率目标: ≥ 80%
- 测试类型: 单元测试
测试要求 [Source: architecture/testing-strategy.md#测试代码规范]
- 使用「应该...」格式描述测试行为
- 遵循Arrange-Act-Assert模式
- 测试桌面端和移动端导航显示
- 测试导航项点击行为
- 测试响应式切换功能
测试文件命名约定 [Source: architecture/testing-strategy.md#测试命名约定]
- 文件名:
Navigation.test.tsx - 描述: 明确描述测试场景和预期结果
Change Log
| Date | Version | Description | Author |
|---|---|---|---|
| 2025-09-30 | 1.0 | 初始故事创建 | Bob (SM) |
| 2025-09-30 | 1.1 | 根据PM建议改进：添加路由路径、汉堡菜单细节、固定导航实现 | Bob (SM) |
Dev Agent Record
Agent Model Used
James (dev agent)
Debug Log References
- 创建了响应式导航组件，包含桌面端和移动端适配
- 实现了汉堡菜单动画和交互功能
- 添加了滚动时背景模糊效果
- 编写了完整的测试套件
Completion Notes List
- 导航组件已成功创建并实现所有验收标准
- 使用 Tailwind CSS 实现响应式设计，桌面端显示水平导航，移动端显示汉堡菜单
- 实现了当前页面高亮显示和导航交互功能
- 导航栏使用 sticky 定位固定在页面顶部
- 所有测试通过，覆盖率良好
File List
src/client/home/components/Navigation.tsx- 导航组件主文件src/client/home/components/__tests__/Navigation.test.tsx- 导航组件测试文件
QA Results
Review Date: 2025-09-30
Reviewed By: Quinn (Test Architect)
Code Quality Assessment
导航组件实现质量优秀，代码结构清晰，遵循React最佳实践。组件实现了完整的响应式设计，包含桌面端水平导航和移动端汉堡菜单，所有验收标准均已满足。
Refactoring Performed
File:
src/client/home/components/Navigation.tsx- Change: 更新品牌名称为"辰通国学文化"
- Why: 根据用户要求更新品牌标识
- How: 保持组件功能完整，仅更新显示文本
File:
src/client/home/components/__tests__/Navigation.test.tsx- Change: 更新测试中的品牌名称断言
- Why: 确保测试与实现保持一致
- How: 将"多八多"改为"辰通国学文化"
File:
src/client/home/pages/__tests__/HomePage.test.tsx- Change: 修复测试选择器以处理导航组件集成
- Why: 导航组件集成后导致重复文本元素
- How: 使用
getAllByText和更精确的选择器
Compliance Check
- Coding Standards: ✓ 遵循TypeScript严格模式和React最佳实践
- Project Structure: ✓ 组件和测试文件位置符合项目结构规范
- Testing Strategy: ✓ 测试覆盖全面，16个测试全部通过
- All ACs Met: ✓ 所有7个验收标准均已实现
Improvements Checklist
- 更新品牌名称以符合用户要求
- 修复测试选择器以处理导航组件集成
- 验证所有测试通过
- 考虑添加E2E测试验证完整导航流程
- 未来可考虑添加键盘导航支持
Security Review
无安全风险。导航组件使用标准的React Router链接，无敏感数据处理。
Performance Considerations
性能良好。滚动事件监听使用适当的防抖处理，响应式设计优化良好。
Files Modified During Review
src/client/home/components/Navigation.tsx- 更新品牌名称src/client/home/components/__tests__/Navigation.test.tsx- 更新测试断言src/client/home/pages/__tests__/HomePage.test.tsx- 修复测试选择器
Gate Status
Gate: PASS → docs/qa/gates/009.003-homepage-top-navigation.yml Risk profile: 无重大风险 NFR assessment: 所有非功能性需求通过
Recommended Status
✓ Ready for Done
(Story owner decides final status)