feat(일위대가실무): 324-1 실무자료 엑셀 읽기 · 저장 · 올리기 길 — 「일위대가」 시트 → 호표 · 줄 · 갈래 · 참조 · 검산

- M02_Hopyo_Excel: xls(xlrd · logfile 막음) · xlsx(openpyxl) · 머리 글로 시트 · 열 찾기 · 제N호표 · 구성 줄 · 갈래(단가산출 · 자재 · 기계 · 호표 · % · 별도계상 · 기타) · 단산N/일위N 참조 · 검산(줄 금액 floor · 합계 단가 · % 줄 · 호표 비목 · 총괄표) · 규격 원문 보관 · 시트 없음 = 「일위대가 시트 없음」
- M02_Hopyo_Store: 층 폴더 실무자료/HP-######.json · 맞춤 기억 실무자료/맞춤.json · 잠금 + 원자 쓰기 · 양식 종류 밖(목록 · 복사 · 프로젝트 씨앗에 안 섞임)
- M02_Labor_Router: GET/POST /layers/{층}/hopyo · GET/DELETE /layers/{층}/hopyo/{키} · 20 MB · 엉터리 · 시트 없음 400 · 권한 = 층 읽기 · 쓰기 규칙
- requirements: xlrd==2.0.2
- 시험 test_m02_hopyo_excel 15 통과(북부청 68 · 사방 27 · 검산 0 · 역할 표 · sha256)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ji4nuyLVHcxrXWHTdb5nRD

M02_MasterTemplete/M02_Labor_Router.py

@@ -3,19 +3,23 @@
 문서 읽기 · 쓰기는 양식 길(`GET/PUT /api/m02/layers/{층}/templates/labor/{열}`) 그대로 ·
 여기는 저장하지 않는 셈만 + 서고(단가승격 · 사전조합 · 50-3) 새로 · 복사(키는 서버가 줌 · 고침 ·
 지우기는 양식 길 그대로) + 개인 자재 목록 · 추가(148-2 · 개인 층만 · 품번은 서버) +
-사전조합 나무 자유 폴더(158-1 · `M02_Precombo_Folders` · 읽기 = 층 읽기 · 고침 = 층 쓰기).
+사전조합 나무 자유 폴더(158-1 · `M02_Precombo_Folders` · 읽기 = 층 읽기 · 고침 = 층 쓰기) +
+일위대가 실무자료(324 · `M02_Hopyo_*` · 올리기 · 지우기 = 층 쓰기 · 목록 · 읽기 = 층 읽기).
 층 권한 = `Router_Items._root`(`M02_Layer_Access` 한 벌).
 ⚠ 등록은 `main.py`(로그인만).
 """
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any, Literal
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
 from pydantic import BaseModel
 
 from common_util.common_util_auth import verify_session
+from M02_MasterTemplete import M02_Hopyo_Excel as hopyo_excel
+from M02_MasterTemplete import M02_Hopyo_Store as hopyo_store
 from M02_MasterTemplete import M02_Labor_Doc as labor
 from M02_MasterTemplete import M02_Labor_Ref as refs
 from M02_MasterTemplete import M02_Layer_Access as access
@@ -159,3 +163,61 @@ def new_material(
         raise HTTPException(status_code=400, detail="신규 자재는 개인 층에서만")
     folder = _root(session, layer, owner, write=True)
     return _call(folder, own.add, folder, body)
+
+
+# ── 일위대가 실무자료(324) ─────────────────────────────────────────────
+HOPYO_MAX_BYTES = 20 * 1024 * 1024
+
+
+def _upload(name: str, data: bytes, who: dict[str, Any]) -> dict[str, Any]:
+    try:
+        parsed = hopyo_excel.read_book(name, data)
+    except hopyo_excel.ExcelError as error:
+        raise store.StoreError(400, str(error)) from error
+    return hopyo_store.save(store.root(), name, parsed, who)
+
+
+@router.get("/layers/{layer}/hopyo")
+def hopyo_list(
+    layer: Layer, owner: str | None = None, session: Session = Depends(verify_session)
+) -> dict:
+    """실무자료 목록 `{줄: [{키, 파일, 올린때, 올린이, 시트, 호표수, 어긋남}]}`."""
+    folder = _root(session, layer, owner)
+    return {"줄": hopyo_store.rows(folder)}
+
+
+@router.post("/layers/{layer}/hopyo")
+def hopyo_upload(
+    layer: Layer,
+    file: UploadFile = File(...),
+    owner: str | None = None,
+    session: Session = Depends(verify_session),
+) -> dict:
+    """엑셀(xls · xlsx) 올리기 — 「일위대가」 시트를 읽어 결과만 저장 · 20 MB ·
+    엉터리 · 시트 없음 400."""
+    folder = _root(session, layer, owner, write=True)
+    data = file.file.read(HOPYO_MAX_BYTES + 1)
+    if len(data) > HOPYO_MAX_BYTES:
+        raise HTTPException(status_code=400, detail="파일이 너무 큼(20 MB 넘음)")
+    name = Path(file.filename or "실무자료").name[:120]
+    who = {"id": session.get("user_id"), "이름": session.get("name")}
+    return _call(folder, _upload, name, data, who)
+
+
+@router.get("/layers/{layer}/hopyo/{key}")
+def hopyo_read(
+    layer: Layer, key: str, owner: str | None = None, session: Session = Depends(verify_session)
+) -> dict:
+    """실무자료 하나(호표 · 줄 · 검산)."""
+    folder = _root(session, layer, owner)
+    return _call(folder, hopyo_store.read, folder, key)
+
+
+@router.delete("/layers/{layer}/hopyo/{key}")
+def hopyo_delete(
+    layer: Layer, key: str, owner: str | None = None, session: Session = Depends(verify_session)
+) -> dict:
+    """실무자료 지우기(만든 사전조합 · 맞춤 기억은 그대로)."""
+    folder = _root(session, layer, owner, write=True)
+    _call(folder, hopyo_store.delete, folder, key)
+    return {"지움": key}