Files
clean-architecture-backend-…/docs/history/packages/web-superpowers-package/VALIDATION.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

203 lines
5.4 KiB
Markdown

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 납품 패키지** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 보관
- 작성일: 2026-08-28
- 요약: 웹 inbound HTTP 설계 패키지 묶음을 받을 때 한 정적 검증 결과다.
- 현재 정본: `docs/web/http-contract.md`
<!-- 머리 블록 끝 -->
# Web Superpowers 문서 정적 검증 결과
검증 기준일: 2026-08-13
## 1. 검증 대상
| 문서 | 행 수 |
|---|---:|
| `web-inbound-http-api-execution-platform-design.md` | 1,656 |
| `web-inbound-http-api-execution-platform-implementation-plan.md` | 4,762 |
| `web-advanced-capabilities-expansion-plan.md` | 1,532 |
| 원본 심층 리서치 | 1,597 |
## 2. 구조 검증
| 항목 | 결과 |
|---|---:|
| 실행 검사 | 1,097 |
| 통과 | 1,097 |
| 실패 | 0 |
| Stable Task | 58 |
| Advanced Task | 19 |
| Stable Create 경로 | 289 |
| Advanced Create 경로 | 94 |
| Stable Task 번호 연속성 | PASS |
| Advanced Task 번호 연속성 | PASS |
| 모든 Task의 Files·Interfaces | PASS |
| 모든 Task의 Implementation requirements | PASS |
| 모든 Task의 Step 1~5 | PASS |
| 모든 Task의 실패·통과 예상 결과 | PASS |
| 모든 Task의 Git commit 명령 | PASS |
| Stable Create 경로 중복 | 없음 |
| Advanced Create 경로 중복 | 없음 |
| Stable·Advanced Create 경로 충돌 | 없음 |
| Markdown code fence 균형 | PASS |
| `TODO`·`TBD`·`FIXME` | 없음 |
검증 명령:
```bash
cd /mnt/data
./validate_web_docs.py
```
실행 결과:
```text
checks=1097 passed=1097 failed=0
```
## 3. 설계 핵심 계약 검증
다음 계약이 설계서와 계획서에 모두 존재하는지 확인했습니다.
```text
W1 / W2 / W3 / W4 공개 계층
MVC와 WebFlux Starter 상호 배타성
Request / Application / Response Evidence 분리
APPLICATION_COMMITTED와 HTTP response delivery 분리
RFC 9457 Problem Details
400 / 422 분리
409 / 412 분리
OpenAPI 3.1.2 Stable
Path major API version
HMAC keyset cursor
ETag / If-Match
Idempotency semantic fingerprint
Redis가 DB commit evidence의 유일한 source가 아님
Business mutation + JPA idempotency evidence same transaction
Application commit 후 response-loss fault test
Durable acceptance 이후에만 202
Trusted Nginx forwarded-header boundary
Tomcat / Jetty / Reactor Netty / Nginx 실제 gate
Rate limit 429와 Admission 503 분리
Low-cardinality metric·access log
Stable·Advanced dependency 격리
```
## 4. 계획 완결성 검증
Stable 계획은 다음 단계로 구성됩니다.
```text
Task 1~14
→ Core·HTTP·JSON·Problem·Architecture Foundation
Task 15~22
→ MVC·Tomcat·Jetty·WebFlux·Reactor Netty
Task 23~30
→ Security·Proxy·Versioning·Route·OpenAPI
Task 31~36
→ Collection Query·Cursor·Conditional·Evidence
Task 37~43
→ Idempotency·JPA Evidence·Redis Gate·Response Loss
Task 44~48
→ Durable Operation·Outbox·HTTP Resource·Cache
Task 49~55
→ Budget·Rate·Admission·CORS/CSRF·Order·Observability·Nginx
Task 56~58
→ Cross-stack Contract·Performance·Stable Release
```
Advanced 계획은 다음 단계로 구성됩니다.
```text
Task 1~3
→ Module isolation·Virtual Thread·Controlled Blocking Bridge
Task 4~5
→ JSON Merge Patch·JSON Patch
Task 6~13
→ Streaming Core·SSE·NDJSON·JSON Sequence·Drain·Replay
Task 14~18
→ Functional WebFlux·CBOR·XML·OpenAPI 3.2·RateLimit Draft
Task 19
→ Soak·Rollback·Promotion Gate
```
## 5. 검증 범위의 한계
현재 검증은 **문서의 구조, 요구사항 추적성, 내부 계약, 파일 경로, 작업 순서에 대한 정적 검증**입니다.
실제 Backend Skeleton 저장소가 이번 입력에 포함되지 않았으므로 다음은 실행한 상태가 아닙니다.
```text
Gradle configuration·compile
Spring Boot ApplicationContext 기동
Tomcat·Jetty·Reactor Netty 실제 contract
PostgreSQL JPA idempotency transaction
Redis concurrent gate
Messaging outbox operation
Nginx TLS·Forwarded topology
commit 후 TCP reset fault injection
OpenAPI generated client compile
abuse·load·graceful shutdown
Git commit
```
계획서의 경로와 package는 다음 명시적 가정을 사용합니다.
```text
Java 21
Gradle Kotlin DSL
Spring Boot 4.1 BOM
root package: io.backend.skeleton.web
stable module root: modules/web
advanced module root: modules/web-advanced
```
## 6. 패키지 무결성 검증
패키지 조립 후 다음 검증을 추가로 수행했습니다.
```text
Package-local validator
→ checks=1104 passed=1104 failed=0
MANIFEST.sha256
→ 모든 7개 파일 OK
ZIP CRC
→ No errors detected
독립 문서와 패키지 내부 문서
→ byte 단위 일치
```
검증 명령:
```bash
cd /mnt/data/web-superpowers-package
./validate_web_docs.py
sha256sum -c MANIFEST.sha256
cd /mnt/data
unzip -t web-superpowers-package.zip
cmp web-inbound-http-api-execution-platform-design.md \
web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md
cmp web-inbound-http-api-execution-platform-implementation-plan.md \
web-superpowers-package/docs/superpowers/plans/2026-08-13-web-inbound-http-api-execution-platform-implementation-plan.md
cmp web-advanced-capabilities-expansion-plan.md \
web-superpowers-package/docs/superpowers/plans/2026-08-13-web-advanced-capabilities-expansion-plan.md
```