|
2 | 2 |
|
3 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | 4 |
|
5 | | -## 🤖 代理专属规则 |
6 | | -> 重要：以下规则仅对开发代理有效 |
7 | | -- 用户用中文提问时，请用中文回答 |
8 | | -- 编辑已存在的文件时，优先使用 edit 工具，不要使用 write 工具 |
9 | | -- 编辑前端代码后运行 `pnpm type-check`，**禁止自动运行 `pnpm build`**，除非用户明确要求 |
10 | | -- 提交代码前必须执行对应语言的格式化和检查命令 |
| 5 | +## 🤖 Agent Rules |
| 6 | +> Important: The following rules apply to development agents only |
| 7 | +- When the user asks in Chinese, respond in Chinese |
| 8 | +- When editing existing files, prefer the `edit` tool over the `write` tool |
| 9 | +- After editing frontend code, run `pnpm type-check`. **Do NOT auto-run `pnpm build`** unless explicitly requested |
| 10 | +- Before committing code, run the corresponding language's formatting and linting commands |
| 11 | +- Do NOT add code comments unless explicitly asked |
| 12 | +- Keep responses concise and technical; avoid conversational filler |
11 | 13 |
|
12 | 14 | --- |
13 | 15 |
|
14 | | -## 项目概述 |
15 | | -基于 FastAPI + Vue 3 的全栈阅读清单管理与个人博客系统，包含用户认证、书籍管理、微信读书导入、博客系统、留言板、RSS 阅读器、AI 助手、后台监控等功能。 |
| 16 | +## Project Overview |
| 17 | +Full-stack reading list management and personal blog system built with FastAPI + Vue 3. Features include user authentication, book management, WeRead import, blog system, guestbook, RSS reader, AI assistant, and admin monitoring. |
16 | 18 |
|
17 | | -## 常用命令 |
| 19 | +## Common Commands |
18 | 20 |
|
19 | | -### 后端 (在 `backend/` 目录下执行) |
| 21 | +### Backend (run from `backend/`) |
20 | 22 | ```bash |
21 | | -# 开发 |
22 | | -python dev.py # 启动开发服务器 (:5555) |
23 | | -ruff format . && ruff check . # 格式化 + 代码检查 |
24 | | -ruff check . --fix # 自动修复 lint 问题 |
25 | | -alembic revision --autogenerate -m "描述" # 生成数据库迁移 |
26 | | -alembic upgrade head # 执行所有迁移 |
27 | | - |
28 | | -# 测试 |
29 | | -python -m pytest # 运行所有后端测试 |
30 | | -python -m pytest tests/test_x.py -v # 运行单个测试文件 |
31 | | -python -m pytest tests/test_x.py::test_func -v # 运行单个测试函数 |
32 | | -python -m pytest -k "关键字" # 按关键字过滤测试 |
| 23 | +python dev.py # Start dev server (:5555) |
| 24 | +ruff format . && ruff check . # Format + lint |
| 25 | +ruff check . --fix # Auto-fix lint issues |
| 26 | +alembic revision --autogenerate -m "desc" # Generate migration |
| 27 | +alembic upgrade head # Run all migrations |
| 28 | + |
| 29 | +# Testing |
| 30 | +python -m pytest # All tests |
| 31 | +python -m pytest tests/test_books.py -v # Single file |
| 32 | +python -m pytest tests/test_books.py::test_list -v # Single function |
| 33 | +python -m pytest -k "keyword" # Filter by keyword |
| 34 | +python -m pytest --tb=short # Short traceback |
33 | 35 | ``` |
34 | 36 |
|
35 | | -### 前端 (在 `frontend/` 目录下执行) |
| 37 | +### Frontend (run from `frontend/`) |
36 | 38 | ```bash |
37 | | -# 开发 |
38 | | -pnpm run dev # 启动开发服务器 (:5173) |
39 | | -pnpm run format # Prettier 格式化代码 |
40 | | -pnpm run lint # 运行 Oxlint + ESLint 检查 |
41 | | -pnpm run type-check # 运行 TypeScript 类型检查 |
42 | | -pnpm run build # 完整构建 (类型检查 + 编译) |
43 | | -pnpm run build-only # 仅构建 (跳过类型检查) |
44 | | - |
45 | | -# 测试 |
46 | | -pnpm run test:unit # 运行 Vitest 单元测试 |
47 | | -npx playwright test # 运行 Playwright E2E 测试 |
48 | | -npx playwright test --headed # 可视化模式运行 E2E 测试 |
49 | | -npx playwright test --debug # 调试 E2E 测试 |
| 39 | +pnpm run dev # Start dev server (:5173) |
| 40 | +pnpm run format # Prettier format |
| 41 | +pnpm run lint # Oxlint + ESLint check |
| 42 | +pnpm run type-check # TypeScript type-check (vue-tsc) |
| 43 | +pnpm run build # Full build (type-check + compile) |
| 44 | +pnpm run build-only # Build only (skip type-check) |
| 45 | + |
| 46 | +# Testing |
| 47 | +pnpm run test:unit # Vitest unit tests |
| 48 | +npx playwright test # Playwright E2E |
| 49 | +npx playwright test --headed # E2E with browser UI |
| 50 | +npx playwright test --debug # Debug E2E |
50 | 51 | ``` |
51 | 52 |
|
52 | | -## 架构概览 |
| 53 | +## Architecture |
53 | 54 | ``` |
54 | | -├── backend/ # FastAPI 后端 |
55 | | -│ ├── app/ |
56 | | -│ │ ├── api/v1/ # API 端点 (auth, books, blog, messages, weread, rss, admin, aiagent, todos 等) |
57 | | -│ │ ├── models/ # 数据库模型 (SQLAlchemy 2.0 + MongoDB Beanie) |
58 | | -│ │ ├── schemas/ # Pydantic 请求/响应 schema (按领域拆分的独立模块) |
59 | | -│ │ ├── repositories/ # 数据访问层 |
60 | | -│ │ ├── services/ # 业务逻辑层 |
61 | | -│ │ ├── core/ # 核心配置、日志、AI Agent |
62 | | -│ │ ├── utils/ # 工具函数 |
63 | | -│ │ ├── tasks/ # Taskiq 异步任务 |
64 | | -│ │ └── main.py # FastAPI 应用入口 |
65 | | -│ ├── alembic/ # 数据库迁移 |
66 | | -│ └── ruff.toml # Ruff 配置 |
67 | | -├── frontend/ # Vue 3 + TypeScript 前端 |
68 | | -│ └── src/ |
69 | | -│ ├── views/ # 页面组件 |
70 | | -│ ├── components/ # 可复用 Vue 组件 |
71 | | -│ ├── stores/ # Pinia 状态管理 |
72 | | -│ ├── router/ # Vue Router 配置 |
73 | | -│ ├── types/ # TypeScript 类型定义 |
74 | | -│ ├── lib/ # 第三方库封装 |
75 | | -│ ├── utils/ # 工具函数 |
76 | | -│ └── layouts/ # 布局组件 |
77 | | -├── tests/ # Pytest 后端测试 + Playwright E2E 测试 |
78 | | -└── scripts/ # 工具脚本 |
| 55 | +backend/app/ |
| 56 | +├── api/v1/ # API endpoints (auth, books, blog, messages, weread, rss, admin, ai, todos, monitor) |
| 57 | +├── models/ # SQLAlchemy 2.0 (models.py) + MongoDB Beanie (beanie.py) |
| 58 | +├── schemas/ # Pydantic schemas (per-domain: auth, book, blog, rss, etc.) |
| 59 | +├── repositories/ # Data access layer |
| 60 | +├── services/ # Business logic |
| 61 | +├── core/ # Config, logging, AI agent |
| 62 | +├── utils/ # Utility functions |
| 63 | +├── tasks/ # Taskiq async tasks |
| 64 | +└── main.py # FastAPI entry point |
| 65 | +
|
| 66 | +frontend/src/ |
| 67 | +├── views/ # Page components (auth, blog, rss, books, general) |
| 68 | +├── components/ # Reusable Vue components (ui/, bento/, basic/, icons/, editor/) |
| 69 | +├── stores/ # Pinia state management |
| 70 | +├── router/ # Vue Router config |
| 71 | +├── types/ # TypeScript type definitions |
| 72 | +├── lib/ # Third-party library wrappers |
| 73 | +├── utils/ # Utility functions |
| 74 | +├── layouts/ # Layout components |
| 75 | +└── assets/ # Static assets |
79 | 76 | ``` |
80 | 77 |
|
81 | | -## 技术栈 |
82 | | -- **后端**: FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL, MongoDB (Beanie), Redis, Taskiq |
83 | | -- **前端**: Vue 3.5, TypeScript, Vite, Tailwind CSS v4, Pinia, shadcn-vue |
84 | | -- **AI**: Agno (替代 Langchain) |
85 | | -- **端口**: 后端 `:5555`，前端 `:5173` |
86 | | - |
87 | | -## 代码规范 |
88 | | - |
89 | | -### 后端 (Python) |
90 | | -- Ruff 配置 (`ruff.toml`)：行宽 79 字符，4 空格缩进，双引号，Python 3.14 目标 |
91 | | -- 类型注解：使用 Python 3.14+ 现代语法 (`list[str]` 而非 `List[str]`) |
92 | | -- 命名：函数/变量用 `snake_case`，类用 `PascalCase`，常量用 `UPPER_SNAKE_CASE` |
93 | | -- 禁止空 `except:` 块，必须指定异常类型 |
94 | | -- 所有公共函数/类需要 Google 风格 docstring |
95 | | -- 数据库操作使用 async 驱动 + `async/await` |
96 | | -- import 排序：标准库 → 第三方 → 本地 (isort) |
97 | | -- 禁止相对导入，使用 `from app.xxx import ...` 绝对路径 |
98 | | -- Schema 按领域拆分到 `app/schemas/` 下独立文件 (auth, book, blog, rss 等) |
99 | | - |
100 | | -### 前端 (Vue/TypeScript) |
101 | | -- 使用 `<script setup lang="ts">` + Composition API (禁止使用 Options API) |
102 | | -- 严格 TypeScript：避免 `any`，使用 `unknown` + 类型守卫 |
103 | | -- 命名：函数/变量用 `camelCase`，组件/类型用 `PascalCase` |
104 | | -- 组件文件用 `PascalCase.vue`，工具文件用 `camelCase.ts` |
105 | | -- 优先使用 Tailwind CSS 工具类，避免自定义 CSS |
106 | | -- 路径使用 `@/` 别名指向 `frontend/src/` 目录 |
107 | | -- 包管理器使用 `pnpm`，不要使用 `npm` |
108 | | - |
109 | | -### 数据库 |
110 | | -- SQLAlchemy 模型：`backend/app/models/models.py` |
111 | | -- MongoDB Beanie 模型：`backend/app/models/beanie.py` |
112 | | -- Pydantic Schema：`backend/app/schemas/` (按领域拆分的独立模块) |
113 | | -- 迁移文件：`backend/alembic/versions/` |
114 | | - |
115 | | -## 提交规范 |
116 | | -1. 后端提交前：`cd backend && ruff format . && ruff check .` |
117 | | -2. 前端提交前：`cd frontend && pnpm format && pnpm lint && pnpm type-check` |
118 | | -3. 提交信息遵循 Conventional Commits 格式：`feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:` |
119 | | -4. 分支命名：`feature/xxx`, `fix/xxx`, `refactor/xxx` |
120 | | -5. 禁止提交：`.env`, `node_modules/`, `.venv/`, `__pycache__/`, 临时文件 |
| 78 | +## Tech Stack |
| 79 | +- **Backend**: FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL, MongoDB (Beanie), Redis, Taskiq |
| 80 | +- **Frontend**: Vue 3.5, TypeScript, Vite, Tailwind CSS v4, Pinia, shadcn-vue, motion-v |
| 81 | +- **AI**: Agno |
| 82 | +- **Ports**: Backend `:5555`, Frontend `:5173` |
| 83 | + |
| 84 | +## Code Style |
| 85 | + |
| 86 | +### Backend (Python) |
| 87 | +- Ruff config (`ruff.toml`): 79 char line width, 4-space indent, double quotes, Python 3.14 target |
| 88 | +- Type annotations: modern Python 3.14+ syntax (`list[str]` not `List[str]`) |
| 89 | +- Naming: `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants |
| 90 | +- No bare `except:` — always specify exception type |
| 91 | +- Google-style docstrings for all public functions/classes |
| 92 | +- Use `async/await` for all database operations |
| 93 | +- Import order: stdlib → third-party → local (isort) |
| 94 | +- Absolute imports only: `from app.xxx import ...` |
| 95 | +- Schemas split by domain in `app/schemas/` (auth, book, blog, rss, etc.) |
| 96 | + |
| 97 | +### Frontend (Vue/TypeScript) |
| 98 | +- Always use `<script setup lang="ts">` + Composition API (no Options API) |
| 99 | +- Strict TypeScript: avoid `any`, use `unknown` + type guards |
| 100 | +- Naming: `camelCase` for functions/variables, `PascalCase` for components/types |
| 101 | +- Component files: `PascalCase.vue`, utility files: `camelCase.ts` |
| 102 | +- Prefer Tailwind CSS utilities over custom CSS |
| 103 | +- Use `@/` alias for imports from `frontend/src/` |
| 104 | +- Package manager: `pnpm` only, never `npm` |
| 105 | + |
| 106 | +### Error Handling |
| 107 | +- Backend: raise custom exceptions in services, catch in API layer with proper HTTP status codes |
| 108 | +- Frontend: use try/catch in async handlers, show user-friendly messages via notification store |
| 109 | +- Never swallow errors silently — always log or notify |
| 110 | + |
| 111 | +## Commit Guidelines |
| 112 | +1. Backend pre-commit: `cd backend && ruff format . && ruff check .` |
| 113 | +2. Frontend pre-commit: `cd frontend && pnpm format && pnpm lint && pnpm type-check` |
| 114 | +3. Commit messages: Conventional Commits (`feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`) |
| 115 | +4. Branch naming: `feature/xxx`, `fix/xxx`, `refactor/xxx` |
| 116 | +5. Never commit: `.env`, `node_modules/`, `.venv/`, `__pycache__/`, temp files |
0 commit comments