---
title: 项目团队协作规范
navTitle: 协作规范
---
# 项目团队协作规范

SuccApp 让多人可以像管理代码一样管理元数据。AI 加入后，团队更需要约定清楚分工、同步顺序、AI 可修改范围、Git 提交和生产发布规则，避免互相覆盖、发布错误和版本混乱。

## 角色分工{#roles}

项目团队中常见角色如下：

| 角色 | 职责 |
| :--- | :--- |
| 项目负责人 | 确认需求范围、评审变更、决定生产发布 |
| 项目成员 | 修改元数据、验证功能、提交 Git |
| 脚本人员 | 修改脚本、排查脚本问题 |
| 发布人员 | 按流程同步生产环境 |
| 评审人员 | 检查变更范围、风险和测试结果 |

一个人可以承担多个角色，但职责仍应清楚。

## 分工原则{#division}

多人协作时，建议按以下方式分工：

1. 按页面、模块或业务流程分工。
2. 避免多人同时修改同一个元数据文件。
3. 大范围重构前先通知团队。
4. 脚本、权限、流程等高风险文件由负责人确认。
5. 生产发布只由指定人员执行。

## 开始工作前{#before-work}

每位成员开始工作前应完成：

1. 从 Git 拉取最新内容。
2. 打开 VS Code 工作区。
3. 连接测试服务器。
4. 使用 SuccApp 拉取服务器变化。
5. 检查 Changes 视图是否已有冲突。
6. 确认自己的修改范围。

如果发现本地或服务器已有其他人的变化，应先沟通再继续。

## 修改过程中{#during-work}

修改过程中建议：

1. 小步修改，不要一次改太多文件。
2. 每次修改后查看 Changes 差异。
3. 推送测试环境前确认当前服务器。
4. 测试通过后及时提交 Git。
5. 在提交信息中写清业务目的。
6. 重要修改在团队群或任务中说明。

不要长时间持有大量未提交修改，否则团队很难判断真实进度和风险。

## 交换数据和修改{#exchange}

团队成员之间交换修改，应优先使用 Git。

推荐方式：

1. 修改者提交到个人分支。
2. 发起合并请求或通知评审。
3. 评审通过后合并到团队分支。
4. 其他成员从 Git 拉取。
5. 需要在测试服务器验证时，再通过 SuccApp 推送。

测试服务器可以作为团队集成验证环境，但不应替代 Git。只在服务器上改、不提交 Git，会导致版本不可追踪。

## 处理远端变化{#remote-change}

如果 push 时提示服务器已有远端变化：

1. 不要直接强制推送。
2. 先查看远端变化差异。
3. 确认远端变化是谁产生的。
4. 如果远端变化需要保留，先 pull 并处理冲突。
5. 如果确认远端变化可以覆盖，由负责人决定是否强制推送。

生产环境中出现远端变化时，应暂停发布并确认原因。

## 冲突处理{#conflict}

冲突处理建议：

1. 打开 diff，确认本地和服务器各自改了什么。
2. 找到对应修改人员沟通。
3. 决定保留本地、保留服务器，或手工合并。
4. 合并后重新推送测试环境。
5. 提交 Git 并说明冲突处理结果。

不要在不了解业务含义时随意选择一侧覆盖。

## 命名和目录规范{#naming}

团队应约定元数据命名和目录规则。

建议：

1. 按业务模块组织目录。
2. 文件名尽量稳定，避免频繁重命名。
3. 页面标题、描述和文件名含义一致。
4. 删除测试文件和临时文件前先确认没有引用。
5. 被同步的目录应保留有效 `.meta`，文件资源应在父目录 `.meta` 中保留对应条目。

## 提交和评审规范{#review}

提交前自查：

1. Changes 视图无无关变化。
2. Git diff 无临时文件。
3. 测试环境已验证。
4. 说明了本次修改目的。
5. 高风险修改已通知负责人。

评审时重点看：

1. 是否符合需求。
2. 是否修改了无关文件。
3. 是否有误删和格式化噪声。
4. 是否会影响生产数据、权限或流程。
5. 是否有回退方式。

## 禁止事项{#forbidden}

正式项目中不建议：

1. 直接在生产环境中调试。
2. 未查看差异就 push。
3. push 被阻止后直接强制覆盖。
4. 只改服务器不提交 Git。
5. 删除目录级 `.meta` 文件或误删其中的资源条目。
6. 提交 `.succapp/remote/`、日志、锁和缓存。
7. 让 AI 未经检查地发布生产。

## 协作检查清单{#checklist}

每日开始工作前：

1. 拉取 Git。
2. 拉取服务器变化。
3. 检查 Changes 视图。
4. 明确今日修改范围。

提交前：

1. 查看 SuccApp diff。
2. 推送测试环境验证。
3. 查看 Git diff。
4. 提交 Git。
5. 通知评审或相关成员。

发布前：

1. 确认 Git 版本。
2. 确认评审通过。
3. 确认生产差异。
4. 准备回退方案。
5. 安排业务验证。