ONAANDALL/frontend

Fork 0

Files

T

chanii8 24c446b880 [as] feat: 체크리스트 관리 페이지 생성

2026-05-20 17:33:05 +09:00

30 KiB

Raw Blame History

화면설계서: 체크리스트관리

1. 기본 정보

항목	내용
버전	0.1
프로세스명	UI설계
화면명	체크리스트관리
화면 유형	[v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력
메뉴 경로	디지털행정지원 > 시스템관리 > 체크리스트관리

2. 화면 목적

업무별·문서별 점검표(체크리스트)를 등록·관리하고, 점검항목 마스터를 유지한다. 상단 좌측에서 점검표를 선택하면 하단 체크리스트 항목 영역에 해당 점검표의 검토 구성(계층형 검토내용)을 편집한다. 상단 우측 점검항목 관리는 점검표에 연결할 항목 풀을 등록·수정·삭제한다.

3. 화면 구성

3-1. 전체 레이아웃

┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│  페이지 타이틀: 체크리스트관리                              브레드크럼: 디지털행정지원 > … >  │
├──────────────────────────────────────────────┬────────────────────────────────────────────────┤
│  [영역 A] 점검표 관리                        │  [영역 B] 점검항목 관리                        │
│                              [점검표 추가]   │                              [점검항목 추가]   │
│  ┌────────────────────────────────────────┐  │  ┌──────────────────────────────────────────┐  │
│  │ 점검표일련번호 | 점검표명 | 문서구분   │  │  │ 점검항목코드 | 점검항목명 | 사용여부     │  │
│  │ 업무구분 | 사용여부 | 등록일시 | 관리  │  │  │ 등록일시 | 관리                          │  │
│  ├────────────────────────────────────────┤  │  ├──────────────────────────────────────────┤  │
│  │ 1 (선택 행 강조)         [관리] [삭제] │  │  │ ITEM_001 요건검토 …         [관리][삭제] │  │
│  │                                        │  │  │ ITEM_002 법령검토 …         [관리][삭제] │  │
│  └────────────────────────────────────────┘  │  └──────────────────────────────────────────┘  │
├──────────────────────────────────────────────┴────────────────────────────────────────────────┤
│  [영역 C] 체크리스트 항목                                         [미리보기]  [추가]  [저장]  │
│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 점검항목 ▼        | 주요 검토내용            | 사용 여부            | 구분  | 관리      │  │
│  │ L1 [요건검토 ▼]   | (입력)                   | ○예 ○아니오          | 1단계 | [하위추가]│  │
│  │ L2 [요건검토 ▼]   | (입력)                   | ○예 ○아니오          | 2단계 | [삭제]    │  │
│  └─────────────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

3-2. 화면 데이터 흐름

BEGIN

  // 최초 진입
  CALL GET /as-checklist-service/api/v1/cklst
  DISPLAY 점검표 그리드 (영역 A)
  CALL GET /as-checklist-service/api/v1/cklst-artcl
  DISPLAY 점검항목 그리드 (영역 B)
  DISPLAY 빈 상태 안내 (영역 C)            // 점검표 미선택 시 C 비활성

  // 영역 A: 점검표 행 선택
  ON 영역 A 행 CLICK DO
      SET 선택된 점검표 = 행.cklstSn
      CALL GET /as-checklist-service/api/v1/cklst-rvw?cklstSn={cklstSn}
      // TBD: 점검표 단위 전체 검토 트리 조회 API — 현재는 항목별 by-artcl 조합 또는 클라이언트 병합
      DISPLAY 체크리스트 항목 그리드 (영역 C)
  END ON

  // 영역 A: 점검표 추가
  ON [점검표 추가] 버튼 CLICK DO
      OPEN 점검표 추가 다이얼로그
      ON [저장] DO
          VALIDATE cklstNm, taskSeComCd
          CALL POST /as-checklist-service/api/v1/cklst
          CALL GET /as-checklist-service/api/v1/cklst
          CLOSE 다이얼로그
      END ON
      ON [취소] / [닫기] DO
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 A: 점검표 수정·삭제
  ON 영역 A 행 [관리] CLICK DO
      OPEN 점검표 수정 다이얼로그 (기존 값 초기화)
      ON [저장] DO
          CALL PUT /as-checklist-service/api/v1/cklst/{cklstSn}
          CALL GET /as-checklist-service/api/v1/cklst
      END ON
  END ON

  ON 영역 A 행 [삭제] CLICK DO
      CONFIRM "선택한 점검표를 삭제하시겠습니까?"
      CALL DELETE /as-checklist-service/api/v1/cklst/{cklstSn}
      IF 삭제 대상 == 선택된 점검표 THEN RESET 영역 C
      CALL GET /as-checklist-service/api/v1/cklst
  END ON

  // 영역 B: 점검항목 추가
  ON [점검항목 추가] 버튼 CLICK DO
      OPEN 점검항목 추가 다이얼로그
      ON [저장] DO
          VALIDATE cklstArtclNm
          // TBD: cklstSn 필수 — UI에 소속 점검표 선택 없음. 백엔드 정책 확인
          CALL POST /as-checklist-service/api/v1/cklst-artcl
          CALL GET /as-checklist-service/api/v1/cklst-artcl
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 B: 점검항목 수정·삭제
  ON 영역 B 행 [관리] CLICK DO
      OPEN 점검항목 수정 다이얼로그
      ON [저장] DO
          CALL PUT /as-checklist-service/api/v1/cklst-artcl/{cklstArtclSn}/{cklstSn}
      END ON
  END ON

  ON 영역 B 행 [삭제] CLICK DO
      CONFIRM "선택한 점검항목을 삭제하시겠습니까?"
      CALL DELETE /as-checklist-service/api/v1/cklst-artcl/{cklstArtclSn}/{cklstSn}
      CALL GET /as-checklist-service/api/v1/cklst-artcl
  END ON

  // 영역 C: 검토 행 추가
  ON [추가] 버튼 CLICK DO
      VALIDATE 선택된 점검표 존재
      ADD 영역 C 그리드 맨 아래 편집 가능 행 (1단계, rvwCnLvNo=1)
  END ON

  // 영역 C: 하위 검토 추가
  ON 행 [하위추가] CLICK DO
      ADD 부모행 하위 편집 행 (2단계, upCklstRvwSn=부모.cklstRvwSn, rvwCnLvNo=2)
  END ON

  // 영역 C: 일괄 저장
  ON [저장] 버튼 CLICK DO
      VALIDATE 선택된 점검표 존재
      FOR EACH 신규·변경된 검토 행 DO
          IF 신규 THEN
              CALL POST /as-checklist-service/api/v1/cklst-rvw
          ELSE
              CALL PUT /as-checklist-service/api/v1/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}
          END IF
      END FOR
      CALL GET /as-checklist-service/api/v1/cklst-rvw?cklstSn={cklstSn}
      TOAST "체크리스트 항목이 저장되었습니다."
  END ON

  // 영역 C: 행 삭제
  ON 행 [삭제] CLICK DO
      CONFIRM "선택한 항목을 삭제하시겠습니까?"
      IF 서버 저장된 행 THEN
          CALL DELETE /as-checklist-service/api/v1/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}
      END IF
      REMOVE 그리드 행 (미저장 행은 API 호출 없이 제거)
  END ON

  // 영역 C: 미리보기
  ON [미리보기] 버튼 CLICK DO
      OPEN 체크리스트 미리보기 다이얼로그 (읽기 전용 트리)
      // TBD: 미리보기 UI·API
  END ON

END

4. 영역 A: 점검표 관리

선택된 점검표가 영역 C의 편집 대상이 된다. 행 클릭으로 선택 상태를 표시한다.

4-1. 헤더 / 툴바

항목	내용
섹션 타이틀	점검표 관리
우측 버튼	[점검표 추가] — 점검표 등록 다이얼로그

4-2. 그리드 컬럼

컬럼명	Field	타입	비고
점검표일련번호	`cklstSn`	number	PK
점검표명	`cklstNm`	string
문서구분공통코드	`docSeComCd`	string	코드명 표시 — `ASDOCSECD` 등 공통코드 (TBD 상위코드)
업무구분공통코드	`taskSeComCd`	string	RE/SF/SP 등 — 공통코드 (TBD 상위코드)
사용여부	`useYn`	string	`Y`→예, `N`→아니오
등록일시	`regDt`	string	`yyyy-MM-dd HH:mm:ss`
관리	—	—	행별 [관리] · [삭제]

행 클릭 시: cklstSn 선택 → 영역 C 헤더·그리드 갱신.
페이지네이션: Spring Pageable (page, size, sort).

4-3. 버튼

버튼명	위치	동작
점검표 추가	섹션 우측 상단	점검표 추가 다이얼로그 오픈
관리	행별	점검표 수정 다이얼로그 (기존 값 초기화)
삭제	행별	확인 후 삭제. 선택 중인 점검표이면 영역 C 초기화.

4-4. 다이얼로그: 점검표 추가 / 수정

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
점검표명	Text	Y	—	`cklstNm`	placeholder: "예: 설치인가 체크리스트"
문서구분	Select(공통코드)	N	—	`docSeComCd`	예: FNRS, INSTL, PWRK, DESIGN
업무구분	Select(공통코드)	Y	—	`taskSeComCd`	예: RE(재이용수), SF(하수처리시설), SP(하수관로)
사용여부	Select	N	Y	`useYn`	Y/N, UI 표시: 예/아니오

버튼명	동작
저장	POST(등록) 또는 PUT(수정) 후 목록 갱신
취소	다이얼로그 닫기, 입력값 폐기
닫기	다이얼로그 닫기

5. 영역 B: 점검항목 관리

점검표 하단(영역 C)에서 선택할 점검항목 마스터를 관리한다.

5-1. 헤더 / 툴바

항목	내용
섹션 타이틀	점검항목 관리
우측 버튼	[점검항목 추가] — 점검항목 등록 다이얼로그

5-2. 그리드 컬럼

컬럼명	Field	타입	비고
점검항목코드	`cklstArtclSn`	number	UI mock `ITEM_001` 형식 표시 여부 TBD
점검항목명	`cklstArtclNm`	string
사용여부	`useYn`	string	`Y`→예, `N`→아니오
등록일시	`regDt`	string	`yyyy-MM-dd HH:mm:ss`
관리	—	—	행별 [관리] · [삭제]

TBD: 백엔드 CklstArtcl은 복합 PK(cklstArtclSn, cklstSn)이며 등록 시 cklstSn 필수. UI 다이얼로그에는 cklstSn 입력이 없음 — 소속 점검표 지정 방식·전역 마스터 여부 백엔드 정책 확인.

5-3. 다이얼로그: 점검항목 추가 / 수정

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
점검항목명	Text	Y	—	`cklstArtclNm`	placeholder: "예: 법령검토"
사용여부	Select	N	Y	`useYn`	Y/N

버튼명	동작
저장	POST(등록) 또는 PUT(수정) 후 목록 갱신
취소	다이얼로그 닫기
닫기	다이얼로그 닫기

6. 영역 C: 체크리스트 항목 (선택된 점검표)

영역 A에서 선택된 cklstSn 기준으로 점검표검토(계층형 검토내용)를 구성한다.

6-1. 헤더 / 툴바

항목	내용
섹션 타이틀	체크리스트 항목 (선택된 점검표: {cklstNm})
우측 버튼	[미리보기] · [추가] · [저장] — 점검표 미선택 시 C 비활성

6-2. 그리드 컬럼

컬럼명	Field	입력 UI	비고
점검항목	`cklstArtclSn`	Select (영역 B 항목 목록)	L1/L2 접두 표시, `cklstArtclNm` 라벨
주요 검토내용	`rvwCn`	Text / Textarea	최대 4000자
사용 여부	`useYn`	Radio (예/아니오)	`Y` / `N`
구분	`rvwCnLvNo`	읽기 전용	1→1단계, 2→2단계, 3→3단계
관리	—	[하위추가] (1·2단계, 저장 후) · [삭제]	3단계 행은 [하위추가] 미표시

계층 정책

항목	내용
최대 깊이	3단계 (`rvwCnLvNo`: 1, 2, 3)
상위-하위 연결	`upCklstRvwSn` — 2단계 행은 부모 1단계 `cklstRvwSn` 참조
정렬	`sortSeq` — 동일 레벨 내 순서 (TBD: UI 드래그 정렬 여부)
체크 사용	`bchckUseYn` — 미리보기·실사용 화면 체크박스 노출 여부 (TBD UI 반영)

6-3. 버튼

버튼명	동작
추가	1단계 검토 행 1건 추가 (편집 가능)
저장	변경·신규 검토 행 일괄 POST/PUT (일괄 저장 API 없음)
미리보기	선택 점검표 체크리스트 읽기 전용 미리보기 (TBD)
하위추가	선택 1·2단계 행 아래 하위 단계(2·3단계) 자식 행 추가
삭제	확인 후 DELETE 또는 미저장 행 로컬 제거

7. API/DTO 명세

7-1. 공통

항목	내용
서비스	`as-checklist-service`
Base prefix	`/as-checklist-service/api/v1` (게이트웨이 프록시 경유)
인증	JWT (`Authorization` 헤더), `X-Site-Id`, `token-id`
페이징	Spring `Pageable`: `page`, `size`, `sort` → `PageResponse<T>`
엔티티	`@/entities/cklst` (`cklstMngService`, `cklstArtclService`, `cklstRvwService`)

7-2. 점검표 (영역 A) — `cklst`

기능	Method	URL	Request / Query	Response	클라이언트
목록 조회	GET	`/cklst`	`CklstMngSearchParams` + Pageable	`Page<CklstMng>`	`cklstMngService.findPage`
단건 조회	GET	`/cklst/{cklstSn}`	—	`CklstMng`	`cklstMngService.findById`
등록	POST	`/cklst`	`CklstMngSaveRequest`	`number` (cklstSn)	`cklstMngService.create`
수정	PUT	`/cklst/{cklstSn}`	`CklstMngSaveRequest`	`number` (cklstSn)	`cklstMngService.update`
삭제	DELETE	`/cklst/{cklstSn}`	—	`number` (cklstSn)	`cklstMngService.remove`

CklstMng (응답)

Field	타입	설명
`cklstSn`	number	점검표일련번호
`cklstNm`	string	점검표명
`taskSeComCd`	string	업무구분공통코드
`useYn`	string?	사용여부
`docSeComCd`	string?	문서구분공통코드
`rgtr`	string?	등록자 UUID
`rgtrNm`	string?	등록자명
`mdfr`	string?	수정자 UUID
`regDt`	string?	등록일시
`mdfcnDt`	string?	수정일시

CklstMngSaveRequest: cklstNm*, taskSeComCd*, useYn?, docSeComCd?

CklstMngSearchParams: cklstNm?, taskSeComCd?, useYn?, docSeComCd? + page, size, sort

React Query hooks: useCklstMngPage, useCklstMng, useCreateCklstMng, useUpdateCklstMng, useDeleteCklstMng

7-3. 점검표항목 (영역 B) — `cklst-artcl`

기능	Method	URL	Request / Query	Response	클라이언트
목록 조회 (페이징)	GET	`/cklst-artcl`	`CklstArtclSearchParams` + Pageable	`Page<CklstArtcl>`	`cklstArtclService.findPage`
점검표별 전체 목록	GET	`/cklst-artcl/by-cklst/{cklstSn}`	—	`CklstArtcl[]`	`cklstArtclService.findByCklstSn`
단건 조회	GET	`/cklst-artcl/{cklstArtclSn}/{cklstSn}`	—	`CklstArtcl`	`cklstArtclService.findById`
등록	POST	`/cklst-artcl`	`CklstArtclSaveRequest`	`CklstArtclId`	`cklstArtclService.create`
수정	PUT	`/cklst-artcl/{cklstArtclSn}/{cklstSn}`	`CklstArtclUpdateRequest`	`CklstArtclId`	`cklstArtclService.update`
삭제	DELETE	`/cklst-artcl/{cklstArtclSn}/{cklstSn}`	—	`CklstArtclId`	`cklstArtclService.remove`

CklstArtcl (응답)

Field	타입	설명
`cklstArtclSn`	number	점검표항목일련번호
`cklstSn`	number	점검표일련번호
`cklstArtclNm`	string?	점검표항목명
`useYn`	string?	사용여부
`rgtr` / `rgtrNm`	string?	등록자
`regDt`	string?	등록일시

CklstArtclSaveRequest: cklstSn*, cklstArtclNm?, useYn?

CklstArtclUpdateRequest: cklstArtclNm?, useYn?

CklstArtclId: { cklstArtclSn: number; cklstSn: number }

React Query hooks: useCklstArtclPage, useCklstArtclList, useCklstArtcl, useCreateCklstArtcl, useUpdateCklstArtcl, useDeleteCklstArtcl

7-4. 점검표검토 (영역 C) — `cklst-rvw`

기능	Method	URL	Request / Query	Response	클라이언트
목록 조회 (페이징)	GET	`/cklst-rvw`	`CklstRvwSearchParams` + Pageable	`Page<CklstRvw>`	`cklstRvwService.findPage`
항목별 검토 전체 목록	GET	`/cklst-rvw/by-artcl/{cklstSn}/{cklstArtclSn}`	—	`CklstRvw[]`	`cklstRvwService.findByArtcl`
단건 조회	GET	`/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}`	—	`CklstRvw`	`cklstRvwService.findById`
등록	POST	`/cklst-rvw`	`CklstRvwSaveRequest`	`CklstRvwId`	`cklstRvwService.create`
수정	PUT	`/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}`	`CklstRvwUpdateRequest`	`CklstRvwId`	`cklstRvwService.update`
삭제	DELETE	`/cklst-rvw/{cklstRvwSn}/{cklstArtclSn}/{cklstSn}`	—	`CklstRvwId`	`cklstRvwService.remove`

CklstRvw (응답)

Field	타입	설명
`cklstRvwSn`	number	점검표검토일련번호
`cklstArtclSn`	number	점검표항목일련번호
`cklstSn`	number	점검표일련번호
`upCklstRvwSn`	number?	상위점검표검토일련번호
`rvwCnLvNo`	number?	검토내용레벨번호
`rvwCn`	string?	검토내용
`bchckUseYn`	string?	체크사용여부
`sortSeq`	number?	정렬순서
`useYn`	string?	사용여부
`regDt`	string?	등록일시

CklstRvwSaveRequest: cklstArtclSn*, cklstSn*, upCklstRvwSn?, rvwCnLvNo?, rvwCn?, bchckUseYn?, sortSeq?, useYn?

CklstRvwUpdateRequest: upCklstRvwSn?, rvwCnLvNo?, rvwCn?, bchckUseYn?, sortSeq?, useYn?

CklstRvwSearchParams: cklstSn?, cklstArtclSn?, useYn? + page, size, sort

CklstRvwId: { cklstRvwSn: number; cklstArtclSn: number; cklstSn: number }

React Query hooks: useCklstRvwPage, useCklstRvwByArtcl, useCklstRvw, useCreateCklstRvw, useUpdateCklstRvw, useDeleteCklstRvw

7-5. 공통코드 (보조)

UI 필드	코드 그룹 (TBD)	예시 값
문서구분	`ASDOCSECD` 등	FNRS, INSTL, PWRK, DESIGN
업무구분	TBD	RE(재이용수), SF(하수처리시설), SP(하수관로)
사용여부	고정	Y, N

공통코드 조회: @/entities/code — codeService, CodeSelect

8. UI 구현 가이드

8-1. 기술 스택·원칙

공통 컴포넌트: @common/components (Dialog, Button, Input, Select, RadioGroup 등)
테이블: @tanstack/react-table + useDataTable
데이터: React Query — @/entities/cklst hooks (useCklstRvwPage 등 영역 C 포함)
공통코드: @/entities/code — CodeSelect, findCodeLabel
상태: 선택된 cklstSn, 영역 C 검토 행 배열(신규·dirty·계층 트리)
모의 데이터: API 연동 전 @faker-js/faker

8-2. 모듈·파일 배치(제안)

구분	경로
라우트	`apps/as/app/(with-base-layout)/checklist-management/page.tsx`
페이지	`apps/as/src/pages/checklist-management/` (Public API: page만 export)
UI	`.../ui/cklst-mng-list.tsx`, `cklst-mng-form-dialog.tsx`, `cklst-artcl-list.tsx`, `cklst-artcl-form-dialog.tsx`, `cklst-rvw-grid.tsx`, `cklst-preview-dialog.tsx`
model	`.../model/cklst-mng-columns.tsx`, `cklst-artcl-columns.tsx`, `cklst-rvw-row-types.ts`
lib	`.../lib/use-cklst-rvw-rows.ts`, `validators.ts`, `build-rvw-tree.ts`
엔티티	`apps/as/src/entities/cklst/` (`cklstMng`, `cklstArtcl`, `cklstRvw` 서비스·hooks)
페이지	`apps/as/src/pages/checklist-management/` — `/checklist-management`
문서	`apps/as/docs/checklist-management/SPEC.md`

8-3. 영역별 UI 매핑

영역	주요 UI
A	DataTable + 행 선택 + 점검표 추가/수정 Dialog
B	DataTable + 점검항목 추가/수정 Dialog
C	계층형 편집 그리드(1·2단계) + [추가][저장][미리보기] + 행별 [하위추가][삭제]
공통	`CodeSelect` (문서구분·업무구분), 사용여부 Y/N Select/Radio

8-4. 다이얼로그·라우팅

다이얼로그명	트리거	API 연동
점검표 추가	[점검표 추가]	`useCreateCklstMng`
점검표 수정	행 [관리]	`useUpdateCklstMng`
점검표 삭제 확인	행 [삭제]	`useDeleteCklstMng`
점검항목 추가	[점검항목 추가]	`useCreateCklstArtcl`
점검항목 수정	행 [관리]	`useUpdateCklstArtcl`
체크리스트 미리보기	[미리보기]	TBD — 읽기 전용 트리 렌더

라우트: /checklist-management (메뉴 URL은 CMS 등록값과 일치시킴)

8-5. 데이터 흐름(요약)

진입: useCklstMngPage → 영역 A, useCklstArtclPage → 영역 B. C 비활성.
점검표 선택: cklstSn 설정 → 영역 C 활성 → useCklstRvwPage({ cklstSn }) → 트리 그리드 표시.
점검표 CRUD: Dialog → useCreateCklstMng / useUpdateCklstMng / useDeleteCklstMng.
점검항목 CRUD: Dialog → useCreateCklstArtcl / useUpdateCklstArtcl / useDeleteCklstArtcl.
검토 저장: [저장] → 신규 POST / 기존 PUT 순차 호출 (일괄 API 없음).
영역 C 점검항목 Select: useCklstArtclList(cklstSn) 또는 영역 B 전체 목록과 교차 — TBD.

8-6. 미확정 / 검증 필요

영역 B 점검항목 등록 시 cklstSn 필수 vs UI 무소속 마스터 — 백엔드·기획 확인
점검항목코드(ITEM_001) 표시 형식 vs cklstArtclSn 숫자 PK
영역 C 전체 검토 트리 조회: cklstSn 단위 일괄 API 부재 — by-artcl 다건 호출 또는 백엔드 확장
@/entities/cklst — cklstRvwService·hooks 구현
pages/checklist-management — 영역 A·B·C UI 구현 (/checklist-management)
문서구분·업무구분 공통코드 상위코드 ID (ASDOCSECD 등)
[미리보기] 다이얼로그 UI·데이터 소스
bchckUseYn UI 반영 여부
영역 A·B 페이지네이션·검색 UI 노출 여부
권한(역할별 CRUD)

30 KiB Raw Blame History