# 排障手册
## 编译失败
症状：`cargo build`、`cargo test` 或 `cargo clippy` 失败。
原因：Rust toolchain 过旧、依赖未解析、代码或生成文件不符合 workspace 约束。
解决步骤：
1. 运行 `cargo metadata --format-version 1 --no-deps` 确认 workspace 可解析。
2. 运行 `cargo fmt --all -- --check` 检查格式。
3. 运行 `cargo clippy --workspace --all-targets -- -D warnings` 查看具体 lint。
4. 按第一个错误修复，不要同时修改无关模块。
验证方式：重新运行失败命令和 `cargo test --workspace`。
## CLI 拒绝覆盖文件
症状：命令返回 `already exists`。
原因：rs-zero 生成器默认保护已有文件。
解决步骤：
1. 确认目标目录是否已有生成结果。
2. 查看现有文件是否包含手写改动。
3. 确认要覆盖后添加 `--force`。
验证方式：重新运行对应 `api gen`、`model gen`、`rpc gen` 或 `api format` 命令。
## API parser 报 unknown type
症状：`api validate` 返回 `unknown request type` 或 `unknown response type`。
原因：route 引用了未定义的 type，或 import 文件没有被正确解析。
解决步骤：
1. 检查 `.api` 中 type 名称大小写。
2. 检查 `import "..."` 是否相对当前 `.api` 文件存在。
3. 用 `cargo test -p rs-zero-cli --test goctl_api_compat` 对照兼容 fixture。
验证方式：重新运行 `cargo run -p rs-zero-cli -- api validate -f <file.api>`。
## RPC import missing
症状：`rpc gen` 返回 missing import。
原因：proto import 路径既不能相对 root proto 解析，也不能相对当前 proto 文件解析。
解决步骤：
1. 检查 import 路径拼写。
2. 确认 sibling、subdir 或 transitive import 文件存在。
3. well-known import 如 `google/protobuf/timestamp.proto` 不需要本地文件。
验证方式：运行 `cargo test -p rs-zero-cli --test goctl_rpc_compat`。
## Model parser 无法识别 SQL
症状：`model gen` 返回 schema 不包含 `CREATE TABLE` 或 parse error。
原因：输入不是当前支持的 MySQL `CREATE TABLE` 子集，或 SQL 被迁移语句包裹。
解决步骤：
1. 先提取单个 `CREATE TABLE` 验证。
2. 检查字段、索引、comment/default/on-update 是否符合常见 MySQL DDL。
3. 对照 `tests/fixtures/goctl/model/user.sql`。
验证方式：运行 `cargo test -p rs-zero-cli --test goctl_model_compat`。
## 外部 adapter 测试被 ignored
症状：测试输出显示 etcd、OTLP 等 external placeholder ignored。
原因：默认测试不依赖外部服务，这是预期行为。
解决步骤：
1. 阅读 `examples/production-adapters/README.md`。
2. 启动对应 docker compose 或外部服务。
3. 显式运行 ignored/external 测试。
验证方式：外部服务就绪后运行对应 `cargo test --ignored ...` 命令。