# STORAGE LABOS 团队协作指南

本文是团队日常 Git 操作的简明入口；完整工程约束见
[ProjectManual.md](ProjectManual.md) 第 13 章。

## 1. 首次加入项目

公开仓库允许匿名克隆；需要提交代码、Issue 或 Pull Request 的成员先注册账号并由管理员批准：

```bash
git clone https://git.imagebrewing.com/yuanshuai/storage-labos.git
cd storage-labos/flashops
make setup
make test
```

不要通过聊天工具传递压缩包继续开发；Git 仓库是代码和文档的唯一版本来源。

## 2. 分支规则

- `main`：始终保持测试通过和可发布，禁止直接开发或强制推送。
- `feat/<short-name>`：功能开发。
- `fix/<short-name>`：缺陷修复。
- `docs/<short-name>`：纯文档变更。
- `chore/<short-name>`：构建、依赖、部署与仓库维护。

一项工作一个分支；不要把无关功能、生产配置和大规模格式化混在同一分支。

```bash
git switch main
git pull --ff-only
git switch -c feat/agent-step-lease
```

## 3. 提交前质量门

```bash
cd flashops
make test
make demo
```

回到仓库根目录后，只暂存本次工作涉及的文件：

```bash
git status -sb
git add <明确的文件或目录>
git diff --cached --stat
git diff --cached --check
```

混合工作区不要直接使用 `git add -A`，避免把别人的改动、数据库或临时文件带入提交。

## 4. 提交格式

使用 Conventional Commits：`type(scope): subject`。

| 类型 | 用途 | 示例 |
|---|---|---|
| `feat` | 新功能 | `feat(agent): add step lease polling` |
| `fix` | 缺陷修复 | `fix(safety): reject stale host heartbeat` |
| `docs` | 文档 | `docs(manual): add agent deployment guide` |
| `test` | 测试 | `test(agent): cover token rotation` |
| `refactor` | 不改变行为的重构 | `refactor(events): isolate projection writer` |
| `perf` | 性能优化 | `perf(api): reduce timeline query cost` |
| `chore` | 工具、依赖和部署 | `chore(ci): add Python test matrix` |

主题用祈使语气、简短明确；一次提交只表达一个完整意图。

## 5. 推送与 Pull Request

```bash
git commit -m "feat(agent): add step lease polling"
git push -u origin "$(git branch --show-current)"
```

在 Gitea 创建 Pull Request，并写清：改了什么、为什么改、影响范围、验证结果和风险。
至少一名团队成员评审且质量门通过后才能合并。当前 Gitea 未在生产服务器上启用自托管
Runner，提交者必须在 PR 中附上本地测试结果；未来接入隔离 CI Runner 后再把自动检查设为
必需。优先使用 Squash merge，PR 标题保持 Conventional Commit 格式；合并后删除远程功能分支。

评审者重点检查：

1. 安全门禁、状态机和事件写路径是否被绕过；
2. 是否新增或修改测试；
3. API、数据结构、配置或部署变化是否同步更新手册；
4. 是否包含凭据、生产数据、日志、构建产物或大文件；
5. 危险动作是否仍为默认拒绝。

## 6. 冲突与回退

功能分支同步 `main` 时使用团队统一方式；首阶段建议 rebase：

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

仅允许对自己尚未合并的功能分支执行 `git push --force-with-lease`；严禁对 `main` 强推。
已合并变更需要撤销时使用 `git revert <commit>`，不要改写共享历史。

## 7. 绝不能提交的内容

- `.env`、密码、Token、SSH 私钥、证书私钥；
- `flashops/var/`、SQLite 数据库、Evidence Bundle 和日志；
- `.venv/`、`node_modules/`、缓存和本机构建产物；
- `~/.flashops/agent-state.json` 或任何 Agent 原始 bearer token；
- 未脱敏的客户数据、设备序列号清单和生产备份。

如果凭据误入提交：立即停止推送、通知管理员轮换凭据，再清理历史；仅删除当前文件不等于
从 Git 历史中删除。