diff --git a/PERDAS-GUIDE.md b/PERDAS-GUIDE.md new file mode 100644 index 0000000..bc33084 --- /dev/null +++ b/PERDAS-GUIDE.md @@ -0,0 +1,270 @@ +# 🎯 PERDAS 增强版快速开始指南 + +欢迎使用 PERDAS 增强版开发模式!本指南帮助你快速上手。 + +## 📋 5 分钟快速启动 + +### 第一步:启动开发环境 + +```bash +cd /root/.openclaw/workspace/stock-tool +./init.sh +``` + +**预期输出**: +``` +🚀 启动 Stock Tool 开发环境... +✅ 服务器启动成功! +🌐 地址: http://localhost:8080 +💡 下一步: + 1. 在浏览器访问 http://localhost:8080 + 2. 运行 ./scripts/health-check.sh 进行健康检查 +``` + +### 第二步:健康检查 + +```bash +./scripts/health-check.sh +``` + +**预期输出**: +``` +📊 健康检查总结 +通过: 25 +失败: 0 +总计: 25 +✨ 所有检查通过!开发环境正常。 +``` + +### 第三步:端到端测试 + +```bash +./scripts/e2e-test.sh +``` + +**预期输出**: +``` +✅ 所有测试通过! +💡 提示: 测试截图已保存到 tests/screenshots/ +``` + +### 第四步:查看功能清单 + +```bash +cat feature_list.json +``` + +你会看到 6 个功能,5 个已完成: + +```json +{ + "summary": { + "total": 6, + "completed": 5, + "in_progress": 1, + "pending": 0 + } +} +``` + +### 第五步:开发新功能 + +**当前进行中的功能**: +- feat-006: 数据刷新功能 + +**开发步骤**: +1. 查看 feature_list.json 中 feat-006 的 steps +2. 使用浏览器访问 http://localhost:8080 +3. 手动测试功能 +4. 更新 feature_list.json(修改 passes: true) +5. 提交代码 + +--- + +## 🔄 标准工作流程 + +### 每次会话开始时 + +```bash +# 1. 确认目录 +pwd +# 输出: /root/.openclaw/workspace/stock-tool + +# 2. 启动环境 +./init.sh + +# 3. 健康检查 +./scripts/health-check.sh + +# 4. 查看进度 +cat PROGRESS.md + +# 5. 查看功能清单 +jq '.features[] | select(.status=="in_progress")' feature_list.json +``` + +### 开发功能时 + +1. **阅读步骤** + ```bash + jq '.features[] | select(.id=="feat-006")' feature_list.json + ``` + +2. **实现功能** + - 修改代码 + - 测试功能 + - 验证效果 + +3. **运行测试** + ```bash + ./scripts/e2e-test.sh + ``` + +4. **保存截图** + ```bash + # 在浏览器中测试后截图 + cp screenshot.png tests/screenshots/feat-006-xxx.png + ``` + +5. **更新状态** + ```bash + # 修改 feature_list.json + jq '.features[] | select(.id=="feat-006") | .passes = true' feature_list.json > tmp.json && mv tmp.json feature_list.json + ``` + +6. **更新进度文件** + ```bash + vim PROGRESS.md + ``` + +7. **提交代码** + ```bash + git add . + git commit -m "feat: 完成 feat-006 数据刷新功能" + git push + ``` + +--- + +## 📚 重要文件说明 + +| 文件 | 用途 | 修改规则 | +|------|------|----------| +| `feature_list.json` | 功能清单 | **仅修改** `passes` 字段 | +| `PROGRESS.md` | 进度跟踪 | 每会话更新 | +| `init.sh` | 环境启动 | 必要时更新 | +| `.gitignore` | 忽略规则 | 必要时更新 | +| `README.md` | 项目文档 | 必要时更新 | + +--- + +## ⚠️ 强约束指令(必须遵守) + +> **It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.** + +### 绝对禁止的行为: + +- ❌ 删除或修改测试用例 +- ❌ 删除或修改其他功能的代码 +- ❌ 修改 `feature_list.json` 中除 `passes` 字段外的任何内容 +- ❌ 未通过端到端测试就标记完成 +- ❌ 未保存截图证据就标记完成 + +### 正确的行为: + +- ✅ 只修改当前要开发的功能 +- ✅ 功能完成后运行端到端测试 +- ✅ 测试通过后保存截图 +- ✅ 更新 `feature_list.json` 的 `passes` 字段 +- ✅ 更新 `PROGRESS.md` 记录本次工作 +- ✅ 提交 Git commit + +--- + +## 🐛 错误处理 + +### 服务器未运行 + +```bash +./init.sh +``` + +### 测试失败 + +```bash +# 查看服务器日志 +cat logs/server.log + +# 检查 API 是否正常 +curl http://localhost:8080/api/stocks + +# 重新测试 +./scripts/e2e-test.sh +``` + +### Git 冲突 + +```bash +git fetch origin +git rebase origin/main +git push +``` + +--- + +## 📖 相关文档 + +- **完整文档**: README.md +- **进度跟踪**: PROGRESS.md +- **功能清单**: feature_list.json +- **健康检查**: scripts/health-check.sh +- **端到端测试**: scripts/e2e-test.sh + +--- + +## 💡 常用命令速查 + +```bash +# 启动环境 +./init.sh + +# 健康检查 +./scripts/health-check.sh + +# 端到端测试 +./scripts/e2e-test.sh + +# 查看功能 +jq '.features[] | select(.status=="in_progress")' feature_list.json + +# 查看提交历史 +git log --oneline -10 + +# 提交更改 +git add . +git commit -m "feat: 描述" +git push +``` + +--- + +## 🎉 开始你的第一个功能 + +当前进行中的功能:**feat-006 - 数据刷新功能** + +按照以下步骤开始: + +1. 查看功能详情: + ```bash + jq '.features[] | select(.id=="feat-006")' feature_list.json + ``` + +2. 启动服务器并测试: + ```bash + ./init.sh + http://localhost:8080 + ``` + +3. 完成功能开发并更新状态 + +祝你开发顺利!🚀