Repository Guidelines

项目结构与模块组织

本仓库是 pnpm monorepo，核心应用只有两个：apps/web 为 Next.js 15 + React 19 前端，apps/api 为 FastAPI 后端。前端页面放在 apps/web/src/app，通用组件放在 apps/web/src/components，状态管理放在 apps/web/src/store，工具函数放在 apps/web/src/lib。后端按分层组织：app/api 路由、app/services 业务编排、app/repositories 数据访问、app/schemas 输入输出模型、app/db 持久化。测试分别位于 apps/web/src/test 和 apps/api/tests，设计与计划文档放在 docs/superpowers/specs、docs/superpowers/plans。

构建、测试与开发命令

先执行 pnpm install 安装工作区依赖。前端本地开发使用 pnpm dev:web，后端本地开发使用 pnpm dev:api。前端测试执行 pnpm test:web，生产构建校验执行 pnpm --filter web build。后端测试执行 pnpm test:api。涉及数据库结构变更时，在 apps/api 目录执行 alembic upgrade head。

编码风格与命名约定

不要顺手重排无关文件，优先延续现有风格。前端使用严格模式 TypeScript、2 空格缩进，并通过 apps/web/tsconfig.json 中的 @/* 别名引用源码。React 组件使用 PascalCase，函数和变量使用 camelCase，文件名保持 kebab-case，例如 use-auth-guard.ts。后端遵循 PEP 8、4 空格缩进、snake_case 模块命名，并尽量补全类型标注。仓库当前没有单独的 lint 脚本，因此提交前至少保证导入顺序、命名和周边文件一致。

测试指南

前端测试基于 Vitest，运行环境是 jsdom，公共初始化文件为 apps/web/src/test/setup.ts。组件测试命名为 *.test.tsx，纯逻辑或状态测试命名为 *.test.ts。后端测试使用 pytest，文件名遵循 test_*.py，例如 test_auth.py、test_messages_service.py。凡是修改行为、接口或状态流转，必须同步新增或更新至少一个自动化测试。

提交与合并请求规范

最近提交历史采用带作用域的 Conventional Commits，例如 feat(web): ...、feat(api): ...，文档和修复也应保持同一格式。每个提交只解决一个明确问题，避免把前后端无关修改混在一起。PR 至少应包含：变更摘要、关联 issue 或设计文档、测试结果；如果涉及界面改动，补充截图或录屏。

安全与配置提示

不要提交 .env 或 apps/web/.env.local 中的密钥、数据库地址和模型提供商凭据。修改认证、跨域、流式响应或 API 地址时，要同时检查前后端配置是否仍然匹配，避免只改一侧导致本地可用、联调失效。