tokens-reef/CLAUDE.md

# CLAUDE.md - Sub2API Project Guide

This file provides Claude Code with specific guidance for working on Sub2API.

## Project Context

Sub2API is an AI API Gateway that distributes API quotas from AI subscriptions (OpenAI, Anthropic, Google, etc.) to users through generated API keys.

## Quick Reference

| Item | Value |
|------|-------|
| Backend Port | 8080 |
| Frontend Dev | pnpm dev |
| Test Account | lon22@qq.com / admin123 |
| Go Path | D:/Program Files/Go/bin/go.exe |

## Test Commands

```bash
# Frontend (Vitest)
cd frontend && pnpm test -- --run

# Backend (Go) - Use full path on Windows
D:/Program Files/Go/bin/go.exe test -short ./...

# E2E (Playwright)
cd tests && npx playwright test --project=chromium
```

## Important Notes

### Windows-Specific
- Go installed at: `D:/Program Files/Go/`
- Use full path: `D:/Program Files/Go/bin/go.exe`
- Logger test (`internal/pkg/logger`) times out on Windows due to zap Fsync() - skip with `-skip "logger"`

### Backend Build
- Frontend builds to: `backend/internal/web/dist/`
- Build command: `cd frontend && pnpm build`
- Binary: `backend/sub2api.exe`

### Database
- Uses Ent ORM for Go
- Generate code: `go generate ./ent` in backend/

## File Patterns

### Backend (Go)
- Handlers: `backend/internal/handler/`
- Services: `backend/internal/service/`
- Routes: `backend/internal/server/routes/`

### Frontend (Vue)
- API: `frontend/src/api/`
- Components: `frontend/src/components/`
- Stores: `frontend/src/stores/`
- Tests: `frontend/src/**/*.spec.ts`

### E2E Tests
- Location: `tests/e2e/*.spec.ts`
- Config: `tests/playwright.config.ts`
- Pages: `tests/e2e/pages/`

## Common Development Tasks

### Running Tests
```bash
# All tests
cd tests && npm test

# Just E2E
cd tests && npx playwright test

# Frontend unit tests
cd frontend && pnpm test

# Backend tests
cd backend && D:/Program Files/Go/bin/go.exe test -short ./...
```

### Adding a Feature
1. Backend first: handler → service → repository
2. Add route registration
3. Frontend API client
4. Vue component
5. Tests

### Code Generation
```bash
cd backend
go generate ./ent
go generate ./cmd/server
```

## Key Dependencies

### Backend
- `go.uber.org/zap` - Logging
- `gin-gonic/gin` - HTTP framework
- `ent/ent` - ORM
- `redis/go-redis` - Redis client

### Frontend
- `vue` 3.4+
- `vite` 5+
- `tailwindcss`
- `pinia` - State management
- `vitest` - Testing

## Testing Best Practices

1. **Frontend**: Tests live next to components in `__tests__/` directories
2. **E2E**: Use Page Object pattern in `tests/e2e/pages/`
3. **Backend**: Tests in `_test.go` files alongside source

## Troubleshooting

### Backend won't start
- Check PostgreSQL and Redis are running
- Verify `backend/config.yaml` is correct

### Frontend build fails
- Run `pnpm install` in frontend directory
- Check Node.js version (18+)

### E2E tests fail
- Ensure backend is running on port 8080
- Check test account exists: lon22@qq.com

## tokens-reef 独立修复仓库

为了避免与主仓库 Wei-Shaw/sub2api 混淆，Sub2API 的代码质量修复（P0/P1 问题）存放在独立的仓库中：

| 属性 | 值 |
|------|-------|
| 仓库名称 | `tokens-reef`（token 海洋） |
| 仓库地址 | https://github.com/phamnazage-jpg/tokens-reef |
| 描述 | Code quality fixes for Sub2API - P0/P1 issues |
| 用途 | 专门存放 Sub2API 项目的 P0/P1 级别代码质量修复 |
| 创建时间 | 2026-03-31 |

**主要修复内容**：
- `ModelError.Is()` 精确匹配修复（避免 errors.Is 误判）
- `shouldClearStickySession` ctx 参数传播（修复 context.Background 导致的请求取消问题）
- `validateCodeSignature` 共享函数抽取（消除 promo_service.go 和 redeem_service.go 中的重复代码）
- TODO 存根返回 501 Not Implemented（而非假数据）
- 混合中英文错误消息统一为英文
- 移除伪 if-else 代码

## 项目经验总结

### 开发注意事项

1. **Windows 特定**：
   - Go 完整路径：`D:/Program Files/Go/bin/go.exe`
   - Logger 测试因 zap Fsync() 超时，使用 `-skip "logger"` 跳过

2. **E2E 测试坑点**：
   - API Key 路由是 `/api/v1/keys`（用户端）/admin 是 `/api/v1/admin/api-keys`
   - 余额调整 Payload：`{balance, operation, notes}`
   - Rate Multiplier Payload：`{entries: [{user_id, rate_multiplier}]}`
   - tests 目录在 .gitignore 中，需用 `git add -f tests/` 强制添加

3. **依赖注入**：
   - 使用 Google Wire 进行依赖注入
   - 修改 wire.go 后运行 `go mod tidy` 确保依赖完整

4. **前端测试覆盖**：
   - `src/views/auth/` 测试覆盖率为 0%
   - `src/views/user/` 测试覆盖率约 20%
   - 建议优先补充 auth 登录相关测试

5. **代码注释一致性**：
   - api_key_handler.go 注释已更新为正确路由 `/api/v1/keys`

### Gitea 远程仓库

| 属性 | 值 |
|------|-------|
| 地址 | https://www.tksea.top/pham/tokensea |
| 名称 | 字节海洋（tokensea） |
| 用户 | pham |

## Project Planning Documents

项目相关文档位置：
- **代码审查报告**: `REVIEW_REPORT_YYYY-MM-DD.md`（按日期生成）
- **开发指南**: `DEV_GUIDE.md`
- **README**: `README.md` / `README_CN.md`（中文）
- **长期记忆**: `.workbuddy/memory/MEMORY.md`