file-starter/docs/stories/009.003.homepage-top-navigation.story.md

Story 009.003: 首页顶部导航栏开发

Status

Ready for Review

Story

As a 用户, I want 在首页顶部看到清晰的导航菜单，包含所有主要服务类别, so that 快速找到所需的服务并浏览相关内容

Acceptance Criteria

1. 首页顶部显示水平导航栏
2. 导航菜单包含以下项目：首页、手机改运、八字详批、取名及改名、风水调整、职业规划、案例分享、行业资讯、道德经悟道、联系我们
3. 导航栏在桌面端显示完整菜单项
4. 移动端显示汉堡菜单，点击展开完整导航
5. 当前页面高亮显示对应导航项
6. 导航项点击后平滑跳转到对应页面或锚点
7. 导航栏固定在页面顶部，滚动时保持可见

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 确保在其他内容之上
  • 添加半透明背景色增强可读性
  • 确保滚动时导航栏保持可见
  • 测试不同屏幕尺寸下的表现
• 编写组件测试 (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)