68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a Rust library called `entity-changes` that provides entity change tracking functionality for MySQL databases using SQLx. The library supports tracking entity modifications with actors, sessions, and change sets, along with procedural macros for automatic derivation of entity tracking capabilities.
|
|
|
|
## Architecture
|
|
|
|
### Workspace Structure
|
|
- **Main library** (`src/`): Core entity change tracking functionality
|
|
- **entity-update_derive** (`entity-update_derive/`): Procedural macro crate for deriving Entity and Update traits
|
|
- **entity-changes-ctl** (`entity-changes-ctl/`): Command-line utility for the library
|
|
|
|
### Core Components
|
|
- **models.rs**: Defines `EntityChange` struct and `Action` enum for tracking entity modifications
|
|
- **repositories.rs**: Database query functions for creating and retrieving entity changes by various criteria (ID, entity, session, actor, change set)
|
|
- **value.rs**: Type-safe value system supporting MySQL types (integers, strings, UUIDs, dates, etc.) with `Value` enum and `Updater` for SQL operations
|
|
- **condition.rs**: Query condition system with `Condition` enum supporting SQL operations (Equal, Like, In, And, Or, etc.)
|
|
- **helpers.rs**: Utility functions and macros for the library
|
|
|
|
### Features
|
|
- `derive`: Enables procedural macro support for Entity and Update traits
|
|
- `static-validation`: Enables static SQLx validation during compilation
|
|
|
|
## Development Commands
|
|
|
|
### Building
|
|
```bash
|
|
cargo build
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
### Building with all features
|
|
```bash
|
|
cargo build --all-features
|
|
```
|
|
|
|
### Working with workspace members
|
|
```bash
|
|
# Build specific workspace member
|
|
cargo build -p entity-update_derive
|
|
cargo build -p entity-changes-ctl
|
|
|
|
# Test specific workspace member
|
|
cargo test -p entity-changes
|
|
```
|
|
|
|
### Releasing
|
|
The project uses a Makefile for tagging releases:
|
|
```bash
|
|
make tag
|
|
```
|
|
This creates a git tag based on the version in Cargo.toml and pushes it to the remote repository.
|
|
|
|
## Important Notes
|
|
|
|
- The library is designed specifically for MySQL databases via SQLx
|
|
- All entity changes include metadata: actor_id, session_id, change_set_id, and timestamps
|
|
- The `new_value` field stores JSON data for tracking actual changes
|
|
- Procedural macros are optional and gated behind the "derive" feature
|
|
- The library uses UUIDs for all entity identifiers
|
|
- Query conditions support both simple field-value pairs and complex nested And/Or logic |