9.7 KiB
9.7 KiB
name, description
| name | description |
|---|---|
| monisuo-dev | Monisuo 项目结构化开发流程技能。用于需求分析、模块化开发、测试验证、构建部署的完整工作流。 |
Monisuo 开发技能
用于 Monisuo 项目的结构化开发流程，确保代码质量和开发效率。
工作流程
需求分析 → 模块化开发 → 测试验证 → 构建部署
Phase 1: 需求结构化定义 (Prompt Engineering)
目标
将模糊的需求转化为结构化的 Feature Spec 文档。
输入
- 用户的需求描述（自然语言）
- 业务场景说明
- 技术约束条件
输出
docs/features/feature-name.md- 结构化的功能规格文档
Feature Spec 模板
# [功能名称] 功能规格
## 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
# 与用户确认需求
# 识别关键业务场景
# 明确技术约束
-
创建文档
mkdir -p docs/features touch docs/features/[feature-name].md -
填充模板
- 完善用户故事
- 设计 API 接口
- 定义数据模型
- 编写测试用例
-
评审确认
- 与用户确认需求理解正确
- 调整优先级和范围
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 迭代开发顺序
-
数据层优先
- 数据库表结构
- Entity 定义
- Repository 实现
-
后端 API
- Controller 接口
- Service 业务逻辑
- 单元测试
-
前端实现
- Model 定义
- API Service
- UI 组件
- 状态管理
开发命令
# 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 3: 测试与重构 (Validation & Refactoring)
目标
确保代码质量和功能正确性。
3.1 使用 Clean Code 技能
# 应用 clean-code 技能进行代码优化
# 参考: ~/.agents/skills/clean-code/SKILL.md
优化重点:
- 代码可读性
- 函数复杂度
- 重复代码
- 命名规范
3.2 自动化测试
API 接口测试
测试脚本位置: tests/api/
测试脚本模板:
#!/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 测试完成 ==="
运行测试:
chmod +x tests/api/test-*.sh
./tests/api/test-feature.sh
Flutter 单元测试
cd flutter_monisuo
flutter test
3.3 Bug 修复循环
测试 → 发现 Bug → 修复 → 重新测试 → 通过
修复流程:
- 运行测试脚本
- 记录失败的用例
- 修复代码
- 重新运行测试
- 直到全部通过
3.4 代码审查清单
- 代码符合规范
- 无硬编码值
- 错误处理完善
- 日志记录清晰
- 测试覆盖完整
- 性能达标
Phase 4: 构建与部署 (Build & Deploy)
目标
构建生产版本并提交代码。
4.1 构建命令
后端 (Spring Boot)
# 清理并打包（跳过测试）
mvn clean package -DskipTests
# 完整构建（包含测试）
mvn clean package
# 只编译检查
mvn compile
输出: target/monisuo-*.jar
验证构建:
# 检查 JAR 文件是否生成
ls -la target/*.jar
# 测试 JAR 可执行性
java -jar target/monisuo-*.jar --spring.profiles.active=dev
Flutter Web
cd flutter_monisuo
flutter build web --release --dart-define=ENV=prod
输出: flutter_monisuo/build/web/
Admin 后台
cd monisuo-admin
pnpm install
pnpm build
输出: monisuo-admin/dist/
4.2 Git 提交流程
# 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
flutter pub get # 安装依赖
flutter run -d chrome # 开发模式
flutter analyze # 代码检查
flutter test # 运行测试
flutter build web --release --dart-define=ENV=prod # 生产构建
Admin
pnpm install # 安装依赖
pnpm dev # 开发模式
pnpm build # 生产构建
Maven
mvn compile # 编译
mvn test # 运行测试
mvn clean package -DskipTests # 打包（跳过测试）
mvn clean package # 完整打包
mvn spring-boot:run # 运行开发服务
Git
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 构建失败
# 清理缓存
flutter clean
flutter pub get
flutter build web --release --dart-define=ENV=prod
Q: API 测试失败
# 检查后端服务
curl http://localhost:5010/actuator/health
# 查看日志
tail -f logs/application.log
Q: Git 推送失败
# 拉取最新代码
git pull origin main --rebase
# 解决冲突后推送
git push origin main
参考资源
版本历史
- v1.0.0 (2026-03-23) - 初始版本
- 定义四阶段开发流程
- 添加 Feature Spec 模板
- 集成测试与构建流程