# AI JSON Schema v1

## 1. 목적

AI 응답은 서버가 검증할 수 있는 고정 JSON 구조로 제한한다.

이 문서는 MVP에서 사용할 AI 분석 응답 스키마 v1이다.

## 2. 최상위 구조

```json
{
  "schema_version": "v1",
  "intent": "create_task",
  "confidence": 0.91,
  "needs_human_review": false,
  "review_reason": null,
  "matched_task_id": null,
  "matched_task_candidates": [],
  "task": {},
  "update": {},
  "report": {}
}
```

## 3. intent 허용값

- `create_task`
- `update_task`
- `complete_task`
- `assign_task`
- `change_schedule`
- `note_only`
- `unclear`

## 4. task 구조

```json
{
  "title": "견적서 수정본 확인",
  "summary": "거래처 요청사항을 반영한 견적서 수정본 확인",
  "description": "김민수 담당자가 내일까지 견적서 수정본을 확인해야 한다.",
  "assignee_name": "김민수",
  "assignee_id": 12,
  "due_date": "2026-07-02",
  "priority": "normal",
  "status": "new"
}
```

## 5. matched_task_candidates 구조

```json
[
  {
    "task_id": 101,
    "title": "홈페이지 메인 시안 수정",
    "assignee_id": 12,
    "score": 0.84,
    "reason": "담당자와 업무 제목이 유사하고 최근 업데이트된 업무"
  }
]
```

후보가 없으면 빈 배열을 사용한다.

## 6. update 구조

```json
{
  "update_type": "progress_note",
  "note": "시안 전달이 완료됨.",
  "new_status": "in_progress",
  "changed_fields": {
    "status": {
      "from": "new",
      "to": "in_progress"
    }
  }
}
```

## 7. report 구조

```json
{
  "include_in_daily_report": true,
  "report_summary": "김민수 담당자의 견적서 수정본 확인 업무가 신규 등록됨.",
  "risk_note": null
}
```

## 8. 자동 반영 가능 조건

다음 조건을 모두 만족해야 자동 반영한다.

- JSON 파싱에 성공한다.
- `schema_version`이 지원 버전이다.
- `intent`가 허용값이다.
- `confidence`가 기준값 이상이다.
- `needs_human_review`가 `false`다.
- 담당자가 필요한 업무라면 `assignee_id`가 존재한다.
- 기존 업무 업데이트라면 `matched_task_id`가 존재한다.
- 상태값과 우선순위가 허용값이다.
- 입력과 출력이 기능별 토큰 제한 안에 있다.

## 9. 확인 필요 처리 조건

다음 중 하나라도 해당하면 확인 필요로 저장한다.

- `confidence`가 기준값 미만이다.
- `needs_human_review`가 `true`다.
- `intent`가 `unclear`다.
- 기존 업무 후보가 여러 개이고 점수 차이가 작다.
- 담당자를 찾지 못했다.
- 마감일 표현이 불명확하다.
- 서버 검증에 실패했다.

## 10. 예시

```json
{
  "schema_version": "v1",
  "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,
    "changed_fields": {}
  },
  "report": {
    "include_in_daily_report": true,
    "report_summary": "김민수 담당자의 견적서 수정본 확인 업무가 신규 등록됨.",
    "risk_note": null
  }
}
```