refactor!: 확인 리뷰 수정과 저장소 구조·문서 체계 정리를 합친다 #2
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Agent"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -57,20 +57,10 @@ jobs:
|
||||
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
|
||||
- name: Verify Compose profile contracts render exactly as declared
|
||||
run: bash scripts/verify-compose-profile-contracts.sh
|
||||
|
||||
sample-portfolio:
|
||||
# The sample is excluded from production architecture/runtime membership policy, but it is still
|
||||
# the reference implementation adopters copy. Compile/test/OpenAPI drift must therefore block PRs.
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
# `qualityCheck` too: the root one covers the production leaves only, so the sample — the code
|
||||
# adopters copy first — was analysed by no stage, and its SpotBugs exclusions matched nothing
|
||||
# (review 2026-11-03 RR-06-05).
|
||||
- name: Verify the standalone sample application
|
||||
working-directory: src
|
||||
run: ./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --stacktrace
|
||||
# The repository root and src/ hold only the entries on the allow list (owner decision
|
||||
# 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit.
|
||||
- name: Refuse a top-level folder outside the allow list
|
||||
run: python3 scripts/check-repo-layout.py
|
||||
|
||||
optional-platforms:
|
||||
runs-on: ubuntu-latest
|
||||
@@ -79,15 +69,15 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Verify the optional gRPC platform build
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms ci --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build ci --stacktrace
|
||||
# The optional build's own lane-reachability check: the main build's cannot see these lanes
|
||||
# (review 2026-11-03 RR-06-03).
|
||||
- name: Require every optional-platform strict lane to be in an executed stage
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --stacktrace
|
||||
|
||||
# gRPC schema policy (owner decision 18). protoc compiles src/grpc/grpc-contract inside the
|
||||
# optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
|
||||
# gRPC schema policy (owner decision 18). protoc compiles src/platforms/grpc/grpc-contract inside
|
||||
# the optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
|
||||
# buf.yaml next to the schema. Buf is a native binary rather than a Maven artifact, so it runs here
|
||||
# and not inside Gradle — and nothing in the repository re-implements its rules.
|
||||
grpc-proto-buf:
|
||||
@@ -102,28 +92,38 @@ jobs:
|
||||
version: 1.73.0
|
||||
setup_only: true
|
||||
- name: Lint the gRPC schema
|
||||
working-directory: src/grpc/grpc-contract
|
||||
working-directory: src/platforms/grpc/grpc-contract
|
||||
run: buf lint
|
||||
- name: Refuse a breaking change to the gRPC schema
|
||||
working-directory: src/grpc/grpc-contract
|
||||
working-directory: src/platforms/grpc/grpc-contract
|
||||
env:
|
||||
# Pull request: the target branch. Push: the commit this push replaced.
|
||||
BASELINE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
baseline_commit="$(git rev-parse --verify --quiet "${BASELINE}^{commit}" || true)"
|
||||
if [[ -z "${baseline_commit}" ]] \
|
||||
|| ! git cat-file -e "${baseline_commit}:src/grpc/grpc-contract/buf.yaml" 2>/dev/null; then
|
||||
# The module moved from src/grpc to src/platforms/grpc on 2026-11-07. A baseline from
|
||||
# before the move holds it at the old path, and comparing against that path keeps the
|
||||
# breaking check running across the move instead of skipping it once.
|
||||
baseline_dir=""
|
||||
if [[ -n "${baseline_commit}" ]]; then
|
||||
for candidate in src/platforms/grpc/grpc-contract src/grpc/grpc-contract; do
|
||||
if git cat-file -e "${baseline_commit}:${candidate}/buf.yaml" 2>/dev/null; then
|
||||
baseline_dir="${candidate}"
|
||||
break
|
||||
fi
|
||||
done
|
||||
fi
|
||||
if [[ -z "${baseline_dir}" ]]; then
|
||||
# The first change that introduces the module has nothing to be compatible with.
|
||||
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no src/grpc/grpc-contract/buf.yaml; breaking check skipped."
|
||||
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no grpc-contract/buf.yaml; breaking check skipped."
|
||||
exit 0
|
||||
fi
|
||||
buf breaking --against "../../../.git#ref=${baseline_commit},subdir=src/grpc/grpc-contract"
|
||||
buf breaking --against "../../../../.git#ref=${baseline_commit},subdir=${baseline_dir}"
|
||||
|
||||
release-gate:
|
||||
needs:
|
||||
- quality-gates
|
||||
- sample-portfolio
|
||||
- optional-platforms
|
||||
- grpc-proto-buf
|
||||
if: always()
|
||||
@@ -134,14 +134,12 @@ jobs:
|
||||
- name: Require every current blocking job to succeed
|
||||
env:
|
||||
QUALITY_RESULT: ${{ needs.quality-gates.result }}
|
||||
SAMPLE_RESULT: ${{ needs.sample-portfolio.result }}
|
||||
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
|
||||
GRPC_PROTO_BUF_RESULT: ${{ needs.grpc-proto-buf.result }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
for result in \
|
||||
"${QUALITY_RESULT}" \
|
||||
"${SAMPLE_RESULT}" \
|
||||
"${OPTIONAL_PLATFORMS_RESULT}" \
|
||||
"${GRPC_PROTO_BUF_RESULT}"; do
|
||||
if [[ "${result}" != "success" ]]; then
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
name: docs-check
|
||||
|
||||
# Document language, record head blocks, references and copied numbers (scripts/check-docs.py).
|
||||
# It runs on every pull request, not on a docs/** path filter: deleting a file or a Gradle project
|
||||
# in code is exactly what makes a living document point at nothing, and that change touches no
|
||||
# document. The checker is plain Python outside Gradle, because the build does not parse documents.
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: ["main"]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
docs:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- name: Test the document checker
|
||||
run: python3 -m unittest discover -s scripts/tests
|
||||
- name: Check documents
|
||||
run: python3 scripts/check-docs.py
|
||||
@@ -26,7 +26,7 @@ jobs:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Start the NFSv4 certification environment
|
||||
run: docker compose -f infra/fileserver/nfs/compose.yml up -d --wait
|
||||
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
|
||||
- name: Run the network-filesystem ambiguity suite
|
||||
working-directory: src
|
||||
run: >-
|
||||
@@ -35,7 +35,7 @@ jobs:
|
||||
--stacktrace
|
||||
- name: Tear down the NFS environment
|
||||
if: always()
|
||||
run: docker compose -f infra/fileserver/nfs/compose.yml down -v
|
||||
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v
|
||||
|
||||
fileserver-process-kill-matrix:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
@@ -24,10 +24,8 @@ on:
|
||||
- 'src/.env'
|
||||
- 'docs/registries/env-keys.yaml'
|
||||
- 'src/Dockerfile'
|
||||
- 'docker-compose.yml'
|
||||
- 'infra/fileserver/nginx/**'
|
||||
- 'infra/fileserver/kubernetes/**'
|
||||
- 'infra/fileserver/nfs/**'
|
||||
- 'compose.yaml'
|
||||
- 'src/app-bootstrap/compose-lanes/fileserver.yaml'
|
||||
- '.github/workflows/fileserver-pr.yml'
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
# it changes what this gate runs.
|
||||
|
||||
@@ -60,7 +60,7 @@ concurrency:
|
||||
|
||||
jobs:
|
||||
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
|
||||
# qualification, the sample web contract, the public-path baseline, the conditional transport
|
||||
# qualification, the public-path baseline, the conditional transport
|
||||
# lanes, the messaging contract lanes and each leaf's document-contract lanes. API surfaces are
|
||||
# in the pull-request `check` (owner decision 20). The rest left the pull-request gate (review
|
||||
# 2026-09-24 BUILD, item 12); none of them is deleted.
|
||||
@@ -189,13 +189,12 @@ jobs:
|
||||
# never catches. This job replaced `web-load-abuse-and-shutdown`, which despite its name ran
|
||||
# `:adapter:inbound:web:test` and `webJettyCompatTest` — two lanes the pull-request and main stages
|
||||
# already run — and never the load lanes (review 2026-11-01 08-01), and `httpclient-performance`.
|
||||
# No assertions switch: the strict-lane convention asserts every performance lane's bounds, so this
|
||||
# job and a person on a workstation run the same command and get the same bounds.
|
||||
performance-check:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 120
|
||||
env:
|
||||
# A project property rather than a command-line flag, so the run command stays a plain,
|
||||
# verifiable task invocation while the machine-dependent bounds are still asserted.
|
||||
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
@@ -208,7 +207,7 @@ jobs:
|
||||
- name: Run every optional-platform performance-category strict lane
|
||||
if: always()
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms performanceCheck --continue --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build performanceCheck --continue --stacktrace
|
||||
- name: Publish the performance lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
@@ -235,7 +234,7 @@ jobs:
|
||||
# `grpc-operation-ledger-jpa:integrationTest`, which certifies the atomic
|
||||
# `INSERT ... ON CONFLICT DO NOTHING` claim that durable mutation idempotency rests on against a
|
||||
# real PostgreSQL. It was registered in Gradle, listed in `strictTestLanes`, and invoked by
|
||||
# nothing: `-p optional-platforms ci` reaches `checkAll`, `qualityCheck` and the dependency
|
||||
# nothing: `-p platforms/optional-build ci` reaches `checkAll`, `qualityCheck` and the dependency
|
||||
# verifier, none of which runs a lane whose category is INTEGRATION, and release.yml's gRPC gate
|
||||
# names only the three grpc-testkit lanes.
|
||||
#
|
||||
@@ -251,13 +250,13 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Certify the gRPC operation ledger against real PostgreSQL
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
|
||||
- name: Publish the optional-platform lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: grpc-optional-platform-integration-reports
|
||||
path: src/optional-platforms/**/build/reports/tests/
|
||||
path: src/platforms/grpc*/**/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on
|
||||
@@ -273,7 +272,7 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- name: Run every blocking Compose runtime lane
|
||||
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
|
||||
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
|
||||
- name: Publish sanitized runtime-smoke evidence
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
|
||||
@@ -15,7 +15,7 @@ name: messaging-certification
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "src/messaging/**"
|
||||
- "src/platforms/messaging/**"
|
||||
- ".github/workflows/messaging-certification.yml"
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
# it changes what this gate runs.
|
||||
@@ -47,5 +47,5 @@ jobs:
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: messaging-broker-certification-evidence
|
||||
path: src/messaging/messaging-kafka/build/messaging-certification/
|
||||
path: src/platforms/messaging/messaging-kafka/build/messaging-certification/
|
||||
if-no-files-found: warn
|
||||
|
||||
@@ -30,7 +30,7 @@ on:
|
||||
- 'src/config/architecture/modules.json'
|
||||
- 'src/.env'
|
||||
- 'docs/notification/**'
|
||||
- 'infra/notification/**'
|
||||
- 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh'
|
||||
- '.github/workflows/notification-platform.yml'
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
# it changes what this gate runs.
|
||||
|
||||
@@ -123,7 +123,6 @@ jobs:
|
||||
'^src/config/architecture/modules\.json$' \
|
||||
'^docs/jpa/' \
|
||||
'^docs/adr/ADR-JPA-' \
|
||||
'^infra/jpa/' \
|
||||
"${common}"
|
||||
|
||||
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Redis SDK topology evidence.
|
||||
#
|
||||
# The lanes in infra/redis-sdk answer what the deterministic in-memory gateway cannot — Sentinel
|
||||
# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel
|
||||
# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which
|
||||
# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not
|
||||
# name the test class behind it.
|
||||
@@ -34,7 +34,7 @@ on:
|
||||
- "src/adapter/outbound/redis-runtime/**"
|
||||
- "src/adapter/outbound/redis-sdk/**"
|
||||
- "src/adapter/outbound/cache-redis/**"
|
||||
- "infra/redis-sdk/**"
|
||||
- "compose/redis/**"
|
||||
- ".github/workflows/redis-sdk-topology.yml"
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
# it changes what this gate runs.
|
||||
@@ -122,7 +122,7 @@ jobs:
|
||||
- name: Start the topology
|
||||
env:
|
||||
REDIS_VERSION: ${{ matrix.redis_version }}
|
||||
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" up -d --wait
|
||||
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait
|
||||
- name: Record the image digest
|
||||
id: image
|
||||
run: |
|
||||
@@ -161,7 +161,7 @@ jobs:
|
||||
# however loudly the file is named "test".
|
||||
tls)
|
||||
port=6390
|
||||
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
|
||||
docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
|
||||
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
|
||||
tasks="$runtime"
|
||||
;;
|
||||
@@ -199,4 +199,4 @@ jobs:
|
||||
retention-days: 90
|
||||
- name: Stop the topology
|
||||
if: always()
|
||||
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" down -v
|
||||
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" down -v
|
||||
|
||||
@@ -132,7 +132,7 @@ jobs:
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the gRPC Stable certification lanes
|
||||
working-directory: src
|
||||
run: ./gradlew -p optional-platforms releaseCheck --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build releaseCheck --stacktrace
|
||||
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
|
||||
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
|
||||
# Docker, which a release runner has (review 2026-11-01 03-12).
|
||||
@@ -140,15 +140,15 @@ jobs:
|
||||
working-directory: src
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
|
||||
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
|
||||
- name: Publish the gRPC release evidence
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: grpc-release-evidence
|
||||
path: |
|
||||
src/grpc/grpc-testkit/build/reports/tests/
|
||||
src/grpc/grpc-operation-ledger-jpa/build/reports/tests/
|
||||
src/platforms/grpc/grpc-testkit/build/reports/tests/
|
||||
src/platforms/grpc/grpc-operation-ledger-jpa/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
|
||||
@@ -160,10 +160,6 @@ jobs:
|
||||
defaults:
|
||||
run:
|
||||
working-directory: src
|
||||
env:
|
||||
# A project property rather than a command-line flag, so each run command stays a plain,
|
||||
# verifiable task invocation while the machine-dependent bounds are still asserted.
|
||||
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
@@ -198,7 +194,7 @@ jobs:
|
||||
# docs/jpa/support-matrix.md recorded all three as covered. start() now fails closed on a
|
||||
# multi-version selection, so this matrix is the only way the Stable majors get covered.
|
||||
#
|
||||
# config/jpa/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
|
||||
# persistence-jpa release/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
|
||||
# build.gradle) depends on its blocking gates, so a gate naming a missing task fails when the task
|
||||
# graph is built, and JpaReleaseRenderingTest holds this matrix and the promotion list below to the
|
||||
# registry's Stable majors. Editing one without the other fails the persistence-jpa unit lane.
|
||||
@@ -330,27 +326,6 @@ jobs:
|
||||
:composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
|
||||
--stacktrace
|
||||
|
||||
fileserver-pvc-certification:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
|
||||
# cluster result comes from an operator running infra/fileserver/kubernetes/
|
||||
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
|
||||
# where the absence of a cluster result is stated rather than hidden behind a green check.
|
||||
- name: Check the certification manifest still says what the claim depends on
|
||||
run: |
|
||||
set -euo pipefail
|
||||
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
|
||||
test -f "$manifest"
|
||||
grep -q 'kind: PersistentVolumeClaim' "$manifest"
|
||||
grep -q 'kind: Job' "$manifest"
|
||||
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
|
||||
# mode would certify a topology the support matrix says is uncertified.
|
||||
grep -q 'ReadWriteOnce' "$manifest"
|
||||
! grep -q 'ReadWriteMany' "$manifest"
|
||||
|
||||
fileserver-sensitive-telemetry-scan:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
@@ -376,7 +351,6 @@ jobs:
|
||||
- jpa-registry-and-docs
|
||||
- fileserver-full-verification
|
||||
- fileserver-documentation-gate
|
||||
- fileserver-pvc-certification
|
||||
- fileserver-sensitive-telemetry-scan
|
||||
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
|
||||
# job and app-image-signing are the only ones that write anything anywhere, and
|
||||
|
||||
+8
-1
@@ -1,6 +1,9 @@
|
||||
.vscode/
|
||||
src/**/bin/
|
||||
.claude/
|
||||
# Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project
|
||||
# settings file is committed: it denies the Agent tool for everyone (AGENTS.md 「Superpowers Workflow」).
|
||||
.claude/*
|
||||
!.claude/settings.json
|
||||
|
||||
# Operator input, not a build input. The examples beside it are the tracked contract;
|
||||
# verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one.
|
||||
@@ -15,3 +18,7 @@ src/.env.lane
|
||||
graphify-out/
|
||||
src/graphify-out/
|
||||
.playwright-mcp/
|
||||
|
||||
# Python bytecode from running scripts/ checks; never committed.
|
||||
__pycache__/
|
||||
*.pyc
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
|
||||
|
||||
기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 엔지니어링 작업 기록 게시판)에 격리한다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
|
||||
기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
|
||||
|
||||
## Prime Directive
|
||||
|
||||
@@ -22,8 +22,9 @@
|
||||
6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다.
|
||||
|
||||
root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어긋나면 이 `AGENTS.md` 목록이
|
||||
우선한다. 자동 강제 범위는 아래 Gradle 정책 권위와 ArchUnit/Test가 담당한다.
|
||||
root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면
|
||||
이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle
|
||||
정책 권위와 ArchUnit/Test가 담당한다.
|
||||
|
||||
## Superpowers Workflow
|
||||
|
||||
@@ -35,8 +36,10 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
||||
- `superpowers:brainstorming`: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다.
|
||||
- `superpowers:writing-plans`: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다.
|
||||
- `superpowers:executing-plans`: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다.
|
||||
- `superpowers:subagent-driven-development`: 계획을 작업 단위로 나누어 독립 에이전트에게 맡길 때 사용한다.
|
||||
- `superpowers:dispatching-parallel-agents`: 서로 독립적인 조사나 구현을 병렬로 진행할 때 사용한다.
|
||||
- `superpowers:subagent-driven-development`, `superpowers:dispatching-parallel-agents`: 이 저장소에서는
|
||||
쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠
|
||||
맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이
|
||||
하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다.
|
||||
- `superpowers:test-driven-development`: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다.
|
||||
- `superpowers:systematic-debugging`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다.
|
||||
- `superpowers:verification-before-completion`: 완료, 수정됨, 통과함을 주장하기 전에 사용한다.
|
||||
@@ -73,13 +76,17 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
||||
`INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼
|
||||
입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을
|
||||
입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
|
||||
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에
|
||||
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
|
||||
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
|
||||
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
|
||||
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
|
||||
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
|
||||
단계(main 빌드: `ci`·`sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·
|
||||
`releaseCheck`, optional-platforms 빌드: `-p optional-platforms`로 부르는 `ci`·`integrationCheck`·
|
||||
단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·
|
||||
`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·
|
||||
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
|
||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
|
||||
@@ -91,8 +98,11 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
||||
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
|
||||
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
|
||||
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
|
||||
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), 세는 job이 부르지 않는
|
||||
`workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
|
||||
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
|
||||
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches`
|
||||
없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이
|
||||
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
|
||||
job.
|
||||
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
|
||||
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
|
||||
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
|
||||
@@ -105,6 +115,8 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
||||
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
|
||||
|
||||
commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다.
|
||||
예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합,
|
||||
다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」).
|
||||
|
||||
## 강제 수준
|
||||
|
||||
@@ -136,7 +148,6 @@ commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit
|
||||
file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는
|
||||
registry만 따른다.
|
||||
- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지.
|
||||
- `sample-portfolio`: 샘플/fixture consumer. production leaf가 의존하면 안 된다.
|
||||
- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
|
||||
|
||||
## 의존성 방향
|
||||
@@ -147,7 +158,6 @@ family 수준 기본 방향:
|
||||
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
||||
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
||||
runtime modules -> shared-contract
|
||||
sample-portfolio -> registered runtime leaves (fixture consumer only)
|
||||
```
|
||||
|
||||
개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다.
|
||||
@@ -159,8 +169,8 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
|
||||
1. 요구사항을 읽고 소유 계층을 판단한다.
|
||||
2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다.
|
||||
3. 여러 단계의 작업이면 `docs/superpowers/specs/`에 설계 문서를 남긴다.
|
||||
4. 구현 전 `docs/superpowers/plans/`에 실행 계획을 작성한다.
|
||||
3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
|
||||
4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다.
|
||||
5. 동작 변경은 테스트를 먼저 작성한다.
|
||||
6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다.
|
||||
7. 유스케이스는 `application-core` command와 use case/service method로 표현한다.
|
||||
@@ -169,8 +179,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
|
||||
|
||||
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. `sample-portfolio`는 모든 계층을 한 leaf에
|
||||
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
@@ -187,7 +196,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
|
||||
쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
|
||||
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
|
||||
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
|
||||
@@ -220,10 +229,10 @@ cd src
|
||||
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
|
||||
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
|
||||
./gradlew ci # PR 게이트 = leaf check + architecture + quality
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동(샘플 포함)·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
|
||||
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
|
||||
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly)
|
||||
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p optional-platforms로 따로)
|
||||
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패
|
||||
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로)
|
||||
./gradlew verifyPublicPathSnapshot
|
||||
./gradlew :app-bootstrap:verifyEnvKeys
|
||||
```
|
||||
@@ -237,7 +246,7 @@ leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름
|
||||
|
||||
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
|
||||
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
|
||||
설계 근거는 `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`.
|
||||
설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`.
|
||||
|
||||
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
|
||||
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
|
||||
@@ -252,7 +261,7 @@ capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
|
||||
자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
|
||||
constructor에서 한다.
|
||||
예외(리뷰 05-18): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
|
||||
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
|
||||
@@ -292,10 +301,10 @@ Docker/runtime 규칙:
|
||||
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다.
|
||||
2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다.
|
||||
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/grpc/grpc-contract/src/main/proto/caskeleton/`의
|
||||
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의
|
||||
디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다.
|
||||
3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가하고, 예시 코드는 `sample-portfolio`에 격리한다.
|
||||
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다.
|
||||
5. 모듈 이름과 경계는 유지한다.
|
||||
6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
|
||||
7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다.
|
||||
|
||||
@@ -1,136 +1,45 @@
|
||||
# CLAUDE.md
|
||||
# CLAUDE.md — 이 repo의 지도
|
||||
|
||||
Repository guidance for the Java 21 + Spring Boot 4.0.8 Clean Architecture template.
|
||||
이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.
|
||||
|
||||
## Prime Directive
|
||||
## 1. 이 repo
|
||||
|
||||
Preserve architecture before optimizing for speed. The following seven HARD-STOP conditions are a
|
||||
synchronized summary of the canonical local policy in `AGENTS.md`:
|
||||
- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
|
||||
- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다.
|
||||
- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다.
|
||||
|
||||
1. `domain-core` gains framework, transport, database, or cloud dependencies.
|
||||
2. A controller directly uses a repository, Spring Data interface, or persistence entity.
|
||||
3. An inbound DTO leaks into `application-core` or `domain-core`.
|
||||
4. Business rules move into mappers, filters, configuration, settings, or controllers.
|
||||
5. Project dependencies violate `src/config/architecture/modules.json` or the Gradle dependency
|
||||
gate.
|
||||
6. Completion is claimed without the relevant verification or a named reason it could not run.
|
||||
7. A repository/corpus conclusion is made without evidence proportional to its scope and risk.
|
||||
## 2. HARD-STOP — 하나라도 어기면 완료가 아니다
|
||||
|
||||
If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must be resynchronized.
|
||||
정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다.
|
||||
|
||||
## Gradle policy authorities
|
||||
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
|
||||
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
|
||||
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
|
||||
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
|
||||
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
|
||||
|
||||
- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source
|
||||
paths, Gradle paths and allowed production project dependency edges. There is no runtime
|
||||
membership list: what a composition root may take is its `allowed_dependencies`, and the direction
|
||||
gate refuses any other edge. The registry owns the leaf list and its size; no document restates
|
||||
the count, because a number written in prose drifts the moment a leaf is added.
|
||||
- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
|
||||
- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
|
||||
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
|
||||
tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test
|
||||
that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`)
|
||||
in that leaf's `mainCheck`; a merge-blocking contract over non-document repository files is a
|
||||
pull-request lane whose inputs are exactly those files (app-bootstrap `repository-contract`).
|
||||
`TEST`/`ARCHITECTURE` lanes are cacheable; `INTEGRATION`/`SYSTEM`/`PERFORMANCE` and main-stage
|
||||
lanes rerun every time.
|
||||
- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's
|
||||
`ca.config-contract`. The `src/build-tools/` included build was emptied and removed.
|
||||
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull
|
||||
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
|
||||
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
|
||||
command removes with `-x` (abbreviations matched as Gradle does) is not covered; a command after
|
||||
which Gradle runs no task (`--dry-run`, `-v`, `--help`, `--status`, `--stop`, …, bundles such as
|
||||
`-qm` included), a short-option bundle Gradle rejects (`-mx`) and a command for another build do
|
||||
not count, nor does one that does not gate for one of three reasons: (1) its failure may not fail
|
||||
its step (an `||` other than `|| exit <non-zero>`, a pipe without pipefail, an `if` condition,
|
||||
after `set +e` or an `exit 0` trap, `continue-on-error`, …); (2) it may not run (inside
|
||||
`if`/`for`/`case` or a function, after a top-level or conditional `exit 0`, `exec` or `set -n`,
|
||||
under a non-status `if:`, in a workflow only a request starts or a `workflow_call` one no counted
|
||||
job calls, in a job that `needs` a conditional job, …); (3) the check does not read it although
|
||||
its failure would fail the step (`|| exit 1`, inside `{ }`, `( )`, `$( )` or `bash -c`, after a
|
||||
`cd` it cannot follow, a `shell:` other than bash or sh, a runner that may be Windows with its
|
||||
`pwsh` default, …) — the failure names each command's reason and says to put the stage command
|
||||
on a line of its own; the build a command runs is its `working-directory`, then the
|
||||
`cd <relative path>` the same shell surely ran before it, joined with `-p` — or a folded workflow
|
||||
`run:` block splits an option off its command.
|
||||
## 3. 맡은 일 → 읽을 문서
|
||||
|
||||
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
|
||||
먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.
|
||||
|
||||
## Proportional workflow
|
||||
| 맡은 일 | playbook |
|
||||
| --- | --- |
|
||||
| 새 업무 기능, 새 capability 모듈 | [docs/work/new-feature.md](docs/work/new-feature.md) → `docs/manual/` |
|
||||
| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | [docs/work/improve.md](docs/work/improve.md) |
|
||||
| 바꾸기 전에 대안 비교와 소유자 결정 | [docs/work/research-design.md](docs/work/research-design.md) |
|
||||
| 매뉴얼·안내 문서 쓰기 | [docs/work/docs-writing.md](docs/work/docs-writing.md) |
|
||||
| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | [docs/work/operate.md](docs/work/operate.md) |
|
||||
| 큰 일을 나눠 다른 세션에 맡기기 | [docs/work/delegate.md](docs/work/delegate.md) |
|
||||
|
||||
- Low risk: work in the owning leaf, follow its nearest guidance, and run the focused check.
|
||||
- Medium risk: use the relevant Superpowers design, planning, TDD, debugging, and review workflows
|
||||
in proportion to the affected boundaries.
|
||||
- High risk: make architecture and behavior decisions explicit, use staged architecture/spec/quality
|
||||
review, and run architecture-wide verification authorized by the task.
|
||||
brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.
|
||||
|
||||
Risk comes from change surface and runtime, security, data, or public-contract impact, not file
|
||||
count.
|
||||
## 4. 검증 명령과 실행 위치
|
||||
|
||||
## Module families
|
||||
|
||||
`src/config/architecture/modules.json` owns the complete leaf list. Root guidance summarizes
|
||||
families; the nearest `src/**/CLAUDE.md` owns local rules. No task enforces this any more:
|
||||
`verifyDocumentedLeafCount` was deleted along with the other documentation-drift parsers. A stated
|
||||
count that disagrees with the registry is a defect, not a build failure — so do not state one.
|
||||
|
||||
| Family | Responsibility | Stable dependency direction |
|
||||
| --- | --- | --- |
|
||||
| `domain-core` | Pure domain model, invariants, events, ports | Java stdlib and registered value-only contracts |
|
||||
| `application-core` | Commands, use cases, application policies, transaction ports | `domain-core`, `shared-contract` |
|
||||
| `adapter:inbound:*` | HTTP, gRPC, GraphQL, WebSocket transport boundaries | application/domain/shared contracts |
|
||||
| `adapter:outbound:persistence-*` | JPA/PostgreSQL and MongoDB persistence adapters | application/domain/shared contracts as registered |
|
||||
| `adapter:outbound:*` | support, messaging, cache, notification, storage, file, HTTP client, identifier capabilities | application/domain/shared and registered support edge |
|
||||
| `shared-contract` | Skeleton-wide operational contracts | Java stdlib only |
|
||||
| `messaging:*` | Vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this application | `messaging:*` only — it depends on no `domain-core`, `application-core`, or `shared-contract` type |
|
||||
| `sample-portfolio` | Fixture/reference consumer | registered runtime leaves; never a production dependency |
|
||||
| `app-bootstrap` | Spring Boot entrypoint and composition root | registered runtime leaves |
|
||||
|
||||
The `messaging:*` family is the one entry that is not a Clean Architecture layer, and it is listed so
|
||||
that the exception is stated rather than inferred from a directory. It is a vendored library — its
|
||||
own `*-api` leaves are its ports, its broker leaves are its adapters, its starter is its composition
|
||||
root — and the messaging module review (`docs/reviews/2026-08-14-messaging-module-code-review.md`
|
||||
MSG-023 §6.2) chose that layout deliberately over folding it into `adapter:outbound:*`. This
|
||||
application reaches it through the application-owned anti-corruption bridge in
|
||||
`adapter:outbound:messaging` (MSG-015). The canonical bridge is the only path: the legacy outbox
|
||||
append port and the legacy Kafka publishing seam were deleted (owner decision 7).
|
||||
|
||||
Never infer an individual leaf's Gradle path, allowed dependency, or test command from this table.
|
||||
Read its `gradle_path` and `allowed_dependencies` from `src/config/architecture/modules.json`; runtime
|
||||
composition is established by actual Gradle dependencies/auto-configuration, not a registry
|
||||
`runtime_memberships` field that does not exist.
|
||||
|
||||
## Layer workflow
|
||||
|
||||
For a full use case, work in this order:
|
||||
|
||||
```text
|
||||
domain-core
|
||||
-> application-core
|
||||
-> adapter:outbound:* (or persistence/identifier)
|
||||
-> adapter:inbound:*
|
||||
-> app-bootstrap wiring
|
||||
```
|
||||
|
||||
Layer-only work stays inside that registered leaf plus its tests. If a required fix crosses a layer
|
||||
or writable scope, stop and request context rather than expanding silently.
|
||||
|
||||
## Testing
|
||||
|
||||
- `domain-core`: pure JUnit unit tests.
|
||||
- `application-core`: use-case tests with hand-rolled fakes; no web or persistence context.
|
||||
- inbound adapters: focused transport slice/contract tests.
|
||||
- persistence adapters: mapping/port contract tests; use a real datastore only when vendor semantics
|
||||
require it.
|
||||
- other outbound adapters: port contract tests with fake external systems; no real network.
|
||||
- identifier: pure deterministic unit tests.
|
||||
- bootstrap/settings: binding, validation, wiring, and architecture tests.
|
||||
|
||||
From `src/`, read the owning leaf's `gradle_path` from
|
||||
`config/architecture/modules.json` and run `./gradlew <gradle-path>:test --console=plain`.
|
||||
Architecture-wide commands:
|
||||
- **실행 위치**: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다.
|
||||
- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew <gradle-path>:test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다.
|
||||
- **저장소 전체 질문**:
|
||||
|
||||
```bash
|
||||
./gradlew architectureCheck --console=plain
|
||||
@@ -139,45 +48,28 @@ Architecture-wide commands:
|
||||
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
|
||||
```
|
||||
|
||||
A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone.
|
||||
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
|
||||
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
|
||||
(SpotBugs, FindSecBugs over production code), `testQualityCheck` (the same over every test source
|
||||
set, against `config/spotbugs/exclude-test.xml`), `configContractCheck` (the environment contract), `integrationCheck` (the
|
||||
declared strict integration lanes; a lane that needs an input the build was not given is left out
|
||||
and named), `performanceCheck` (the declared performance lanes; main and nightly). `ci` (pull
|
||||
request) is leaf checks (API surfaces included, owner decision 20) + architectureCheck +
|
||||
qualityCheck, and the workflow also runs `verifyStrictLaneStages --dry-run`; `mainCheck` (main branch) is configContractCheck +
|
||||
qualificationCheck (which includes testQualityCheck) + the sample web contract + the sample full boot (`:sample-portfolio:systemTest`)
|
||||
+ the public-path snapshot + the transport and messaging qualification lanes + the feature
|
||||
generator round trip (`verifyFeatureScaffold`) + every leaf's `mainCheck` (document-contract lanes
|
||||
and any lane the leaf adds). `releaseCheck` is the tag-only checks: release provenance and the
|
||||
public-path snapshot.
|
||||
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
|
||||
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
|
||||
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
|
||||
- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다.
|
||||
|
||||
Test-writing rules (behavior-sentence names that assert what they promise, `@DisplayName` in Korean
|
||||
only when the name cannot say it (owner decision 5), given/when/then comments, one `// when`, one
|
||||
fake per port in the port owner's testFixtures, fake and adapter sharing one abstract contract test)
|
||||
are canonical in `AGENTS.md`.
|
||||
## 5. 코드만 보고는 헷갈리는 곳
|
||||
|
||||
Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
|
||||
requires the controller's workflow authorization.
|
||||
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
|
||||
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
|
||||
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
|
||||
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
|
||||
- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다.
|
||||
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
|
||||
- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다.
|
||||
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
|
||||
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
|
||||
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다.
|
||||
|
||||
## Capability modules
|
||||
## 6. 소유자 환경
|
||||
|
||||
Optional features (JPA, Redis, Kafka, notification, Mongo, object storage, HTTP client, GraphQL,
|
||||
WebSocket, gRPC, file server) are modules that turn on when present and disappear when removed. A
|
||||
service selects them with one `runtimeOnly` line each in `app-bootstrap/build.gradle`; the template's
|
||||
default composition is the web inbound adapter, observability, the cores, and support/identifier. The
|
||||
seven completion criteria for a capability module are canonical in `AGENTS.md`.
|
||||
|
||||
## Advisory and reporting
|
||||
|
||||
Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many
|
||||
exist; use fewer when the option set is smaller. Judgment findings include falsifiable assumptions
|
||||
and counterarguments. Deterministic compile, dependency, secret, or failed-test findings use
|
||||
Rule → Evidence → Fix without manufactured debate.
|
||||
|
||||
Citation verification is profile-based: none for `review-lite`, blocking citations for
|
||||
`review-standard`, and all material citations for `audit-deep`/`regulated`. Durable reports are
|
||||
triggered by high risk, at least 3 blocking findings, an architecture decision, explicit user request,
|
||||
or the regulated profile. Otherwise a concise result is allowed.
|
||||
- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: [docs/work/operate.md](docs/work/operate.md) 4.1절(실행 위치)과 [docs/work/delegate.md](docs/work/delegate.md) 4.3절(세션). 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다.
|
||||
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다.
|
||||
- 작업 사고 순서의 정본은 design-docs `conventions/work-thinking-order.md`, 커밋·PR 형식은 `conventions/commit-and-pr.md`다.
|
||||
- 보고 말투와 형식은 소유자의 전역 `~/.claude/CLAUDE.md`를 따른다.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ca-skeleton — Clean Architecture Spring Boot 템플릿
|
||||
|
||||
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 작업 기록 게시판)에 격리합니다.
|
||||
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다.
|
||||
|
||||
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다.
|
||||
|
||||
@@ -12,7 +12,6 @@ ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Grad
|
||||
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
||||
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
||||
모든 런타임 모듈 -> shared-contract
|
||||
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)
|
||||
```
|
||||
|
||||
family 수준의 책임은 다음과 같습니다.
|
||||
@@ -26,7 +25,6 @@ family 수준의 책임은 다음과 같습니다.
|
||||
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
|
||||
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
|
||||
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
|
||||
| `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
|
||||
|
||||
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
|
||||
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
|
||||
@@ -38,10 +36,10 @@ test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain`
|
||||
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
|
||||
|
||||
```bash
|
||||
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
|
||||
scripts/bootstrap-local.sh
|
||||
```
|
||||
|
||||
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
|
||||
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
|
||||
|
||||
```bash
|
||||
curl -fsS http://localhost:8080/api/healthcheck
|
||||
@@ -50,9 +48,13 @@ curl -fsS http://localhost:8080/api/healthcheck
|
||||
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml -f docker-compose.local.yml down
|
||||
docker compose --profile '*' down
|
||||
```
|
||||
|
||||
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
|
||||
|
||||
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다.
|
||||
|
||||
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
|
||||
|
||||
### 기본 조립과 부가 기능
|
||||
@@ -91,10 +93,10 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
|
||||
|
||||
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
|
||||
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는 `sample-portfolio`에만 둡니다.
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
|
||||
4. 모듈 이름과 경계는 그대로 유지합니다.
|
||||
|
||||
검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서
|
||||
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
|
||||
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
|
||||
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
|
||||
담당합니다.
|
||||
@@ -102,18 +104,16 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:test
|
||||
./gradlew :sample-portfolio:check
|
||||
./gradlew architectureCheck
|
||||
```
|
||||
|
||||
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다.
|
||||
|
||||
`sample-portfolio`는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.
|
||||
|
||||
## 아키텍처 규칙과 검증
|
||||
|
||||
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. 8개 HARD-STOP 조건의 정본 로컬
|
||||
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 동기화된 요약입니다.
|
||||
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
|
||||
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다.
|
||||
일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다.
|
||||
|
||||
- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
|
||||
- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
|
||||
@@ -134,8 +134,7 @@ cd src
|
||||
|
||||
## 수동 전용 Gradle 태스크
|
||||
|
||||
아래 세 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 각각
|
||||
적어 둔다.
|
||||
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
|
||||
|
||||
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
|
||||
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
|
||||
@@ -145,16 +144,11 @@ Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
|
||||
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
|
||||
```
|
||||
|
||||
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
|
||||
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
|
||||
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
|
||||
- `openapiCheckSnapshot` — 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는
|
||||
`OpenApiDriftContractTest`는 `:sample-portfolio:test`의 일부이고, 그건 `check` 안이며 stage 1에서
|
||||
실행된다. 이 태스크의 고유한 역할은 `-PapproveOpenApiChange`로 **커밋된 스냅샷을 다시 만드는 것**
|
||||
— 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.
|
||||
|
||||
|
||||
## 더 알아보기
|
||||
|
||||
+426
@@ -0,0 +1,426 @@
|
||||
# =============================================================================
|
||||
# 개발 환경 — 이 repo의 compose 파일은 이것 하나다.
|
||||
#
|
||||
# docker compose up -d --wait app # 앱 컨테이너(기본 조립, local 런타임)
|
||||
# docker compose up -d --wait db # 뒷단 서비스 하나만(이름을 대면 그 profile이 켜진다)
|
||||
# docker compose --profile jpa --profile redis up -d --wait # 뒷단 서비스 묶음
|
||||
# docker compose --profile '*' down # 내린다. 데이터까지 지우려면 down -v
|
||||
#
|
||||
# 내릴 때 --profile '*'를 붙인다. 붙이지 않으면 compose는 켜진 profile의 서비스만 내리므로, 이름으로
|
||||
# 띄운 db 같은 profile 서비스가 남는다.
|
||||
#
|
||||
# 뒷단 서비스는 capability 이름의 profile로 고른다. profile을 대지 않으면 app만 뜬다.
|
||||
#
|
||||
# profile 서비스 쓰는 기능
|
||||
# jpa db (PostgreSQL 16) JPA
|
||||
# redis redis (ACL 계정) Redis
|
||||
# kafka kafka Kafka 발행
|
||||
# mongo mongo, mongo-rs-init MongoDB
|
||||
# objectstorage minio, minio-init 객체 저장소
|
||||
# auth keycloak JWT 발급자
|
||||
# mail mailpit (STARTTLS 필수) SMTP 발송
|
||||
#
|
||||
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
|
||||
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
|
||||
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
|
||||
#
|
||||
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
|
||||
# 때는 compose/keycloak/secrets/graphql-smoke-client-secret에 아무 값이나 한 줄 넣는다(그 폴더는
|
||||
# Git이 무시한다). mail profile도 같다: compose/mailpit/tls/에 server.crt·server.key가 있어야 한다.
|
||||
#
|
||||
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
|
||||
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
|
||||
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
|
||||
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
|
||||
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
|
||||
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
|
||||
#
|
||||
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
|
||||
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
|
||||
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
|
||||
# DeveloperExperienceContractTest fails when this value is below the sum.
|
||||
#
|
||||
# Memory limit (D4):
|
||||
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
|
||||
# Default 512m suits a small service; adjust per deployment. A compose lane that boots every
|
||||
# capability at once raises it for itself (compose-profile-contracts.json, appMemoryLimit).
|
||||
# =============================================================================
|
||||
|
||||
# The local MinIO runtime, used by the server below and by the lane's object storage smoke client.
|
||||
#
|
||||
# It is the image the MinIO qualification lanes measured, by the same digest:
|
||||
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
|
||||
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
|
||||
# leaf fails when this default (or the lane file's copy) and the evidence disagree. Change them
|
||||
# together.
|
||||
#
|
||||
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
|
||||
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
|
||||
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
|
||||
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
|
||||
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
|
||||
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: src/
|
||||
dockerfile: Dockerfile
|
||||
args:
|
||||
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
|
||||
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
|
||||
GIT_SHA: "${GIT_SHA:-0000000}"
|
||||
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
|
||||
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
|
||||
# qualification: every capability module present, each lane switching on what it tests.
|
||||
COMPOSITION: "${COMPOSITION:-default}"
|
||||
# The composition is in the tag, so a lane's qualification image is never reused as the
|
||||
# default one (Compose reuses a matching tag instead of building).
|
||||
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
|
||||
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
|
||||
# was marked optional, untracking that file made `docker compose config` fail outright on a
|
||||
# clone. The tracked contract is src/.env.example; copy it. A compose lane does not depend on it:
|
||||
# its values go into a generated `environment:` block, which outranks every env_file.
|
||||
env_file:
|
||||
- path: ./src/.env
|
||||
required: false
|
||||
ports:
|
||||
- "${APP_SERVER_PORT:-8080}:8080"
|
||||
# Management (health, info, prometheus — answered without authentication) on loopback only:
|
||||
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
|
||||
# inside the container, so they need no host port at all.
|
||||
- "127.0.0.1:9001:9001"
|
||||
environment:
|
||||
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
|
||||
# environment the application believes it is in. The dev and prod-smoke lane overlays set
|
||||
# their own.
|
||||
SPRING_PROFILES_ACTIVE: "local"
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
|
||||
# Override via .env or docker compose --env-file if you need a different value.
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
|
||||
APP_SERVER_SHUTDOWN: "graceful"
|
||||
# The `db` service below, on the internal network. The default composition does not read
|
||||
# these; a service that selects the relational capability does.
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
|
||||
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
# ---- Read-only root filesystem (D2) -------------------------------------
|
||||
# The application must write only to the tmpfs mounts declared below.
|
||||
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
|
||||
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
|
||||
read_only: true
|
||||
tmpfs:
|
||||
- /tmp:mode=1777,size=128m
|
||||
- /var/tmp/heap:mode=1777,size=512m
|
||||
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
|
||||
# mount in its own overlay, added with -f when the capability is selected, so this file never
|
||||
# names one (07-08).
|
||||
# ---- Memory limit (D4) --------------------------------------------------
|
||||
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
|
||||
mem_limit: 512m
|
||||
memswap_limit: 512m
|
||||
# ---- Graceful shutdown (D5) ---------------------------------------------
|
||||
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
|
||||
# + margin (6s) = 60s.
|
||||
stop_grace_period: 60s
|
||||
# ---- Health check -------------------------------------------------------
|
||||
# The actuator readiness probe on the management port (9001). It answers under every runtime
|
||||
# (local, dev, prod), unlike the public health path, whose base path differs by runtime.
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD"
|
||||
- "wget"
|
||||
- "--no-verbose"
|
||||
- "--tries=1"
|
||||
- "--spider"
|
||||
- "http://localhost:9001/actuator/health/readiness"
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
start_period: 60s
|
||||
retries: 12
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
|
||||
# ---- PostgreSQL --------------------------------------------------------------
|
||||
# Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`,
|
||||
# IDE) reaches the same database the containerised app reaches over the internal network. The
|
||||
# port is the one src/.env.example's APP_DATASOURCE_URL names.
|
||||
db:
|
||||
profiles:
|
||||
- jpa
|
||||
image: postgres:16-alpine
|
||||
environment:
|
||||
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
|
||||
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
TZ: "UTC"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-db-data
|
||||
target: /var/lib/postgresql/data
|
||||
ports:
|
||||
- "127.0.0.1:5433:5432"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD-SHELL",
|
||||
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
|
||||
]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
|
||||
# ---- MongoDB -----------------------------------------------------------------
|
||||
# A replica set of one. Single-node is still a replica set: transactions and change streams need
|
||||
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
|
||||
# difference at the first transaction.
|
||||
mongo:
|
||||
profiles:
|
||||
- mongo
|
||||
image: mongo:8.0.16
|
||||
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-mongo-data
|
||||
target: /data/db
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 20s
|
||||
|
||||
mongo-rs-init:
|
||||
profiles:
|
||||
- mongo
|
||||
image: mongo:8.0.16
|
||||
depends_on:
|
||||
mongo:
|
||||
condition: service_healthy
|
||||
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
|
||||
# stack can be re-run against a surviving volume without a manual reset.
|
||||
command:
|
||||
- mongosh
|
||||
- --host
|
||||
- mongo
|
||||
- --quiet
|
||||
- --eval
|
||||
- >-
|
||||
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
|
||||
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Kafka -------------------------------------------------------------------
|
||||
kafka:
|
||||
profiles:
|
||||
- kafka
|
||||
image: apache/kafka:3.8.0
|
||||
environment:
|
||||
KAFKA_NODE_ID: "1"
|
||||
KAFKA_PROCESS_ROLES: "broker,controller"
|
||||
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
|
||||
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
|
||||
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
|
||||
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
|
||||
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
|
||||
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
|
||||
interval: 10s
|
||||
timeout: 10s
|
||||
retries: 12
|
||||
start_period: 30s
|
||||
|
||||
# ---- Redis -------------------------------------------------------------------
|
||||
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
|
||||
# compose/redis/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
|
||||
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
|
||||
# a lane-only `+@all` account (compose/redis/acl/README.md). Its first line turns the passwordless
|
||||
# `default` user off, so the application connects as the named accounts the lane contract gives it
|
||||
# (compose-profile-contracts.json, $redisComment).
|
||||
#
|
||||
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
|
||||
# The application then logged that trade, and the missing advanced account, as two startup
|
||||
# warnings — correctly, because in production both are risks — and every Redis lane failed its
|
||||
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
|
||||
# lane now authenticates the way a deployment does instead.
|
||||
#
|
||||
# The passwords are the file's fixture values (compose/redis/acl/README.md); this container is
|
||||
# on the internal network only and publishes no port.
|
||||
redis:
|
||||
profiles:
|
||||
- redis
|
||||
image: redis:7.4
|
||||
command:
|
||||
- redis-server
|
||||
- --appendonly
|
||||
- "no"
|
||||
- --save
|
||||
- ""
|
||||
- --aclfile
|
||||
- /etc/redis/acl/lane-fixture-accounts.acl
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./compose/redis/acl
|
||||
target: /etc/redis/acl
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
|
||||
- "CMD-SHELL"
|
||||
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
start_period: 5s
|
||||
|
||||
# ---- Mailpit — the reference SMTP relay ----------------------------------------
|
||||
mailpit:
|
||||
profiles:
|
||||
- mail
|
||||
image: axllent/mailpit:v1.21
|
||||
environment:
|
||||
MP_SMTP_AUTH_ACCEPT_ANY: "1"
|
||||
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
|
||||
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
|
||||
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
|
||||
# any AUTH now happens inside the TLS session.
|
||||
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
|
||||
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A stack
|
||||
# that wanted a plaintext Mailpit would be asking for a transport the type refuses to express,
|
||||
# and the honest way to satisfy it is to give the relay a certificate.
|
||||
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
|
||||
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
|
||||
MP_SMTP_REQUIRE_STARTTLS: "true"
|
||||
volumes:
|
||||
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
|
||||
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
|
||||
# private key in Git.
|
||||
- type: bind
|
||||
source: ./compose/mailpit/tls
|
||||
target: /run/mailpit-tls
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "/mailpit", "readyz"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
start_period: 5s
|
||||
|
||||
# ---- MinIO -------------------------------------------------------------------
|
||||
minio:
|
||||
profiles:
|
||||
- objectstorage
|
||||
image: *local-minio-image
|
||||
command: ["server", "/data"]
|
||||
environment:
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-minio-data
|
||||
target: /data
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mc", "ready", "local"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 10s
|
||||
|
||||
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
|
||||
# server accepts an admin command, not that an object survives being written and read back.
|
||||
minio-init:
|
||||
profiles:
|
||||
- objectstorage
|
||||
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
|
||||
# it has no shell, and the bootstrap below is a shell script.
|
||||
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
|
||||
depends_on:
|
||||
minio:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./compose/minio/init
|
||||
target: /opt/minio
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Keycloak ----------------------------------------------------------------
|
||||
keycloak:
|
||||
profiles:
|
||||
- auth
|
||||
image: quay.io/keycloak/keycloak:26.0
|
||||
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
|
||||
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
|
||||
# command line.
|
||||
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
|
||||
environment:
|
||||
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
|
||||
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
|
||||
KC_HEALTH_ENABLED: "true"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./compose/keycloak/entrypoint.sh
|
||||
target: /opt/keycloak-entrypoint/entrypoint.sh
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./compose/keycloak/realms
|
||||
target: /opt/keycloak/data/import
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD-SHELL"
|
||||
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 20
|
||||
start_period: 30s
|
||||
|
||||
networks:
|
||||
caskeleton-infra:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
caskeleton-db-data:
|
||||
driver: local
|
||||
caskeleton-mongo-data:
|
||||
driver: local
|
||||
caskeleton-minio-data:
|
||||
driver: local
|
||||
|
||||
secrets:
|
||||
keycloak-graphql-smoke-client-secret:
|
||||
file: ./compose/keycloak/secrets/graphql-smoke-client-secret
|
||||
@@ -1,6 +1,6 @@
|
||||
# Keycloak realm artifact
|
||||
|
||||
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in `docker-compose.infra.yml`
|
||||
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml`
|
||||
and is the same realm every GraphQL qualification lane authenticates against.
|
||||
|
||||
## The client secret is a reference, never a value
|
||||
@@ -42,9 +42,10 @@ a fork that copied one of them got an open account and a green lane.
|
||||
|
||||
## Who loads `lane-fixture-accounts.acl`
|
||||
|
||||
The Redis topology lanes (`../standalone`, `../sentinel`, `../cluster`, `../tls`) and the
|
||||
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the
|
||||
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in
|
||||
`src/config/runtime/compose-profile-contracts.json`). Both mount this directory read-only; neither
|
||||
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's
|
||||
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither
|
||||
keeps a copy, because a second copy of these lines is a second place for a password or a key
|
||||
pattern to drift.
|
||||
|
||||
@@ -1,579 +0,0 @@
|
||||
# =============================================================================
|
||||
# Shared infrastructure, owned here and nowhere else.
|
||||
#
|
||||
# Environment overlays (local, dev, prod-smoke) describe how the application runs. This file
|
||||
# describes what it runs against. Keeping the two apart is why `local` could stop meaning "the app
|
||||
# plus a database" and start meaning "the app, with whichever services the lane asked for".
|
||||
#
|
||||
# Every service carries a Compose profile, so nothing here starts unless a lane names it. A profile
|
||||
# selects services; it never implies a Spring profile. The lane definitions live in
|
||||
# src/config/runtime/compose-profile-contracts.json, and scripts/verify-compose-profile-contracts.sh
|
||||
# checks this file against them.
|
||||
# =============================================================================
|
||||
|
||||
# The local MinIO runtime, used by the server and by the object-storage smoke client below.
|
||||
#
|
||||
# It is the image the MinIO qualification lanes measured, by the same digest:
|
||||
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
|
||||
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
|
||||
# leaf fails when this default and the evidence disagree. Change both together.
|
||||
#
|
||||
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
|
||||
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
|
||||
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
|
||||
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
|
||||
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
|
||||
|
||||
services:
|
||||
# ---- PostgreSQL --------------------------------------------------------------
|
||||
db:
|
||||
profiles:
|
||||
- local-jpa
|
||||
- local-messaging-outbox
|
||||
- local-fileserver
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: postgres:16-alpine
|
||||
environment:
|
||||
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
|
||||
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
TZ: "UTC"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-db-data
|
||||
target: /var/lib/postgresql/data
|
||||
ports:
|
||||
- "127.0.0.1:5433:5432"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD-SHELL",
|
||||
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
|
||||
]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
|
||||
# ---- MongoDB -----------------------------------------------------------------
|
||||
# A replica set of one. Single-node is still a replica set: transactions and change streams need
|
||||
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
|
||||
# difference at the first transaction.
|
||||
mongo:
|
||||
profiles:
|
||||
- local-mongo
|
||||
- all-adapters
|
||||
image: mongo:8.0.16
|
||||
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-mongo-data
|
||||
target: /data/db
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 20s
|
||||
|
||||
mongo-rs-init:
|
||||
profiles:
|
||||
- local-mongo
|
||||
- all-adapters
|
||||
image: mongo:8.0.16
|
||||
depends_on:
|
||||
mongo:
|
||||
condition: service_healthy
|
||||
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
|
||||
# lane can be re-run against a surviving volume without a manual reset.
|
||||
command:
|
||||
- mongosh
|
||||
- --host
|
||||
- mongo
|
||||
- --quiet
|
||||
- --eval
|
||||
- >-
|
||||
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
|
||||
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Kafka -------------------------------------------------------------------
|
||||
kafka:
|
||||
profiles:
|
||||
- local-messaging
|
||||
- local-messaging-outbox
|
||||
- all-adapters
|
||||
image: apache/kafka:3.8.0
|
||||
environment:
|
||||
KAFKA_NODE_ID: "1"
|
||||
KAFKA_PROCESS_ROLES: "broker,controller"
|
||||
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
|
||||
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
|
||||
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
|
||||
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
|
||||
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
|
||||
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
|
||||
interval: 10s
|
||||
timeout: 10s
|
||||
retries: 12
|
||||
start_period: 30s
|
||||
|
||||
# ---- Redis — local compose contract for the shipped Redis runtime ----------------
|
||||
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
|
||||
# infra/redis-sdk/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
|
||||
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
|
||||
# a lane-only `+@all` account (infra/redis-sdk/acl/README.md). Its first line turns the passwordless
|
||||
# `default` user off, so the application connects as the named accounts the lane contract gives it
|
||||
# (compose-profile-contracts.json, $redisComment).
|
||||
#
|
||||
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
|
||||
# The application then logged that trade, and the missing advanced account, as two startup
|
||||
# warnings — correctly, because in production both are risks — and every Redis lane failed its
|
||||
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
|
||||
# lane now authenticates the way a deployment does instead.
|
||||
#
|
||||
# The passwords are the file's fixture values (infra/redis-sdk/acl/README.md); this container is
|
||||
# on the lane's internal network only and publishes no port.
|
||||
redis:
|
||||
profiles:
|
||||
- local-redis
|
||||
- all-adapters
|
||||
image: redis:7.4
|
||||
command:
|
||||
- redis-server
|
||||
- --appendonly
|
||||
- "no"
|
||||
- --save
|
||||
- ""
|
||||
- --aclfile
|
||||
- /etc/redis/acl/lane-fixture-accounts.acl
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/redis-sdk/acl
|
||||
target: /etc/redis/acl
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
|
||||
test:
|
||||
- "CMD-SHELL"
|
||||
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
start_period: 5s
|
||||
|
||||
# ---- Mailpit — the reference SMTP provider for notification serving ----------
|
||||
mailpit:
|
||||
profiles:
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: axllent/mailpit:v1.21
|
||||
environment:
|
||||
MP_SMTP_AUTH_ACCEPT_ANY: "1"
|
||||
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
|
||||
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
|
||||
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
|
||||
# any AUTH now happens inside the TLS session.
|
||||
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
|
||||
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A lane that
|
||||
# wanted a plaintext Mailpit would be asking for a transport the type refuses to express, and
|
||||
# the honest way to satisfy it is to give the relay a certificate.
|
||||
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
|
||||
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
|
||||
MP_SMTP_REQUIRE_STARTTLS: "true"
|
||||
volumes:
|
||||
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
|
||||
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
|
||||
# private key in Git.
|
||||
- type: bind
|
||||
source: ./infra/mailpit/tls
|
||||
target: /run/mailpit-tls
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "/mailpit", "readyz"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
start_period: 5s
|
||||
|
||||
# ---- MinIO -------------------------------------------------------------------
|
||||
minio:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: *local-minio-image
|
||||
command: ["server", "/data"]
|
||||
environment:
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-minio-data
|
||||
target: /data
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mc", "ready", "local"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 10s
|
||||
|
||||
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
|
||||
# server accepts an admin command, not that an object survives being written and read back.
|
||||
minio-init:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
|
||||
# it has no shell, and the bootstrap below is a shell script.
|
||||
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
|
||||
depends_on:
|
||||
minio:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/minio/init
|
||||
target: /opt/minio
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Keycloak ----------------------------------------------------------------
|
||||
keycloak:
|
||||
profiles:
|
||||
- local-graphql
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: quay.io/keycloak/keycloak:26.0
|
||||
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
|
||||
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
|
||||
# command line.
|
||||
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
|
||||
environment:
|
||||
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
|
||||
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
|
||||
KC_HEALTH_ENABLED: "true"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/keycloak/entrypoint.sh
|
||||
target: /opt/keycloak-entrypoint/entrypoint.sh
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./infra/keycloak/realms
|
||||
target: /opt/keycloak/data/import
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD-SHELL"
|
||||
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 20
|
||||
start_period: 30s
|
||||
|
||||
# ---- Capability schema streams ------------------------------------------------
|
||||
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
|
||||
# rather than a property.
|
||||
#
|
||||
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
|
||||
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
|
||||
# INSTALLED_INACTIVE.
|
||||
#
|
||||
# Promote: an operator sanctions the installed schema, and the application refuses to start until
|
||||
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
|
||||
# the install step without making "the tables exist" and "this is sanctioned" the same event.
|
||||
#
|
||||
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
|
||||
# could not have run in the migration container at all.
|
||||
#
|
||||
# Both run before `up`, not with the smoke clients after it — the application is what they are a
|
||||
# precondition for. The lane contract's preStartServices carries that ordering.
|
||||
db-migrate-capabilities:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- local-fileserver
|
||||
- all-adapters
|
||||
image: flyway/flyway:11.1.0
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/postgres/apply-capability-streams.sh
|
||||
target: /opt/capability-streams/apply-capability-streams.sh
|
||||
read_only: true
|
||||
# The whole migration tree, not just db/migration/jpa: the application's own postgresql stream
|
||||
# has to be installed first, or the capability tables arrive in a schema whose flyway_schema_history
|
||||
# does not exist yet and the application refuses to start — which is its baseline-on-migrate: false
|
||||
# policy working as designed.
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
|
||||
target: /flyway/sql
|
||||
read_only: true
|
||||
# Each capability stream from the leaf that owns it, beside rather than inside /flyway/sql: a
|
||||
# bind mount nested in that read-only one would need its mount point created in the source
|
||||
# tree. They moved out of persistence-jpa with their capabilities, and the mount above stopped
|
||||
# reaching them — the script then refused with "no such stream".
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
|
||||
target: /flyway/streams/notification-platform
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
|
||||
target: /flyway/streams/fileserver
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
db-promote-capabilities:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- local-fileserver
|
||||
- all-adapters
|
||||
image: postgres:16-alpine
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/postgres/promote-capability-streams.sh
|
||||
target: /opt/capability-streams/promote-capability-streams.sh
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# The GraphQL transport, as a request. auth-smoke proves a token can be obtained and that public
|
||||
# health answers; this proves /graphql is guarded and that an authenticated query executes.
|
||||
graphql-smoke:
|
||||
profiles:
|
||||
- local-graphql
|
||||
- all-adapters
|
||||
image: curlimages/curl:8.10.1
|
||||
depends_on:
|
||||
keycloak:
|
||||
condition: service_healthy
|
||||
# uid 0 for the mounted 0600 client secret, same as auth-smoke.
|
||||
user: "0:0"
|
||||
entrypoint: ["/bin/sh", "/opt/graphql-smoke/graphql-smoke.sh"]
|
||||
environment:
|
||||
APP_BASE_URL: "http://app:8080"
|
||||
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
|
||||
# Spring for GraphQL serves its own endpoint through a router function rather than an
|
||||
# annotated controller, so the presentation base-path prefix does not apply to it.
|
||||
GRAPHQL_PATH: "${GRAPHQL_PATH:-/graphql}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/graphql/smoke
|
||||
target: /opt/graphql-smoke
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- One-shot smoke clients --------------------------------------------------
|
||||
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
|
||||
# non-zero one fails its lane rather than being treated as "not applicable".
|
||||
auth-smoke:
|
||||
profiles:
|
||||
- local-graphql
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: curlimages/curl:8.10.1
|
||||
depends_on:
|
||||
keycloak:
|
||||
condition: service_healthy
|
||||
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
|
||||
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
|
||||
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
|
||||
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
|
||||
# the container reads it as root instead. The two alternatives are both worse: loosening the host
|
||||
# file to world-readable leaves a credential readable by every process on the machine, and passing
|
||||
# the value as an environment variable puts it in `docker compose config` output and in ps.
|
||||
user: "0:0"
|
||||
entrypoint: ["/bin/sh", "/opt/auth-smoke/auth-smoke.sh"]
|
||||
environment:
|
||||
# The same issuer URL the application is given. A token obtained from one URL and validated
|
||||
# against another proves nothing, and localhost means a different host inside each container.
|
||||
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
|
||||
APP_BASE_URL: "http://app:8080"
|
||||
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
|
||||
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
|
||||
# wrapper exports the value that matches the lane's Spring runtime.
|
||||
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/keycloak/smoke
|
||||
target: /opt/auth-smoke
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
|
||||
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
|
||||
# unnoticed. The lane already pulls this image for the server itself.
|
||||
object-storage-smoke:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: *local-minio-image
|
||||
depends_on:
|
||||
minio-init:
|
||||
condition: service_completed_successfully
|
||||
entrypoint: ["/bin/sh", "/opt/minio-smoke/object-storage-smoke.sh"]
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/minio/smoke
|
||||
target: /opt/minio-smoke
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
notification-smoke:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: curlimages/curl:8.10.1
|
||||
depends_on:
|
||||
keycloak:
|
||||
condition: service_healthy
|
||||
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
|
||||
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
|
||||
# fails on the smoke client rather than on anything it was checking.
|
||||
user: "0:0"
|
||||
entrypoint: ["/bin/sh", "/opt/notification-smoke/notification-smoke.sh"]
|
||||
environment:
|
||||
APP_BASE_URL: "http://app:8080"
|
||||
MAILPIT_BASE_URL: "http://mailpit:8025"
|
||||
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
|
||||
#
|
||||
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
|
||||
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
|
||||
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
|
||||
# have kept passing for as long as the check happened to run before the dispatch worker. An
|
||||
# unset value now renders empty and the client refuses it.
|
||||
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
|
||||
# variable on every lane that never runs this client, while still rendering empty so the
|
||||
# client refuses it.
|
||||
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
|
||||
# Submission and template publication are authenticated like every other non-public path, so
|
||||
# this client obtains a token the same way auth-smoke does — client credentials against the
|
||||
# same issuer URL the application validates against.
|
||||
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
|
||||
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/notification/smoke
|
||||
target: /opt/notification-smoke
|
||||
read_only: true
|
||||
# The handoff lane runs this client twice in one project and the second run needs the request
|
||||
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
|
||||
# container and is removed with the project by the teardown's --volumes.
|
||||
#
|
||||
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
|
||||
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
|
||||
# filesystem it was just told is read-only.
|
||||
- type: volume
|
||||
source: caskeleton-notification-smoke-state
|
||||
target: /opt/notification-smoke-state
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
networks:
|
||||
caskeleton-infra:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
caskeleton-notification-smoke-state:
|
||||
driver: local
|
||||
caskeleton-db-data:
|
||||
driver: local
|
||||
caskeleton-mongo-data:
|
||||
driver: local
|
||||
caskeleton-minio-data:
|
||||
driver: local
|
||||
|
||||
secrets:
|
||||
# Written per run at mode 0600 by the qualification wrapper and removed on teardown. The realm
|
||||
# artifact references it by name; the value never reaches Git, a rendered config, a command line,
|
||||
# or an evidence file.
|
||||
keycloak-graphql-smoke-client-secret:
|
||||
file: ./infra/keycloak/secrets/graphql-smoke-client-secret
|
||||
@@ -1,64 +0,0 @@
|
||||
# =============================================================================
|
||||
# feature-container-runtime-contract — local infrastructure override
|
||||
#
|
||||
# Merge with base (and optionally dev):
|
||||
# docker compose -f docker-compose.yml -f docker-compose.local.yml up
|
||||
#
|
||||
# Local intent:
|
||||
# - Wires the app environment to point at the shared `db` service, which lives in
|
||||
# docker-compose.infra.yml and starts only for lanes whose Compose profile names it.
|
||||
# - Declares no depends_on: a depends_on aimed at a profiled service makes every lane that does
|
||||
# not enable that profile fail to render at all, and ordering is the runtime-smoke wrapper's
|
||||
# job — it knows which services a lane actually starts.
|
||||
# - Keeps read-only filesystem and memory limits from the base compose.
|
||||
# - Publishes the DB on the loopback interface only, so a host-side run
|
||||
# (`./gradlew :app-bootstrap:bootRun`, IDE) reaches the same database the
|
||||
# containerised app reaches over the internal `caskeleton-local` network.
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
app:
|
||||
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
|
||||
# was marked optional, untracking that file made `docker compose config` fail outright on a
|
||||
# clone — the environment override that exists for convenience became a hard prerequisite for
|
||||
# rendering the stack at all. The tracked contract is src/.env.example; copy it.
|
||||
env_file:
|
||||
- path: ./src/.env
|
||||
required: false
|
||||
# Wire the app to the local Postgres service on the internal network.
|
||||
environment:
|
||||
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
|
||||
# environment the application believes it is in, and the two drifting is how a dev stack ends
|
||||
# up running local's settings.
|
||||
SPRING_PROFILES_ACTIVE: "local"
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 60s.
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
|
||||
APP_SERVER_SHUTDOWN: "graceful"
|
||||
# Database connection — points to the local `db` service below.
|
||||
# Override with your actual DB credentials in a local .env file.
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
|
||||
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD"
|
||||
- "wget"
|
||||
- "--no-verbose"
|
||||
- "--tries=1"
|
||||
- "--spider"
|
||||
- "http://localhost:8080/api/healthcheck"
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
start_period: 20s
|
||||
retries: 12
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
|
||||
networks:
|
||||
# Defined in docker-compose.infra.yml, where the services that share it live.
|
||||
caskeleton-infra:
|
||||
external: false
|
||||
|
||||
@@ -1,107 +0,0 @@
|
||||
# =============================================================================
|
||||
# feature-container-runtime-contract — base docker-compose service definition
|
||||
#
|
||||
# Usage:
|
||||
# docker compose up # base only
|
||||
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up # dev override
|
||||
# docker compose -f docker-compose.yml -f docker-compose.local.yml up # local override
|
||||
#
|
||||
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
|
||||
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
|
||||
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
|
||||
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
|
||||
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
|
||||
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
|
||||
#
|
||||
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
|
||||
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
|
||||
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
|
||||
# DeveloperExperienceContractTest fails when this value is below the sum.
|
||||
#
|
||||
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
|
||||
# *relationship* (stop_grace_period >= app timeout + async wait + preStop + margin). The grace is therefore
|
||||
# sized UP to the env-keys SSOT value (30s) — you do not shrink the app drain window to fit an
|
||||
# arbitrary grace. This resolves the earlier 20s/35s drift, which had assumed an app-timeout
|
||||
# value this branch does not own (env-keys.yaml is the SSOT and sets 30s).
|
||||
#
|
||||
# Memory limit (D4):
|
||||
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
|
||||
# Default 512m suits a small service; adjust per deployment.
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: src/
|
||||
dockerfile: Dockerfile
|
||||
args:
|
||||
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
|
||||
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
|
||||
GIT_SHA: "${GIT_SHA:-0000000}"
|
||||
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
|
||||
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
|
||||
# qualification: every capability module present, each lane switching on what it tests.
|
||||
COMPOSITION: "${COMPOSITION:-default}"
|
||||
# The composition is in the tag, so a lane's qualification image is never reused as the
|
||||
# default one (Compose reuses a matching tag instead of building).
|
||||
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
|
||||
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
|
||||
# have no inline default on purpose — the datasource address and credential, the application
|
||||
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
|
||||
# the developer's own src/.env would be reproducible only on that developer's machine. Optional,
|
||||
# so an ordinary `docker compose up` is unaffected.
|
||||
env_file:
|
||||
- path: ./src/.env.lane
|
||||
required: false
|
||||
ports:
|
||||
- "${APP_SERVER_PORT:-8080}:8080"
|
||||
# Management (health, info, prometheus — answered without authentication) on loopback only:
|
||||
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
|
||||
# inside the container, so they need no host port at all.
|
||||
- "127.0.0.1:9001:9001"
|
||||
environment:
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
|
||||
# Override via .env or docker compose --env-file if you need a different value.
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
|
||||
APP_SERVER_SHUTDOWN: "graceful"
|
||||
# ---- Read-only root filesystem (D2) -------------------------------------
|
||||
# The application must write only to the tmpfs mounts declared below.
|
||||
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
|
||||
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
|
||||
read_only: true
|
||||
tmpfs:
|
||||
- /tmp:mode=1777,size=128m
|
||||
- /var/tmp/heap:mode=1777,size=512m
|
||||
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
|
||||
# mount in its own overlay file under infra/<capability>/compose/, added with -f when the
|
||||
# capability is selected, so this file never names one (07-08).
|
||||
# ---- Memory limit (D4) --------------------------------------------------
|
||||
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
|
||||
mem_limit: 512m
|
||||
memswap_limit: 512m
|
||||
# ---- Graceful shutdown (D5) ---------------------------------------------
|
||||
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
|
||||
# + margin (6s) = 60s.
|
||||
stop_grace_period: 60s
|
||||
# ---- Health check -------------------------------------------------------
|
||||
# Targets the actuator readiness probe on the management port (9001).
|
||||
# The warning that used to stand here — that this probe would report UNHEALTHY until two
|
||||
# parallel branches merged — outlived the branches. src/Dockerfile removed its copy and said
|
||||
# why: "a stale warning about a healthcheck is the kind of comment that gets a real red
|
||||
# container ignored."
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD"
|
||||
- "wget"
|
||||
- "--no-verbose"
|
||||
- "--tries=1"
|
||||
- "--spider"
|
||||
- "http://localhost:9001/actuator/health/readiness"
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
start_period: 60s
|
||||
retries: 3
|
||||
restart: unless-stopped
|
||||
+102
-10
@@ -1,7 +1,8 @@
|
||||
# docs
|
||||
|
||||
저장소의 모든 문서는 이 디렉터리 아래에 있다. 어떤 문서를 어디에 두는지가 유일한 규칙이고,
|
||||
파일 목록은 디렉터리를 직접 읽는다. 개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
|
||||
저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표),
|
||||
문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다.
|
||||
개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
|
||||
|
||||
## 어댑터별 운영 문서
|
||||
|
||||
@@ -24,30 +25,121 @@
|
||||
| --- | --- |
|
||||
| `adr/` | 아키텍처 결정 기록 |
|
||||
| `architecture/` | 공개 API 표면 스냅숏 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`) |
|
||||
| `evidence/` | 작업 단계별 증거·체크포인트 |
|
||||
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
|
||||
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
|
||||
| `reviews/` | 모듈 코드 리뷰 결과 |
|
||||
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
|
||||
| `security/` | 공개 경로 스냅숏 |
|
||||
|
||||
## 설계와 계획
|
||||
## 설계와 기록
|
||||
|
||||
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
|
||||
|
||||
| 디렉터리 | 대상 |
|
||||
| --- | --- |
|
||||
| `superpowers/specs/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
|
||||
| `superpowers/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
|
||||
| `superpowers/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
|
||||
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
|
||||
| `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
|
||||
| `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
|
||||
| `history/evidence/` | 작업 단계별 증거·체크포인트 |
|
||||
| `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
|
||||
|
||||
`superpowers/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
|
||||
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `specs/` 와 `plans/` 에 있으므로 이 디렉터리에서
|
||||
`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
|
||||
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서
|
||||
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
|
||||
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은
|
||||
납품 당시 바이트의 해시다.
|
||||
|
||||
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
|
||||
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
|
||||
`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
|
||||
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
|
||||
|
||||
## 문서 수명과 언어
|
||||
|
||||
규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고,
|
||||
이 템플릿을 받은 파생 서비스도 이 절을 따른다.
|
||||
|
||||
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
|
||||
| 결정 | 결정 기록(ADR) | `adr/`, `notification/adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
|
||||
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
|
||||
|
||||
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
|
||||
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
|
||||
- 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR은 문서 검사의 예외 목록에 있다(「문서 검사」).
|
||||
|
||||
## 기록 문서의 머리 블록
|
||||
|
||||
`design/`, `history/`, `adr/`, `notification/adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
|
||||
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
|
||||
|
||||
```text
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 구현됨
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 한국어 한 문장
|
||||
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
||||
- 대체됨: `docs/design/<대체한 문서>.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
```
|
||||
|
||||
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서,
|
||||
`history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지,
|
||||
`history/study/` 학습 문서. ADR의 둘째 줄은
|
||||
`> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
||||
- 상태는 종류마다 고정 어휘다.
|
||||
|
||||
| 종류 | 상태 |
|
||||
| --- | --- |
|
||||
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
|
||||
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
|
||||
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
|
||||
| 납품 패키지 · 증거 · 학습 문서 | 보관 |
|
||||
|
||||
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
|
||||
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
|
||||
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다.
|
||||
- 2026-11-07에 처음 단 상태는 문서의 원래 상태 줄을 바꾼 값이다: Accepted·Approved·확정·승인 → 채택,
|
||||
Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 보완 메모가 있는 ADR → 채택(보완).
|
||||
상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
|
||||
`capability-status.md` 「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다.
|
||||
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
|
||||
|
||||
## 문서와 코드를 같은 변경에서 고친다
|
||||
|
||||
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
|
||||
`grep -rn '<바꾼 이름>' docs src --include=*.md`.
|
||||
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나
|
||||
`upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다.
|
||||
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는
|
||||
registry(`src/config/architecture/modules.json`)를 가리킨다.
|
||||
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
|
||||
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다.
|
||||
|
||||
## 문서 검사
|
||||
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가
|
||||
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
||||
문서를 낡게 만든다.
|
||||
|
||||
| 검사 | 보는 것 |
|
||||
| --- | --- |
|
||||
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
|
||||
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
|
||||
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
|
||||
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 |
|
||||
|
||||
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
|
||||
- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서
|
||||
더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은
|
||||
규칙을 바꾸는 일이라 소유자 결정이 필요하다.
|
||||
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
|
||||
- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다.
|
||||
|
||||
## 여기에 없는 것
|
||||
|
||||
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-09-07
|
||||
- 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
|
||||
- 현재 정본: `src/build-logic/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-BUILD-001: `java-test-fixtures` is the standard for shared test code
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
- 요약: GraphQL context는 inbound에 두고 객체 권한 판단은 application-core로 옮긴다는 결정이다.
|
||||
- 현재 정본: `src/adapter/inbound/graphql/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GQL-001 — GraphQL context stays inbound; object authorization moves to application-core; the persisted-operation store stays an inbound SPI
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 플랫폼을 adapter leaf 하나가 아니라 registry에 등록한 family로 낸다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
|
||||
|
||||
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 영속성 모델은 도메인이 소유한다는 결정이다.
|
||||
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-001 — The domain owns the persistence model
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 재시도는 유스케이스 전체를 다시 돌린다는 결정이다. 그 재시도 엔진은 2026-09-25에 지웠다.
|
||||
- 현재 정본: `docs/jpa/transaction-guide.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-002 — Retry re-runs the whole use case
|
||||
|
||||
- Status: Superseded (2026-09-25) — the retry engine this ADR describes
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: commit 결과를 모르는 실패는 재시도하지 않는다는 결정이다. 2026-09-25 보완이 있다.
|
||||
- 현재 정본: `docs/jpa/transaction-guide.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-003 — Completion unknown is never retried
|
||||
|
||||
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier`
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 스키마의 정본은 Flyway라는 결정이다.
|
||||
- 현재 정본: `docs/jpa/migration-guide.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-004 — Flyway is the schema source of truth
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 영속성 계약은 실제 PostgreSQL에서 돌린다는 결정이다.
|
||||
- 현재 정본: `docs/jpa/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-005 — Contracts run against real PostgreSQL
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
- 요약: 기술 감사 모델은 audit 하나뿐이라는 결정이다.
|
||||
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-JPA-006 — `audit` is the sole technical audit model
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: MongoDB 플랫폼의 경계를 정한 결정이다.
|
||||
- 현재 정본: `docs/mongodb/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-MONGO-001 — MongoDB platform boundary
|
||||
|
||||
- **Status:** Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: BSON 표현을 고정한 목록으로 관리한다는 결정이다.
|
||||
- 현재 정본: `docs/mongodb/bson-mapping-guide.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-MONGO-002 — BSON representation is a pinned manifest
|
||||
|
||||
- **Status:** Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: 트랜잭션 본문 재시도와 commit 재시도를 다른 반복으로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/mongodb/consistency-transaction-guide.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-MONGO-003 — Transaction body retry and commit retry are separate loops
|
||||
|
||||
- **Status:** Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: 인덱스와 스키마 변경은 관리 평면이 맡는다는 결정이다.
|
||||
- 현재 정본: `docs/mongodb/schema-index-migration-guide.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-MONGO-004 — Index and schema changes belong to the admin plane
|
||||
|
||||
- **Status:** Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-13
|
||||
- 요약: MongoDB 고급 기능의 승격 기준을 정한 결정이다. 2026-09-25 보완이 있다.
|
||||
- 현재 정본: `docs/mongodb/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-MONGO-ADV-001 — Advanced capability promotion
|
||||
|
||||
- **Status:** Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: 스트리밍은 실시간 전달이고 web 모듈은 이력을 저장하지 않는다는 결정이다.
|
||||
- 현재 정본: `docs/web/streaming-contract.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WEB-ADV-001: Streaming is live delivery, and the web module stores no history
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: 가상 스레드는 스케줄링을 바꿀 뿐 동시성 예산을 없애지 않는다는 결정이다.
|
||||
- 현재 정본: `docs/web/virtual-thread-profile.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WEB-ADV-002: Virtual threads change scheduling, not the concurrency budget
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: OpenAPI 3.2 문서는 나란히 만들고 실험 등급으로 둔다는 결정이다.
|
||||
- 현재 정본: `docs/web/openapi-32-compatibility.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WEB-ADV-003: OpenAPI 3.2 is generated in parallel and stays experimental
|
||||
|
||||
- Status: Accepted
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: WebSocket 플랫폼을 leaf 하나의 패키지들로 내고 경계를 기계로 검사한다는 결정이다. 2026-09-25 플랫폼을 줄이면서 바뀌었다.
|
||||
- 현재 정본: `src/adapter/inbound/websocket/README.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries
|
||||
|
||||
- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: resume·cluster 상태는 캐시로 다룬다는 결정이다. 그 기능은 2026-09-25에 지웠다.
|
||||
- 현재 정본: `src/adapter/inbound/websocket/README.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WS-002: Resume and cluster state are caches, and are treated as caches
|
||||
|
||||
- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence`
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
- 요약: STOMP를 목적지 목록이 있는 고급 어댑터로 둔다는 결정이다. 그 고급 STOMP는 2026-09-25에 지웠다.
|
||||
- 현재 정본: `src/adapter/inbound/websocket/README.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog
|
||||
|
||||
- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the
|
||||
|
||||
@@ -27,11 +27,11 @@ lanes and CI; it is not a deployment artifact.
|
||||
|
||||
| Capability | Enabled key (property / env, default) | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
|
||||
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. |
|
||||
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
|
||||
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
|
||||
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap` and `sample-portfolio` both take that module with one `runtimeOnly` line, so there is no second assembly. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
|
||||
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
|
||||
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
|
||||
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
|
||||
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
@@ -71,7 +71,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
|
||||
|
||||
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
|
||||
|
||||
리뷰 후속 작업(2026-09-25~28, `docs/superpowers/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
|
||||
리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
|
||||
|
||||
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@@ -60,12 +60,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
|
||||
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
|
||||
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
|
||||
|
||||
`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전
|
||||
`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
|
||||
선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은
|
||||
운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고
|
||||
`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인
|
||||
이유가 이것이다 — 이 잡은 릴리스하지 않는다.
|
||||
PVC 매니페스트와 그 파일을 검사하던 `release.yml` 잡(`fileserver-pvc-certification`)은 2026-11-07에
|
||||
지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이
|
||||
`docs/fileserver/storage-certification.md` 절차로 하고, volume 조건은 `docs/fileserver/operations.md`
|
||||
「운영 환경이 지켜야 할 조건」에 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
|
||||
@@ -4,8 +4,8 @@
|
||||
|
||||
이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.
|
||||
|
||||
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — sample 모듈이 정말 제거 가능한가, optional 모듈
|
||||
조합이 모두 빌드되는가, 레지스트리가 확장 가능한가.
|
||||
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — optional 모듈 조합이 모두 빌드되는가, 레지스트리가
|
||||
확장 가능한가.
|
||||
2. **스켈레톤을 가져다 서비스를 만드는 사람**에게 필요한 검증 — 내 애플리케이션의 테스트,
|
||||
아키텍처 방향, 보안, 릴리스.
|
||||
|
||||
@@ -16,10 +16,7 @@
|
||||
|
||||
| 대상 | 무엇을 지키는가 |
|
||||
| --- | --- |
|
||||
| `:app-bootstrap:sampleOffTest`, `ci-quality-gates.yml`의 `sample-off` job | sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가 |
|
||||
| `sample-portfolio` leaf 전체 | 참조 구현 |
|
||||
| `Dockerfile.sample`, `docker-compose.*` 중 sample 관련 | 위와 동일 |
|
||||
| `docs/superpowers/**` | 이 템플릿을 만든 과정의 설계/계획 기록 |
|
||||
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
|
||||
| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 |
|
||||
| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 |
|
||||
|
||||
|
||||
+10
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-07-20
|
||||
- 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다.
|
||||
- 현재 정본: `src/config/architecture/modules.json`
|
||||
- 대체됨: `docs/design/2026-07-25-harness-free-mode-b-amendment.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
> **SUPERSEDED — HISTORICAL PROVENANCE ONLY (2026-07-25):** The user-approved harness-free
|
||||
> Mode B amendment supersedes this design. Retain the body as historical provenance; it is not
|
||||
> executable instruction.
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: application-core에서 Spring·로깅 의존을 걷어내고 확정된 outbox 실패를 보고하는 방식을 정한 설계다.
|
||||
- 현재 정본: `src/composition/outbox-relay/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Application Outbox Failure Reporting Refactoring Design
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: 하네스 없이 application-core를 프레임워크·로깅 없이 두면서 outbox 실패를 구조화된 ERROR 한 줄로 남기는 설계다.
|
||||
- 현재 정본: `src/composition/outbox-relay/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Application Outbox Failure Reporting — Harness-Free Design
|
||||
|
||||
## Context
|
||||
+10
-1
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: 숨어 있던 CI 제어면을 저장소 안으로 되살려 Gradle·Docker 빌드와 의존성 자동화를 맞추는 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# CI Control Plane Recovery Design
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
@@ -114,7 +123,7 @@ native provenance.
|
||||
**Mode B — controlled reconstruction.** The original source is unavailable or incomplete. The
|
||||
human records that fact and explicitly authorizes reconstruction from the approved
|
||||
[`2026-07-20-harness-policy-engine-design.md`](2026-07-20-harness-policy-engine-design.md),
|
||||
[`2026-07-20-harness-policy-engine.md`](../plans/2026-07-20-harness-policy-engine.md), the tracked
|
||||
[`2026-07-20-harness-policy-engine.md`](../history/plans/2026-07-20-harness-policy-engine.md), the tracked
|
||||
Gradle/module sources, and this design. Reconstructed artifacts receive new hashes and a
|
||||
`controlled-reconstruction` provenance record. Schema, renderer parity, mutation coverage, Gradle
|
||||
project discovery, and architecture dependency checks must pass before the new artifacts can act as
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: 하네스를 되살리지 않고 Gradle 부트스트랩과 의존 방향 검사를 복구하며 registry JSON을 정본으로 정한 범위 수정이다.
|
||||
- 현재 정본: `src/config/architecture/modules.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Harness-Free Mode B Amendment
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: 하네스 없이 품질·의존성 보안 CI를 저장소 안에서 다시 세우는 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Harness-Free Quality and Security CI Design
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: leaf Gradle 의존 그래프를 Clean Architecture를 지키는 최소 모양으로 줄이는 정리 설계다.
|
||||
- 현재 정본: `src/config/architecture/modules.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Module and Gradle Hygiene Refactoring Design
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-25
|
||||
- 요약: 같은 모듈·Gradle 정리를 하네스 없이 적용하는 설계다.
|
||||
- 현재 정본: `src/config/architecture/modules.json`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Harness-Free Module and Gradle Hygiene Design
|
||||
|
||||
- **Date:** 2026-07-25
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 폐기
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 파일 서버를 단계별로 운영 가능한 capability로 올리는 상세 설계다. 이 설계의 publication R1/R2 어댑터는 2026-09-25에 지웠다.
|
||||
- 현재 정본: `docs/fileserver/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Fileserver Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-26
|
||||
+11
-1
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: 통합 지점 모음을 opt-in 운영 capability 플랫폼으로 키우는 전체 설계다. 스위치로 끄던 방식은 2026-09-25 capability 모듈 포장으로 바뀌었다.
|
||||
- 현재 정본: `docs/capability-status.md`
|
||||
- 대체됨: `docs/design/2026-09-25-capability-module-packaging-design.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Production Capability Platform Design
|
||||
|
||||
- Date: 2026-07-26
|
||||
@@ -952,7 +962,7 @@ and durable interfaces are explicit.
|
||||
The authoritative implementation-level design for this capability is
|
||||
[Object Storage Production Capability Deep Design](2026-07-28-objectstorage-production-capability-design.md).
|
||||
Its ordered RED–GREEN execution batches and promotion gates are in the
|
||||
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md).
|
||||
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md).
|
||||
This subsection is only the cross-capability baseline; the dedicated design governs when details
|
||||
differ.
|
||||
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-26
|
||||
- 요약: Redis를 운영 가능한 capability로 올리는 단계별 상세 설계다.
|
||||
- 현재 정본: `docs/redis/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Redis Production Capability Deep Design
|
||||
|
||||
- Date: 2026-07-26
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-27
|
||||
- 요약: HTTP client를 운영 가능한 capability로 올리는 단계별 상세 설계다.
|
||||
- 현재 정본: `docs/httpclient/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# HTTP Client Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-27
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 폐기
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 파일 서버 R2 제어면과 provider 선택을 정한 설계다. 이 R2 어댑터는 2026-09-25에 지웠다.
|
||||
- 현재 정본: `docs/fileserver/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Fileserver R2 Control Plane and Provider Selection Design
|
||||
|
||||
- Date: 2026-07-28
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: JPA·PostgreSQL을 운영 가능한 capability로 올리는 상세 설계다.
|
||||
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# JPA/PostgreSQL Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-28
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 메시징을 운영 가능한 capability로 올리는 상세 설계다.
|
||||
- 현재 정본: `docs/messaging/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Messaging Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-28
|
||||
+11
-2
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 알림을 운영 가능한 capability로 올리는 상세 설계다.
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Notification Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-28
|
||||
@@ -15,7 +24,7 @@
|
||||
|
||||
이 문서는 Notification capability의 승인된 상세 설계다. 2026-07-28에 §36의 다섯 gate를
|
||||
사용자가 승인했으며, 실제 구현 순서는
|
||||
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)을
|
||||
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)을
|
||||
정본으로 사용한다. 구현 및 production readiness는 아직 주장하지 않는다.
|
||||
|
||||
2026-07-28 현재 구현된 범위:
|
||||
@@ -4793,7 +4802,7 @@ COMPLETE 뒤 reverse가 필요하다면 canonical in-flight/intent backlog/provi
|
||||
inbound messaging/inbox architecture로 설계를 수정해야 한다.
|
||||
|
||||
사용자는 2026-07-28에 위 다섯 결정을 승인했다. 구현은
|
||||
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)의
|
||||
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)의
|
||||
작은 TDD task, owner leaf, registry-derived Gradle path, focused test, architecture gate,
|
||||
real-provider evidence와 rollback point를 따른다.
|
||||
|
||||
+16
-7
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: object storage를 운영 가능한 capability로 올리는 상세 설계와 batch 진행 기록이다.
|
||||
- 현재 정본: `src/adapter/outbound/objectstorage/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Object Storage Production Capability Deep Design
|
||||
|
||||
- 작성일: 2026-07-28
|
||||
@@ -12,7 +21,7 @@
|
||||
- 상위 문서:
|
||||
[Production Capability Platform Design](2026-07-26-production-capability-platform-design.md)
|
||||
- 구현 계획:
|
||||
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)
|
||||
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)
|
||||
- 참고 설계:
|
||||
[Redis Production Capability Deep Design](2026-07-26-redis-production-capability-design.md),
|
||||
[Fileserver Production Capability Deep Design](2026-07-26-fileserver-production-capability-design.md),
|
||||
@@ -78,11 +87,11 @@
|
||||
create-only PUT/complete 조건을 무시하므로 managed/direct mutation profile을
|
||||
`UNSUPPORTED`로 유지하며 readiness를 올리지 않는다.
|
||||
|
||||
증거는 [Batch A checkpoint](../../evidence/object-storage/batch-a-checkpoint.md),
|
||||
[Batch B checkpoint](../../evidence/object-storage/batch-b-checkpoint.md),
|
||||
[Batch C checkpoint](../../evidence/object-storage/batch-c-progress.md),
|
||||
[Batch D checkpoint](../../evidence/object-storage/batch-d-checkpoint.md),
|
||||
[Batch E pause checkpoint](../../evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
|
||||
증거는 [Batch A checkpoint](../history/evidence/object-storage/batch-a-checkpoint.md),
|
||||
[Batch B checkpoint](../history/evidence/object-storage/batch-b-checkpoint.md),
|
||||
[Batch C checkpoint](../history/evidence/object-storage/batch-c-progress.md),
|
||||
[Batch D checkpoint](../history/evidence/object-storage/batch-d-checkpoint.md),
|
||||
[Batch E pause checkpoint](../history/evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
|
||||
|
||||
격리 브랜치에서는 private vault 경로를 잘못 선택해 capture가 차단됐지만, main 통합 작업은
|
||||
사용자가 지정한 public vault의
|
||||
@@ -4015,7 +4024,7 @@ authorization endpoint의 ephemeral response이며 stored object DTO에 영구
|
||||
## 37. 구현 계획 작성 전 확정 항목
|
||||
|
||||
정본 구현 순서와 아래 결정의 현재 freeze/approval gate는
|
||||
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)에
|
||||
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)에
|
||||
기록한다. Tasks 1–24의 구현은 Batch E pause checkpoint까지 진행됐지만 Batch E 전체
|
||||
combined/root gate는 아직 통과하지 않았다. Tasks 25–30은 미착수다. 이 구현 진행이나
|
||||
계획 승인이 public API, scanner provider 또는 AWS/IaC 외부 변경 권한을 자동으로 부여하지
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 제안
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: 운영 수준 테스트 구조와 테스트 환경(서비스 준비, 데이터 격리, CI·릴리스 환경)을 정하는 제안이다.
|
||||
- 현재 정본: `docs/testing/TESTING_STRATEGY.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Production-grade test architecture and environment design
|
||||
|
||||
- Status: proposed design; implementation not started
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: Redis 캐시에 cache-aside, 원본 보호, soft/hard TTL을 더하는 증분 설계다.
|
||||
- 현재 정본: `docs/redis/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Redis Cache Resilience Increment Design
|
||||
|
||||
**Status:** approved for implementation
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 구현됨
|
||||
- 작성일: 2026-07-28
|
||||
- 요약: Redis로 고를 수 있는 분산 rate-limit 알고리즘 셋을 제공하는 증분 설계다.
|
||||
- 현재 정본: `docs/redis/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Redis Distributed Rate-Limit Increment Design
|
||||
|
||||
**Status:** implemented as standalone R1
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-01
|
||||
- 요약: 릴리스 위생 경로(sample-off 게이트, wrapper 검증, Docker 캐시, SpotBugs)를 사실대로 맞추는 리팩터링 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Release Hygiene Refactoring Design
|
||||
|
||||
**Date:** 2026-08-01
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 공개 HTTP 오류 응답에 허용한 문구와 안전한 값만 담게 하는 경계 설계다.
|
||||
- 현재 정본: `docs/web/http-contract.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Client-Safe Error Boundary Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: GraphQL·gRPC·WebSocket 전송을 고를 때만 켜고 위험한 활성화는 실패시키는 경계 설계다.
|
||||
- 현재 정본: `docs/web/http-contract.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Conditional Inbound Transport Boundary Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 동작을 바꾸지 않고 남은 fail-open 검증 경로를 없애는 리팩터링 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# P2 Verification Governance Refactoring Design
|
||||
|
||||
## Goal
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: Redis 세션과 HTTP 경계에서 브라우저 세션 보안이 유지되고 실패 시 닫히는지 증명하는 설계다.
|
||||
- 현재 정본: `docs/redis/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Redis Session HTTP Boundary Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 파일을 고치던 검증 경로(stale JAR, 공개 경로)를 읽기 전용으로 바꾸는 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Verification Purity Refactoring Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: 컴파일러·정적 분석·테스트 출력 경고를 0으로 만드는 빌드 설계다.
|
||||
- 현재 정본: `docs/work/reference/gates.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Warning-Zero Build Refactoring Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-02
|
||||
- 요약: JWT·JWKS와 CORS 필터 경계를 밀봉된 테스트와 릴리스 차단 검사로 고정하는 설계다.
|
||||
- 현재 정본: `docs/web/http-contract.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Web Security Boundary Design
|
||||
|
||||
**Date:** 2026-08-02
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-07
|
||||
- 요약: 업로드·다운로드를 넘어 저장·게시·전송을 나눈 공통 파일 서비스 플랫폼 설계다.
|
||||
- 현재 정본: `docs/fileserver/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Fileserver Platform 설계서
|
||||
|
||||
**문서 상태:** 설계 확정안
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-07
|
||||
- 요약: Redis 자료구조와 명령을 위험도에 따라 Typed API와 통제된 Raw Gateway로 나눠 제공하는 설계다.
|
||||
- 현재 정본: `docs/redis/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Redis Wrapper 및 Typed API 설계서
|
||||
|
||||
- **상태:** 구현 기준선 확정
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-08
|
||||
- 요약: 외부 HTTP 호출의 대상, 연결 자원, 시간 예산, 재시도 증거를 다루는 HTTP client 플랫폼 설계다.
|
||||
- 현재 정본: `docs/httpclient/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# HTTP Client Platform 설계서
|
||||
|
||||
**문서 상태:** 구현 기준선 확정
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-10
|
||||
- 요약: 메시지 생성부터 브로커 수락, 소비자 정산까지 증거로 다루는 메시징 플랫폼 설계다.
|
||||
- 현재 정본: `docs/messaging/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Messaging Platform 설계서
|
||||
|
||||
- **상태:** 구현 승인용 기준 설계
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-10
|
||||
- 요약: 요청·수신자·시도 수명주기와 provider 결과를 다루는 알림 전달 플랫폼 설계다.
|
||||
- 현재 정본: `docs/notification/support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# Notification Delivery Platform 설계서
|
||||
|
||||
> 상태: 구현 기준 설계(Implementation-ready)
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: JPA 관계형 영속성 플랫폼의 공개 계약, 모듈 경계, 트랜잭션 의미론을 정한 설계다.
|
||||
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# JPA 관계형 영속성 플랫폼 설계서
|
||||
|
||||
- 문서 상태: 구현 기준 설계
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-11
|
||||
- 요약: 도메인이 MongoDB 문서와 repository를 소유하게 하는 문서 영속성 플랫폼 설계다.
|
||||
- 현재 정본: `docs/mongodb/repository-adaptation.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# MongoDB 문서 영속성 플랫폼 설계서
|
||||
|
||||
- 문서 상태: 구현 기준 설계
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-12
|
||||
- 요약: SDL 계약이 인증·제한·실행·오류 계약을 거쳐 유스케이스에 닿게 하는 GraphQL 실행 플랫폼 설계다.
|
||||
- 현재 정본: `src/adapter/inbound/graphql/README.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# GraphQL API 실행 플랫폼 설계서
|
||||
|
||||
- **문서 상태:** 구현 기준선 확정
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-15
|
||||
- 요약: 다섯 어댑터를 한 bootJar에서 켜고 끌 수 있게 고치는 통합 리뷰와 개선 설계다.
|
||||
- 현재 정본: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 다섯 Adapter 최종 통합 리뷰 및 개선 설계
|
||||
|
||||
- 기준 일자: 2026-08-15
|
||||
+9
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계
|
||||
|
||||
두 계획 문서를 이 저장소(`ca-skeleton`)의 실제 구조·정책·빌드 게이트에 맞춰 실행 가능한 형태로
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user