---
applyTo: '**'
---
- 说中文
- 这是一个基于Avalonia的项目管理工程，目标是让非程序员也能轻松使用luban管理配置表。
- 命令行是PowerShell使用分号作为命令分隔符

## 架构说明

### 🏗️ LubanHub.Core 核心能力库
LubanHub.Core 提供了项目的底层核心能力，**优先使用这些服务**来实现功能，避免重复造轮子：

#### 📥 下载服务 (ICoreDownloadService)
- **默认下载目录**: 系统用户数据目录的LubanHub子目录 (`%AppData%\LubanHub\Downloads`)
- **目录管理**: 获取/设置下载目录
- **进度追踪**: 实时下载进度、速度、文件名显示
- **取消支持**: 支持CancellationToken取消下载
- **使用场景**: Luban版本下载、模板下载、资源文件下载

#### 📁 文件管理服务 (ICoreFileService)
- **文件操作**: 创建、删除、复制、移动文件
- **目录操作**: 创建、删除、遍历目录
- **异步读写**: ReadAllTextAsync/WriteAllTextAsync
- **信息获取**: FileInfo/DirectoryInfo
- **使用场景**: 配置文件操作、项目文件管理、模板文件处理

#### ⚙️ 进程调用服务 (ICoreProcessService)
- **同步执行**: 等待进程完成并获取输出
- **异步执行**: 实时获取stdout/stderr输出
- **后台进程**: 启动但不等待的进程
- **进程管理**: 检查进程状态、杀死进程
- **使用场景**: 调用Luban命令行、Git操作、外部工具集成

#### 🗜️ 解压缩服务 (ICoreCompressionService)
- **ZIP支持**: 完整的ZIP解压缩功能
- **进度追踪**: 解压进度回调
- **格式检测**: 自动识别压缩格式
- **扩展支持**: 预留RAR/7Z接口（需第三方库）
- **使用场景**: Luban安装包解压、模板包解压、资源包处理

#### 🔧 依赖注入集成
```csharp
// 在App.axaml.cs中已配置
services.AddCoreServices(); // 自动注册所有Core服务
```

#### ⚠️ 扩展原则
- **优先使用**: 实现新功能时，首先检查Core是否已提供相关服务
- **必要扩展**: 只有在Core无法满足需求时，才考虑扩展Core
- **接口设计**: 新增Core功能需要定义接口，保持架构一致性
- **日志集成**: 所有Core服务已集成Microsoft.Extensions.Logging

## UI设计规范

### 🎨 主题兼容性
- **深色模式支持**: 所有UI元素必须在深色主题下清晰可见，具有足够的对比度
- **浅色模式支持**: 所有UI元素必须在浅色主题下保持良好的可读性和视觉效果
- **动态主题切换**: 使用DynamicResource绑定，支持运行时主题切换
- **颜色资源化**: 避免硬编码颜色值，统一使用主题资源字典中的颜色定义

### 🎯 交互状态设计
- **主要操作按钮**: 使用主题蓝色系，在两种模式下都要突出显示
- **成功/确认状态**: 使用绿色系，表示积极操作
- **警告状态**: 使用黄色系，提醒用户注意
- **错误/删除状态**: 使用红色系，表示危险操作
- **悬停和按下状态**: 提供清晰的视觉反馈，确保在两种主题下都有足够的对比度

### 📝 文字层级
- **主要文字**: 使用主题的主要文字颜色，确保最佳可读性
- **次要文字**: 使用稍浅的颜色，但仍保持良好的可读性
- **占位符文字**: 使用更浅的颜色，明确区分占位符和实际内容
- **禁用文字**: 使用最浅的颜色，明确表示不可用状态

### 🔘 圆角规范
- **按钮圆角**: `4px`
- **输入框圆角**: `4px`
- **卡片圆角**: `5px`
- **列表项圆角**: `3px`

### 📏 间距规范
- **小间距**: `5px`
- **标准间距**: `10px`
- **中等间距**: `15px`
- **大间距**: `20px`
- **页面边距**: `20px`
- **按钮内边距**: 水平`15px` 垂直`8px`
- **导航按钮内边距**: 水平`20px` 垂直`15px`

### 🎭 动画规范
- **过渡时间**: `0.2s` (200ms)
- **缓动函数**: `ease-out`
- **支持的过渡**: 背景色、前景色、透明度

### 📱 组件规范
- **导航栏宽度**: `200px`
- **最小窗口尺寸**: 宽度`1000px` 高度`600px`
- **设计尺寸**: 宽度`1200px` 高度`800px`
- **按钮最小高度**: `36px`
- **输入框最小高度**: `32px`

### 🎪 图标使用
- 使用Emoji作为图标: 📚📁📦📱⚙️🎮📊🔧🤖➕🔄📂🌐等
- 图标大小: 导航按钮中正常大小，卡片中`40px`

### 🖱️ 交互反馈
- 所有可点击元素必须有悬停状态
- 按钮支持按下状态反馈
- 输入框支持焦点状态
- 列表项支持选中和悬停状态
- 过渡动画让交互更流畅

## 开发指导

### 📋 功能实现流程
1. **需求分析**: 明确功能需求和用户场景
2. **Core检查**: 检查LubanHub.Core是否已提供相关服务
3. **服务利用**: 优先使用Core服务实现功能逻辑
4. **UI设计**: 按照设计规范创建用户界面
5. **进度显示**: 长时间操作使用底部进度条显示状态
6. **错误处理**: 合理的异常处理和用户提示

### 🎯 常见场景示例
- **文件下载**: 使用ICoreDownloadService，进度显示在底部
- **Luban调用**: 使用ICoreProcessService执行命令行
- **配置管理**: 使用ICoreFileService读写配置文件
- **安装包处理**: 使用ICoreCompressionService解压
- **目录选择**: 集成系统文件对话框（需要时扩展Core）

### 🔄 服务扩展指南
当需要新功能且Core无法满足时：
1. 在`LubanHub.Core/Interfaces`添加接口定义
2. 在`LubanHub.Core/Services`添加实现类
3. 在`ServiceCollectionExtensions`中注册服务
4. 更新本文档说明新增能力
5. 在App层通过依赖注入使用新服务

### 📊 UI状态管理
- **ViewModelBase**: 所有ViewModel继承此基类
- **属性绑定**: 使用SetProperty方法通知UI更新
- **命令模式**: 使用RelayCommand处理用户交互
- **进度显示**: 使用DownloadProgressViewModel显示长时间操作

### 🎨 主题和样式
- **主题切换**: 使用ThemeManager管理深色/浅色主题
- **资源绑定**: 所有颜色使用DynamicResource绑定
- **样式复用**: 在Styles.axaml中定义通用样式
- **响应式**: 支持运行时主题切换