fullstackspec

FullStackSpec

全栈标准化交付技能包，基于 Superpowers + OpenSpec 规范，适配 Vue3(JavaScript) + Python3 + 多数据库(MySQL/SQLite/PostgreSQL) + 大模型应用 技术栈的中小型交付项目，深度集成Trae编辑工具。

核心理念

• OpenSpec = 全栈唯一事实数据源 — 需求、架构、数据库、接口、前端交互规范全部归档到 spec，Git 持久化
• 先 Spec 后代码 — 任何变更先改 spec，再同步三层代码，杜绝跨层不一致
• TDD 强制流程 — 先写测试再写代码，每层代码与 spec 严格对齐
• 三层一致性校验 — DB API Frontend 字段、校验规则、错误码自动对齐

安装

npm install fullstackspec

安装完成后，10 个 Skills 和模板文件会自动复制到项目目录：

• .trae/skills/ — Skills 定义
• templates/fullstack/ — spec 模板、superpowers.config 等

快速开始

1. 初始化项目

在 Trae 对话中输入：

fullstack-init

自动生成标准目录结构、superpowers.config、Git 仓库。

2. 提出需求

opsx-propose 全栈需求：用户会员充值页面，后端充值订单、支付回调、余额计算，前端充值表单、订单列表、余额弹窗

自动在 openspec/specs/member_recharge/ 下生成七份规范文件：

• requirement_analysis.md — 需求分析报告（需求来源、现状分析、用户画像、竞品参考、风险评估、AI关联分析）
• brd.md — 业务需求文档（业务背景、目标、范围、核心流程、约束条件、术语定义）
• feature_list.md — Feature List（七列：业务模块、场景描述、核心痛点、功能名称、功能说明、交付优先级、AI关联度）
• proposal.md — 业务目标、用户场景、边界规则
• architecture.md — 架构方案对比与推荐
• fullstack.spec.yaml — 数据库 + 接口 + 前端 + 错误码全栈规范
• test_cases.md — 全栈验收用例

Feature List 生成后可选择生成高保真原型页面（openspec/ui_layout/*.html），基于 6 种布局模板自动匹配页面类型。

生成后自动执行 opsx-verify 校验规范，校验通过后自动执行 opsx-sync 锁定基线，无需手动触发。

3. 校验规范

opsx-verify

检查 spec 完整性，校验 DB API 前端三层一致性。校验通过后自动执行 opsx-sync 锁定基线，无需手动触发。

4. 锁定基线

opsx-sync

将校验通过的 spec 提交 Git，锁定为基线版本。通常由 opsx-verify 校验通过后自动触发。

5. 拆分任务

fullstack-plan

自动拆分全栈最小任务，按 DB → 后端 → 前端依赖排序，每个任务绑定 spec 验收标准。对 Feature List 中的每个业务模块执行头脑风暴，深度思考实现方案，结合需求分析、BRD、原型页面等全部产出物。

6. TDD 编码

fullstack-tdd

按"先写测试再写代码"流程，分层实现数据库、后端接口、前端页面，每层强制校验与 spec 一致。编码完成后自动执行 fullstack-crosscheck 进行全量三层校验，校验通过后自动启动前后端服务，无需手动触发。

7. 三层一致性校验

fullstack-crosscheck

全量校验 DB API Frontend 字段、校验规则、错误码是否完全对齐，含安全检查。通常由 fullstack-tdd 编码完成后自动触发，校验通过后自动启动前后端服务。

8. 自测联调

fullstack-debug

批量执行 spec 中定义的全栈测试用例，bug 定位与修复。

9. 归档交付

opsx-archive

归档完整迭代资产（spec、测试报告、变更记录），写入 Git 永久留存。

需求变更时

fullstack-iterate

先改 spec → 再改代码，自动对比差异只生成增量代码和测试。

标准工作流

fullstack-init
    ↓
opsx-propose ──自动──→ opsx-verify ──自动──→ opsx-sync
    ↓
fullstack-plan
    ↓
fullstack-tdd ──自动──→ fullstack-crosscheck ──自动──→ 启动前后端服务
    ↓
fullstack-debug
    ↓
opsx-archive

迭代变更：fullstack-iterate（先改spec → 校验 → 同步 → 增量编码 → 校验 → 归档）

10 个 Skills 速查

Skill	功能	触发时机
fullstack-init	初始化项目标准目录结构、superpowers.config	新项目启动
opsx-propose	生成全栈规范提案（7份文件：需求分析/BRD/Feature List/proposal/architecture/spec/test_cases），自动触发 verify → sync	提出新需求
opsx-verify	校验规范完整性 + 三层一致性，通过后自动触发 sync	spec 编写后
opsx-sync	同步 spec 到 Git，锁定基线	由 verify 自动触发
fullstack-plan	拆分全栈最小任务，依赖排序，每个业务模块执行头脑风暴	spec 定稿后
fullstack-tdd	TDD 编码，先测试后代码，自动触发 crosscheck	开始编码
fullstack-crosscheck	三层一致性校验，通过后自动启动前后端服务	由 tdd 自动触发
fullstack-debug	全栈自测联调、bug 修复	联调阶段
opsx-archive	归档交付资产到 Git	准备上线
fullstack-iterate	需求迭代，先改 spec 再改代码	需求变更

项目目录结构

项目根目录/
├── openspec/                    # OpenSpec 规范仓库（核心资产，纳入 Git）
│   ├── specs/
│   │   └── {module}/
│   │       ├── requirement_analysis.md
│   │       ├── brd.md
│   │       ├── feature_list.md
│   │       ├── proposal.md
│   │       ├── architecture.md
│   │       ├── fullstack.spec.yaml
│   │       ├── test_cases.md
│   │       ├── CHANGELOG.md
│   │       ├── task_plan.md
│   │       ├── test_report.md
│   │       └── delivery.md
│   └── ui_layout/               # 高保真原型页面（可选）
│       └── {module}_{page}.html
├── backend/                     # Python3 后端
│   ├── app/
│   │   ├── api/                 # FastAPI 路由
│   │   ├── services/            # 业务逻辑
│   │   ├── models/              # SQLAlchemy 模型
│   │   ├── schemas/             # Pydantic Schema
│   │   ├── core/                # 全局配置（数据库连接、环境变量、LLM密钥）
│   │   └── llm/                 # 大模型集成（按需）
│   ├── .env                     # 环境变量（数据库/LLM密钥，不提交Git）
│   ├── .env.example             # 环境变量模板（提交Git，使用占位符）
│   └── tests/
├── frontend/                    # Vue3 前端（JavaScript）
│   ├── src/
│   │   ├── api/                 # 接口请求封装
│   │   ├── views/               # 页面
│   │   ├── components/          # 组件
│   │   ├── stores/              # Pinia 状态管理
│   │   └── router/              # 路由
│   └── tests/
├── sql/                         # 数据库脚本
│   ├── migrations/
│   └── seeds/
├── tests/                       # 全栈联调测试
└── superpowers.config           # Superpowers 统一配置

fullstack.spec.yaml 核心结构

规范文件覆盖四大块，确保全栈一致性：

# 数据库：表结构、字段、索引、约束
database:
  tables: [...]

# 接口：路径、入参、出参、错误码
api:
  endpoints: [...]

# 前端：路由、页面、表单校验、表格列、弹窗
frontend:
  routes: [...]
  pages: [...]

# 错误码：后端消息 + 前端提示文案
error_codes: [...]

三层一致性保障：

• 数据库字段约束 ≡ 后端入参校验 ≡ 前端表单校验
• 后端接口返回字段 ≡ 前端页面渲染字段
• 错误码、提示文案前后端统一

superpowers.config 配置

enforced:
  spec_consistency_check: true    # 所有代码必须与 spec 对齐
  tdd_workflow: true              # 先写测试再写代码
  cross_layer_check: true         # DB ↔ API ↔ 前端三层校验
  auto_test_generation: true      # 依据 spec 自动生成测试

constraints:
  no_spec_no_code: true           # 无 spec 禁止生成业务代码
  test_coverage_threshold: 80     # 测试覆盖率门槛
  change_spec_first: true         # 修改需求必须先改 spec

tech_stack:
  frontend: vue3_js            # Vue3 + JavaScript（不使用 TypeScript）
  backend: python3
  database: "{DB_TYPE}"        # mysql / sqlite / postgresql，由用户选择
  llm_enabled: true

大模型平台配置

llm:
  platform: "{dify|bailian|other|none}"  # 大模型平台类型
  # 实际 API Key 和 URL 存储在 backend/.env，不提交Git

不同规模项目适配

规模	spec 策略	流程策略
小型（单页面、配置功能）	精简 proposal，保留核心 spec.yaml	TDD + spec 校验
中型（完整用户模块、支付）	完整五步标准流程	全量测试 + 三层校验
大型（多模块联动）	分模块拆分 spec，共享全局错误码	分批流水线，逐模块归档

核心收益

1. 交付标准统一 — 每个人都走需求→设计→TDD→校验→归档，不会有人缺文档、没测试
2. 降低交接成本 — 新人只看 openspec 目录即可掌握全栈逻辑
3. 根除跨层 bug — 改接口忘改前端、新增字段漏加校验等问题不再发生
4. 单人效率提升 — 自动拆分任务、生成测试、校验规范，不用人工多层核对
5. 项目长期可维护 — 所有设计和变更记录 Git 归档，故障可回溯

避坑指南

1. 严禁"先写代码后补 spec"，会导致三层校验失效
2. 修改需求必须同步更新 spec 里 DB + API + 前端三部分，只改一处会报错
3. 多人并行时，每次 opsx-sync 先拉取远端最新 spec
4. 不要省略 opsx-archive 归档步骤，否则迭代多轮后无变更记录
5. superpowers.config 必须绑定本地 openspec/ 目录路径

License

MIT