# AI 분석 설계

## 1. AI 역할

AI는 사용자의 자연어 입력을 업무 관리 시스템에서 사용할 수 있는 구조화 데이터로 변환한다.

AI의 역할은 다음과 같다.

- 입력 의도 분류
- 신규 업무와 기존 업무 업데이트 판별
- 담당자 추출
- 마감일 추출
- 업무 제목 생성
- 업무 요약 생성
- 상태 및 우선순위 추론
- 기존 업무 후보 매칭
- 사람 검토 필요 여부 판단

## 2. 입력 데이터

AI 분석에는 다음 데이터를 제공한다.

- 현재 입력 텍스트
- 입력자 정보
- 현재 날짜
- 등록된 담당자 목록
- 최근 업무 목록
- 담당자별 진행중 업무 목록
- 기존 업무 후보 목록

## 3. 출력 원칙

AI 출력은 반드시 JSON으로 제한한다.

문장 설명을 함께 출력하지 않는다.

알 수 없는 값은 추측하지 않고 `null`로 둔다.

판단이 애매하면 `needs_human_review`를 `true`로 설정한다.

## 4. AI 출력 JSON 초안

```json
{
  "intent": "create_task",
  "confidence": 0.91,
  "needs_human_review": false,
  "review_reason": null,
  "matched_task_id": null,
  "matched_task_candidates": [],
  "task": {
    "title": "견적서 수정본 확인",
    "summary": "거래처 요청사항을 반영한 견적서 수정본을 확인한다.",
    "description": "김민수 담당자가 내일까지 견적서 수정본을 확인해야 한다.",
    "assignee_name": "김민수",
    "assignee_id": 12,
    "due_date": "2026-07-02",
    "priority": "normal",
    "status": "new"
  },
  "update": {
    "update_type": null,
    "note": null,
    "new_status": null
  },
  "report": {
    "include_in_daily_report": true,
    "report_summary": "김민수 담당자에게 견적서 수정본 확인 업무가 신규 등록됨.",
    "risk_note": null
  }
}
```

## 5. intent 값

- `create_task`: 신규 업무 등록
- `update_task`: 기존 업무 업데이트
- `complete_task`: 업무 완료 처리
- `assign_task`: 담당자 배정 또는 변경
- `change_schedule`: 일정 또는 마감일 변경
- `note_only`: 업무 반영 없이 참고 메모
- `unclear`: 판단 불명확

## 6. 기존 업무 매칭 기준

기존 업무 업데이트 여부는 다음 정보를 조합해서 판단한다.

- 담당자 일치 여부
- 업무 제목 유사도
- 업무 설명 유사도
- 최근 업데이트 시점
- 마감일 근접성
- 상태가 완료되지 않았는지 여부
- 입력 내용에 포함된 지시어

기존 업무 후보가 2개 이상이고 신뢰도 차이가 작으면 확인 필요로 처리한다.

## 7. 사람 검토 필요 조건

다음 경우에는 자동 반영하지 않는다.

- `confidence`가 기준값보다 낮은 경우
- 담당자를 찾지 못한 경우
- 기존 업무 후보가 여러 개인 경우
- 마감일 표현이 애매한 경우
- 완료 처리인지 단순 진행 보고인지 불명확한 경우
- 입력 내용이 너무 짧은 경우

## 8. 프롬프트 구성 초안

```text
너는 업무 관리 시스템의 입력 분석기다.
사용자의 자연어 입력을 분석해 정해진 JSON 형식으로만 응답한다.

현재 날짜:
{current_date}

입력자:
{submitter}

담당자 목록:
{users}

기존 업무 후보:
{task_candidates}

사용자 입력:
{input_text}

규칙:
- 반드시 JSON만 출력한다.
- 알 수 없는 값은 null로 둔다.
- 추측이 필요한 경우 needs_human_review를 true로 한다.
- 신규 업무와 기존 업무 업데이트를 신중히 구분한다.
- 리포트에 들어갈 문장은 짧고 일관된 문체로 작성한다.
```

## 9. 검증 단계

AI 응답을 DB에 반영하기 전에 서버에서 다음을 검증한다.

- JSON 파싱 가능 여부
- 필수 키 존재 여부
- intent 허용값 여부
- status 허용값 여부
- priority 허용값 여부
- assignee_id 존재 여부
- matched_task_id 존재 여부
- due_date 날짜 형식

검증 실패 시 자동 반영하지 않고 확인 필요로 저장한다.

## 10. 처리 파이프라인

AI 처리의 전체 흐름은 [14-ai-processing-pipeline.md](14-ai-processing-pipeline.md)를 기준으로 한다.

핵심 원칙은 다음과 같다.

- AI API 키는 브라우저에 노출하지 않는다.
- AI 요청은 서버에서만 수행한다.
- 서버가 담당자 후보와 기존 업무 후보를 먼저 줄인다.
- AI는 정해진 JSON으로 판단 결과를 반환한다.
- 서버가 JSON을 검증한 뒤 DB에 반영한다.
- 자동 반영이 불가능하면 확인 필요로 저장한다.