# Contributing

## 开发环境要求

- Node.js 20+
- pnpm 9+
- Go 1.22+
- Python 3.12+
- Docker Desktop
- buf 1.40+ (`go install github.com/bufbuild/buf/cmd/buf@latest`)

## 开发流程

1. 从 main 创建 feature 分支：`git checkout -b feature/xxx`
2. 开发并确保 CI 通过：`pnpm lint && pnpm test && pnpm build`
3. 提交 PR 到 main
4. CI 全绿后合并

## 提交规范

使用 Conventional Commits：

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

types: feat, fix, chore, docs, style, refactor, test, perf, ci
scope: 服务名或包名（如 api-gateway, classes, shared-proto）
```

示例：
- `feat(api-gateway): add JWT auth middleware`
- `fix(classes): resolve N+1 query in list classes`
- `docs(004): update service dependency graph`

## 文档同步

修改代码后必须：
1. 运行 `pnpm run arch:scan` 更新 arch.db
2. 若架构意图变化，更新 `docs/architecture/004_architecture_impact_map.md`
3. 若服务接口变化，更新对应 `docs/modules/<service>/README.md`
4. 若发现新经验，更新 `docs/troubleshooting/known-issues.md`