SOP：新功能从需求到上线¶
一份能照着跑的实操手册。从需求池到生产环境。
阶段 1：需求收敛 (PM)¶
1. Notion 调研页 / 钉钉群 / 微信原料
2. Claude Code 跑 czerp-pm/notion-research-distill 提炼
3. 跑 user-story-author 按模板写故事草稿
4. （UI 类）跑 figma-to-axure 出原型
5. PM 自审 → 评审会过审
6. pingcode-sync 上传到 CZKB 故事根目录 + CZPRD 需求池
完成标志：PingCode 上有完整故事页 + 原型链接，关联 CZPRD-X。
阶段 2：计划会拆任务 (PM + Dev + QA + Tech Lead)¶
1. 评审故事完整性（按 user-story.md 自检 Checklist）
2. Tech Lead 决定是否需要拆子任务 / 跨服务协调
3. 估点（故事点斐波那契 1/2/3/5/8/13）
4. 分配 Dev / QA
5. 在 PingCode CZPRJ 创建 Sprint issue 关联 CZKB 故事
6. QA 当场或会后 24h 内起 testplan-author 测试计划
完成标志：CZPRJ-Sprint 中有 issue，CZTST 中有计划。
阶段 3：开发实现 (Dev)¶
3.1 拉故事 + 起 OpenSpec¶
# 在 czerp-api 或对应仓库
cd ~/Documents/CZERP/czerp-api
git checkout -b feature/oms-export-multi-currency-CZPRJ-1024 develop
# Claude Code 中
/user-story-impl CZPRJ-1024
/openspec-new oms-export-multi-currency
# 编辑 proposal.md / tasks.md（按 spec-change.md 模板）
3.2 推敲方案¶
/brainstorming # Superpowers — 仅在方案不明时
如果需要选型 / 涉及新中间件，写 design.md 留档。
3.3 TDD 实现¶
/test-driven-development # Superpowers
按 验收标准 一条条写失败测试 → 实现 → 测试通过。期间按需引用 czerp-backend/ 各 skill。
3.4 自查 + PR¶
/pre-pr-review # czerp 特有
/code-review # 内置命令，通用检查
/pr-describe # 生成 PR 描述
git push -u origin feature/oms-export-multi-currency-CZPRJ-1024
# Gitee 上创建 PR，把 /pr-describe 输出贴进去
完成标志：PR 已创建，关联 CZPRJ-1024。
阶段 4：PR Review + 合并 (Gitee + 开发组长)¶
1. Gitee Go 流水线自动跑（当前仅一个 Maven 编译 stage，mvn package -Dmaven.test.skip=true，跳单测；无 lint/sonar/评审门禁，失败仅飞书/钉钉通知）
2. AI 自动评审（Qodo PR-Agent）在自建 GitLab 对 czerp-demo 试点中，尚未覆盖 Gitee 主仓；主仓暂靠本地 /review、/code-review 自检
3. 开发组长人工复核（主仓当前的实际合并把关）
4. Approve → 合并到 develop
完成标志：PR merged，develop 触发 Jenkins。
阶段 5：CI 构建 + 部署 dev (Jenkins + GitOps)¶
1. Jenkins 拉代码 / mvn build / docker build / push 镜像
2. Jenkins 直接 commit + push 到 czerp-gitops（main，改 overlays/dev/patch-deployment.yaml 的 image tag）
3. ArgoCD AutoSync → k8s 更新 Pod（业务多为 Recreate；无 PR 人审门，推送后立即自动同步）
4. Pod 健康 → dev 环境就绪
develop 触发 Jenkins → dev 环境（分支映射：develop→dev、release/test→test、release/uat→uat）。
完成标志：dev 环境的 OMS 跑新版本，监控正常。
阶段 6：开发 dev 验证 (Dev)¶
1. 跑核心 验收标准 在 dev 环境
2. 截图 / 日志保留作为证据
3. 在 PingCode CZPRJ 评论 "dev 验证通过，附证据"
4. 通知 QA 接手
阶段 7：QA 测试 (QA)¶
1. 拉故事 + 用例
2. 手工跑 P0/P1 用例（dev 环境——故事在 sprint 内位于 dev；test/uat 回归在 T-1 批量提测后，见 03_release）
3. 跑 ai-driven-regression smoke
4. 全部通过 → 在 CZPRJ 评论"测试通过"
5. 有缺陷 → defect-submission → 缺陷库 → 关联开发
→ 开发修复 → 重新走 PR → 再回归
完成标志：CZTST 上测试报告通过，无 Blocker / Critical 缺陷。
阶段 8：上线 uat 准生产验收 (Ops + Dev + PM)¶
当前无独立 prod 环境，以 uat 作准生产验收；prod 上线为未来规划。
1. PM 决定上线时间窗口
2. 把 release/test 合并到 release/uat → Jenkins 构建 uat 镜像
3. Jenkins 直接 push czerp-gitops（main，改 overlays/uat 镜像 tag），ArgoCD AutoSync 自动同步（无 PR 人审门）
4. 公告钉钉群
5. 同步后跑 uat smoke
6. 5 分钟 / 15 分钟 / 1 小时 / 24 小时观察指标
完成标志：uat 监控正常，PingCode CZPRD 状态置"已上线"。
阶段 9：闭环 (Dev + Tech Lead)¶
1. openspec archive oms-export-multi-currency
2. PingCode CZPRJ issue 关闭
3. PingCode CZKB 故事页加"已上线"标签
4. Sprint Review 上演示
5. Sprint Retro 复盘
时间预算（典型 5 故事点 / 3 人天的故事）¶
| 阶段 | 估算 |
|---|---|
| 需求收敛 + 评审 | 0.5 - 2 天 |
| 计划会拆任务 | 0.5 小时 |
| 开发实现 | 1.5 天 |
| PR + Review | 0.5 天 |
| dev 验证 | 0.25 天 |
| QA 测试 | 0.5 - 1 天 |
| 上线 + 观察 | 0.5 - 1 天 |
| 总计 | 3.5 - 6 天 |
失败回退¶
任何一个阶段失败：
| 失败点 | 回退 |
|---|---|
| OpenSpec proposal 被打回 | 修正后重新评审，不进入实现 |
| PR review 被打回 | 修复 → 重新提 commit → 再 review |
| dev 验证未过 | 回到实现阶段 |
| QA 测试有 Blocker | 关联开发优先修，本故事不进入上线 |
| uat 上线异常 | 立即回滚 ArgoCD 到上一版（并同步改回 gitops 镜像 tag），再调查根因 |
回退没有羞耻成本 — 错误尽早暴露 + 修复才是健康节奏。