crm-backend-matt/docs/agents/collaboration.md

# 多人协作约定

本仓库是 Maven 多模块单仓库。协作目标不是靠事后解决 Git 冲突，而是让任务边界、模块边界和公共契约在写代码前就清楚。

## 主干与分支

- `main` 是唯一长期分支，必须始终可构建。当前仓库仍使用 `master` 时，由仓库管理员完成迁移前，`master` 以同等规则充当主干。
- 所有功能、缺陷和热修复都从主干创建短分支，并经 PR 合回主干。
- 不使用 `develop`，不以分支表达测试、预发或生产环境。
- 只有形成固定验收窗口后，才建立短期 `release/<version>` 分支。

## 任务领取与文件所有权

任务和规格存放在 `.scratch/`，规则见 [issue-tracker.md](issue-tracker.md)。领取前必须记录：

- 目标和可验证的完成条件；
- 影响的 `crm-*` 模块；
- 计划修改的文件；
- 对外 API、共享 DTO、数据库结构、配置或部署影响；
- 依赖、阻塞项和负责者。

一个文件在同一时间只能有一个写入责任人。下列位置是高冲突区，修改前必须显式指定 owner 并在 PR 中请求其审核：

- 根 `pom.xml`、`settings.xml` 和根构建/容器配置；
- `crm-base` 的公共模型、异常、通用服务与安全接口；
- `crm-auth` 的认证、授权和权限资源；
- 跨模块 port、共享 DTO、数据库实体与迁移策略；
- `deploy/`、`docker-compose.yml`、`nginx/` 与 CI 配置。

## 跨模块变更

先交付并审查“契约提交”，再并行实施上下游。契约包括接口、DTO、权限资源、事件、表结构和兼容策略。若无法在不共享文件的情况下并行，按依赖顺序安排任务；不允许两个 Agent 或开发者同时修改同一个公共 seam。

## Agent 工作规则

- 每位开发者、每个 Agent 使用独立 clone 或 `git worktree`，不共享未提交工作区。
- Agent 在读取任务和关联 CONTEXT/ADR 后才开始修改；它只能改变任务声明的范围。
- 提交前由人类确认 diff、测试证据和外部副作用。Agent 没有主干写入、PR 合并、仓库管理或生产凭据权限。
- 遇到范围重叠、接口含义不明或数据兼容性问题时停止实施，先补任务决策或 ADR。

## 0–1 阶段合并标准

在自动化验收尚未建立前，合并条件为：CI 编译通过、现有测试通过、Java 无 BOM、至少一名非作者 review 通过，以及 PR 提供可执行的人工验证记录。没有独立环境的行为不能声称已验收。

## 例行协作节奏

每日异步更新一次：任务链接、计划变更文件、阻塞项、即将改变的 API/表结构。每周复盘 PR 大小、冲突根因、构建失败和返工，只有在真实瓶颈出现时增加流程。

# 待讨论：两人协作落地方案

> 本文是 0–1 阶段的协作提案，不代表已生效的仓库或 Gitea 策略。团队确认后，才由仓库管理员配置权限、分支保护和 CODEOWNERS。

## 目标与原则

两人并行开发的首要目标是避免同时改同一个文件或同一个公共契约，而不是依赖 Git 在最后一刻解决冲突。采用一个长期主干、短生命周期任务分支和强制 PR 审查；暂不引入 `develop`、长期个人分支或 `release` 分支。

- 主干：迁移完成后使用 `main`；当前仍是 `master` 时，以受保护的 `master` 临时代替。
- 分支：功能用 `feature/<ticket>-<short-name>`，缺陷用 `fix/<ticket>-<short-name>`，线上紧急修复用 `hotfix/<ticket>-<short-name>`。
- 合并：所有分支经 PR 合入主干，默认 squash merge；禁止直接 push 主干或 force push 主干。
- 责任：提交 PR 的人对 Agent 生成内容、测试证据和外部副作用承担最终责任。

## 两人并行开发的标准流程

以下示例中，A 开发客户导入，B 开发线索状态流转。

### 1. 分别创建并领取任务

任务卡继续使用本仓库的本地 Markdown tracker：

```text
.scratch/customer-import/issues/01-import.md
.scratch/lead-status-transition/issues/01-transition.md
```

每张卡在开始前应记录：目标、可验证完成条件、owner、分支名、影响模块、计划修改文件、API/DTO/数据库/权限影响、高冲突区标记、依赖与阻塞项。双方先互相确认计划修改文件没有重叠。

### 2. 从主干分别创建短分支

```powershell
git switch main
git pull --ff-only
git switch -c feature/01-customer-import
```

B 使用自己的 `feature/01-lead-status-transition` 分支。一个分支只服务一个任务，不共享分支，不在同一 PR 混入无关重构或格式化。

### 3. Agent 使用独立 worktree

每个开发者和每个 Agent 必须拥有独立工作目录，不能共用未提交状态：

```powershell
git worktree add ..\crm-customer-import feature/01-customer-import
git worktree add ..\crm-lead-status feature/01-lead-status-transition
```

Agent 开始前读取任务卡和相关模块的 `CONTEXT.md`；它只能修改任务列出的范围。发现文件重叠、接口语义不清或数据兼容问题时，停止实施并由人先拆分任务或形成决策。

### 4. 发起 PR 并交叉审查

A 和 B 都向主干发 PR；A 审查 B 的 PR，B 审查 A 的 PR。合并前由 PR 作者更新主干并处理冲突：

```powershell
git fetch origin
git rebase origin/main
git push --force-with-lease
```

`--force-with-lease` 仅允许用于自己的任务分支，绝不能用于主干。PR 的合并条件是：CI 通过、至少一名非作者审批、讨论已解决、人工验证记录完整。

## 高冲突区与契约优先

根 `pom.xml`、`crm-base`、`crm-auth`、共享 DTO、跨模块 port、数据库实体、部署文件和 CI 配置都属于高冲突区。

当 A、B 都需要改同一公共区域时，不并行修改。先创建一个小型“契约任务”，由一人先提交并合入接口、DTO、权限资源、事件定义、表结构或兼容策略；另一人随后基于已合入的契约实现下游功能。这样解决业务语义冲突，而不只是文本冲突。

## 文件入库规则

### 必须提交

| 类型 | 典型路径 |
|---|---|
| 业务源码与测试 | `crm-*/src/**` |
| Maven 和可复现构建配置 | 根及子模块 `pom.xml`、`settings.xml` |
| 部署和基础设施配置 | `Dockerfile`、`docker-compose.yml`、`deploy/`、`nginx/` |
| CI、PR 模板和协作说明 | `.gitea/`、`CONTRIBUTING.md`、`docs/agents/` |
| 架构和领域决策 | `docs/adr/`、`CONTEXT-MAP.md`、各模块 `CONTEXT.md` |
| 规格和任务卡 | `.scratch/<feature>/spec.md`、`.scratch/<feature>/issues/*.md` |
| 可重复、脱敏且体积可控的测试 fixture | 测试资源目录中的 JSON、CSV、Excel 等 |
| 配置样例 | `.env.example`、`application-local.yml.example` |

### 不应提交

| 类型 | 处理方式 |
|---|---|
| 密钥、token、私钥、真实密码 | 仅保存在受控的密钥管理或本地环境 |
| 真实客户数据、生产导出、数据库备份 | 不入库；使用脱敏 fixture |
| 本地 `.env`、个人 `application-local.yml` | 使用已提交的 example 模板生成，本体忽略 |
| `target/`、Jar、IDE 缓存、`__pycache__/` | 忽略；均可重新生成 |
| `logs/`、JVM 崩溃日志 | 忽略；运行产物不作为源码 |
| 临时截图、浏览器下载、测试录像、运行结果 | 置于 `tmp/` 或制品存储；仅明确作为交付证据时例外 |

`.scratch/` 需区分可审计的文字资料和临时产物：规格、决策、任务卡可入库；截图、临时 Excel、运行 JSON、演示文件应放在 `tmp/` 或按功能建立明确的 `*-local/` 忽略目录。现有已被跟踪的日志和临时产物不在本提案执行时自动删除，需单独审查后迁移。

## 0–1 阶段质量门禁

当前尚无测试验收环境，因此不把自动部署、集成验收或 release 分支设为门禁。每个 PR 的最低要求是：

1. `mvn -B -s settings.xml verify` 通过；
2. Java 源文件无 UTF-8 BOM；
3. 至少一名非作者完成审查；
4. 写清手工验证步骤、执行人和结果；
5. 写清 API、数据结构、权限、配置、部署及回滚影响；没有影响时明确写“无”。

具备稳定集成环境和验收样例后，再增加集成测试与部署验证，并将相应 CI 检查设置为 required；不要提前设置长期失败的虚假门禁。

## 管理员待执行清单

以下动作需要 Gitea 管理员确认后手工完成：

1. 在组织空间保留至少两名管理员，开发者使用最小权限，Agent 没有管理员、合并或生产凭据权限。
2. 在清理或隔离当前未提交改动、确认构建成功后，为确定提交创建 annotated baseline tag。
3. 将默认分支从 `master` 迁移为 `main`；迁移前后分别保护当前主干。
4. 开启分支保护：禁止直接 push 和 force push；强制 PR、至少一名审批、讨论解决、CI 通过与合并后删除分支。
5. 确认 Gitea Actions runner 有 `ubuntu-latest` 标签，并能执行 `.gitea/workflows/ci.yml`。
6. 将 `CODEOWNERS.example` 中的占位账号替换为真实用户或团队后，另存为 `CODEOWNERS`；确认 Gitea 版本支持后再要求 owner 审核。

## 推行方式

不要一次性向所有工作强推流程。先选两个低风险、互不共享高冲突文件的功能，按本文完成一次领取任务、独立分支、PR、交叉审查和 squash merge。复盘 PR 大小、冲突原因、CI 耗时及人工验证成本；只有真实问题出现后才扩充规则。稳定运行两到三次后，再决定是否正式将本提案设为团队规范。