docs: update PROJECT_EXPERIENCE with comprehensive project lessons

- Add API routing structure (user /keys vs admin /api-keys) - Add本次审查问题修复清单 - Add testing commands and coverage info - Update common pitfalls section
2026-04-03 07:25:50 +08:00
parent daae3497af
commit 4bf838105b
1 changed files with 87 additions and 10 deletions
--- a/docs/PROJECT_EXPERIENCE.md
+++ b/docs/PROJECT_EXPERIENCE.md
@@ -9,6 +9,7 @@
 - **前端**：Vue 3 + Vite + Pinia + TailwindCSS
 - **数据库**：PostgreSQL 16 + Redis
 - **包管理**：Go modules + pnpm
+- **测试**：Vitest (前端) + Playwright (E2E) + Go test

 ### 项目结构
 ```
@@ -24,10 +25,21 @@ sub2api/
 │   ├── migrations/       # 数据库迁移
 │   └── config.yaml       # 配置文件
 ├── frontend/             # Vue 前端
-├── tests/                # E2E 测试
+├── tests/                # E2E 测试 (Playwright)
 └── docs/                 # 文档
 ```

+### API 路由结构（关键）
+
+| 端点 | 路由 | 文件位置 |
+|------|------|----------|
+| 用户 API Key | `/api/v1/keys` | routes/user.go:42 |
+| 管理员 API Key | `/api/v1/admin/api-keys` | routes/admin.go:91 |
+| 用户分组 | `/api/v1/groups/available` | routes/user.go:52 |
+| 管理员分组 | `/api/v1/admin/groups` | routes/admin.go |
+
+**注意**：用户端是 `/keys`，管理端是 `/api-keys`，容易混淆。
+
 ## 二、Git 仓库管理

 ### 当前仓库配置
@@ -35,18 +47,18 @@ sub2api/
 | 远程 | 地址 | 用途 |
 |------|------|------|
 | origin | https://github.com/phamnazage-jpg/tokens-reef.git | GitHub（代码质量修复） |
-| gitea | https://www.tksea.top/pham/tokensea.git | Gitea（主仓库） |
+| gitea | https://www.tksea.top/pham/tokensea.git | Gitea（字节海洋主仓库） |

 ### 常用命令
 ```bash
 # 添加 Gitea 远程
 git remote add gitea https://www.tksea.top/pham/tokensea.git

-# 强制推送到 Gitea（覆盖）
-git push -f gitea main
+# 推送到 Gitea
+git push gitea test-fix-branch

-# 强制推送到 GitHub
-git push -f origin main
+# 推送到 GitHub
+git push origin test-fix-branch

 # 查看远程
 git remote -v
@@ -56,13 +68,18 @@ git remote -v

 ### 1. E2E 测试问题

-#### API 路径错误
- **问题**：测试调用 `/api/v1/keys` 但后端路由是 `/api/v1/api-keys`
- **解决**：将所有路径改为 `/api/v1/api-keys`
+#### API 路径错误（重要）
+- **问题**：测试调用 `/api/v1/api-keys` 但后端用户端路由是 `/api/v1/keys`
+- **解决**：
+  - 用户端：`/api/v1/keys`
+  - 管理员端：`/api/v1/admin/api-keys`
+- **验证方法**：查看 `routes/user.go` 和 `routes/admin.go` 中的路由注册

 #### Payload 格式不匹配
 - **余额调整**：使用 `{balance, operation, notes}`
+  - ❌ 错误：`{amount, reason}`
 - **Rate Multiplier**：使用 `{entries: [{user_id, rate_multiplier}]}`
+  - ❌ 错误：`[{model, multiplier}]`

 #### 测试文件无法提交
 - **原因**：`tests` 目录在 `.gitignore` 中
@@ -77,6 +94,11 @@ git remote -v
 #### Interface 新增方法
 - **问题**：新增方法后编译失败
 - **解决**：所有实现该 interface 的 stub/mock 必须补上新方法
+- **示例**：admin_service.go 新增方法后，stub_test.go 也需同步更新
+
+#### Handler 注释与路由不一致
+- **问题**：注释写 `/api/v1/api-keys` 但实际是 `/api/v1/keys`
+- **解决**：始终以 `routes/*.go` 中的注册为准更新注释

 #### Ent Schema 修改
 - **命令**：`go generate ./ent`
@@ -95,6 +117,10 @@ rm -rf node_modules
 pnpm install
 ```

+#### 测试 Mock 不完整
+- **问题**：运行时警告 "XXX is not a function"
+- **解决**：在 `vi.mock()` 中补充缺失的 mock 函数
+
 ## 四、代码审查经验

 ### 审查维度
@@ -121,6 +147,17 @@ pnpm install
 4. **前端测试**：`cd frontend && pnpm test -- --run`
 5. **E2E 测试**：确保后端运行在 8080 端口

+### 本次审查发现的问题及修复
+
+| ID | 问题 | 位置 | 修复 |
+|----|------|------|------|
+| P0-01 | sticky_session_test.go 缺少 context | service/sticky_session_test.go | 添加 import |
+| P1-01 | gateway_service.go defaultMaxLineSize过大 | service/gateway_service.go | 优化为合理值 |
+| P1-03 | GetStats 返回硬编码零值 | handler/admin/group_handler.go | 实现真实数据查询 |
+| E2E-01 | API Key 路径错误 (24处) | tests/e2e/user-apikey-lifecycle.spec.ts | 改为 `/api/v1/keys` |
+| C-01 | Handler注释与路由不一致 | handler/api_key_handler.go | 更新注释 |
+| O-02 | getModelStats mock 缺失 | frontend/.../UsageView.spec.ts | 添加 mock |
+
 ## 五、关键配置

 ### Windows 开发环境
@@ -131,6 +168,7 @@ pnpm install
 | PostgreSQL | `C:\Program Files\PostgreSQL\16\` |
 | 测试账号 | lon22@qq.com / admin123 |
 | 后端端口 | 8080 |
+| 前端端口 | 5173 |

 ### 测试环境变量

@@ -141,28 +179,67 @@ TEST_EMAIL=lon22@qq.com
 TEST_PASSWORD=admin123
 ```

+### 测试命令
+
+```bash
+# 后端编译
+cd backend && D:/Program\ Files/Go/bin/go.exe build ./...
+
+# 后端测试
+cd backend && D:/Program\ Files/Go/bin/go.exe test -short ./...
+
+# 前端测试
+cd frontend && pnpm test -- --run
+
+# 前端覆盖测试
+cd frontend && pnpm test -- --run --coverage
+
+# E2E 测试
+cd tests && npx playwright test --project=chromium
+```
+
 ## 六、经验教训

 ### 1. 测试必须验证真实 API 路径
 - 不要假设路由是什么，要去 `routes/*.go` 确认
 - E2E 测试调用前先手动 curl 验证
+- 用户端 `/keys` vs 管理端 `/api-keys` 容易混淆

 ### 2. Payload 必须与后端 DTO 一致
 - 查看 handler 中的 struct 定义
 - 不要猜测字段名，用 grep 确认
+- 余额操作使用 balance+operation+notes 不是 amount+reason

 ### 3. 提交前务必本地验证
 - 编译通过 ≠ 测试通过
 - 测试通过 ≠ 功能正常
+- 单元测试通过 ≠ E2E 测试通过

 ### 4. 文档要及时更新
 - 每次修复问题后更新 MEMORY.md
 - 新增坑点更新 DEV_GUIDE.md
 - 配置变更更新 CLAUDE.md

-## 七、相关文档
+### 5. 代码审查重点
+- API 路径一致性（handler 注释 vs 实际路由）
+- 测试 Mock 完整性
+- 敏感信息硬编码检查
+
+## 七、测试覆盖率
+
+| 模块 | 覆盖率 | 说明 |
+|------|--------|------|
+| src/api | 85% | 高覆盖率 |
+| src/composables | 55% | 中等 |
+| src/stores | 55% | 中等 |
+| src/views/admin | 35% | 待提高 |
+| src/views/user | 20% | 待提高 |
+| src/views/auth | 0% | 需补充 |
+
+## 八、相关文档

 - `DEV_GUIDE.md` - 开发指南
 - `CLAUDE.md` - Claude Code 配置
 - `.workbuddy/memory/MEMORY.md` - 长期记忆
 - `REVIEW_REPORT_*.md` - 代码审查报告
+- `COMPREHENSIVE_TEST_REVIEW_*.md` - 测试审查报告