agentic-dev 0.1.0 → 0.2.1

package/scripts/dev/audit_sdd_build_ast.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+SERVICE_DOCS = {
+    "mobile": ROOT / "sdd/03_build/01_feature/service/mobile_surface.md",
+    "platform": ROOT / "sdd/03_build/01_feature/service/platform_surface.md",
+    "admin": ROOT / "sdd/03_build/01_feature/service/admin_surface.md",
+    "landing": ROOT / "sdd/03_build/01_feature/service/landing_surface.md",
+}
+
+BUILD_AST_DOC = ROOT / "sdd/03_build/03_architecture/build_ast_runtime_tree_governance.md"
+
+
+def read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def score(value: float, maximum: float) -> int:
+    if maximum <= 0:
+        return 0
+    scaled = round((value / maximum) * 10)
+    return max(0, min(10, scaled))
+
+
+def contains_all(text: str, needles: list[str]) -> bool:
+    return all(needle in text for needle in needles)
+
+
+def ast_similarity() -> tuple[int, list[str]]:
+    findings: list[str] = []
+    points = 0.0
+    maximum = 10.0
+
+    mobile = read(SERVICE_DOCS["mobile"])
+    if contains_all(
+        mobile,
+        [
+            "client/mobile/src/main.tsx",
+            "AuthProvider",
+            "BrowserRouter",
+            "client/mobile/src/app/App.tsx",
+            "ProtectedRoute",
+            "InShell",
+            "DashboardPage",
+            "FulfillmentPage",
+            "ShippingPage",
+        ],
+    ):
+        points += 2.5
+    else:
+        findings.append("mobile surface summary does not reflect the real provider/router/shell chain.")
+
+    platform = read(SERVICE_DOCS["platform"])
+    if contains_all(
+        platform,
+        [
+            "client/platform/src/main.tsx",
+            "AuthProvider",
+            "BrowserRouter",
+            "client/platform/src/app/App.tsx",
+            "ProtectedRoute",
+            "AppShell",
+            "DashboardPage",
+            "OrdersPage",
+        ],
+    ):
+        points += 2.5
+    else:
+        findings.append("platform surface summary does not reflect the real app shell route tree.")
+
+    admin = read(SERVICE_DOCS["admin"])
+    if contains_all(
+        admin,
+        [
+            "client/admin/src/main.tsx",
+            "AuthProvider",
+            "BrowserRouter",
+            "client/admin/src/app/App.tsx",
+            "ProtectedRoute",
+            "AdminShell",
+            "AdminDashboardPage",
+            "AdminQueuePage",
+            "AdminSupportPage",
+        ],
+    ):
+        points += 2.5
+    else:
+        findings.append("admin surface summary does not reflect the real admin shell route tree.")
+
+    landing = read(SERVICE_DOCS["landing"])
+    if contains_all(
+        landing,
+        [
+            "client/landing/src/main.tsx",
+            "AuthProvider",
+            "BrowserRouter",
+            "client/landing/src/App.tsx",
+            "LandingHomePage",
+            "LandingLoginPage",
+            "ProtectedRoute",
+            "LandingShell",
+            "LandingWorkspacePage",
+        ],
+    ):
+        points += 2.5
+    else:
+        findings.append("landing surface summary does not reflect the public and gated route assembly.")
+
+    return score(points, maximum), findings
+
+
+def implementation_traceability() -> tuple[int, list[str]]:
+    findings: list[str] = []
+    points = 0.0
+    maximum = 10.0
+
+    mobile = read(SERVICE_DOCS["mobile"])
+    if contains_all(
+        mobile,
+        [
+            "server/main.py",
+            "server/api/http/app.py",
+            "server/api/http/router.py",
+            "contexts/auth/contracts/http/router.py",
+            "contexts/fulfillment/contracts/http/router.py",
+            "contexts/shipping/contracts/http/router.py",
+        ],
+    ):
+        points += 2.0
+    else:
+        findings.append("mobile surface summary does not trace route leaves to backend contract leaves.")
+
+    platform = read(SERVICE_DOCS["platform"])
+    if contains_all(
+        platform,
+        [
+            "server/main.py",
+            "server/api/http/app.py",
+            "server/api/http/router.py",
+            "contexts/auth/contracts/http/router.py",
+            "contexts/catalog/contracts/http/router.py",
+            "contexts/orders/contracts/http/router.py",
+        ],
+    ):
+        points += 2.0
+    else:
+        findings.append("platform surface summary does not trace dashboard and orders routes to backend contracts.")
+
+    admin = read(SERVICE_DOCS["admin"])
+    if contains_all(
+        admin,
+        [
+            "server/main.py",
+            "server/api/http/app.py",
+            "server/api/http/router.py",
+            "contexts/alerts/contracts/http/router.py",
+            "contexts/inventory/contracts/http/router.py",
+            "contexts/support/contracts/http/router.py",
+        ],
+    ):
+        points += 2.0
+    else:
+        findings.append("admin surface summary does not trace admin routes to backend contracts.")
+
+    landing = read(SERVICE_DOCS["landing"])
+    if contains_all(
+        landing,
+        [
+            "server/main.py",
+            "server/api/http/app.py",
+            "server/api/http/router.py",
+            "contexts/catalog/contracts/http/router.py",
+            "contexts/health/contracts/http/router.py",
+            "contexts/user/contracts/http/router.py",
+        ],
+    ):
+        points += 2.0
+    else:
+        findings.append("landing surface summary does not trace public/workspace routes to backend contracts.")
+
+    architecture = read(BUILD_AST_DOC)
+    if contains_all(
+        architecture,
+        [
+            ".agent/ralph.sh",
+            ".claude/agents/",
+            ".codex/skills/SKILL.md",
+            "infra/terraform/README.md",
+        ],
+    ):
+        points += 2.0
+    else:
+        findings.append("build AST architecture summary does not retain the canonical harness and infra roots.")
+
+    return score(points, maximum), findings
+
+
+def human_agent_readability() -> tuple[int, list[str]]:
+    findings: list[str] = []
+    points = 10.0
+    maximum = 10.0
+
+    build_md_files = sorted((ROOT / "sdd/03_build").rglob("*.md"))
+    combined = "\n".join(read(path) for path in build_md_files)
+
+    pattern_penalties = [
+        (r"## Current Build Note", 2.0, "build docs still use a Current Build Note section instead of current-state structure."),
+        (r"\bRalph\b", 2.0, "build docs still contain Ralph loop narrative."),
+        (r"2026-\d{2}-\d{2}", 2.0, "build docs still contain dated history markers."),
+        (r"이번 턴", 1.0, "build docs still contain turn-specific execution narrative."),
+        (r"run `\d+", 1.0, "build docs still contain run-id style execution narrative."),
+        (r"\biteration\b", 1.0, "build docs still contain iteration-oriented loop narrative."),
+    ]
+
+    for pattern, penalty, message in pattern_penalties:
+        if re.search(pattern, combined):
+            points -= penalty
+            findings.append(message)
+
+    for path in SERVICE_DOCS.values():
+        if len(read(path).splitlines()) > 80:
+            points -= 0.5
+            findings.append(f"{path.name} is too large to serve as a concise runtime tree summary.")
+
+    if points < 0:
+        points = 0
+
+    return score(points, maximum), findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--write", type=Path, default=None)
+    args = parser.parse_args()
+
+    ast_score, ast_findings = ast_similarity()
+    trace_score, trace_findings = implementation_traceability()
+    readability_score, readability_findings = human_agent_readability()
+
+    payload = {
+        "scores": {
+            "ast_similarity": ast_score,
+            "implementation_traceability": trace_score,
+            "human_agent_readability": readability_score,
+        },
+        "all_ten": ast_score == 10 and trace_score == 10 and readability_score == 10,
+        "findings": {
+            "ast_similarity": ast_findings,
+            "implementation_traceability": trace_findings,
+            "human_agent_readability": readability_findings,
+        },
+    }
+
+    output = json.dumps(payload, ensure_ascii=False, indent=2)
+    print(output)
+
+    if args.write is not None:
+        target = args.write
+        if not target.is_absolute():
+            target = ROOT / target
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(output + "\n", encoding="utf-8")
+
+    return 0 if payload["all_ten"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/sdd/01_planning/01_feature/INDEX.md

@@ -0,0 +1,16 @@
+# Feature Index
+
+현재 canonical feature spec은 backend domain 기준으로 작성한다.
+
+- [auth_feature_spec.md](./auth_feature_spec.md)
+- [alerts_feature_spec.md](./alerts_feature_spec.md)
+- [catalog_feature_spec.md](./catalog_feature_spec.md)
+- [fulfillment_feature_spec.md](./fulfillment_feature_spec.md)
+- [health_feature_spec.md](./health_feature_spec.md)
+- [inventory_feature_spec.md](./inventory_feature_spec.md)
+- [order_feature_spec.md](./order_feature_spec.md)
+- [shipping_feature_spec.md](./shipping_feature_spec.md)
+- [support_feature_spec.md](./support_feature_spec.md)
+- [user_feature_spec.md](./user_feature_spec.md)
+
+현재 canonical owner domain은 `auth`, `user`, `catalog`, `inventory`, `orders`, `fulfillment`, `shipping`, `alerts`, `support`, `health`다.

package/sdd/01_planning/01_feature/README.md

@@ -0,0 +1,76 @@
+# Feature Planning
+
+## Naming
+
+- Folder name: `01_feature`
+- Document naming: `{domain}_feature_spec.md`
+- Source-of-truth feature spec files are backend domain based.
+
+## Scope
+
+- feature spec은 DDD 관점의 도메인 유스케이스 문서다.
+- route, navigation, sidebar, modal, tab, client local state, 화면 전이는 feature spec에 쓰지 않는다.
+- 위 항목은 `02_screen`에서 관리한다.
+- 하나의 feature code는 하나의 핵심 query 또는 command 유스케이스를 대표한다.
+
+## Implementation Basis
+
+- `Bounded Context`는 실제 backend owner module에 맞춰 작성한다.
+- feature spec은 현재 구현을 기준으로 먼저 정리하고, 미구현 요구는 `02_plan` backlog로 관리한다.
+- frontend-only mock, redirect, client local state machine은 feature spec에 쓰지 않는다.
+- 개별 domain feature spec은 `Purpose -> Scope -> Actor Summary -> Domain Summary -> Aggregate / Model -> Use Case Matrix` 흐름을 기본 뼈대로 사용한다.
+
+## Code Rule
+
+- Feature code format: `{DOMAIN}-F{NNN}`
+- 각 segment는 고정 길이로 유지한다.
+
+| Segment | Rule | Example |
+| --- | --- | --- |
+| `DOMAIN` | 3-letter uppercase domain code | `AUT`, `USR`, `CAT` |
+| `TYPE` | feature 식별자 고정값 | `F` |
+| `NNN` | 3-digit sequence | `001`, `002` |
+
+현재 canonical backend domain code는 `AUT`, `USR`, `CAT`, `INV`, `ORD`, `FUL`, `SHP`, `ALR`, `SUP`, `HLT`다.
+
+## Required Fields
+
+모든 feature row는 아래 정보를 포함한다.
+
+| Field | Purpose |
+| --- | --- |
+| `Feature Code` | 유스케이스의 고유 식별자 |
+| `Use Case` | 비즈니스 의도 |
+| `Actor` | 유스케이스를 시작하거나 소비하는 주체 |
+| `Bounded Context` | 해당 유스케이스가 속한 DDD 경계 |
+| `Aggregate / Model` | 핵심 aggregate, entity, policy, read model |
+| `Type` | `Query` 또는 `Command` |
+| `Preconditions` | 유스케이스가 성립하기 위한 선행 조건 |
+| `Domain Outcome` | 도메인 상태 변화 또는 조회 결과 |
+| `Invariant / Business Rule` | 반드시 지켜야 하는 규칙 |
+
+개별 domain feature spec은 use case matrix 외에 아래 섹션을 포함한다.
+
+| Section | Purpose |
+| --- | --- |
+| `Scope` | 포함/제외 범위를 분리해 screen, transport, backlog와의 경계를 명시한다 |
+| `Actor Summary` | use case matrix에 등장하는 각 actor의 책임과 사용 맥락을 설명한다 |
+
+## Document Boundary
+
+| Folder | Role |
+| --- | --- |
+| `01_feature` | actor, use case, aggregate, invariant 중심의 도메인 유스케이스 |
+| `02_screen` | route, UI surface, CTA, local interaction, transition |
+| `03_architecture` | bounded context 관계, 시스템 경계, 런타임 구조 |
+| `04_data` | 저장 모델, 관계, 키 정책 |
+| `05_api` | request/response, endpoint contract, transport 규약 |
+
+## Writing Rule
+
+- feature spec은 도메인 유스케이스 문서다.
+- `Type`은 `Query` 또는 `Command`만 사용한다.
+- use case matrix에 등장하는 모든 actor는 같은 문서의 `Actor Summary`에서 최소 1회 설명한다.
+- actor 이름은 화면 이름이 아니라 도메인 상호작용을 시작하거나 소비하는 주체 기준으로 유지한다.
+- 식별자는 UUID v7을 기준으로 해석하고, legacy numeric id는 기준 식별자로 간주하지 않는다.
+- 기본 정렬은 `created_at` 또는 time-ordered UUID v7을 사용하고, 명시 순서가 필요해질 때만 `order` 계열 필드를 추가한다.

package/sdd/01_planning/01_feature/alerts_feature_spec.md

@@ -0,0 +1,55 @@
+# alerts feature spec
+
+- 작성 버전: 1.0.0
+
+## 1. Purpose
+
+`alerts` bounded context가 제공하는 운영 알람 feed와 읽음 처리 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - admin surface의 운영 알람 목록 조회
+  - 알람 단건 읽음 처리와 전체 읽음 처리
+- 제외 범위:
+  - email, SMS, push 같은 외부 발송 인프라
+  - 주문/배송/재고 도메인 내부의 원인 계산 로직 자체
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Admin Operator` | admin 서비스에서 운영 이벤트와 예외 상황을 확인하고 알람 읽음 상태를 관리하는 운영 관리자다. | `ALR-F001`, `ALR-F002`, `ALR-F003` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `ALR` |
+| Bounded Context | Alert Center |
+| Primary Backend Owner | `server/contexts/alerts` |
+| Related Context | `orders`, `shipping`, `inventory`, `support` |
+| Main Entry Contract | `GET /api/v1/alerts`, `POST /api/v1/alerts/{alert_id}/read`, `POST /api/v1/alerts/read-all` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `AlertRecord` | 운영 알람 저장 모델 |
+| `AlertItem` | 알람 feed 응답 모델 |
+| `AlertsPayload` | unread count와 목록을 묶은 응답 모델 |
+| `AlertReadResult` | 단건 읽음 처리 결과 |
+| `AlertsReadAllResult` | 전체 읽음 처리 결과 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `ALR-F001` | 운영 알람 feed를 조회한다 | Admin Operator | Alert Center | `AlertsPayload`, `AlertItem`, `AlertRecord` | Query | 관리자 토큰이 유효하고 alert bootstrap 데이터가 존재해야 한다 | unread count와 최신 운영 알람 목록을 반환한다 | feed 조회는 알람 읽음 상태를 변경하지 않는다 |
+| `ALR-F002` | 운영 알람 1건을 읽음 처리한다 | Admin Operator | Alert Center | `AlertReadResult`, `AlertRecord` | Command | 관리자 토큰이 유효하고 요청한 `alert_id`가 존재해야 한다 | 선택한 알람의 `read` 상태가 `true`가 된다 | 존재하지 않는 `alert_id`면 `404`를 반환한다 |
+| `ALR-F003` | 운영 알람 전체를 읽음 처리한다 | Admin Operator | Alert Center | `AlertsReadAllResult`, `AlertRecord` | Command | 관리자 토큰이 유효하고 alert bootstrap 데이터가 존재해야 한다 | 미읽음 알람이 모두 읽음 상태로 갱신된다 | 이미 읽은 알람은 중복 변경하지 않는다 |
+
+## 7. Notes
+
+- `alerts`는 admin dashboard의 보조 read model이 아니라 독립 운영 피드로 취급한다.
+- 원인 도메인이 무엇이든 admin이 소비하는 알람 표현과 읽음 상태는 `alerts` context가 소유한다.

package/sdd/01_planning/01_feature/auth_feature_spec.md

@@ -0,0 +1,57 @@
+# auth feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`auth` bounded context가 제공하는 인증과 현재 세션 해석 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - 이메일/비밀번호 기반 로그인과 bearer token 기반 현재 세션 해석
+  - `auth_accounts.json`이 소유하는 credential 검증과 공통 session contract
+- 제외 범위:
+  - 사용자 프로필 조회/변경과 role 관리
+  - 로그인 이후 서비스별 route 분기나 client-side token 저장 방식
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Platform User` | platform 서비스에서 주문/운영 기능에 접근하기 위해 인증 세션을 발급받는 사용자다. | `AUT-F001` |
+| `Mobile Operator` | mobile 서비스에서 이행 작업을 수행하기 위해 로그인하는 현장 운영자다. | `AUT-F001` |
+| `Admin Operator` | admin 서비스에서 카탈로그, 재고, 사용자 운영 명령을 수행하기 위해 관리자 세션을 발급받는 주체다. | `AUT-F001` |
+| `Landing Member` | landing 서비스에서 회원 전용 자원이나 개인화 동작을 사용하기 위해 로그인하는 사용자다. | `AUT-F001` |
+| `Authenticated Client` | 이미 bearer token을 보유한 frontend runtime 또는 HTTP client로 현재 세션 사용자 해석을 요청하는 주체다. | `AUT-F002` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `AUT` |
+| Bounded Context | Authentication & Session |
+| Primary Backend Owner | `server/contexts/auth` |
+| Related Context | `server/contexts/user` |
+| Main Entry Contract | `POST /api/v1/auth/login`, `GET /api/v1/auth/me` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `LoginCommand` | 로그인 명령 입력 모델 |
+| `AuthToken` | bearer token 응답 모델 |
+| `AuthAccountRecord` | 인증 계정 저장 모델 |
+| `AuthenticatedUser` | 현재 세션 사용자 응답 모델 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `AUT-F001` | 이메일/비밀번호로 로그인하고 access token을 발급한다 | Platform User, Mobile Operator, Admin Operator, Landing Member | Authentication & Session | `LoginCommand`, `AuthToken`, `AuthAccountRecord` | Command | 이메일과 비밀번호가 전달되고, 인증 계정 저장소에 해당 사용자가 존재해야 한다 | access token과 `user_id`가 발급된다 | credential이 일치하지 않으면 `401 Invalid credentials`를 반환한다 |
+| `AUT-F002` | bearer token으로 현재 세션 사용자를 해석한다 | Authenticated Client | Authentication & Session | `AuthToken`, `AuthenticatedUser`, `AuthAccountRecord` | Query | 유효한 bearer token이 전달되고 token subject가 인증 계정 저장소에 존재해야 한다 | 현재 사용자 summary를 반환한다 | token이 위조되었거나 subject 사용자가 없으면 `401 Invalid token`을 반환한다 |
+
+## 7. Notes
+
+- `auth`는 `auth_accounts.json` bootstrap을 소유하며 `user` profile 저장과 credential 저장을 분리한다.
+- 인증 성공 이후 권한별 화면 분기는 frontend service에서 처리하고, backend는 공통 session contract만 제공한다.

package/sdd/01_planning/01_feature/catalog_feature_spec.md

@@ -0,0 +1,61 @@
+# catalog feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`catalog` bounded context가 제공하는 상품 카탈로그 조회와 관리자 상품 편집 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - landing/public 상품 카탈로그 조회와 단일 상품 상세 조회
+  - admin surface의 상품 생성, 수정, 상태 변경 command
+- 제외 범위:
+  - landing 화면의 정렬, 탭, CTA 같은 UI 상호작용
+  - 주문 생성이나 재고 선점 같은 타 context orchestration
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Landing Visitor` | 비로그인 상태로 공개 상품 카탈로그와 상품 상세를 탐색하는 방문자다. | `CAT-F001`, `CAT-F002` |
+| `Landing Member` | 로그인된 landing 회원으로 공개 상품을 둘러보고 구매 전 탐색을 수행하는 사용자다. | `CAT-F001`, `CAT-F002` |
+| `Platform User` | platform 서비스에서 주문 생성이나 운영 판단을 위해 상품 정보를 조회하는 내부 사용자다. | `CAT-F001`, `CAT-F002` |
+| `Admin Operator` | admin 서비스에서 상품을 등록, 수정, 상태 변경하는 운영 관리자다. | `CAT-F003`, `CAT-F004`, `CAT-F005` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `CAT` |
+| Bounded Context | Product Catalog |
+| Primary Backend Owner | `server/contexts/catalog` |
+| Related Context | `auth`, `inventory`, `orders`, `landing` |
+| Main Entry Contract | `GET /api/v1/catalog/products`, `GET /api/v1/catalog/products/{product_id}`, `POST /api/v1/catalog/products`, `PUT /api/v1/catalog/products/{product_id}`, `PATCH /api/v1/catalog/products/{product_id}/status` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `ProductRecord` | 상품 원본 저장 모델 |
+| `ProductSummary` | 상품 목록 응답 모델 |
+| `ProductDetail` | 상품 상세 응답 모델 |
+| `CreateProductCommand` | 상품 생성 명령 |
+| `UpdateProductCommand` | 상품 수정 명령 |
+| `UpdateProductStatusCommand` | 상품 상태 변경 명령 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `CAT-F001` | 상품 카탈로그 목록을 조회한다 | Landing Visitor, Landing Member, Platform User | Product Catalog | `ProductSummary`, `ProductRecord` | Query | 상품 bootstrap 데이터가 존재해야 한다 | 공개 가능한 상품 목록을 필터와 검색 조건에 맞게 반환한다 | `status`, `category`, `q` 조건은 모두 현재 카탈로그 집합 안에서 계산한다 |
+| `CAT-F002` | 단일 상품 상세를 조회한다 | Landing Visitor, Landing Member, Platform User | Product Catalog | `ProductDetail`, `ProductRecord` | Query | 요청한 `product_id`가 저장소에 존재해야 한다 | 상세 페이지 구성을 위한 상품 전체 속성을 반환한다 | 존재하지 않는 `product_id`면 `404 Catalog product not found`를 반환한다 |
+| `CAT-F003` | 관리자가 새 상품을 등록한다 | Admin Operator | Product Catalog | `CreateProductCommand`, `ProductDetail`, `ProductRecord` | Command | 관리자 토큰이 유효하고 slug, 이름, 가격, variant 정보가 전달되어야 한다 | 새 상품 레코드가 생성되어 카탈로그 목록에 합류한다 | `slug`는 카탈로그 내에서 유일해야 하며 variant는 최소 1개 이상이어야 한다 |
+| `CAT-F004` | 관리자가 상품 속성을 수정한다 | Admin Operator | Product Catalog | `UpdateProductCommand`, `ProductDetail`, `ProductRecord` | Command | 관리자 토큰이 유효하고 요청한 `product_id`가 존재해야 한다 | 상품 속성이 부분 갱신되고 `updated_at`이 갱신된다 | 빈 수정 요청은 `400 No catalog product fields provided`, 중복 slug는 `409`를 반환한다 |
+| `CAT-F005` | 관리자가 상품 상태를 변경한다 | Admin Operator | Product Catalog | `UpdateProductStatusCommand`, `ProductDetail`, `ProductRecord` | Command | 관리자 토큰이 유효하고 요청한 `product_id`가 존재해야 한다 | 상품 `status`가 `draft`, `active`, `archived` 중 하나로 전환된다 | 존재하지 않는 `product_id`면 `404 Catalog product not found`를 반환한다 |
+
+## 7. Notes
+
+- `catalog`는 landing/public read surface와 admin write surface를 함께 소유한다.
+- 카탈로그의 가격, 이미지, 속성, variant는 모두 product aggregate 내부 속성으로 유지한다.

package/sdd/01_planning/01_feature/fulfillment_feature_spec.md

@@ -0,0 +1,58 @@
+# fulfillment feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`fulfillment` bounded context가 제공하는 모바일 운영 overview와 task board 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - mobile 서비스의 fulfillment overview, board, note read model
+  - fulfillment task 상태 전이 command
+- 제외 범위:
+  - route 최적화나 배차 같은 고도화 계획
+  - fulfillment 외부 context를 직접 갱신하는 orchestration
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Mobile Operator` | mobile 서비스에서 현장 이행 작업을 수행하며 task 현황을 보고 상태를 갱신하는 운영자다. | `FUL-F001`, `FUL-F002`, `FUL-F003` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `FUL` |
+| Bounded Context | Fulfillment Operations |
+| Primary Backend Owner | `server/contexts/fulfillment` |
+| Related Context | `auth`, `orders`, `inventory` |
+| Main Entry Contract | `GET /api/v1/fulfillment/overview`, `GET /api/v1/fulfillment/board`, `PATCH /api/v1/fulfillment/tasks/{task_id}/status` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `FulfillmentTaskRecord` | 이행 task 원본 |
+| `FulfillmentOverview` | 모바일 dashboard overview 응답 |
+| `FulfillmentBoardPayload` | 모바일 task board 응답 |
+| `FulfillmentEvent` | timeline 이벤트 모델 |
+| `FulfillmentNote` | 운영 note 모델 |
+| `FulfillmentTaskStatusTransitionCommand` | task 상태 전이 명령 |
+| `FulfillmentTaskStatusTransition` | task 상태 전이 결과 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `FUL-F001` | 이행 overview를 조회한다 | Mobile Operator | Fulfillment Operations | `FulfillmentOverview`, `FulfillmentTaskRecord`, `FulfillmentEvent` | Query | 인증 토큰이 유효하고 task/event bootstrap 데이터가 존재해야 한다 | throughput, stat, timeline, stage load를 반환한다 | `Blocked`와 `Outbound` 지표는 현재 task 상태 집합으로 계산한다 |
+| `FUL-F002` | 이행 board와 note 목록을 조회한다 | Mobile Operator | Fulfillment Operations | `FulfillmentBoardPayload`, `FulfillmentTaskRecord`, `FulfillmentNote` | Query | 인증 토큰이 유효하고 task/note bootstrap 데이터가 존재해야 한다 | task board 목록과 note 목록을 함께 반환한다 | board payload는 `tasks`와 `notes` 두 블록을 항상 함께 반환한다 |
+| `FUL-F003` | 이행 task 상태를 전환한다 | Mobile Operator | Fulfillment Operations | `FulfillmentTaskStatusTransitionCommand`, `FulfillmentTaskStatusTransition`, `FulfillmentTaskRecord` | Command | 인증 토큰이 유효하고 요청한 `task_id`가 존재해야 한다 | task의 `status`와 선택적 `stage`가 갱신된다 | 존재하지 않는 `task_id`면 `404`를 반환한다 |
+
+## 7. Notes
+
+- `fulfillment`는 mobile 서비스의 canonical backend surface다.
+- 출고 이후 배송 추적과 carrier 진행 상태는 별도 `shipping` context가 소유한다.
+- timeline과 notes는 별도 bootstrap source를 사용하지만, screen 단위에서는 fulfillment context가 함께 조합해 반환한다.

package/sdd/01_planning/01_feature/health_feature_spec.md

@@ -0,0 +1,52 @@
+# health feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`health` bounded context가 제공하는 기술 상태 확인 contract를 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - 무인증 liveness/status probe contract
+  - runtime이 기동 중인지 확인하는 최소 운영 신호
+- 제외 범위:
+  - 알림 전파, auto-recovery, runbook 절차 같은 운영 후속 조치
+  - business domain readiness나 데이터 정합성 검증
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `CI Runner` | CI 파이프라인에서 서버 기동과 기본 응답 계약을 확인하는 자동 검증 주체다. | `HLT-F001`, `HLT-F002` |
+| `Compose Runtime` | compose healthcheck나 container supervisor처럼 주기적으로 프로브를 호출하는 런타임 주체다. | `HLT-F001`, `HLT-F002` |
+| `External Monitor` | 외부 uptime/monitoring 시스템에서 서비스 생존 여부를 확인하는 감시 주체다. | `HLT-F001`, `HLT-F002` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `HLT` |
+| Bounded Context | Technical Health |
+| Primary Backend Owner | `server/contexts/health` |
+| Related Context | `server/api/http/app.py` |
+| Main Entry Contract | `GET /health`, `GET /api/v1/status` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `health_response()` | 루트 프로브 응답 생성 함수 |
+| `get_status_payload()` | API prefix 하의 상태 응답 생성 함수 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `HLT-F001` | 루트 health probe를 조회한다 | CI Runner, Compose Runtime, External Monitor | Technical Health | `health_response()` | Query | FastAPI app이 기동 중이어야 한다 | `{"status":"ok"}` 응답을 반환한다 | 인증 없이 호출 가능해야 한다 |
+| `HLT-F002` | API status probe를 조회한다 | CI Runner, Compose Runtime, External Monitor | Technical Health | `get_status_payload()` | Query | API router가 정상 mount되어야 한다 | `{"service":"template-server","status":"healthy"}` 응답을 반환한다 | 인증 없이 호출 가능해야 한다 |
+
+## 7. Notes
+
+- `health`는 비즈니스 도메인이 아니라 technical bounded context지만, 운영/검증 contract를 위해 canonical feature spec에 포함한다.