fix: 하네스 제거 및 keycloak 문서 보강

raw/errors/sample-portfolio-flyway-out-of-order-2026-06-23.md

@@ -1 +0,0 @@
-../../vault/10-projects/errors/sample-portfolio-flyway-out-of-order-2026-06-23.md

raw/errors/sample-portfolio-flyway-out-of-order-2026-06-23.md

@@ -0,0 +1,60 @@
+---
+title: error / sample-portfolio-flyway-out-of-order-2026-06-23
+source_type: error-note
+status: raw
+branch: feature-build-release-supply-chain-contract
+related_projects: [ca-skeleton]
+tags: [error, flyway, out-of-order, sample-portfolio, migration]
+created: 2026-06-23
+updated: 2026-06-23
+---
+
+# Flyway validation fails with out-of-order migration in SamplePortfolioApplication standalone run
+
+## Parent
+- Parent branch note: [[raw/branch-notes/feature-build-release-supply-chain-contract]]
+
+## Symptoms
+
+When running `SamplePortfolioApplication` standalone after having run `CaSkeletonApplication` on the same database, Flyway validation failed during application boot:
+
+```text
+org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer' defined in class path resource [org/springframework/boot/autoconfigure/flyway/FlywayAutoConfiguration$FlywayConfiguration.class]: Validate failed: Migrations have failed validation
+Detected resolved migration not applied to database: 2.
+To ignore this migration, set -ignoreMigrationPatterns='*:ignored'. To allow executing this migration, set -outOfOrder=true.
+```
+
+## Root Cause
+
+1. The Flyway migrations are split between two locations:
+   - Production migrations: `db/migration/postgresql` contains `V1__idempotency_record.sql`, `V3__outbox_event.sql`, etc. (No `V2`).
+   - Sample migrations: `db/sample-migration` contains `V2__work_log.sql`.
+2. Running the main application (`CaSkeletonApplication`) first applies versions 1, 3, 4 from the production directory. Version 2 is completely skipped because the main app does not scan `db/sample-migration`.
+3. When running `SamplePortfolioApplication` next, it scans both directories. It sees that versions 1, 3, and 4 are already applied to the database, but version 2 (from `db/sample-migration`) is pending.
+4. Because Flyway enforces ordered migration sequences by default, it throws a validation error when it encounters an unapplied lower version (`V2`) after higher versions (`V3`, `V4`) have already been applied.
+
+## Solution
+
+1. **Credentials alignment**: Update the default fallback database/username/password properties in `sample-portfolio`'s `application.yml` from `sample` to `ca_skeleton` so it automatically connects to the same local development database even when run directly from the IDE without environment variables.
+2. **Enable out-of-order migrations**: Set `spring.flyway.out-of-order` to `true` in `sample-portfolio/src/main/resources/application.yml`.
+   ```yaml
+     flyway:
+       baseline-on-migrate: false
+       out-of-order: true
+       clean-disabled: true
+   ```
+
+This tells Flyway to apply `V2` (out of order) on top of the already migrated schema, allowing the sample application to boot cleanly and share the database with the main app.
+
+## Verification & Outcomes
+
+1. Updated `application.yml` in the `sample-portfolio` module.
+2. Ran `./gradlew :sample-portfolio:bootRun` (and IDE Run configuration).
+3. 기동 검증: Flyway가 `V2` 마이그레이션을 out-of-order 모드로 정상 적용하며 애플리케이션이 완벽히 기동되었습니다.
+   ```text
+   o.f.core.internal.command.DbMigrate      : outOfOrder mode is active. Migration of schema "public" may not be reproducible.
+   o.f.core.internal.command.DbMigrate      : Migrating schema "public" to version "2 - work log" [out of order]
+   o.f.core.internal.command.DbMigrate      : Successfully applied 1 migration to schema "public", now at version v2 (execution time 00:00.046s)
+   ...
+   d.c.s.p.SamplePortfolioApplication       : Started SamplePortfolioApplication in 4.462 seconds
+   ```