설계: 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>
4.3 KiB
Document Modeling Guide
Design §7–§9. The platform does not own your documents — D-01 is explicit that the domain owns
@Document, repositories, queries, index requirements and schema version. What the platform owns is
the set of modeling decisions that are expensive to reverse once a collection holds production data.
1. There is no CommonMongoRepository
A generic CommonMongoRepository<T, ID> is listed under explicitly unsupported (§3.4), and the
reason is not purity. A shared supertype forces every collection to share an id strategy, a
consistency profile and a query surface, and the first collection that needs a different one either
gets a cast or a leaky generic parameter. Declare a Spring Data repository per aggregate.
2. Embed or reference
MongoDocumentModelManifest records the decision per collection so it is reviewable, and
MongoDocumentModelValidator refuses the combinations that do not survive growth.
| Descriptor | Use when |
|---|---|
EmbeddedCollectionDescriptor |
The child is read with the parent, is bounded, and has no independent lifecycle. Declare maxElements; an unbounded array is the single most common way a document reaches the size limit. |
MongoReferenceDescriptor |
The child is queried independently, is unbounded, or outlives the parent. Declare MongoReferenceLifecycle so the deletion story is written down rather than discovered. |
The validator rejects an embedded collection without a bound, and a reference whose lifecycle says the child is owned by the parent but which is also referenced from elsewhere.
3. Size budget
MongoDocumentSizeBudget:
| Constant | Bytes | Meaning |
|---|---|---|
MONGODB_HARD_LIMIT_BYTES |
16 MiB | MongoDB's own limit. |
PLATFORM_CEILING_BYTES |
4 MiB | The largest budget the platform will accept. |
DEFAULT_BYTES |
2 MiB | MongoDocumentSizeBudget.standard(). |
A budget above the ceiling is refused at construction. Budgeting to 16 MiB means the failing write is the first symptom, and by then the collection is already full of near-limit documents.
4. Identity
DomainDocumentId is written to _id as a BSON string by DomainIdWriteConverter. Any other
representation is the document class's own field type. Pick the representation once per collection:
OBJECT_ID— server-generated, monotonic, 12 bytes. Good default when the domain has no natural id.UUID_BINARY— a domain UUID stored asBinarysubtype 4 (STANDARD). Never store a UUID as a string "because it is easier to read"; it doubles the index size and loses the type.STRING— a natural key that is genuinely a string (a slug, an external system's id).
An _id choice is effectively permanent: it is the shard key candidate, the resume-token join key
and the pagination tie-breaker.
5. Schema version
Every long-lived collection carries DocumentSchemaVersion. MongoSchemaVersionPolicy and
MongoSchemaVersionRange say which versions the running code can read; a document outside the range
raises MongoDataSchemaUnsupportedException rather than being silently mapped with missing fields.
Write the range down before the migration, not after: the range is what lets old and new instances run at once during a rolling deploy.
6. Type metadata
@LongLivedMongoDocument marks a document whose stored type alias must not be a Java class name.
MongoTypeMetadataRegistry maps alias → class. Storing the FQCN means moving or renaming the class
becomes a data migration; storing an alias keeps it a refactor. See
bson-mapping-guide.md §4.
7. Collection profiles
MongoCollectionProfileRegistry binds a CollectionProfileName to its consistency profile, budget
and allowlist. A collection that is not registered cannot be reached through
MongoImperativeExecutor — the allowlist is the mechanism that keeps an
unreviewed collection from appearing in production by accident.
8. What to write down before the first insert
- Embed/reference decision per child collection, with bounds.
- Size budget.
_idrepresentation.- Schema version range.
- Index manifest (see schema-index-migration-guide.md).
- Consistency profile (see consistency-transaction-guide.md).
Each of these is cheap now and a migration later.