# 协作与提交规范

## 分支

- `main`：始终保持可构建、可部署。
- `feature/<name>`：新功能。
- `fix/<name>`：缺陷修复。
- `docs/<name>`：仅文档。

禁止直接覆盖历史标签。合并前应同步 `main` 并完成与变更风险相匹配的测试。

## 提交信息

使用 Conventional Commits：

```text
feat(inbox): add message intent toggle
fix(whatsapp): reconcile delivery status
docs(deploy): document reverse proxy setup
```

常用类型：`feat`、`fix`、`refactor`、`test`、`docs`、`chore`、`perf`、`security`。

## 变更检查

1. 不提交密钥、账号登录态、数据库、客户媒体和本地日志。
2. 更新相关接口类型、错误文案和文档。
3. 前端至少运行 `npm run typecheck` 和 `npm run build`。
4. 后端改动运行 `server` 测试；WhatsApp 改动运行网关测试。
5. 用户路径变更补充或更新 Playwright E2E。
6. 数据结构变更必须可重复执行，并说明备份与回滚步骤。

## 发布

1. 更新 `CHANGELOG.md` 和版本号。
2. 完成全量测试和 Docker 健康检查。
3. 创建带说明的版本标签：`git tag -a vX.Y.Z -m "..."`。
4. 推送分支和标签，随后按部署文档发布。