feat(location): add paicha overview endpoint

tests/test_location_overview.py

@@ -0,0 +1,106 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api.v1 import location as location_api
+from app.services.box_service import InvalidZongpaiError
+from app.services.location_service import PaichaNotFoundError, get_paicha_overview
+
+
+class _Bind:
+    class Dialect:
+        name = "postgresql"
+
+    dialect = Dialect()
+
+
+class _Rows:
+    def __init__(self, rows):
+        self._rows = rows
+
+    def fetchone(self):
+        return self._rows[0] if self._rows else None
+
+    def fetchall(self):
+        return self._rows
+
+
+class _Location:
+    def __init__(self, zongpai_no, location_code):
+        self.zongpai_no = zongpai_no
+        self.location_code = location_code
+
+
+class _Query:
+    def __init__(self, rows):
+        self._rows = rows
+
+    def filter(self, *_args, **_kwargs):
+        return self
+
+    def all(self):
+        return self._rows
+
+
+class _Session:
+    bind = _Bind()
+
+    def execute(self, _sql, params):
+        if "zongpai_no" in params:
+            if params["zongpai_no"] == "26B404":
+                return _Rows([])
+            return _Rows([("26B1", "R00001", 80, "6-1(7)")])
+        return _Rows([
+            ("26B2", "6-1(7)", 34),
+            ("26B3", "6-2(3)", 60),
+            ("26B1", "6-1(7)", 80),
+            ("26B4", "6-2(3)", 45),
+        ])
+
+    def query(self, _model):
+        return _Query([
+            _Location("26B1", "A01-02-03"),
+            _Location("26B3", "TRANS-01"),
+        ])
+
+
+def test_paicha_overview_maps_statuses_and_sorts():
+    data = get_paicha_overview(_Session(), "26B1")
+
+    assert data["paicha_no"] == "R00001"
+    assert data["total_count"] == 4
+    assert [item["zongpai_no"] for item in data["items"]] == [
+        "26B1",
+        "26B3",
+        "26B2",
+        "26B4",
+    ]
+    assert data["items"][0]["status"] == "on_shelf"
+    assert data["items"][0]["location_code"] == "A01-02-03"
+    assert data["items"][1]["status"] == "transferred"
+    assert data["items"][1]["location_code"] == "TRANS-01"
+    assert data["items"][2]["status"] == "not_shelved"
+    assert data["items"][2]["location_code"] is None
+
+
+def test_paicha_overview_invalid_zongpai():
+    with pytest.raises(InvalidZongpaiError):
+        get_paicha_overview(_Session(), "INVALID")
+
+
+def test_paicha_overview_not_found():
+    with pytest.raises(PaichaNotFoundError):
+        get_paicha_overview(_Session(), "26B404")
+
+
+def test_paicha_overview_api_not_found(client: TestClient, monkeypatch):
+    def raise_not_found(_db, _zongpai_no):
+        raise PaichaNotFoundError()
+
+    monkeypatch.setattr(location_api, "get_paicha_overview", raise_not_found)
+    resp = client.get(
+        "/CargoTrace/location/paicha-overview",
+        params={"zongpai_no": "26B404"},
+    )
+
+    assert resp.status_code == 404
+    assert resp.json()["error_code"] == "PAICHA_NOT_FOUND"