문제: 설계서·계획서·납품 패키지·증거·학습 문서와 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.
108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||
> **기록 · 납품 패키지** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||
|
||
- 상태: 보관
|
||
- 작성일: 2026-08-13
|
||
- 요약: GraphQL 설계 패키지를 받을 때 한 정적 검증 결과다.
|
||
- 현재 정본: `src/adapter/inbound/graphql/README.md`
|
||
<!-- 머리 블록 끝 -->
|
||
|
||
# GraphQL Superpowers 문서 정적 검증 결과
|
||
|
||
- **검증 시각 기준:** 2026-08-12
|
||
- **검증 대상:** 설계서 1개, Stable 구현 계획서 1개, Advanced·Experimental 확장 계획서 1개
|
||
- **검증 명령:** `python3 validate_graphql_docs.py`
|
||
- **결과:** **PASS**
|
||
- **실행 검사:** 1,475
|
||
- **통과:** 1,475
|
||
- **실패:** 0
|
||
|
||
## 문서 규모
|
||
|
||
| 문서 | 행 수 | 크기 |
|
||
|---|---:|---:|
|
||
| GraphQL API 실행 플랫폼 설계서 | 2,553 | 93,359 bytes |
|
||
| Stable 구현 계획서 | 4,560 | 209,041 bytes |
|
||
| Advanced 확장 계획서 | 1,976 | 105,717 bytes |
|
||
|
||
## 계획 구조
|
||
|
||
| 항목 | Stable | Advanced |
|
||
|---|---:|---:|
|
||
| Task 수 | 48 | 19 |
|
||
| Create 경로 수 | 227 | 113 |
|
||
| Task 번호 연속성 | PASS | PASS |
|
||
| 모든 Task의 `Files`·`Interfaces` | PASS | PASS |
|
||
| 모든 Task의 Implementation Requirements | PASS | PASS |
|
||
| 모든 Task의 Step 1–5 | PASS | PASS |
|
||
| 실패·통과 예상 결과 | PASS | PASS |
|
||
| Task별 Git commit 명령 | PASS | PASS |
|
||
| Create 경로 중복 | 없음 | 없음 |
|
||
| Stable·Advanced 경로 충돌 | 없음 | 없음 |
|
||
|
||
## 핵심 계약 검증
|
||
|
||
```text
|
||
SDL-first external contract
|
||
Single Executable Schema Stable default
|
||
HTTP POST Stable profile
|
||
application/graphql-response+json preferred
|
||
Validation 이후 Field Error·Partial Data는 HTTP 200
|
||
Draft 294는 Stable에서 제외
|
||
JPA Entity·MongoDB Document 직접 노출 금지
|
||
GraphQL Multipart Upload 미지원·Fileserver 사용
|
||
request-wide database transaction 금지
|
||
DataLoader request scope
|
||
Finite Fetch Profile
|
||
HMAC-signed cursor
|
||
Mutation idempotency·expected version 분리
|
||
Parser·shape·complexity·runtime response budget
|
||
Actor·Field·Object·Tenant authorization
|
||
Low-cardinality observability
|
||
Stable/Advanced dependency isolation
|
||
Persisted Operation·WebSocket·SSE·Federation 분리
|
||
RSocket·HTTP GET·Incremental Delivery Experimental
|
||
```
|
||
|
||
위 계약은 설계서와 계획서의 필수 문자열·모듈 경로·Task별 파일·테스트를 대조해 검증했습니다.
|
||
|
||
## 입력 리서치 추적성
|
||
|
||
- 첨부된 `GraphQL API 실행 플랫폼 심층 리서치` 원문 전체가 설계서의 `부록 B`에 포함되어 있습니다.
|
||
- 설계 본문은 원문의 용어와 결론을 유지하면서 구현 판단을 Stable·Advanced·Experimental로 고정합니다.
|
||
- 설계서와 입력 원문의 exact text 포함 검사를 별도로 통과했습니다.
|
||
|
||
## 패키지 검증 항목
|
||
|
||
```text
|
||
문서 파일 존재
|
||
Markdown code fence 균형
|
||
Task 1–48 / 1–19 연속성
|
||
Task별 테스트·명령·commit
|
||
정확한 Create 경로
|
||
Placeholder 금지
|
||
Stable module에 WebSocket·Federation·Persisted Operation 경로 부재
|
||
Advanced module에 feature flag와 capability 경로 존재
|
||
금지 API pattern 부재
|
||
문서 SHA-256 계산
|
||
```
|
||
|
||
## 검증 범위의 한계
|
||
|
||
현재 PASS는 **문서의 정적 구조, 요구사항 추적성, 내부 계약과 실행 계획의 완결성**을 의미합니다. 실제 Backend Skeleton 저장소가 입력으로 제공되지 않았으므로 다음은 실행하지 않았습니다.
|
||
|
||
```text
|
||
Gradle configuration·compile
|
||
Spring Boot ApplicationContext 기동
|
||
SchemaMappingInspector 실제 결과
|
||
GraphQlTester HTTP·WebFlux contract
|
||
JPA·MongoDB statement/query-count integration
|
||
query bomb·complexity load test
|
||
Virtual Thread·event-loop blocking test
|
||
WebSocket·SSE soak test
|
||
Federation composition·router integration
|
||
actual Git commit
|
||
```
|
||
|
||
실제 구현에서는 Stable Task 1–48을 먼저 수행해 Stable Release Gate를 통과한 뒤 Advanced Task 1–19를 시작해야 합니다.
|