# BingPaper WebApp

BingPaper 的前端 Web 应用，使用 Vue 3 + TypeScript + Vite 构建。

> 💡 **性能优化提示**：已配置浏览器缓存优化，可减少 60-80% 带宽！  
> 👉 后端配置：查看 [缓存配置快速参考](./CACHE_QUICK_REF.md)

## 特性

- ✨ Vue 3 组合式 API
- 🎨 Tailwind CSS + shadcn-vue 组件库
- 📦 TypeScript 类型支持
- 🔧 完整的 API 客户端封装
- 🚀 优化的构建配置
- ⚡ 浏览器缓存优化（内容哈希 + 代码分割）
- 🌐 支持自定义后端路径
- 📁 自动输出到上级目录的 web 文件夹
- 🔐 完整的管理后台系统（Token 管理、定时任务、系统配置）

## 快速开始

### 安装依赖

```bash
npm install
```

### 开发环境

```bash
npm run dev
```

开发服务器会在 `http://localhost:5173` 启动，并自动代理 `/api` 请求到后端服务器。

### 构建生产版本

```bash
npm run build
```

构建产物会自动输出到项目上级目录的 `web` 文件夹，供 Go 服务器使用。

### 预览构建结果

```bash
npm run preview
```

## 构建配置

### 环境变量

项目支持通过环境变量配置后端 API 路径：

- `.env` - 默认配置
- `.env.development` - 开发环境配置
- `.env.production` - 生产环境配置

修改 `VITE_API_BASE_URL` 来自定义后端 API 路径。

### 输出目录

构建产物输出到 `../web/`，目录结构：

```
web/
├── index.html
├── assets/
│   ├── index-[hash].js
│   └── index-[hash].css
└── vite.svg
```

## API 使用

项目提供了完整的 TypeScript API 客户端：

```typescript
import { bingPaperApi } from '@/lib/api-service'

// 获取今日图片
const meta = await bingPaperApi.getTodayImageMeta()

// 获取图片列表
const images = await bingPaperApi.getImages({ limit: 10 })
```

详细的 API 使用示例请参阅 [API_EXAMPLES.md](./API_EXAMPLES.md)

## 构建说明

详细的构建配置和部署说明请参阅 [BUILD.md](./BUILD.md)

## 项目结构

```
src/
├── assets/           # 静态资源
├── components/       # Vue 组件
│   └── ui/          # shadcn-vue UI 组件库
├── composables/      # 可组合函数
│   └── useImages.ts # 图片管理相关逻辑
├── lib/             # 核心库
│   ├── api-config.ts    # API 配置
│   ├── api-service.ts   # API 服务类
│   ├── api-types.ts     # TypeScript 类型定义
│   ├── http-client.ts   # HTTP 客户端
│   └── utils.ts         # 工具函数
├── router/          # 路由配置
│   └── index.ts
├── views/           # 页面组件
│   ├── Home.vue          # 首页
│   ├── ImageView.vue     # 图片详情页
│   ├── ApiDocs.vue       # API 文档页
│   ├── AdminLogin.vue    # 管理员登录页
│   ├── Admin.vue         # 管理后台主页面
│   ├── AdminTokens.vue   # Token 管理
│   ├── AdminTasks.vue    # 定时任务管理
│   └── AdminConfig.vue   # 系统配置管理
├── App.vue          # 根组件
└── main.ts          # 入口文件
```

## 管理后台

访问 `/admin/login` 进入管理后台登录页面。

### 功能模块

#### 1. Token 管理
- 查看所有 API Token
- 创建新的 Token（支持设置过期时间）
- 启用/禁用 Token
- 删除 Token

#### 2. 定时任务管理
- 手动触发图片抓取（可指定抓取天数）
- 手动触发旧图片清理
- 查看任务执行历史

#### 3. 系统配置管理
- **JSON 编辑模式**：直接编辑配置 JSON
- **表单编辑模式**：通过友好的表单界面修改配置
- 支持的配置项：
  - 服务器配置（端口、基础 URL）
  - API 模式（本地/重定向）
  - 定时任务配置
  - 数据库配置
  - 存储配置（本地/S3/WebDAV）
  - 图片保留策略
  - Token 配置
  - 日志配置
  - 功能特性开关

#### 4. 密码管理
- 修改管理员密码
- 安全退出登录

### 安全特性
- 基于 JWT Token 的身份验证
- Token 过期自动跳转登录页
- 路由守卫保护管理页面
- 密码修改后强制重新登录

## 项目结构

```
src/
├── lib/              # 核心库
│   ├── api-config.ts    # API 配置
│   ├── api-types.ts     # TypeScript 类型定义
│   ├── api-service.ts   # API 服务封装
│   ├── http-client.ts   # HTTP 客户端
│   └── utils.ts        # 工具函数
├── components/       # Vue 组件
│   └── ui/          # UI 组件库
├── views/           # 页面视图
├── assets/          # 静态资源
├── App.vue          # 根组件
└── main.ts          # 入口文件
```

## 📚 文档

### 核心文档
- [README.md](./README.md) - 项目概览（本文件）
- [BUILD.md](./BUILD.md) - 构建说明
- [USAGE.md](./USAGE.md) - 使用指南

### 性能优化 ⚡
- [CACHE_QUICK_REF.md](./CACHE_QUICK_REF.md) - **缓存配置快速参考**（推荐从这里开始）
- [CACHE_CONFIG.md](./CACHE_CONFIG.md) - 详细的缓存配置指南
- [CACHE_OPTIMIZATION_SUMMARY.md](./CACHE_OPTIMIZATION_SUMMARY.md) - 优化总结
- [CACHE_TEST.html](./CACHE_TEST.html) - 缓存测试页面

### API 相关
- [CORS_CONFIG.md](./CORS_CONFIG.md) - CORS 配置
- [API_EXAMPLES.md](./API_EXAMPLES.md) - API 使用示例

### 其他
- [CHANGELOG.md](./CHANGELOG.md) - 更新日志