feat: implement Phase 2 & Phase 3 roadmap features + update docs

[aupv9]

Tổng quan

Implement toàn bộ Phase 2 (v2.0) và Phase 3 (v3.0) theo roadmap đã được approve. 49 files changed, 3.3k+ insertions.

---

Phase 2 — v2.0

2.1 @ShardBy AOP (sharding-aop — module mới)

• ShardByAspect intercept methods annotated @ShardBy, tự động set/clear ShardContext
• 3 extraction modes: first-long-param, named-param (@ShardBy("accountId")), entity-field (fromEntity=true)
• Chạy ở HIGHEST_PRECEDENCE + 10 — trước @Transactional
• ShardingAopAutoConfiguration (@ConditionalOnClass(Aspect.class))
• Fix @ShardBy: xóa ElementType.PARAMETER (incompatible với Spring AOP CGLIB proxies)

2.2 Micrometer Metrics (sharding-metrics — module mới)

• MeteredShardRouter: counter sharding.routing.count{shard, strategy} + timer sharding.routing.latency
• MeteredShardJdbcTemplate: timer sharding.query.latency{shard, operation} + counter sharding.errors{shard, exception}
• ShardActuatorMetrics: MeterBinder gauge sharding.shard.count
• HikariCP pool metrics tự động qua setMetricRegistry()
• ShardingMetricsAutoConfiguration (@ConditionalOnBean(MeterRegistry.class))
• ShardJdbcTemplate.executeWithShardKey: private → protected

2.3 Read/Write Splitting (sharding-readwrite — module mới)

• ReadWriteRoutingDataSource: route đến replica khi @Transactional(readOnly=true) hoặc ShardContext.isReadOnly(); round-robin load balance
• ReplicaAwareShardContextTaskDecorator: propagate readOnly flag sang @Async threads
• ShardContext: thêm READ_ONLY ThreadLocal (backward-compatible)
• Shard record: thêm readReplicaDataSources + factory Shard.withReplicas()
• ShardingReadWriteAutoConfiguration (sharding.read-write-splitting.enabled=true)

2.4 Dynamic Shard Management

• ConsistentHashShardRouter: List<Shard> → AtomicReference + ReentrantReadWriteLock; incremental ring mutation
• ShardRouter interface: thêm default addShard(Shard) / removeShard(int)
• ShardManagementService: runtime add/remove/list/override với HikariCP lifecycle
• ShardManagementEndpoint: Actuator /actuator/shards (GET/POST/DELETE)
• ShardingManagementAutoConfiguration (sharding.management.enabled=true)

---

Phase 3 — v3.0

3.1 Cross-Shard Query Optimization (sharding-jdbc mở rộng)

• queryShards(List<Integer> shardIndices, ...): shard affinity — query subset thay vì tất cả shards
• queryAllShardsPaged(sql, rowMapper, comparator, pageSize, pageNumber, args): LIMIT push-down xuống từng shard, merge + sort + paginate

3.2 Online Shard Migration (sharding-migration — module mới)

• State machine: PENDING → DOUBLE_WRITING → BACKFILLING → READY_TO_CUTOVER → COMPLETED/ROLLED_BACK
• ShardMigrationService: start, runBackfill (batched upsert), cutover (add router overrides), rollback
• ShardMigrationAspect: double-write interceptor cho @ShardBy-annotated write methods
• ShardMigrationProgressTracker: thread-safe rows copied + progress %
• ShardMigrationActuatorEndpoint: /actuator/shard-migration
• ShardingMigrationAutoConfiguration (sharding.migration.enabled=true)

3.3 CDC Integration (sharding-cdc — module mới)

• ShardChangeEvent record + ShardChangeEventListener interface
• DebeziumShardChangeProducer: embedded Debezium → ShardChangeEvent
• KafkaShardChangeProducer: Kafka consumer (Debezium Kafka Connect topics) → ShardChangeEvent
• ShardMigrationConsistencyChecker: phát hiện double-write gaps
• ShardCacheInvalidator: base class cho cache eviction on write events
• ShardingCdcAutoConfiguration (sharding.cdc.enabled=true)

---

Docs

• README rewrite: coverage đầy đủ cho tất cả features, config reference, code examples
• CHANGELOG: thêm entries v2.0.0 và v3.0.0

---

Build changes

• root pom.xml: 5 modules mới
• sharding-autoconfigure/pom.xml: optional deps cho tất cả feature modules
• sharding-spring-boot-starter/pom.xml: optional deps
• AutoConfiguration.imports: 6 entries mới

Test plan

• mvn test -pl sharding-core — unit tests cho ConsistentHashShardRouter (mutable), ShardContext (READ_ONLY flag), Shard record
• mvn test -pl sharding-aop — ShardByAspect integration tests (3 extraction modes, @transactional ordering)
• mvn test -pl sharding-metrics — MeteredShardRouter, SimpleMeterRegistry assertions
• mvn test -pl sharding-readwrite — ReadWriteRoutingDataSource routing logic
• mvn test -pl sharding-migration — ShardMigrationService state transitions
• mvn test -pl example-app — Testcontainers integration tests (existing suite)