speedlogis-tracking-api 분석 보고서

실행 한계

현재 작업 환경은 읽기 전용이며 저장소 파일을 조회·수정·실행할 수 있는 터미널 도구가 제공되지 않았습니다. 따라서 아래 분석은 사용자가 제공한 코드와 설명을 근거로 한 확정 findings입니다.

다음 작업은 수행하지 못했습니다.

• 전체 디렉터리 및 파일 구조 확인
• 실제 의존성·CI·테스트·마이그레이션 검사
• 브랜치 생성 및 코드 수정
• 테스트·정적 분석·취약점 스캔 실행
• 실제 Markdown/JSON/YAML/CSV 파일 생성

시스템 개요

• 저장소: speedlogis-tracking-api
• 런타임: Python 3.11
• 웹 프레임워크: FastAPI
• ORM: SQLAlchemy
• 핵심 경로:
  • app/routers/shipment.py
  • app/services/shipment.py
  • Shipment 모델
  • SessionLocal
  • 데이터베이스 트랜잭션 및 배송 상태 전이 로직

---

Findings

BUG-001 — 비동기 함수가 호출되지 않음

• 심각도: Critical
• 분류: Functional / Integration
• 파일:
  • app/services/shipment.py
  • app/routers/shipment.py

현재 코드:

async def update_status(shipment_id, new_status, db):
    ...

@router.post("/shipments/{id}/status")
def change_status(id: int, status: str):
    update_status(id, status, SessionLocal())
    return {"ok": True}

update_status()는 coroutine을 반환하지만 await하지 않습니다. 따라서 함수 본문이 실행되지 않고, 실제로는 배송 상태가 변경되지 않을 수 있습니다. 일반적으로 다음 경고도 발생합니다.

RuntimeWarning: coroutine 'update_status' was never awaited

예상 동작은 상태 변경 및 커밋 후 성공 응답을 반환하는 것입니다.

수정 방법은 두 가지 중 하나로 일관되게 선택해야 합니다.

권장안: 동기 SQLAlchemy 세션을 계속 사용할 경우

def update_status(shipment_id: int, new_status: str, db: Session) -> Shipment:
    ...

@router.post("/shipments/{id}/status")
def change_status(
    id: int,
    status: str,
    db: Session = Depends(get_db),
):
    shipment = update_status(id, status, db)
    return {"ok": True, "status": shipment.status}

비동기 SQLAlchemy를 사용할 경우

@router.post("/shipments/{id}/status")
async def change_status(
    id: int,
    status: str,
    db: AsyncSession = Depends(get_async_db),
):
    shipment = await update_status(id, status, db)
    return {"ok": True, "status": shipment.status}

---

BUG-002 — 동시 업데이트에서 상태 및 카운터가 유실됨

• 심각도: High
• 분류: Concurrency / Data Integrity
• 파일: app/services/shipment.py

현재 로직은 전형적인 lost update 문제가 있습니다.

shipment = db.query(Shipment).get(shipment_id)
shipment.status = new_status
shipment.updated_count += 1
db.commit()

두 요청이 동시에 실행되면 다음과 같은 상황이 가능합니다.

시점	요청 A	요청 B
1	상태 READY, count 10 조회
2		상태 READY, count 10 조회
3	상태를 SHIPPED, count 11로 변경
4		상태를 DELIVERED, count 11로 변경
5	커밋	커밋

결과:

• 마지막 요청의 상태만 남음
• updated_count는 12가 아닌 11
• 상태 전이 순서를 검증할 수 없음
• 클라이언트는 둘 다 성공 응답을 받을 수 있음

최소 수정안: 행 잠금

동기 SQLAlchemy 기준:

from fastapi import HTTPException
from sqlalchemy.orm import Session

def update_status(
    shipment_id: int,
    new_status: str,
    db: Session,
) -> Shipment:
    try:
        with db.begin():
            shipment = (
                db.query(Shipment)
                .filter(Shipment.id == shipment_id)
                .with_for_update()
                .one_or_none()
            )

            if shipment is None:
                raise HTTPException(status_code=404, detail="Shipment not found")

            shipment.status = new_status
            shipment.updated_count += 1
            db.flush()

            return shipment

    except HTTPException:
        raise
    except Exception:
        db.rollback()
        raise

주의 사항:

• with_for_update()는 트랜잭션 내부에서 사용해야 합니다.
• SQLite에서는 행 잠금이 제한적이므로 PostgreSQL 또는 실제 운영 DB에서 검증해야 합니다.
• 단순히 Python에서 updated_count += 1을 수행하는 것보다 DB 행 잠금이 중요합니다.

라우터는 세션을 직접 생성하지 말고 의존성으로 주입해야 합니다.

@router.post("/shipments/{id}/status")
def change_status(
    id: int,
    status: str,
    db: Session = Depends(get_db),
):
    shipment = update_status(id, status, db)
    return {
        "ok": True,
        "status": shipment.status,
        "updated_count": shipment.updated_count,
    }

---

BUG-003 — 요청마다 생성한 DB 세션이 닫히지 않음

• 심각도: High
• 분류: Resource Management
• 파일: app/routers/shipment.py

현재 코드는 다음과 같습니다.

SessionLocal()

생성한 세션을 닫지 않습니다. 요청이 반복되면 커넥션 풀이 고갈되거나 장시간 실행 후 API가 데이터베이스 연결을 획득하지 못할 수 있습니다.

권장 패턴:

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

그리고 라우터에서:

db: Session = Depends(get_db)

서비스 계층이 세션을 생성하거나 닫는 것이 아니라, 요청 수명주기를 관리하는 FastAPI dependency가 담당해야 합니다.

---

BUG-004 — 존재하지 않는 배송에 대한 null 처리 없음

• 심각도: Medium
• 분류: Edge Case / API Contract

현재 코드에서는 조회 결과가 None일 때 다음 코드가 실행됩니다.

shipment.status = new_status

그 결과 AttributeError 및 HTTP 500이 발생합니다.

예상 응답은 다음과 같아야 합니다.

404 Not Found

수정 예시는 BUG-002의 one_or_none() 및 HTTPException(404)를 사용하면 됩니다.

---

BUG-005 — Query.get() 사용

• 심각도: Medium
• 분류: Maintainability / Deprecated API

db.query(Shipment).get(shipment_id)

SQLAlchemy 2.x에서는 Query.get()보다 Session.get() 또는 select() 사용이 권장됩니다.

동기 코드:

shipment = db.get(Shipment, shipment_id)

잠금과 함께 조회해야 한다면:

shipment = (
    db.query(Shipment)
    .filter(Shipment.id == shipment_id)
    .with_for_update()
    .one_or_none()
)

---

BUG-006 — 상태 전이 규칙 및 입력 검증 부재

• 심각도: High
• 분류: Functional / Data Integrity

status: str를 그대로 저장하므로 다음 문제가 발생할 수 있습니다.

• 임의 문자열 저장
• 오타 상태 저장
• 허용되지 않은 상태 역행
• 예: DELIVERED → READY
• 상태별 비즈니스 규칙 우회

Pydantic enum을 사용하는 것이 좋습니다.

from enum import StrEnum
from pydantic import BaseModel

class ShipmentStatus(StrEnum):
    READY = "READY"
    SHIPPED = "SHIPPED"
    IN_TRANSIT = "IN_TRANSIT"
    DELIVERED = "DELIVERED"
    CANCELLED = "CANCELLED"

class StatusUpdateRequest(BaseModel):
    status: ShipmentStatus

상태 전이도 검증해야 합니다.

ALLOWED_TRANSITIONS = {
    ShipmentStatus.READY: {
        ShipmentStatus.SHIPPED,
        ShipmentStatus.CANCELLED,
    },
    ShipmentStatus.SHIPPED: {
        ShipmentStatus.IN_TRANSIT,
        ShipmentStatus.CANCELLED,
    },
    ShipmentStatus.IN_TRANSIT: {
        ShipmentStatus.DELIVERED,
    },
    ShipmentStatus.DELIVERED: set(),
    ShipmentStatus.CANCELLED: set(),
}

---

BUG-007 — 트랜잭션 실패 시 rollback 보장 없음

• 심각도: High
• 분류: Integration / Reliability

commit()이 실패했을 때 명시적 rollback이 없습니다. 세션이 실패 상태에 남으면 동일 세션을 재사용하는 후속 작업도 실패할 수 있습니다.

최소한 다음 구조를 보장해야 합니다.

try:
    db.commit()
except Exception:
    db.rollback()
    raise

다만 가장 안전한 방식은 with db.begin():을 사용하는 것입니다.

---

BUG-008 — 라우터에서 서비스 예외를 숨길 가능성

• 심각도: Medium
• 분류: API Reliability

현재 라우터는 서비스 호출 결과나 오류를 처리하지 않고 항상 성공 응답을 반환합니다.

update_status(...)
return {"ok": True}

실제 구현에서도 coroutine 미실행, DB 오류, 대상 없음 등의 오류가 응답에 반영되지 않을 가능성이 있습니다. 성공 응답은 커밋이 완료된 뒤에만 반환되어야 합니다.

---

권장 수정 우선순위

우선순위	BUG-ID	조치
P0	BUG-001	async/sync 호출 방식 일치
P0	BUG-002	행 잠금 또는 optimistic locking 적용
P1	BUG-003	DB 세션 dependency 및 close 보장
P1	BUG-006	상태 enum 및 전이 규칙 검증
P1	BUG-007	rollback 및 트랜잭션 경계 보장
P2	BUG-004	404 처리
P2	BUG-005	SQLAlchemy 현대 API로 변경
P2	BUG-008	성공·실패 응답 계약 정리

---

반드시 추가해야 할 테스트

1. 정상 상태 변경

def test_update_status(client, shipment):
    response = client.post(
        f"/shipments/{shipment.id}/status",
        json={"status": "SHIPPED"},
    )

    assert response.status_code == 200
    assert response.json()["status"] == "SHIPPED"

2. 존재하지 않는 배송

def test_update_missing_shipment_returns_404(client):
    response = client.post(
        "/shipments/999999/status",
        json={"status": "SHIPPED"},
    )

    assert response.status_code == 404

3. 잘못된 상태

def test_invalid_status_returns_422(client, shipment):
    response = client.post(
        f"/shipments/{shipment.id}/status",
        json={"status": "NOT_A_REAL_STATUS"},
    )

    assert response.status_code == 422

4. 허용되지 않은 상태 역행

def test_invalid_transition_returns_409(client, delivered_shipment):
    response = client.post(
        f"/shipments/{delivered_shipment.id}/status",
        json={"status": "READY"},
    )

    assert response.status_code == 409

5. 동시성 회귀 테스트

PostgreSQL 테스트 DB에서 두 트랜잭션을 동시에 실행해야 합니다.

검증 조건:

assert final_shipment.updated_count == initial_count + 2

행 잠금을 적용한 경우 두 업데이트가 직렬화되어야 합니다. 동시에 상태 전이가 허용되지 않는 정책이라면 한 요청은 409 Conflict가 되어야 합니다.

---

동시성 정책 결정 필요

현재 요구사항만으로는 두 명의 변경을 모두 허용할지, 하나만 허용할지 명확하지 않습니다.

정책 A: 모든 상태 변경을 순서대로 허용

• SELECT ... FOR UPDATE
• 트랜잭션 안에서 상태 조회·검증·변경
• updated_count 증가 보장

정책 B: 오래된 클라이언트의 변경 거부

Shipment에 버전 컬럼을 추가합니다.

version_id = Column(Integer, nullable=False, default=1)

SQLAlchemy optimistic locking을 적용하고 충돌 시 409 Conflict를 반환합니다.

배송 추적 시스템에서는 일반적으로 상태의 순서와 감사 가능성이 중요하므로, 상태 전이 검증이 필요한 경우 정책 A 또는 A+B 조합을 권장합니다.

---

JSON 보고서

{
  "repository": "speedlogis-tracking-api",
  "analysis_basis": "user-provided source excerpts",
  "environment_limitation": {
    "filesystem": "read-only",
    "tests_executed": false,
    "dependency_scan_executed": false,
    "files_modified": false,
    "branch_created": false
  },
  "findings": [
    {
      "id": "BUG-001",
      "severity": "critical",
      "category": ["functional", "integration"],
      "files": [
        "app/services/shipment.py",
        "app/routers/shipment.py"
      ],
      "summary": "async update_status is called without await",
      "recommended_fix": "Use async route with await, or make service synchronous"
    },
    {
      "id": "BUG-002",
      "severity": "high",
      "category": ["concurrency", "data-integrity"],
      "files": ["app/services/shipment.py"],
      "summary": "Lost update during concurrent status changes",
      "recommended_fix": "Use SELECT FOR UPDATE or optimistic locking"
    },
    {
      "id": "BUG-003",
      "severity": "high",
      "category": ["resource-management"],
      "files": ["app/routers/shipment.py"],
      "summary": "Database session is created but not closed",
      "recommended_fix": "Inject session through FastAPI dependency"
    },
    {
      "id": "BUG-004",
      "severity": "medium",
      "category": ["edge-case"],
      "summary": "Missing shipment causes AttributeError",
      "recommended_fix": "Return HTTP 404"
    },
    {
      "id": "BUG-005",
      "severity": "medium",
      "category": ["maintenance"],
      "summary": "Query.get is deprecated in modern SQLAlchemy",
      "recommended_fix": "Use Session.get or select"
    },
    {
      "id": "BUG-006",
      "severity": "high",
      "category": ["validation", "data-integrity"],
      "summary": "Arbitrary status strings and invalid transitions are accepted",
      "recommended_fix": "Use enum and transition validation"
    },
    {
      "id": "BUG-007",
      "severity": "high",
      "category": ["transaction"],
      "summary": "Rollback is not guaranteed after commit failure",
      "recommended_fix": "Use transaction context manager"
    },
    {
      "id": "BUG-008",
      "severity": "medium",
      "category": ["api-reliability"],
      "summary": "Router may return success without confirmed update",
      "recommended_fix": "Return success only after committed transaction"
    }
  ]
}

CSV 보고서

BUG-ID,Severity,Category,Files,Summary,Recommended Fix
BUG-001,Critical,Functional/Integration,app/services/shipment.py;app/routers/shipment.py,Coroutine is not awaited,Align async/sync implementation
BUG-002,High,Concurrency/Data Integrity,app/services/shipment.py,Lost update under concurrent requests,SELECT FOR UPDATE or optimistic locking
BUG-003,High,Resource Management,app/routers/shipment.py,Database session is not closed,FastAPI dependency with finally close
BUG-004,Medium,Edge Case,app/services/shipment.py,Missing shipment causes server error,Return 404
BUG-005,Medium,Maintenance,app/services/shipment.py,Deprecated Query.get usage,Use Session.get/select
BUG-006,High,Validation/Data Integrity,app/routers/shipment.py,Invalid statuses and transitions accepted,Enum and transition validation
BUG-007,High,Transaction,app/services/shipment.py,Rollback not guaranteed,Use transaction context manager
BUG-008,Medium,API Reliability,app/routers/shipment.py,Success may be returned without update,Return after successful commit

결론

제공된 코드만으로도 최소 2개의 즉시 수정 대상이 확인됩니다.

1. async update_status()를 await하지 않는 호출 오류
2. 동시 요청에서 status와 updated_count가 유실되는 트랜잭션 경쟁 조건

운영 장애와 데이터 정합성 측면에서는 먼저 동기/비동기 모델을 통일하고, DB 세션 dependency와 SELECT FOR UPDATE 기반 트랜잭션을 적용한 뒤 PostgreSQL 동시성 회귀 테스트를 추가해야 합니다.