.cursorrules

# Roon 艺术墙项目开发规范

## 重要规则
- 严格保护现有的 Roon 图片抓取功能
- 不得修改 package.json 中的 Roon 相关依赖

- 艺术墙项目必须作为独立模块开发
- 艺术墙服务必须使用3090端口

## 项目目标
构建一个高性能、优雅的专辑封面展示墙，通过3D翻转动画效果展示音乐艺术。

## 第一性原理

### 1. 目标明确
- 展示目录：art/Albums/下的所有专辑封面
- 显示要求：全屏自适应，满屏显示
- 更新周期：每60秒自动更换一批
- 动画效果：3D扑克牌翻转效果
- 性能目标：流畅无卡顿，快速响应

### 2. 挑战假设
- 质疑传统网格布局方案
- 重新思考图片加载策略
- 探索最优的动画实现方式

### 3. 从零开始
- 不依赖重型框架
- 最小化依赖
- 自主实现核心功能

### 4. 关注本质
- 核心功能：展示和动画
- 关键指标：性能和用户体验
- 避免过度设计

### 5. 推演可行性
- 验证性能瓶颈
- 确保动画流畅度
- 测试内存占用

## Unix 哲学

### 1. 小而精
- 组件化设计
- 功能模块独立
- 代码精简高效

### 2. 组合为王
- 模块解耦
- 接口标准化
- 便于扩展

### 3. 文本为本
- 配置文件简单明了
- 日志清晰可读
- 代码自文档化

### 4. 沉默是金
- 只在必要时输出信息
- 错误处理优雅
- 避免冗余提示

### 5. 可复用
- 通用组件抽象
- 避免硬编码
- 接口标准化

## Python之禅

### 1. 追求优雅
- 代码结构清晰
- 命名规范统一
- 注释适度

### 2. 显式胜于隐式
- 避免魔法数字
- 配置明确声明
- 依赖清晰可见

### 3. 简洁至上
- 避免过度工程
- 删除无用代码
- 精简实现方案

### 4. 可读性优先
- 代码自解释
- 函数职责单一
- 变量命名有意义

### 5. 追求唯一
- 统一编码风格
- 一致的解决方案
- 避免重复代码

## 具体实现要求

### 前端实现
1. HTML5 + CSS3 + 原生JavaScript
2. 使用CSS Grid实现自适应布局
3. CSS 3D Transform实现翻转效果
4. 使用IntersectionObserver实现懒加载

### 性能优化
1. 图片预加载策略
2. 内存管理机制
3. DOM批量更新
4. 防抖和节流处理

### 代码组织
1. 模块化设计
2. 清晰的目录结构
3. 统一的命名规范
4. 完整的错误处理 

## 实现方案

### 系统架构
1. 纯前端方案
   - 直接使用浏览器打开HTML文件
   - 通过file://协议访问本地图片
   - 无需额外服务器支持

### 目录结构
```
art-wall/
  ├── index.html     # 主页面
  ├── css/
  │   └── style.css  # 样式文件（Grid布局、3D效果）
  └── js/
      └── main.js    # 核心逻辑（图片加载、动画控制）
```

### 技术选型
1. 显示层
   - HTML5语义化标签
   - CSS Grid自适应布局
   - CSS 3D Transform实现翻转
   - CSS变量管理主题

2. 逻辑层
   - 原生JavaScript ES6+
   - FileSystem API读取本地图片
   - RequestAnimationFrame实现动画
   - IntersectionObserver实现懒加载

3. 数据层
   - 本地存储优化（LocalStorage）
   - 内存数据结构优化
   - 图片预加载队列
   - 垃圾回收优化

### 核心功能模块
1. 布局管理器
   - 计算最优网格尺寸
   - 响应窗口大小变化
   - 维护图片显示位置

2. 资源加载器
   - 扫描本地图片目录
   - 构建图片预加载队列
   - 管理内存中的图片缓存

3. 动画控制器
   - 实现3D翻转效果
   - 控制动画时序
   - 优化动画性能

4. 定时管理器
   - 控制60秒更新周期
   - 随机选择更新图片
   - 平滑处理更新过程

### 性能优化策略
1. 资源管理
   - 图片预加载机制
   - 内存使用监控
   - 及时释放无用资源

2. 渲染优化
   - 使用GPU加速
   - 避免重排重绘
   - 优化动画性能

3. 内存优化
   - 限制同时加载的图片数量
   - 采用图片池复用机制
   - 主动触发垃圾回收

### 开发规范
1. 代码组织
   - 模块化设计
   - 单一职责原则
   - 清晰的接口定义

2. 命名规范
   - 语义化命名
   - 统一命名风格
   - 清晰的注释文档

3. 错误处理
   - 优雅降级策略
   - 完整的错误提示
   - 异常恢复机制