# Vibe Coding CN - 元规范 (Level 0)

> 本文件定义整个工作空间的约束规范，所有子项目必须遵循。

## 文档层级体系

| 级别 | 目录 | 文件 | 职责 |
|------|------|------|------|
| 0级 | `/` (本目录) | `CLAUDE.md` | 工作流程、文档标准、Canvas规范 |
| 1级 | `/[project]/` | `CLAUDE.md` + `architecture.canvas` | 项目配置、整体架构 |
| 2级 | `/[project]/[subproject]/` | `CLAUDE.md` + `*.canvas` | 子项目配置、子系统架构 |
| 3级 | `/[project]/[subproject]/[module]/` | `*.canvas` | 模块详细设计（可选） |

**约束继承**：下级继承上级所有约束，可添加但不可违反。

---

## 工作流程约束

### 开发流程
```
Canvas 设计 → CLAUDE.md 配置 → 代码实现 → 测试验证
```

### 前后端协作顺序
同时涉及前后端的功能，按以下顺序开发：
1. **后端 API** - 先实现接口
2. **前端调用** - 后实现页面

### 任务管理
- 任务从 Obsidian Canvas 开始
- 使用 Vibe Kanban 跟踪进度
- 任务编号格式：`任务YYYYMMDD-NN[-suffix]`

---

## 操作命令

标准化命令格式，支持命令格式和自然语言两种触发方式。

### 命令格式
```
@<category>/<command> [--options] [<arguments>]
```

### 常用命令速查

| 命令 | 说明 | 自然语言触发 |
|------|------|--------------|
| `@check/spec <project>` | 规范检查 | "检查 xxx 是否符合规范" |
| `@project/create --name <name>` | 创建项目 | "创建新项目 xxx" |
| `@task/list --project <project>` | 任务列表 | "列出 xxx 的任务" |
| `@gen/context <project>` | 生成上下文 | "生成 xxx 的上下文" |

### 命令分类

| 分类 | 前缀 | 用途 |
|------|------|------|
| `check` | `@check/` | 检查与验证 |
| `project` | `@project/` | 项目管理 |
| `sync` | `@sync/` | 同步操作 |
| `gen` | `@gen/` | 生成文档 |
| `task` | `@task/` | 任务管理 |
| `dev` | `@dev/` | 开发辅助 |

详细命令定义见 `i18n/zh/prompts/04-命令提示词/`

---

## 文档命名规范

| 文件名 | 用途 | 级别 |
|--------|------|------|
| `CLAUDE.md` | AI 配置文件 | 0/1/2级 |
| `architecture.canvas` | 整体/子系统架构图 | 1/2级 |
| `database.canvas` | 数据库设计 | 2级 |
| `[feature].canvas` | 功能/模块设计 | 2/3级 |
| `workflow.md` | 工作流程说明 | 任意 |

---

## Canvas 节点规范

### 颜色编码标准（所有级别统一）

| 颜色代码 | 颜色 | 含义 | 用途 |
|----------|------|------|------|
| `"1"` | 红色 | 入口/标题 | 项目入口点、系统标题 |
| `"2"` | 橙色 | 配置/存储 | 数据库、缓存、配置层 |
| `"3"` | 黄色 | 业务模块 | 核心业务功能模块 |
| `"4"` | 绿色 | 用户端 | 小程序、H5、移动端 |
| `"5"` | 青色 | 管理端 | 后台管理系统 |
| `"6"` | 蓝色 | 后端服务 | API、后端系统 |

### 1级 Canvas 必须节点 (architecture.canvas)

```json
必须包含：
- title: 项目标题 (color: "1")
- user-client: 用户端入口 (color: "4")  // 如有
- admin-client: 管理端入口 (color: "5") // 如有
- backend: 后端服务 (color: "6")
- database: 数据存储 (color: "2")
- external: 外部服务 (color: "2")       // 如有
```

### 2级 Canvas 必须节点

```json
必须包含：
- title: 子系统标题 (color: "1")
- entry: 入口点 (color: "6")
- modules[]: 功能模块列表 (color: "3")
- dependencies: 依赖服务 (color: "2")   // 如有
```

### 3级 Canvas 必须节点

```json
必须包含：
- title: 模块标题 (color: "1")
- api: 接口定义 (color: "6")           // 如有
- data-model: 数据模型 (color: "2")
- flow: 业务流程 (color: "3")
```

---

## 技术栈参考

### 后端技术栈
| 场景 | 推荐技术 |
|------|----------|
| 轻量级 API | Hono + Cloudflare Workers |
| 全栈 Java | Spring Boot 3 + MyBatis Plus |
| 数据库 | D1 (Cloudflare) / MySQL |
| 缓存 | Redis / KV |

### 前端技术栈
| 场景 | 推荐技术 |
|------|----------|
| Web 管理后台 | Vue 3 + Vite + Element Plus |
| 小程序/H5 | UniApp + Vue 3 |
| 移动端 | UniApp / Taro |

### 部署平台
| 平台 | 用途 |
|------|------|
| Cloudflare | Workers, D1, Stream, Pages |
| Vercel | 静态站点, Serverless |

---

## Git 提交规范

### Commit 类型
| 类型 | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档更新 |
| `style` | 代码格式 |
| `refactor` | 重构 |
| `test` | 测试 |
| `chore` | 构建/工具 |

### 格式
```
<type>: <description>

[optional body]
```

---

## 模板使用

所有新项目使用 `/templates/` 下的模板：

| 模板文件 | 用途 |
|----------|------|
| `project.claude.md.template` | 1级项目 CLAUDE.md |
| `subproject.claude.md.template` | 2级子项目 CLAUDE.md |
| `module.claude.md.template` | 3级模块 CLAUDE.md |
| `architecture.canvas.template` | 1级项目架构图 |
| `subsystem.canvas.template` | 2级子系统架构图 |
| `module.canvas.template` | 3级模块设计图 |

---

## 现有项目

| 项目 | 类型 | 状态 |
|------|------|------|
| `tg-live-game/` | 直播游戏系统 | 开发中 |
| `yshop/` | 点餐系统 | 开发中 |
| `askyi/` | 问答应用 | 开发中 |
| `pwtk-admin-web/` | 管理后台 | 开发中 |