325 lines
6.5 KiB
Markdown
325 lines
6.5 KiB
Markdown
# 🖼️ Loongyan Web
|
||
|
||
Loongyan 相册系统的前端应用，基于 [SvelteKit](https://kit.svelte.dev/) 5 构建，提供现代化的相册浏览体验。
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 📁 **相册列表** - 卡片式展示所有相册
|
||
- 🖼️ **照片浏览** - 网格布局展示照片，支持预览
|
||
- 🔍 **照片详情** - 查看照片完整信息和原图
|
||
- 🌍 **国际化** - 支持中文/英文切换（Paraglide JS）
|
||
- 📱 **响应式设计** - 适配桌面和移动设备
|
||
- ⌨️ **键盘导航** - 左右键切换照片，ESC 关闭预览
|
||
- 🎨 **UI 组件库** - 可复用的组件系统
|
||
- 🔐 **用户认证** - Better Auth 集成
|
||
|
||
---
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
| 技术 | 说明 |
|
||
|------|------|
|
||
| [Svelte 5](https://svelte.dev/) | 前端框架（Runes 模式） |
|
||
| [SvelteKit 2](https://kit.svelte.dev/) | 全栈框架 |
|
||
| [Vite 7](https://vitejs.dev/) | 构建工具 |
|
||
| [Paraglide JS](https://inlang.com/m/gerre34r/library-inlang-paraglideJs) | 国际化 |
|
||
| [Better Auth](https://www.better-auth.com/) | 用户认证 |
|
||
| [Drizzle ORM](https://orm.drizzle.team/) | 数据库 ORM |
|
||
| [SQLite](https://www.sqlite.org/) | 嵌入式数据库 |
|
||
| [Vitest](https://vitest.dev/) | 单元测试 |
|
||
| [Playwright](https://playwright.dev/) | 浏览器测试 |
|
||
| [mdsvex](https://mdsvex.pngwn.io/) | Markdown 组件 |
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
web/
|
||
├── src/
|
||
│ ├── lib/
|
||
│ │ ├── api/ # API 客户端
|
||
│ │ │ ├── client.js # API 请求封装
|
||
│ │ │ └── types.js # 类型定义
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ │ ├── album/ # 相册组件
|
||
│ │ │ ├── photo/ # 照片组件
|
||
│ │ │ ├── layout/ # 布局组件
|
||
│ │ │ └── ui/ # 基础 UI 组件
|
||
│ │ ├── paraglide/ # 国际化生成文件
|
||
│ │ └── server/ # 服务端代码
|
||
│ │ ├── auth.js # 认证配置
|
||
│ │ └── db/ # 数据库
|
||
│ ├── routes/ # 页面路由
|
||
│ │ ├── +layout.svelte # 根布局
|
||
│ │ ├── +page.svelte # 首页（相册列表）
|
||
│ │ ├── album/[id]/ # 相册详情页
|
||
│ │ ├── photo/[id]/ # 照片详情页
|
||
│ │ └── demo/ # 演示页面
|
||
│ └── app.html # HTML 模板
|
||
├── messages/ # 国际化翻译文件
|
||
│ ├── en.json
|
||
│ └── zh.json
|
||
├── static/ # 静态资源
|
||
├── package.json
|
||
├── svelte.config.js
|
||
├── vite.config.js
|
||
└── drizzle.config.js
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+
|
||
- pnpm（推荐）或 npm
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 开发运行
|
||
|
||
```bash
|
||
pnpm dev
|
||
|
||
# 或自动打开浏览器
|
||
pnpm dev -- --open
|
||
```
|
||
|
||
开发服务器将在 `http://localhost:5173` 启动。
|
||
|
||
> ⚠️ **注意**: 前端需要配合后端 API 使用。开发模式下，`/api` 请求会自动代理到 `http://localhost:8080`。
|
||
|
||
### 构建生产版本
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
### 预览生产构建
|
||
|
||
```bash
|
||
pnpm preview
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 API 配置
|
||
|
||
### 代理配置（开发）
|
||
|
||
开发模式下，API 请求自动代理到后端（`vite.config.js`）：
|
||
|
||
```js
|
||
server: {
|
||
proxy: {
|
||
'/api': 'http://localhost:8080'
|
||
}
|
||
}
|
||
```
|
||
|
||
### API 基础路径
|
||
|
||
API 基础路径定义在 `src/lib/api/client.js`：
|
||
|
||
```js
|
||
const API_BASE = '/api/v1';
|
||
```
|
||
|
||
### 可用 API 方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `getAlbums()` | 获取所有相册 |
|
||
| `getAlbum(id)` | 获取相册详情 |
|
||
| `getAlbumPhotos(albumId)` | 获取相册内照片 |
|
||
| `getPhoto(id)` | 获取照片详情 |
|
||
| `getPhotoFileUrl(id)` | 获取原图 URL |
|
||
| `getPhotoPreviewUrl(id)` | 获取预览图 URL |
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
### 单元测试
|
||
|
||
```bash
|
||
pnpm test:unit
|
||
```
|
||
|
||
### 类型检查
|
||
|
||
```bash
|
||
pnpm check
|
||
|
||
# 监听模式
|
||
pnpm check:watch
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 组件库
|
||
|
||
### 基础 UI 组件
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| `Button` | 按钮组件 |
|
||
| `Card` | 卡片容器 |
|
||
| `Container` | 页面容器 |
|
||
| `Grid` | 网格布局 |
|
||
| `Loading` | 加载状态 |
|
||
| `Empty` | 空状态提示 |
|
||
|
||
### 业务组件
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| `AlbumCard` | 相册卡片 |
|
||
| `AlbumList` | 相册列表 |
|
||
| `PhotoCard` | 照片卡片 |
|
||
| `PhotoGrid` | 照片网格 |
|
||
| `BackLink` | 返回链接 |
|
||
| `PageHeader` | 页面标题 |
|
||
|
||
---
|
||
|
||
## 🌍 国际化
|
||
|
||
### 支持语言
|
||
|
||
- 🇨🇳 中文（zh）
|
||
- 🇬🇧 English（en）
|
||
|
||
### 翻译文件
|
||
|
||
翻译文件位于 `messages/` 目录：
|
||
|
||
```json
|
||
// messages/zh.json
|
||
{
|
||
"welcome": "欢迎"
|
||
}
|
||
|
||
// messages/en.json
|
||
{
|
||
"welcome": "Welcome"
|
||
}
|
||
```
|
||
|
||
### 使用方法
|
||
|
||
```svelte
|
||
<script>
|
||
import * as m from '$lib/paraglide/messages';
|
||
</script>
|
||
|
||
<h1>{m.welcome()}</h1>
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 用户认证
|
||
|
||
项目集成 Better Auth，提供用户认证功能。
|
||
|
||
### 生成认证 Schema
|
||
|
||
```bash
|
||
pnpm auth:schema
|
||
```
|
||
|
||
### 数据库
|
||
|
||
使用 SQLite + Drizzle ORM：
|
||
|
||
```bash
|
||
# 生成迁移
|
||
pnpm drizzle-kit generate
|
||
|
||
# 执行迁移
|
||
pnpm drizzle-kit migrate
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 脚本命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `pnpm dev` | 启动开发服务器 |
|
||
| `pnpm build` | 构建生产版本 |
|
||
| `pnpm preview` | 预览生产构建 |
|
||
| `pnpm test` | 运行测试 |
|
||
| `pnpm test:unit` | 运行单元测试 |
|
||
| `pnpm check` | 类型检查 |
|
||
| `pnpm lint` | 代码检查 |
|
||
| `pnpm format` | 格式化代码 |
|
||
| `pnpm auth:schema` | 生成认证 Schema |
|
||
|
||
---
|
||
|
||
## 📦 部署
|
||
|
||
### 适配器
|
||
|
||
默认使用 `@sveltejs/adapter-auto`，会自动检测部署环境。
|
||
|
||
如需部署到特定平台，可安装对应适配器：
|
||
|
||
```bash
|
||
# Vercel
|
||
pnpm add -D @sveltejs/adapter-vercel
|
||
|
||
# Netlify
|
||
pnpm add -D @sveltejs/adapter-netlify
|
||
|
||
# Node.js
|
||
pnpm add -D @sveltejs/adapter-node
|
||
|
||
# 静态站点
|
||
pnpm add -D @sveltejs/adapter-static
|
||
```
|
||
|
||
然后在 `svelte.config.js` 中配置：
|
||
|
||
```js
|
||
import adapter from '@sveltejs/adapter-node';
|
||
|
||
const config = {
|
||
kit: {
|
||
adapter: adapter()
|
||
}
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [后端 API 文档](../README.md#-api-文档)
|
||
- [SvelteKit 文档](https://kit.svelte.dev/docs)
|
||
- [Svelte 5 文档](https://svelte-5-preview.vercel.app/)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>Made with ❤️ using SvelteKit</sub>
|
||
</div> |