doa-workcopilot

# 在 PowerShell 中执行
& "path/to/doa-workcopilot/scripts/deploy.ps1"

doa-workcopilot/
├── SKILL.md                              ← 主编排逻辑（本文件）
├── scripts/
│   └── deploy.ps1                        ← 团队一键部署脚本
├── references/                           ← 脚手架模板 & 内嵌工作流
│   ├── agents.md                         ← 6 个 Agent 精简角色定义
│   ├── embedded-harness.md               ← Harness 工程轨道工作流
│   ├── embedded-spec-flow.md             ← Spec-Flow 结构化开发流程
│   ├── dotnet-scaffold.md                ← .NET 8 脚手架模板
│   ├── python-scaffold.md                ← FastAPI 脚手架模板
│   └── react-scaffold.md                 ← React + Vite 脚手架模板
├── embedded-agents/                      ← 完整 Agent 定义文件（项目注入用）
│   ├── requirements-analyst.md
│   ├── system-architect.md
│   ├── backend-engineer.md
│   ├── frontend-engineer.md
│   ├── test-engineer.md
│   └── mermaid-diagram.md
├── embedded-hooks/                       ← PreToolUse Hook（项目注入用）
│   ├── update-workcopilot.json           ← Hook 配置（commit/build/docker 前拦截）
│   └── scripts/
│       └── check-workcopilot.ps1         ← 拦截脚本（检查 .workcopilot 是否已更新）
├── embedded-prompts/                     ← Prompt 模板（项目注入用）
│   ├── code-review.prompt.md             ← 全面 Code Review（安全+性能+规范+逻辑）
│   └── generate-tests.prompt.md          ← 生成 xUnit + Moq 单元测试
└── embedded-skills/                      ← 完整 Skill 包（项目注入用）
    ├── doa-ppt/          (SKILL.md + 2 模板)
    ├── doa-metting/      (SKILL.md + 1 模板)
    ├── doa-apidoc/       (SKILL.md + 2 模板)
    ├── doa-image/        (SKILL.md)
    ├── doa-quotation/    (SKILL.md + 3 模板)
    ├── doa-testreport/   (SKILL.md)
    ├── doa-e2etest/      (SKILL.md + 3 参考文档)
    ├── doa-harness/      (SKILL.md + 5 模板)
    ├── spec-flow-main/   (SKILL.md + 模板 + 参考 + 脚本)
    ├── brainstorming/    (SKILL.md)
    ├── frontend-design/  (SKILL.md)
    └── ui-ux-pro-max/    (SKILL.md + data + scripts)

{project-root}/
├── .github/
│   ├── hooks/                 ← 从 embedded-hooks/ 注入
│   │   ├── update-workcopilot.json
│   │   └── scripts/
│   │       └── check-workcopilot.ps1
│   └── prompts/               ← 从 embedded-prompts/ 注入
│       ├── code-review.prompt.md
│       └── generate-tests.prompt.md
└── .claude/
    ├── agents/                ← 从 embedded-agents/ 注入
    │   ├── requirements-analyst.md
    │   ├── system-architect.md
    │   ├── backend-engineer.md
    │   ├── frontend-engineer.md
    │   ├── test-engineer.md
    │   └── mermaid-diagram.md
    └── skills/                ← 从 embedded-skills/ 注入
        ├── doa-ppt/
        ├── doa-metting/
        ├── doa-apidoc/
        ├── doa-image/
        ├── doa-quotation/
        ├── doa-e2etest/
        ├── doa-harness/
        ├── doa-testreport/
        ├── spec-flow-main/
        ├── brainstorming/
        ├── frontend-design/
        └── ui-ux-pro-max/

调用 WorkCopilot
  → Step 0: 项目类型判定（新 / 老）
  ┌─ 老项目路线 ──────────────────────────────────────┐
  │ → Step E1: 运行 Harness（探测 + 生成工程轨道）       │
  │ → Step E2: 生成/更新 docs/README.md                   │
  │ → Step E3: 注入项目级 Agent & Skill & Hook（6+12+1）          │
  │ → Step E4: 输出 Day-1 验证 & 可用命令清单            │
  │ → Step E5: 状态持久化 + 初始化项目记忆               │
  └──────────────────────────────────────────────────────┘
  ┌─ 新项目路线 ──────────────────────────────────────────┐
  │ → Step N1: 项目子类型判定（代码 / 非代码）             │
  │   ┌─ 非代码项目 ─────────────────────────────────────┐│
  │   │ → 运行 Harness（生成工程轨道）                    ││
  │   │ → 引导选择合适 Skill（PPT/文档/报价/图片等）      ││
  │   │ → 调度 Skill 执行，产出存入 output/{名称}/        ││
  │   │ → 状态持久化（state.json + changelog.md）         ││
  │   └──────────────────────────────────────────────────┘│
  │   ┌─ 代码项目 ───────────────────────────────────────┐│
  │   │ → Phase 1: 技术栈 + 规模 + CI/CD + 环境选型      ││
  │   │ → Phase 2-4: 委托 spec-flow-main skill           ││
  │   │   （需求分析/系统设计/任务拆解，可跳过/可导入）    ││
  │   │ → Phase 5: 脚手架搭建（支持完整/空项目模式）       ││
  │   │   ├── 5.0 脚手架模式判定 + 参考图导入             ││
  │   │   ├── 5.1 后端（完整/空项目 + 多模块/微服务）     ││
  │   │   ├── 5.2 前端（完整/空项目 + 可导入参考图）      ││
  │   │   ├── 5.3 数据库                                  ││
  │   │   ├── 5.4 Docker                                  ││
  │   │   ├── 5.5 测试框架                                ││
  │   │   ├── 5.6 Git 初始化                              ││
  │   │   ├── 5.7 CI/CD 管线                              ││
  │   │   ├── 5.8 多环境配置                              ││
  │   │   └── 5.9 安全基线                                ││
  │   │ → Phase 6: 工程轨道（Harness）                     ││
  │   │ → Phase 6.5: 注入项目级 Agent & Skill & Hook             ││
  │   │ → Phase 7: Day-1 验证                             ││
  │   │ → Phase 8: 项目状态持久化                         ││
  │   │ → Phase 9: 迭代开发（持续循环入口）↺              ││
  │   └──────────────────────────────────────────────────┘│
  └───────────────────────────────────────────────────────┘
  ┌─ 迭代入口（已初始化项目再次调用）──────────────────────┐
  │ → 检测 .workcopilot/state.json                        │
  │ → 自动跳过初始化，直接进入 Phase 9 迭代开发            │
  └───────────────────────────────────────────────────────┘

Q1: 项目类型
  - "🆕 新创建的项目" (recommended)
  - "📂 已存在的老项目"

# {项目名称}

{用户在 harness Step 2 输入的项目描述}

## 技术栈

{从 harness 探测结果填充，按子项目分段}

## 快速开始

### 环境要求
{根据技术栈列出 Node/dotnet/Python 版本要求}

### 安装 & 运行
{根据包管理器和框架生成具体命令}

## 项目结构

{从 AGENTS.md 模块地图提炼，简化展示}

## 开发规范

- 工程轨道：`.github/copilot-instructions.md`
- Agent 约束：`.github/AGENTS.md`
- 编码规则：`docs/rules/*.md`
- 验证命令：参见 `.vscode/tasks.json`

1. 在项目根目录创建 .claude/agents/ 和 .claude/skills/ 目录
2. 复制 embedded-agents/ 下的 6 个 Agent 文件 → {project}/.claude/agents/
3. 复制 embedded-skills/ 下的 12 个 Skill 目录 → {project}/.claude/skills/
4. 复制 embedded-hooks/ 下的 Hook 配置 → {project}/.github/hooks/
   - update-workcopilot.json → .github/hooks/
   - scripts/check-workcopilot.ps1 → .github/hooks/scripts/
5. 复制 embedded-prompts/ 下的 Prompt 文件 → {project}/.github/prompts/
   - code-review.prompt.md → .github/prompts/
   - generate-tests.prompt.md → .github/prompts/
6. 如果目标位置已存在同名文件，询问用户是否覆盖

{project}/
├── .github/
│   ├── hooks/
│   │   ├── update-workcopilot.json
│   │   └── scripts/
│   │       └── check-workcopilot.ps1
│   └── prompts/
│       ├── code-review.prompt.md
│       └── generate-tests.prompt.md
└── .claude/
    ├── agents/
    │   ├── requirements-analyst.md
    │   ├── system-architect.md
    │   ├── backend-engineer.md
    │   ├── frontend-engineer.md
    │   ├── test-engineer.md
    │   └── mermaid-diagram.md
    └── skills/
        ├── doa-ppt/
        ├── doa-metting/
        ├── doa-apidoc/
        ├── doa-image/
        ├── doa-quotation/
        ├── doa-e2etest/
        ├── doa-harness/
        ├── spec-flow-main/
        ├── brainstorming/
        ├── frontend-design/
        └── ui-ux-pro-max/

{
  "version": "1.0",
  "source": "existing",
  "createdAt": "...",
  "updatedAt": "...",
  "project": {
    "name": "{从 harness 探测到的项目名}",
    "description": "{用户在 E1 输入的描述}",
    "detectedStack": {
      "backend": "dotnet | python | node | other",
      "frontend": "react | vue | angular | h5 | other",
      "database": "sqlserver | postgresql | mysql | other"
    }
  },
  "phases": {
    "E1": { "status": "completed", "completedAt": "..." },
    "E2": { "status": "completed", "completedAt": "..." },
    "E3": { "status": "completed", "completedAt": "..." },
    "E4": { "status": "completed", "completedAt": "..." }
  },
  "iterations": [],
  "services": []
}

Q1: 项目子类型
  - "💻 代码项目（Web应用/API/系统）" (recommended)
  - "📄 非代码项目（PPT/文档/报价/设计稿）"

Q2: 要做什么？
  - "📊 PPT / 方案演示" → 调用 doa-ppt
  - "📋 会议纪要" → 调用 doa-metting
  - "💰 项目报价" → 调用 doa-quotation
  - "📝 接口文档" → 调用 doa-apidoc
  - "🎨 可视化页面/长图" → 调用 doa-image
  - "📄 Word 文档" → 调用 docx skill
  - "🖼️ 前端设计稿" → 调用 frontend-design

{project-root}/
└── output/
    ├── {产出名称A}/              # 如 "Q3季度汇报PPT"
    │   ├── Q3季度汇报.pptx
    │   └── generate_ppt.py       # 生成脚本（如有）
    ├── {产出名称B}/              # 如 "项目报价单"
    │   ├── 报价单_v1.xlsx
    │   └── generate_quotation.py
    └── {产出名称C}/              # 如 "API接口文档"
        ├── 接口说明书.pdf
        └── generate_apidoc.py

// .workcopilot/state.json
{
  "version": "1.0",
  "source": "non-code",
  "timezone": "Asia/Shanghai",
  "createdAt": "...",
  "updatedAt": "...",
  "project": {
    "name": "{项目名}",
    "description": "{项目描述}",
    "type": "non-code",
    "skill": "doa-ppt | doa-metting | doa-quotation | doa-apidoc | doa-image | docx | frontend-design"
  },
  "outputs": [
    {
      "name": "{产出名称}",
      "skill": "doa-ppt",
      "path": "output/{产出名称}/",
      "createdAt": "..."
    }
  ],
  "iterations": [
    {
      "id": "iter-001",
      "date": "...",
      "scope": "{首次调度的 Skill 及产出摘要}"
    }
  ]
}

Q1: 项目名称
  [自由输入]

Q2: 一句话描述项目
  [自由输入]

Q3: 后端技术栈
  - ".NET 8 (WebAPI + SqlSugar)" (recommended)
  - ".NET 8 (WebAPI + EF Core)"
  - "Python (FastAPI + SQLAlchemy)"
  - "其他（请说明）"

Q4: 前端技术栈
  - "React + TypeScript + Ant Design" (recommended)
  - "纯 HTML5 + CSS + JS (轻量级)"
  - "其他（请说明）"

Q5: 数据库
  - "SQL Server" (recommended)
  - "PostgreSQL"
  - "MySQL"
  - "SQLite (开发/轻量)"
  - "其他（请说明）"

Q6: 认证方式
  - "JWT Token 认证" (recommended)
  - "Azure AD / Entra ID"
  - "Cookie Session"
  - "暂不需要"

Q7: 是否需要 Docker 支持
  - "是" (recommended)
  - "否"

Q8: 项目规模 & 架构
  - "🏠 单体应用（单后端 + 单前端）" (recommended)
  - "📦 多模块单体（共享代码库，多个功能模块）"
  - "🔗 微服务架构（多个独立后端服务 + API 网关）"

Q9: CI/CD 管线
  - "GitHub Actions" (recommended)
  - "Azure DevOps Pipelines"
  - "暂不配置"

Q10: 多环境配置
  - "dev + prod（两套环境）" (recommended)
  - "dev + staging + prod（三套环境）"
  - "仅 dev（开发环境）"

Q-scaffold: 脚手架生成模式
  header: "后端和前端分别选择脚手架模式"

  Q-scaffold-backend: 后端脚手架模式
    - "🏗️ 完整脚手架（包含业务代码骨架 + 示例）" (recommended)
    - "📦 空项目（仅项目结构 + 基础配置，不含业务代码）"

  Q-scaffold-frontend: 前端脚手架模式
    - "🏗️ 完整脚手架（包含页面骨架 + 路由 + 状态管理）" (recommended)
    - "📦 空项目（仅项目结构 + 基础配置，不含页面代码）"
    - "🖼️ 完整脚手架 + 参考设计图（导入 UI 参考图辅助生成）"

project:
  name: "{项目名}"
  description: "{项目描述}"
  backend:
    stack: "dotnet" | "python"
    framework: "webapi" | "fastapi"
    orm: "sqlsugar" | "efcore" | "sqlalchemy"
  frontend:
    stack: "react" | "h5"
    ui: "antd" | "none"
  database: "sqlserver" | "postgresql" | "mysql" | "sqlite"
  auth: "jwt" | "azure-ad" | "cookie" | "none"
  docker: true | false
  scale: "monolith" | "modular" | "microservice"
  cicd: "github-actions" | "azure-devops" | "none"
  environments: "dev-prod" | "dev-staging-prod" | "dev-only"
  docs: "generate" | "import" | "skip"
  scaffold:
    backend: "full" | "empty"
    frontend: "full" | "empty" | "full-with-ref-image"
    ref_image: "{path}" | null      # 前端参考设计图路径（仅 full-with-ref-image 时有值）

Q11: 需求 & 设计文档策略
  - "📝 AI 生成（逐阶段引导生成需求/设计/任务文档）" (recommended)
  - "📂 我有现成资料（上传或粘贴，AI 整理为标准格式）"
  - "⏭️ 跳过（直接进入脚手架搭建，后续按需补充）"

1. 提示用户提供资料（支持以下方式）：
   - 直接在对话中粘贴文本
   - 指定工作区中的文件路径（.md / .docx / .pdf / .txt）
   - 提供多份资料，逐份处理

2. AI 读取并分析资料内容

3. 调用 spec-flow-main skill，将资料作为输入：
   - spec-flow 自动按其标准格式在 .spec-flow/active/{project-name}/ 下
     生成 proposal.md、requirements.md、design.md、tasks.md
   - WorkCopilot 不自行创建这些文件，完全复用 spec-flow 的产出

4. 展示整理结果摘要，用户确认或修改

里程碑 M1: 基础设施搭建（Sprint 1）
  T-001: 创建后端项目结构          [Low]  [4h]  backend-engineer
  T-002: 创建前端项目结构          [Low]  [4h]  frontend-engineer
  T-003: 配置数据库连接            [Med]  [4h]  backend-engineer
  T-004: 搭建认证模块              [Med]  [8h]  backend-engineer
  T-005: 配置 Docker（如需）       [Low]  [4h]  backend-engineer

里程碑 M2: 核心功能开发（Sprint 2-N）
  T-00x: （根据需求文档 FR 列表生成，每个 FR 至少拆为 1 个任务）

里程碑 M3: 集成 & 测试（Sprint N+1）
  T-0xx: 单元测试                  [Med]  [8h]  test-engineer
  T-0xx: 集成测试                  [High] [8h]  test-engineer
  T-0xx: 端到端测试                [High] [8h]  test-engineer

里程碑 M4: 文档 & 部署（Sprint N+2）
  T-0xx: API 文档                  [Low]  [4h]  backend-engineer
  T-0xx: 部署配置                  [Med]  [4h]  backend-engineer

### T-001: {任务标题}
- **里程碑**：M1 基础设施搭建
- **Sprint**：Sprint 1
- **复杂度**：Low / Medium / High
- **预估工时**：4h / 8h / 16h / 24h
- **Agent**：backend-engineer / frontend-engineer / test-engineer
- **文件**：`src/Controllers/...`, `src/Services/...`
- **依赖**：无 / T-003, T-004
- **验收标准**：AC-001（关联 requirements.md）
- **状态**：⏳ 待开始

## 关键路径

T-001 → T-003 → T-004 → T-010（首个核心功能）→ T-020（集成测试）

⏱️ 关键路径总工时：48h
📅 预计总工期：{根据工时 ÷ 每日有效编码时间 6h 估算}

⚠️ 瓶颈任务：T-004（认证模块），阻塞所有需要鉴权的后续任务

## 📊 汇总

| 里程碑 | 任务数 | 总工时 | 建议 Sprint |
|--------|-------|--------|------------|
| M1 基础设施 | 5 | 24h | Sprint 1 |
| M2 核心功能 | {n} | {x}h | Sprint 2-{n} |
| M3 测试 | {n} | {x}h | Sprint {n+1} |
| M4 文档部署 | {n} | {x}h | Sprint {n+2} |
| **合计** | **{total}** | **{total}h** | **{sprints} 个 Sprint** |

按 Agent 分配：
| Agent | 任务数 | 工时 |
|-------|-------|------|
| backend-engineer | {n} | {x}h |
| frontend-engineer | {n} | {x}h |
| test-engineer | {n} | {x}h |

1. 使用 vscode_askQuestions 请用户提供参考图：
   - 提示用户将设计图/截图/原型图放入项目目录（如 docs/design-refs/）
   - 支持格式：PNG / JPG / JPEG / WEBP
   - 可提供多张图（不同页面/模块各一张）

2. 使用 view_image 逐张读取参考图，分析并提取：
   - 页面布局结构（Header / Sidebar / Content / Footer）
   - 色彩方案（主色/辅助色/背景色/文字色）
   - 组件类型识别（表格/表单/卡片/图表/导航）
   - 页面数量与导航结构

3. 将分析结果保存为 docs/design-refs/analysis.md：
   ```markdown
   # 参考设计图分析

   ## 页面清单
   | 页面 | 参考图 | 布局类型 | 核心组件 |
   |------|--------|---------|----------|
   | 首页 | home.png | 侧边栏布局 | 数据卡片 ×4, 折线图, 表格 |
   | ... |

   ## 色彩方案
   - 主色：#1890FF
   - 辅助色：...

   ## 布局模式
   - 整体布局：左侧边栏 + 顶部导航 + 内容区
   - 响应式：...
   ```

4. 在 5.2 前端脚手架生成时，将 analysis.md 作为上下文传递给 frontend-engineer：
   - 页面结构参照参考图布局
   - 配色方案与参考图保持一致
   - 组件选型匹配参考图中识别到的类型

backend/
├── src/
│   └── {ProjectName}.Api/
│       ├── Program.cs              # 最小 Minimal API 入口（仅健康检查端点）
│       ├── appsettings.json
│       ├── appsettings.Development.json
│       └── {ProjectName}.Api.csproj
├── {ProjectName}.sln
├── .editorconfig
└── Directory.Build.props

backend/
├── app/
│   ├── __init__.py
│   └── main.py                    # 最小 FastAPI 入口（仅健康检查端点）
├── requirements.txt
├── pyproject.toml
└── .env.example

frontend/
├── src/
│   ├── main.tsx                   # 入口
│   ├── App.tsx                    # 空白根组件
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .eslintrc.cjs

frontend/
├── index.html                     # 空白 HTML 骨架
├── css/
│   └── style.css
├── js/
│   └── app.js
└── assets/

backend/
├── src/
│   └── {ProjectName}.Api/
│       ├── Program.cs                  # Minimal API 入口
│       ├── appsettings.json            # 配置文件
│       ├── appsettings.Development.json
│       ├── Controllers/                # API 控制器
│       │   └── HealthController.cs     # 健康检查
│       ├── Services/                   # 业务服务层
│       ├── Repositories/              # 数据访问层
│       ├── Models/                     # 实体模型
│       │   └── Entities/
│       ├── DTOs/                       # 数据传输对象
│       ├── Infrastructure/            # 基础设施
│       │   ├── Auth/                  # 认证模块
│       │   ├── Database/              # SqlSugar 配置
│       │   ├── Middleware/            # 中间件
│       │   └── Extensions/           # 服务扩展
│       └── {ProjectName}.Api.csproj
├── tests/
│   └── {ProjectName}.Tests/
│       ├── {ProjectName}.Tests.csproj
│       └── Controllers/
├── {ProjectName}.sln
├── .editorconfig
├── Directory.Build.props
└── Dockerfile (如需)

backend/
├── app/
│   ├── __init__.py
│   ├── main.py                      # FastAPI 入口
│   ├── core/
│   │   ├── config.py                # 配置管理
│   │   ├── security.py              # 认证模块
│   │   └── database.py              # 数据库连接
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/           # API 路由
│   │       └── deps.py              # 依赖注入
│   ├── models/                      # SQLAlchemy 模型
│   ├── schemas/                     # Pydantic Schema
│   ├── services/                    # 业务逻辑
│   └── repositories/               # 数据访问
├── tests/
├── alembic/                         # 数据库迁移
├── requirements.txt
├── pyproject.toml
├── Dockerfile (如需)
└── .env.example

backend/
├── src/
│   ├── {ProjectName}.Api/              # API 入口（网关层）
│   ├── {ProjectName}.Core/             # 核心业务逻辑（共享）
│   │   ├── Interfaces/                 # 服务接口定义
│   │   ├── Entities/                   # 领域实体
│   │   └── DTOs/                       # 共享 DTO
│   ├── {ProjectName}.Module.{ModuleA}/ # 功能模块 A
│   │   ├── Controllers/
│   │   ├── Services/
│   │   └── Repositories/
│   ├── {ProjectName}.Module.{ModuleB}/ # 功能模块 B
│   └── {ProjectName}.Infrastructure/   # 基础设施（数据库/缓存/消息）
├── tests/
│   ├── {ProjectName}.Core.Tests/
│   ├── {ProjectName}.Module.{ModuleA}.Tests/
│   └── {ProjectName}.Module.{ModuleB}.Tests/
├── {ProjectName}.sln
└── Directory.Build.props               # 统一版本管理

backend/
├── app/
│   ├── main.py
│   ├── core/                            # 共享核心
│   │   ├── config.py
│   │   ├── security.py
│   │   ├── database.py
│   │   └── shared_schemas.py            # 共享 Schema
│   ├── modules/
│   │   ├── {module_a}/                  # 功能模块 A
│   │   │   ├── router.py
│   │   │   ├── service.py
│   │   │   ├── models.py
│   │   │   └── schemas.py
│   │   └── {module_b}/                  # 功能模块 B
│   └── infrastructure/                  # 基础设施
├── tests/
│   ├── test_{module_a}/
│   └── test_{module_b}/
└── pyproject.toml

{project-root}/
├── backend/
│   ├── services/
│   │   ├── gateway/                     # API 网关（YARP/.NET 或 Kong）
│   │   │   ├── src/
│   │   │   ├── Dockerfile
│   │   │   └── README.md
│   │   ├── {service-a}/                 # 业务服务 A
│   │   │   ├── src/
│   │   │   ├── tests/
│   │   │   ├── Dockerfile
│   │   │   └── README.md
│   │   └── {service-b}/                 # 业务服务 B
│   ├── shared/
│   │   └── {ProjectName}.Contracts/     # 共享契约（DTO/事件/接口）
│   └── {ProjectName}.sln               # 或 pyproject.toml（全局）
├── frontend/                            # 前端
├── docs/                                # 项目文档
├── infra/
│   ├── docker-compose.yml               # 全部服务编排
│   ├── docker-compose.override.yml      # 本地开发覆盖
│   └── k8s/                             # Kubernetes 部署文件（可选）
│       ├── namespace.yaml
│       ├── {service-a}-deployment.yaml
│       └── {service-b}-deployment.yaml
├── .github/
│   └── workflows/                       # 每个服务独立 CI/CD
└── README.md

frontend/
├── src/
│   ├── main.tsx                     # 入口
│   ├── App.tsx                      # 根组件
│   ├── routes/                      # 路由配置
│   │   └── index.tsx
│   ├── pages/                       # 页面
│   │   ├── Login/
│   │   ├── Dashboard/
│   │   └── NotFound/
│   ├── components/                  # 通用组件
│   │   └── Layout/
│   ├── hooks/                       # 自定义 Hooks
│   ├── services/                    # API 调用层
│   │   ├── api.ts                   # Axios 实例
│   │   └── auth.ts                  # 认证 API
│   ├── stores/                      # 状态管理 (zustand)
│   │   └── useAuthStore.ts
│   ├── types/                       # TypeScript 类型
│   └── utils/                       # 工具函数
├── public/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── .eslintrc.cjs
└── .prettierrc

frontend/
├── index.html
├── css/
│   └── style.css
├── js/
│   ├── app.js
│   ├── api.js                      # API 调用封装
│   └── auth.js                     # 认证逻辑
└── assets/

# 触发条件: push 到 main/develop，PR 到 main
# 矩阵策略: 后端构建 + 前端构建 + 测试并行

jobs:
  backend:
    - checkout
    - 安装依赖（dotnet restore / pip install）
    - 编译（dotnet build / 语法检查）
    - 单元测试（dotnet test / pytest）
    - 代码覆盖率报告
  frontend:
    - checkout
    - npm ci
    - lint（eslint）
    - 单元测试（vitest）
    - 构建（vite build）
  docker: (if docker enabled)
    - needs: [backend, frontend]
    - 构建 Docker 镜像
    - 推送到容器注册表（标签: commit SHA + latest）

on:
  push:
    paths: ['backend/services/{service-name}/**', 'backend/shared/**']

appsettings.json                    # 通用配置（不含敏感信息）
appsettings.Development.json        # 开发环境
appsettings.Staging.json            # 预发布环境（如选三套）
appsettings.Production.json         # 生产环境（仅结构，值用环境变量）

.env.example                        # 环境变量模板（提交到 Git）
.env.development                    # 开发环境
.env.staging                        # 预发布环境（如选三套）
.env.production                     # 生产环境（仅结构，值用环境变量）

.env                                # 通用
.env.development                    # VITE_API_BASE_URL=http://localhost:8080
.env.staging                        # VITE_API_BASE_URL=https://staging-api.example.com
.env.production                     # VITE_API_BASE_URL=https://api.example.com

docker-compose.yml                  # 基础定义
docker-compose.override.yml         # 本地开发覆盖（端口映射、卷挂载、热重载）
docker-compose.staging.yml          # 预发布覆盖（如选三套）
docker-compose.prod.yml             # 生产覆盖（资源限制、日志驱动、重启策略）

1. 创建 {project}/.claude/agents/ 和 {project}/.claude/skills/
2. 复制 embedded-agents/* → .claude/agents/
3. 复制 embedded-skills/* → .claude/skills/
4. 复制 embedded-hooks/* → .github/hooks/（含 scripts/ 子目录）
5. 复制 embedded-prompts/* → .github/prompts/
6. 将 .claude/ 加入 .gitignore 的考量项（提示用户确认）

📦 项目创建完成！

📂 项目结构:
├── backend/                 ← 后端 (.NET / Python)
├── frontend/                ← 前端 (React / H5)
├── docs/                    ← 项目文档 (README + rules)
├── .claude/                 ← 项目级 Agent & Skill（6+10）
├── docker-compose.yml       ← Docker 编排 (如有)
├── .env.docker              ← Docker 环境变量模板 (如有)
├── .github/                 ← 工程轨道
├── .vscode/tasks.json       ← 验证链
├── .workcopilot/            ← 项目状态 & 记忆
└── .spec-flow/              ← 需求 & 设计文档

🚀 快速启动:
  后端: cd backend && dotnet run --project src/{ProjectName}.Api
  前端: cd frontend && npm install && npm run dev

🐳 Docker 启动 (如有):
  cp .env.docker .env && docker compose up -d
  访问: http://localhost (前端) | http://localhost:8080/swagger (后端API)

✅ 验证命令:
  Ctrl+Shift+P → "Run Task" → "verify"

🛠️ 后续可用 Skill（已注入项目 .claude/skills/）:
  - doa-apidoc   → 生成接口文档
  - doa-ppt      → 生成方案PPT
  - doa-quotation → 生成报价单
  - doa-metting  → 生成会议纪要
  - doa-image    → 生成可视化页面/长图
  - doa-harness  → 更新工程轨道
  - spec-flow-main → 结构化需求-设计-任务流
  - brainstorming → 创意探索与需求澄清
  - frontend-design → 高质量前端界面设计
  - ui-ux-pro-max → UI/UX 专业设计系统

🤖 项目级 Agent（已注入 .claude/agents/，优先于用户级）:
  - requirements-analyst / system-architect / backend-engineer
  - frontend-engineer / test-engineer / mermaid-diagram

{
  "version": "1.0",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z",
  "project": {
    "name": "{项目名}",
    "description": "{项目描述}",
    "backend": { "stack": "dotnet", "framework": "webapi", "orm": "sqlsugar" },
    "frontend": { "stack": "react", "ui": "antd" },
    "database": "sqlserver",
    "auth": "jwt",
    "docker": true,
    "scale": "monolith",
    "cicd": "github-actions",
    "environments": "dev-staging-prod"
  },
  "phases": {
    "phase1": { "status": "completed", "completedAt": "..." },
    "phase2": { "status": "completed", "completedAt": "..." },
    "phase3": { "status": "completed", "completedAt": "..." },
    "phase4": { "status": "completed", "completedAt": "..." },
    "phase5": { "status": "completed", "completedAt": "..." },
    "phase6": { "status": "completed", "completedAt": "..." },
    "phase7": { "status": "completed", "completedAt": "..." }
  },
  "iterations": [],
  "services": []
}

.workcopilot/
├── state.json              ← 项目配置 + 阶段状态 + 迭代记录
├── decisions.md            ← 架构决策记录（ADR）
├── tech-debt.md            ← 技术债 & 已知问题追踪
└── changelog.md            ← 变更日志（自动维护）

# 架构决策记录

## ADR-001: 选择 SqlSugar 作为 ORM
- **日期**：2025-01-01
- **状态**：已采纳
- **背景**：需要一个轻量级 ORM，支持 Code First 和多数据库
- **决策**：使用 SqlSugar 而非 EF Core
- **原因**：SqlSugar 更轻量、API 更简洁、支持更多数据库方言
- **后果**：团队需要学习 SqlSugar API，不能使用 EF Core 的 Migration 工具
- **关联**：Phase 1 技术选型

## ADR-002: 用户认证采用 JWT + Refresh Token
- **日期**：...

# 技术债 & 已知问题

| ID | 类型 | 描述 | 优先级 | 来源 | 状态 |
|----|------|------|--------|------|------|
| TD-001 | 性能 | 用户列表接口未分页 | P2 | iter-001 | ⏳ 待处理 |
| TD-002 | 安全 | 文件上传未做类型校验 | P1 | iter-003 | 🔄 处理中 |
| TD-003 | 重构 | UserService 过大需拆分 | P3 | iter-005 | ⏳ 待处理 |

# 变更日志

## [iter-003] 2025-02-15 — 订单管理模块
### 新增
- 订单 CRUD API（FR-010 ~ FR-015）
- 订单列表页面 + 详情页面
### 修改
- 用户模型增加 `lastOrderAt` 字段
### 技术债
- TD-003: UserService 职责过多，需拆分

必读：
  1. .workcopilot/state.json        → 项目配置 & 历史迭代
  2. .workcopilot/decisions.md      → 技术决策（避免矛盾选择）
  3. .workcopilot/tech-debt.md      → 已知问题（可能关联本次迭代）

按需读取：
  4. .spec-flow/active/*/tasks.md   → 当前任务状态
  5. .spec-flow/active/*/design.md  → 现有架构（增量设计时参考）

Q1: 本次迭代要做什么？
  - "🆕 新增功能模块"
  - "🐛 修复 Bug"
  - "♻️ 重构已有模块"
  - "🧪 补充测试"
  - "📦 新增微服务（仅微服务架构）"
  - "� 补充/更新需求 & 设计文档"
  - "📄 生成文档（API文档/PPT/会议纪要）"
  - "🔧 更新工程轨道（Harness）"

1. 检查 .spec-flow/active/{project-name}/ 目录下已有文件
2. 询问用户本次要补充哪些文档：
   - 提案文档（proposal.md）
   - 需求文档（requirements.md）
   - 系统设计（design.md）
   - 任务拆解（tasks.md）
3. 调用 spec-flow-main skill 执行对应阶段的文档生成/更新
   - spec-flow 负责 proposal.md、requirements.md、design.md、tasks.md 的创建和更新
   - WorkCopilot 不自行创建这些文件
4. 更新 state.json 中对应 Phase 的状态

迭代流程图:
  用户描述功能 → brainstorming 探索需求
    → 可选：用户提供参考设计图（同 5.0 参考图导入流程）
    → 调用 spec-flow-main skill 更新 requirements.md（追加 FR/NFR）
    → 调用 spec-flow-main skill 更新 design.md（增量设计）
    → 调用 spec-flow-main skill 更新 tasks.md（追加任务，分配里程碑 & 工时）
    → backend-engineer / frontend-engineer 实现
      （如有参考图，frontend-engineer 参照 analysis.md 生成 UI）
    → test-engineer 编写测试
    → 迭代验证（测试 + lint + 构建检查）
    → 双向同步（tasks.md 状态 + state.json 记录）

⏳ 待开始 → 🔄 进行中 → ✅ 完成
                       → ❌ 阻塞（标注阻塞原因）
                       → ⏭️ 跳过（标注跳过原因）

{
  "iterations": [
    {
      "id": "iter-001",
      "type": "feature",
      "description": "用户管理模块",
      "milestone": "M2",
      "sprint": "Sprint 2",
      "startedAt": "...",
      "completedAt": "...",
      "tasks": [
        { "id": "T-010", "status": "completed", "actualHours": 6 },
        { "id": "T-011", "status": "completed", "actualHours": 10 },
        { "id": "T-012", "status": "completed", "actualHours": 4 }
      ],
      "estimatedHours": 24,
      "actualHours": 20,
      "filesChanged": ["src/Controllers/UserController.cs", "..."],
      "decisions": ["ADR-003"],
      "verification": { "tests": "pass", "lint": "pass", "build": "pass" }
    }
  ]
}

迭代验证清单:
  1. 运行测试：dotnet test / pytest / vitest
  2. 运行 lint：eslint / dotnet format --verify-no-changes
  3. 构建检查：dotnet build / vite build（确保无编译错误）
  4. 安全检查：对新增代码检查 docs/rules/security.md 中的约束
  5. 更新文档：如有新 API，提醒用户是否需要更新 API 文档

# 需要更新的字段（按实际 README 结构定位）：
1. Docker 版本表格中的「最新标签」→ 新版本号
2. Docker 版本表格中的「完整镜像地址」→ 新完整地址
3. Docker 版本表格中的「镜像 Digest」→ 新 Digest（从 docker push 输出中提取）
4. 构建 & 推送命令示例中的版本号 → 新版本号

会话工作完成
  → 0. 回顾本次会话操作清单，对照「变更检测矩阵」判定需更新的文件
  → 1. 更新 state.json（updatedAt + 里程碑进度 + 新迭代记录）
  → 2. 追加 changelog.md（本次变更摘要）
  → 3. 更新 docs/README.md（Docker 版本/Digest、技术栈、接口等）
  → 4. 如有决策：追加 decisions.md
  → 5. 如有技术债变更：更新 tech-debt.md
  → 6. 如有任务状态变更：更新 tasks.md
  → 7. 输出更新摘要（列出实际更新了哪些文件及关键变更）

{
  "updatedAt": "2026-05-07 10:30:00",
  "milestones": {
    "M{x}": { "tasksCompleted": "{更新后的数量}" }
  },
  "iterations": [
    {
      "id": "iter-{下一个编号}",
      "date": "2026-05-07 10:30:00",
      "scope": "{本次会话做了什么的一句话摘要}"
    }
  ]
}

## [iter-{id}] {yyyy-MM-dd HH:mm:ss} — {范围描述}
### 新增
- {新增的功能/文件}
### 修改
- {修改的内容}
### 修复
- {修复的问题}
### 技术债
- {新增或关闭的技术债}

1. 询问服务名称和职责描述
2. 在 backend/services/ 下创建新服务目录（复用 5.1 后端脚手架模板）
3. 更新 gateway 路由配置（YARP / Nginx）
4. 更新 docker-compose.yml 添加新服务
5. 生成该服务的独立 CI/CD workflow
6. 更新 shared/Contracts/ 添加新的契约
7. 更新 state.json 的 services 列表