agentic-dev 0.1.0 → 0.2.0

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

@@ -0,0 +1,60 @@
+# inventory feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`inventory` bounded context가 제공하는 재고 조회와 관리자 재고 조정 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - SKU/거점 단위 재고 read model과 관리자 재고 mutation command
+  - 수동 조정, 선점, 해제, 절대값 설정 같은 inventory 내부 상태 변경
+- 제외 범위:
+  - 주문/이행 context가 자동으로 일으키는 재고 orchestration
+  - 창고 배차, 입고, 출고 작업 계획의 상세 workflow
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Admin Operator` | admin 서비스에서 재고 현황을 조회하고 조정, 선점, 해제, 재설정 같은 운영 명령을 수행하는 관리자다. | `INV-F001`, `INV-F002`, `INV-F003`, `INV-F004`, `INV-F005`, `INV-F006` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `INV` |
+| Bounded Context | Inventory Availability |
+| Primary Backend Owner | `server/contexts/inventory` |
+| Related Context | `auth`, `catalog`, `orders` |
+| Main Entry Contract | `GET /api/v1/inventory/levels`, `GET /api/v1/inventory/levels/{sku}/{location_id}`, `POST /api/v1/inventory/levels/{sku}/{location_id}/adjustments`, `POST /api/v1/inventory/levels/{sku}/{location_id}/reservations`, `POST /api/v1/inventory/levels/{sku}/{location_id}/releases`, `PUT /api/v1/inventory/levels/{sku}/{location_id}` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `InventoryLevelRecord` | SKU-거점별 재고 원본 |
+| `InventoryLevel` | 재고 조회 응답 모델 |
+| `AdjustInventoryCommand` | cycle count 등 수동 증감 명령 |
+| `ReserveInventoryCommand` | 주문 선점 명령 |
+| `ReleaseInventoryCommand` | 선점 해제 명령 |
+| `SetInventoryLevelCommand` | 절대값 설정 명령 |
+| `InventoryMutationReceipt` | 재고 조정 결과 응답 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `INV-F001` | 재고 레벨 목록을 조회한다 | Admin Operator | Inventory Availability | `InventoryLevel`, `InventoryLevelRecord` | Query | 관리자 토큰이 유효하고 inventory bootstrap 데이터가 존재해야 한다 | SKU, 상품, 거점, 상태 기준 재고 레벨 목록을 반환한다 | `status`는 `available_to_sell`과 `reorder_point` 계산 결과로 결정된다 |
+| `INV-F002` | 단일 SKU/거점 재고 상세를 조회한다 | Admin Operator | Inventory Availability | `InventoryLevel`, `InventoryLevelRecord` | Query | 관리자 토큰이 유효하고 요청한 `sku/location_id` 조합이 존재해야 한다 | 선택한 재고 레벨의 가용 재고와 재주문 여부를 반환한다 | 존재하지 않는 조합이면 `404 Inventory level not found`를 반환한다 |
+| `INV-F003` | 재고를 증감 조정한다 | Admin Operator | Inventory Availability | `AdjustInventoryCommand`, `InventoryMutationReceipt`, `InventoryLevelRecord` | Command | 관리자 토큰이 유효하고 요청한 재고 레벨이 존재해야 한다 | `on_hand`가 증감되고 조정 영수증을 반환한다 | delta는 0일 수 없고, 조정 후 `on_hand`는 `reserved`보다 작아질 수 없다 |
+| `INV-F004` | 재고를 선점한다 | Admin Operator | Inventory Availability | `ReserveInventoryCommand`, `InventoryMutationReceipt`, `InventoryLevelRecord` | Command | 관리자 토큰이 유효하고 요청한 재고 레벨이 존재해야 한다 | `reserved` 수량이 증가한다 | 선점 수량은 가용 재고를 초과할 수 없다 |
+| `INV-F005` | 선점된 재고를 해제한다 | Admin Operator | Inventory Availability | `ReleaseInventoryCommand`, `InventoryMutationReceipt`, `InventoryLevelRecord` | Command | 관리자 토큰이 유효하고 요청한 재고 레벨이 존재해야 한다 | `reserved` 수량이 감소한다 | 해제 수량은 현재 `reserved`를 초과할 수 없다 |
+| `INV-F006` | 재고 절대값을 재설정한다 | Admin Operator | Inventory Availability | `SetInventoryLevelCommand`, `InventoryMutationReceipt`, `InventoryLevelRecord` | Command | 관리자 토큰이 유효하고 요청한 재고 레벨이 존재해야 한다 | `on_hand`, `reserved`, `safety_stock`, `reorder_point`가 새 값으로 설정된다 | `reserved`는 `on_hand`보다 클 수 없다 |
+
+## 7. Notes
+
+- inventory는 현재 admin 전용 운영 컨텍스트다.
+- order/fulfillment에서 직접 inventory mutation을 일으키는 orchestration은 아직 없고, template baseline에서는 admin command로 먼저 노출한다.

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

@@ -0,0 +1,63 @@
+# order feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`orders` bounded context가 제공하는 플랫폼 주문 현황과 관리자 운영 큐 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - platform 주문 overview/list read model과 주문 생성, 상태 전이 command
+  - admin 주문 overview/queue read model
+- 제외 범위:
+  - 외부 결제 게이트웨이 정산이나 배송사 연동
+  - 비동기 이벤트 버스 기반 후속 orchestration
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Platform User` | platform 서비스에서 주문 현황을 조회하고 신규 주문 생성이나 주문 상태 갱신을 수행하는 운영 사용자다. | `ORD-F001`, `ORD-F002`, `ORD-F003`, `ORD-F004` |
+| `Admin Operator` | admin 서비스에서 주문 KPI와 운영 큐를 모니터링하는 관리자다. | `ORD-F005`, `ORD-F006` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `ORD` |
+| Bounded Context | Order Operations |
+| Primary Backend Owner | `server/contexts/orders` |
+| Related Context | `auth`, `catalog`, `fulfillment` |
+| Main Entry Contract | `GET /api/v1/orders/overview`, `GET /api/v1/orders`, `POST /api/v1/orders`, `PATCH /api/v1/orders/{order_id}/status`, `GET /api/v1/orders/admin/overview`, `GET /api/v1/orders/admin/queue` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `OrderRecord` | bootstrap 기반 주문 원본 |
+| `OrderOverview` | 플랫폼 dashboard 요약 읽기 모델 |
+| `OrderSummary` | 플랫폼 orders 목록 읽기 모델 |
+| `CreateOrderCommand` | 주문 생성 명령 |
+| `UpdateOrderStatusCommand` | 주문 상태 전이 명령 |
+| `OrderStatusTransition` | 주문 상태 전이 결과 |
+| `AdminOrderOverview` | 관리자 운영 요약 읽기 모델 |
+| `AdminQueueItem` | 관리자 거래 큐 읽기 모델 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `ORD-F001` | 플랫폼 주문 overview를 조회한다 | Platform User | Order Operations | `OrderOverview`, `OrderRecord` | Query | 인증 토큰이 유효하고 주문 bootstrap 데이터가 존재해야 한다 | 주문 카드, 최근 활동, 선택 주문 상세를 함께 반환한다 | overview는 최근 활동 3건과 선택 주문 1건을 항상 포함한다 |
+| `ORD-F002` | 플랫폼 주문 목록을 조회한다 | Platform User | Order Operations | `OrderSummary`, `OrderRecord` | Query | 인증 토큰이 유효하고 주문 bootstrap 데이터가 존재해야 한다 | 주문 목록을 반환한다 | 목록 행은 `id`, `product_name`, `customer_name`, `status`를 유지한다 |
+| `ORD-F003` | 신규 주문을 생성한다 | Platform User | Order Operations | `CreateOrderCommand`, `OrderRecord` | Command | 인증 토큰이 유효하고 제품, 고객, 판매자, 금액 정보가 전달되어야 한다 | 새 `OrderRecord`가 생성되어 목록과 overview에 반영된다 | 새 주문은 문자열 ID를 부여받고 `Pending`과 `Queued`를 기본 상태로 사용한다 |
+| `ORD-F004` | 주문의 결제/이행 상태를 변경한다 | Platform User | Order Operations | `UpdateOrderStatusCommand`, `OrderStatusTransition`, `OrderRecord` | Command | 인증 토큰이 유효하고 요청한 `order_id`가 존재해야 한다 | 주문의 `status`, `fulfillment_status`, `stage`가 변경된다 | 존재하지 않는 `order_id`면 `404`를 반환한다 |
+| `ORD-F005` | 관리자용 주문 overview를 조회한다 | Admin Operator | Order Operations | `AdminOrderOverview`, `OrderRecord` | Query | 관리자 토큰이 유효하고 주문 bootstrap 데이터가 존재해야 한다 | 관리자 KPI와 stage 현황을 반환한다 | admin surface는 platform surface와 다른 운영형 read model을 사용한다 |
+| `ORD-F006` | 관리자용 거래 큐를 조회한다 | Admin Operator | Order Operations | `AdminQueueItem`, `OrderRecord` | Query | 관리자 토큰이 유효하고 주문 bootstrap 데이터가 존재해야 한다 | 주문별 운영 큐 행을 반환한다 | 큐 행은 `order_id`, `product_name`, `customer_name`, `status`, `sla`를 유지한다 |
+
+## 7. Notes
+
+- `orders`는 platform surface와 admin surface에 서로 다른 read model을 제공한다.
+- 운영 알람 feed는 별도 `alerts` context가 소유하고, `orders`는 주문 자체 read/write 모델만 유지한다.
+- template baseline의 주문 상태 전이는 내부 mutation semantics까지만 다루며 외부 결제/이벤트 연동은 포함하지 않는다.

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

@@ -0,0 +1,55 @@
+# shipping feature spec
+
+- 작성 버전: 1.0.0
+
+## 1. Purpose
+
+`shipping` bounded context가 제공하는 배송 추적 overview와 shipment 상태 전이 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - mobile/operator surface에서 배송 현황 overview와 shipment 목록 조회
+  - shipment 상태 전이와 마지막 배송 이벤트 갱신
+- 제외 범위:
+  - 외부 택배사 webhook, 실시간 위치 추적, 고객 알림 발송
+  - 결제 승인이나 재고 선점 같은 upstream orchestration
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Mobile Operator` | mobile 서비스에서 출고 이후 배송 상태를 추적하고 shipment 진행 상태를 갱신하는 운영자다. | `SHP-F001`, `SHP-F002`, `SHP-F003` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `SHP` |
+| Bounded Context | Shipping Operations |
+| Primary Backend Owner | `server/contexts/shipping` |
+| Related Context | `orders`, `fulfillment` |
+| Main Entry Contract | `GET /api/v1/shipping/overview`, `GET /api/v1/shipping/shipments`, `PATCH /api/v1/shipping/shipments/{shipment_id}/status` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `ShipmentRecord` | 배송 원본 저장 모델 |
+| `ShippingOverview` | 배송 overview 응답 모델 |
+| `ShipmentSummary` | 배송 목록 응답 모델 |
+| `UpdateShipmentStatusCommand` | 배송 상태 전이 명령 |
+| `ShipmentStatusTransition` | 배송 상태 전이 결과 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `SHP-F001` | 배송 overview를 조회한다 | Mobile Operator | Shipping Operations | `ShippingOverview`, `ShipmentRecord` | Query | 인증 토큰이 유효하고 shipment bootstrap 데이터가 존재해야 한다 | 배송 중, 지연, 오늘 완료 건수와 carrier 현황을 반환한다 | overview 집계는 shipment 원본을 변경하지 않는다 |
+| `SHP-F002` | 배송 shipment 목록을 조회한다 | Mobile Operator | Shipping Operations | `ShipmentSummary`, `ShipmentRecord` | Query | 인증 토큰이 유효하고 shipment bootstrap 데이터가 존재해야 한다 | 배송 목록과 최신 이벤트를 반환한다 | 목록 행은 `shipment_id`, `order_id`, `carrier`, `status`, `eta`를 유지한다 |
+| `SHP-F003` | 배송 상태를 갱신한다 | Mobile Operator | Shipping Operations | `UpdateShipmentStatusCommand`, `ShipmentStatusTransition`, `ShipmentRecord` | Command | 인증 토큰이 유효하고 요청한 `shipment_id`가 존재해야 한다 | shipment의 `status`, `last_event`, 선택적 `eta`가 갱신된다 | 존재하지 않는 `shipment_id`면 `404`를 반환한다 |
+
+## 7. Notes
+
+- `shipping`은 출고 이후 배송 추적 책임을 `fulfillment`에서 분리해 downstream delivery 상태만 소유한다.
+- 고객-facing tracking 경험은 아직 포함하지 않고 operator/mobile surface만 baseline으로 제공한다.

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

@@ -0,0 +1,53 @@
+# support feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`support` bounded context가 제공하는 관리자 FAQ/support 관리 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - admin surface에서 FAQ/support 항목 목록 조회
+  - FAQ 작성과 visibility 변경 command
+- 제외 범위:
+  - end-user 문의 inbox나 대화형 support workflow
+  - notification, ticket assignment 같은 별도 support operations
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Admin Operator` | admin 서비스에서 FAQ/support 콘텐츠를 조회하고 등록하거나 공개 상태를 바꾸는 운영 관리자다. | `SUP-F001`, `SUP-F002`, `SUP-F003` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `SUP` |
+| Bounded Context | Support Content |
+| Primary Backend Owner | `server/contexts/support` |
+| Related Context | `auth` |
+| Main Entry Contract | `GET /api/v1/support/faqs`, `POST /api/v1/support/faqs`, `PATCH /api/v1/support/faqs/{faq_id}/visibility` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `SupportFaq` | FAQ/support 항목 읽기 모델 |
+| `SupportFaqRecord` | FAQ 저장/수정 결과 모델 |
+| `CreateSupportFaqCommand` | FAQ 작성 명령 |
+| `ChangeFaqVisibilityCommand` | FAQ 공개 상태 변경 명령 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `SUP-F001` | FAQ/support 목록을 조회한다 | Admin Operator | Support Content | `SupportFaq`, `SupportFaqRecord` | Query | 관리자 토큰이 유효하고 support bootstrap 데이터가 존재해야 한다 | 질문과 visibility가 포함된 FAQ 목록을 반환한다 | admin support surface는 질문 목록과 visibility를 같은 read model로 유지한다 |
+| `SUP-F002` | FAQ 항목을 새로 등록한다 | Admin Operator | Support Content | `CreateSupportFaqCommand`, `SupportFaqRecord` | Command | 관리자 토큰이 유효하고 question, answer가 전달되어야 한다 | 새 FAQ 레코드가 생성되어 목록에 추가된다 | 새 FAQ는 문자열 ID와 `updated_at`을 갖는다 |
+| `SUP-F003` | FAQ 노출 상태를 변경한다 | Admin Operator | Support Content | `ChangeFaqVisibilityCommand`, `SupportFaqRecord` | Command | 관리자 토큰이 유효하고 요청한 `faq_id`가 존재해야 한다 | FAQ의 `visibility`가 새 값으로 갱신된다 | 존재하지 않는 `faq_id`면 `404`를 반환한다 |
+
+## 7. Notes
+
+- 현재 `support`는 FAQ 중심 운영 content context이고, create/visibility change만 command surface로 제공한다.

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

@@ -0,0 +1,54 @@
+# user feature spec
+
+- 작성 버전: 1.1.0
+
+## 1. Purpose
+
+`user` bounded context가 제공하는 사용자 디렉터리 조회와 상태 변경 기능을 구현 기준으로 정리한다.
+
+## 2. Scope
+
+- 포함 범위:
+  - admin surface에서 사용자 목록/상세 조회
+  - 사용자 운영 상태 변경 command
+- 제외 범위:
+  - 로그인, 세션 발급, credential 검증
+  - end-user 자기 프로필 수정 같은 self-service profile workflow
+
+## 3. Actor Summary
+
+| Actor | Description | Appears In |
+| --- | --- | --- |
+| `Admin Operator` | admin 서비스에서 사용자 디렉터리를 조회하고 운영 상태를 변경하는 관리자다. | `USR-F001`, `USR-F002`, `USR-F003` |
+
+## 4. Bounded Context Summary
+
+| Item | Value |
+| --- | --- |
+| Domain Code | `USR` |
+| Bounded Context | User Directory |
+| Primary Backend Owner | `server/contexts/user` |
+| Related Context | `auth` |
+| Main Entry Contract | `GET /api/v1/users`, `GET /api/v1/users/{user_id}`, `PATCH /api/v1/users/{user_id}/status` |
+
+## 5. Aggregate / Model Snapshot
+
+| Aggregate / Model | Role |
+| --- | --- |
+| `UserRecord` | profile 저장 모델 |
+| `UserSummary` | 사용자 목록 응답 모델 |
+| `UserDetail` | 단일 사용자 상세 응답 모델 |
+| `UpdateUserStatusCommand` | 사용자 상태 전이 명령 |
+
+## 6. Use Case Matrix
+
+| Feature Code | Use Case | Actor | Bounded Context | Aggregate / Model | Type | Preconditions | Domain Outcome | Invariant / Business Rule |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `USR-F001` | 사용자 summary 목록을 조회한다 | Admin Operator | User Directory | `UserSummary`, `UserRecord` | Query | 관리자 토큰이 유효하고 사용자 bootstrap 데이터가 존재해야 한다 | 사용자 목록을 반환한다 | 목록 행은 `id`, `name`, `email`, `role`, `status`를 유지한다 |
+| `USR-F002` | 단일 사용자 상세를 조회한다 | Admin Operator | User Directory | `UserDetail`, `UserRecord` | Query | 관리자 토큰이 유효하고 요청한 `user_id`가 저장소에 존재해야 한다 | timezone과 last login이 포함된 상세를 반환한다 | 존재하지 않는 `user_id`면 `404 User not found`를 반환한다 |
+| `USR-F003` | 사용자의 운영 상태를 변경한다 | Admin Operator | User Directory | `UpdateUserStatusCommand`, `UserDetail`, `UserRecord` | Command | 관리자 토큰이 유효하고 요청한 `user_id`가 저장소에 존재해야 한다 | 대상 사용자의 `status`가 새 값으로 갱신된다 | 존재하지 않는 `user_id`면 `404 User not found`를 반환한다 |
+
+## 7. Notes
+
+- `user`는 profile directory context이고 credential hash를 소유하지 않는다.
+- 인증 credential은 `auth` context가 별도 bootstrap 저장소로 관리한다.

package/sdd/01_planning/02_screen/INDEX.md

@@ -0,0 +1,13 @@
+# Screen Planning
+
+- screen code format: `{SERVICE}-S{NNN}`
+- canonical service code: `PLT`, `ADM`, `MOB`, `LND`
+
+- [platform_screen_spec.pdf](./platform_screen_spec.pdf)
+- [admin_screen_spec.pdf](./admin_screen_spec.pdf)
+- [mobile_screen_spec.pdf](./mobile_screen_spec.pdf)
+- [landing_screen_spec.pdf](./landing_screen_spec.pdf)
+
+화면 코드와 기능 설명은 각 PDF 상세 페이지의 우측 테이블을 canonical surface로 사용한다.
+build source, capture asset, generator는 `sdd/99_toolchain/01_automation` 아래에 둔다.
+`MOB-S003`의 canonical route는 `/fulfillment`이고, landing catalog proof는 `GET /api/v1/catalog/products`를 기준으로 한다.

package/sdd/01_planning/02_screen/README.md

@@ -0,0 +1,41 @@
+# Screen Planning
+
+## Naming
+
+- Folder name: `02_screen`
+- Canonical artifact: `{service}_screen_spec.pdf`
+- Source-of-truth screen spec files are service based.
+
+## Code Rule
+
+- Screen code format: `{SERVICE}-S{NNN}`
+- 각 segment는 고정 길이로 유지한다.
+
+| Segment | Rule | Example |
+| --- | --- | --- |
+| `SERVICE` | 3-letter uppercase service code | `PLT`, `ADM`, `MOB`, `LND` |
+| `TYPE` | screen 식별자 고정값 | `S` |
+| `NNN` | 3-digit sequence | `001`, `002` |
+
+## Canonical Output
+
+- [platform_screen_spec.pdf](./platform_screen_spec.pdf)
+- [admin_screen_spec.pdf](./admin_screen_spec.pdf)
+- [mobile_screen_spec.pdf](./mobile_screen_spec.pdf)
+- [landing_screen_spec.pdf](./landing_screen_spec.pdf)
+
+## Rule
+
+- screen spec은 서비스 surface 기준 산출물이다.
+- route, UI block, CTA, interaction, transition은 screen spec PDF 안에서 관리한다.
+- build source, capture asset, generator는 `sdd/99_toolchain/01_automation` 아래에 둔다.
+- reusable asset planning 산출물은 `sdd/01_planning/02_screen/assets/` 아래에 둔다.
+- data 모델링 상세는 `04_data`에서 다루고, architecture/system boundary는 `03_architecture`에서 다룬다.
+- screen spec에서 파생되는 로고/일러스트 등 재사용 자산은 generic asset recipe generator로 재생성 가능해야 한다.
+
+## Toolchain
+
+- generic asset recipe generator (`스펙에셋빌더`): [`spec_asset_builder.py`](../../99_toolchain/01_automation/spec_asset_builder.py)
+- compatibility wrapper: [`build_asset_recipes.py`](../../99_toolchain/01_automation/build_asset_recipes.py)
+- example recipe manifest: [`asset_recipe_manifest.example.py`](../../99_toolchain/03_templates/asset_recipe_manifest.example.py)
+- asset planning root example: [`assets/README.md`](assets/README.md)

package/sdd/01_planning/02_screen/assets/README.md

@@ -0,0 +1,16 @@
+# Assets
+
+## Role
+
+- `assets/`는 screen planning에서 파생되는 reusable asset의 planning 산출물을 둔다.
+- 여기에는 inventory, source reference, crop rationale, naming rule 같은 문서성 산출물을 저장한다.
+
+## Storage Rule
+
+- project/service별 하위 폴더를 만든다.
+- generator와 manifest는 `sdd/99_toolchain/01_automation/`에 둔다.
+- runtime asset output은 각 구현 repo 경로에 둔다.
+
+## Example
+
+- [example/README.md](example/README.md)

package/sdd/01_planning/02_screen/assets/example/README.md

@@ -0,0 +1,13 @@
+# Example Assets
+
+## Purpose
+
+- 이 폴더는 템플릿 사용자가 project-specific asset inventory를 어떻게 남겨야 하는지 보여주는 예시다.
+
+## Recommended Contents
+
+- reusable asset inventory
+- source page / source file reference
+- crop rationale
+- naming convention
+- approval note

package/sdd/01_planning/03_architecture/INDEX.md

@@ -0,0 +1,9 @@
+# Architecture Planning
+
+- [README.md](./README.md)
+- [architecture_document_structure.md](./architecture_document_structure.md)
+- [templates_system_architecture.md](./templates_system_architecture.md)
+- [frontend](./frontend)
+- [backend](./backend)
+- [infra](./infra)
+- [tech-research](./tech-research)

package/sdd/01_planning/03_architecture/README.md

@@ -0,0 +1,25 @@
+# Architecture Planning
+
+- 범위: 서비스별 세부 화면보다 시스템 공통 구조와 구현 선택을 우선 기록한다.
+- architecture 문서는 공통/일반화된 기준을 먼저 두고, 필요할 때만 특화 문서를 추가한다.
+- 주요 축:
+  - frontend architecture
+  - backend architecture
+  - infra architecture
+  - auth/session
+  - deployment topology
+  - migration
+- frontend architecture 문서는 모듈화, 컴포넌트, store/state, domain/use case, UI/UX, storage, API adapter 패턴을 다룬다.
+- backend architecture 문서는 DDD context 구조, context 내부 계층, 3-layer, hexagonal, monolithic, EDA, MSA, CQRS와 실제 구현체 선택을 다룬다.
+- infra architecture 문서는 container, orchestration, database, network, redundancy, multi-region 같은 서비스 기반 구조를 다룬다.
+- 데이터 모델링은 architecture 범위에 포함하지 않고 `sdd/01_planning/04_data/`에서 다룬다.
+
+## Canonical Docs
+
+- [INDEX.md](./INDEX.md)
+- [architecture_document_structure.md](./architecture_document_structure.md)
+- [templates_system_architecture.md](./templates_system_architecture.md)
+- [frontend/README.md](./frontend/README.md)
+- [backend/README.md](./backend/README.md)
+- [infra/README.md](./infra/README.md)
+- [tech-research/README.md](./tech-research/README.md)

package/sdd/01_planning/03_architecture/architecture_document_structure.md

@@ -0,0 +1,77 @@
+# Architecture Document Structure
+
+## 1. Purpose
+
+- `sdd/01_planning/03_architecture`는 프론트엔드, 백엔드, 인프라를 아우르는 공통 구조와 구현 선택을 기록한다.
+- architecture 문서는 주로 일반화/공통화된 기준을 설명한다.
+- 특정 기술, 인증, 배포, 런타임처럼 개별 주제가 독립 가치가 있으면 특화 문서를 함께 둔다.
+
+## 2. Boundary
+
+### Included In Architecture
+
+- frontend architecture
+  - module composition
+  - component structure
+  - store/state management
+  - domain / use case / adapter structure
+  - UI/UX patterns
+  - local storage / session storage / cache
+  - API client / facade / contract adapter
+- backend architecture
+  - DDD bounded context structure
+  - domain / application / infrastructure / contracts layers
+  - structural choices such as 3-layer, hexagonal, monolithic
+  - pattern adoption such as EDA, MSA, CQRS and the selected implementation
+  - runtime composition and service boundaries
+- infra architecture
+  - container runtime
+  - orchestration
+  - database runtime
+  - network / domain / routing
+  - redundancy / HA
+  - multi-region / deployment topology
+
+### Excluded From Architecture
+
+- entity, schema, relationship, key policy 같은 데이터 모델링 상세
+- table/column 수준 ERD 정의
+- above items belong to [`sdd/01_planning/04_data/README.md`](../04_data/README.md)
+
+## 3. Document Structure
+
+### Root
+
+- 공통/횡단 아키텍처 문서를 둔다.
+- 예:
+  - structure principle
+  - document boundary
+  - migration guide
+  - runtime alignment rule
+
+### frontend/
+
+- 프런트엔드 특화 아키텍처 문서를 둔다.
+- 특정 surface에 종속되더라도 재사용 가능한 구조 원칙이면 여기에 둔다.
+
+### backend/
+
+- 백엔드 특화 아키텍처 문서를 둔다.
+- context structure, layering, pattern, runtime composition을 기록한다.
+
+### infra/
+
+- 인프라 특화 아키텍처 문서를 둔다.
+- deployment topology, networking, orchestration, runtime platform을 기록한다.
+
+### tech-research/
+
+- 인증, 외부 provider, 실험 기술 같은 특정 주제 리서치를 둔다.
+- research는 architecture 하위에 두되 공통 구조 문서와 분리한다.
+
+## 4. Writing Rule
+
+- 공통 문서를 먼저 작성하고, 특화 문서는 필요할 때만 추가한다.
+- 이론 자체보다 현재 repo가 어떤 구조와 구현체를 채택했는지를 우선 기록한다.
+- 여러 대안이 있을 때는 후보 나열로 끝내지 않고 현재 권장안과 이유를 적는다.
+- feature, screen, data 문서가 맡아야 할 내용을 architecture에 중복 기록하지 않는다.

package/sdd/01_planning/03_architecture/backend/README.md

@@ -0,0 +1,10 @@
+# Backend Architecture Planning
+
+- 범위: 백엔드의 공통 구조와 구현 패턴
+- 주요 축:
+  - DDD bounded context
+  - domain/application/infrastructure/contracts layering
+  - 3-layer / hexagonal / monolithic structure
+  - adoption of patterns such as EDA, MSA, CQRS
+  - actual runtime composition and implementation choices
+- entity/schema/relationship 정의는 `04_data`에서 다룬다.

package/sdd/01_planning/03_architecture/frontend/README.md

@@ -0,0 +1,12 @@
+# Frontend Architecture Planning
+
+- 범위: 프런트엔드의 공통 구조와 구현 패턴
+- 주요 축:
+  - 모듈화
+  - 컴포넌트 구조
+  - store/state
+  - domain/use case
+  - UI/UX 패턴
+  - storage/session/cache
+  - API client / facade / adapter
+- 화면별 route/CTA/전이는 `02_screen`에서 다루고, 기능별 business rule은 `01_feature`에서 다룬다.

package/sdd/01_planning/03_architecture/infra/README.md

@@ -0,0 +1,10 @@
+# Infra Architecture Planning
+
+- 범위: 프런트엔드, 백엔드, supporting service를 올리는 기반 구조
+- 주요 축:
+  - docker / compose / kubernetes
+  - container runtime / orchestration
+  - database / storage / secret / network
+  - redundancy / HA / multi-region
+  - deployment topology / runtime boundary
+- 운영 절차 자체는 필요 시 `05_operate` runbook과 분리해 기록한다.

package/sdd/01_planning/03_architecture/tech-research/README.md

@@ -0,0 +1,4 @@
+# Tech Research
+
+- 이 폴더는 architecture 하위의 주제별 기술 리서치를 둔다.
+- 인증, 외부 provider, 실험 기술처럼 공통 구조 문서와 분리할 가치가 있는 주제만 둔다.

package/sdd/01_planning/03_architecture/templates_system_architecture.md

@@ -0,0 +1,84 @@
+# templates system architecture
+
+- 작성 버전: 1.0.0
+
+## Purpose
+
+`templates` 레포의 현재 runtime 구조와 bounded context 경계를 구현 기준으로 정리한다.
+
+## Document Boundary
+
+- frontend, backend, infra 공통 구조와 구현 선택을 이 문서에서 다룬다.
+- entity/schema/relationship/key policy 같은 데이터 모델링 상세는 `sdd/01_planning/04_data/`에서 다룬다.
+
+## 1. Runtime Topology
+
+| Layer | Owner | Responsibility |
+| --- | --- | --- |
+| `server` | HTTP backend | auth, user, catalog, inventory, orders, fulfillment, shipping, alerts, support, health를 HTTP API surface로 제공 |
+| `client/platform` | React + Vite frontend | 보호된 플랫폼 shell과 dashboard/orders surface |
+| `client/admin` | React + Vite frontend | 보호된 관리자 shell과 overview/queue/support surface |
+| `client/mobile` | React + Vite frontend | 보호된 모바일 shell과 dashboard/fulfillment surface |
+| `client/landing` | React + Vite frontend | public landing + protected workspace surface |
+| `infra/compose` | container runtime | root compose baseline + dedicated DEV(개발계)/PROD overlay 레이아웃 |
+
+## 2. Transport Topology
+
+| Surface | Module | Responsibility |
+| --- | --- | --- |
+| HTTP | `server/api/http` | FastAPI app, router aggregation, `/health`, `/api/v1/*` 제공 |
+
+## 3. Backend Context Map
+
+| Bounded Context | Module | Role |
+| --- | --- | --- |
+| Authentication & Session | `server/contexts/auth` | login, bearer token 해석, 인증 계정 저장 |
+| User Directory | `server/contexts/user` | 사용자 profile 목록/상세/상태 관리 |
+| Product Catalog | `server/contexts/catalog` | public catalog read와 admin catalog write |
+| Inventory Availability | `server/contexts/inventory` | SKU/거점 재고 조회와 운영 mutation |
+| Order Operations | `server/contexts/orders` | platform/admin 주문 overview, 목록, 생성, 상태 전이 |
+| Fulfillment Operations | `server/contexts/fulfillment` | mobile overview, board, task 상태 전이 |
+| Shipping Operations | `server/contexts/shipping` | mobile 배송 overview, shipment 목록, 배송 상태 전이 |
+| Alert Center | `server/contexts/alerts` | admin 운영 알람 feed, 읽음 처리 |
+| Support Content | `server/contexts/support` | 관리자 FAQ 목록/작성/노출 상태 변경 |
+| Health | `server/contexts/health` | technical health/status contract |
+
+## 4. Context Relationship
+
+- `auth`는 `user`와 분리된 인증 계정 bootstrap을 사용한다.
+- `user`는 profile directory만 소유하고 credential hash를 저장하지 않는다.
+- `catalog`는 landing/public read와 admin write surface를 함께 소유한다.
+- `inventory`는 현재 admin 운영 surface를 통해 직접 조정되고, `orders`와 `fulfillment`의 참조 도메인으로 연결된다.
+- `orders`는 platform read model과 admin read model을 동시에 노출한다.
+- `fulfillment`는 mobile 서비스의 canonical backend surface다.
+- `shipping`은 `fulfillment`의 downstream delivery 상태를 분리해 mobile/operator surface에 제공한다.
+- `alerts`는 admin이 소비하는 운영 알람 표현과 읽음 상태를 별도 context로 소유한다.
+
+## 5. Layering Rule
+
+- context 외부 진입점은 `contexts/*/contracts/http`에 둔다.
+- application layer는 use case orchestration만 담당한다.
+- domain layer는 request/response model과 aggregate/read model을 가진다.
+- infrastructure layer는 adapter, repository factory, shared gateway binding을 담당한다.
+- shared logic는 `shared/application`, `shared/infrastructure`에 두되, 특정 domain 소유물이 되면 context 내부로 이동한다.
+- transport wiring은 `api/http`에 두고 domain 로직은 `contexts/*`에만 둔다.
+
+## 6. Runtime Component Baseline
+
+| Component | Current Baseline | Next Step |
+| --- | --- | --- |
+| HTTP server | `FastAPI + Uvicorn` | authz, rate limit, observability middleware 추가 |
+| Persistence | bootstrap JSON + selectable DB adapter | transaction boundary와 repository parity 강화 |
+| Frontend runtime | `React 18 + Vite 5 + pnpm workspace` | contract-driven env injection 자동화 |
+
+## 7. Current Known Gaps
+
+- persistence baseline은 여전히 bootstrap JSON + in-memory mutation 중심이다.
+- order 생성과 fulfillment/shipping 전이가 inventory 자동 연동까지는 아직 확장되지 않았다.
+- support는 FAQ 관리 중심이고 ticket/workflow 도메인까지는 아직 포함하지 않는다.
+
+## 8. Next Refactoring Direction
+
+- catalog/inventory/order/fulfillment/shipping 간의 orchestration을 application service 수준으로 확장한다.
+- auth account와 user profile 사이의 provisioning 흐름을 별도 domain service로 일반화한다.
+- admin surface에서 alerts/support/catalog/inventory command를 직접 소비하도록 frontend scope를 넓힌다.

package/sdd/01_planning/04_data/INDEX.md

@@ -0,0 +1,4 @@
+# Data Planning
+
+- [README.md](./README.md)
+- [templates_data_modeling.md](./templates_data_modeling.md)

package/sdd/01_planning/04_data/README.md

@@ -0,0 +1,10 @@
+# Data Planning
+
+- 범위: 공통 데이터 모델과 엔티티 관계 정의
+- architecture 문서에서 다루지 않는 entity/schema/relationship/key policy는 이 루트에서 다룬다.
+- 데이터 모델링은 current canonical 기준만 남기고, 구조 문서와 중복 기록하지 않는다.
+
+## Canonical Docs
+
+- [INDEX.md](./INDEX.md)
+- [templates_data_modeling.md](./templates_data_modeling.md)