stock-tool/PERDAS-GUIDE.md

# 🎯 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. 完成功能开发并更新状态

祝你开发顺利！🚀