캠퍼스 헬프데스크 에이전트 스킬
이 스킬은 캠퍼스 헬프데스크 웹 애플리케이션을 개발, 개선 및 유지하기 위한 기술 표준, 워크플로 및 모범 사례를 정의합니다. 이 프로젝트에서 기능을 추가하거나, 컴포넌트를 리팩터링하거나, 상태 워크플로를 업데이트하거나, 데이터 모델을 수정할 때 이 가이드를 사용하십시오.
1. 깔끔하고 재사용 가능한 React 컴포넌트 작성
모듈식이며 분리된 컴포넌트 아키텍처를 유지하십시오:
- 단일 책임 원칙: 각 컴포넌트는 한 가지 일을 잘해야 합니다.
- 폼 로직과 입력은
IssueForm.jsx에 속합니다. - 공개 검색, 필터링 및 티켓 카드 표시는
TicketList.jsx에 속합니다. - 분석 메트릭, 시각적 진행률 표시줄 및 관리 테이블은
AdminDashboard.jsx에 속합니다. - 모달 검사 및 기록 타임라인은
TicketModal.jsx에 속합니다. - 알림은
Toast.jsx에 속합니다.
- 폼 로직과 입력은
- Props 및 State 설계:
- 상태를 가능한 한 로컬로 유지하십시오. 여러 뷰(예: 전역
tickets,activeTab,toasts)에서 공유할 때만App.jsx로 상태를 올리십시오. - 가능한 경우 순수 프레젠테이션 자식 컴포넌트를 사용하고, 콜백(
onSelectTicket,onUpdateStatus,onDeleteTicket)을 깔끔하게 전달하십시오. - 중복 상태를 피하고, 파생된 값(예: 필터링된 티켓, KPI 통계)은
useMemo를 사용하여 계산하십시오.
- 상태를 가능한 한 로컬로 유지하십시오. 여러 뷰(예: 전역
- 명명 규칙 및 클린 코드:
- 컴포넌트 파일은 PascalCase(
AdminDashboard.jsx,IssueForm.jsx)를 사용합니다. - 유틸리티 및 상수 파일은 camelCase(
storage.js,constants.js)를 사용합니다. - 이벤트 핸들러는
handle[Action]패턴(예:handleSubmit,handleStatusChange)을 따라야 합니다. - 주석과 문서 문자열을 보존하십시오. 설명적인 변수 이름으로 자체 설명이 가능한 코드를 작성하십시오.
- 컴포넌트 파일은 PascalCase(
- 무거운 외부 종속성 제로:
- 가벼운 아키텍처를 유지하십시오: 네이티브 React 훅, 순수 인라인 SVG 아이콘, 범위가 지정된 CSS 클래스를 사용하고 부피가 큰 타사 컴포넌트 라이브러리를 사용하지 마십시오.
2. 반응형 및 접근성 높은 UI 생성
캠퍼스 헬프데스크 포털은 모든 기기(모바일 폰, 태블릿, 노트북, 대형 모니터)에서 원활한 사용자 경험을 제공해야 합니다:
- 유동적 레이아웃 및 중단점:
- 일관된 중단점으로 모바일 우선 또는 데스크톱 다운 방식으로 설계하십시오:
- 데스크톱: 최대 컨테이너 너비
1240px, 다중 열 그리드(5개 메트릭 카드, 2열 분석, 2열 폼). - 태블릿(
<= 1024px): 5열 메트릭 그리드를 3열 또는 2열로 축소하고, 분석 차트를 단일 열로 쌓습니다. - 모바일(
<= 768px): 헤더 내비게이션과 폼 입력을 1열로 쌓고, 데이터 테이블에 가로 스크롤을 활성화합니다. - 소형 화면(
<= 480px): 전체 너비 메트릭 카드, 쌓인 작업 버튼, 하단 고정 토스트 알림.
- 데스크톱: 최대 컨테이너 너비
- 일관된 중단점으로 모바일 우선 또는 데스크톱 다운 방식으로 설계하십시오:
- 접근성(a11y) :
- 모든 대화형 요소는 적절한 시맨틱 HTML(
<button>,<input>,<select>,<textarea>)을 가져야 합니다. - 폼 컨트롤에는 일치하는
id속성을 가진 연결된<label htmlFor="...">요소가 있어야 합니다. - 모달 대화상자는
role="dialog",aria-modal="true"를 가져야 하며, 배경 클릭 및 Escape 키를 통한 해제를 지원해야 합니다. - 대화형 아이콘 또는 아이콘 전용 버튼에는 설명적인
aria-label또는title속성이 포함되어야 합니다. - 상태 배지 및 우선순위 태그의 텍스트에 대해 접근 가능한 색상 대비 비율을 유지하십시오.
- 모든 대화형 요소는 적절한 시맨틱 HTML(
- 시각적 피드백 및 전환:
- 대화형 요소는 명확한
:hover,:focus및:active상태를 표시해야 합니다. - 포커스가 있는 폼 필드는 고대비 포커스 링(
var(--primary-ring))을 표시해야 합니다. - 마이크로 애니메이션(토스트 슬라이드 인, 모달 확대, 버튼 스피너)을 사용하여 레이아웃 이동 없이 백그라운드 작업을 사용자에게 알리십시오.
- 대화형 요소는 명확한
3. 학생 이슈 폼 검증
IssueForm.jsx를 통한 모든 이슈 제출은 상태 변형 또는 저장 전에 엄격한 클라이언트 측 검증 규칙을 따라야 합니다:
검증 규칙 매트릭스
| 필드 | 규칙 | 오류 메시지 |
|---|---|---|
| 전체 이름 | 필수, 공백 제거, 비어 있지 않음 | "전체 이름을 입력해 주세요." |
| 캠퍼스 이메일 | 필수, 유효한 정규식 패턴 /^[^\s@]+@[^\s@]+\.[^\s@]+$/ | "유효한 이메일 주소를 입력해 주세요." |
| 위치/방 | 필수, 공백 제거, 비어 있지 않음 | "건물, 홀 또는 캠퍼스 위치를 지정해 주세요." |
| 카테고리 | 필수, CATEGORIES 목록과 일치해야 함 | 기본값으로 자동 선택 |
| 우선순위 | 필수, PRIORITIES(Low, Medium, High, Urgent)와 일치해야 함 | 기본값 'Medium' |
| 이슈 제목 | 필수, 공백 제거, 최소 길이 $\ge 5$자 | "제목은 최소 5자 이상이어야 합니다." |
| 상세 설명 | 필수, 공백 제거, 최소 길이 $\ge 15$자 | "설명은 최소 15자 이상이어야 합니다." |
검증 구현 단계
- 필드 이름을 오류 문자열에 매핑하는
errors상태 객체를 유지합니다. - 사용자가 입력을 수정할 때(
handleChange) 특정 필드의 오류를 지웁니다. handleSubmit시 모든 규칙을 확인합니다. 오류가 있으면 제출을 방지하고.input-error및.field-error로 잘못된 필드를 강조 표시합니다.- 성공 시:
- 고유 ID(예:
TCK-XXXX)를 생성합니다. - 초기 상태
Pending을 할당합니다. - 초기 제출 타임스탬프 및 기록 노드를 기록합니다.
- 폼 필드와 오류 상태를 재설정합니다.
- 성공 토스트를 트리거하고 티켓 추적기 뷰로 이동합니다.
- 고유 ID(예:
4. Pending, In Progress 및 Resolved 상태 관리
캠퍼스 헬프데스크는 엄격하게 정의된 3단계 수명 주기를 따릅니다:
[ Pending ] ───► [ In Progress ] ───► [ Resolved ]
▲ ▲ │
└──────────────────────┴─────────────────────┘ (필요시 재개설 가능)
상태 정의 및 시각적 디자인 시스템
Pending:- 의미: 학생/직원이 제출한 새 이슈, 분류 또는 할당 대기 중.
- 색상 테마: 호박색(
#d97706), 배경#fef3c7, 테두리#fde68a. - 진행 단계: 1단계 활성.
In Progress:- 의미: 기술자 또는 캠퍼스 부서가 티켓을 접수하여 적극적으로 조사 또는 수리 중.
- 색상 테마: 로열 블루(
#2563eb), 배경#dbeafe, 테두리#bfdbfe. - 진행 단계: 1단계 및 2단계 활성.
Resolved:- 의미: 수리 완료, 장비 교체 또는 서비스 복원.
- 색상 테마: 에메랄드 그린(
#059669), 배경#d1fae5, 테두리#a7f3d0. - 진행 단계: 1, 2, 3단계 모두 활성.
수명 주기 규칙 및 감사 기록
- 모든 상태 전환은 티켓의
history배열에 이벤트를 추가해야 합니다:{ status: newStatus, timestamp: new Date().toISOString(), note: `Status updated to ${newStatus}` } - 내부 직원 메모 업데이트는 티켓의 원래
createdAt을 재설정하지 않고adminNote와updatedAt을 업데이트해야 합니다. - 업데이트는 즉시
localStorage(campus_helpdesk_tickets_v1)에 동기화되어야 합니다.
5. 대시보드 통계 정확성 유지
관리자 대시보드는 실시간 운영 가시성을 제공합니다. 모든 KPI 메트릭 및 차트 계산은 신뢰할 수 있는 데이터 소스인 tickets 배열에서 동적으로 파생되어야 합니다:
메트릭 계산
- 전체 티켓 수: $$\text{Total} = \text{tickets.length}$$
- Pending 개수: $$\text{Pending} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
- In Progress 개수: $$\text{In Progress} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
- Resolved 개수: $$\text{Resolved} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
- 해결율(%) : $$\text{Resolution Rate} = \begin{cases} \text{Math.round}\left(\frac{\text{Resolved}}{\text{Total}} \times 100\right), & \text{if Total} > 0 \ 0, & \text{otherwise} \end{cases}$$
- 높음 및 긴급 우선순위 대기열: $$\text{Urgent/High} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Urgent' \lor t.\text{priority} === 'High').\text{length}$$
- 카테고리 및 우선순위 분포:
- UI 깜빡임 또는 0으로 나누기를 방지하기 위해 개수가 0이더라도 사전 정의된 모든 카테고리 및 우선순위에 대한 개수를 계산합니다.
- 진행률 표시줄 너비 백분율이 항상 $\le 100%$가 되도록 합니다.
성능 유지를 위해 모든 통계 계산을 [tickets]을 종속성으로 사용하는 React의 useMemo 훅 내부에 래핑하십시오.
6. 변경 사항 테스트 및 빌드 실행
코드 변경 사항을 제출하거나 작업을 완료로 표시하기 전에 정적 분석 및 프로덕션 빌드 단계를 통해 애플리케이션을 확인하십시오:
확인 절차
-
프로젝트 디렉토리로 이동:
cd "campus-helpdesk" -
정적 코드 린트 실행:
npm run lint- 종료 코드
0으로 종료되어야 합니다. - 사용되지 않은 import, 변수 또는 이스케이프되지 않은 JSX 엔터티가 없는지 확인하십시오.
- 종료 코드
-
프로덕션 빌드 실행:
npm run build- Vite가 오류나 경고 없이 프로덕션 에셋 번들링을 완료하는지 확인하십시오.
dist/index.html,dist/assets/*.css및dist/assets/*.js가 성공적으로 생성되었는지 확인하십시오.
-
LocalStorage 지속성 확인:
- 티켓 제출 시
localStorage.getItem('campus_helpdesk_tickets_v1')이 업데이트되는지 테스트하십시오. - 티켓 상태 업데이트가 페이지 새로 고침 후에도 유지되는지 테스트하십시오.
- "Reset Sample Data" 및 "Clear All" 기능을 테스트하십시오.
- 티켓 제출 시
7. 오류 정직하게 보고
시스템 상태 또는 오류를 보고할 때 정직성은 필수적입니다:
- 실패를 숨기지 마십시오: 빌드 오류, 구문 오류 또는 린트 실패가 발생하면 정확한 오류 메시지, 파일 이름 및 줄 번호를 보고하십시오.
- 근본 원인 설명: 오류가 발생한 이유를 설명하십시오(예: 누락된 import, 스토리지 파서에서 처리되지 않은 null 케이스, 깨진 prop 계약).
- 확인된 수정만 보고: 확인 명령(
npm run lint/npm run build)을 다시 실행하고 종료 코드0을 확인하지 않고는 문제가 수정되었다고 주장하지 마십시오. - 사용자 투명성: 예상치 못한 브라우저 제한 또는 localStorage 할당량 문제가 발생하면 사용자에게 제한 사항을 사전에 설명하고 명확한 기술적 옵션을 제시하십시오.