설비 운영 현황 백엔드 참고 매뉴얼

목적과 범위

설비 운영 현황판은 새 원장을 소유하지 않는 Office 범위 읽기 모델입니다. 시설관리 상품의 기존 세 원장을 느슨하게 합성하며, 이 페이지를 위해 테이블·RPC·마이그레이션을 추가하지 않습니다.

• 기준 원장: public.facility_assets
• 선택 점검 원장: public.facility_inspections
• 선택 작업 원장: public.facility_work_orders

실시간 센서나 설비제어시스템의 운전 텔레메트리는 현재 계약에 없습니다. 따라서 running|stopped|down 같은 상태는 파생하거나 저장하지 않습니다.

Office 범위와 인가

세 조회는 각각 company_id + office_id를 명시하고 기존 RLS 및 시설관리 상품 entitlement를 그대로 적용합니다. 자산과 작업지시는 추가로 subject_kind='equipment'를 제한합니다. 현황판 전용 privileged RPC나 RLS 우회 view를 만들지 않습니다.

Supabase 연결 설정이 없으면 클라이언트 adapter는 backend='unavailable'과 빈 목록을 반환합니다. 운영·개발 화면이 test mock을 자동 선택하지 않습니다. mock은 unit test의 명시 주입 또는 MODE=test에만 허용합니다.

합성 계약

facility_assets의 설비 행을 기준으로 다음 축을 붙입니다.

1. 점검: facility_inspections.asset_id = facility_assets.id
2. 작업지시: subject_kind='equipment'이고 subject_ref = facility_assets.subject_ref인 exact match
3. 미종결 작업지시: status <> 'verified'

설비명이나 대상 참조의 부분 문자열, 관리코드, 등록코드로 추측 연결하지 않습니다. 점검·작업지시는 선택 연결이므로 둘 중 하나가 없거나 조회에 실패해도 자산 목록을 폐기하지 않습니다.

projection

| 필드 | 파생 근거 | | ----------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | | 자산 상태 | facility_assets.status 원문 | | 최근 점검 | 같은 자산의 completed 점검 중 completed_at, 없으면 scheduled_for 최신 | | 다음 점검 | 같은 자산의 planned | in_progress중scheduled_for 최소 | | 점검 일정 지남 | planned이고 scheduled_for < client now | | 미종결 작업지시 건수 | exact subject link의 status <> verified 건수 | | 미종결 작업지시 최고 우선순위 | urgent > high > normal > low |

자산 상태 operational|attention|out_of_service|retired는 각각 정상·주의 필요·사용 중지·운영 종료로 표시합니다. operational은 자산 원장의 관리 상태이며 실시간 운전 중이라는 뜻이 아닙니다.

부분 실패 계약

세 원장 조회 결과는 독립적으로 처리합니다.

• 자산 성공 + 점검 실패: 자산 타일 유지, 점검 축을 error
• 자산 성공 + 작업지시 실패: 자산 타일 유지, 작업지시 축을 error
• 연결 설정 없음: 해당 repo를 unavailable, 목록을 빈 배열로 반환
• 자산 실패: 기준행이 없으므로 오류와 재시도 안내

participant directory는 작업지시 목록의 선택 의존성입니다. 참여자 조회가 실패해도 작업지시 목록은 유지하고 배정 선택지만 오류로 관리합니다.

동시성 및 Office 전환

현황판은 쓰기 read model이 아니지만 재사용하는 작업지시 composable의 명령을 보호해야 합니다. load/create/transition은 Company·Office와 sequence를 호출 시 캡처합니다. Office 전환은 모든 sequence를 증가시키고 목록·오류·pending을 초기화합니다. 이전 Office의 늦은 성공, 늦은 오류, create/transition 응답은 현재 Office 상태를 upsert하거나 덮어쓸 수 없습니다.

검증

DB 변경이 없으므로 기존 시설 migration과 smoke를 그대로 사용합니다. 프론트 계약 테스트는 exact subject link, 검수 완료 제외, 최근·다음 점검, 부분 원장 실패, no-config empty adapter, Office stale success/error/command 응답 폐기를 검증합니다.