142 lines
8.6 KiB
Markdown
142 lines
8.6 KiB
Markdown
# 开发与验收协作流程
|
||
|
||
## 1. 两台电脑，一条主线
|
||
|
||
- **开发机（本机）**：负责业务源码、测试脚本、依赖与构建配置；实现需求、自测、构建并提交交付记录。
|
||
- **验收与规划机（另一台）**：独立拉取指定提交、安装依赖和构建，验收、记录问题并规划下一批；不直接修改业务源码“顺手修复”。
|
||
- 使用当前仓库的 `master` 协作，不另设长期开发／验收分支。Git/Gitea 保存需求、代码、证据索引和结论，**不会自动执行开发或验收**；每次交接须明确通知对方批次、记录位置和 SHA。
|
||
- 开始前阅读根目录 `AGENTS.md`、`docs/接手状态-2026-10-15.md` 及本批相关记录。原版 WorkBuddy 取证只通过 REA，不能因验收困难绕过。
|
||
|
||
## 2. 批次与状态
|
||
|
||
1. 规划方给任务稳定编号，如 `YC-001`，归入批次 `B01`，写清范围、优先级、依赖、逐项验收标准和不做的内容。
|
||
2. 双方确认后，锁定本批范围和验收标准。开发方接单并更新状态；新增想法进入下一批，不暗中改变正在验收的标准。
|
||
3. 开发方实现、自测、提交代码，再提交交付记录，指明**完整代码提交 SHA**。交付记录自身可以是后续文档提交，不要求自引用其 SHA。
|
||
4. 验收方按该 SHA 独立构建、逐项验收，提交结论。失败项退回开发方；修复后交付新 SHA，保留旧失败记录并重新验收。
|
||
5. 本批全部约定标准通过后才关闭；受环境或证据限制的项目标记“阻塞／未验证”，不能算通过。
|
||
|
||
任务状态：`待确认 → 待开发 → 开发中 → 待验收 → 已通过`；验收失败为 `待修复 → 开发中 → 待验收`。任何阶段可标记 `阻塞` 并写原因、责任方及解除条件；取消须记录原因。
|
||
|
||
验收 B01 时可以规划 B02，但两批记录分开；B01 的验收结果不受随后 `master` 上的 B02 代码影响。
|
||
|
||
## 3. 文件归属与推送顺序
|
||
|
||
- 开发方主写业务源码和交付记录；验收方主写需求、验收结果和下一批规划。同一记录的同一段一次只由一方编辑，转交前先提交、推送并通知。
|
||
- 双方可以并行工作，但**一次只由一方推送**：约定推送窗口，推送完交还；另一方先同步再继续提交。无需引入自动锁或新系统。
|
||
- 按需在 `docs/协作/` 保存批次记录，使用下面的内联模板即可；本流程不要求预先建立一套空文件。
|
||
- 提交只包含本批相关文件；先检查差异，避免 `git add .` 混入日志、构建产物或其他工作。
|
||
|
||
开始工作或接到推送通知后，在主工作目录执行：
|
||
|
||
```sh
|
||
git status --short --branch
|
||
git fetch origin
|
||
git log --oneline --left-right HEAD...origin/master
|
||
# 确认当前在 master、工作区干净且没有分叉后：
|
||
git pull --ff-only origin master
|
||
```
|
||
|
||
有未提交修改时先检查并保留：适合提交的做独立提交，否则明确暂存并记录恢复方式；不要直接覆盖或清理。`pull --ff-only` 失败即停下检查，不用强制同步消除差异。
|
||
|
||
提交／推送前再次检查并与对方确认窗口：
|
||
|
||
```sh
|
||
git diff --check
|
||
git diff
|
||
# git add <明确的文件路径>
|
||
git diff --cached
|
||
# git commit -m "docs(B01): 记录验收结果" # 按实际类型和批次填写
|
||
git fetch origin
|
||
git log --oneline --left-right HEAD...origin/master
|
||
git push origin master
|
||
```
|
||
|
||
若推送被拒绝，先 `git fetch origin`、审阅双方新增提交；工作区干净后按实际情况快进，分叉则协商并显式 `git merge origin/master`。冲突由文件负责人逐项核对、解决、检查后提交，再推送。涉及代码的合并必须重跑相关测试；若交付代码变了，登记新的交付 SHA。禁止 `push --force`，禁止用 `reset --hard` 或删除文件丢掉另一方／本地修改。
|
||
|
||
## 4. 固定 SHA 的独立验收
|
||
|
||
不要把“验收时最新的 master”当作交付版本。记录 `git rev-parse HEAD`、工作区状态、系统／架构、Node/npm 版本、依赖安装与构建命令；验收工作树应无源码改动。不能复用开发机的 `node_modules` 或旧构建产物来代替独立构建。
|
||
|
||
可选：主工作目录保留 `master` 写验收记录，另建 detached worktree 固定代码，不新增远端分支：
|
||
|
||
```sh
|
||
git fetch origin
|
||
# 将 <完整交付SHA> 替换为交付记录中的真实值；目标目录须不存在。
|
||
git worktree add --detach ../ycode-accept-B01 <完整交付SHA>
|
||
cd ../ycode-accept-B01
|
||
git rev-parse HEAD
|
||
git status --short
|
||
node --version
|
||
npm --version
|
||
npm ci --legacy-peer-deps
|
||
npm run build
|
||
# 再执行本批交付记录列出的针对性测试；先阅读脚本，确认数据隔离。
|
||
```
|
||
|
||
当前锁文件存在已知 peer 依赖冲突，暂用 `--legacy-peer-deps` 与现有构建说明一致；后续修复依赖约束后同步更新此步骤。
|
||
|
||
构建失败先记录安装／构建阶段、命令、错误及环境差异，不把环境失败冒充功能失败，也不擅自升级依赖或修改锁文件。验收结束回主工作目录同步，再提交文档；不要在 detached worktree 提交验收记录。
|
||
|
||
### 数据与环境安全
|
||
|
||
- 启动前检查 `src/main/index.ts` 的数据初始化逻辑：默认 userData 在特定迁移条件下可能被清空。先备份重要数据，**每轮必须显式设置独立的 `YCODE_USER_DATA_DIR`**，使用全新绝对路径，并确认启动进程继承变量。
|
||
- Windows PowerShell 示例：`$env:YCODE_USER_DATA_DIR = 'C:\ycode-qa\B01-run01'`；创建该目录后，在同一终端启动该 SHA 构建的应用。每次复测使用新的隔离目录，或明确记录恢复的测试夹具。
|
||
- 只用测试账号、脱敏夹具和专用工作目录；禁止用正式用户数据验收。隔离 userData 不等于隔离所有外部服务与工作区，运行前另行核对路径、账号和外部写操作。
|
||
- 不提交令牌、密码、私钥、真实用户配置或含敏感信息的日志／截图。证据须脱敏，注明仓库相对路径或双方可访问的附件地址；仅本机临时路径不能作为唯一交付证据。
|
||
|
||
### 验证层级必须分开写
|
||
|
||
| 层级 | 能说明什么／不能替代什么 |
|
||
| --- | --- |
|
||
| 静态检查、类型检查、构建 | 代码与产物基础检查；不等于功能运行通过 |
|
||
| 单元测试、mock／回环测试 | 指定逻辑和模拟通路；不等于真实服务可用 |
|
||
| 真实 Electron 集成 | 主进程、预加载、渲染器及实际交互；注明使用开发态还是构建产物 |
|
||
| Windows 安装包／运行环境 | 目标平台启动、打包与系统集成；不能用其他平台结果替代 |
|
||
| 原版对照／像素验收 | 按约定版本、窗口、缩放、字体、主题和状态比较；记录 REA Evidence ID 与限制 |
|
||
|
||
逐项区分“已实现”“mock／占位”“已验证”“未验证”。像素比较算法自测、token 对齐或构建成功均不是完整 1:1 验收；无相应环境／证据时如实标注，不补写通过结论。
|
||
|
||
## 5. 可直接复制的记录模板
|
||
|
||
### 需求／批次（规划方主写，双方确认）
|
||
|
||
```text
|
||
批次／任务编号：B01 / YC-001
|
||
目标、优先级、负责人：
|
||
基线 SHA、依赖：
|
||
本批范围／不做：
|
||
验收标准：AC1…；AC2…（可操作、可判断，含必要异常场景）
|
||
所需环境／原版版本及 REA 证据：
|
||
双方确认、范围锁定时间：
|
||
状态／阻塞原因与解除条件：
|
||
下一批建议（不改变本批标准）：
|
||
```
|
||
|
||
### 交付（开发方主写）
|
||
|
||
```text
|
||
批次／任务编号：
|
||
完整代码 SHA／需求记录位置：
|
||
改动范围、实现／mock／未实现：
|
||
环境与依赖、构建／测试命令、结果及脱敏证据位置：
|
||
验收启动步骤、隔离数据目录／夹具要求：
|
||
已知问题、风险、未验证项：
|
||
状态：待验收（或阻塞及原因）
|
||
```
|
||
|
||
### 验收／退回（验收方主写）
|
||
|
||
```text
|
||
批次／任务编号、完整受测 SHA：
|
||
验收人／时间、系统／工具版本、干净工作树确认：
|
||
独立安装与构建命令／结果、隔离数据与夹具：
|
||
逐项标准：AC1 通过／失败／未验证；证据位置；验证层级
|
||
失败：前置条件 → 最短复现步骤 → 预期 → 实际；频率／影响
|
||
日志／截图：脱敏文件路径或共享附件地址（对应 SHA 与场景）
|
||
结论：已通过／待修复／阻塞；责任方及下一步：
|
||
复测：修复 SHA、重跑范围、结果（保留原失败记录）
|
||
下一批需求：另列编号，不覆盖本批结论
|
||
```
|
||
|
||
完成标准是“约定范围在指定 SHA 上有可复核的通过证据”，不是“代码已推送”。本文件只定义流程，不代表任何功能已经完成验收。
|