# 🖼️ 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
{m.welcome()}
```
---
## 🔐 用户认证
项目集成 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/)
---
Made with ❤️ using SvelteKit