# AutoCRUD Agent Instructions

You are an AI developer working on the AutoCRUD project, a model-driven automated FastAPI framework with built-in versioning, permissions, and search.

## 🏗 Project Architecture

- **Core Components**:
  - `AutoCRUD` ([autocrud/crud/core.py](autocrud/crud/core.py)): Main entry point. Registers models and applies routes to FastAPI apps.
  - `ResourceManager` ([autocrud/resource_manager/core.py](autocrud/resource_manager/core.py)): Handles business logic including storage, versioning, permissions, and events.
  - `RouteTemplate`: Defines how API endpoints are generated. See [autocrud/crud/route_templates/](autocrud/crud/route_templates/).
  - **Storage**: Abstracted via `IStorage` and `IStorageFactory`.

- **Key Concepts**:
  - **Versioning**: Every resource has a revision history. Status can be `draft` or `stable`. See `RevisionInfo` in [autocrud/types.py](autocrud/types.py).
  - **Permissions**: Integrated RBAC and custom permission checkers (`IPermissionChecker`).
  - **Events**: Lifecycle hooks (`BeforeCreate`, `AfterCreate`, etc.) via `IEventHandler`.

## 🛠 Development Workflow

- **Package Manager**: Use `uv` for dependency management and script execution.
  - **Execute Scripts**: Always use `uv run <script>`.
  - **Install**: `uv sync`.

- **Build & Test**:
  - **Coverage**: `make test`. Maintain at least **86%** code coverage.
  - **Style**: `make style` (runs ruff format & check).

- **Documentation**:
  - Build docs with `make html` (uses Sphinx).

## 📝 Coding Conventions

- **Models**: Use `msgspec.Struct` for data models, NOT Pydantic `BaseModel`.
  ```python
  from msgspec import Struct
  class MyModel(Struct):
      name: str
      age: int
  ```
- **Async/Await**: The core is built on FastAPI and is fully async. Ensure proper `await` usage.
- **Type Hinting**: Extensive use of type hints is required.
- **Language**: 
  - Source code and comments: English.
  - User interactions (if requested via instructions): Taiwan Traditional Chinese (台灣繁體中文).

## 🔍 Specific Patterns

- **Route Generation**: To add a new endpoint type, create a class inheriting from `IRouteTemplate` (or `BaseRouteTemplate`) and register it.
- **Event Handling**: Implement `IEventHandler` and register it with `ResourceManager.add_event_handler`.
- **Search**: Search logic uses `build_query` and supports rich filtering/sorting. See [autocrud/crud/route_templates/search.py](autocrud/crud/route_templates/search.py).
- **Partial Updates**: Handled via `get_partial` in `ResourceManager`.

## 📂 Key File Locations

- `autocrud/crud/core.py`: `AutoCRUD` class.
- `autocrud/resource_manager/core.py`: `ResourceManager` logic.
- `autocrud/types.py`: Core interfaces (`IResourceManager`, `ResourceMeta`, etc.).
- `tests/`: Comprehensive test suite. Check `test_autocrud.py` for integration tests.
