영업용 보세화물 관리 시스템

세관의 통제를 받는 특수성 때문에 반입부터 보수작업, 통관, 반출까지의 이력을 추구 관리하는 것이 핵심이죠.

보세화물 시스템은 화물의 위치와 상태를 실시간으로 추적하고, 세관 신고 번호와 연동되어야 합니다. 특히 영업용 창고는 여러 화주의 물건을 동시에 관리하므로 화주별, 화물관리번호별 관리가 필수적입니다.

 

---

데이터베이스 모델링 (ERD)

장치장 관리를 위해 필요한 테이블은 크게 5가지 영역으로 나뉩니다.

1. 기본 마스터 정보

창고에 등록된 화주(고객사)와 창고 내부의 구역(Location) 정보를 저장합니다.

CREATE TABLE shippers (
    shipper_id INT PRIMARY KEY AUTO_INCREMENT,
    shipper_name VARCHAR(100) NOT NULL,
    business_reg_no VARCHAR(20) UNIQUE,
    contact_person VARCHAR(50),
    phone_number VARCHAR(20)
);

CREATE TABLE locations (
    location_id VARCHAR(10) PRIMARY KEY, -- 예: A-01-101
    zone_name VARCHAR(50),
    storage_type ENUM('냉동', '냉장', '상온', '위험물'),
    is_occupied BOOLEAN DEFAULT FALSE
);

2. 화물 메인 정보 (Cargo Master)

가장 중요한 테이블입니다. B/L(Bill of Lading) 번호와 관세청에서 부여하는 화물관리번호를 기준으로 관리합니다.

CREATE TABLE cargo_master (
    cargo_id INT PRIMARY KEY AUTO_INCREMENT,
    cargo_mgmt_no VARCHAR(20) UNIQUE, -- 화물관리번호
    bl_no VARCHAR(20) NOT NULL,       -- B/L 번호
    shipper_id INT,
    item_name VARCHAR(200),
    total_quantity INT,
    total_weight DECIMAL(10, 2),
    unit VARCHAR(10),
    arrival_date DATE,
    status ENUM('반입예정', '장치중', '통관완료', '반출완료'),
    FOREIGN KEY (shipper_id) REFERENCES shippers(shipper_id)
);

3. 반출입 및 이력 관리

화물이 실제로 창고에 들어오고 나가는 모든 움직임을 기록합니다. 보세화물은 부분 반출이 빈번하므로 이력 관리가 매우 중요합니다.

CREATE TABLE warehouse_logs (
    log_id INT PRIMARY KEY AUTO_INCREMENT,
    cargo_id INT,
    location_id VARCHAR(10),
    log_type ENUM('IN', 'OUT', 'MOVE'), -- 반입, 반출, 위치이동
    quantity INT,
    log_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    remarks TEXT,
    FOREIGN KEY (cargo_id) REFERENCES cargo_master(cargo_id),
    FOREIGN KEY (location_id) REFERENCES locations(location_id)
);

---

프로젝트 구현 시 유의사항

1. 화물관리번호 체계 보세화물은 관세청에서 부여하는 19자리 혹은 15자리의 화물관리번호를 가집니다. 이를 PK 또는 Unique Index로 설정하여 중복 반입을 방지해야 합니다.
2. 선입선출 및 장치 기간 관리 보세구역은 화물을 장치할 수 있는 기간이 정해져 있습니다. 체화(장기간 방치된 화물)를 방지하기 위해 입고일 기준 알림 기능을 구현하는 것이 좋습니다.
3. 보수작업 기록 창고 내에서 라벨링이나 재포장(보수작업)이 일어날 경우, 이에 따른 수량 변화나 상태 변화를 별도 테이블로 관리해야 세관 감사 시 대응이 가능합니다.

728x90

프로젝트 핵심 구성 요소

보세구역 화물관리는 일반 WMS에 통관 상태 추적과 보관료 정산 로직이 결합된 형태입니다.

 

---

DB 설계 확장 (MySQL)

화물의 상태 변화와 돈이 되는 보관료 정산 부분을 보강한 설계입니다.

1. 통관 상태 및 보증 관리

보세화물은 통관이 완료되어야만 외부로 나갈 수 있습니다. 이를 관리하기 위한 상태 테이블이 필요합니다.

CREATE TABLE customs_clearance (
    clearance_id INT PRIMARY KEY AUTO_INCREMENT,
    cargo_id INT,
    declaration_no VARCHAR(25) UNIQUE, -- 수입신고번호
    clearance_status ENUM('미신고', '신고완료', '수리완료', '보완요구'),
    clearance_date DATETIME,
    customs_officer VARCHAR(50),
    FOREIGN KEY (cargo_id) REFERENCES cargo_master(cargo_id)
);

2. 보관료 정산 마스터 (Billing)

영업용 창고의 수익 모델인 보관료를 계산하기 위한 설정입니다. 종량제(무게/부피) 또는 종가제(가격) 기준을 설정합니다.

CREATE TABLE billing_rules (
    rule_id INT PRIMARY KEY AUTO_INCREMENT,
    item_category VARCHAR(50),
    daily_rate_per_kg DECIMAL(10, 2),
    min_charge DECIMAL(10, 2),
    handling_fee DECIMAL(10, 2) -- 상하차비
);

CREATE TABLE invoices (
    invoice_id INT PRIMARY KEY AUTO_INCREMENT,
    cargo_id INT,
    shipper_id INT,
    total_amount DECIMAL(15, 2),
    billing_start_date DATE,
    billing_end_date DATE,
    is_paid BOOLEAN DEFAULT FALSE,
    FOREIGN KEY (cargo_id) REFERENCES cargo_master(cargo_id),
    FOREIGN KEY (shipper_id) REFERENCES shippers(shipper_id)
);

---

개발 시나리오 가이드

1. 반입 단계 화물이 입항하여 창고에 도착하면 화물관리번호를 키값으로 입고 등록을 합니다. 이때 보세구역 내 로케이션(A구역, B구역 등)을 배정합니다.
2. 장치 중 단계 세관의 검사 대상(C/S)으로 지정될 경우 해당 화물의 로케이션 이동이나 보수작업(라벨링) 이력을 기록합니다. 시스템상에서 장치기간 만료 15일 전 알림을 띄워 체화를 방지합니다.
3. 반출 단계 화주로부터 화물인도지시서(D/O)가 접수되고, 통관 상태가 수리완료인 경우에만 시스템에서 반출 승인 처리가 가능하도록 로직을 설계합니다. 이때 보관 일수에 따른 비용이 자동 계산됩니다.

---

728x90

보세화물은 창고 내에서 라벨 부착이나 재포장 같은 보수작업(Maintenance)이 빈번하게 일어나며 이는 모두 세관 보고 대상입니다.

---

보수작업 및 정산 로직 확장 (MySQL)

1. 보수작업 관리 (Maintenance Work)

화물의 원상태를 변경하거나 가공하는 작업을 기록합니다. 세관의 승인 번호와 작업 전후의 상태를 비교 관리해야 합니다.

CREATE TABLE maintenance_logs (
    work_id INT PRIMARY KEY AUTO_INCREMENT,
    cargo_id INT,
    work_type ENUM('분할', '합병', '라벨링', '재포장'),
    request_date DATETIME,
    approval_no VARCHAR(50), -- 세관 승인 번호
    before_qty INT,
    after_qty INT,
    worker_name VARCHAR(50),
    FOREIGN KEY (cargo_id) REFERENCES cargo_master(cargo_id)
);

2. 일별 재고 및 보관료 집계 (Daily Inventory Snapshot)

영업용 창고는 매일 밤 12시 기준으로 재고를 파악하여 보관료를 누적해야 합니다. 이 테이블은 정산의 근거가 됩니다.

CREATE TABLE daily_stock_snapshots (
    snapshot_date DATE,
    cargo_id INT,
    current_qty INT,
    current_weight DECIMAL(10, 2),
    daily_fee DECIMAL(15, 2), -- 해당 날짜에 발생한 보관료
    PRIMARY KEY (snapshot_date, cargo_id),
    FOREIGN KEY (cargo_id) REFERENCES cargo_master(cargo_id)
);

---

프로젝트 구현 팁: 핵심 알고리즘

보관료 자동 계산 로직 (Stored Procedure 활용)

매일 정해진 시간에 실행되어 보관료를 계산하는 로직 예시입니다.

1. cargo_master에서 상태가 장치중인 화물을 조회합니다.
2. billing_rules 테이블의 요율과 화물의 무게/CBM을 곱합니다.
3. 결과를 daily_stock_snapshots에 인서트하여 반출 시 합산합니다.

통관 및 반출 유효성 검사

반출 로직 구현 시 반드시 체크해야 할 3단계 조건입니다.

• 수입신고수리 여부: customs_clearance 테이블의 상태가 수리완료인가?
• 보관료 완납 여부: invoices 테이블의 결제 상태가 TRUE인가?
• 화물관리번호 일치: 실제 출고되는 화물 태그와 시스템 번호가 일치하는가?

---

마무리를 위한 추천 기능

이 프로젝트를 포트폴리오로 만드신다면 대시보드 기능을 추가해 보세요. 현재 창고 점유율(Location 테이블 기준), 이번 달 예상 매출(Invoices 기준), 그리고 장치기간이 임박한 화물 리스트를 시각화하면 실무적인 느낌을 줄 수 있습니다.

---

프로젝트 기술 스택

Backend: NestJS, Prisma ORM, PostgreSQL 또는 MySQL Frontend: Nuxt 3, Tailwind CSS, Pinia (상태 관리) Communication: REST API 또는 GraphQL

1. Prisma Schema 설계

먼저 Prisma 모델을 정의합니다. 앞서 설계한 DB 구조를 Prisma 문법으로 변환하여 데이터 관계를 명확히 합니다.

// schema.prisma

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Shipper {
  id              Int           @id @default(autoincrement())
  shipperName     String
  businessRegNo   String        @unique
  contactPerson   String?
  cargoes         CargoMaster[]
}

model CargoMaster {
  id              Int           @id @default(autoincrement())
  cargoMgmtNo     String        @unique
  blNo            String
  shipperId       Int
  shipper         Shipper       @relation(fields: [shipperId], references: [id])
  status          CargoStatus   @default(PENDING)
  arrivalDate     DateTime      @default(now())
  logs            WarehouseLog[]
  clearance       CustomsClearance?
}

enum CargoStatus {
  PENDING    // 반입예정
  STORED     // 장치중
  CLEARED    // 통관완료
  RELEASED   // 반출완료
}

model WarehouseLog {
  id          Int       @id @default(autoincrement())
  cargoId     Int
  cargo       CargoMaster @relation(fields: [cargoId], references: [id])
  locationId  String
  logType     LogType
  createdAt   DateTime  @default(now())
}

enum LogType {
  IN, OUT, MOVE
}

model CustomsClearance {
  id             Int          @id @default(autoincrement())
  cargoId        Int          @unique
  cargo          CargoMaster  @relation(fields: [cargoId], references: [id])
  declarationNo  String?      @unique
  status         String       @default("미신고")
}

2. NestJS Backend 구현 (Service 로직)

화물 반입 시 로케이션 상태를 변경하고 로그를 남기는 핵심 비즈니스 로직입니다.

// src/cargo/cargo.service.ts
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma.service';

@Injectable()
export class CargoService {
  constructor(private prisma: PrismaService) {}

  async processInbound(cargoId: number, locationId: string) {
    return this.prisma.$transaction(async (tx) => {
      // 1. 화물 상태 업데이트
      const cargo = await tx.cargoMaster.update({
        where: { id: cargoId },
        data: { status: 'STORED' },
      });

      // 2. 창고 위치 이력 기록
      await tx.warehouseLog.create({
        data: {
          cargoId,
          locationId,
          logType: 'IN',
        },
      });

      return cargo;
    });
  }
}

3. NuxtJS Frontend 구현 (대시보드 UI)

화물 현황을 한눈에 볼 수 있는 데이터 테이블과 상태 필터링을 구현합니다.

<template>
  <div class="p-6">
    <h1 class="text-2xl font-bold mb-4">보세화물 장치 현황</h1>
    
    <div class="overflow-x-auto bg-white rounded-lg shadow">
      <table class="min-w-full table-auto">
        <thead class="bg-gray-50">
          <tr>
            <th class="px-6 py-3 text-left">화물관리번호</th>
            <th class="px-6 py-3 text-left">B/L 번호</th>
            <th class="px-6 py-3 text-left">화주명</th>
            <th class="px-6 py-3 text-left">상태</th>
            <th class="px-6 py-3 text-left">관리</th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="cargo in cargoes" :key="cargo.id" class="border-b">
            <td class="px-6 py-4">{{ cargo.cargoMgmtNo }}</td>
            <td class="px-6 py-4">{{ cargo.blNo }}</td>
            <td class="px-6 py-4">{{ cargo.shipper.shipperName }}</td>
            <td class="px-6 py-4">
              <span :class="statusBadgeClass(cargo.status)">
                {{ cargo.status }}
              </span>
            </td>
            <td class="px-6 py-4">
              <button @click="viewDetail(cargo.id)" class="text-blue-600">상세보기</button>
            </td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>
</template>

<script setup>
const { data: cargoes } = await useFetch('/api/cargo');

const statusBadgeClass = (status) => {
  if (status === 'STORED') return 'bg-green-100 text-green-800 px-2 py-1 rounded';
  if (status === 'PENDING') return 'bg-yellow-100 text-yellow-800 px-2 py-1 rounded';
  return 'bg-gray-100 text-gray-800 px-2 py-1 rounded';
}
</script>

 

---

개발 고도화 포인트

1. 서버 측 유효성 검사 (Validation) NestJS의 class-validator를 사용하여 반입 시 필수 값(화물번호 등)이 누락되지 않도록 강제합니다.
2. 실시간 알림 (WebSocket) 통관 상태가 '수리완료'로 변경될 때 NuxtJS 화면에 실시간 푸시 알림을 띄워 관리자가 즉시 반출 준비를 할 수 있게 합니다.
3. PDF 보고서 출력 화물인도지시서(D/O)나 입고확인서를 PDF로 생성하는 라이브러리를 NestJS에 추가하여 업무 효율을 높입니다.

---

NestJS와 Nuxt 3를 연동하여 실제 비즈니스 흐름을 제어할 수 있는 핵심 인증 로직과 입고 프로세스 API 규격을 설계해 드릴게요. 보세화물 관리자는 보안이 중요하므로 JWT 기반의 인증이 필수입니다.

---

1. NestJS: 화물 입고 처리를 위한 Controller & DTO

데이터가 들어올 때 형식을 강제하기 위해 class-validator를 활용한 DTO를 정의하고 API 엔드포인트를 생성합니다.

// src/cargo/dto/create-inbound.dto.ts
import { IsString, IsInt, IsNotEmpty } from 'class-validator';

export class CreateInboundDto {
  @IsString()
  @IsNotEmpty()
  cargoMgmtNo: string;

  @IsString()
  @IsNotEmpty()
  locationId: string;

  @IsInt()
  @IsNotEmpty()
  shipperId: number;
}

// src/cargo/cargo.controller.ts
@Controller('api/cargo')
export class CargoController {
  constructor(private readonly cargoService: CargoService) {}

  @Post('inbound')
  @UseGuards(JwtAuthGuard) // 인증된 관리자만 접근 가능
  async inbound(@Body() dto: CreateInboundDto) {
    return this.cargoService.processInbound(dto);
  }
}

2. Nuxt 3: Server Engine (Nitro) 및 Fetch 연동

Nuxt 3에서는 useFetch를 사용하여 서버 데이터를 가져오고, 클라이언트 측에서 상태 관리를 수행합니다.

// composables/useCargo.js
export const useCargo = () => {
  const config = useRuntimeConfig();
  
  const registerInbound = async (formData) => {
    const { data, error } = await useFetch('/api/cargo/inbound', {
      method: 'POST',
      baseURL: config.public.apiBase,
      body: formData,
      headers: {
        Authorization: `Bearer ${useCookie('auth_token').value}`
      }
    });
    
    if (error.value) throw error.value;
    return data.value;
  };

  return { registerInbound };
};

3. 화면 UI: 입고 등록 폼 (Tailwind CSS)

사용자가 화물 정보를 입력하고 로케이션을 지정하는 입력 폼 구성입니다.

<template>
  <form @submit.prevent="handleInbound" class="space-y-4 bg-white p-6 shadow rounded">
    <div>
      <label class="block text-sm font-medium gray-700">화물관리번호</label>
      <input v-model="form.cargoMgmtNo" type="text" class="w-full border p-2 rounded" placeholder="19자리 번호 입력" />
    </div>
    <div>
      <label class="block text-sm font-medium gray-700">배정 로케이션</label>
      <select v-model="form.locationId" class="w-full border p-2 rounded">
        <option value="A-101">A구역 101</option>
        <option value="B-201">B구역 201</option>
      </select>
    </div>
    <button type="submit" class="w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700">
      화물 반입 승인
    </button>
  </form>
</template>

<script setup>
const form = ref({ cargoMgmtNo: '', locationId: '', shipperId: 1 });
const { registerInbound } = useCargo();

const handleInbound = async () => {
  try {
    await registerInbound(form.value);
    alert('반입 처리가 완료되었습니다.');
  } catch (err) {
    alert('처리 중 오류가 발생했습니다.');
  }
};
</script>

---

개발 고도화 제언

1. 통관 API 연동 (Cron Job) NestJS의 @nestjs/schedule을 사용하여 1시간마다 관세청 유니패스 API를 호출하고, customs_clearance 테이블의 상태를 자동으로 업데이트하는 스케줄러를 추가해 보세요.
2. 권한 분리 (RBAC) 관리자(Admin)는 입출고 승인을 하고, 화주(Shipper)는 본인의 화물 위치와 보관료 발생 현황만 조회할 수 있도록 Prisma의 미들웨어나 NestJS Guards로 권한을 제어하면 완벽합니다.
3. 바코드/QR 코드 생성 화물 입고 시 로케이션 정보가 담긴 라벨을 출력할 수 있도록 간단한 QR 생성 라이브러리를 연결하면 실무 현장에서 바로 사용 가능한 수준이 됩니다.

---

보세화물 시스템의 실질적인 완성도를 높이기 위해 영업용 창고의 수익과 직결되는 보관료 정산(Billing) 자동화 로직과 통관 상태 연동 모듈을 구체화해 드릴게요.

 

---

1. NestJS: 보관료 자동 계산 스케줄러 (Cron Job)

매일 자정마다 장치 중인 모든 화물의 보관료를 계산하여 누적하는 기능입니다. 영업용 창고에서는 이 기록이 곧 청구서(Invoice)의 근거가 됩니다.

// src/billing/billing.scheduler.ts
import { Injectable } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { PrismaService } from '../prisma.service';

@Injectable()
export class BillingScheduler {
  constructor(private prisma: PrismaService) {}

  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
  async calculateDailyStorageFee() {
    // 1. 현재 창고에 장치 중인(STORED) 화물 목록 조회
    const activeCargoes = await this.prisma.cargoMaster.findMany({
      where: { status: 'STORED' },
      include: { billingRule: true }
    });

    // 2. 각 화물별 일일 보관료 계산 및 스냅샷 저장
    for (const cargo of activeCargoes) {
      const dailyFee = cargo.weight * cargo.billingRule.dailyRatePerKg;
      
      await this.prisma.dailyStockSnapshot.create({
        data: {
          cargoId: cargo.id,
          snapshotDate: new Date(),
          feeAmount: dailyFee
        }
      });
    }
    console.log(`[${new Date().toISOString()}] 보관료 계산 완료`);
  }
}

2. NestJS: 관세청 유니패스(UNI-PASS) 연동 서비스

화물관리번호를 이용해 세관의 통관 수리 여부를 자동으로 가져오는 로직입니다.

// src/customs/customs.service.ts
import { HttpService } from '@nestjs/axios';
import { Injectable } from '@nestjs/common';

@Injectable()
export class CustomsService {
  constructor(private httpService: HttpService) {}

  async checkClearanceStatus(cargoMgmtNo: string) {
    const apiKey = process.env.UNIPASS_API_KEY;
    const url = `https://unipass.customs.go.kr/openapi/getTraceCaMgmtNo?crkyCn=${apiKey}&cargMtNo=${cargoMgmtNo}`;
    
    const response = await this.httpService.get(url).toPromise();
    // API 응답에서 통관진행상태(prgsStts) 추출 후 DB 업데이트 로직 수행
    return response.data;
  }
}

3. Nuxt 3: 보관료 정산 및 청구서 대시보드

화주별로 누적된 보관료를 확인하고 정산 처리를 할 수 있는 관리 화면입니다.

<template>
  <div class="p-8">
    <div class="flex justify-between items-center mb-6">
      <h2 class="text-xl font-semibold">미정산 보관료 현황</h2>
      <button @click="generateInvoices" class="bg-indigo-600 text-white px-4 py-2 rounded">
        일괄 청구서 발행
      </button>
    </div>

    <div class="grid grid-cols-1 md:grid-cols-3 gap-4 mb-8">
      <div v-for="summary in billingSummaries" :key="summary.shipperId" class="border p-4 rounded-lg shadow-sm bg-white">
        <p class="text-sm text-gray-500">{{ summary.shipperName }}</p>
        <p class="text-2xl font-bold text-gray-900">{{ formatCurrency(summary.totalUnpaid) }}원</p>
        <div class="mt-2 text-xs text-blue-600">장치 화물: {{ summary.cargoCount }}건</div>
      </div>
    </div>
  </div>
</template>

<script setup>
const { data: billingSummaries } = await useFetch('/api/billing/summary');

const formatCurrency = (value) => {
  return new Intl.NumberFormat('ko-KR').format(value);
};
</script>

---

시스템 통합 및 테스트 가이드

1. 데이터 정합성 테스트 화물이 반출(Release)될 때, 해당 화물의 daily_stock_snapshots에 쌓인 금액 합계와 invoices 테이블의 금액이 일치하는지 검증하는 테스트 코드를 Jest로 작성하세요.
2. 비정상 프로세스 차단 통관이 완료되지 않은 화물에 대해 status를 RELEASED로 변경하려고 할 때, NestJS 인터셉터나 가드에서 에러를 던지도록 설정하여 사고를 방지합니다.
3. 사용자 경험(UX) 최적화 Nuxt 3의 v-calendar 등을 활용해 화물별 장치 기간을 타임라인 형태로 시각화하면 관리자가 체화 화물을 직관적으로 파악할 수 있습니다.

 

 

---

영업용 보세화물 장치장 관리 시스템의 전체 설계를 마무리하기 위해, 실제 창고 운영의 꽃이라고 할 수 있는 화물 위치 시각화(Location Map)와 최종 프로젝트 구조를 정리해 드릴게요.

프로젝트 최종 아키텍처 및 화면 구성

이 시스템은 화물이 어디에 있는지 직관적으로 파악하고, 세관 신고 상태에 따라 물리적 반출을 통제하는 것이 핵심입니다.

1. 창고 로케이션 시각화 (Nuxt 3 + CSS Grid)

창고 내부의 랙(Rack) 구조를 화면에 그리드 형식으로 표현하여 어느 자리가 비어 있고, 어느 화물이 장치되어 있는지 한눈에 확인합니다.

 

<template>
  <div class="p-6 bg-gray-100 rounded-xl">
    <h3 class="text-lg font-bold mb-4">창고 평면도 (A구역)</h3>
    <div class="grid grid-cols-10 gap-2">
      <div 
        v-for="cell in locations" 
        :key="cell.id"
        :class="[
          'h-16 flex items-center justify-center border text-xs font-medium rounded transition-colors',
          cell.isOccupied ? 'bg-red-500 text-white' : 'bg-green-100 text-green-700 hover:bg-green-200'
        ]"
        @click="showCellDetail(cell)"
      >
        {{ cell.id }}
      </div>
    </div>
  </div>
</template>

<script setup>
const props = defineProps(['locations']);
const showCellDetail = (cell) => {
  if (cell.isOccupied) {
    // 화물 상세 정보 팝업 로직
    emit('select', cell.cargoId);
  }
};
</script>

2. 전체 프로젝트 폴더 구조 (NestJS + Nuxt 3)

실제 개발을 시작할 때 참고할 수 있는 표준 구조입니다.

root/
├── backend-nestjs/           # NestJS 프로젝트
│   ├── src/
│   │   ├── cargo/            # 화물 관리 모듈
│   │   ├── billing/          # 정산 및 스케줄러 모듈
│   │   ├── customs/          # 유니패스 API 연동 모듈
│   │   ├── common/           # DTO, 인터셉터, 가드
│   │   └── prisma/           # Prisma Service & Client
│   └── prisma/
│       └── schema.prisma     # 데이터베이스 스키마
├── frontend-nuxtjs/          # Nuxt 3 프로젝트
│   ├── components/           # 재사용 가능한 UI 컴포넌트
│   ├── composables/          # API 호출 로직 (useFetch 등)
│   ├── pages/                # 대시보드, 입고관리, 정산관리 페이지
│   └── store/                # Pinia 상태 관리 (사용자, 설정)
└── docker-compose.yml        # MySQL 및 Redis 설정

 

---

개발 마무리 가이드: 실무 포인트

1. 트랜잭션 무결성 (Prisma Transaction) 화물 반출 시 cargo_master 상태 변경, warehouse_logs 기록, locations 상태 업데이트는 반드시 하나의 트랜잭션으로 묶어야 데이터 꼬임을 방지할 수 있습니다.
2. 비동기 처리 (Redis / BullMQ) 수천 건의 화물에 대한 보관료를 계산하거나 세관 API를 호출할 때는 메인 서버에 부하를 주지 않도록 메시지 큐(Redis)를 활용한 비동기 처리를 권장합니다.
3. 예외 상황 처리 보세화물은 부분 반출(일부만 먼저 나감)이나 보수작업 중 수량 변경이 잦습니다. 이를 위해 parent_cargo_id 필드를 두어 화물 분할 이력을 관리하면 시스템의 완성도가 비약적으로 올라갑니다.