Code Review & Business Intent: Making Code Speak "Human"

If AI is the producer of code in the future, the core role of human developers will inevitably shift to Code Reviewers.

A reviewer's worst nightmare is facing hundreds of lines of string-concatenated SQL queries or messy, nested-loop update logic. Under traditional ORMs, you only see the "implementation details" but struggle to decipher the actual "business intent".

TeaQL returns code from "machine-oriented" to "human-oriented" by providing declarative operational abstractions.

1. Eliminating Glue Code: Aggregation Root Graph Save

Consider a common e-commerce scenario: "A customer cancels an order; we need to update the order status and record an activity log."

Under traditional ActiveRecord or raw SQL patterns, the code might look like this:

// Traditional Review Overhead: Focus is entirely on database transactions and execution order
let mut tx = pool.begin().await?;
let mut order = Order::find(id).fetch_one(&mut tx).await?;
order.status = "CANCELLED";
order.update().execute(&mut tx).await?;

let log = OrderLog { order_id: id, action: "CANCEL", ... };
sqlx::query!("INSERT INTO order_logs ...", log.order_id, log.action)
    .execute(&mut tx).await?;

tx.commit().await?;

Reviewers must spend mental effort checking whether transactions are opened, if foreign keys are correct, and whether the update statement missed any fields.

However, under the TeaQL Domain-Driven Pattern, the same logic is expressed as:

// TeaQL Pattern: Straightforward intent, eliminating database bookkeeping
let mut order = Q::orders().with_id_eq(id).execute_for_single(&ctx).await?;

order.set_status("CANCELLED");
order.logs_mut().push(OrderLog::new_cancel_action());

// A single graph save, automatically compiled into a safe database transaction
order.audit_as("Save operation").save(&ctx).await?;

This significantly frees up the reviewer's cognitive load, letting them understand the business flow at a single glance: "status changed to CANCELLED, accompanied by a log entry, then persisted." Complex transactions, dirty field comparisons, and foreign key mappings are fully managed by the TeaQL runtime.

2. Making Intent Visible: SQL Comment Propagation

Sometimes query logic is highly complex, involving multiple filter conditions. Reviewers looking at long chain calls often wonder: which PRD requirement is this code satisfying?

TeaQL introduces SQL Comment Propagation. The framework allows you to attach business context to your query, ensuring this human-readable description travels throughout the query lifecycle and reaches database slow query logs.

let tasks = Q::tasks()
    // This comment is visible to reviewers and propagates down to the database SQL comments
    .comment("Dashboard: Get high-priority and overdue focus tasks")
    .with_priority_gt(5)
    .with_deadline_lt(Utc::now())
    .with_status_in(vec!["PLANNED", "DOING"])
    .execute_for_list(&ctx).await?;

For reviewers, this .comment(...) makes the code self-documenting. Every data retrieval operation comes with explicit business backing.

3. Anti-Corruption: Offloading Complex Validations to the Core

In complex business systems, hard rules such as "draft tasks cannot have their deadlines modified" are common. Traditionally, these checks are scattered at the beginning of various service methods, making it difficult for reviewers to ensure no check is missed.

TeaQL allows architects to declare anti-corruption guardrails directly at the entity layer using Checkers:

#[async_trait]
impl TypedChecker<Task> for TaskStatusChecker {
    async fn on_before_save(&self, ctx: &UserContext, current: &Task, original: &Task) -> Result<(), CheckerError> {
        if original.status == "DRAFT" && current.deadline != original.deadline {
            return Err(CheckerError::Business("Draft tasks cannot have deadline modifications".into()));
        }
        Ok(())
    }
}

With this underlying guard mechanism, reviewers no longer need to perform meticulous cross-checks on top-level business glue code. The entity layer contains its own defense.

Summary

In the AI coding era, code will be read far more often than it is written. The API design philosophy of TeaQL is built to optimize the human review experience: replacing procedural updates with declarative mutations, and using intent propagation instead of complex documentation, protecting the purity of core business logic.