refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환

설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent 208077fddf
commit 6d27356e2b
2822 changed files with 27992 additions and 166879 deletions
+8 -15
View File
@@ -1,6 +1,5 @@
plugins {
id 'ca.java-library'
id 'ca.strict-qualification'
}
// Skeleton-wide operational contracts only. No business/domain concepts.
@@ -8,18 +7,12 @@ plugins {
dependencies {
}
def messagingSharedSchemaQualification = extensions.getByName('strictQualification').register(
'messagingSharedSchemaQualificationTest',
sourceSets.test,
[
'dev.caskeleton.shared.contract.messaging.MessagingEnvelopeSchemaResourceTest'
],
rootProject.layout.buildDirectory.dir(
'test-results/messaging-evidence/shared'),
rootProject.layout.buildDirectory.dir(
'test-results/messaging-evidence-binary/shared'),
'Runs exact Messaging shared schema qualification tests.'
)
messagingSharedSchemaQualification.configure {
dependsOn ':prepareMessagingContractEvidence'
// Half of the root `verifyMessagingContracts`: the shared envelope schema, run by name, no skips.
strictTestLanes {
lane('messagingSharedSchemaQualificationTest') {
description = 'Runs exact Messaging shared schema qualification tests.'
requires 'dev.caskeleton.shared.contract.messaging.MessagingEnvelopeSchemaResourceTest'
rejectSkipped = true
jvmArgs '-Duser.timezone=UTC'
}
}
@@ -1,102 +0,0 @@
package dev.caskeleton.shared.activation;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
/**
* The runtime capabilities this skeleton ships behind an explicit switch, and the names that
* address them.
*
* <p>One place knows the names. Spread across conditions as string literals, a rename becomes a
* silent activation change: the condition stops matching, the adapter stops assembling, and nothing
* reports it.
*
* <p>The superseded names sit in a static map rather than in an instance field, because Error
* Prone's {@code ImmutableEnumChecker} rejects a collection-typed field on an enum and this
* repository compiles with {@code -Werror}. The two scalar names stay as fields, since a String is
* already immutable.
*/
public enum MasterSwitch {
/** Relational persistence: entity scan, repositories, pool, migration. */
PERSISTENCE_JPA("ca-skeleton.persistence-jpa.enabled", "APP_PERSISTENCE_JPA_ENABLED"),
/** MongoDB persistence. */
PERSISTENCE_MONGO("ca-skeleton.persistence-mongo.enabled", "APP_PERSISTENCE_MONGO_ENABLED"),
/** Broker publication and consumption. */
MESSAGING("app.messaging.enabled", "APP_MESSAGING_ENABLED"),
/** The notification delivery platform. */
NOTIFICATION_PLATFORM(
"ca-skeleton.notification.platform.enabled", "APP_NOTIFICATION_PLATFORM_ENABLED"),
/** The GraphQL transport boundary. */
GRAPHQL("backend.graphql.enabled", "APP_GRAPHQL_ENABLED"),
/** The shared Redis runtime substrate. */
REDIS("app.redis.enabled", "APP_REDIS_ENABLED"),
/** The explicit Fileserver R2 publication capability. */
FILESERVER("app.fileserver.enabled", "APP_FILESERVER_ENABLED"),
/** The HTTP upload/download Fileserver platform. */
FILESERVER_PLATFORM("app.fileserver-platform.enabled", "APP_FILESERVER_PLATFORM_ENABLED"),
/** The outbound HTTP client platform. */
HTTPCLIENT("app.httpclient.enabled", "APP_HTTPCLIENT_ENABLED");
private static final Map<MasterSwitch, List<String>> SUPERSEDED = supersededProperties();
private final String property;
private final String environmentVariable;
MasterSwitch(String property, String environmentVariable) {
this.property = property;
this.environmentVariable = environmentVariable;
}
private static Map<MasterSwitch, List<String>> supersededProperties() {
Map<MasterSwitch, List<String>> superseded = new EnumMap<>(MasterSwitch.class);
// Gated only add-on beans while reading as a whole-adapter switch, and defaulted to on.
superseded.put(PERSISTENCE_JPA, List.of("app.jpa-platform.enabled"));
superseded.put(PERSISTENCE_MONGO, List.of());
superseded.put(MESSAGING, List.of());
// Deliberately empty. The notification provider selectors and the two GraphQL safety flags are
// often described as "legacy activation", and they are not alternative spellings of these
// switches — they are subordinate settings that stay meaningful while the adapter is on.
// Listing
// them here made every shipped configuration ambiguous, because a provider selector is present
// in the default configuration and would collide with a master switch that is legitimately set.
// Their own migrations are keyed to the settings that replace them: the provider selectors to
// the
// delivery-platform runtime, and backend.graphql.production / .environment to
// backend.graphql.deployment-mode.
superseded.put(NOTIFICATION_PLATFORM, List.of());
superseded.put(GRAPHQL, List.of());
superseded.put(REDIS, List.of());
superseded.put(FILESERVER, List.of());
superseded.put(FILESERVER_PLATFORM, List.of());
superseded.put(HTTPCLIENT, List.of());
return Map.copyOf(superseded);
}
/**
* Returns the canonical Spring property name.
*
* @return the property this switch is read from
*/
public String property() {
return property;
}
/**
* Returns the canonical environment variable name.
*
* @return the operator-facing environment variable
*/
public String environmentVariable() {
return environmentVariable;
}
/**
* Returns property names this switch supersedes, which are now migration errors.
*
* @return superseded property names, possibly empty
*/
public List<String> legacyProperties() {
return SUPERSEDED.get(this);
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.shared.activation;
/**
* The outcome of reading one master switch. Only {@link Off} and {@link On} may start a context.
*/
public sealed interface MasterSwitchParseResult {
/**
* The switch this result describes.
*
* @return the owning switch
*/
MasterSwitch owner();
/**
* The switch is off, either explicitly or because nobody set it.
*
* @param owner the switch that is off
*/
record Off(MasterSwitch owner) implements MasterSwitchParseResult {}
/**
* The switch is on.
*
* @param owner the switch that is on
*/
record On(MasterSwitch owner) implements MasterSwitchParseResult {}
/**
* The value is neither {@code true} nor {@code false}.
*
* @param owner the switch that was misconfigured
* @param raw the rejected raw value
*/
record Invalid(MasterSwitch owner, String raw) implements MasterSwitchParseResult {}
/**
* Canonical and legacy keys are both set.
*
* @param owner the switch addressed by both keys
* @param legacyProperty the superseded key that is also present
*/
record Ambiguous(MasterSwitch owner, String legacyProperty) implements MasterSwitchParseResult {}
/**
* Only a superseded key is set.
*
* @param owner the switch the legacy key used to address
* @param legacyProperty the superseded key that is present
* @param replacementProperty the canonical key to use instead
*/
record LegacyOnly(MasterSwitch owner, String legacyProperty, String replacementProperty)
implements MasterSwitchParseResult {}
}
@@ -1,51 +0,0 @@
package dev.caskeleton.shared.activation;
import java.util.Locale;
import java.util.Map;
/**
* Reads one master switch, strictly.
*
* <p>No Spring types, so the rule is testable without a context — and usable by the environment
* post-processor, which has to run before there is one.
*
* <p>The strictness is the design. {@code yes} read as true turns something on by accident; {@code
* yes} read as false is a deployment that believes it turned something on and did not. Rejecting
* the value is the only answer that cannot be wrong in a way nobody notices.
*/
public final class MasterSwitchParser {
private MasterSwitchParser() {}
/**
* Parses a switch from its canonical raw value and whatever legacy keys are present.
*
* @param owner the switch being read
* @param canonicalRaw the raw canonical value, or null when unset
* @param legacyRaw legacy property names to their raw values; only present keys belong here
* @return the parse outcome
*/
public static MasterSwitchParseResult parse(
MasterSwitch owner, String canonicalRaw, Map<String, String> legacyRaw) {
String legacyPresent =
owner.legacyProperties().stream().filter(legacyRaw::containsKey).findFirst().orElse(null);
if (canonicalRaw != null && legacyPresent != null) {
return new MasterSwitchParseResult.Ambiguous(owner, legacyPresent);
}
if (canonicalRaw == null && legacyPresent != null) {
return new MasterSwitchParseResult.LegacyOnly(owner, legacyPresent, owner.property());
}
if (canonicalRaw == null) {
return new MasterSwitchParseResult.Off(owner);
}
String normalized = canonicalRaw.toLowerCase(Locale.ROOT);
if ("true".equals(normalized)) {
return new MasterSwitchParseResult.On(owner);
}
if ("false".equals(normalized)) {
return new MasterSwitchParseResult.Off(owner);
}
return new MasterSwitchParseResult.Invalid(owner, canonicalRaw);
}
}
@@ -1,86 +0,0 @@
package dev.caskeleton.shared.activation;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* A master switch is the one value an operator must be able to trust absolutely.
*
* <p>Every rule here exists because the permissive alternative fails silently. {@code yes} parsed
* as true is a deployment that turned something on by accident; {@code yes} parsed as false is a
* deployment that thought it turned something on and did not. Rejecting it is the only answer that
* cannot be wrong in a way nobody notices.
*/
class MasterSwitchParserTest {
@Test
@DisplayName("an unset switch is off")
void unsetIsOff() {
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, null, Map.of()))
.isInstanceOf(MasterSwitchParseResult.Off.class);
}
@Test
@DisplayName("true and false parse case-insensitively")
void booleansParse() {
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, "TRUE", Map.of()))
.isInstanceOf(MasterSwitchParseResult.On.class);
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, "False", Map.of()))
.isInstanceOf(MasterSwitchParseResult.Off.class);
}
@Test
@DisplayName("yes, 1, on, blank, and whitespace are configuration errors rather than off")
void truthyLookalikesAreRejected() {
for (String raw : new String[] {"yes", "1", "on", "", " ", "true ", " false", "ture"}) {
assertThat(MasterSwitchParser.parse(MasterSwitch.MESSAGING, raw, Map.of()))
.as("%s must be rejected; a silent off here is a deployment that thinks it is on", raw)
.isInstanceOf(MasterSwitchParseResult.Invalid.class);
}
}
@Test
@DisplayName("canonical and legacy together are ambiguous even when they agree")
void agreeingDuplicatesAreStillAmbiguous() {
MasterSwitchParseResult result =
MasterSwitchParser.parse(
MasterSwitch.PERSISTENCE_JPA, "true", Map.of("app.jpa-platform.enabled", "true"));
assertThat(result)
.as(
"two keys that agree today diverge the first time somebody edits one of them; the "
+ "ambiguity is the defect, not the disagreement")
.isInstanceOf(MasterSwitchParseResult.Ambiguous.class);
}
@Test
@DisplayName("a legacy key alone names its replacement")
void legacyAloneNamesTheReplacement() {
MasterSwitchParseResult result =
MasterSwitchParser.parse(
MasterSwitch.PERSISTENCE_JPA, null, Map.of("app.jpa-platform.enabled", "true"));
assertThat(result).isInstanceOf(MasterSwitchParseResult.LegacyOnly.class);
assertThat(((MasterSwitchParseResult.LegacyOnly) result).replacementProperty())
.isEqualTo("ca-skeleton.persistence-jpa.enabled");
}
@Test
@DisplayName("every switch has one unique operator-facing APP_* environment name")
void environmentNamesAreCanonical() {
var names =
java.util.Arrays.stream(MasterSwitch.values())
.map(MasterSwitch::environmentVariable)
.toList();
assertThat(names)
.allSatisfy(
name -> {
assertThat(name).startsWith("APP_").endsWith("_ENABLED");
assertThat(name).doesNotContain(".");
})
.doesNotHaveDuplicates();
assertThat(MasterSwitch.GRAPHQL.environmentVariable()).isEqualTo("APP_GRAPHQL_ENABLED");
}
}