Kodev 官方网站建设 (Next.js + Tailwind)

# 技术方案

## 架构

前端 React SPA (Vite + React + TypeScript + Tailwind CSS) + 后端 Go REST API (Gin框架) + PostgreSQL，前端由 nginx 托管静态文件，后端提供 API 服务，通过 Docker Compose 编排所有服务

## 基础设施

| 类型 | 镜像 | 别名 |

|------|------|------|

| postgres | postgres:15-alpine | postgres |

## 子任务

### 1. 首页开发

开发 Kodev 官网首页，包含以下内容和UI要求：

**页面结构：**

1. 顶部导航栏（Logo + 导航链接：首页/功能/文档/关于 + 深色/浅色主题切换按钮），桌面端水平排列，移动端汉堡菜单

2. Hero 区域：大标题介绍 Kodev 产品定位，副标题简短描述核心价值，两个 CTA 按钮（'立即体验' 主按钮 + '查看文档' 次按钮），背景使用渐变色或抽象几何图形装饰

3. 核心特性展示区：以 3~4 列卡片网格布局展示产品核心特性，每张卡片包含图标、标题和简短描述，移动端改为单列堆叠

4. 底部 Footer：版权信息、快速链接、社交媒体图标

**UI设计要求：**

- 主色调使用科技蓝(#2563EB)，辅助色使用靛蓝(#4F46E5)

- 深色主题背景使用 #0F172A，浅色主题背景使用 #FFFFFF

- 所有交互元素需有 hover/focus 状态反馈

- 使用 Tailwind CSS 实现响应式布局，断点：sm(640px), md(768px), lg(1024px)

- 页面切换和元素出现使用平滑过渡动画

- 字体使用 Inter 或系统默认无衬线字体

**技术要求：**

- 使用 React Router 配置路由

- 实现深色/浅色主题切换（使用 React Context + Tailwind dark mode）

- 提取公共布局组件（Header、Footer）供所有页面复用

- 配置 SEO meta tags（使用 react-helmet-async）

- 首页数据从后端 API 获取（GET /api/v1/pages/home）

分支后缀: `homepage`

### 2. 功能页开发

开发功能详情展示页面，详细介绍 Kodev 产品的所有功能模块。

**页面结构：**

1. 页面顶部 Banner：标题'产品功能'，简短引导文案

2. 功能分类导航：水平标签栏或侧边栏，支持按分类筛选功能

3. 功能列表区域：每个功能模块以左右交替布局展示（奇数行图左文右，偶数行文左图右），包含功能标题、详细描述、功能截图/示意图占位区域

4. 功能对比表格（可选）：以表格形式对比不同版本/方案的功能差异

**UI设计要求：**

- 功能卡片使用圆角(rounded-xl)、轻微阴影(shadow-md)，深色模式下使用边框(border-gray-700)替代阴影

- 截图区域使用 16:9 或 4:3 比例的占位容器，带圆角和阴影模拟浏览器窗口效果

- 功能图标使用 Heroicons 或 Lucide React 图标库

- 列表项进入视口时触发淡入上移动画（使用 Intersection Observer 或 framer-motion）

- 移动端所有内容改为单列纵向堆叠

**技术要求：**

- 功能列表数据从后端 API 获取（GET /api/v1/features）

- 支持按分类过滤（query param: ?category=xxx）

- 图片使用懒加载优化性能

- 页面 SEO meta tags 配置

分支后缀: `features-page`

### 3. 文档页开发

开发技术文档页面，支持 Markdown 内容渲染，提供良好的文档阅读体验。

**页面结构：**

1. 左侧边栏：文档目录树，支持多级嵌套展开/折叠，当前阅读文档高亮，移动端改为顶部下拉菜单或抽屉式侧边栏

2. 中间主内容区：渲染 Markdown 文档内容，支持标题、段落、代码块（带语法高亮）、表格、图片、链接、列表等

3. 右侧目录（桌面端）：当前文档的 TOC（Table of Contents），滚动时自动高亮当前章节

**UI设计要求：**

- 文档页采用三栏布局（侧边栏240px + 主内容区自适应 + TOC 200px），移动端隐藏两侧栏

- 代码块使用等宽字体，深色背景(bg-gray-900)，支持一键复制按钮

- 代码语法高亮使用 Prism.js 或 highlight.js，支持常见语言（JavaScript, TypeScript, Go, SQL, YAML, Bash）

- Markdown 渲染后的排版遵循良好的阅读体验：行高1.75，段落间距适当，标题层级清晰

- 搜索框（可选）：支持文档内关键字搜索

**技术要求：**

- 使用 react-markdown + remark-gfm 渲染 Markdown

- 使用 rehype-highlight 或 react-syntax-highlighter 实现代码高亮

- 文档目录结构和内容从后端 API 获取（GET /api/v1/docs/tree, GET /api/v1/docs/:slug）

- 后端从数据库或文件系统读取 Markdown 文件

- 实现 URL 路由与文档 slug 映射（/docs/:slug）

- 页面 SEO meta tags 配置

分支后缀: `docs-page`

### 4. 关于页开发

开发团队介绍页面，展示 Kodev 团队成员和公司信息。

**页面结构：**

1. 页面顶部 Banner：标题'关于我们'，公司使命/愿景描述

2. 公司介绍区域：一段介绍 Kodev 公司背景、发展历程的文字内容，可配合时间线组件展示里程碑

3. 团队成员展示区：卡片网格布局（桌面端3~4列，移动端1~2列），每张卡片包含头像（圆形裁剪）、姓名、职位、简短介绍

4. 联系信息区域：公司邮箱、社交媒体链接、办公地址（可选）

**UI设计要求：**

- 团队成员卡片使用圆角、hover 时轻微上浮效果(transform: translateY(-4px))和阴影增强

- 头像使用圆形裁剪(rounded-full)，尺寸 96x96 或 128x128

- 时间线组件使用左侧竖线 + 圆点标记 + 右侧内容的经典布局

- 联系区域使用图标+文字的组合排列

- 整体风格保持与其他页面一致的设计语言

**技术要求：**

- 团队成员数据从后端 API 获取（GET /api/v1/team）

- 公司信息从后端 API 获取（GET /api/v1/about）

- 头像图片支持懒加载

- 页面 SEO meta tags 配置

分支后缀: `about-page`

### 5. 后端 API 开发

使用 Go + Gin 框架开发所有后端 REST API 接口，连接 PostgreSQL 数据库。

**API 接口列表：**

1. GET /api/v1/pages/home - 获取首页内容（Hero文案、核心特性列表）

2. GET /api/v1/features - 获取功能列表，支持 ?category= 查询参数过滤

3. GET /api/v1/features/:id - 获取单个功能详情

4. GET /api/v1/docs/tree - 获取文档目录树结构

5. GET /api/v1/docs/:slug - 获取单篇文档的 Markdown 内容

6. GET /api/v1/team - 获取团队成员列表

7. GET /api/v1/about - 获取公司介绍信息

8. GET /api/v1/sitemap - 生成 sitemap.xml 数据

**数据库设计：**

- pages 表：id, slug, title, content(JSONB), created_at, updated_at

- features 表：id, title, description, category, icon, image_url, sort_order, created_at

- docs 表：id, slug, title, content(TEXT/Markdown), parent_id(自引用实现目录树), sort_order, created_at, updated_at

- team_members 表：id, name, role, bio, avatar_url, sort_order, created_at

**技术要求：**

- 使用 GORM 作为 ORM 操作 PostgreSQL

- 数据库迁移使用 GORM AutoMigrate 或 golang-migrate

- 提供 seed 脚本填充初始示例数据

- API 响应统一使用 JSON 格式，包含 code/message/data 结构

- 配置 CORS 允许前端跨域访问

- 错误处理中间件统一处理异常

- 环境变量配置数据库连接信息（DATABASE_URL）

分支后缀: `backend-api`

### 6. 主题切换与SEO优化

实现全局深色/浅色主题切换功能，以及完整的 SEO 优化配置。

**主题切换功能：**

1. 使用 React Context 创建 ThemeProvider，管理 dark/light 主题状态

2. 主题偏好持久化到 localStorage，首次访问时跟随系统偏好（prefers-color-scheme）

3. Tailwind CSS dark mode 使用 class 策略，ThemeProvider 控制 html 元素的 dark 类名

4. 切换按钮使用太阳/月亮图标，带平滑过渡动画

5. 所有页面组件的颜色使用 Tailwind 的 dark: 变体适配

**SEO优化：**

1. 使用 react-helmet-async 为每个页面设置独立的 title、description、keywords meta tags

2. 配置 Open Graph 标签（og:title, og:description, og:image）用于社交媒体分享

3. 生成 sitemap.xml（从后端 /api/v1/sitemap 获取数据，构建为静态文件或动态路由）

4. 配置 robots.txt

5. 语义化 HTML 标签（header, nav, main, section, article, footer）

6. 图片添加 alt 属性

7. 页面标题使用合理的 h1~h6 层级结构

**UI设计要求：**

- 主题切换按钮放置在导航栏右侧，图标尺寸20x20

- 切换时全局颜色过渡时间 200ms

- 确保深色和浅色主题下所有文字与背景的对比度符合 WCAG AA 标准（至少4.5:1）

分支后缀: `theme-and-seo`