XCDesktop/CONTRIBUTING.md

# 贡献指南

感谢你对 XCDesktop 项目的兴趣！我们欢迎任何形式的贡献，包括但不限于：

- 🐛 报告 Bug
- 💡 提出新功能建议
- 📝 完善文档
- 💻 提交代码修复或新功能
- 🔧 改进构建流程

## 开发环境搭建

### 前置要求

- Node.js 18+
- npm 9+
- Git

### 克隆项目

```bash
git clone https://github.com/your-repo/XCDesktop.git
cd XCDesktop
```

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
# 启动前端开发服务器
npm run dev

# 或启动完整 Electron 开发环境（推荐）
npm run electron:dev
```

### 代码检查

```bash
# 运行 ESLint
npm run lint

# 运行 TypeScript 类型检查
npm run check
```

## 代码规范

### 命名规范

- **文件命名**: 使用 kebab-case（如 `file-system.tsx`）
- **组件命名**: 使用 PascalCase（如 `FileTree.tsx`）
- **函数命名**: 使用 camelCase（如 `useFileTree`）
- **常量命名**: 使用 UPPER_SNAKE_CASE

### TypeScript 规范

- 尽量使用明确的类型定义，避免使用 `any`
- 优先使用接口（interface）而不是类型别名（type）定义对象结构
- 导出类型时使用 `export type`

### React 规范

- 使用函数组件和 Hooks
- 组件文件以 `.tsx` 为扩展名
- 纯逻辑文件以 `.ts` 为扩展名

### CSS 规范

- 使用 Tailwind CSS 进行样式开发
- 避免直接编写 CSS，优先使用 Tailwind 工具类
- 自定义样式放在组件同名的 `.module.css` 文件中

### Git 提交规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

#### 类型（type）

| 类型 | 说明 |
|------|------|
| feat | 新功能 |
| fix | Bug 修复 |
| docs | 文档更新 |
| style | 代码格式调整 |
| refactor | 代码重构 |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建或辅助工具变动 |

#### 示例

```bash
# 新功能
git commit -m "feat(file-system): 添加文件拖拽功能"

# Bug 修复
git commit -m "fix(editor): 修复数学公式渲染错误"

# 文档更新
git commit -m "docs: 更新 README 安装步骤"
```

## Pull Request 流程

### 创建分支

```bash
# 从主分支创建新分支
git checkout -b feature/your-feature-name

# 或创建修复分支
git checkout -b fix/bug-description
```

### 提交代码

```bash
# 暂存修改
git add .

# 提交修改
git commit -m "feat(module): 添加新功能"
```

### 推送分支

```bash
# 推送到远程仓库
git push origin feature/your-feature-name
```

### 创建 Pull Request

1. 访问项目仓库
2. 点击 "Compare & pull request"
3. 填写 PR 标题和描述
4. 提交 PR

### PR 标题规范

请使用与提交信息相同的格式：

```
feat(file-system): 添加文件搜索功能
fix(editor): 修复保存内容丢失问题
```

## 项目结构概览

```
XCDesktop/
├── src/                 # 前端源码
│   ├── components/      # UI 组件
│   ├── contexts/       # React Context
│   ├── hooks/          # 自定义 Hooks
│   ├── lib/            # 工具库
│   ├── modules/        # 功能模块
│   └── pages/          # 页面组件
├── api/                # 后端 API
├── electron/           # Electron 主进程
├── shared/             # 共享类型定义
└── notebook/           # 笔记存储目录
```

### 添加新模块

如需添加新功能模块，请参考以下步骤：

1. 在 `src/modules/` 下创建新模块目录
2. 在 `shared/modules/` 下定义模块配置
3. 在后端 `api/modules/` 下实现 API 接口
4. 使用模块注册系统进行注册

## 问题反馈

如果你发现了 Bug 或有新功能建议，请：

1. 搜索是否已有类似问题
2. 如果没有，创建新的 Issue
3. 使用对应的模板并提供详细信息

## 行为准则

请尊重所有参与项目的开发者，保持友好和专业的交流环境。

---

感谢你的贡献！🎉