monisuo/.agents/skills/monisuo-dev/SKILL.md

---
name: monisuo-dev
description: Monisuo 项目结构化开发流程技能。用于需求分析、模块化开发、测试验证、构建部署的完整工作流。
---

# Monisuo 开发技能

用于 Monisuo 项目的结构化开发流程，确保代码质量和开发效率。

## 工作流程

```
需求分析 → 模块化开发 → [启动独立Agent] → 测试验证 → 构建部署
   ↑                                          │
   └──────────── Bug 修复 ←───────────────────┘
```

## ⚠️ 多 Agent 执行策略

为避免上下文过长，**Phase 3-4 必须启动独立 Agent 执行**。

### Agent 切换点

```
Phase 1-2: 主对话完成（需求 + 开发）
    ↓
    ↓ 开发完成后，启动独立 Agent
    ↓
Phase 3-4: 独立 Agent 完成（测试 + 构建）
    ↓
    ↓ 如发现 Bug，返回主对话修复
    ↓
重新启动 Agent 测试验证
```

### Agent 通信协议

**传递给测试 Agent 的信息**:
```yaml
feature_spec: docs/features/[feature-name].md  # Feature Spec 路径
changed_files:                                  # 变更的文件列表
  - src/main/java/com/example/...
  - flutter_monisuo/lib/...
test_requirements:                              # 测试要求
  - API 测试
  - Flutter 单元测试
  - 代码审查
build_targets:                                  # 构建目标
  - spring-boot
  - flutter-web
```

## Phase 1: 需求结构化定义 (Prompt Engineering)

### 目标
将模糊的需求转化为结构化的 Feature Spec 文档。

### 输入
- 用户的需求描述（自然语言）
- 业务场景说明
- 技术约束条件

### 输出
- `docs/features/feature-name.md` - 结构化的功能规格文档

### Feature Spec 模板

```markdown
# [功能名称] 功能规格

## 1. 功能概述
- **功能名称**: 
- **优先级**: P0/P1/P2
- **负责人**: 
- **预计工期**: 

## 2. 业务背景
- 当前痛点
- 解决方案
- 预期收益

## 3. 功能详情

### 3.1 用户故事
作为 [角色]，我希望 [行为]，以便 [目的]

### 3.2 功能列表
- [ ] 功能点 1
- [ ] 功能点 2
- [ ] 功能点 3

### 3.3 UI/UX 设计
- 页面布局
- 交互流程
- 原型链接

## 4. 技术方案

### 4.1 架构设计
- 前端方案 (Flutter)
- 后端方案 (Spring Boot)
- 数据库设计

### 4.2 API 设计
```
GET /api/endpoint
POST /api/endpoint
```

### 4.3 数据模型
```dart
class Model {
  final String id;
  // ...
}
```

## 5. 测试用例
- [ ] 正常流程测试
- [ ] 异常流程测试
- [ ] 边界条件测试

## 6. 验收标准
- [ ] 功能完整
- [ ] 测试通过
- [ ] 代码审查
- [ ] 性能达标

## 7. 依赖与风险
- 依赖项
- 潜在风险
- 缓解措施
```

### 执行步骤

1. **需求收集**
   ```bash
   # 与用户确认需求
   # 识别关键业务场景
   # 明确技术约束
   ```

2. **创建文档**
   ```bash
   mkdir -p docs/features
   touch docs/features/[feature-name].md
   ```

3. **填充模板**
   - 完善用户故事
   - 设计 API 接口
   - 定义数据模型
   - 编写测试用例

4. **评审确认**
   - 与用户确认需求理解正确
   - 调整优先级和范围

---

## Phase 2: 模块化生成 (Iterative Coding)

### 目标
根据 Feature Spec 分模块实现功能。

### 开发策略

#### 2.1 按模块拆分
```
Feature
├── Frontend (Flutter)
│   ├── UI 组件
│   ├── 状态管理 (Provider)
│   └── API 调用 (Dio)
├── Backend (Spring Boot)
│   ├── Controller
│   ├── Service
│   └── Repository
└── Database
    └── Migration Scripts
```

#### 2.2 迭代开发顺序

1. **数据层优先**
   - 数据库表结构
   - Entity 定义
   - Repository 实现

2. **后端 API**
   - Controller 接口
   - Service 业务逻辑
   - 单元测试

3. **前端实现**
   - Model 定义
   - API Service
   - UI 组件
   - 状态管理

### 开发命令

```bash
# Flutter 开发
cd flutter_monisuo
flutter pub get
flutter run -d chrome

# 后端开发
cd ../
mvn spring-boot:run
```

### 代码规范

#### Flutter
- 使用 `flutter analyze` 检查代码
- 遵循 Effective Dart 规范
- 使用 Provider 进行状态管理
- 统一使用 AppSpacing, AppRadius, AppColorScheme

#### Spring Boot
- 遵循阿里巴巴 Java 开发手册
- 使用 Lombok 简化代码
- 统一异常处理
- RESTful API 设计

### 🔄 Phase 2 完成后：启动测试 Agent

**当开发完成后，立即启动独立 Agent 执行测试和构建**。

使用 Agent tool 启动：

```
subagent_type: general-purpose
description: 测试验证与构建
prompt: |
  你是 Monisuo 项目的测试 Agent。请执行以下任务：

  ## 1. 读取 Feature Spec
  - 文件路径: docs/features/[feature-name].md
  - 理解功能需求和验收标准

  ## 2. 代码审查
  - 检查变更的文件（见 git diff）
  - 验证代码规范
  - 检查错误处理

  ## 3. 执行测试
  - API 测试: ./tests/api/test-[feature].sh
  - Flutter 测试: cd flutter_monisuo && flutter test
  - 后端测试: mvn test

  ## 4. 构建
  - 后端: mvn clean package -DskipTests
  - Flutter: flutter build web --release --dart-define=ENV=prod

  ## 5. 输出结果
  - 测试通过/失败
  - Bug 列表（如有）
  - 构建产物路径

  如果发现 Bug，列出详细信息和修复建议，返回给主对话修复。
```

---

## Phase 3: 测试与重构 (Validation & Refactoring)

> ⚠️ **此阶段由独立 Agent 执行**，主对话只负责接收结果和修复 Bug。

### 目标
确保代码质量和功能正确性。

### 3.1 使用 Clean Code 技能

```bash
# 应用 clean-code 技能进行代码优化
# 参考: ~/.agents/skills/clean-code/SKILL.md
```

**优化重点**:
- 代码可读性
- 函数复杂度
- 重复代码
- 命名规范

### 3.2 自动化测试

#### API 接口测试

**测试脚本位置**: `tests/api/`

**测试脚本模板**:
```bash
#!/bin/bash
# API 测试脚本

BASE_URL="http://localhost:5010"
TOKEN=""

echo "=== API 测试开始 ==="

# 1. 登录测试
echo "1. 测试登录接口..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"phone":"13800138000","password":"123456"}')
  
TOKEN=$(echo $RESPONSE | jq -r '.data.token')
echo "✓ 登录成功，Token: ${TOKEN:0:20}..."

# 2. 获取用户信息
echo "2. 测试获取用户信息..."
curl -s -X GET "$BASE_URL/api/user/info" \
  -H "Authorization: Bearer $TOKEN" | jq '.'
echo "✓ 获取用户信息成功"

# 3. 更多测试用例...
# TODO: 根据具体功能添加

echo "=== API 测试完成 ==="
```

**运行测试**:
```bash
chmod +x tests/api/test-*.sh
./tests/api/test-feature.sh
```

#### Flutter 单元测试

```bash
cd flutter_monisuo
flutter test
```

### 3.3 Bug 修复循环

```
Agent 测试 → 发现 Bug → 主对话修复 → 重新启动 Agent → 通过
```

**修复流程**:
1. Agent 报告 Bug
2. **主对话**修复代码
3. **重新启动 Agent** 验证修复
4. 直到全部通过

### 3.4 重新启动测试 Agent

Bug 修复后，再次启动 Agent 验证：

```
subagent_type: general-purpose
description: 验证 Bug 修复
prompt: |
  验证以下 Bug 是否已修复：

  ## Bug 列表
  [从上次 Agent 结果中获取]

  ## 验证步骤
  1. 重新运行相关测试
  2. 确认 Bug 已修复
  3. 检查是否有回归问题

  输出：修复确认 / 仍需修复
```

### 3.4 代码审查清单

- [ ] 代码符合规范
- [ ] 无硬编码值
- [ ] 错误处理完善
- [ ] 日志记录清晰
- [ ] 测试覆盖完整
- [ ] 性能达标

---

## Phase 4: 构建与部署 (Build & Deploy)

> ⚠️ **此阶段由独立 Agent 执行**，与 Phase 3 合并在同一个 Agent 中。

### 目标
构建生产版本并提交代码。

### 4.1 构建命令

#### 后端 (Spring Boot)
```bash
# 清理并打包（跳过测试）
mvn clean package -DskipTests

# 完整构建（包含测试）
mvn clean package

# 只编译检查
mvn compile
```

**输出**: `target/monisuo-*.jar`

**验证构建**:
```bash
# 检查 JAR 文件是否生成
ls -la target/*.jar

# 测试 JAR 可执行性
java -jar target/monisuo-*.jar --spring.profiles.active=dev
```

#### Flutter Web
```bash
cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod
```

**输出**: `flutter_monisuo/build/web/`

#### Admin 后台
```bash
cd monisuo-admin
pnpm install
pnpm build
```

**输出**: `monisuo-admin/dist/`

### 4.2 Git 提交流程

```bash
# 1. 检查变更
git status
git diff

# 2. 添加文件
git add .

# 3. 提交（遵循 Conventional Commits）
git commit -m "feat(module): 简短描述

- 详细说明 1
- 详细说明 2
- 详细说明 3

Closes #issue-number"

# 4. 推送到远程
git push origin main
```

### 4.3 提交消息规范

**格式**:
```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型**:
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建/工具

**示例**:
```
feat(auth): 添加用户登录功能

- 实现手机号+密码登录
- 添加 JWT Token 验证
- 实现自动刷新 Token

Closes #123
```

---

## 项目结构

```
monisuo/
├── .agents/
│   └── skills/
│       └── monisuo-dev/
│           └── SKILL.md          # 本文件
├── docs/
│   └── features/                 # Feature Specs
│       ├── user-auth.md
│       └── trade-system.md
├── flutter_monisuo/              # Flutter 前端
│   ├── lib/
│   ├── build/web/                # Web 构建产物
│   └── BUILD.md
├── monisuo-admin/                # Vue 管理后台
│   ├── src/
│   └── dist/                     # 构建产物
├── src/                          # Spring Boot 后端
│   └── main/
├── tests/
│   ├── api/                      # API 测试脚本
│   └── e2e/                      # 端到端测试
└── README.md
```

---

## 常用命令速查

### Flutter
```bash
flutter pub get                  # 安装依赖
flutter run -d chrome            # 开发模式
flutter analyze                  # 代码检查
flutter test                     # 运行测试
flutter build web --release --dart-define=ENV=prod  # 生产构建
```

### Admin
```bash
pnpm install                     # 安装依赖
pnpm dev                         # 开发模式
pnpm build                       # 生产构建
```

### Maven
```bash
mvn compile                      # 编译
mvn test                         # 运行测试
mvn clean package -DskipTests    # 打包（跳过测试）
mvn clean package                # 完整打包
mvn spring-boot:run              # 运行开发服务
```

### Git
```bash
git status                       # 查看状态
git add .                        # 添加所有
git commit -m "message"          # 提交
git push origin main             # 推送
```

---

## 环境配置

| 环境 | ENV | API 地址 |
|------|-----|----------|
| 生产 | prod | http://8.155.172.147:5010 |

---

## 最佳实践

### 1. 需求阶段
- ✅ 充分理解业务场景
- ✅ 与用户确认需求细节
- ✅ 明确验收标准
- ✅ 评估技术可行性

### 2. 开发阶段
- ✅ 先写测试用例（TDD）
- ✅ 小步迭代，频繁提交
- ✅ 保持代码简洁
- ✅ 及时重构

### 3. 测试阶段
- ✅ 自动化测试优先
- ✅ 覆盖正常和异常流程
- ✅ 性能测试
- ✅ 安全测试

### 4. 部署阶段
- ✅ 使用生产环境配置
- ✅ 备份数据库
- ✅ 灰度发布
- ✅ 监控告警

---

## 故障排查

### 常见问题

**Q: Flutter Web 构建失败**
```bash
# 清理缓存
flutter clean
flutter pub get
flutter build web --release --dart-define=ENV=prod
```

**Q: API 测试失败**
```bash
# 检查后端服务
curl http://localhost:5010/actuator/health

# 查看日志
tail -f logs/application.log
```

**Q: Git 推送失败**
```bash
# 拉取最新代码
git pull origin main --rebase

# 解决冲突后推送
git push origin main
```

---

## 参考资源

- [Flutter 官方文档](https://flutter.dev/docs)
- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Clean Code 技能](~/.agents/skills/clean-code/SKILL.md)

---

## 版本历史

- **v1.1.0** (2026-03-26) - 多 Agent 支持
  - 添加 Phase 3-4 独立 Agent 执行策略
  - 定义 Agent 通信协议
  - 添加 Bug 修复循环流程
- **v1.0.0** (2026-03-23) - 初始版本
  - 定义四阶段开发流程
  - 添加 Feature Spec 模板
  - 集成测试与构建流程

---

## 📋 测试 Agent 完整 Prompt 模板

复制以下内容启动测试 Agent：

```
你是 Monisuo 项目的测试 Agent。你需要独立完成测试验证和构建任务。

## 项目信息
- 后端: Spring Boot (Maven)
- 前端: Flutter Web
- 管理后台: Vue (pnpm)

## 你的任务

### 1. 读取 Feature Spec
首先读取功能规格文档：
- 路径: docs/features/[feature-name].md
- 理解功能需求和验收标准

### 2. 代码审查
- 使用 git diff 查看变更
- 检查代码规范（见下方规范清单）
- 检查错误处理是否完善

### 3. 执行测试

#### API 测试
```bash
# 如果后端服务未启动，先启动
mvn spring-boot:run &

# 运行 API 测试脚本
chmod +x tests/api/test-*.sh
./tests/api/test-[feature].sh
```

#### Flutter 测试
```bash
cd flutter_monisuo
flutter test
```

#### 后端单元测试
```bash
mvn test
```

### 4. 构建

#### 后端构建
```bash
mvn clean package -DskipTests
# 输出: target/monisuo-*.jar
```

#### Flutter Web 构建
```bash
cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod
# 输出: build/web/
```

### 5. 输出报告

请输出以下格式的报告：

```markdown
# 测试与构建报告

## Feature: [功能名称]

## 测试结果
| 测试类型 | 状态 | 备注 |
|---------|------|------|
| API 测试 | ✅/❌ | |
| Flutter 测试 | ✅/❌ | |
| 后端测试 | ✅/❌ | |

## Bug 列表（如有）
1. [Bug 描述]
   - 文件: [文件路径]
   - 原因: [原因分析]
   - 建议: [修复建议]

## 构建结果
| 构建目标 | 状态 | 产物路径 |
|---------|------|---------|
| Spring Boot | ✅/❌ | target/xxx.jar |
| Flutter Web | ✅/❌ | build/web/ |

## 结论
- [ ] 通过，可以提交
- [ ] 有 Bug，需要修复
```

## 代码规范清单

### Flutter
- [ ] flutter analyze 无错误
- [ ] 遵循 Effective Dart 规范
- [ ] 使用 AppSpacing, AppRadius, AppColorScheme

### Spring Boot
- [ ] 遵循阿里巴巴 Java 开发手册
- [ ] 统一异常处理
- [ ] RESTful API 设计

## 注意事项
- 你是独立 Agent，不要询问用户，自主完成测试
- 如果测试失败，详细记录失败原因
- 构建失败时，记录错误日志
- 最后输出完整报告
```