项目

一般

简介

行为
历史记录

技术方案 » 历史记录 » 修订 1

修订 1/2 | 下一页 »
郑毅洁, 2026-02-26 16:43

技术方案

架构

前端 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

由 郑毅洁 更新于 大约 2 个月 之前 · 2 修订