be-stack-and-commands — GS Retail BE 표준 기술 스택과 명령어 기준선

레이어드 아키텍처

flask-app-architecture 핵심 제약:

• 모듈 전역 app = Flask(__name__) 절대 금지 → 항상 create_app() factory
• extension 객체는 unbound로 모듈 상단 선언, factory 안에서 ext.init_app(app)
• Blueprint 등록은 factory 안에서만
• 비즈니스 로직은 Flask를 import하지 않음

# ❌ 금지 패턴 — 모듈 전역 app
app = Flask(__name__)
db = SQLAlchemy(app)  # 이 패턴은 테스트와 팩토리 패턴을 막음

# ✅ application factory + unbound extensions
db = SQLAlchemy()  # unbound

def create_app(config=None):
    app = Flask(__name__)
    db.init_app(app)
    app.register_blueprint(api_bp)
    return app

openapi-first-contract: OpenAPI YAML → SSOT. 손으로 생성 트리 편집 금지. Connexion이 spec에서 라우팅/검증 수행.

# Connexion은 operationId를 hand-written handler로 연결
# openapi.yaml
paths:
  /api/users:
    get:
      operationId: app.handlers.users.list_users  # ← 이 함수가 실제 구현

# handlers/users.py — Flask import 없음
def list_users(limit: int = 20) -> list[User]:
    return user_service.list(limit=limit)

api-error-and-health: 글로벌 에러 핸들러, liveness/readiness 엔드포인트, 구조화 로그 (request ID 포함).

dynamodb-data-access 핵심 제약:

• 모든 boto3 코드는 repository seam 뒤에. service layer는 AbstractRepository에만 의존.
• access-pattern first: GSI 설계는 쿼리 패턴에서 시작. full-scan/N+1 금지.
• 개발은 local-first: DynamoDB Local (Docker). AWS는 준비됐을 때 connect.
• 테이블 프로비저닝은 IaC (CDK/SAM/Terraform). app 코드에서 create_table 호출 금지.
• FakeRepository (in-memory dict)로 서비스 레이어 단위 테스트. moto로 repository 테스트.

# AbstractRepository seam
class AbstractUserRepository(ABC):
    @abstractmethod
    def get(self, user_id: str) -> User | None: ...

    @abstractmethod
    def save(self, user: User) -> None: ...

# DynamoDB 구현
class DynamoUserRepository(AbstractUserRepository):
    def __init__(self, table_name: str):
        self._table = boto3.resource('dynamodb').Table(table_name)  # boto3는 여기만

# 테스트용 FakeRepository
class FakeUserRepository(AbstractUserRepository):
    def __init__(self): self._store: dict[str, User] = {}
    def get(self, user_id: str) -> User | None: return self._store.get(user_id)

python-type-hints: 모든 public 함수에 type annotation. mypy로 검사 (gradual, ratcheting). 도메인 엔티티는 dataclass/Pydantic으로 명시적 정의.

# ✅ 완전한 type annotation
from dataclasses import dataclass
from typing import Optional

@dataclass
class User:
    id: str
    name: str
    role: str
    email: Optional[str] = None

def get_user(user_id: str) -> Optional[User]:
    ...

# mypy 설정 (pyproject.toml)
[tool.mypy]
python_version = "3.11"
strict = true

• plan-first: 코드 전에 구현 계획 (레이어 설계, 함수 시그니처, 변경 파일)
• be-tdd: Red-Green-Refactor — 실패하는 pytest (서비스 유닛 테스트 또는 test_client 기능 테스트) 먼저
• cleanup-after-green: 테스트 통과 후 ruff format, 죽은 import 제거, print 삭제
• codegraph-first: 파일 직접 grep/read보다 CodeGraph 지식 그래프 (심볼, 콜 그래프, 영향) 우선 사용

• backend-api-access-control: BOLA 방지 (객체 레벨 권한), 모든 요청 인증, 비밀 정보는 env/Secrets Manager, IAM 최소 권한 (특정 table/index ARN 범위), CORS 허용 목록, rate limiting, 보안 헤더
• no-hardcoded-secrets: 소스 코드에 API 키/토큰/비밀 커밋 금지
• sanitize-untrusted-input: 모든 외부 입력을 신뢰 불가로 처리. SQL/command injection, path traversal 방지
• mask-pii: 로그/에러/애널리틱스에 원시 PII/토큰/자격증명 노출 금지

# ✅ BOLA 방지 예시 — 항상 current user의 소유권 확인
@require_auth
def get_document(document_id: str, current_user: User) -> Document:
    doc = document_repo.get(document_id)
    if doc.owner_id != current_user.id:  # 소유권 검증 필수
        raise Forbidden("Not your document")
    return doc

• python-casing: snake_case (함수/변수/모듈/파일), PascalCase (클래스), UPPER_SNAKE_CASE (상수)
• commits: Conventional Commits, 명령형 제목
• language-policy: 코드/커밋=영어, PR/UI=한국어
• no-comments: WHY가 자명하지 않은 경우에만 주석. 코드가 WHAT을 설명해야 함. 멀티라인 docstring 금지.
• autonomous-retry: 빌드/lint/테스트 실패 시 최대 3회 자율 수정
• protected-config-be: pyproject.toml, uv.lock, OpenAPI spec, IaC, CI 설정 수동 승인 없이 수정 금지