260707_1_대시보드정리 1차

2026-07-08 19:04:20 +09:00
parent 3485eeb096
commit 9c40dec070
26 changed files with 1264 additions and 305 deletions
@@ -0,0 +1,166 @@
+# code_20260708_b01_dashboard.md
+
+## 목적
+
+이번 대화 세션에서는 `.agent/plan_register_split.md`와
+`.agent/plan_register_split_validation.md` 기준으로 B01 페이지를 역할별 대시보드와
+계정관리 기능을 함께 포함하는 단일 페이지로 구현했다.
+
+## 주요 구현
+
+### 1. B01 단일 폴더 정리
+
+- `B01_Dashboard/`를 B01의 단일 구현 폴더로 사용한다.
+- 기존 `B01_AccountDetail/`의 계정관리 성격은 `B01_Dashboard` 안으로 흡수했다.
+- 기존 `B01_AccountDetail_UI_Page.ts`, `B01_AccountDetail_UI_Style.css`는 삭제했다.
+- `B01_AccountDetail` 문자열 참조는 주석까지 정리했다.
+
+### 2. 백엔드 API
+
+신규 파일:
+
+- `B01_Dashboard/B01_Dashboard_Router.py`
+- `B01_Dashboard/B01_Dashboard_Repository.py`
+- `B01_Dashboard/B01_Dashboard_Schema.py`
+
+구현된 API 범위:
+
+- 공통 사용자 정보 조회/수정
+- USER 프로젝트/회사 조회, 회사 검색, 회사 생성, 회사 가입 신청
+- ADMIN 팀원 조회/추가/제거, 가입 요청 승인/거절, 회사 프로젝트 조회
+- SYSTEM_ADMIN 회사/사용자/가입 요청/감사 로그/리소스 조회
+
+라우터 등록:
+
+- `main.py`에 `B01_Dashboard_Router`를 등록했다.
+
+### 3. 프론트엔드
+
+신규/수정 파일:
+
+- `B01_Dashboard/B01_Dashboard_UI_Page.ts`
+- `B01_Dashboard/B01_Dashboard_Api_Fetch.ts`
+- `B01_Dashboard/B01_Dashboard_UI_Style.css`
+- `A00_Common/router.ts`
+- `ui_template/ui_template_locale.ts`
+
+구현된 UI 범위:
+
+- 역할별 대시보드 섹션 조건부 렌더링
+- 프로젝트 테이블 및 B03~B09 워크플로우 단계 버튼
+- 회사 미연결/가입 대기/활성 상태 표시
+- 회사 생성 및 회사 검색/가입 신청 모달
+- ADMIN 팀원 관리 및 가입 요청 처리
+- SYSTEM_ADMIN 리소스/회사/사용자/가입 요청/로그 섹션
+- 기본정보 수정
+- 비밀번호 변경
+
+주의:
+
+- 색상은 직접 하드코딩하지 않고 `ui_template_theme.css` 변수 기반 CSS를 사용했다.
+- UI 문구는 `ui_template_locale.ts`에 등록해 참조했다.
+
+### 4. 인증/세션 관련 최소 수정
+
+로그인 인증 이슈 재발을 피하기 위해 수정 범위를 좁혔다.
+
+수정 파일:
+
+- `common_util/common_util_auth.py`
+- `common_util/common_util_auth_repository.py`
+- `A06_Login/A06_Login_Router.py`
+- `A07_Register/A07_Register_Router.py`
+
+변경 내용:
+
+- `PENDING` 상태 사용자도 B01 대시보드에 접근할 수 있도록 세션 검증 허용 상태에 포함했다.
+- 신규 가입 기본 역할을 기존 `MEMBER`가 아니라 계획 기준인 `USER`로 맞췄다.
+- 이메일 인증 완료 시 `auth_expires_at`을 3개월 뒤로 설정했다.
+- 로그인 완료 시 `last_login`, `auth_expires_at`을 갱신한다.
+- 회사 생성/연결 안내 주석을 `B01_Dashboard` 기준으로 갱신했다.
+
+### 5. DB 마이그레이션
+
+신규 파일:
+
+- `db_management/004_dashboard.sql`
+
+적용 내용:
+
+- `users.role`을 `SYSTEM_ADMIN`, `ADMIN`, `USER` 기준으로 정규화
+- 기존 `MASTER -> ADMIN`, `MEMBER -> USER` 데이터 변환
+- `users.status`에 `NO_COMPANY` 포함
+- `users.department`, `last_login`, `auth_expires_at` 추가
+- `system_audit_logs`, `system_resources` 생성
+- `join_requests.review_comment` 추가
+
+실행 결과:
+
+- 원격 MariaDB에 `004_dashboard.sql` 실행 완료
+- 10개 SQL statement 실행 및 커밋 완료
+- information_schema 조회로 다음 항목 확인 완료:
+  - `users.role = enum('SYSTEM_ADMIN','ADMIN','USER')`
+  - `users.status = enum('PENDING_EMAIL','NO_COMPANY','PENDING','ACTIVE','INACTIVE','REJECTED')`
+  - `department`, `last_login`, `auth_expires_at`
+  - `system_audit_logs`, `system_resources`
+  - `join_requests.review_comment`
+
+## 검증
+
+실행한 검증:
+
+- `npx.cmd tsc --noEmit`
+- `ruff check --fix --no-cache ...`
+- venv 기준 Python import 확인
+- DB information_schema 확인
+
+결과:
+
+- TypeScript 검사 통과
+- Ruff 검사 통과
+- DB 마이그레이션 적용 확인
+
+참고:
+
+- 서버 실행은 프로젝트 지침에 따라 수행하지 않았다.
+- 의존성은 venv에서 `pymysql`, `aiomysql`, `fastapi` import가 정상이라 추가 설치하지 않았다.
+
+## 후속 수정 (리소스 현황 실측)
+
+- `get_system_resources`에서 `None`으로 하드코딩되어 화면에 `-`로만 표시되던 CPU/메모리 값을 `psutil`로 실측하도록 변경했다.
+  - CPU: `psutil.cpu_percent(interval=0.1)`
+  - 메모리: `psutil.virtual_memory().percent`
+  - 디스크: 기존 `shutil.disk_usage()` 유지
+- 이력 조회 기간을 24시간 → 기본 30일로 변경했다. (`days` 파라미터, 1~90일)
+- API 파라미터 불일치 수정: 프론트가 보내던 `period=24h`(문자열)를 백엔드 `days`(정수)와 일치하도록 `fetchSystemResources(days = 30)`로 변경했다.
+- `psutil`은 이미 `requirements.txt`(`psutil>=6.1,<7`) 및 venv에 존재하여 추가 설치 불필요.
+
+## 후속 수정 (리소스 그래프 + 계측 로그)
+
+### 프론트엔드 그래프
+- `ui_template_elements.ts`에 공통 라인 차트 컴포넌트 `createLineChart` 추가 (외부 라이브러리 없이 인라인 SVG).
+  - null 값 구간은 선을 끊고 다음 유효점에서 재시작.
+  - 색상은 `ui_template_theme.css`에 추가한 `--color-chart-0~3` 변수 참조 (하드코딩 없음).
+- `B01_Dashboard_UI_Page.ts`의 리소스 섹션을 `buildResourcePanel`로 교체하여 지표(metrics) + 30일 추이 그래프(CPU/메모리/디스크)를 함께 표시.
+- `ResourceData.history`를 `unknown[]` → `ResourceHistoryPoint[]`로 타입 구체화.
+- locale에 `B01_Dashboard_Resources_ChartCaption`, `B01_Dashboard_Resources_ChartAria` 추가.
+
+### 계측 백그라운드 태스크 + 로그 파일
+- `common_util/common_util_resource_monitor.py` 신규: 2분 주기로 CPU/메모리/디스크 계측.
+  - DB `system_resources` 테이블 INSERT (그래프 조회 소스) + 30일 경과 행 DELETE.
+  - 루트 `log/system_resources.log` 단일 파일에 탭 구분 1줄 append, 30일 경과 줄 제거(오래된 줄 삭제 + 신규 줄 추가).
+- `main.py` lifespan에 `sample_resources_loop` 태스크 등록/취소 (기존 cleanup 태스크 패턴).
+- `config_system.py`에 `LOG_BASE_DIR`, `RESOURCE_LOG_PATH`, `RESOURCE_SAMPLE_INTERVAL_SEC=120`, `RESOURCE_LOG_RETENTION_DAYS=30` 추가.
+- `.gitignore`에 `log/` 추가.
+
+### 검증
+- `npx tsc --noEmit` 통과, `ruff format`/`ruff check` 통과, `prettier --write` 변경 없음.
+- 계측/로그 트림 로직은 스크립트로 실측 확인 (샘플 기록·30일 경과 줄 제거 동작 확인 후 테스트 로그 삭제).
+
+## 남은 주의점
+
+- B01 화면은 구현됐지만 실제 브라우저 검증은 수행하지 않았다.
+- 그래프는 `system_resources` 이력이 쌓여야 선이 그려진다 (앱 최초 구동 직후에는 데이터 2점 미만이면 `—` 빈 상태 표시, 2분 주기로 누적).
+- 로그인/회사 상태별 실제 시나리오 검증은 별도 검증 AI 또는 사용자가 수행해야 한다.
+- `B01_Dashboard_UI_Page.ts`는 645줄로 700줄 제한 이내지만, 향후 기능 추가 시 컴포넌트 분리를 고려해야 한다.
+- 이전 import 검증 중 기존 B04 계열 Pydantic `model_*` 필드 경고가 출력됐으나, 이번 B01 구현에서 발생한 경고는 아니다.