SVM-Stack (Skill Virtual Machine)

本项目是一套基于 Claude/Trae 的全栈开发 Agent 协作体系。通过定义四个核心 Skill，实现从需求分析、数据库建模、后端接口开发到前端页面实现的自动化工作流。

核心架构与 Skill 概览

本项目包含四个专职 Agent Skill，分别负责不同的开发领域：

Skill 名称	对应文件	核心职责	触发场景
project-orchestrator	.claude/skills/project-orchestrator/SKILL.md	总控与编排。负责跨端一致性审计、流程监督。	"开发一个用户管理功能"、"全栈实现订单模块"
database-expert	.claude/skills/database-expert/SKILL.md	数据层。MySQL 8.0 建模、DDL 生成、索引优化。	"设计订单表结构"、"添加一个字段"
backend-expert	.claude/skills/backend-expert/SKILL.md	后端层。Java Spring Boot 接口实现、分层架构。	"实现用户登录接口"、"生成 Controller 代码"
frontend-expert	.claude/skills/frontend-expert/SKILL.md	前端层。Vue 3 + TS 页面与组件开发、接口对接。	"开发登录页面"、"封装 API 请求"

---

🚀 快速开始 (Workflow)

推荐使用 project-orchestrator 作为入口，通过它来调度其他 Agent。

1. 启动全栈开发任务

在对话框中输入类似指令：

"请使用 project-orchestrator 开发一个【商品管理】模块，包含商品的增删改查功能。"

Orchestrator 将自动执行以下流程：

1. Step 1 (Plan & Database): 调用 database-expert 设计数据库表结构（如 product 表），并生成 /sql/init.sql。
2. Step 2 (Contract): 定义前后端接口契约，更新 docs/api_contract.md。
3. Step 3 (Backend): 指挥 backend-expert 生成 Entity, Mapper, Service, Controller 代码。
4. Step 4 (Frontend): 指挥 frontend-expert 生成 API 定义、TS 类型和 Vue 组件。

2. 单点功能开发

你也可以直接调用特定 Expert 处理具体任务：

• 数据库变更：

  "请让 database-expert 为 user 表添加一个 phone 字段，并给出索引建议。"

• 后端接口调整：

  "请 backend-expert 修改 UserContoller，增加一个根据手机号查询用户的接口。"

• 前端页面优化：

  "请 frontend-expert 优化 UserList.vue 的表格样式，增加分页组件。"

---

🛠 通用开发规约 (Global Constraints)

所有 Agent 必须严格遵守以下规范：

1. 目录意识

• 根目录优先：所有操作基于项目根目录。
• 结构保持：严禁随意更改 backend/ 或 frontend/ 的一级目录结构。

2. 命名规范

类型	规范	示例
数据库/JSON	snake_case	user_id, create_time
Java/TS 变量	camelCase	userId, createTime
Java 类名/Vue 组件	PascalCase	UserController, UserProfile.vue

3. 前后端契约

• 统一响应体：后端必须封装 Result<T>。

  public class Result<T> {
      private Integer code;
      private String msg;
      private T data;
  }

• 错误处理：
  • 后端：@RestControllerAdvice 全局异常处理。
  • 前端：Axios 拦截器统一处理错误码。

---

📂 交付物标准

Database Expert

• DDL：严禁物理外键，使用逻辑外键。
• 审计字段：所有表必须包含 id (PK), create_time, update_time, is_deleted。

Backend Expert

• 分层：
  • Entity: 数据库映射 (与 DB 严格一致)。
  • DTO: 接收前端参数。
  • VO: 响应前端数据。
• Swagger: 所有接口必须包含 @Operation 或 @Tag 注解。

Frontend Expert

• 类型安全：必须先定义 TypeScript interface，再写组件。
• API 封装：所有请求封装在 src/api/ 目录下。

---

💡 最佳实践

1. 始终从数据开始：任何功能变更，先思考数据库结构变化，调用 database-expert。
2. 契约先行：在写代码前，确认 docs/api_contract.md 或 Swagger 定义。
3. 冲突检测：project-orchestrator 会自动检查类型映射（如 Decimal vs BigDecimal vs number），请留意其警告。