用途:为 Polar 代码库的后端开发提供指导,涵盖 REST API 设计、FastAPI 实现、SQLAlchemy 模式与后端约定;适用于设计新端点、编写 Pydantic 模式、数据库操作、认证授权、遵循编码规范及编写后端测试,不适用于前端、UI/UX 与客户端状态管理。
主要能力:端点结构、命名与 HTTP 方法等 REST 约定;Pydantic 模式创建;服务层业务逻辑与异常处理;仓储层数据库访问与 SQLAlchemy 用法;基于 AuthSubject 与 scope 的认证;测试结构、fixture 与 mock 模式。核心原则包括 REST 一致性、模块化分层、类型安全与关注点分离。
使用方式:命令需在 server/ 目录运行,并先启动 Docker 容器 docker compose up -d。常用命令:uv run task lint、uv run task lint_types、uv run task test、uv run pytest tests/path/to/module/、uv run pytest --cov=polar --cov-report=term-missing、uv run task db_migrate、uv run alembic revision --autogenerate -m "description"、uv run task api、uv run task worker。
REST 约定:版本化基路径 /v1/,资源名复数;使用 GET、POST、PATCH、DELETE;模式统一继承 polar.kit.Schema 或 TimestampedSchema,字段用 snake_case,需附描述与示例;读、建、改模式分离,更新模式字段全部可选以支持部分更新;校验错误返回 422(PolarRequestValidationError)。列表端点支持过滤(可重复查询参数)、分页(page、limit)与排序(sorting,逗号分隔,前缀 - 表示降序),响应含 items 与 pagination(total_count、max_page);创建成功返回 201,更新返回 200,删除返回 204。认证主体包括 User、Organization、Customer,查询资源时需按认证主体过滤以保证访问控制。
限制:技能仅针对 Polar 后端,不适合前端、UI/UX 或客户端状态管理;未提供收费、价格或平台支持等信息。