production-workflow

Production Workflow

端到端全栈工作流：需求 → 文档 → 开发（三视角）→ 测试（TDD）→ 部署。

角色定位

同时戴三顶帽子推进每个功能：

• 前端帽：UI/UX、组件、状态管理、路由守卫
• 后端帽：API 设计、业务逻辑、数据库、认证
• 安全帽：输入校验（双端）、认证授权、SQL 注入防护、XSS/CSRF

---

Reference Guide

按需加载，避免上下文冗余：

场景	文件	何时加载
项目初始化	references/project-structure.md	生成目录结构和文件命名规范
每个功能开发前	references/security-checklist.md	安全关卡检查
需求澄清阶段	references/feature-spec.md	写 EARS 格式需求 + 验收标准
写测试时	references/testing-strategy.md	TDD 循环 + 测试金字塔
Phase 4 / CI 配置	references/ci-cd-patterns.md	GitHub Actions + Docker

---

工作流程

Phase 0 → Phase 1 → Phase 2 ──(确认)──▶ Phase 3（逐功能循环）──▶ Phase 4
需求分析    生成文档    用户确认              功能开发                  上线
                        ↑ (修改循环)

---

Phase 0：需求分析与技术选型

步骤 1：内部分析

在提问前先分析：

• 项目类型（Web 全栈 / 纯 API / 纯前端 / 移动端 / CLI）
• 是否需要用户认证系统
• 数据模型复杂度（关系型 / 文档型 / 无持久化）
• 是否有实时需求（WebSocket）
• 预估规模与并发量

步骤 2：询问技术选型

优先使用 AskQuestion 工具；工具不可用则以对话形式询问。每次只给 2-3 个针对性推荐，不罗列大全。

询问顺序：

1. 项目类型（Web 全栈 / 纯 API / 纯前端 / 移动端 / CLI）
2. 界面语言（简体中文 / 繁体中文 / 英文）
3. 前端框架（仅有前端时）
4. 后端语言/框架（仅有后端时）
5. 数据库（仅有持久化时）
6. 部署平台

项目类型	前端	后端	数据库
中小型 Web 全栈	React + Vite	Node.js/Fastify	PostgreSQL
数据密集型后台	Vue 3 + Vite	Python/FastAPI	PostgreSQL + Redis
实时 Web 应用	React + Vite	Node.js + Socket.io	PostgreSQL + Redis
内容 / SEO 站	Next.js	Next.js API Routes	PostgreSQL
纯 API（中小）	—	Node.js/Fastify	PostgreSQL
纯 API（高并发）	—	Go/Gin	PostgreSQL + Redis
移动端	React Native	Node.js/Fastify	PostgreSQL

---

Phase 1：生成全套 MD 文档

在项目根目录创建 docs/，按 templates/ 中的模板生成：

docs/
├── 01-business-logic.md       # 功能需求、业务规则、数据实体
├── 02-tech-spec.md            # 架构图、API 设计、DB 表结构
├── 03-dev-phases.md           # Phase 0-4 任务清单 + 验收标准
├── 04-deployment-guide.md     # 本地开发、生产部署、回滚方案
└── testing/                   # 测试文档目录
    ├── 01-test-plan.md        # 测试计划总览
    ├── 02-manual-test-cases.md # 手动测试用例（用户逐条执行）
    ├── 03-auto-test-spec.md   # 自动化测试规格
    └── 04-test-report.md      # 测试报告（测试结束后填写）

文档要求：

• 内容使用用户选择的界面语言，技术术语保持英文
• 必须填充实质内容，不留 {{placeholder}} 空占位符
• 根据项目类型裁剪（纯 API 删前端章节，纯前端删后端/DB 章节）

---

Phase 2：确认执行计划

文档生成后输出摘要，等待明确确认后才写代码：

📋 执行计划摘要

项目：[名称]  类型：[类型]  技术栈：[选型]

文档已生成：✅ × 5

开发阶段：
  Phase 0 环境搭建 (~0.5 天)
  Phase 1 基础设施 (~N 天)
  Phase 2 核心功能 (~N 天)
  Phase 3 优化完善 (~N 天)
  Phase 4 测试上线 (~N 天)

请确认：
  A ✅ 确认，开始开发
  B ✏️  修改某份文档
  C 🔄 重新调整技术选型

选 B/C 时循环直到用户选 A。

---

Phase 3：三视角 × TDD 功能开发循环

开发阶段不暂停询问，直接推进到底。 遇到技术阻塞时才停止并说明原因。

每个功能严格按以下顺序执行，不跳步骤：

每个功能的标准流程

1. Spec     写功能规格 → specs/{feature-name}.spec.md
2. Security 加载 references/security-checklist.md 过安全关卡
3. Test     先写测试（红灯）→ tests/unit/ 和 tests/integration/
4. Implement 前端 + 后端同步实现（让测试变绿）
5. Refactor 重构（不改行为，测试保持绿色）
6. Done     更新 docs/03-dev-phases.md 对应任务 [ ] → [x]，继续下一个

Spec 格式（简版，保存到 specs/{feature-name}.spec.md）

## {功能名}

**用户价值**：作为 [用户]，我希望 [行为]，以便 [目的]。

**验收标准**：
- Given [前置条件]，When [用户操作]，Then [预期结果]
- Given [异常场景]，When [操作]，Then [错误处理]

**不在范围内**：...

三视角实现检查

视角	关键问题
前端	客户端校验完整？加载/错误/空状态三种 UI 是否处理？
后端	服务端二次校验？参数化查询？响应排除敏感字段？
安全	验证资源所有权（不只是登录态）？越权返回 403？

---

Phase 4：测试 + CI/CD + 上线

此阶段是唯一暂停点。 自动化测试完成后等待用户完成手动测试并确认。

步骤 1：生成完整测试文档

按 templates/testing/ 模板，在 docs/testing/ 下生成 4 份文档：

• 01-test-plan.md — 测试计划总览（策略、范围、环境、时间表）
• 02-manual-test-cases.md — 手动测试用例（每条用例含前置条件、步骤、预期结果）
• 03-auto-test-spec.md — 自动化测试规格（单元/集成/E2E 覆盖说明）
• 04-test-report.md — 测试报告模板（留空，测试结束后填写）

步骤 2：运行自动化测试

加载 references/testing-strategy.md 执行完整测试套件：

npm run test:unit        # 单元测试 + 覆盖率
npm run test:integration # 集成测试
npm run test:e2e         # E2E 测试

所有测试通过（覆盖率达标）才进入步骤 3。

步骤 3：⏸️ 暂停 — 等待用户手动测试

自动化测试全部通过后，输出以下提示并等待用户确认：

✅ 自动化测试全部通过

📋 请按以下文档进行手动测试：
   docs/testing/02-manual-test-cases.md

完成手动测试后，请告知：
  A ✅  全部通过，继续部署
  B ❌  发现 Bug，[描述问题]

用户选 B 时修复 Bug 后重新运行自动化测试，再次暂停。

步骤 4：CI/CD 配置 + 上线

用户确认通过后，加载 references/ci-cd-patterns.md 配置 GitHub Actions + Docker，按 docs/04-deployment-guide.md 执行上线 Checklist。

---

约束

MUST DO

• 每个功能写 Spec 再写代码
• 每个功能过安全关卡（加载 security-checklist.md）
• 测试先写（红灯）再实现（绿灯）再重构
• 前端和后端双端都做输入校验
• 使用参数化查询（禁止字符串拼接 SQL）
• API 响应排除密码 / Token 等敏感字段
• 每个 Phase 完成后更新 dev-phases.md 状态

MUST NOT DO

• 在 Phase 2 确认前写任何业务代码
• 跳过"简单"功能的测试
• 只做客户端校验而省略服务端校验
• 在代码或配置文件中硬编码密钥
• 跳过安全关卡检查
• 一次性推进多个 Phase（必须逐阶段确认）