ONAANDALL/frontend

Fork 0

Files

T

chanii8 4bd5276fc5 [as] rename: 스펙 문서 폴더 이동

2026-08-24 09:32:46 +09:00

22 KiB

Raw Blame History

화면설계서: 코드관리

1. 기본 정보

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

2. 화면 목적

설치인가 등 AS 업무에서 참조하는 공종구분코드(공종코드)와 회계구분코드(회계코드)를 한 화면에서 조회·등록·수정·삭제한다. 좌측 공종코드 관리와 우측 회계코드 관리는 독립된 목록·CRUD 영역이며, 각 섹션은 자체 API(cnstp-se, acntg-se)와 연동한다.

3. 화면 구성

3-1. 전체 레이아웃

┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
│  페이지 타이틀: 코드관리                      브레드크럼: 디지털행정지원 > 사이트관리 > 코드관리  │
├──────────────────────────────────────────────────┬────────────────────────────────────────────────┤
│  [영역 A] 공종코드 관리                          │  [영역 B] 회계코드 관리                        │
│                                         [등록]   │                                       [등록]   │
│  ┌────────────────────────────────────────────┐  │  ┌──────────────────────────────────────────┐  │
│  │ 코드 | 코드명 | 설명 | 사용여부 | 관리     │  │  │ 코드 | 코드명 | 설명 | 사용여부 | 관리   │  │
│  ├────────────────────────────────────────────┤  │  ├──────────────────────────────────────────┤  │
│  │ WC001 공공하수처리시설 …  사용 [수정][삭제]│  │  │ AC101 시설비 …         사용 [수정][삭제] │  │
│  │ WC002 하수관로정비 …      사용 [수정][삭제]│  │  │ AC102 용역비 …         사용 [수정][삭제] │  │
│  │ WC003 재이용시설 …        사용 [수정][삭제]│  │  │ AC103 운영비 …       미사용 [수정][삭제] │  │
│  └────────────────────────────────────────────┘  │  └──────────────────────────────────────────┘  │
│  « 1 2 3 … »                                     │  « 1 2 3 … »                                   │
└──────────────────────────────────────────────────┴────────────────────────────────────────────────┘

3-2. 화면 데이터 흐름

BEGIN

  // 최초 진입 — 좌·우 독립 조회
  CALL cnstpSeMngService.findAll({ page, size })
  DISPLAY 공종코드 그리드 (영역 A)

  CALL acntgSeMngService.findAll({ page, size })
  DISPLAY 회계코드 그리드 (영역 B)

  // 영역 A: 공종코드 등록
  ON 영역 A [등록] 버튼 CLICK DO
      OPEN 공종코드 등록 다이얼로그
      ON [저장] DO
          VALIDATE cnstpSeCd
          CALL cnstpSeMngService.save(CnstpSeMngSaveRequestDto)
          CALL cnstpSeMngService.findAll
          CLOSE 다이얼로그
      END ON
      ON [취소] / [닫기] DO
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 A: 공종코드 수정
  ON 영역 A 행 [수정] CLICK DO
      CALL cnstpSeMngService.findById(cnstpSeCd)
      OPEN 공종코드 수정 다이얼로그 (기존 값 초기화)
      ON [저장] DO
          CALL cnstpSeMngService.update(cnstpSeCd, CnstpSeMngSaveRequestDto)
          CALL cnstpSeMngService.findAll
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 A: 공종코드 삭제
  ON 영역 A 행 [삭제] CLICK DO
      CONFIRM "선택한 공종코드를 삭제하시겠습니까?"
      CALL cnstpSeMngService.delete(cnstpSeCd)
      CALL cnstpSeMngService.findAll
  END ON

  // 영역 B: 회계코드 등록
  ON 영역 B [등록] 버튼 CLICK DO
      OPEN 회계코드 등록 다이얼로그
      ON [저장] DO
          VALIDATE acntgSeCd, acntgSeCdNm
          CALL acntgSeMngService.save(AcntgSeMngSaveRequestDto)
          CALL acntgSeMngService.findAll
          CLOSE 다이얼로그
      END ON
      ON [취소] / [닫기] DO
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 B: 회계코드 수정
  ON 영역 B 행 [수정] CLICK DO
      CALL acntgSeMngService.findById(acntgSeCd)
      OPEN 회계코드 수정 다이얼로그 (기존 값 초기화)
      ON [저장] DO
          CALL acntgSeMngService.update(acntgSeCd, AcntgSeMngSaveRequestDto)
          CALL acntgSeMngService.findAll
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 B: 회계코드 삭제
  ON 영역 B 행 [삭제] CLICK DO
      CONFIRM "선택한 회계코드를 삭제하시겠습니까?"
      CALL acntgSeMngService.delete(acntgSeCd)
      CALL acntgSeMngService.findAll
  END ON

END

4. 영역 A: 공종코드 관리

백엔드 공종구분코드(CnstpSeMng) CRUD. 계층 구조(upCnstpCd, cdLvNo)를 지원하나, 본 화면은 평면 목록으로 표시.

4-1. 헤더 / 툴바

항목	내용
섹션 타이틀	공종코드 관리
우측 버튼	[등록] — 공종코드 등록 다이얼로그

4-2. 그리드 컬럼

컬럼명	Field	타입	비고
코드	`cnstpSeCd`	string	PK, 최대 10자
코드명	`cnstpSeCdNm`	string	최대 100자
설명	`expln`	string	최대 1000자, 선택
사용여부	`useYn`	string	`Y`→사용, `N`→미사용
관리	—	—	행별 [수정] · [삭제]

행 클릭 시 별도 상세 이동 없음. 수정은 [수정] 버튼으로 다이얼로그 진입.
페이지네이션: Spring Pageable (page, size, sort) — UI 노출. 기본 size: 10, @common/components 공통 페이지네이션 컴포넌트 사용.

4-3. 버튼

버튼명	위치	동작
등록	섹션 우측 상단	공종코드 등록 다이얼로그 오픈
수정	행별	상세 조회 후 수정 다이얼로그 (값 초기화)
삭제	행별	확인 후 삭제, 목록 갱신

4-4. 다이얼로그: 공종코드 등록 / 수정

다이얼로그 입력 필드는 코드 · 코드명 · 설명 · 사용여부 4개만 노출한다.

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
코드	Input	Y	—	`cnstpSeCd`	등록 시 입력, 수정 시 읽기 전용
코드명	Input	N	—	`cnstpSeCdNm`	최대 100자
설명	Input	N	—	`expln`	최대 1000자
사용여부	Radio	N	Y	`useYn`	`Y`→사용, `N`→미사용

UI에 노출하지 않는 API 필드(upCnstpCd, cdLvNo): 등록 시 cdLvNo: 1 등 기본값 전송, 수정 시 findById 응답값 유지.

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

5. 영역 B: 회계코드 관리

백엔드 회계구분관리(AcntgSeMng) CRUD. 영역 A와 동일한 평면 목록 UI 패턴을 따른다.

5-1. 헤더 / 툴바

항목	내용
섹션 타이틀	회계코드 관리
우측 버튼	[등록] — 회계코드 등록 다이얼로그

5-2. 그리드 컬럼

컬럼명	Field	타입	비고
코드	`acntgSeCd`	string	PK, 최대 10자
코드명	`acntgSeCdNm`	string	최대 100자
설명	`expln`	string	최대 1000자, 선택
사용여부	`useYn`	string	`Y`→사용, `N`→미사용
관리	—	—	행별 [수정] · [삭제]

페이지네이션: 영역 A와 동일 — UI 노출, 기본 size: 10.

5-3. 버튼

버튼명	위치	동작
등록	섹션 우측 상단	회계코드 등록 다이얼로그 오픈
수정	행별	상세 조회 후 수정 다이얼로그 (값 초기화)
삭제	행별	확인 후 삭제, 목록 갱신

5-4. 다이얼로그: 회계코드 등록 / 수정

다이얼로그 입력 필드는 코드 · 코드명 · 설명 · 사용여부 4개만 노출한다. (영역 A와 동일 패턴)

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
코드	Input	Y	—	`acntgSeCd`	등록 시 입력, 수정 시 읽기 전용
코드명	Input	Y	—	`acntgSeCdNm`	최대 100자
설명	Input	N	—	`expln`	최대 1000자
사용여부	Radio	N	Y	`useYn`	`Y`→사용, `N`→미사용

UI에 노출하지 않는 API 필드(upAcntgSeCd, cdLvNo): 등록 시 cdLvNo: 1 등 기본값 전송, 수정 시 findById 응답값 유지.

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

6. API/DTO 명세

6-1. 공통

항목	내용
서비스	`as-service`
Base prefix	`/as-service/api/v1` (`ENDPOINT.AS_COMMON_SERVICE`)
인증	JWT (`Authorization` 헤더), `X-Site-Id`, `token-id`
페이징	Spring `Pageable`: `page`, `size`, `sort` → `PageResponse<T>`
엔티티	`@/entities/cnstp` (`cnstpSeMngService`), `@/entities/acntg` (`acntgSeMngService`)

부가 API (본 화면 목록 외 참조용)

리소스	Method	URL	Response	용도
공종구분코드	GET	`/cnstp-se/list/tree`	`CnstpSeMngTreeDto[]`	계층 트리 (타 화면·상위코드 선택)
회계구분관리	GET	`/acntg-se/list/tree`	`AcntgSeMngTreeDto[]`	계층 트리 (타 화면·상위코드 선택)

6-2. 공종구분코드 (영역 A) — `cnstp-se`

기능	Method	URL	Request / Query	Response	클라이언트
목록 조회	GET	`/cnstp-se`	`CnstpSeMngSearchDto` + Pageable	`Page<CnstpSeMngResponseDto>`	`cnstpSeMngService.findAll`
트리 조회	GET	`/cnstp-se/list/tree`	—	`CnstpSeMngTreeDto[]`	`cnstpSeMngService.findTree`
상세 조회	GET	`/cnstp-se/{cnstpSeCd}`	—	`CnstpSeMngResponseDto`	`cnstpSeMngService.findById`
등록	POST	`/cnstp-se`	`CnstpSeMngSaveRequestDto`	`string` (cnstpSeCd)	`cnstpSeMngService.save`
수정	PUT	`/cnstp-se/{cnstpSeCd}`	`CnstpSeMngSaveRequestDto`	`string` (cnstpSeCd)	`cnstpSeMngService.update`
삭제	DELETE	`/cnstp-se/{cnstpSeCd}`	—	`string` (cnstpSeCd)	`cnstpSeMngService.delete`

CnstpSeMngResponseDto

Field	타입	설명
`cnstpSeCd`	string	공종구분코드
`cnstpSeCdNm`	string	공종구분코드명
`upCnstpCd`	string?	상위공종코드
`cdLvNo`	number	코드레벨번호
`useYn`	string	사용여부
`expln`	string?	설명 (최대 1000자)
`rgtr`	string?	등록자 UUID
`rgtrNm`	string?	등록자명
`mdfr`	string?	수정자 UUID
`regDt`	string?	등록일시
`mdfcnDt`	string?	수정일시

CnstpSeMngSaveRequestDto: cnstpSeCd, cnstpSeCdNm?, upCnstpCd?, cdLvNo?, useYn?, expln?

CnstpSeMngSearchDto: cnstpSeCd?, cnstpSeCdNm?, useYn? + page, size, sort

React Query hooks: useCnstpSeMngPage, useCnstpSeMngTree, useCnstpSeMng, useSaveCnstpSeMng, useUpdateCnstpSeMng, useDeleteCnstpSeMng

6-3. 회계구분관리 (영역 B) — `acntg-se`

기능	Method	URL	Request / Query	Response	클라이언트
목록 조회	GET	`/acntg-se`	`AcntgSeMngSearchDto` + Pageable	`Page<AcntgSeMngResponseDto>`	`acntgSeMngService.findAll`
트리 조회	GET	`/acntg-se/list/tree`	—	`AcntgSeMngTreeDto[]`	`acntgSeMngService.findTree`
상세 조회	GET	`/acntg-se/{acntgSeCd}`	—	`AcntgSeMngResponseDto`	`acntgSeMngService.findById`
등록	POST	`/acntg-se`	`AcntgSeMngSaveRequestDto`	`string` (acntgSeCd)	`acntgSeMngService.save`
수정	PUT	`/acntg-se/{acntgSeCd}`	`AcntgSeMngSaveRequestDto`	`string` (acntgSeCd)	`acntgSeMngService.update`
삭제	DELETE	`/acntg-se/{acntgSeCd}`	—	`string` (acntgSeCd)	`acntgSeMngService.delete`

AcntgSeMngResponseDto

Field	타입	설명
`acntgSeCd`	string	회계구분코드
`acntgSeCdNm`	string	회계구분코드명
`upAcntgSeCd`	string?	상위회계구분코드
`cdLvNo`	number	코드레벨번호
`useYn`	string	사용여부
`expln`	string?	설명 (최대 1000자)
`rgtr`	string?	등록자 UUID
`rgtrNm`	string?	등록자명
`mdfr`	string?	수정자 UUID
`regDt`	string?	등록일시
`mdfcnDt`	string?	수정일시

AcntgSeMngSaveRequestDto: acntgSeCd, acntgSeCdNm, upAcntgSeCd?, cdLvNo, useYn?, expln?

AcntgSeMngSearchDto: acntgSeCd?, acntgSeCdNm?, useYn? + page, size, sort

React Query hooks: useAcntgSeMngPage, useAcntgSeMngTree, useAcntgSeMng, useSaveAcntgSeMng, useUpdateAcntgSeMng, useDeleteAcntgSeMng

7. UI 구현 가이드

7-1. 기술 스택·원칙

Next.js App Router, React Query (@tanstack/react-query)
@common/components — Card, Button, Dialog, DataTable / useDataTable
@tanstack/react-table — 컬럼 정의는 model/*-table-columns.tsx 분리
기존 entity 레이어 재사용: @/entities/cnstp, @/entities/acntg (service·queries·interface 구현 완료)
좌·우 2열 레이아웃: grid grid-cols-1 lg:grid-cols-2 gap-4 (모바일 1열 스택)
삭제 전 confirm / Toast 피드백 — 프로젝트 공통 패턴 준수
목록 하단 페이지네이션 UI 노출 — 영역 A·B 각각 독립 page state
검색 필터 UI 미제공 — findAll 호출 시 page, size만 전달
등록/수정 다이얼로그 — 코드·코드명·설명은 Input, 사용여부는 Radio (4필드만 노출)
상위 코드 삭제 시 하위 코드 연쇄 삭제 UI·로직 미구현 — 단건 삭제만 수행

7-2. 모듈·파일 배치

구분	경로 (제안)
라우트	`apps/as/src/app/(authenticated)/site/code-management/page.tsx`
페이지 컴포넌트	`apps/as/src/pages/code-management/ui/code-management-page.tsx`
공종 그리드 컬럼	`apps/as/src/pages/code-management/model/cnstp-se-table-columns.tsx`
회계 그리드 컬럼	`apps/as/src/pages/code-management/model/acntg-se-table-columns.tsx`
공종 등록/수정 폼	`apps/as/src/pages/code-management/ui/cnstp-se-form-dialog.tsx`
회계 등록/수정 폼	`apps/as/src/pages/code-management/ui/acntg-se-form-dialog.tsx`
API·타입 (기존)	`@/entities/cnstp`, `@/entities/acntg`

7-3. 영역별 UI 매핑

영역	UI 컴포넌트	데이터 소스	비고
A	`CnstpSeSection` + Table + Pagination	`useCnstpSeMngPage({ page, size })`	독립 page state·mutation
B	`AcntgSeSection` + Table + Pagination	`useAcntgSeMngPage({ page, size })`	A와 상호 의존 없음
A 다이얼로그	`CnstpSeFormDialog`	`useCnstpSeMng`, `useSave/UpdateCnstpSeMng`	Input 4필드 + Radio 사용여부
B 다이얼로그	`AcntgSeFormDialog`	`useAcntgSeMng`, `useSave/UpdateAcntgSeMng`	Input 4필드 + Radio 사용여부

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

다이얼로그	트리거	라우팅
공종코드 등록	영역 A [등록]	URL 변경 없음 (모달)
공종코드 수정	영역 A 행 [수정]	URL 변경 없음 (모달)
회계코드 등록	영역 B [등록]	URL 변경 없음 (모달)
회계코드 수정	영역 B 행 [수정]	URL 변경 없음 (모달)

7-5. 데이터 흐름 (구현 관점)

BEGIN

  // 페이지 마운트 — 검색 조건 없이 page·size만 전달
  const cnstpQuery = useCnstpSeMngPage({ page: 0, size: 20 })
  const acntgQuery = useAcntgSeMngPage({ page: 0, size: 20 })

  DISPLAY CodeManagementPage
    ├─ CnstpSeSection(data=cnstpQuery.data, pagination)
    └─ AcntgSeSection(data=acntgQuery.data, pagination)

  // 페이지 변경
  ON pagination page/size CHANGE DO
      refetch cnstpQuery | acntgQuery with new page, size
  END ON

  // mutation 성공 시
  ON save/update/delete SUCCESS DO
      invalidateQueries cnstp-se | acntg-se baseKey
      TOAST "저장되었습니다." | "삭제되었습니다."
  END ON

END

22 KiB Raw Blame History