|
| 1 | +# TrailSnap 官网设计文档 |
| 2 | + |
| 3 | +## 1. 官网功能介绍 |
| 4 | + |
| 5 | +TrailSnap 官网旨在为用户和开发者提供一个全面了解、使用和参与 TrailSnap 项目的平台。官网主要具备以下功能: |
| 6 | + |
| 7 | +- **项目展示 (Landing Page)**: 通过现代化的落地页,展示 TrailSnap 的核心功能(AI 相册、智能分类、足迹地图、票据识别等),吸引用户尝试。 |
| 8 | +- **用户文档**: 提供详细的用户操作指南,帮助普通用户快速上手,了解如何导入照片、管理相册、使用 AI 功能。 |
| 9 | +- **开发者文档**: 为贡献者和二次开发者提供架构设计、技术栈分析、环境搭建和部署指南。 |
| 10 | +- **常见问题 (FAQ)**: 汇总用户在使用过程中可能遇到的问题及解决方案。 |
| 11 | +- **版本更新**: 展示项目的更新日志和未来规划。 |
| 12 | + |
| 13 | +## 2. 官网文档结构 |
| 14 | + |
| 15 | +官网文档基于 VitePress 构建,文档内容来源于项目 `doc` 目录下的现有设计文档,并进行结构化整理。 |
| 16 | + |
| 17 | +### 2.1 架构设计文档 |
| 18 | +- **内容来源**: `doc/architecture_design.md` |
| 19 | +- **主要内容**: |
| 20 | + - 整体架构图 (Mermaid) |
| 21 | + - 前后端分离架构说明 |
| 22 | + - AI 微服务交互流程 |
| 23 | + - 技术选型及版本 (Frontend, Backend, AI, Database) |
| 24 | + - 目录结构说明 |
| 25 | + |
| 26 | +### 2.2 前端框架分析 |
| 27 | +- **内容来源**: `doc/frontend_analysis.md` |
| 28 | +- **主要内容**: |
| 29 | + - 技术栈拆解 (Vue 3, TypeScript, Vite, Element Plus, TailwindCSS, Pinia) |
| 30 | + - 组件层级关系图 |
| 31 | + - 性能指标与优化分析 |
| 32 | + - 前端与后端交互示意图 |
| 33 | + |
| 34 | +### 2.3 后端框架分析 |
| 35 | +- **内容来源**: `doc/backend_analysis.md` |
| 36 | +- **主要内容**: |
| 37 | + - 核心框架说明 (FastAPI, Uvicorn, SQLAlchemy, Alembic) |
| 38 | + - 服务模块划分与调用关系图 |
| 39 | + - AI 微服务调用链 |
| 40 | + - API 设计规范与现状 |
| 41 | + |
| 42 | +### 2.4 开发者文档 |
| 43 | +- **内容来源**: `doc/developer_guide.md` |
| 44 | +- **主要内容**: |
| 45 | + - 环境准备 (Node.js, Python, PostgreSQL, Docker) |
| 46 | + - 本地开发环境搭建步骤 |
| 47 | + - 数据库迁移指南 |
| 48 | + - 代码规范与贡献指南 |
| 49 | + |
| 50 | +### 2.5 用户指南 |
| 51 | +- **内容来源**: `doc/user_guide.md` |
| 52 | +- **主要内容**: |
| 53 | + - 系统登录与初始化 |
| 54 | + - 照片上传与管理 |
| 55 | + - 智能分类与搜索 |
| 56 | + - 足迹地图使用 |
| 57 | + - 票据识别与行程管理 |
| 58 | + - 年度报告生成 |
| 59 | + |
| 60 | +### 2.6 常见问题 (FAQ) |
| 61 | +- **内容规划**: |
| 62 | + - 部署常见错误 (Docker 端口冲突, 数据库连接失败) |
| 63 | + - AI 模型下载失败处理 |
| 64 | + - 浏览器兼容性说明 |
| 65 | + - 数据备份与恢复 |
| 66 | + |
| 67 | +## 3. 部署方案 |
| 68 | + |
| 69 | +### 3.1 部署平台 |
| 70 | +- **GitHub Pages**: 利用 GitHub 提供的免费静态托管服务,通过 GitHub Actions 实现自动化部署。 |
| 71 | + |
| 72 | +### 3.2 自动化部署流程 |
| 73 | +每次代码推送到 `main` 分支时,触发 GitHub Actions Workflow,执行以下步骤: |
| 74 | +1. **Checkout**: 拉取最新代码。 |
| 75 | +2. **Setup Node**: 配置 Node.js 环境。 |
| 76 | +3. **Install Dependencies**: 安装 VitePress 及相关依赖。 |
| 77 | +4. **Build**: 运行 `vitepress build` 生成静态文件。 |
| 78 | +5. **Deploy**: 将生成的静态文件 (`dist` 目录) 推送到 `gh-pages` 分支。 |
| 79 | + |
| 80 | +## 4. 目录结构规划 |
| 81 | + |
| 82 | +官网代码将存放于 `package/official-site` 目录下,保持 Monorepo 结构整洁。 |
| 83 | + |
| 84 | +``` |
| 85 | +package/official-site/ |
| 86 | +├── .vitepress/ |
| 87 | +│ ├── config.mts # VitePress 配置文件 (导航栏, 侧边栏, 主题配置) |
| 88 | +│ └── theme/ # 自定义主题样式 |
| 89 | +├── docs/ # 文档内容 (Markdown) |
| 90 | +│ ├── guide/ # 用户指南 |
| 91 | +│ │ ├── intro.md |
| 92 | +│ │ └── ... |
| 93 | +│ ├── dev/ # 开发者文档 |
| 94 | +│ │ ├── architecture.md |
| 95 | +│ │ ├── frontend.md |
| 96 | +│ │ └── backend.md |
| 97 | +│ └── public/ # 静态资源 (图片) |
| 98 | +├── index.md # 首页 (Landing Page) |
| 99 | +└── package.json # 依赖配置 |
| 100 | +``` |
0 commit comments