equipments 스키마 (현장 장비)

현장에 배정된 장비 본문 문서. companies/{cid}/members가 아닌 장비 단위 문서이며, 장비 소유자 혹은 임대 장비 정보가 저장됩니다. 장비대(재무) 페이지에서 사용하는 월별 가동 공수(attendance)와 임대 계약(contracts) 서브컬렉션은 finance/equipment_cost.md에서 별도 관리합니다. 본 문서는 equipments/{equipment_id} 본문 필드만 다룹니다.

저장 위치

companies/{company_id}/sites/{site_id}/equipments/{equipment_id}

• equipment_id는 users/{UID}/equipments의 장비 문서 ID를 그대로 사용합니다 (사용자 측 장비 문서와 ID 공유).
• 하위 컬렉션:
• contracts/{contract_id} — 임대 계약 (finance/equipment_cost.md 참조)
• attendance/{YYYYMM} — 월별 가동 공수 (finance/equipment_cost.md 참조)

상태 흐름

(요청) equipment_assign_requests (pending)
  → equipment_assign_request_approval(approved)
     → equipments 문서 생성/갱신 (resign=false)
  → 장비대 페이지에서 edit_equipment_info / edit_equipment_lessor_info 로 필드 업데이트
  → equipment_resign / equipment_site_change 로 resign=true 처리 (문서 삭제 X)

생성/업데이트 엔드포인트 요약

엔드포인트	동작	주요 필드
equipment_assign_request_approval (승인)	문서 최초 생성 또는 resign 해제 후 재생성	소유자 신상 + 장비 정보 스냅샷
equipment_site_change_request_approval / equipment_site_change (도착 현장)	현장 이동 시 도착 현장 문서 생성/갱신	출발 현장 문서 필드 그대로 복사 + resign=false
edit_equipment_info	장비 정보 수정	equipment_name, equipment_number, equipment_type
edit_equipment_lessor_info	임대인 정보 저장	lessor_company_name, lessor_registration_number, main_address, sub_address_enc, phone_enc
equipment_resign	해제 처리	resign=true, resign_at, resign_UID, resign_reason="manual_resign"
equipment_site_change (출발 현장)	이동 시 출발 현장 해제 처리	resign=true, resign_reason="site_change"

문서 필드

소유자/운전자 정보 (배정 시점 스냅샷)

필드	타입	설명
UID	string	장비 소유자(운전자) UID
name	string	소유자 이름 (스냅샷)
phone_enc	string	소유자 전화번호 AES 암호화
phone_masked	string	"010-****-XXXX" 형식의 마스킹 번호
email_enc	string	소유자 이메일 AES 암호화
main_address	string	주소 (평문)
sub_address_enc	string	상세주소 AES 암호화
birth	timestamp	생년월일
sex	string	"male" | "female"

장비 정보

필드	타입	설명
equipment_type	string	장비 종류 (예: "굴착기", "덤프트럭")
equipment_name	string	장비명
equipment_number	string	장비 번호/차량번호

배정/해제 메타

필드	타입	설명
assigned_by	string	배정한 관리자 UID
assigned_at	timestamp	배정 시각
resign	bool	해제 여부 (true면 이 현장에서 해제됨, 문서는 삭제되지 않음)
resign_at	timestamp?	해제 시각
resign_UID	string?	해제 처리자 UID
resign_reason	string?	해제 사유 — "manual_resign" (수동 해제) 또는 "site_change" (현장 이동)

임대 장비 추가 필드 (edit_equipment_lessor_info 호출 시)

필드	타입	설명
lessor_company_name	string?	임대인 회사명
lessor_registration_number	string?	임대인 사업자등록번호

주의: 임대인 정보 저장 시 main_address, sub_address_enc, phone_enc가 소유자 정보에서 임대인 정보로 덮어쓰기됩니다. 직영/임대 구분 플래그는 없고, lessor_company_name / lessor_registration_number의 존재 여부와 contracts 서브컬렉션 유무로 임대 장비를 판별합니다.

장비대(재무) 하위 컬렉션

• contracts/{contract_id} — 임대 계약 단위 문서 (start_date, end_date, amount, tax 등)
• attendance/{YYYYMM} — 월별 가동 공수 (man_days[31], attendance_id map)

두 서브컬렉션의 스키마와 업데이트 로직은 finance/_schema/equipment_cost.md에서 관리하므로 중복 기재하지 않습니다.

데이터 동기화 주의사항

• users/{UID}/equipments의 장비 정보가 바뀌어도 현장 equipments 문서는 자동 동기화되지 않습니다 (배정 시점 스냅샷).
• 현장 변경(equipment_site_change) 시 출발 현장 문서는 resign=true로 유지되고 도착 현장에 동일 equipment_id로 새 문서가 생성됩니다. 두 문서가 공존할 수 있습니다.
• 검색 인덱스(companies/{cid}/search_index/{site_id})는 equipments 문서 변경 시 트리거(update_site_equipment_index)로 자동 갱신됩니다.

예시 문서

직영 장비

{
  "UID": "uid_driver_1",
  "name": "김장비",
  "phone_enc": "AES(...)",
  "phone_masked": "010-****-1234",
  "email_enc": "AES(...)",
  "main_address": "서울특별시 구로구",
  "sub_address_enc": "AES(...)",
  "birth": "1978-06-10T00:00:00Z",
  "sex": "male",
  "equipment_type": "굴착기",
  "equipment_name": "06W",
  "equipment_number": "서울12가3456",
  "resign": false,
  "assigned_by": "uid_admin",
  "assigned_at": "2026-01-05T09:00:00Z"
}

임대 장비 (edit_equipment_lessor_info 호출 후)

{
  "UID": "uid_driver_1",
  "name": "김장비",
  "phone_enc": "AES(임대인_전화번호)",
  "phone_masked": "010-****-1234",
  "email_enc": "AES(...)",
  "main_address": "경기도 안산시",
  "sub_address_enc": "AES(임대인_상세주소)",
  "birth": "1978-06-10T00:00:00Z",
  "sex": "male",
  "equipment_type": "굴착기",
  "equipment_name": "06W",
  "equipment_number": "서울12가3456",
  "resign": false,
  "assigned_by": "uid_admin",
  "assigned_at": "2026-01-05T09:00:00Z",
  "lessor_company_name": "대한중기",
  "lessor_registration_number": "123-45-67890"
}

해제된 장비 (현장 이동으로 해제된 경우)

{
  "UID": "uid_driver_1",
  "equipment_type": "굴착기",
  "equipment_name": "06W",
  "equipment_number": "서울12가3456",
  "resign": true,
  "resign_at": "2026-02-15T10:00:00Z",
  "resign_UID": "uid_admin",
  "resign_reason": "site_change",
  "assigned_by": "uid_admin",
  "assigned_at": "2026-01-05T09:00:00Z"
}