Skip to content

Commit 272ef70

Browse files
committed
feat(官网): 添加深色模式支持并优化移动端体验(构建文档)
- 在tailwind配置中启用class驱动的深色模式 - 为所有组件添加深色模式样式 - 隐藏移动端的返回顶部按钮 - 添加多语言标签配置 - 新增官网设计文档
1 parent bd5f3de commit 272ef70

File tree

5 files changed

+202
-82
lines changed

5 files changed

+202
-82
lines changed
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
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+
```

package/official-site/.vitepress/config.mts

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,21 @@ export default defineConfig({
4141
{ icon: 'github', link: 'https://github.com/LC044/TrailSnap' }
4242
],
4343

44+
outline: {
45+
label: '页面导航'
46+
},
47+
48+
sidebarMenuLabel: '菜单',
49+
returnToTopLabel: '回到顶部',
50+
darkModeSwitchLabel: '主题',
51+
lightModeSwitchTitle: '切换到浅色模式',
52+
darkModeSwitchTitle: '切换到深色模式',
53+
54+
docFooter: {
55+
prev: '上一页',
56+
next: '下一页'
57+
},
58+
4459
footer: {
4560
message: '基于 AGPL-3.0 许可发布',
4661
copyright: '版权所有 © 2025-至今 TrailSnap'

0 commit comments

Comments
 (0)