lzw-723/loongyan

Fork 0

Files

lzw-723 4cc754f5b4 添加自述文件

2026-03-21 21:17:01 +08:00

6.5 KiB

Raw Blame History

🖼️ Loongyan Web

Loongyan 相册系统的前端应用，基于 SvelteKit 5 构建，提供现代化的相册浏览体验。

✨ 功能特性

📁 相册列表 - 卡片式展示所有相册
🖼️ 照片浏览 - 网格布局展示照片，支持预览
🔍 照片详情 - 查看照片完整信息和原图
🌍 国际化 - 支持中文/英文切换（Paraglide JS）
📱 响应式设计 - 适配桌面和移动设备
⌨️ 键盘导航 - 左右键切换照片，ESC 关闭预览
🎨 UI 组件库 - 可复用的组件系统
🔐 用户认证 - Better Auth 集成

🛠️ 技术栈

技术	说明
Svelte 5	前端框架（Runes 模式）
SvelteKit 2	全栈框架
Vite 7	构建工具
Paraglide JS	国际化
Better Auth	用户认证
Drizzle ORM	数据库 ORM
SQLite	嵌入式数据库
Vitest	单元测试
Playwright	浏览器测试
mdsvex	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

安装依赖

pnpm install

开发运行

pnpm dev

# 或自动打开浏览器
pnpm dev -- --open

开发服务器将在 http://localhost:5173 启动。

⚠️ 注意: 前端需要配合后端 API 使用。开发模式下，/api 请求会自动代理到 http://localhost:8080。

构建生产版本

pnpm build

预览生产构建

pnpm preview

📡 API 配置

代理配置（开发）

开发模式下，API 请求自动代理到后端（vite.config.js）：

server: {
  proxy: {
    '/api': 'http://localhost:8080'
  }
}

API 基础路径

API 基础路径定义在 src/lib/api/client.js：

const API_BASE = '/api/v1';

可用 API 方法

方法	说明
`getAlbums()`	获取所有相册
`getAlbum(id)`	获取相册详情
`getAlbumPhotos(albumId)`	获取相册内照片
`getPhoto(id)`	获取照片详情
`getPhotoFileUrl(id)`	获取原图 URL
`getPhotoPreviewUrl(id)`	获取预览图 URL

🧪 测试

运行测试

pnpm test

单元测试

pnpm test:unit

类型检查

pnpm check

# 监听模式
pnpm check:watch

🎨 组件库

基础 UI 组件

组件	说明
`Button`	按钮组件
`Card`	卡片容器
`Container`	页面容器
`Grid`	网格布局
`Loading`	加载状态
`Empty`	空状态提示

业务组件

组件	说明
`AlbumCard`	相册卡片
`AlbumList`	相册列表
`PhotoCard`	照片卡片
`PhotoGrid`	照片网格
`BackLink`	返回链接
`PageHeader`	页面标题

🌍 国际化

支持语言

🇨🇳 中文（zh）
🇬🇧 English（en）

翻译文件

翻译文件位于 messages/ 目录：

// messages/zh.json
{
  "welcome": "欢迎"
}

// messages/en.json
{
  "welcome": "Welcome"
}

使用方法

<script>
  import * as m from '$lib/paraglide/messages';
</script>

<h1>{m.welcome()}</h1>

🔐 用户认证

项目集成 Better Auth，提供用户认证功能。

生成认证 Schema

pnpm auth:schema

数据库

使用 SQLite + Drizzle ORM：

# 生成迁移
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，会自动检测部署环境。

如需部署到特定平台，可安装对应适配器：

# 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 中配置：

import adapter from '@sveltejs/adapter-node';

const config = {
  kit: {
    adapter: adapter()
  }
};

🔗 相关链接

_{Made with ❤️ using SvelteKit}

6.5 KiB Raw Blame History Unescape Escape