# 实现路线图

## 开发原则

> **"做完一个模块，测试一个模块，保证每一步的实现都能使用。"**

---

## 第一阶段：基础架构搭建（第 1 步）

### 目标
搭建前后端基础架构，确保开发环境可用，前后端能正常通信。

### 任务清单

#### 1.1 后端基础架构
- [ ] 创建项目目录结构
- [ ] 初始化 Python 虚拟环境
- [ ] 安装依赖：FastAPI, SQLAlchemy, Pydantic, python-jose, passlib, bcrypt, uvicorn
- [ ] 创建 `app/main.py` - FastAPI 入口
- [ ] 创建 `app/database.py` - SQLite 连接配置
- [ ] 创建 `app/config.py` - 环境配置
- [ ] 配置 CORS 允许前端访问
- [ ] 配置自动 Swagger 文档
- [ ] 测试：启动后端，访问 `/docs` 确认文档页面正常

#### 1.2 前端基础架构
- [ ] 使用 Vite 创建 React 项目
- [ ] 安装依赖：tailwindcss, react-router, axios, swiper, lucide-react
- [ ] 配置 TailwindCSS 4
- [ ] 创建基础目录结构
- [ ] 配置 API 请求基础路径
- [ ] 测试：启动前端，确认页面正常显示

### 验收标准
```bash
# 后端启动成功
cd backend && uvicorn app.main:app --reload --port 10003
# 访问 http://localhost:10003/docs 能看到 Swagger 文档

# 前端启动成功
cd frontend && npm run dev
# 访问 http://localhost:10002 能看到默认 React 页面
```

---

## 第二阶段：数据模型与认证（第 2 步）

### 目标
建立数据库模型，实现管理员认证功能。

### 任务清单

#### 2.1 数据库模型
- [ ] 创建 `app/models/admin.py` - 管理员模型
- [ ] 创建 `app/models/home_module.py` - 首页模块模型
- [ ] 创建 `app/models/nav_menu.py` - 导航菜单模型
- [ ] 创建 `app/models/setting.py` - 系统设置模型
- [ ] 创建数据库初始化脚本
- [ ] 创建默认管理员账号 (admin/admin123)
- [ ] 测试：确认数据库表创建成功

#### 2.2 认证模块
- [ ] 创建 `app/auth.py` - JWT 认证工具
- [ ] 创建 `app/routers/auth.py` - 登录/获取信息/修改密码接口
- [ ] 创建登录依赖 `get_current_admin`
- [ ] 测试：使用 Swagger 测试登录接口

#### 2.3 后台登录页面
- [ ] 创建 `views/admin/Login.jsx`
- [ ] 实现登录表单
- [ ] 调用登录 API
- [ ] Token 本地存储
- [ ] 登录成功跳转
- [ ] 测试：能正常登录并跳转到后台

### 验收标准
```bash
# 1. 数据库初始化成功
sqlite3 backend/cms.db ".tables"
# 应显示: admins, home_modules, nav_menus, settings

# 2. 登录接口正常
curl -X POST http://localhost:10003/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
# 返回包含 token 的 JSON

# 3. 前端登录页面正常
# 访问 http://localhost:10002/admin/login 能看到登录表单
# 输入 admin/admin123 登录成功
```

---

## 第三阶段：首页模块管理（第 3 步）⭐ 核心

### 目标
实现首页模块化功能，支持后台配置，前台展示。

### 任务清单

#### 3.1 首页模块后端 API
- [ ] 创建 `app/routers/home_modules.py`
- [ ] GET `/api/home/modules` - 前台获取启用的模块
- [ ] GET `/api/admin/home/modules` - 后台获取所有模块
- [ ] GET `/api/admin/home/modules/:id` - 获取单个模块详情
- [ ] PUT `/api/admin/home/modules/:id` - 更新模块
- [ ] PUT `/api/admin/home/modules/sort` - 批量更新排序
- [ ] PUT `/api/admin/home/modules/:id/toggle` - 切换启用状态
- [ ] 测试：所有接口在 Swagger 中测试通过

#### 3.2 首页模块后台管理页面
- [ ] 创建 `views/admin/Dashboard.jsx` - 后台首页仪表盘
- [ ] 创建 `views/admin/HomeModules.jsx` - 模块列表页
  - [ ] 显示所有模块（名称、类型、排序、启用状态）
  - [ ] 拖拽排序功能
  - [ ] 启用/禁用开关
  - [ ] 编辑按钮跳转
- [ ] 创建 `views/admin/HomeModuleEdit.jsx` - 模块编辑页
  - [ ] 基础信息编辑（标题、副标题）
  - [ ] 内容编辑（根据模块类型不同表单）
  - [ ] 样式配置（背景色、内边距）
  - [ ] 保存功能
- [ ] 创建 `components/layout/AdminLayout.jsx` - 后台布局
- [ ] 测试：能在后台增删改查模块

#### 3.3 首页模块前台展示组件
- [ ] 创建 `components/modules/BannerModule.jsx` - 轮播图
- [ ] 创建 `components/modules/FeaturesModule.jsx` - 产品优势
- [ ] 创建 `components/modules/NewsModule.jsx` - 新闻动态
- [ ] 创建 `components/modules/PartnersModule.jsx` - 合作伙伴
- [ ] 创建 `components/modules/DownloadsModule.jsx` - APP下载
- [ ] 创建 `components/modules/ContactModule.jsx` - 联系方式
- [ ] 创建 `components/modules/HtmlModule.jsx` - 自定义HTML

#### 3.4 首页页面
- [ ] 创建 `views/home/Index.jsx`
- [ ] 调用 `/api/home/modules` 获取模块数据
- [ ] 根据模块类型渲染对应组件
- [ ] 按 sort_order 排序
- [ ] 过滤未启用的模块
- [ ] 测试：首页能正确展示所有启用的模块

### 验收标准
```bash
# 1. 后台能管理模块
# 访问 http://localhost:10002/admin
# 能看到模块列表，可以拖拽排序、启用/禁用、编辑内容

# 2. 前台能展示模块
# 访问 http://localhost:10002/
# 能看到按顺序排列的各个模块

# 3. 修改实时生效
# 在后台修改模块内容或顺序
# 刷新前台页面立即看到变化
```

---

## 第四阶段：导航与布局（第 4 步）

### 目标
实现导航栏和页脚，支持后台配置导航菜单。

### 任务清单

#### 4.1 导航菜单后端 API
- [ ] 创建 `app/routers/nav_menus.py`
- [ ] GET `/api/nav` - 前台获取启用菜单
- [ ] GET `/api/admin/nav` - 后台获取所有菜单
- [ ] POST `/api/admin/nav` - 创建菜单
- [ ] PUT `/api/admin/nav/:id` - 更新菜单
- [ ] DELETE `/api/admin/nav/:id` - 删除菜单

#### 4.2 导航菜单后台管理
- [ ] 创建 `views/admin/NavMenus.jsx`
- [ ] 菜单列表展示
- [ ] 新增菜单表单
- [ ] 编辑菜单
- [ ] 删除菜单确认
- [ ] 排序调整

#### 4.3 前台导航和页脚
- [ ] 创建 `components/layout/Navbar.jsx`
- [ ] 动态渲染导航菜单
- [ ] 移动端汉堡菜单
- [ ] 创建 `components/layout/Footer.jsx`
- [ ] 从 settings 读取公司信息
- [ ] 应用到所有页面

### 验收标准
```bash
# 1. 后台能管理导航
# 访问 http://localhost:10002/admin/nav
# 能增删改查导航菜单

# 2. 前台显示正确
# 访问 http://localhost:10002/
# 导航栏显示配置的菜单，点击能跳转
# 页脚显示公司信息
```

---

## 第五阶段：系统设置（第 5 步）

### 目标
实现系统设置功能，支持配置网站基本信息。

### 任务清单

#### 5.1 设置后端 API
- [ ] 创建 `app/routers/settings.py`
- [ ] GET `/api/settings` - 前台获取公开设置
- [ ] GET `/api/admin/settings` - 后台获取所有设置
- [ ] PUT `/api/admin/settings` - 批量更新设置

#### 5.2 设置后台管理
- [ ] 创建 `views/admin/Settings.jsx`
- [ ] 网站信息设置（名称、Logo、Favicon）
- [ ] 公司信息设置（地址、电话、邮箱）
- [ ] SEO 设置（标题、描述、关键词）
- [ ] 备案信息设置

#### 5.3 文件上传
- [ ] 创建 `app/routers/upload.py`
- [ ] POST `/api/upload/image` - 图片上传
- [ ] 限制文件类型和大小
- [ ] 生成唯一文件名
- [ ] 存储到 public/uploads

### 验收标准
```bash
# 1. 后台能修改设置
# 访问 http://localhost:10002/admin/settings
# 能修改网站名称、上传 Logo

# 2. 设置生效
# 修改后前台导航栏显示新 Logo
# 页脚显示新公司信息
```

---

## 第六阶段：数据迁移与优化（后续）

### 目标
导入原有网站的内容数据，优化性能和体验。

### 任务清单（暂不实现）
- [ ] 分析原网站数据结构
- [ ] 编写数据迁移脚本
- [ ] 导入新闻数据
- [ ] 导入产品数据
- [ ] 导入图片资源
- [ ] 图片懒加载优化
- [ ] SEO 优化

---

## 开发检查清单

每个步骤完成后，确认以下事项：

- [ ] 代码已提交到 Git
- [ ] 功能在本地测试通过
- [ ] API 文档已更新
- [ ] 无明显 Bug
- [ ] 代码有适当注释

---

## 端口分配

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端开发 | 5173 | Vite 默认 |
| 前端生产 | 10002 | serve 部署 |
| 后端 API | 10003 | uvicorn |

---

## 下一步行动

**当前准备开始：第一阶段 - 基础架构搭建**

等待用户确认后，开始编写代码。