ONAANDALL/frontend

Fork 0

Files

T

chanii8 cf681125a6 [as] docs: 문서 수정

2026-08-19 11:40:13 +09:00

28 KiB

Raw Blame History

화면설계서: 전국 행정지원 지도 (대시보드 메인)

1. 기본 정보

항목	내용
버전	1.2
프로세스명	UI설계
화면명	전국 행정지원 지도 (대시보드 메인)
화면 ID	TBD
화면 유형	[v] 조회 [ ] 입력 [ ] 수정 [ ] 삭제 [ ] 출력
메뉴 경로	메인

2. 화면 목적

로그인 사용자의 기관 권한·당해 연도 기준으로 문서별 진행상태 통계와 행정지원 알림을 한 화면에서 조회한다. 좌측 지도에서 전국 행정지원 현황을 보고, 우측에서 진행상황 카드·알림이력·공지사항을 확인한 뒤 알림 [처리하기]로 연계 업무 화면으로 이동한다.

3. 화면 구성

3-1. 전체 레이아웃

브레드크럼·페이지 타이틀은 스크린샷에 없음. 홈(/) 메인 콘텐츠로 구성한다.

┌────────────────────────────────┬─────────────────────────────────────────────────┐
│  [영역 A] 전국 행정지원 지도   │  [영역 B] 문서별 진행상황 카드 (2×2)            │
│  타이틀: 전국 행정지원 지도    │  ┌────────────────┐ ┌────────────────┐          │
│                                │  │ 재원협의       │ │ 설치인가       │          │
│  (대한민국 시도·시군구 경계)   │  │ 신청/진행/완료 │ │ 신청/진행/완료 │          │
│  마커: 서울 강남구,            │  ├────────────────┤ ├────────────────┤          │
│        대전 유성구,            │  │ 설계자문       │ │ 기본계획       │          │
│        부산 해운대구           │  │ 신청/진행/완료 │ │ 신청/진행/완료 │          │
│                                │  └────────────────┘ └────────────────┘          │
│                                ├─────────────────────────────────────────────────┤
│                                │  [영역 C] 알림이력                              │
│                                │  알림이력    업데이트 HH:mm          [전체보기] │
│                                │  [오늘 N건] [지연 N건] [완료대기 N건]           │
│                                │  [뱃지] [일자] 제목                  [처리하기] │
│                                │  … (최대 5건)                                   │
│                                ├─────────────────────────────────────────────────┤
│                                │  [영역 D] 공지사항               [더보기]       │
│                                │  ┌────┬────────┬────────┬────────┬──────┐       │
│                                │  │번호│ 제목   │ 작성자 │ 작성일 │조회수│       │
│                                │  └────┴────────┴────────┴────────┴──────┘       │
└────────────────────────────────┴─────────────────────────────────────────────────┘

3-2. 화면 데이터 흐름

BEGIN

  // 최초 진입
  // searchYear 미전달 → 서버가 당해 연도로 고정. 알림 목록은 최신 5건
  CALL getMainDashboard(DashboardMainSearchDto)   // Authorization은 client 인터셉터
  DISPLAY 진행상황 카드 (영역 B)                  // docPrgrsSttsList, TOTAL 행 제외
  DISPLAY 알림 통계 칩 · 알림 목록 (영역 C)      // notiStats, notiList

  CALL getUserPostList(UserPostSearchParams)      // board-service, AS_DASHBOARD_BBS_ID
  DISPLAY 공지사항 그리드 (영역 D)

  CALL 지도 마커/음영 조회(…)                     // TBD — 대시보드 API에 없음
  DISPLAY 전국 지도 (영역 A)

  ON 영역 C [전체보기] 버튼 CLICK DO
      NAVIGATE /nti-hstry
  END ON

  ON 영역 C [처리하기] 버튼 CLICK DO
      CALL readNoti(notiId)                       // entities/noti
      NAVIGATE notiUrl                            // 비어 있으면 이동하지 않음
      CALL getMainDashboard(…)                    // → 영역 C 갱신 (invalidate)
  END ON

  ON 영역 D [더보기] 버튼 CLICK DO
      NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}   // as 앱 공지 목록 라우트 미구현. st/cm 관례
  END ON

  ON 영역 D 행 CLICK DO
      NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}
  END ON

  ON 영역 B 카드 CLICK DO
      NAVIGATE 해당 문서 목록                     // §5-3
  END ON

  ON 영역 A 마커 CLICK DO
      // TBD — 팝업/필터/이동 여부 미확정
  END ON

END

4. 영역 A — 전국 행정지원 지도

스크린샷 타이틀: 전국 행정지원 지도.

getMainDashboard 응답에 지도·좌표·행정구역 음영 데이터는 없다. 마커·음영 소스 API는 TBD.

4-1. 표시 요소

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
섹션 타이틀	Text	—	—	—	고정 문구 `전국 행정지원 지도`
전국 지도	Map	—	—	TBD	시도·시군구 경계. 북·동부 음영(청) / 남서부 비음영(백) — 의미 TBD
마커 라벨	Marker	—	—	TBD	스크린샷 샘플: `서울 강남구`, `대전 유성구`, `부산 해운대구`

4-2. 상호작용

동작	설명
마커 클릭	TBD (상세 팝업 / 해당 지자체 필터 / 이동)
지도 줌·팬	TBD (스크린샷에 컨트롤 없음)

entities/adstdstr는 시도·구군 콤보만 제공하며 좌표를 주지 않는다. 지도 라이브러리도 as 앱에 없음 — 선정 TBD.

5. 영역 B — 문서별 진행상황 카드

DashboardMainResponseDto.docPrgrsSttsList를 docSeComCd로 매핑해 4장 카드를 그린다. 배열 순서에 의존하지 않는다.

스크린샷 배치(좌→우, 상→하):

화면 카드 타이틀	`docSeComCd`	API `docSeNm`
재원협의 진행상황	`FNRS`	재원협의
설치인가 진행상황	`INSTL`	설치인가
설계자문 진행상황	`CNFM`	설계자문
기본계획 진행상황	`SEWER`	하수도기본계획

서버 SQL ORDER BY는 INSTL → FNRS → SEWER → CNFM 이며, GROUP BY ROLLUP으로 docSeComCd = TOTAL 합계 행이 추가된다. 카드에는 TOTAL 행을 표시하지 않는다.

카드 타이틀은 스크린샷 문구(… 진행상황)를 쓴다. SEWER의 API명 하수도기본계획은 화면에서 기본계획으로 축약한다.

5-1. 카드 내부 필드

각 카드 공통 구조. totCnt는 화면에 없음.

표시명	Field	비고
신청	`reqCnt`	파란 아이콘 + 건수
진행	`prgrsCnt`	초록 아이콘 + 건수
완료	`cmptnCnt`	주황 아이콘 + 건수

상태 그룹(서버): 임시저장(SV/CV) 제외. 문서별 prgrs_stts_com_cd → REQ/PRG/CMP.

5-2. 검색 파라미터 (화면 미표시)

영역 B에 연도·필터 UI는 없다. 서버 기본값을 따른다.

표시명	입력 유형	필수	기본값	API 파라미터 매핑	비고
(없음)	—	—	당해 연도	`searchYear`	미전달 시 서버 `LocalDate.now().getYear()`. 연도 셀렉터 추가 여부 TBD

docSeComCd 쿼리는 알림 목록 필터에만 쓰이며, 진행상황 SQL에는 전달되지 않는다. 카드 4종은 항상 전원 집계한다.

5-3. 상호작용

카드 클릭 시 해당 문서 목록 페이지로 이동한다. docSeComCd → 라우트 고정 매핑.

동작	`docSeComCd`	이동 경로
카드 클릭	`FNRS`	`/fnrs-cnsltn`
카드 클릭	`INSTL`	`/instl-sncn`
카드 클릭	`CNFM`	`/design-cnstn`
카드 클릭	`SEWER`	`/sewer-bsc-plan`

6. 영역 C — 알림이력

서버가 cms-service 알림을 대시보드 응답에 합친다. 목록은 page=0, size=5 (최신 5건). 페이지네이션 없음.

6-1. 헤더

표시명	Field / 소스	비고
섹션 타이틀	—	고정 문구 `알림이력`
업데이트 시각	(client)	스크린샷 `업데이트 10:32`. API 필드 없음. `getMainDashboard` 마지막 fetch 시각(`HH:mm`)
전체보기	Button	`/nti-hstry`로 이동

6-2. 통계 칩

NotiAsStatResponseDto.

표시명	Field	비고
오늘 N건	`todayCount`	당일 00:00 이후 수신
지연 N건	`delayCount`	`notReadYn=N` 이고 수신 후 3일 이상
완료대기 N건	`pendingCount`	`notReadYn=Y` 이고 `notiPrcsCmptnYn=N`

6-3. 목록 행

표시명	Field	비고
일자	`regDt`	표시 `YYYY-MM-DD`. 응답 `yyyy-MM-dd HH:mm:ss`
제목	`notiTtl`	알림 제목
처리	(action)	스크린샷 라벨 `처리하기`. 클릭 §6-4

응답에 있으나 이 목록에 표시하지 않음:

Field	비고
`notiId`	행 키 · `readNoti` 파라미터
`recvUnqId`	수신 회원 UUID (서버 로그인 사용자 고정)
`senderUnqId`	발신 회원 UUID
`notiType`	`ADSS`
`notiCn`	본문
`notiUrl`	처리 후 이동 URL. 컬럼 미표시
`notiLnkgUnqNo`	알림연결고유번호
`docSeComCd`	문서구분 코드
`docSeComNm`	문서구분명 (알림이력 화면에서는 연계업무)
`notReadYn`	뱃지 판정 TBD에 사용 가능
`notiIdntyYn`	확인 여부
`notiIdntyDt`	확인 일시
`notiPrcsCmptnYn`	처리 완료 여부
`notiPrcsCmptnDt`	처리 완료 일시

6-4. 행 상호작용

동작	설명
[전체보기] 클릭	`/nti-hstry` (알림이력 목록)로 이동
[처리하기] 클릭	`readNoti(notiId)` 후 `notiUrl`로 이동. URL이 비면 이동하지 않음(읽음 처리는 수행). `dashboardBaseKey` invalidate

DashboardController에 읽음 API는 없다. entities/noti의 readNoti 를 쓴다. 알림이력 화면과 동일 (PUT /cms-service/api/v1/noti/{notiId}/read).

6-5. 검색 파라미터 (화면 미표시)

서버 toNotiSearchDto() 기본: notiType = ADSS. 화면 필터 없음.

DashboardMainSearchDto	화면	비고
`notiType`	없음	서버 기본 `ADSS`
`notReadYn`	없음	통계 칩 클릭 필터 시 후보 (TBD)
`startDt` / `endDt`	없음	대시보드 기본 미전달
`docSeComCd`	없음	알림만 필터. 진행상황 카드와 무관

7. 영역 D — 공지사항

getMainDashboard에 공지 필드는 없다. board-service getUserPostList로 별도 조회한다.

Base: GET /board-service/api/v1/posts/user/{AS_DASHBOARD_BBS_ID}
AS_DASHBOARD_BBS_ID = NEXT_PUBLIC_AS_DASHBOARD_BBS_ID (로컬 예: 7)
클라이언트: @/entities/board — postApi.getUserPostList / useUserPostList

페이지네이션 컨트롤은 없다. 요약 목록만 표시한다 (page=0, size=3).

7-1. 헤더·버튼

버튼명	동작
더보기	`/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}` 로 이동. as 앱에 공지 목록 라우트는 없음(st/cm 관례)

7-2. 그리드 컬럼

스크린샷 헤더 순서. UserPost.

표시명	Field	비고
번호	`rowNo`	`upndFixYn` = `Y` 이면 `[공지]` Badge, 그 외 `rowNo`
제목	`pstTtl`	truncate
작성자	`wrtrNm`
작성일	`regDt`	표시 `YYYY-MM-DD` (응답 datetime)
조회수	`inqNocs`	숫자

조회 파라미터 (UserPostSearchParams):

필드	값	비고
`page`	`0`	Spring 0-based
`size`	`3`	대시보드 요약. 스크린샷 3행
`keywordType`	`bbsTypeCd`	st 대시보드 공지 패널과 동일
`keyword`	`BBSNOTICE`	게시판 유형. path의 bbsId와 함께 공지 한정

응답에 있으나 그리드에 표시하지 않음: bbsId, pstNo(행 키·상세 이동), pstCn, upndFixYn(번호 열 판정만), rgtrNm, atflCd 등.

7-3. 행 상호작용

동작	설명
행 클릭	`/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}` (as 앱 공지 상세 라우트 미구현)

8. API/DTO 명세

8-1. 공통

항목	값
Base prefix	`/as-service/api/v1/dashboard` (`ENDPOINT.AS_SERVICE.DASHBOARD`)
인증	`Authorization` 헤더. 프론트는 `client` 인터셉터. 로그인 기관 권한은 서버가 사용자 캐시로 적용
클라이언트 모듈	`@/entities/dashboard` — `dashboardService` / `useGetMainDashboard`
알림 읽음	`@/entities/noti` — `notiService.readNoti` / `useReadNoti`
공지사항	`@/entities/board` — `postApi.getUserPostList` / `useUserPostList`

영역 A(지도)는 본 컨트롤러·board-service 범위 밖 → TBD.

8-2. 대시보드 메인 조회 — `getMainDashboard`

기능	Method	URL	Request DTO	Response DTO	API
대시보드 메인 통합진행상태 및 알림 정보 조회	GET	`{BASE}/main`	Query: `DashboardMainSearchDto`	`DashboardMainResponseDto`	`dashboardService.getMainDashboard` / `useGetMainDashboard`

Request (DashboardMainSearchDto)

필드	필수	설명
`searchYear`	N	검색 연도. 미전달 시 서버 당해 연도. 영역 B 집계 기간
`notiType`	N	알림 종류. 미전달 시 서버 `ADSS`
`notReadYn`	N	알림 확인 여부 `Y`/`N`. 본 화면 미사용
`startDt`	N	알림 시작일 `YYYY-MM-DD`. 본 화면 미사용
`endDt`	N	알림 종료일 `YYYY-MM-DD`. 본 화면 미사용
`docSeComCd`	N	알림 문서구분 (`INSTL`/`FNRS`/`SEWER`/`CNFM` 등). 진행상황 집계와 무관

Authorization은 service 시그니처에 넣지 않는다.

Response (DashboardMainResponseDto)

필드	타입	설명
`docPrgrsSttsList`	`DocPrgrsSttsResponseDto[]`	문서별 진행상태 + TOTAL 행
`notiList`	`NotiAsUserResponseDto[]`	최신 최대 5건
`notiStats`	`NotiAsStatResponseDto`	오늘 / 지연 / 완료대기 건수

DocPrgrsSttsResponseDto

필드	타입	설명
`docSeNm`	string	문서 구분 명칭
`docSeComCd`	string	`INSTL` / `FNRS` / `SEWER` / `CNFM` / `TOTAL`
`reqCnt`	number	신청 건수
`prgrsCnt`	number	진행 건수
`cmptnCnt`	number	완료 건수
`totCnt`	number	총 건수 (화면 미표시)

NotiAsStatResponseDto

필드	타입	설명
`todayCount`	number	오늘 알림
`delayCount`	number	지연 알림
`pendingCount`	number	완료대기

NotiAsUserResponseDto — 필드 상세는 docs/spec/nti-hstry §6-2와 동일 (notiId, notiTtl, regDt, notiUrl, notReadYn, notiPrcsCmptnYn 등).

8-3. 알림 읽음 처리 — `readNoti`

대시보드 컨트롤러가 아니라 cms-service. 영역 C [처리하기]에서 호출.

기능	Method	URL	Request DTO	Response DTO	API
알림 읽음 처리	PUT	`/cms-service/api/v1/noti/{notiId}/read`	Path: `notiId` (`Long`)	`Long` (알림 ID)	`notiService.readNoti` / `useReadNoti`

Body 없음. 성공 시 dashboardBaseKey(및 필요 시 notiBaseKey) invalidate.

8-4. 전국 행정지원 지도 — TBD

기능	Method	URL	Request DTO	Response DTO	API
지도 마커·음영 조회	TBD	TBD	TBD	TBD	TBD

8-5. 공지사항 — `getUserPostList`

board-service. bbsId는 환경변수 AS_DASHBOARD_BBS_ID로 path에 고정한다.

기능	Method	URL	Request DTO	Response DTO	API
대시보드 공지 요약 목록	GET	`/board-service/api/v1/posts/user/{bbsId}`	Query: `UserPostSearchParams`	`PageResponse<UserPost>`	`postApi.getUserPostList` / `useUserPostList`

Request (UserPostSearchParams) — 본 화면 고정값

필드	필수	설명
`page`	N	`0`
`size`	N	`3`
`keywordType`	N	`bbsTypeCd`
`keyword`	N	`BBSNOTICE`
`popupYn` 등	N	본 화면 미사용

Response (UserPost) — 화면 매핑 필드

필드	타입	설명
`rowNo`	number	번호. 고정글이 아니면 표시
`pstNo`	number	게시 번호. 상세 이동 키
`bbsId`	number	게시판 ID
`pstTtl`	string	제목
`wrtrNm`	string	작성자
`regDt`	string	작성일
`inqNocs`	number	조회수
`upndFixYn`	string	상단고정 `Y`/`N` → `[공지]`

9. UI 구현 가이드

9-1. 기술 스택·원칙

라우트: 기존 홈 app/(main)/(with-base-layout)/page.tsx → pages/home (현재 MainPage 플레이스홀더)
UI: @common/components — Card, Badge, Button, Table(공지). 지도 라이브러리 TBD
데이터: React Query useGetMainDashboard(). 처리하기는 useReadNoti(). 공지는 useUserPostList()
진행상황 카드: docSeComCd로 4슬롯 매핑. TOTAL 제외
알림 목록: 테이블이 아닌 행 리스트(뱃지 + 일자 + 제목 + 버튼)
공지: @tanstack/react-table + useDataTable, 페이지네이션 없음
검색 조건 URL 동기화: 본 화면 필터 없음. searchYear UI가 생기면 그때 검토

9-2. 모듈·파일 배치

구분	경로
라우트	`app/(main)/(with-base-layout)/page.tsx`
페이지	`pages/dashboard/ui/dashboard-page.tsx`
지도	`pages/dashboard/ui/national-as-map.tsx` (API TBD, Skeleton)
진행상황 카드	`pages/dashboard/ui/doc-prgrs-stts-cards.tsx`
알림이력	`pages/dashboard/ui/dashboard-noti-list.tsx`
공지사항	`pages/dashboard/ui/dashboard-notice-table.tsx`
공지 컬럼	`pages/dashboard/model/dashboard-notice-table-columns.tsx`
Entity API	`entities/dashboard/api/dashboard-service.ts`
Entity Hook	`entities/dashboard/api/queries.ts` → `useGetMainDashboard`
Entity Model	`entities/dashboard/model/dashboard-interface.ts`
알림 읽음	`entities/noti` → `useReadNoti`
공지 Entity	`entities/board` → `useUserPostList`

Entity(getMainDashboard, getUserPostList) 구현됨. 영역 B·C·D 화면 구현. 영역 A는 Skeleton.

9-3. 영역별 UI 매핑

영역	컴포넌트	데이터
A	`national-as-map`	Skeleton (지도 API TBD)
B	`doc-prgrs-stts-cards`	`useGetMainDashboard` → `docPrgrsSttsList` (`TOTAL` 제외, 코드 매핑)
C	`dashboard-noti-list`	동 훅 → `notiStats`, `notiList`. 처리 → `useReadNoti`. 전체보기 `/nti-hstry`
D	`dashboard-notice-table`	`useUserPostList` → `content[]`. [더보기]·행 클릭 → `/cms/bbsnotice/...`

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

항목	내용
다이얼로그	없음
본 화면 라우트	`/` (홈)
알림 처리 이동	[처리하기] → `readNoti` 후 `notiUrl` (알림이력과 동일, SEWER URL은 상세 세그먼트 제거)
알림 전체보기	`/nti-hstry`
공지 더보기	`/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}` (as 앱 공지 라우트 미구현, st/cm 관례)
공지 행 클릭	`/cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}`
진행상황 카드	§5-3 목록 라우트 (`/fnrs-cnsltn`, `/instl-sncn`, `/design-cnstn`, `/sewer-bsc-plan`)

9-5. 데이터 흐름

BEGIN

  // 최초 진입 (홈)
  CALL getMainDashboard({})
  DISPLAY 영역 B   // docPrgrsSttsList — FNRS/INSTL/CNFM/SEWER 슬롯
  DISPLAY 영역 C   // notiStats + notiList(≤5)

  CALL getUserPostList({ page: 0, size: 3, keywordType: "bbsTypeCd", keyword: "BBSNOTICE" })
  DISPLAY 영역 D

  CALL 지도 데이터 // TBD → 영역 A

  ON 영역 C [전체보기] CLICK DO
      NAVIGATE /nti-hstry
  END ON

  ON 영역 C [처리하기] CLICK DO
      CALL readNoti(notiId)
      IF notiUrl THEN
          NAVIGATE notiUrl
      END IF
      CALL getMainDashboard   // invalidate dashboardBaseKey
  END ON

  ON 영역 B 카드 CLICK DO
      NAVIGATE 문서 목록   // §5-3
  END ON

  ON 영역 D [더보기] CLICK DO
      NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}
  END ON

  ON 영역 D 행 CLICK DO
      NAVIGATE /cms/bbsnotice/{AS_DASHBOARD_BBS_ID}/{pstNo}
  END ON

END

28 KiB Raw Blame History