diff --git a/.github/ISSUE_TEMPLATE/bounty_claim.md b/.github/ISSUE_TEMPLATE/bounty_claim.md new file mode 100644 index 00000000..b8fc97eb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bounty_claim.md @@ -0,0 +1,93 @@ +--- +name: Bounty Claim +about: Claim a bounty task or propose a new bounty +title: '[BOUNTY CLAIM] ' +labels: bounty +assignees: '' +--- + +## 💰 Bounty Information + +**Claiming existing bounty?** +- Issue #: +- Bounty amount: + +**OR proposing new bounty?** +- Proposed feature/fix: +- Estimated effort: [Small / Medium / Large] + +--- + +## 👤 About You + +**Name/Username:** + +**Contact:** +- GitHub: @your_username +- Telegram: @your_telegram (optional) +- Email: your@email.com (optional) + +**Relevant Experience:** +- +- +- + +--- + +## 📋 Implementation Plan + +### 1. Approach + +- How will you implement this? +- What components will be affected? +- Any dependencies or libraries needed? + +### 2. Timeline +- **Start date:** +- **Estimated completion:** +- **Milestones:** + - [ ] Week 1: ... + - [ ] Week 2: ... + - [ ] Week 3: ... + +### 3. Deliverables +- [ ] Working code (merged PR) +- [ ] Unit tests (if applicable) +- [ ] Documentation updates +- [ ] Demo video/screenshots + +--- + +## 🔍 Questions for Maintainers + + + +1. +2. +3. + +--- + +## 📚 References + + + +- + +--- + +## ✅ Acknowledgment + +By claiming this bounty, I acknowledge that: +- [ ] I have read the [Contributing Guide](../../CONTRIBUTING.md) +- [ ] I will follow the [Code of Conduct](../../CODE_OF_CONDUCT.md) +- [ ] I understand the acceptance criteria +- [ ] My contribution will be licensed under MIT License +- [ ] Payment is subject to successful PR merge + +--- + +**For maintainers:** +- [ ] Bounty claim approved +- [ ] Issue assigned to claimant +- [ ] Timeline agreed upon diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..d26f1d0a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,167 @@ +--- +name: Bug Report +about: Report a bug to help us improve NOFX +title: '[BUG] ' +labels: bug +assignees: '' +--- + +> **⚠️ Before submitting:** Please check the [Troubleshooting Guide](../../docs/guides/TROUBLESHOOTING.md) ([中文版](../../docs/guides/TROUBLESHOOTING.zh-CN.md)) to see if your issue can be resolved quickly. + +## 🐛 Bug Description + + + +## 🔍 Bug Category + +- [ ] Trading execution (orders not executing, wrong position size, etc.) +- [ ] AI decision issues (unexpected decisions, only opening one direction, etc.) +- [ ] Exchange connection (API errors, authentication failures, etc.) +- [ ] UI/Frontend (display issues, buttons not working, data not updating, etc.) +- [ ] Backend/API (server errors, crashes, performance issues, etc.) +- [ ] Configuration (settings not saving, database errors, etc.) +- [ ] Other: _________________ + +## 📋 Steps to Reproduce +1. Go to '...' +2. Click on '...' / Run command '...' +3. Configure '...' +4. See error + +## ✅ Expected Behavior + + + +## ❌ Actual Behavior + + + +## 📸 Screenshots & Logs + +### Frontend Error (if applicable) + + + + + + +**Browser Console Screenshot:** + + +**Network Tab (failed requests):** + + +### Backend Logs (if applicable) + + +**Docker users:** +```bash +# View backend logs +docker compose logs backend --tail=100 + +# OR continuously follow logs +docker compose logs -f backend +``` + +**Manual/PM2 users:** +```bash +# Terminal output where you ran: ./nofx +# OR PM2 logs: +pm2 logs nofx --lines 100 +``` + +**Backend Log Output:** +``` +Paste backend logs here (last 50-100 lines around the error) +``` + +### Trading/Decision Logs (if trading issue) + + + +**Decision Log Path:** `decision_logs/{trader_id}/{timestamp}.json` + +```json +{ + "paste relevant decision log here if applicable" +} +``` + +## 💻 Environment + +**System:** +- **OS:** [e.g. macOS 13, Ubuntu 22.04, Windows 11] +- **Deployment:** [Docker / Manual / PM2] + +**Backend:** +- **Go Version:** [run: `go version`] +- **NOFX Version:** [run: `git log -1 --oneline` or check release tag] + +**Frontend:** +- **Browser:** [e.g. Chrome 120, Firefox 121, Safari 17] +- **Node.js Version:** [run: `node -v`] + +**Trading Setup:** +- **Exchange:** [Binance / Hyperliquid / Aster] +- **Account Type:** [Main Account / Subaccount] +- **Position Mode:** [Hedge Mode (Dual) / One-way Mode] ← **Important for trading bugs!** +- **AI Model:** [DeepSeek / Qwen / Custom] +- **Number of Traders:** [e.g. 1, 2, etc.] + +## 🔧 Configuration (if relevant) + + + +**Leverage Settings:** +```json +{ + "btc_eth_leverage": 5, + "altcoin_leverage": 5 +} +``` + +**Any custom settings:** + + + +## 📊 Additional Context + +**Frequency:** +- [ ] Happens every time +- [ ] Happens randomly +- [ ] Happened once + +**Timeline:** +- Did this work before? [ ] Yes [ ] No +- When did it break? [e.g. after upgrade to v3.0.0, after changing config, etc.] +- Recent changes? [e.g. updated dependencies, changed exchange, etc.] + +**Impact:** +- [ ] System cannot start +- [ ] Trading stopped/broken +- [ ] UI broken but trading works +- [ ] Minor visual issue +- [ ] Other: _________________ + +## 💡 Possible Solution + + + +--- + +## 📝 Quick Tips for Faster Resolution + +**For Trading Issues:** +1. ✅ Check Binance position mode: Go to Futures → ⚙️ Preferences → Position Mode → Must be **Hedge Mode** +2. ✅ Verify API permissions: Futures trading must be enabled +3. ✅ Check decision logs in `decision_logs/{trader_id}/` for AI reasoning + +**For Connection Issues:** +4. ✅ Test API connectivity: `curl http://localhost:8080/api/health` +5. ✅ Check API rate limits on exchange +6. ✅ Verify API keys are not expired + +**For UI Issues:** +7. ✅ Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac) +8. ✅ Check browser console (F12) for errors +9. ✅ Verify backend is running: `docker compose ps` or `ps aux | grep nofx` diff --git a/.github/PR_TITLE_GUIDE.md b/.github/PR_TITLE_GUIDE.md new file mode 100644 index 00000000..95fbc12c --- /dev/null +++ b/.github/PR_TITLE_GUIDE.md @@ -0,0 +1,322 @@ +# PR 标题指南 + +## 📋 概述 + +我们使用 **Conventional Commits** 格式来保持 PR 标题的一致性，但这是**建议性的**，不会阻止你的 PR 被合并。 + +## ✅ 推荐格式 + +``` +type(scope): description +``` + +### 示例 + +``` +feat(trader): add new trading strategy +fix(api): resolve authentication issue +docs: update README +chore(deps): update dependencies +ci(workflow): improve GitHub Actions +``` + +--- + +## 📖 详细说明 + +### Type（类型）- 必需 + +描述这次变更的类型： + +| Type | 说明 | 示例 | +|------|------|------| +| `feat` | 新功能 | `feat(trader): add stop-loss feature` | +| `fix` | Bug 修复 | `fix(api): handle null response` | +| `docs` | 文档变更 | `docs: update installation guide` | +| `style` | 代码格式（不影响代码运行） | `style: format code with prettier` | +| `refactor` | 重构（既不是新功能也不是修复） | `refactor(exchange): simplify connection logic` | +| `perf` | 性能优化 | `perf(ai): optimize prompt processing` | +| `test` | 添加或修改测试 | `test(trader): add unit tests` | +| `chore` | 构建过程或辅助工具的变动 | `chore: update dependencies` | +| `ci` | CI/CD 相关变更 | `ci: add test coverage report` | +| `security` | 安全相关修复 | `security: update vulnerable dependencies` | +| `build` | 构建系统或外部依赖项变更 | `build: upgrade webpack to v5` | + +### Scope（范围）- 可选 + +描述这次变更影响的范围： + +| Scope | 说明 | +|-------|------| +| `exchange` | 交易所相关 | +| `trader` | 交易员/交易策略 | +| `ai` | AI 模型相关 | +| `api` | API 接口 | +| `ui` | 用户界面 | +| `frontend` | 前端代码 | +| `backend` | 后端代码 | +| `security` | 安全相关 | +| `deps` | 依赖项 | +| `workflow` | GitHub Actions workflows | +| `github` | GitHub 配置 | +| `actions` | GitHub Actions | +| `config` | 配置文件 | +| `docker` | Docker 相关 | +| `build` | 构建相关 | +| `release` | 发布相关 | + +**注意：** 如果变更影响多个范围，可以省略 scope 或选择最主要的。 + +### Description（描述）- 必需 + +- 使用现在时态（"add" 而不是 "added"） +- 首字母小写 +- 结尾不加句号 +- 简洁明了地描述变更内容 + +--- + +## 🎯 完整示例 + +### ✅ 好的 PR 标题 + +``` +feat(trader): add risk management system +fix(exchange): resolve connection timeout issue +docs: add API documentation for trading endpoints +style: apply consistent code formatting +refactor(ai): simplify prompt processing logic +perf(backend): optimize database queries +test(api): add integration tests for auth +chore(deps): update TypeScript to 5.0 +ci(workflow): add automated security scanning +security(api): fix SQL injection vulnerability +build(docker): optimize Docker image size +``` + +### ⚠️ 需要改进的标题 + +| 不好的标题 | 问题 | 改进后 | +|-----------|------|--------| +| `update code` | 太模糊 | `refactor(trader): simplify order execution logic` | +| `Fixed bug` | 首字母大写，不够具体 | `fix(api): handle edge case in login` | +| `Add new feature.` | 有句号，不够具体 | `feat(ui): add dark mode toggle` | +| `changes` | 完全不符合格式 | `chore: update dependencies` | +| `feat: Added new trading algo` | 时态错误 | `feat(trader): add new trading algorithm` | + +--- + +## 🤖 自动检查行为 + +### 当 PR 标题不符合格式时 + +1. **不会阻止合并** ✅ + - 检查会标记为"建议" + - PR 仍然可以被审查和合并 + +2. **会收到友好提示** 💬 + - 机器人会在 PR 中留言 + - 提供格式说明和示例 + - 建议如何改进标题 + +3. **可以随时更新** 🔄 + - 更新 PR 标题后会重新检查 + - 无需关闭和重新打开 PR + +### 示例评论 + +如果你的 PR 标题是 `update workflow`，你会收到这样的评论： + +```markdown +## ⚠️ PR Title Format Suggestion + +Your PR title doesn't follow the Conventional Commits format, +but this won't block your PR from being merged. + +**Current title:** `update workflow` + +**Recommended format:** `type(scope): description` + +### Valid types: +feat, fix, docs, style, refactor, perf, test, chore, ci, security, build + +### Common scopes (optional): +exchange, trader, ai, api, ui, frontend, backend, security, deps, +workflow, github, actions, config, docker, build, release + +### Examples: +- feat(trader): add new trading strategy +- fix(api): resolve authentication issue +- docs: update README +- chore(deps): update dependencies +- ci(workflow): improve GitHub Actions + +**Note:** This is a suggestion to improve consistency. +Your PR can still be reviewed and merged. +``` + +--- + +## 🔧 配置详情 + +### 支持的 Types + +在 `.github/workflows/pr-checks.yml` 中配置： + +```yaml +types: | + feat + fix + docs + style + refactor + perf + test + chore + ci + security + build +``` + +### 支持的 Scopes + +```yaml +scopes: | + exchange + trader + ai + api + ui + frontend + backend + security + deps + workflow + github + actions + config + docker + build + release +``` + +### 添加新的 Scope + +如果你需要添加新的 scope，请： + +1. 在 `.github/workflows/pr-checks.yml` 的 `scopes` 部分添加 +2. 在 `.github/workflows/pr-checks-run.yml` 更新正则表达式（可选） +3. 更新本文档 + +--- + +## 📚 为什么使用 Conventional Commits？ + +### 优点 + +1. **自动化 Changelog** 📝 + - 可以自动生成版本更新日志 + - 清晰地分类各种变更 + +2. **语义化版本** 🔢 + - `feat` → MINOR 版本（1.1.0） + - `fix` → PATCH 版本（1.0.1） + - `BREAKING CHANGE` → MAJOR 版本（2.0.0） + +3. **更好的可读性** 👀 + - 一眼看出 PR 的目的 + - 更容易浏览 Git 历史 + +4. **团队协作** 🤝 + - 统一的提交风格 + - 降低沟通成本 + +### 示例：自动生成的 Changelog + +```markdown +## v1.2.0 (2025-11-02) + +### Features +- **trader**: add risk management system (#123) +- **ui**: add dark mode toggle (#125) + +### Bug Fixes +- **api**: resolve authentication issue (#124) +- **exchange**: fix connection timeout (#126) + +### Documentation +- update API documentation (#127) +``` + +--- + +## 🎓 学习资源 + +- **Conventional Commits 官网:** https://www.conventionalcommits.org/ +- **Angular Commit Guidelines:** https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit +- **Semantic Versioning:** https://semver.org/ + +--- + +## ❓ FAQ + +### Q: 我必须遵循这个格式吗？ + +**A:** 不必须。这是建议性的，不会阻止你的 PR 被合并。但遵循格式可以提高项目的可维护性。 + +### Q: 如果我忘记了怎么办？ + +**A:** 机器人会在 PR 中提醒你，你可以随时更新标题。 + +### Q: 我可以在一个 PR 中做多种类型的变更吗？ + +**A:** 可以，但建议： +- 选择最主要的类型 +- 或者考虑拆分成多个 PR（更易于审查） + +### Q: Scope 可以省略吗？ + +**A:** 可以。`requireScope: false` 表示 scope 是可选的。 + +示例：`docs: update README` （没有 scope 也可以） + +### Q: 我想添加新的 type 或 scope，怎么做？ + +**A:** 提一个 PR 修改 `.github/workflows/pr-checks.yml`，并在本文档中说明新增项的用途。 + +### Q: Breaking Changes 怎么表示？ + +**A:** 在描述中添加 `BREAKING CHANGE:` 或在 type 后加 `!`： + +``` +feat!: remove deprecated API +feat(api)!: change authentication method + +BREAKING CHANGE: The old /auth endpoint is removed +``` + +--- + +## 📊 统计 + +想看项目的 commit 类型分布？运行： + +```bash +git log --oneline --no-merges | \ + grep -oE '^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|chore|ci|security|build)' | \ + cut -d' ' -f2 | sort | uniq -c | sort -rn +``` + +--- + +## ✅ 快速检查清单 + +在提交 PR 前，检查你的标题是否： + +- [ ] 包含有效的 type（feat, fix, docs 等） +- [ ] 使用小写字母开头 +- [ ] 使用现在时态（"add" 而不是 "added"） +- [ ] 简洁明了（最好在 50 字符内） +- [ ] 准确描述了变更内容 + +**记住：** 这些都是建议，不是强制要求！ diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..8d6a71b0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,288 @@ +# Pull Request | PR 提交 + +> **💡 提示 Tip:** 推荐 PR 标题格式 Recommended PR title format: `type(scope): description` +> 例如 Examples: `feat(trader): add new strategy` | `fix(api): resolve auth issue` +> 详情 Details: [PR Title Guide](./PR_TITLE_GUIDE.md) + +--- + +## 📝 Description | 描述 + + + + +**English:** + +**中文：** + +--- + +## 🎯 Type of Change | 变更类型 + + + + +- [ ] 🐛 Bug fix | 修复 Bug（不影响现有功能的修复） +- [ ] ✨ New feature | 新功能（不影响现有功能的新增） +- [ ] 💥 Breaking change | 破坏性变更（会导致现有功能无法正常工作的修复或功能） +- [ ] 📝 Documentation update | 文档更新 +- [ ] 🎨 Code style update | 代码样式更新（格式化、重命名等） +- [ ] ♻️ Refactoring | 重构（无功能变更） +- [ ] ⚡ Performance improvement | 性能优化 +- [ ] ✅ Test update | 测试更新 +- [ ] 🔧 Build/config change | 构建/配置变更 +- [ ] 🔒 Security fix | 安全修复 + +--- + +## 🔗 Related Issues | 相关 Issue + + + + +- Closes # | 关闭 # +- Related to # | 相关 # + +--- + +## 📋 Changes Made | 具体变更 + + + + +**English:** +- Change 1 +- Change 2 +- Change 3 + +**中文：** +- 变更 1 +- 变更 2 +- 变更 3 + +--- + +## 🧪 Testing | 测试 + +### Manual Testing | 手动测试 + + + + +- [ ] Tested locally | 本地测试通过 +- [ ] Tested on testnet | 测试网测试通过（交易所集成相关） +- [ ] Tested with different configurations | 测试了不同配置 +- [ ] Verified no existing functionality broke | 确认没有破坏现有功能 + +### Test Environment | 测试环境 + +- **OS | 操作系统:** [e.g. macOS, Ubuntu, Windows] +- **Go Version | Go 版本:** [e.g. 1.21.5] +- **Node Version | Node 版本:** [e.g. 18.x] (if applicable | 如适用) +- **Exchange | 交易所:** [if applicable | 如适用] + +### Test Results | 测试结果 + + + + +``` +Test output here | 测试输出 +``` + +--- + +## 📸 Screenshots / Demo | 截图/演示 + + + + + + + +**Before | 变更前:** + + +**After | 变更后:** + + +--- + +## ✅ Checklist | 检查清单 + + + + +### Code Quality | 代码质量 + +- [ ] My code follows the project's code style | 我的代码遵循项目代码风格 ([Contributing Guide](../CONTRIBUTING.md)) +- [ ] I have performed a self-review of my code | 我已进行代码自查 +- [ ] I have commented my code, particularly in hard-to-understand areas | 我已添加代码注释，特别是难以理解的部分 +- [ ] My changes generate no new warnings or errors | 我的变更没有产生新的警告或错误 +- [ ] Code compiles successfully | 代码编译成功 (`go build` / `npm run build`) +- [ ] I have run `go fmt` (for Go code) | 我已运行 `go fmt`（Go 代码） +- [ ] I have run `npm run lint` (for frontend code) | 我已运行 `npm run lint`（前端代码） + +### Testing | 测试 + +- [ ] I have added tests that prove my fix is effective or that my feature works | 我已添加证明修复有效或功能正常的测试 +- [ ] New and existing unit tests pass locally | 新旧单元测试在本地通过 +- [ ] I have tested on testnet (for trading/exchange changes) | 我已在测试网测试（交易/交易所变更） +- [ ] Integration tests pass | 集成测试通过 + +### Documentation | 文档 + +- [ ] I have updated the documentation accordingly | 我已相应更新文档 +- [ ] I have updated the README if needed | 我已更新 README（如需要） +- [ ] I have added inline code comments where necessary | 我已在必要处添加代码注释 +- [ ] I have updated type definitions (for TypeScript changes) | 我已更新类型定义（TypeScript 变更） +- [ ] I have updated API documentation (if applicable) | 我已更新 API 文档（如适用） + +### Git + +- [ ] My commits follow the conventional commits format | 我的提交遵循 Conventional Commits 格式 (`feat:`, `fix:`, etc.) +- [ ] I have rebased my branch on the latest `dev` branch | 我已将分支 rebase 到最新的 `dev` 分支 +- [ ] There are no merge conflicts | 没有合并冲突 +- [ ] Commit messages are clear and descriptive | 提交信息清晰明确 + +--- + +## 🔒 Security Considerations | 安全考虑 + + + + +- [ ] No API keys or secrets are hardcoded | 没有硬编码 API 密钥或密钥 +- [ ] User inputs are properly validated | 用户输入已正确验证 +- [ ] No SQL injection vulnerabilities introduced | 未引入 SQL 注入漏洞 +- [ ] No XSS vulnerabilities introduced | 未引入 XSS 漏洞 +- [ ] Authentication/authorization properly handled | 认证/授权已正确处理 +- [ ] Sensitive data is encrypted | 敏感数据已加密 +- [ ] N/A (not security-related) | 不适用（非安全相关） + +--- + +## ⚡ Performance Impact | 性能影响 + + + + +- [ ] No significant performance impact | 无显著性能影响 +- [ ] Performance improved | 性能提升 +- [ ] Performance may be impacted (explain below) | 性能可能受影响（请在下方说明） + + + + +**English:** + +**中文：** + +--- + +## 🌐 Internationalization | 国际化 + + + + +- [ ] All user-facing text supports i18n | 所有面向用户的文本支持国际化 +- [ ] Both English and Chinese versions provided | 提供了中英文版本 +- [ ] N/A | 不适用 + +--- + +## 📚 Additional Notes | 补充说明 + + + + +**English:** + +**中文：** + +--- + +## 💰 For Bounty Claims | 赏金申请 + + + + +- [ ] This PR is for bounty issue # | 此 PR 用于赏金 issue # +- [ ] All acceptance criteria from the bounty issue are met | 满足赏金 issue 的所有验收标准 +- [ ] I have included a demo video/screenshots | 我已包含演示视频/截图 +- [ ] I am ready for payment upon merge | 我准备好在合并后接收付款 + +**Payment Details | 付款详情:** + +--- + +## 🙏 Reviewer Notes | 审查者注意事项 + + + + +**English:** + +**中文：** + +--- + +## 📋 PR Size Estimate | PR 大小估计 + + + + +- [ ] 🟢 Small (< 100 lines) | 小（< 100 行） +- [ ] 🟡 Medium (100-500 lines) | 中（100-500 行） +- [ ] 🔴 Large (> 500 lines) | 大（> 500 行） + + + + + + + +--- + +## 🎯 Review Focus Areas | 审查重点 + + + + +Please pay special attention to: +请特别注意： + +- [ ] Logic changes | 逻辑变更 +- [ ] Security implications | 安全影响 +- [ ] Performance optimization | 性能优化 +- [ ] API changes | API 变更 +- [ ] Database schema changes | 数据库架构变更 +- [ ] UI/UX changes | UI/UX 变更 + +--- + +**By submitting this PR, I confirm that:** +**提交此 PR，我确认：** + +- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) | 我已阅读[贡献指南](../CONTRIBUTING.md) +- [ ] I agree to the [Code of Conduct](../CODE_OF_CONDUCT.md) | 我同意[行为准则](../CODE_OF_CONDUCT.md) +- [ ] My contribution is licensed under the MIT License | 我的贡献遵循 MIT 许可证 +- [ ] I understand this is a voluntary contribution | 我理解这是自愿贡献 +- [ ] I have the right to submit this code | 我有权提交此代码 + +--- + + diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 00000000..89bcae3f --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,127 @@ +# Auto-labeler configuration +# Automatically adds labels based on changed files + +# Area: Frontend +'area: frontend': + - changed-files: + - any-glob-to-any-file: + - 'web/**/*' + - '*.tsx' + - '*.ts' + - '*.jsx' + - '*.js' + - '*.css' + +# Area: Backend +'area: backend': + - changed-files: + - any-glob-to-any-file: + - '**/*.go' + - 'go.mod' + - 'go.sum' + - 'cmd/**/*' + - 'internal/**/*' + - 'pkg/**/*' + +# Area: Exchange +'area: exchange': + - changed-files: + - any-glob-to-any-file: + - 'internal/exchange/**/*' + - 'pkg/exchange/**/*' + - '**/binance*.go' + - '**/hyperliquid*.go' + - '**/aster*.go' + - '**/okx*.go' + - '**/bybit*.go' + +# Area: AI +'area: ai': + - changed-files: + - any-glob-to-any-file: + - 'internal/ai/**/*' + - 'pkg/ai/**/*' + - '**/deepseek*.go' + - '**/qwen*.go' + - '**/openai*.go' + - '**/claude*.go' + +# Area: API +'area: api': + - changed-files: + - any-glob-to-any-file: + - 'internal/api/**/*' + - 'pkg/api/**/*' + - '**/handler*.go' + - '**/router*.go' + +# Area: Security +'area: security': + - changed-files: + - any-glob-to-any-file: + - '**/auth*.go' + - '**/jwt*.go' + - '**/encryption*.go' + - '**/crypto*.go' + - 'SECURITY.md' + +# Area: Database +'area: database': + - changed-files: + - any-glob-to-any-file: + - 'internal/database/**/*' + - 'internal/db/**/*' + - '**/migration*.go' + - '**/*.sql' + - '**/schema*.go' + +# Area: UI/UX +'area: ui/ux': + - changed-files: + - any-glob-to-any-file: + - 'web/src/components/**/*' + - 'web/src/pages/**/*' + - '**/*.css' + - '**/style*.ts' + +# Area: Deployment +'area: deployment': + - changed-files: + - any-glob-to-any-file: + - 'Dockerfile' + - 'docker-compose*.yml' + - '.github/workflows/**/*' + - 'start.sh' + - '**/*deploy*.md' + +# Type: Documentation +'type: documentation': + - changed-files: + - any-glob-to-any-file: + - 'docs/**/*' + - '*.md' + - 'README*' + - 'CHANGELOG*' + - 'CONTRIBUTING.md' + - 'CODE_OF_CONDUCT.md' + +# Type: Test +'type: test': + - changed-files: + - any-glob-to-any-file: + - '**/*_test.go' + - 'test/**/*' + - '**/*.test.ts' + - '**/*.test.tsx' + - '**/*.spec.ts' + +# Dependencies +'dependencies': + - changed-files: + - any-glob-to-any-file: + - 'go.mod' + - 'go.sum' + - 'package.json' + - 'package-lock.json' + - 'web/package.json' + - 'web/package-lock.json' diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 00000000..26cadba4 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,180 @@ +# GitHub Labels Configuration +# Use https://github.com/crazy-max/ghaction-github-labeler to sync labels + +# Priority Labels +- name: "priority: critical" + color: "d73a4a" + description: "Critical priority - requires immediate attention" + +- name: "priority: high" + color: "ff6b6b" + description: "High priority - should be addressed soon" + +- name: "priority: medium" + color: "fbca04" + description: "Medium priority - normal queue" + +- name: "priority: low" + color: "0e8a16" + description: "Low priority - nice to have" + +# Type Labels +- name: "type: bug" + color: "d73a4a" + description: "Something isn't working" + +- name: "type: feature" + color: "a2eeef" + description: "New feature or request" + +- name: "type: enhancement" + color: "84b6eb" + description: "Improvement to existing feature" + +- name: "type: documentation" + color: "0075ca" + description: "Documentation improvements" + +- name: "type: security" + color: "ee0701" + description: "Security-related changes" + +- name: "type: performance" + color: "f9d0c4" + description: "Performance improvements" + +- name: "type: refactor" + color: "fbca04" + description: "Code refactoring" + +- name: "type: test" + color: "c5def5" + description: "Test-related changes" + +# Status Labels +- name: "status: needs review" + color: "fbca04" + description: "PR is ready for review" + +- name: "status: needs changes" + color: "d93f0b" + description: "PR needs changes based on review" + +- name: "status: on hold" + color: "fef2c0" + description: "PR/issue is on hold" + +- name: "status: in progress" + color: "0e8a16" + description: "Currently being worked on" + +- name: "status: blocked" + color: "d93f0b" + description: "Blocked by another issue/PR" + +# Area Labels (aligned with roadmap) +- name: "area: security" + color: "ee0701" + description: "Security enhancements (Phase 1.1)" + +- name: "area: ai" + color: "7057ff" + description: "AI capabilities and models (Phase 1.2)" + +- name: "area: exchange" + color: "0075ca" + description: "Exchange integrations (Phase 1.3)" + +- name: "area: architecture" + color: "d4c5f9" + description: "Project structure refactoring (Phase 1.4)" + +- name: "area: ui/ux" + color: "c2e0c6" + description: "User experience improvements (Phase 1.5)" + +- name: "area: frontend" + color: "bfdadc" + description: "Frontend (React/TypeScript)" + +- name: "area: backend" + color: "c5def5" + description: "Backend (Go)" + +- name: "area: api" + color: "0e8a16" + description: "API endpoints" + +- name: "area: database" + color: "f9d0c4" + description: "Database changes" + +- name: "area: deployment" + color: "fbca04" + description: "Deployment and CI/CD" + +# Special Labels +- name: "good first issue" + color: "7057ff" + description: "Good for newcomers" + +- name: "help wanted" + color: "008672" + description: "Extra attention is needed" + +- name: "bounty" + color: "1d76db" + description: "Bounty available for this issue" + +- name: "bounty: claimed" + color: "5319e7" + description: "Bounty has been claimed" + +- name: "bounty: paid" + color: "0e8a16" + description: "Bounty has been paid" + +- name: "RFC" + color: "d4c5f9" + description: "Request for Comments - needs discussion" + +- name: "breaking change" + color: "d73a4a" + description: "Includes breaking changes" + +- name: "duplicate" + color: "cfd3d7" + description: "This issue or pull request already exists" + +- name: "invalid" + color: "e4e669" + description: "This doesn't seem right" + +- name: "wontfix" + color: "ffffff" + description: "This will not be worked on" + +- name: "dependencies" + color: "0366d6" + description: "Dependency updates" + +# Roadmap Phases +- name: "roadmap: phase-1" + color: "0e8a16" + description: "Core Infrastructure Enhancement" + +- name: "roadmap: phase-2" + color: "fbca04" + description: "Testing & Stability" + +- name: "roadmap: phase-3" + color: "0075ca" + description: "Universal Market Expansion" + +- name: "roadmap: phase-4" + color: "7057ff" + description: "Advanced AI & Automation" + +- name: "roadmap: phase-5" + color: "d73a4a" + description: "Enterprise & Scaling" diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 00000000..5eb6f985 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,176 @@ +# GitHub Actions Workflows + +This directory contains the GitHub Actions workflows for the NOFX project. + +## 📚 Documentation Index + +- **[README.md](./README.md)** - This file, overview of all workflows +- **[PERMISSIONS.md](./PERMISSIONS.md)** - Detailed permission analysis and security model +- **[TRIGGERS.md](./TRIGGERS.md)** - Comparison of event triggers (pull_request vs pull_request_target vs workflow_run) +- **[FORK_PR_FLOW.md](./FORK_PR_FLOW.md)** - Complete analysis of what happens when a fork PR is submitted +- **[FLOW_DIAGRAM.md](./FLOW_DIAGRAM.md)** - Visual flow diagrams and quick reference +- **[SECRETS_SCANNING.md](./SECRETS_SCANNING.md)** - Secrets scanning solutions and TruffleHog setup + +## 🚀 Quick Start + +**Want to understand how fork PRs work?** → Read [FLOW_DIAGRAM.md](./FLOW_DIAGRAM.md) + +**Need security details?** → Read [PERMISSIONS.md](./PERMISSIONS.md) + +**Confused about triggers?** → Read [TRIGGERS.md](./TRIGGERS.md) + +## PR Check Workflows + +We use a **two-workflow pattern** to safely handle PR checks from both internal and fork PRs: + +### 1. `pr-checks-run.yml` - Execute Checks + +**Trigger:** On pull request (opened, synchronize, reopened) + +**Permissions:** Read-only + +**Purpose:** Executes all PR checks with read-only permissions, making it safe for fork PRs. + +**What it does:** +- ✅ Checks PR title format (Conventional Commits) +- ✅ Calculates PR size +- ✅ Runs backend checks (Go formatting, vet, tests) +- ✅ Runs frontend checks (linting, type checking, build) +- ✅ Saves all results as artifacts + +**Security:** Safe for fork PRs because it only has read permissions and cannot access secrets or modify the repository. + +### 2. `pr-checks-comment.yml` - Post Results + +**Trigger:** When `pr-checks-run.yml` completes (workflow_run) + +**Permissions:** Write (pull-requests, issues) + +**Purpose:** Posts check results as PR comments, running in the main repository context. + +**What it does:** +- ✅ Downloads artifacts from `pr-checks-run.yml` +- ✅ Reads check results +- ✅ Posts a comprehensive comment to the PR + +**Security:** Safe because: +- Runs in the main repository context (not fork context) +- Has write permissions but doesn't execute untrusted code +- Only reads pre-generated results from artifacts + +### 3. `pr-checks.yml` - Strict Checks + +**Trigger:** On pull request + +**Permissions:** Read + conditional write + +**Purpose:** Runs mandatory checks that must pass before PR can be merged. + +**What it does:** +- ✅ Validates PR title (blocks merge if invalid) +- ✅ Auto-labels PR based on size and files changed (non-fork only) +- ✅ Runs backend tests (Go) +- ✅ Runs frontend tests (React/TypeScript) +- ✅ Security scanning (Trivy, Gitleaks) + +**Security:** +- Fork PRs: Only runs read-only operations (tests, security scans) +- Non-fork PRs: Can add labels and comments +- Uses `continue-on-error` for operations that may fail on forks + +## Why Two Workflows for PR Checks? + +### The Problem + +When a PR comes from a forked repository: +- GitHub restricts `GITHUB_TOKEN` permissions for security +- Fork PRs cannot write comments, add labels, or access secrets +- This prevents malicious contributors from: + - Stealing repository secrets + - Modifying workflow files to execute malicious code + - Spamming issues/PRs with automated comments + +### The Solution + +**Two-Workflow Pattern:** + +``` +Fork PR Submitted + ↓ +[pr-checks-run.yml] + - Runs with read-only permissions + - Executes all checks safely + - Saves results to artifacts + ↓ +[pr-checks-comment.yml] + - Triggered by workflow_run + - Runs in main repo context (has write permissions) + - Downloads artifacts + - Posts comment with results +``` + +This approach: +- ✅ Allows fork PRs to run checks +- ✅ Safely posts results as comments +- ✅ Prevents security vulnerabilities +- ✅ Follows GitHub's best practices + +### Can workflow_run Comment on Fork PRs? + +**Yes! ✅ The permissions are sufficient.** + +**Key Understanding:** +- `workflow_run` executes in the **base repository** context +- Fork PRs exist in the **base repository** (not in the fork) +- The base repository's `GITHUB_TOKEN` has write permissions +- Therefore, `workflow_run` can comment on fork PRs + +**Security:** +- Fork PR code runs in isolated environment (read-only) +- Comment workflow doesn't execute fork code +- Only reads pre-generated artifact data + +**For detailed permission analysis, see:** [PERMISSIONS.md](./PERMISSIONS.md) + +## Workflow Comparison + +| Workflow | Fork PRs | Write Access | Blocks Merge | Purpose | +|----------|----------|--------------|--------------|---------| +| `pr-checks-run.yml` | ✅ Yes | ❌ No | ❌ No | Advisory checks | +| `pr-checks-comment.yml` | ✅ Yes | ✅ Yes* | ❌ No | Post results | +| `pr-checks.yml` | ✅ Yes | ⚠️ Partial | ✅ Yes | Mandatory checks | + +\* Write access only in main repo context, not available to fork PR code + +## File History + +- `pr-checks-advisory.yml.old` - Old advisory workflow that failed on fork PRs (deprecated) +- Now replaced by the two-workflow pattern (`pr-checks-run.yml` + `pr-checks-comment.yml`) + +## Testing the Workflows + +### Test with a Fork PR + +1. Fork the repository +2. Make changes in your fork +3. Create a PR to the main repository +4. Observe: + - `pr-checks-run.yml` runs successfully with read-only access + - `pr-checks-comment.yml` posts results as a comment + - `pr-checks.yml` runs tests but skips labeling + +### Test with a Branch PR + +1. Create a branch in the main repository +2. Make changes +3. Create a PR +4. Observe: + - All workflows run with full permissions + - Labels are added automatically + - Comments are posted + +## References + +- [GitHub Actions: Keeping your GitHub Actions and workflows secure Part 1](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) +- [Safely posting comments from untrusted workflows](https://securitylab.github.com/research/github-actions-building-blocks/) +- [GitHub Actions: workflow_run trigger](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run) diff --git a/.github/workflows/pr-checks-advisory.yml.old b/.github/workflows/pr-checks-advisory.yml.old new file mode 100644 index 00000000..2fb62b42 --- /dev/null +++ b/.github/workflows/pr-checks-advisory.yml.old @@ -0,0 +1,331 @@ +name: PR Checks (Advisory) + +on: + pull_request: + types: [opened, synchronize, reopened] + branches: [main, dev] + +# These checks are advisory only - they won't block PR merging +# Results will be posted as comments to help contributors improve their PRs + +permissions: + contents: write + pull-requests: write + checks: write + issues: write + +jobs: + pr-info: + name: PR Information + runs-on: ubuntu-latest + steps: + - name: Check PR title format + id: check-title + run: | + PR_TITLE="${{ github.event.pull_request.title }}" + + # Check if title follows conventional commits + if echo "$PR_TITLE" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore|ci|security)(\(.+\))?: .+"; then + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "message=PR title follows Conventional Commits format" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Suggestion" >> $GITHUB_OUTPUT + echo "message=Consider using Conventional Commits format: type(scope): description" >> $GITHUB_OUTPUT + fi + + - name: Calculate PR size + id: pr-size + run: | + ADDITIONS=${{ github.event.pull_request.additions }} + DELETIONS=${{ github.event.pull_request.deletions }} + TOTAL=$((ADDITIONS + DELETIONS)) + + if [ $TOTAL -lt 100 ]; then + echo "size=🟢 Small" >> $GITHUB_OUTPUT + echo "label=size: small" >> $GITHUB_OUTPUT + elif [ $TOTAL -lt 500 ]; then + echo "size=🟡 Medium" >> $GITHUB_OUTPUT + echo "label=size: medium" >> $GITHUB_OUTPUT + else + echo "size=🔴 Large" >> $GITHUB_OUTPUT + echo "label=size: large" >> $GITHUB_OUTPUT + echo "suggestion=Consider breaking this into smaller PRs for easier review" >> $GITHUB_OUTPUT + fi + echo "lines=$TOTAL" >> $GITHUB_OUTPUT + + - name: Post advisory comment + uses: actions/github-script@v7 + with: + script: | + const titleStatus = '${{ steps.check-title.outputs.status }}'; + const titleMessage = '${{ steps.check-title.outputs.message }}'; + const prSize = '${{ steps.pr-size.outputs.size }}'; + const prLines = '${{ steps.pr-size.outputs.lines }}'; + const sizeSuggestion = '${{ steps.pr-size.outputs.suggestion }}' || ''; + + let comment = '## 🤖 PR Advisory Feedback\n\n'; + comment += 'Thank you for your contribution! Here\'s some automated feedback to help improve your PR:\n\n'; + comment += '### PR Title\n'; + comment += titleStatus + ' ' + titleMessage + '\n\n'; + comment += '### PR Size\n'; + comment += prSize + ' (' + prLines + ' lines changed)\n'; + if (sizeSuggestion) { + comment += '\n💡 **Suggestion:** ' + sizeSuggestion + '\n'; + } + comment += '\n---\n\n'; + comment += '### 📖 New PR Management System\n\n'; + comment += 'We\'re introducing a new PR management system! These checks are **advisory only** and won\'t block your PR.\n\n'; + comment += '**Want to check your PR against new standards?**\n'; + comment += '```bash\n'; + comment += '# Run the PR health check tool\n'; + comment += './scripts/pr-check.sh\n'; + comment += '```\n\n'; + comment += 'This tool will:\n'; + comment += '- 🔍 Analyze your PR (doesn\'t modify anything)\n'; + comment += '- ✅ Show what\'s already good\n'; + comment += '- ⚠️ Point out issues\n'; + comment += '- 💡 Give specific suggestions on how to fix\n\n'; + comment += '**Learn more:**\n'; + comment += '- [Migration Guide](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md)\n'; + comment += '- [Contributing Guidelines](https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md)\n\n'; + comment += '**Questions?** Just ask in the comments! We\'re here to help. 🙏\n\n'; + comment += '---\n\n'; + comment += '*This is an automated message. It won\'t affect your PR being merged.*'; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + + backend-checks: + name: Backend Checks (Advisory) + runs-on: ubuntu-latest + continue-on-error: true + steps: + - uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.21' + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y libta-lib-dev || true + go mod download || true + + - name: Check Go formatting + id: go-fmt + continue-on-error: true + run: | + UNFORMATTED=$(gofmt -l . 2>/dev/null || echo "") + if [ -n "$UNFORMATTED" ]; then + echo "status=⚠️ Needs formatting" >> $GITHUB_OUTPUT + echo "files<> $GITHUB_OUTPUT + echo "$UNFORMATTED" | head -10 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + else + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "files=" >> $GITHUB_OUTPUT + fi + + - name: Run go vet + id: go-vet + continue-on-error: true + run: | + if go vet ./... 2>&1 | tee vet-output.txt; then + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "output=" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + cat vet-output.txt | head -20 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Run tests + id: go-test + continue-on-error: true + run: | + if go test ./... -v 2>&1 | tee test-output.txt; then + echo "status=✅ Passed" >> $GITHUB_OUTPUT + echo "output=" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Failed" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + cat test-output.txt | tail -30 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Post backend feedback + if: always() + uses: actions/github-script@v7 + with: + script: | + const fmtStatus = '${{ steps.go-fmt.outputs.status }}' || '⚠️ Skipped'; + const vetStatus = '${{ steps.go-vet.outputs.status }}' || '⚠️ Skipped'; + const testStatus = '${{ steps.go-test.outputs.status }}' || '⚠️ Skipped'; + const fmtFiles = `${{ steps.go-fmt.outputs.files }}`; + const vetOutput = `${{ steps.go-vet.outputs.output }}`; + const testOutput = `${{ steps.go-test.outputs.output }}`; + + let comment = '## 🔧 Backend Checks (Advisory)\n\n'; + comment += '### Go Formatting\n'; + comment += fmtStatus + '\n'; + if (fmtFiles) { + comment += '\nFiles needing formatting:\n```\n' + fmtFiles + '\n```\n'; + } + comment += '\n### Go Vet\n'; + comment += vetStatus + '\n'; + if (vetOutput) { + comment += '\n```\n' + vetOutput.substring(0, 500) + '\n```\n'; + } + comment += '\n### Tests\n'; + comment += testStatus + '\n'; + if (testOutput) { + comment += '\n```\n' + testOutput.substring(0, 1000) + '\n```\n'; + } + comment += '\n---\n\n'; + comment += '💡 **To fix locally:**\n'; + comment += '```bash\n'; + comment += '# Format code\n'; + comment += 'go fmt ./...\n\n'; + comment += '# Check for issues\n'; + comment += 'go vet ./...\n\n'; + comment += '# Run tests\n'; + comment += 'go test ./...\n'; + comment += '```\n\n'; + comment += '*These checks are advisory and won\'t block merging. Need help? Just ask!*'; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + + frontend-checks: + name: Frontend Checks (Advisory) + runs-on: ubuntu-latest + continue-on-error: true + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Check if web directory exists + id: check-web + run: | + if [ -d "web" ]; then + echo "exists=true" >> $GITHUB_OUTPUT + else + echo "exists=false" >> $GITHUB_OUTPUT + fi + + - name: Install dependencies + if: steps.check-web.outputs.exists == 'true' + working-directory: ./web + continue-on-error: true + run: npm ci + + - name: Run linter + if: steps.check-web.outputs.exists == 'true' + id: lint + working-directory: ./web + continue-on-error: true + run: | + if npm run lint 2>&1 | tee lint-output.txt; then + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "output=" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + cat lint-output.txt | head -20 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Type check + if: steps.check-web.outputs.exists == 'true' + id: typecheck + working-directory: ./web + continue-on-error: true + run: | + if npm run type-check 2>&1 | tee typecheck-output.txt; then + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "output=" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + cat typecheck-output.txt | head -20 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Build + if: steps.check-web.outputs.exists == 'true' + id: build + working-directory: ./web + continue-on-error: true + run: | + if npm run build 2>&1 | tee build-output.txt; then + echo "status=✅ Success" >> $GITHUB_OUTPUT + echo "output=" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Failed" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + cat build-output.txt | tail -20 >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Post frontend feedback + if: always() && steps.check-web.outputs.exists == 'true' + uses: actions/github-script@v7 + with: + script: | + const lintStatus = '${{ steps.lint.outputs.status }}' || '⚠️ Skipped'; + const typecheckStatus = '${{ steps.typecheck.outputs.status }}' || '⚠️ Skipped'; + const buildStatus = '${{ steps.build.outputs.status }}' || '⚠️ Skipped'; + const lintOutput = `${{ steps.lint.outputs.output }}`; + const typecheckOutput = `${{ steps.typecheck.outputs.output }}`; + const buildOutput = `${{ steps.build.outputs.output }}`; + + let comment = '## ⚛️ Frontend Checks (Advisory)\n\n'; + comment += '### Linting\n'; + comment += lintStatus + '\n'; + if (lintOutput) { + comment += '\n```\n' + lintOutput.substring(0, 500) + '\n```\n'; + } + comment += '\n### Type Checking\n'; + comment += typecheckStatus + '\n'; + if (typecheckOutput) { + comment += '\n```\n' + typecheckOutput.substring(0, 500) + '\n```\n'; + } + comment += '\n### Build\n'; + comment += buildStatus + '\n'; + if (buildOutput) { + comment += '\n```\n' + buildOutput.substring(0, 500) + '\n```\n'; + } + comment += '\n---\n\n'; + comment += '💡 **To fix locally:**\n'; + comment += '```bash\n'; + comment += 'cd web\n\n'; + comment += '# Fix linting issues\n'; + comment += 'npm run lint -- --fix\n\n'; + comment += '# Check types\n'; + comment += 'npm run type-check\n\n'; + comment += '# Test build\n'; + comment += 'npm run build\n'; + comment += '```\n\n'; + comment += '*These checks are advisory and won\'t block merging. Need help? Just ask!*'; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); diff --git a/.github/workflows/pr-checks-comment.yml b/.github/workflows/pr-checks-comment.yml new file mode 100644 index 00000000..db0983f8 --- /dev/null +++ b/.github/workflows/pr-checks-comment.yml @@ -0,0 +1,248 @@ +name: PR Checks - Comment + +# This workflow posts ADVISORY check results as comments +# Runs in the main repo context with write permissions (SAFE) +# Triggered after pr-checks-run.yml completes +# +# NOTE: PR title and size checks are handled by pr-checks.yml (no duplication) +# This workflow only posts backend/frontend advisory check results + +on: + workflow_run: + workflows: ["PR Checks - Run"] + types: [completed] + +# Write permissions - SAFE because runs in main repo context +# This token has write access to the base repository +# Fork PRs exist in the base repo, so we can comment on them +permissions: + pull-requests: write + issues: write + actions: read # Needed to download artifacts + +jobs: + comment: + name: Post Advisory Check Results + runs-on: ubuntu-latest + # Only run if the workflow was triggered by a pull_request event + if: github.event.workflow_run.event == 'pull_request' + steps: + - name: Download artifacts + id: download-artifacts + continue-on-error: true + uses: actions/download-artifact@v4 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + run-id: ${{ github.event.workflow_run.id }} + path: artifacts + + - name: Debug workflow run info + run: | + echo "=== Workflow Run Debug Info ===" + echo "Workflow Run ID: ${{ github.event.workflow_run.id }}" + echo "Workflow Run Event: ${{ github.event.workflow_run.event }}" + echo "Workflow Run Conclusion: ${{ github.event.workflow_run.conclusion }}" + echo "Workflow Run Head SHA: ${{ github.event.workflow_run.head_sha }}" + + - name: List downloaded artifacts + run: | + echo "=== Checking downloaded artifacts ===" + ls -la artifacts/ || echo "⚠️ No artifacts directory found" + find artifacts/ -type f || echo "⚠️ No files found in artifacts" + echo "" + echo "Artifact download result: ${{ steps.download-artifacts.outcome }}" + + - name: Read backend results + id: backend + continue-on-error: true + run: | + if [ -f artifacts/backend-results/backend-results.json ]; then + echo "=== Backend Results JSON ===" + cat artifacts/backend-results/backend-results.json + echo "pr_number=$(jq -r '.pr_number' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT + echo "fmt_status=$(jq -r '.fmt_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT + echo "vet_status=$(jq -r '.vet_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT + echo "test_status=$(jq -r '.test_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT + + # Read output files + if [ -f artifacts/backend-results/fmt-files.txt ]; then + echo "fmt_files<> $GITHUB_OUTPUT + cat artifacts/backend-results/fmt-files.txt >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + if [ -f artifacts/backend-results/vet-output-short.txt ]; then + echo "vet_output<> $GITHUB_OUTPUT + cat artifacts/backend-results/vet-output-short.txt >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + if [ -f artifacts/backend-results/test-output-short.txt ]; then + echo "test_output<> $GITHUB_OUTPUT + cat artifacts/backend-results/test-output-short.txt >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + else + echo "pr_number=0" >> $GITHUB_OUTPUT + echo "⚠️ Backend results artifact not found" + fi + + - name: Read frontend results + id: frontend + continue-on-error: true + run: | + if [ -f artifacts/frontend-results/frontend-results.json ]; then + echo "=== Frontend Results JSON ===" + cat artifacts/frontend-results/frontend-results.json + echo "build_status=$(jq -r '.build_status' artifacts/frontend-results/frontend-results.json)" >> $GITHUB_OUTPUT + + # Read output files + if [ -f artifacts/frontend-results/build-output-short.txt ]; then + echo "build_output<> $GITHUB_OUTPUT + cat artifacts/frontend-results/build-output-short.txt >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + else + echo "⚠️ Frontend results artifact not found" + fi + + - name: Post advisory results comment + if: steps.backend.outputs.pr_number != '0' + uses: actions/github-script@v7 + with: + script: | + const prNumber = ${{ steps.backend.outputs.pr_number }}; + + let comment = '## 🤖 Advisory Check Results\n\n'; + comment += 'These are **advisory** checks to help improve code quality. They won\'t block your PR from being merged.\n\n'; + comment += '> **Note:** PR title and size checks are handled by the main workflow and may appear in a separate comment.\n\n'; + + // Backend checks + const fmtStatus = '${{ steps.backend.outputs.fmt_status }}'; + const vetStatus = '${{ steps.backend.outputs.vet_status }}'; + const testStatus = '${{ steps.backend.outputs.test_status }}'; + + if (fmtStatus || vetStatus || testStatus) { + comment += '\n### 🔧 Backend Checks\n\n'; + + if (fmtStatus) { + comment += '**Go Formatting:** ' + fmtStatus + '\n'; + const fmtFiles = `${{ steps.backend.outputs.fmt_files }}`; + if (fmtFiles && fmtFiles.trim()) { + comment += '
Files needing formatting\n\n```\n' + fmtFiles + '\n```\n
\n\n'; + } + } + + if (vetStatus) { + comment += '**Go Vet:** ' + vetStatus + '\n'; + const vetOutput = `${{ steps.backend.outputs.vet_output }}`; + if (vetOutput && vetOutput.trim()) { + comment += '
Issues found\n\n```\n' + vetOutput.substring(0, 1000) + '\n```\n
\n\n'; + } + } + + if (testStatus) { + comment += '**Tests:** ' + testStatus + '\n'; + const testOutput = `${{ steps.backend.outputs.test_output }}`; + if (testOutput && testOutput.trim()) { + comment += '
Test output\n\n```\n' + testOutput.substring(0, 1000) + '\n```\n
\n\n'; + } + } + + comment += '\n**Fix locally:**\n'; + comment += '```bash\n'; + comment += 'go fmt ./... # Format code\n'; + comment += 'go vet ./... # Check for issues\n'; + comment += 'go test ./... # Run tests\n'; + comment += '```\n'; + } + + // Frontend checks + const buildStatus = '${{ steps.frontend.outputs.build_status }}'; + + if (buildStatus) { + comment += '\n### ⚛️ Frontend Checks\n\n'; + + comment += '**Build & Type Check:** ' + buildStatus + '\n'; + const buildOutput = `${{ steps.frontend.outputs.build_output }}`; + if (buildOutput && buildOutput.trim()) { + comment += '
Build output\n\n```\n' + buildOutput.substring(0, 1000) + '\n```\n
\n\n'; + } + + comment += '\n**Fix locally:**\n'; + comment += '```bash\n'; + comment += 'cd web\n'; + comment += 'npm run build # Test build (includes type checking)\n'; + comment += '```\n'; + } + + comment += '\n---\n\n'; + comment += '### 📖 Resources\n\n'; + comment += '- [Contributing Guidelines](https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md)\n'; + comment += '- [Migration Guide](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md)\n\n'; + comment += '**Questions?** Feel free to ask in the comments! 🙏\n\n'; + comment += '---\n\n'; + comment += '*These checks are advisory and won\'t block your PR from being merged. This comment is automatically generated from [pr-checks-run.yml](https://github.com/tinkle-community/nofx/blob/dev/.github/workflows/pr-checks-run.yml).*'; + + // Post comment + await github.rest.issues.createComment({ + issue_number: prNumber, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + + - name: Post fallback comment if no results + if: steps.backend.outputs.pr_number == '0' + uses: actions/github-script@v7 + with: + script: | + // Try to get PR number from the workflow_run event + const pulls = await github.rest.pulls.list({ + owner: context.repo.owner, + repo: context.repo.repo, + state: 'open', + head: `${context.repo.owner}:${{ github.event.workflow_run.head_branch }}` + }); + + if (pulls.data.length === 0) { + console.log('⚠️ Could not find PR for this workflow run'); + return; + } + + const prNumber = pulls.data[0].number; + + const comment = [ + '## ⚠️ Advisory Checks - Results Unavailable', + '', + 'The advisory checks workflow completed, but results could not be retrieved.', + '', + '### Possible reasons:', + '- Artifacts were not uploaded successfully', + '- Artifacts expired (retention: 1 day)', + '- Permission issues', + '', + '### What to do:', + '1. Check the [PR Checks - Run workflow](${{ github.event.workflow_run.html_url }}) logs', + '2. Ensure your code passes local checks:', + '```bash', + '# Backend', + 'go fmt ./...', + 'go vet ./...', + 'go build', + 'go test ./...', + '', + '# Frontend (if applicable)', + 'cd web', + 'npm run build', + '```', + '', + '---', + '', + '*This is an automated fallback message. The advisory checks ran but results are not available.*' + ].join('\n'); + + await github.rest.issues.createComment({ + issue_number: prNumber, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); diff --git a/.github/workflows/pr-checks-run.yml b/.github/workflows/pr-checks-run.yml new file mode 100644 index 00000000..48d23afe --- /dev/null +++ b/.github/workflows/pr-checks-run.yml @@ -0,0 +1,160 @@ +name: PR Checks - Run + +# This workflow runs advisory PR checks with read-only permissions +# Safe for fork PRs - results are saved as artifacts +# Companion workflow (pr-checks-comment.yml) will post comments +# +# NOTE: This workflow provides ADVISORY checks (non-blocking) +# Main blocking checks are in pr-checks.yml +# PR title and size checks are handled by pr-checks.yml (no duplication) + +on: + pull_request: + types: [opened, synchronize, reopened] + branches: [main, dev] + +# Read-only permissions - safe for fork PRs +permissions: + contents: read + +jobs: + # Backend advisory checks + # Different from pr-checks.yml: these use continue-on-error and generate reports + backend-checks: + name: Backend Checks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.21' + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y libta-lib-dev || true + go mod download || true + + - name: Check Go formatting + id: go-fmt + continue-on-error: true + run: | + UNFORMATTED=$(gofmt -l . 2>/dev/null || echo "") + if [ -n "$UNFORMATTED" ]; then + echo "status=⚠️ Needs formatting" >> $GITHUB_OUTPUT + echo "$UNFORMATTED" | head -10 > fmt-files.txt + else + echo "status=✅ Good" >> $GITHUB_OUTPUT + echo "" > fmt-files.txt + fi + + - name: Run go vet + id: go-vet + continue-on-error: true + run: | + if go vet ./... 2>&1 | tee vet-output.txt; then + echo "status=✅ Good" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT + cat vet-output.txt | head -20 > vet-output-short.txt + fi + + - name: Run tests + id: go-test + continue-on-error: true + run: | + if go test ./... -v 2>&1 | tee test-output.txt; then + echo "status=✅ Passed" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Failed" >> $GITHUB_OUTPUT + cat test-output.txt | tail -30 > test-output-short.txt + fi + + - name: Save backend results + if: always() + run: | + cat > backend-results.json <> $GITHUB_OUTPUT + else + echo "exists=false" >> $GITHUB_OUTPUT + fi + + - name: Install dependencies + if: steps.check-web.outputs.exists == 'true' + working-directory: ./web + continue-on-error: true + run: npm ci + + - name: Build and Type Check + if: steps.check-web.outputs.exists == 'true' + id: build + working-directory: ./web + continue-on-error: true + run: | + # build script includes: tsc && vite build + if npm run build 2>&1 | tee build-output.txt; then + echo "status=✅ Success" >> $GITHUB_OUTPUT + else + echo "status=⚠️ Failed" >> $GITHUB_OUTPUT + cat build-output.txt | tail -30 > build-output-short.txt + fi + + - name: Save frontend results + if: always() && steps.check-web.outputs.exists == 'true' + working-directory: ./web + run: | + cat > frontend-results.json <= 1000) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + body: comment + }); + } + } catch (error) { + console.log('Failed to add label/comment (expected for fork PRs):', error.message); + } + } else { + console.log('Fork PR detected - skipping label/comment (will be handled by pr-checks-comment.yml)'); + } + + # Backend checks (simplified - no TA-Lib required) + backend-checks: + name: Backend Code Quality (Go) + runs-on: ubuntu-latest + permissions: + contents: read # Only need read access for testing + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.21' + + - name: Cache Go modules + uses: actions/cache@v4 + with: + path: ~/go/pkg/mod + key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + restore-keys: | + ${{ runner.os }}-go- + + - name: Download dependencies + run: go mod download + + - name: Run go fmt + continue-on-error: true # Don't block PR if formatting issues found + run: | + if [ "$(gofmt -s -l . | wc -l)" -gt 0 ]; then + echo "⚠️ Code formatting issues found. Please run 'go fmt ./...' locally." + echo "" + echo "Files needing formatting:" + gofmt -s -l . + echo "" + echo "This is a warning and won't block your PR from being merged." + exit 1 + else + echo "✅ All Go files are properly formatted" + fi + + - name: Run go vet + run: go vet ./... + + - name: Build + run: go build -v -o nofx + + # Frontend tests + frontend-tests: + name: Frontend Tests (React/TypeScript) + runs-on: ubuntu-latest + permissions: + contents: read # Only need read access for testing + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Cache Node modules + uses: actions/cache@v4 + with: + path: web/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('web/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + + - name: Install dependencies + working-directory: ./web + run: npm ci + + - name: Build and Type Check + working-directory: ./web + run: npm run build + # Note: build script runs "tsc && vite build" which includes type checking + + # Auto-label based on files changed + auto-label: + name: Auto Label PR + runs-on: ubuntu-latest + # Only run for non-fork PRs (fork PRs don't have write permission) + if: github.event.pull_request.head.repo.full_name == github.repository + permissions: + contents: read + pull-requests: write + issues: write # Required: PRs are issues, labeler needs to modify issue labels + steps: + - uses: actions/labeler@v5 + with: + configuration-path: .github/labeler.yml + repo-token: ${{ secrets.GITHUB_TOKEN }} + + # Check for security issues + security-check: + name: Security Scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write # Required: Upload SARIF results to GitHub Security + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Trivy vulnerability scanner + uses: aquasecurity/trivy-action@master + with: + scan-type: 'fs' + scan-ref: '.' + format: 'sarif' + output: 'trivy-results.sarif' + + - name: Upload Trivy results + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: 'trivy-results.sarif' + + # Check for secrets in code + secrets-check: + name: Check for Secrets + runs-on: ubuntu-latest + permissions: + contents: read # Only need read access for scanning + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run TruffleHog OSS + uses: trufflesecurity/trufflehog@main + with: + path: ./ + base: ${{ github.event.pull_request.base.sha }} + head: ${{ github.event.pull_request.head.sha }} + extra_args: --debug --only-verified + + # All checks passed + all-checks: + name: All Checks Passed + runs-on: ubuntu-latest + needs: [validate-pr, backend-checks, frontend-tests, security-check, secrets-check] + if: always() + permissions: + contents: read # Only need read access for status checking + steps: + - name: Check all jobs + run: | + # Note: validate-pr uses continue-on-error, so it won't block even if title format is invalid + # We only care about actual test failures + echo "validate-pr: ${{ needs.validate-pr.result }}" + echo "backend-checks: ${{ needs.backend-checks.result }}" + echo "frontend-tests: ${{ needs.frontend-tests.result }}" + echo "security-check: ${{ needs.security-check.result }}" + echo "secrets-check: ${{ needs.secrets-check.result }}" + + # Check if any critical checks failed (excluding validate-pr which is advisory) + if [[ "${{ needs.backend-checks.result }}" == "failure" ]] || \ + [[ "${{ needs.frontend-tests.result }}" == "failure" ]] || \ + [[ "${{ needs.security-check.result }}" == "failure" ]] || \ + [[ "${{ needs.secrets-check.result }}" == "failure" ]]; then + echo "❌ Critical checks failed" + exit 1 + else + echo "✅ All critical checks passed!" + if [[ "${{ needs.validate-pr.result }}" != "success" ]]; then + echo "ℹ️ Note: PR title format check is advisory only and doesn't block merging" + fi + fi diff --git a/.gitignore b/.gitignore index d501f8dd..ad0d2a5b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ *.iml *.xml +# AI 工具 +.claude/ + # 编译产物 nofx-auto *.exe @@ -26,6 +29,7 @@ Thumbs.db # 环境变量 .env config.json +config.db # 决策日志 decision_logs/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..f520303d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,203 @@ +# Changelog + +All notable changes to the NOFX project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +**Languages:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md) + +--- + +## [Unreleased] + +### Added +- Documentation system with multi-language support (EN/CN/RU/UK) +- Complete getting-started guides (Docker, PM2, Custom API) +- Architecture documentation with system design details +- User guides with FAQ and troubleshooting +- Community documentation with bounty programs + +### Changed +- Reorganized documentation structure into logical categories +- Updated all README files with proper navigation links + +--- + +## [3.0.0] - 2025-10-30 + +### Added - Major Architecture Transformation 🚀 + +**Complete System Redesign - Web-Based Configuration Platform** + +This is a **major breaking update** that completely transforms NOFX from a static config-based system to a modern web-based trading platform. + +#### Database-Driven Architecture +- SQLite integration replacing static JSON config +- Persistent storage with automatic timestamps +- Foreign key relationships and triggers for data consistency +- Separate tables for AI models, exchanges, traders, and system config + +#### Web-Based Configuration Interface +- Complete web-based configuration management (no more JSON editing) +- AI Model setup through web interface (DeepSeek/Qwen API keys) +- Exchange management (Binance/Hyperliquid credentials) +- Dynamic trader creation (combine any AI model with any exchange) +- Real-time control (start/stop traders without system restart) + +#### Flexible Architecture +- Separation of concerns (AI models and exchanges independent) +- Mix & match capability (unlimited combinations) +- Scalable design (support for unlimited traders) +- Clean slate approach (no default traders) + +#### Enhanced API Layer +- RESTful design with complete CRUD operations +- New endpoints: + - `GET/PUT /api/models` - AI model configuration + - `GET/PUT /api/exchanges` - Exchange configuration + - `POST/DELETE /api/traders` - Trader management + - `POST /api/traders/:id/start|stop` - Trader control +- Updated documentation for all API endpoints + +#### Modernized Codebase +- Type safety with proper separation of configuration types +- Database abstraction with prepared statements +- Comprehensive error handling and validation +- Better code organization (database, API, business logic) + +### Changed +- **BREAKING**: Old `config.json` files no longer used +- Configuration must be done through web interface +- Much easier setup and better UX +- No more server restarts for configuration changes + +### Why This Matters +- 🎯 **User Experience**: Much easier to configure and manage +- 🔧 **Flexibility**: Create any combination of AI models and exchanges +- 📊 **Scalability**: Support for complex multi-trader setups +- 🔒 **Reliability**: Database ensures data persistence and consistency +- 🚀 **Future-Proof**: Foundation for advanced features + +--- + +## [2.0.2] - 2025-10-29 + +### Fixed - Critical Bug Fixes: Trade History & Performance Analysis + +#### PnL Calculation - Major Error Fixed +- **Fixed**: PnL now calculated as actual USDT amount instead of percentage only +- Previously ignored position size and leverage (e.g., 100 USDT @ 5% = 1000 USDT @ 5%) +- Now: `PnL (USDT) = Position Value × Price Change % × Leverage` +- Impact: Win rate, profit factor, and Sharpe ratio now accurate + +#### Position Tracking - Missing Critical Data +- **Fixed**: Open position records now store quantity and leverage +- Previously only stored price and time +- Essential for accurate PnL calculations + +#### Position Key Logic - Long/Short Conflict +- **Fixed**: Changed from `symbol` to `symbol_side` format +- Now properly distinguishes between long and short positions +- Example: `BTCUSDT_long` vs `BTCUSDT_short` + +#### Sharpe Ratio Calculation - Code Optimization +- **Changed**: Replaced custom Newton's method with `math.Sqrt` +- More reliable, maintainable, and efficient + +### Why This Matters +- Historical trade statistics now show real USDT profit/loss +- Performance comparison between different leverage trades is accurate +- AI self-learning mechanism receives correct feedback +- Multi-position tracking (long + short simultaneously) works correctly + +--- + +## [2.0.2] - 2025-10-29 + +### Fixed - Aster Exchange Precision Error + +- Fixed Aster exchange precision error (code -1111) +- Improved price and quantity formatting to match exchange requirements +- Added detailed precision processing logs for debugging +- Enhanced all order functions with proper precision handling + +#### Technical Details +- Added `formatFloatWithPrecision` function +- Price and quantity formatted according to exchange specifications +- Trailing zeros removed to optimize API requests + +--- + +## [2.0.1] - 2025-10-29 + +### Fixed - ComparisonChart Data Processing + +- Fixed ComparisonChart data processing logic +- Switched from cycle_number to timestamp grouping +- Resolved chart freezing issue when backend restarts +- Improved chart data display (shows all historical data chronologically) +- Enhanced debugging logs + +--- + +## [2.0.0] - 2025-10-28 + +### Added - Major Updates + +- AI self-learning mechanism (historical feedback, performance analysis) +- Multi-trader competition mode (Qwen vs DeepSeek) +- Binance-style UI (complete interface imitation) +- Performance comparison charts (real-time ROI comparison) +- Risk control optimization (per-coin position limit adjustment) + +### Fixed + +- Fixed hardcoded initial balance issue +- Fixed multi-trader data sync issue +- Optimized chart data alignment (using cycle_number) + +--- + +## [1.0.0] - 2025-10-27 + +### Added - Initial Release + +- Basic AI trading functionality +- Decision logging system +- Simple Web interface +- Support for Binance Futures +- DeepSeek and Qwen AI model integration + +--- + +## How to Use This Changelog + +### For Users +- Check the [Unreleased] section for upcoming features +- Review version sections to understand what changed +- Follow migration guides for breaking changes + +### For Contributors +When making changes, add them to the [Unreleased] section under appropriate categories: +- **Added** - New features +- **Changed** - Changes to existing functionality +- **Deprecated** - Features that will be removed +- **Removed** - Features that were removed +- **Fixed** - Bug fixes +- **Security** - Security fixes + +When releasing a new version, move [Unreleased] items to a new version section with date. + +--- + +## Links + +- [Documentation](docs/README.md) +- [Contributing Guidelines](CONTRIBUTING.md) +- [Security Policy](SECURITY.md) +- [GitHub Repository](https://github.com/tinkle-community/nofx) + +--- + +**Last Updated:** 2025-11-01 diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md new file mode 100644 index 00000000..0bfdab3d --- /dev/null +++ b/CHANGELOG.zh-CN.md @@ -0,0 +1,203 @@ +# 更新日志 + +NOFX 项目的所有重要更改都将记录在此文件中。 + +本文件格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， +本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +**语言:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md) + +--- + +## [未发布] + +### 新增 +- 多语言文档系统（英文/中文/俄语/乌克兰语） +- 完整的快速开始指南（Docker、PM2、自定义 API） +- 架构文档，包含系统设计细节 +- 用户指南，包含 FAQ 和故障排除 +- 社区文档，包含悬赏计划 + +### 变更 +- 重组文档结构为逻辑分类 +- 更新所有 README 文件，添加适当的导航链接 + +--- + +## [3.0.0] - 2025-10-30 + +### 新增 - 重大架构变革 🚀 + +**系统完全重新设计 - 基于 Web 的配置平台** + +这是一个**重大破坏性更新**，将 NOFX 从基于静态配置的系统完全转变为现代化的 Web 交易平台。 + +#### 数据库驱动架构 +- SQLite 集成，取代静态 JSON 配置 +- 持久化存储，自动时间戳 +- 外键关系和触发器确保数据一致性 +- 为 AI 模型、交易所、交易员和系统配置分离表结构 + +#### 基于 Web 的配置界面 +- 完整的 Web 配置管理（无需编辑 JSON） +- 通过 Web 界面设置 AI 模型（DeepSeek/Qwen API 密钥） +- 交易所管理（Binance/Hyperliquid 凭证） +- 动态创建交易员（结合任意 AI 模型和交易所） +- 实时控制（无需重启即可启动/停止交易员） + +#### 灵活架构 +- 关注点分离（AI 模型和交易所独立） +- 混合搭配能力（无限组合） +- 可扩展设计（支持无限交易员） +- 清洁起点（无默认交易员） + +#### 增强的 API 层 +- RESTful 设计，完整的 CRUD 操作 +- 新端点： + - `GET/PUT /api/models` - AI 模型配置 + - `GET/PUT /api/exchanges` - 交易所配置 + - `POST/DELETE /api/traders` - 交易员管理 + - `POST /api/traders/:id/start|stop` - 交易员控制 +- 更新所有 API 端点文档 + +#### 现代化代码库 +- 类型安全，适当分离配置类型 +- 数据库抽象，使用预处理语句 +- 全面的错误处理和验证 +- 更好的代码组织（数据库、API、业务逻辑） + +### 变更 +- **破坏性变更**：不再使用旧的 `config.json` 文件 +- 必须通过 Web 界面进行配置 +- 设置更简单，用户体验更好 +- 配置更改无需重启服务器 + +### 为什么重要 +- 🎯 **用户体验**：配置和管理更容易 +- 🔧 **灵活性**：创建 AI 模型和交易所的任意组合 +- 📊 **可扩展性**：支持复杂的多交易员设置 +- 🔒 **可靠性**：数据库确保数据持久性和一致性 +- 🚀 **面向未来**：为高级功能奠定基础 + +--- + +## [2.0.2] - 2025-10-29 + +### 修复 - 关键错误修复：交易历史和性能分析 + +#### 盈亏计算 - 重大错误修复 +- **修复**：盈亏现在计算为实际 USDT 金额，而不是仅百分比 +- 之前忽略了仓位大小和杠杆（例如，100 USDT @ 5% = 1000 USDT @ 5%） +- 现在：`盈亏 (USDT) = 仓位价值 × 价格变化 % × 杠杆` +- 影响：胜率、盈利因子和夏普比率现在准确 + +#### 仓位跟踪 - 缺失关键数据 +- **修复**：持仓记录现在存储数量和杠杆 +- 之前只存储价格和时间 +- 这对准确的盈亏计算至关重要 + +#### 仓位键逻辑 - 多空冲突 +- **修复**：从 `symbol` 改为 `symbol_side` 格式 +- 现在正确区分多头和空头仓位 +- 示例：`BTCUSDT_long` vs `BTCUSDT_short` + +#### 夏普比率计算 - 代码优化 +- **变更**：用 `math.Sqrt` 替换自定义牛顿法 +- 更可靠、可维护和高效 + +### 为什么重要 +- 历史交易统计现在显示真实的 USDT 盈亏 +- 不同杠杆交易之间的性能比较准确 +- AI 自学习机制接收正确的反馈 +- 多仓位跟踪（同时多空）正常工作 + +--- + +## [2.0.2] - 2025-10-29 + +### 修复 - Aster 交易所精度错误 + +- 修复 Aster 交易所精度错误（代码 -1111） +- 改进价格和数量格式化以匹配交易所要求 +- 添加详细的精度处理日志用于调试 +- 增强所有订单函数的精度处理 + +#### 技术细节 +- 添加 `formatFloatWithPrecision` 函数 +- 根据交易所规范格式化价格和数量 +- 删除尾随零以优化 API 请求 + +--- + +## [2.0.1] - 2025-10-29 + +### 修复 - ComparisonChart 数据处理 + +- 修复 ComparisonChart 数据处理逻辑 +- 从 cycle_number 切换到时间戳分组 +- 解决后端重启时图表冻结问题 +- 改进图表数据显示（按时间顺序显示所有历史数据） +- 增强调试日志 + +--- + +## [2.0.0] - 2025-10-28 + +### 新增 - 重大更新 + +- AI 自学习机制（历史反馈、性能分析） +- 多交易员竞赛模式（Qwen vs DeepSeek） +- 币安风格 UI（完整界面仿制） +- 性能比较图表（实时 ROI 比较） +- 风险控制优化（每币种仓位限制调整） + +### 修复 + +- 修复硬编码初始余额问题 +- 修复多交易员数据同步问题 +- 优化图表数据对齐（使用 cycle_number） + +--- + +## [1.0.0] - 2025-10-27 + +### 新增 - 初始版本 + +- 基础 AI 交易功能 +- 决策日志系统 +- 简单的 Web 界面 +- 支持币安合约 +- DeepSeek 和 Qwen AI 模型集成 + +--- + +## 如何使用本更新日志 + +### 用户 +- 查看 [未发布] 部分了解即将推出的功能 +- 查看版本部分了解变更内容 +- 遵循破坏性变更的迁移指南 + +### 贡献者 +进行更改时，将它们添加到 [未发布] 部分的相应类别下： +- **新增** - 新功能 +- **变更** - 现有功能的变更 +- **弃用** - 即将删除的功能 +- **移除** - 已删除的功能 +- **修复** - 错误修复 +- **安全** - 安全修复 + +发布新版本时，将 [未发布] 项目移动到带日期的新版本部分。 + +--- + +## 链接 + +- [文档](docs/README.md) +- [贡献指南](CONTRIBUTING.md) +- [安全策略](SECURITY.md) +- [GitHub 仓库](https://github.com/tinkle-community/nofx) + +--- + +**最后更新:** 2025-11-01 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..d1c34065 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,237 @@ +# Contributor Covenant Code of Conduct / 贡献者公约行为准则 + +**Languages:** [English](#english) | [中文](#中文) + +--- + +# English + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at: + + +You can also report via: +- **Telegram:** Direct message to [@Web3Tinkle](https://t.me/Web3Tinkle) +- **Twitter:** DM to [@nofx_ai](https://x.com/nofx_ai) + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + +--- + +# 中文 + +## 我们的承诺 + +作为成员、贡献者和领导者，我们承诺使社区中的每个人都不受骚扰，无论其年龄、体型、明显或不明显的残疾、种族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、个人外貌、种族、种姓、肤色、宗教或性认同和取向如何。 + +我们承诺以有助于开放、友好、多元、包容和健康社区的方式行事和互动。 + +## 我们的标准 + +有助于为我们的社区创造积极环境的行为示例包括： + +* 对他人表现出同理心和善意 +* 尊重不同的意见、观点和经验 +* 给予并优雅地接受建设性反馈 +* 接受责任并向受我们错误影响的人道歉，并从经验中学习 +* 关注不仅对我们个人最好，而且对整个社区最好的事情 + +不可接受的行为示例包括： + +* 使用性化的语言或图像，以及任何形式的性关注或性挑逗 +* 挑衅、侮辱性或贬损性评论，以及人身或政治攻击 +* 公开或私下骚扰 +* 未经他人明确许可，发布他人的私人信息，如物理地址或电子邮件地址 +* 在专业环境中可能被合理认为不适当的其他行为 + +## 执行责任 + +社区领导者负责阐明和执行我们可接受行为的标准，并将对他们认为不适当、威胁性、冒犯性或有害的任何行为采取适当和公平的纠正措施。 + +社区领导者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、wiki 编辑、问题和其他贡献，并在适当时传达审核决定的原因。 + +## 范围 + +本行为准则适用于所有社区空间，也适用于个人在公共空间正式代表社区的情况。代表我们社区的示例包括使用官方电子邮件地址、通过官方社交媒体账户发布信息，或在线上或线下活动中担任指定代表。 + +## 执行 + +可以向负责执行的社区领导者报告滥用、骚扰或其他不可接受行为的实例： + + +您也可以通过以下方式报告： +- **Telegram:** 直接消息 [@Web3Tinkle](https://t.me/Web3Tinkle) +- **Twitter:** 私信 [@nofx_ai](https://x.com/nofx_ai) + +所有投诉都将得到迅速和公正的审查和调查。 + +所有社区领导者都有义务尊重任何事件报告者的隐私和安全。 + +## 执行指南 + +社区领导者将遵循这些社区影响指南来确定他们认为违反本行为准则的任何行动的后果： + +### 1. 纠正 + +**社区影响**：使用不适当的语言或其他被认为在社区中不专业或不受欢迎的行为。 + +**后果**：社区领导者的私下书面警告，说明违规的性质和解释为什么行为不适当。可能要求公开道歉。 + +### 2. 警告 + +**社区影响**：通过单一事件或一系列行动违规。 + +**后果**：警告并说明持续行为的后果。在指定时间内不与相关人员互动，包括不主动与执行行为准则的人互动。这包括避免在社区空间以及外部渠道（如社交媒体）的互动。违反这些条款可能导致临时或永久禁令。 + +### 3. 临时禁令 + +**社区影响**：严重违反社区标准，包括持续的不当行为。 + +**后果**：在指定时间内临时禁止与社区进行任何形式的互动或公开交流。在此期间，不允许与相关人员进行公开或私下互动，包括不主动与执行行为准则的人互动。违反这些条款可能导致永久禁令。 + +### 4. 永久禁令 + +**社区影响**：表现出违反社区标准的模式，包括持续的不当行为、对个人的骚扰，或对个人类别的攻击或贬低。 + +**后果**：永久禁止在社区内进行任何形式的公开互动。 + +## 归属 + +本行为准则改编自 [贡献者公约][homepage] 2.1 版，可在 +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1] 获取。 + +社区影响指南受到 [Mozilla 行为准则执行阶梯][Mozilla CoC] 的启发。 + +有关本行为准则的常见问题解答，请参阅 [https://www.contributor-covenant.org/faq][FAQ]。翻译版本可在 [https://www.contributor-covenant.org/translations][translations] 获取。 + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..31fc7c02 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,481 @@ +# 🤝 Contributing to NOFX + +**Language:** [English](CONTRIBUTING.md) | [中文](docs/i18n/zh-CN/CONTRIBUTING.md) + +Thank you for your interest in contributing to NOFX! This document provides guidelines and workflows for contributing to the project. + +--- + +## 📑 Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Workflow](#development-workflow) +- [PR Submission Guidelines](#pr-submission-guidelines) +- [Coding Standards](#coding-standards) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Review Process](#review-process) +- [Bounty Program](#bounty-program) + +--- + +## 📜 Code of Conduct + +This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. + +--- + +## 🎯 How Can I Contribute? + +### 1. Report Bugs 🐛 + +- Use the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md) +- Check if the bug has already been reported +- Include detailed reproduction steps +- Provide environment information (OS, Go version, etc.) + +### 2. Suggest Features ✨ + +- Use the [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md) +- Explain the use case and benefits +- Check if it aligns with the [project roadmap](docs/roadmap/README.md) + +### 3. Submit Pull Requests 🔧 + +Before submitting a PR, please check the following: + +#### ✅ **Accepted Contributions** + +**High Priority** (aligned with roadmap): +- 🔒 Security enhancements (encryption, authentication, RBAC) +- 🧠 AI model integrations (GPT-4, Claude, Gemini Pro) +- 🔗 Exchange integrations (OKX, Bybit, Lighter, EdgeX) +- 📊 Trading data APIs (AI500, OI analysis, NetFlow) +- 🎨 UI/UX improvements (mobile responsiveness, charts) +- ⚡ Performance optimizations +- 🐛 Bug fixes +- 📝 Documentation improvements + +**Medium Priority:** +- ✅ Test coverage improvements +- 🌐 Internationalization (new language support) +- 🔧 Build/deployment tooling +- 📈 Monitoring and logging enhancements + +#### ❌ **Not Accepted** (without prior discussion) + +- Major architectural changes without RFC (Request for Comments) +- Features not aligned with project roadmap +- Breaking changes without migration path +- Code that introduces new dependencies without justification +- Experimental features without opt-in flag + +**⚠️ Important:** For major features, please open an issue for discussion **before** starting work. + +--- + +## 🛠️ Development Workflow + +### 1. Fork and Clone + +```bash +# Fork the repository on GitHub +# Then clone your fork +git clone https://github.com/YOUR_USERNAME/nofx.git +cd nofx + +# Add upstream remote +git remote add upstream https://github.com/tinkle-community/nofx.git +``` + +### 2. Create a Feature Branch + +```bash +# Update your local dev branch +git checkout dev +git pull upstream dev + +# Create a new branch +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-bug-fix +``` + +**Branch Naming Convention:** +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation updates +- `refactor/` - Code refactoring +- `perf/` - Performance improvements +- `test/` - Test updates +- `chore/` - Build/config changes + +### 3. Set Up Development Environment + +```bash +# Install Go dependencies +go mod download + +# Install frontend dependencies +cd web +npm install +cd .. + +# Install TA-Lib (required) +# macOS: +brew install ta-lib + +# Ubuntu/Debian: +sudo apt-get install libta-lib0-dev +``` + +### 4. Make Your Changes + +- Follow the [coding standards](#coding-standards) +- Write tests for new features +- Update documentation as needed +- Keep commits focused and atomic + +### 5. Test Your Changes + +```bash +# Run backend tests +go test ./... + +# Build backend +go build -o nofx + +# Run frontend in dev mode +cd web +npm run dev + +# Build frontend +npm run build +``` + +### 6. Commit Your Changes + +Follow the [commit message guidelines](#commit-message-guidelines): + +```bash +git add . +git commit -m "feat: add support for OKX exchange integration" +``` + +### 7. Push and Create PR + +```bash +# Push to your fork +git push origin feature/your-feature-name + +# Go to GitHub and create a Pull Request +# Use the PR template and fill in all sections +``` + +--- + +## 📝 PR Submission Guidelines + +### Before Submitting + +- [ ] Code compiles successfully (`go build` and `npm run build`) +- [ ] All tests pass (`go test ./...`) +- [ ] No linting errors (`go fmt`, `go vet`) +- [ ] Documentation is updated +- [ ] Commits follow conventional commits format +- [ ] Branch is rebased on latest `dev` + +### PR Title Format + +Use [Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +(): + +Examples: +feat(exchange): add OKX exchange integration +fix(trader): resolve position tracking bug +docs(readme): update installation instructions +perf(ai): optimize prompt generation +refactor(core): extract common exchange interface +``` + +**Types:** +- `feat` - New feature +- `fix` - Bug fix +- `docs` - Documentation +- `style` - Code style (formatting, no logic change) +- `refactor` - Code refactoring +- `perf` - Performance improvement +- `test` - Test updates +- `chore` - Build/config changes +- `ci` - CI/CD changes +- `security` - Security improvements + +### PR Description + +Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md) and ensure: + +1. **Clear description** of what and why +2. **Type of change** is marked +3. **Related issues** are linked +4. **Testing steps** are documented +5. **Screenshots** for UI changes +6. **All checkboxes** are completed + +### PR Size + +Keep PRs focused and reasonably sized: + +- ✅ **Small PR** (< 300 lines): Ideal, fast review +- ⚠️ **Medium PR** (300-1000 lines): Acceptable, may take longer +- ❌ **Large PR** (> 1000 lines): Please break into smaller PRs + +--- + +## 💻 Coding Standards + +### Go Code + +```go +// ✅ Good: Clear naming, proper error handling +func ConnectToExchange(apiKey, secret string) (*Exchange, error) { + if apiKey == "" || secret == "" { + return nil, fmt.Errorf("API credentials are required") + } + + client, err := createClient(apiKey, secret) + if err != nil { + return nil, fmt.Errorf("failed to create client: %w", err) + } + + return &Exchange{client: client}, nil +} + +// ❌ Bad: Poor naming, no error handling +func ce(a, s string) *Exchange { + c := createClient(a, s) + return &Exchange{client: c} +} +``` + +**Best Practices:** +- Use meaningful variable names +- Handle all errors explicitly +- Add comments for complex logic +- Follow Go idioms and conventions +- Run `go fmt` before committing +- Use `go vet` and `golangci-lint` + +### TypeScript/React Code + +```typescript +// ✅ Good: Type-safe, clear naming +interface TraderConfig { + id: string; + exchange: 'binance' | 'hyperliquid' | 'aster'; + aiModel: string; + enabled: boolean; +} + +const TraderCard: React.FC<{ trader: TraderConfig }> = ({ trader }) => { + const [isRunning, setIsRunning] = useState(false); + + const handleStart = async () => { + try { + await startTrader(trader.id); + setIsRunning(true); + } catch (error) { + console.error('Failed to start trader:', error); + } + }; + + return
...
; +}; + +// ❌ Bad: No types, unclear naming +const TC = (props) => { + const [r, setR] = useState(false); + const h = () => { startTrader(props.t.id); setR(true); }; + return
...
; +}; +``` + +**Best Practices:** +- Use TypeScript strict mode +- Define interfaces for all data structures +- Avoid `any` type +- Use functional components with hooks +- Follow React best practices +- Run `npm run lint` before committing + +### File Structure + +``` +NOFX/ +├── cmd/ # Main applications +├── internal/ # Private code +│ ├── exchange/ # Exchange adapters +│ ├── trader/ # Trading logic +│ ├── ai/ # AI integrations +│ └── api/ # API handlers +├── pkg/ # Public libraries +├── web/ # Frontend +│ ├── src/ +│ │ ├── components/ +│ │ ├── pages/ +│ │ ├── hooks/ +│ │ └── utils/ +│ └── public/ +└── docs/ # Documentation +``` + +--- + +## 📋 Commit Message Guidelines + +### Format + +``` +(): + + + +