# Contributing Guide

本仓库已经同时包含服务端、Android 客户端、Web 客户端和本地部署脚本。后续协作必须按下面的规则执行，避免再次出现分支漂移、协议不一致、WIP PR 长期悬挂、本地调试资产误入版本库等问题。

## 基本原则

1. `main` 只接收可合并、可验证、可发布的代码。
2. 一个 `issue` 对应一个主题分支，不要在同一分支里混入多个不相关需求。
3. 本地调试资产不进 Git，包括证书、密钥、构建产物、个人环境配置。
4. 任何跨端协议改动都必须做双端联调，不能只改单边实现。
5. 没做完的工作不要以普通可合并 PR 的形式挂着；未完成状态请使用 Draft 或继续在本地分支开发。

## 分支规则

1. 新功能或修复必须从最新 `main` 切出：

```bash
git fetch origin
git checkout main
git pull --ff-only origin main
git checkout -b emilia-t/issue-<id>-<topic>
```

2. 分支名建议包含作者、issue、主题，例如：
   - `emilia-t/issue-7-audio-message`
   - `emilia-t/issue-12-notification-sound`
   - `emilia-t/issue-18-server-switching`
3. 不要长期复用一个旧分支持续堆新需求。
4. 合并前必须再次同步 `main`，优先用 `rebase`，避免无意义 merge commit：

```bash
git fetch origin
git rebase origin/main
```

## 提交规则

1. 提交应当聚焦单一目的，避免一个提交同时混入协议、UI、美术、文档、重构。
2. 提交信息必须带范围和目的，推荐格式：
   - `feat(android): add voice message playback`
   - `fix(web): parse Android audio payload correctly`
   - `docs: document local debug CA setup`
   - `chore(server): tighten message size validation`
3. 不要使用 `update`、`misc`、`fix bug` 这类无信息量的提交说明。
4. 提交前先看一遍差异，确认没有把临时调试代码、个人地址、日志打印一起带上。

## PR 规则

1. PR 标题必须描述结果，不要长期保留 `WIP:` 前缀。
2. 未完成内容请使用 Draft PR；准备好评审后再转正式 PR。
3. PR 描述至少写清楚以下内容：
   - 改了什么
   - 为什么改
   - 怎么验证
   - 是否影响协议、兼容性或部署方式
4. 如果 PR 和目标分支冲突，提交人必须先在本地解决冲突，再更新 PR。
5. 如果发现 PR 只包含部分有效改动，而剩余部分与当前主线冲突或重复，应当把有效增量摘到新提交中，而不是强行点合并。

## 验证要求

提交 PR 前，至少执行与你改动范围对应的验证命令，并在 PR 描述里写明结果。

### 服务端

根据改动类型至少做一项：

```bash
dotnet build
dotnet test
```

如果改动涉及消息大小、限流、鉴权、peer 转发或 TLS/WSS，请补充实际联调结果。

### Android 客户端

```bash
cd android-client
./gradlew :app:assembleDebug
```

如果改动涉及以下内容，还需要额外验证：

- 语音消息：Android 发 -> Web 收；Web 发 -> Android 收
- 通知：前台/后台通知、系统通知开关、通知音效预览
- 服务器切换：切换后自动重连、聊天记录按服务器隔离
- WSS 联调：确认 `deploy/certs/android-local/local_ca.crt` 能被 debug 包信任

### Web 客户端

```bash
cd web-client
npm install
npm run build
```

如果改动涉及录音、播放或协议兼容，还要验证：

- Web 发语音 -> Android 收
- Android 发语音 -> Web 收
- 分片消息能正确重组

## 协议改动规则

本项目最容易出问题的部分是“服务端、Android、Web 三端协议不同步”。任何协议改动必须遵守以下要求：

1. 明确改动的是哪一层：
   - 握手
   - 鉴权签名
   - 业务包结构
   - 语音标签或分片
   - 消息大小限制
2. 修改协议后，至少检查：
   - Android 客户端
   - Web 客户端
   - 服务端解析或转发逻辑
3. 如需兼容旧客户端，必须写清楚退化策略。
4. 不允许只在某一端“默认推断”字段而不在代码或文档中说明。

## 本地调试资产规则

以下内容只允许本地存在，不允许提交到版本库：

- `deploy/certs/`
- `deploy/keys/`
- 本地生成的 `server.pfx`
- `android-client/app/build/`
- `web-client/dist/`
- 调试日志、抓包、临时脚本

Android debug 本地 CA 信任的约定如下：

1. 本地 CA 证书路径固定为 `deploy/certs/android-local/local_ca.crt`
2. 该路径已被 `.gitignore` 覆盖
3. `android-client/app/build.gradle.kts` 会在 `assembleDebug` 时动态生成 debug-only `networkSecurityConfig`
4. release 构建不会信任本地 CA

## 冲突处理建议

如果 PR 已经明显落后于 `main`，不要直接在平台上硬点合并。正确做法：

1. 本地同步最新 `main`
2. 手动解决冲突
3. 重新跑验证
4. 再推回分支

如果发现 PR 中一部分内容已经被主线吸收，另一部分仍有价值，优先做“摘取有效增量”，不要把旧分支整条强行合进来。

## Issue 与关闭规则

1. 处理 issue 前先确认需求边界，避免顺手扩需求。
2. 做完后在 issue 或 PR 中写清楚：
   - 实际完成内容
   - 验证方式
   - 仍未解决的边界
3. 关闭 issue 前，确认代码已经合入目标分支，而不是只停留在本地或个人分支。

## 推荐工作流

1. 从最新 `main` 切分支
2. 只做单一目标改动
3. 本地自测
4. 更新必要文档
5. 同步最新 `main`
6. 再次验证
7. 提交 PR
8. 评审完成后合并
9. 删除分支

## 最低合并清单

合并前至少确认以下事项全部满足：

- 改动范围单一且清晰
- 无本地调试资产入库
- 与改动相关的构建命令已通过
- 协议变更已做跨端验证
- 文档已补齐
- PR 无未处理冲突
- PR 标题和描述可读，不是 `WIP`