# 开发指南

## 环境准备

### 安装依赖

#### Go
```bash
# 安装 Go 1.22+
# 参考：https://golang.org/doc/install

go version  # 验证安装
```

#### Rust
```bash
# 安装 Rust 1.75+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustc --version  # 验证安装
cargo --version
```

#### Docker
```bash
# 安装 Docker 和 Docker Compose
# 参考：https://docs.docker.com/get-docker/

docker --version
docker compose version
```

---

## 项目结构

请参考 [架构文档](../architecture/README.md) 了解完整的项目结构。

---

## 开发工作流

### 1. 创建功能分支

```bash
git checkout -b feature/your-feature-name
```

### 2. 开发

```bash
# 实时编译检查
make check

# 运行测试
make test

# 格式化代码
make fmt
```

### 3. 提交

```bash
git add .
git commit -m "feat: 添加新功能"
```

提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
- `feat:` 新功能
- `fix:` 修复 bug
- `docs:` 文档更新
- `style:` 代码格式（不影响功能）
- `refactor:` 重构
- `test:` 测试相关
- `chore:` 构建工具或辅助工具

### 4. 推送和 PR

```bash
git push origin feature/your-feature-name
# 然后在 GitHub 创建 Pull Request
```

---

## 代码规范

### Go
- 遵循 [Effective Go](https://golang.org/doc/effective_go)
- 使用 `gofmt` 格式化
- 使用 `golangci-lint` 进行静态检查

### Rust
- 遵循 [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- 使用 `cargo fmt` 格式化
- 使用 `cargo clippy` 进行静态检查

### TypeScript
- 遵循 [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
- 使用 ESLint 和 Prettier

---

## 测试

### 当前必跑测试

```bash
cargo test -p bat-adapters -- --nocapture
cargo test -p bat-ffi -- --nocapture
cargo test -p bat-infrastructure -- --nocapture
cargo test -p bat-infrastructure --bin bat -- --nocapture
```

Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。

### 集成测试

```bash
cargo test --workspace
```

带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 `BAT_REAL_*` 环境变量读取隔离样本路径。不要默认读取 `/home/wanye/D/BlueArchive` 或任何已有客户端目录。

### 官方资源同步手动检查

查看参数：

```bash
cargo run -p bat-infrastructure --bin bat -- --help
```

dry-run：

```bash
cargo run -p bat-infrastructure --bin bat -- \
  --auto-discover \
  --dry-run
```

开发环境真实下载默认写入 `./bat-resources`；如果要覆盖，必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。

### 基准测试

```bash
make bench
```

---

## 调试

### Go
使用 Delve 调试器：
```bash
go install github.com/go-delve/delve/cmd/dlv@latest
dlv debug ./cmd/bat
```

### Rust
使用 rust-lldb 或 rust-gdb：
```bash
rust-lldb target/debug/bat-cas-engine
```

---

## 常见问题

### 1. 编译失败

确保安装了所有依赖：
```bash
go mod download
cargo fetch
```

### 2. 测试失败

先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。

### 3. FFI 绑定问题

重新生成绑定：
```bash
cd crates/bat-ffi
cargo build
```

---

更多当前状态请查看 [当前状态](../../CURRENT_STATUS.md) 和 [当前缺口清单](../reports/CURRENT_GAPS.md)。