# 贡献指南

感谢你对 QRGen 的关注！这份指南帮助你了解如何参与项目。

## 项目架构

QRGen 是 Rust workspace，四层架构：

| crate | 用途 | 技术栈 |
|-------|------|--------|
| `qr-core` | 核心算法库 | Rust，纯算法无三方依赖 |
| `qrgen` | CLI 命令行 | clap + anyhow |
| `qrgen-gui` | 桌面应用 | Tauri 2.x + React 18 + TypeScript |
| `qrgen-web` | Web 服务 | axum 0.8 + tokio |

详细架构见 [CLAUDE.md](CLAUDE.md)。

## 开发环境

- **Rust** 1.95+ (`stable-x86_64-pc-windows-gnu` 或 `stable-x86_64-unknown-linux-gnu`)
- **Node.js** 22+（仅 GUI 前端需要）
- **pnpm**（GUI 前端包管理）

## 本地构建

```bash
# 克隆
git clone git@lhy-git.liuhangyv.top:Serendipity/QRGen.git
cd QRGen

# 安装 GUI 前端依赖
cd gui/src-frontend && pnpm install && cd ../..

# 编译检查
cargo check

# CLI
cargo build -p qrgen

# Web
cargo build -p qrgen-web

# GUI（需要前端依赖）
cd gui/src-frontend && pnpm build && cd ../..
cargo build -p qrgen-gui
```

## 提交规范

使用 Conventional Commits 格式：

```
<type>: <简短描述>

feat: 添加 Logo 图片支持
fix: 修复 PNG margin 全黑问题
refactor: 提取 fill_module 辅助函数
docs: 更新 README 安装说明
test: 添加格式信息 roundtrip 测试
```

类型：`feat` `fix` `refactor` `docs` `test` `chore` `perf` `ci`

## 代码风格

- **Rust**: `cargo fmt` + `cargo clippy -- -D warnings` 必须通过
- **TypeScript**: `pnpm tsc --noEmit` 必须通过（strict 模式）
- 注释用中文，标识符用英文

## 测试

```bash
# 全量测试
cargo test                          # 所有 crate

# 仅核心库
cargo test -p qr-core

# 特定测试
cargo test -p qr-core -- mask       # 掩码相关测试

# 覆盖率
cargo tarpaulin --out Html
```

测试覆盖率目标 ≥ 80%。

## 提交流程

1. Fork 仓库
2. 创建功能分支 (`git checkout -b feat/my-feature`)
3. 编码 + 测试（遵循 TDD）
4. `cargo fmt` + `cargo clippy -- -D warnings`
5. `cargo test` 全部通过
6. 提交并 push
7. 创建 Pull Request

## Issue 规范

- Bug 报告：附重现步骤 + 预期/实际行为
- 功能请求：描述使用场景和期望效果

## 感谢

所有贡献者将在 [README.md](README.md) 中致谢。