# 开发指南

本指南是本地开发流程的权威入口。贡献协作规则见 `../../CONTRIBUTING.md`，AI agent 长期规则见 `../../AGENTS.md`。

## 环境准备

### 安装依赖

#### 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
```

#### 自托管 Gitea runner

`.gitea/workflows/bat.yml` 使用 `runs-on: linux`，并且不依赖 `actions/checkout`、`dtolnay/rust-toolchain` 等外部 GitHub Action。runner 需要在执行环境中预装以下命令：

```bash
git --version
rustc --version
cargo --version
rustfmt --version
cargo clippy --version
```

该 workflow 会用 `GITHUB_SERVER_URL`、`GITHUB_REPOSITORY`、`GITHUB_REF` 和 `GITHUB_SHA` 手动 `git fetch` 当前提交，再执行 Rust workspace 的格式化、检查、构建、clippy 和测试。这样可以避免自托管 runner 在准备阶段通过代理克隆第三方 action 仓库。

#### 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
```

开发约束：

1. 先阅读相关文档和代码，再判断实现方式。
2. 跨模块、架构、数据格式或用户工作流变更必须先说明设计取舍。
3. 保持改动聚焦，不做无关重构、批量格式化或元数据 churn。
4. 公共接口、状态文件、manifest、catalog、patch 和下载流程变更必须补充测试或 fixture。
5. 用户可见命令、运行路径、配置、状态文件、日志或缺口状态变化时，同步更新 README、指南、架构文档或 `docs/reports/CURRENT_GAPS.md`。

### 3. 提交

```bash
git add .
git commit -m "feat(cli): 添加 doctor 命令骨架"
```

提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
- 必须使用 `type(scope): 中文说明` 格式。
- `type` 使用 `feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore` 等 Conventional Commits 类型。
- `scope` 必须写具体模块或文档域，例如 `ffi`、`docs`、`cli`、`cas`、`official-sync`。
- 提交标题和正文默认使用简体中文；代码标识符、协议字段和命令参数仍保持英文。

示例：

- `feat(cli): 添加 doctor 命令骨架`
- `fix(docs): 修正官方同步运行说明`
- `refactor(ffi): 降级 FFI 为可选兼容层`

### 4. 推送和 PR

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

---

## 代码规范

默认使用简体中文写文档、提交说明、开发日志和面向用户的说明。代码标识符、协议字段、数据库字段、包名和命令参数保持英文命名规范。

禁止使用 demo、临时实现、硬编码路径或只为当前测试通过的伪实现。确实未完成的能力应写入当前缺口文档，而不是用 `TODO` 或 `FIXME` 隐藏。

### 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 fmt --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
go test ./...
go vet ./...
```

Go 产品入口尚未完成，但仓库已有 `cmd/bat` 与 `internal/ffi` 骨架。提交前应运行 `go test ./...` 和 `go vet ./...`；目前输出可能只有 `[no test files]`，这代表缺少 Go 产品测试覆盖，不代表 Go CLI 已完成。

### 常用聚焦命令

```bash
cargo test -p bat-core -- --nocapture
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
cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets -- -D warnings
```

官方资源同步、下载、daemon、status、verify 或 repair 相关改动必须至少覆盖 `bat-infrastructure` 和 `bat` 二进制测试。

`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 导出、JSON schema、错误返回或 `internal/ffi` CGO 包装时必须运行 `cargo test -p bat-ffi -- --nocapture`；未来 Go 产品入口和生产同步默认应通过 Rust `bat --json` 或 daemon RPC 进程边界集成。

### 集成测试

```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` 或其他隔离目录，不要写入现有资源目录。

生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。

### 基准测试

```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 兼容层问题

`bat-ffi` 不是主集成边界，只用于需要 C ABI 的兼容场景。未来 Go 产品入口集成优先运行 Rust `bat --json` 或调用 daemon RPC。

重新构建兼容库：
```bash
cd crates/bat-ffi
cargo build
```

---

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