# Repository Guidelines

## 项目结构与模块组织
- `wolai-frontend/`：主前端（Next.js），源码在 `wolai-frontend/src/`，静态资源在 `wolai-frontend/public/`。
- `wolai-backend/`：后端（FastAPI + Celery），源码在 `wolai-backend/app/`。
- `services/`：配套服务与集成点（如 `services/mineru/` OCR、RAG 相关服务等）。
- `supabase/`：本地 Supabase 迁移与配置（参考 `supabase.md` 的本地端口说明）。
- `pw-tests/`：端到端测试（Playwright + Python），脚本在 `pw-tests/scripts/`，产物在 `pw-tests/artifacts/`。
- 根目录 `src/`：Next.js 相关代码与共享模块（如 `src/app/`、`src/components/` 等）。

## 构建、测试与本地开发命令
- 一键热启动（推荐）：在仓库根目录执行 `npm run desktop:hot`（启动 `wolai-frontend` + `wolai-backend`；Redis 可用时自动启动 Celery）。
- 前端：`cd wolai-frontend && pnpm dev|build|start`；质量检查：`pnpm lint`；单测：`pnpm test`。
- 后端：`cd wolai-backend && pip install -r requirements.txt`；运行：`uvicorn app.main:app --reload --port 8000`；Worker：`celery -A app.workers.celery_app worker --loglevel=info`。
- E2E：`cd pw-tests/scripts && python e2e_mindmap_sync.py`（更多脚本见 `pw-tests/README.md`）。

## 编码风格与命名约定
- 文件编码：统一使用 UTF-8；缩进建议：TS/TSX 2 空格，Python 4 空格。
- 命名示例：组件 `PascalCase.tsx`，hooks `useXxx.ts`，测试文件 `*.test.ts(x)`（Vitest 配置包含 `src/**/*.test.ts(x)`）。
- 优先遵循现有 ESLint/Vitest 配置（见 `eslint.config.mjs`、`vitest.config.ts`）。

## 提交与 Pull Request 规范
- 提交信息在历史中常见两类：版本号摘要（如 `0.1.13 ...`）与类 Conventional Commits（如 `feat(mindmap): ...` / `fix(mindmap): ...` / `chore: ...`）。新增提交建议延续该风格。
- PR 需要：变更说明（动机/影响范围）、必要的 UI 截图、可复现步骤或测试结果、关联的 issue/任务链接。

## 安全与配置提示
- 不要提交密钥/Token/账号；本地配置优先放在 `.env.local`、`wolai-frontend/.env.local`、`wolai-backend/.env`。
- 如发现敏感信息已进入仓库，请立即轮换密钥，并与维护者确认是否需要清理历史记录。

## Agent/自动化协作注意
- 仅修改与目标相关的文件；不要擅自回滚、覆盖或丢弃他人改动；代码注释使用简体中文并保持 UTF-8。

## 代码索引
- 更细的前后端代码层级索引见 `CODE_INDEX.md`（按路由/API/模块/职责整理，便于后续快速定位与开发）。