WuYongJie/furniture-3d-system-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
furniture-3d-system-Wu/furniture-3d-system/docs/workflow/团队协作模式.md

10 KiB
Raw Blame History

团队协作模式

适用范围：furniture-3d-system 仓库。
目标：把当前项目从“单人连续开发”切换成“多人并行协作，但主链不打架”的模式。

进入这个仓库协作时，固定先读这 3 份文档，再开始改代码：

  1. docs/workflow/团队协作模式.md
  2. docs/workflow/模块边界说明.md
  3. docs/workflow/主线同步操作手册.md

这 3 份就是当前唯一的第一层协作入口，不再额外维护第二套平级入口文档。

1. 先记住一句话

这个仓库现在默认按下面这条主链协作：

资产中心 -> 辅助装配 -> 草稿组 -> 正式入库 -> 轻仓库

  • 包装相关能力当前挂在 DraftGroup / PreSku / Warehouse 承接口里，不作为独立顶层主线入口。
  • 旧的 CAD -> 装配步骤 链继续保留，但它是历史兼容链，不是新开品主链。
  • 历史文档里如果还出现 auto-combinations、自动组合、自动拼装，统一按旧称呼理解，不再代表当前页面入口。

2. 当前协作口径

先固定两件事

  • main 继续只由 WuYongJie 直接 push 和收口。
  • 这份文档现在只固定 Git 协作方式、主线收口规则和共享接缝处理原则，不再把当前模块职责长期写死在这里。

当前主线入口

  • src/app/asset-center
  • src/app/assisted-assembly
  • src/app/draft-groups
  • src/app/intake
  • src/app/warehouse
  • src/app/api/asset-center
  • src/app/api/assisted-assembly
  • src/app/api/draft-groups
  • src/app/api/intake
  • src/app/api/pre-skus
  • src/app/api/warehouse
  • src/components/platform
  • src/lib/open-product

具体职责怎么定

  • 具体谁负责哪个模块，不再以这份文档里的旧分工为准。
  • 当前任务边界以任务单、交接摘要、已确认协作信息和实际代码现状为准。
  • 如果任务碰到共享接缝，再和主线收口人对齐后再动。

哪些地方仍然算共享接缝

  • src/server/services/draft-group.service.ts
  • src/server/repositories/draft-group.repository.ts
  • src/server/services/intake.service.ts
  • src/app/intake
  • prisma/schema.prisma
  • src/app/draft-groups/[id]

3. 分支规则

主分支

  • main 继续保持受保护状态，且当前只允许 WuYongJie 直接 push 和收口。
  • 其他协作者默认不能直接 push main，只能走自己的功能分支。
  • 这样做的目的不是放开主线，而是保证主负责人可以快速收口，同事不会误把半成品直接推上主线。

开发分支

统一使用：

  • codex/<负责人>-<工作域>
  • codex/<负责人>-<工作域>-<任务简称>

固定口径：

  • 负责人必须进分支名，不能只用 feature/...、packaging/...、dev 这类泛名字
  • WuYongJie 主线相关分支统一放 codex/wuyongjie-mainline...
  • 长期共享分支和临时任务分支都要把当前工作域写进分支名，不再把人长期绑定在单一旧分支名上
  • 其他负责人也按同一模式命名，不再额外发明新前缀
  • 历史分支名不强制重命名，但从现在开始新分支全部按这套规则建

示例：

  • codex/wuyongjie-mainline
  • codex/wuyongjie-mainline-asset-center
  • codex/xuxiake-packaging
  • codex/xuxiake-intake-warehouse-clean-20260415
  • codex/zhangsan-cad-compat

合并方式

  • 主负责人可以直接在 main 收口、修主线、推主线。
  • 其他协作者默认先推自己的功能分支。
  • 同事的改动进入主线前，默认先由主负责人检查和收口。
  • 协作者不要自己合并到 main，也不要自己改远端主线历史。
  • 没有过验收清单，不合并，不并线。

当前固定流程：

  1. 协作者先从最新 main 同步到自己的长期分支或任务分支。
  2. 协作者只在自己负责的工作域内开发。
  3. 协作者推送自己的分支，并附上交接说明。
  4. WuYongJie 负责检查范围、决定 merge / cherry-pick / 手工收口。
  5. 只有进过主负责人收口的内容，才允许进入 main。

主线收口检查单

WuYongJie 收同事分支前，固定先看这 6 项：

  1. 这个分支是不是已经同步过最新 main
  2. 这次改动是不是只落在任务约定范围内
  3. 有没有碰共享接缝；如果碰了，交接里有没有写清原因
  4. 有没有最小验证结果，而不是只说“应该可以”
  5. 有没有交接说明，且写清楚“这次只改了什么、没改什么、风险是什么”
  6. 这次改动会不会影响正式入库、轻仓库或主链真相

只要这 6 项里有明显缺项，就先不要急着收口。

merge / cherry-pick / 手工整合 怎么选

固定口径：

  • 直接 merge

    • 适用：改动范围干净，只在同事负责域内，没有混入共享接缝或无关改动
    • 前提：已经同步最新 main，并且附了最小验证和交接说明

  • 优先 cherry-pick

    • 适用：同一个分支里既有可收的目标提交，也混入了暂时不该进主线的提交
    • 常见场景：同一个协作分支里夹带了共享接缝改动、调试提交、试错提交

  • 手工整合

    • 适用：目标功能要收，但提交历史太脏、冲突太多，或者改动虽然合理但不能整段直接拿
    • 常见场景：同一个文件同时碰到主线重构区和同事任务区

  • 暂不收口

    • 适用：没同步最新 main、没交接说明、没最小验证、范围失控、直接改了敏感共享接缝但没写原因
    • 处理方式：先退回补说明、补同步、补验证，再继续看

同事和主线怎么保持同步

当前项目默认采用这个口径：

  • WuYongJie 负责持续更新和收口 main
  • 协作者长期在自己的长期共享分支或当前任务分支开发
  • 同事不能等做完了再一次性同步，而是要高频同步 main

默认同步时机：

  • 每天开始开发前同步一次
  • 主负责人刚推了重要改动后同步一次
  • 自己准备提交前再同步一次

默认推荐方式：

  • 长期协作分支固定优先使用 merge main
  • 只有临时个人任务分支才优先使用 rebase main
  • 但不要一边长期不同步，一边继续堆改动

白话规则：

  • 长期共享分支保留真实协作历史，所以固定用 merge main
  • 临时个人任务分支只服务当前任务，为了保持提交线清楚，才用 rebase main
  • 如果你拿不准自己现在是不是长期共享分支，就先按长期共享分支处理，不要擅自改写共享历史

长期共享分支日常同步固定步骤：

git checkout main
git pull origin main
git checkout <你的长期共享分支>
git merge main
git push origin <你的长期共享分支>

如果你临时开了个人任务分支，再用：

git checkout main
git pull origin main
git checkout <你的临时任务分支>
git rebase main
git push --force-with-lease origin <你的临时任务分支>

怎么选：

  • 长期共享分支，用 merge
  • 临时个人任务分支，用 rebase

详细操作说明见：docs/workflow/主线同步操作手册.md 高频协作总规则见：docs/workflow/高频协作五条铁律.md

4. 每个任务都按这个流程走

  1. 先建一张任务单。
  2. 写清楚本次只做什么、不做什么、验收标准是什么。
  3. 明确归属模块，不跨模块顺手乱改。
  4. 开发前先读对应模块边界说明。
  5. 改完后同步必要文档。
  6. 跑最小验证。
  7. 做一次规范自审，再推分支。

额外固定动作：

  • 任务涉及共享接缝时，先在任务单里写清“为什么必须碰共享层”。
  • 协作者推分支后，要附一段交接说明，明确本次只改了什么、没改什么、风险是什么。
  • WuYongJie 收口同事改动时，优先按小任务合并，不一次性吞并长期积压改动。
  • 如果任务只是要把局部工作区做完整，默认不要直接在 src/app/draft-groups/[id]、src/app/intake 这类共享接缝里堆实现；先确认是否该在当前工作域内独立收口。
  • 如果这次改动会影响 intake / warehouse / Product / SKU 承接链，收口时额外确认：有没有把局部协作逻辑误带进正式入库主链，或者把旧兼容链重新当成主链真相。

5. 人和 AI 都要遵守的几条硬规则

先修根因，不打补丁

  • 影响 3D 拼装、命名、包装、BOM、安装步骤的数据，优先在数据源修。
  • 不允许只在页面上压报错、绕校验。

不跨层

  • Page / Route 不直接写 Prisma 业务逻辑。
  • Route 负责收参、鉴权、返回。
  • Service 负责业务规则。
  • Repository 负责数据访问。

不混主链和兼容链

  • 新平台主链的数据真相在 AssetFamily / AssetVariant / DraftGroup / PreSku。
  • 旧 Product / SKU / Panel / Hole / ProductHardware 继续服务兼容链。
  • 包装本期要能挂接 PreSku，但不直接跳过草稿组去造正式产品。

不破坏统一视觉

  • 新平台页面优先复用 src/components/platform。
  • 旧装配编辑器继续走现有视觉体系，不另起一套杂样式。

6. 本地目录管理规则

需要长期保留的

  • 源码
  • 迁移
  • 测试
  • 正式文档
  • 确认要进仓库的设计稿或说明

默认视为本地产物的

  • .dev-*.log
  • .qa-*.log
  • .start-*.log
  • .next-start-*.log
  • dev-server.log
  • .codex-logs/
  • _logs/
  • output/
  • temp/
  • public/uploads/

推荐习惯

  • 提交前先运行：npm run clean:local
  • 然后再看：git status --short

7. 提交前最少要交代什么

  • 这次改的是哪个模块
  • 本次只做了什么
  • 哪些地方明确没做
  • 跑了哪些验证
  • 有没有风险或依赖别人继续接

详细清单见：docs/workflow/提测与验收清单.md

8. 给 Codex 的一句话协作口径

如果要把任务转给 AI，建议在任务里直接写明：

  • 当前目标
  • 所属模块
  • 禁止改动的目录
  • 验收标准
  • 需要同步更新的文档

模板见：docs/workflow/任务单模板.md 和 docs/workflow/同事交接模板.md

9. 团队共享 AGENTS 和个人 AGENTS 怎么分

当前默认规则：

  • 仓库里的 AGENTS.md 是团队共享规则
  • 个人额外规则不要直接改仓库根目录那份
  • 谁要给自己的 Codex 加私有约束，就在自己电脑上的项目外层工作区再放一份本地 AGENTS.md

推荐说明：

  • 共享规则：继续放仓库里，大家共用
  • 个人规则：放各自机器上的外层工作区，不进仓库

对应说明和模板见：

  • docs/workflow/同事本地AGENTS使用说明.md
  • docs/workflow/同事本地AGENTS模板.md
  • docs/workflow/高频协作五条铁律.md