Fauto/java-g/AI_CONTEXT.md

AI Context: Dynamic Query & Low-Code Engine

1. Project Overview

This project explores two distinct approaches for building a "Low-Code" style backend that supports dynamic field selection, complex filtering, and deep graph traversal without writing boilerplate code.

2. Core Architectures

A. Hibernate/JPA Strategy (Runtime Dynamic)

• Goal: Fully dynamic query construction at runtime.
• Key Components:
  • BaseRepository<T, ID>: Extends JpaRepository & JpaSpecificationExecutor.
  • BaseController<T>: Provides generic /list endpoint.
  • GenericSpecification: Converts Map params to JPA Predicates.
    • Supports exact match (default).
    • Supports LIKE match via wildcard * (e.g., name=John*).
  • Squiggly: Used for dynamic JSON field projection (Graph-trimming) after DB fetch.
• Pros: Zero code generation, extremely flexible, standard JPA ecosystem.
• Cons: "N+1" issues if not careful (Entity Graph needed for optimization), limited by JPA's performance on complex joins.

B. MyBatis XML Generation Strategy (Compile/Runtime Generation)

• Goal: Generate optimized, static-like SQL/XML artifacts for high performance and complex mapping.
• Key Components:
  • MyBatisGeneratorUtils: The core engine.
• Mechanism:
  1. ResultMap Generation:
     • Generates standard <resultMap> for each involved Entity.
     • Uses columnPrefix (e.g., author$, books$) to link nested associations/collections recursively.
     • This allows infinite recursion (Book -> Author -> Book) using the same set of ResultMaps.
  2. SQL Generation:
     • Builds a Join Tree based on requested fields (e.g., ["title", "author.books.title"]).
     • Generates LEFT JOINs automatically.
     • Smart Alias Strategy:
       • Table Alias: Full path (e.g., book$author$books) to avoid collisions.
       • Column Alias: path$ColumnName (e.g., author$books$publish_month).
       • Crucial: The last part of the alias MUST be the DB Column Name (not Java Field Name) to match <result column="..."> during prefix stripping.
  3. One-To-Many Handling:
     • Detects @OneToMany(mappedBy=...) to generate correct ON parent.id = child.parent_id join condition.
     • Forced ID Projection: Automatically selects id columns for all nodes to ensure correct MyBatis collection folding.
• Pros: High performance (single SQL), solves N+1, precise column selection.
• Cons: Requires generation step (or runtime string manipulation), more complex engine logic.

3. Key Files & Locations

• com.example.demo.util.MyBatisGeneratorUtils: The "Brain" of the MyBatis strategy.
• com.example.demo.repository.GenericSpecification: The "Brain" of the JPA strategy.
• com.example.demo.controller.BaseController: The generic entry point.

4. Current Status

• JPA Strategy: Fully functional. Read operations support wildcard search and dynamic projection. Write operations support cascading creation and deep-merge patching.
• MyBatis Strategy: Engine is complete and tested (MyBatisGeneratorUtilsTest). Capable of generating full valid XML with recursive mappings and List support. Integration into Controller is the next logical step.