# jira-issue-report

> 기간 기반 주간업무보고서 생성. 프로젝트 키와 기간을 입력하면 Jira에서 이슈와 코멘트를 가져와 팀별 카테고리 설정으로 마크다운 보고서를 자동 생성한다.

- Author: hnc-minjae
- Repository: hnc-minjae/claude-plugin
- Version: 20260208222957
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/hnc-minjae/claude-plugin
- Web: https://mule.run/skillshub/@@hnc-minjae/claude-plugin~jira-issue-report:20260208222957

---

---
name: jira-issue-report
description: 기간 기반 주간업무보고서 생성. 프로젝트 키와 기간을 입력하면 Jira에서 이슈와 코멘트를 가져와 팀별 카테고리 설정으로 마크다운 보고서를 자동 생성한다.
user_invocable: true
argument: "{PROJECT_KEY} {시작일}~{종료일} — 예: 'MYPROJ 2026-02-03~2026-02-07'"
---

# 기간 기반 이슈 보고서 생성 워크플로우

참조: [TEAM_CONFIG.md](TEAM_CONFIG.md) | [REPORT_FORMAT.md](REPORT_FORMAT.md) | [categories/](categories/)

## Step 0: 환경 검증

`JIRA_USER`, `JIRA_TOKEN` 환경변수 확인 → 미설정 시 안내 후 중단.

> `{API_BASE}`는 [TEAM_CONFIG.md](TEAM_CONFIG.md)에서 읽는다.

```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/myself" \
  -H "Accept: application/json" -w "\nHTTP_STATUS:%{http_code}"
```
HTTP 200 아니면 중단.

## Step 1: 인자 파싱

사용자 입력에서 프로젝트 키와 기간을 추출한다.

**형식**: `{PROJECT_KEY} {시작일}~{종료일}`

- `{PROJECT_KEY}`: 대문자 영문 프로젝트 키 (예: `MYPROJ`, `WEBTEAM`)
- `{시작일}`, `{종료일}`: `YYYY-MM-DD` 형식 (예: `2026-02-03~2026-02-07`)

파싱 결과:
- `PROJECT_KEY` — JQL 쿼리와 팀 설정 매칭에 사용
- `startDate`, `endDate` — JQL 기간 필터와 코멘트 필터에 사용

> 형식이 맞지 않으면 사용 예시를 보여주고 중단.

## Step 2: 이슈 조회 및 팀원 필터링

[TEAM_CONFIG.md](TEAM_CONFIG.md)에서 `{PROJECT_KEY}`로 팀 섹션을 찾는다.
- **매칭 팀 있음**: 해당 팀의 팀원 목록과 카테고리 파일 경로를 사용
- **매칭 팀 없음**: 팀원 필터 없이 전체 이슈 포함, `categories/DEFAULT.md` 사용

```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/search/jql" -G \
  --data-urlencode "jql=project = {PROJECT_KEY} AND updated >= \"{startDate}\" AND updated <= \"{endDate}\" ORDER BY key ASC" \
  --data-urlencode "fields=key,summary,status,assignee,fixVersions,parent,comment,issuetype,labels,components,created,updated,statuscategorychangedate,description" \
  --data-urlencode "maxResults=100" --data-urlencode "startAt=0" \
  -H "Accept: application/json"
```

> `total > maxResults`이면 `startAt` 증가시키며 반복.

팀원 목록이 있으면 해당 팀원의 이슈만 포함 (미지정 이슈 제외). 통계 집계 전에 적용.

## Step 3: 코멘트에서 작업 내용 추출

### 필터링 (3단계)

1. **조회 기간 내** 코멘트만 — `startDate` ~ `endDate`
2. **담당자 작성분만** — `comment.author.displayName == assignee.displayName`
3. **진행 내용만** — 의견/질문/요청/상태변경알림/인사/자동생성 코멘트 제외

### ADF 텍스트 추출

```
extractAdfText(node):
  text → node.text | hardBreak → "\n" | mention → "@"+attrs.text
  emoji → attrs.shortName | inlineCard → attrs.url
  content(배열) → children.map(extractAdfText).join("")
```

블록: paragraph→텍스트+줄바꿈, bulletList/orderedList→"- "+텍스트, heading→텍스트, codeBlock/table/media→무시

### 요약

- 1~2개 한국어 개조식 bullet ("~구현", "~수정", "~완료", "~적용")
- 여러 코멘트 통합. "..."으로 자르지 않음. 원문 복사 금지, 핵심만 재작성

### Fallback

완료/종료/Done → "{제목} 완료" | 진행중 → "{제목} 진행중" | 대기/To do → "{제목} 착수 예정"

## Step 4: fixVersion 확보

카테고리 설정 파일의 fixVersion 교차 조회 규칙을 따른다.

- 이슈 자체 fixVersions가 있으면 그대로 사용.
- 없으면 교차 조회 로직 적용: summary에서 외부 이슈 키 패턴 `\[{키}[-_]\d+\]` 추출 → 해당 이슈의 fixVersions API 조회 (결과 캐싱):
```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/issue/{issueKey}?fields=fixVersions" \
  -H "Accept: application/json"
```
→ `fixVersions[0].name` 사용. 실패 시 빈 값.

## Step 5: 이슈 분류 및 그룹핑

Step 2에서 결정된 카테고리 파일을 로드한다.

- 등록된 팀 → TEAM_CONFIG의 카테고리 설정 경로에서 로드
- 미등록 팀 → `categories/DEFAULT.md` 로드

카테고리 파일의 `### 섹션 N:` 헤더를 순서대로 파싱하여 섹션 목록을 구성한다. 각 섹션의 분류 규칙 테이블(P0~P5)과 그룹핑 설정을 적용한다.

## Step 6: 마크다운 생성

[REPORT_FORMAT.md](REPORT_FORMAT.md) 형식에 따라 생성. 섹션 순서는 카테고리 파일 정의 순서를 따른다. 빈 섹션은 출력하지 않음.

## Step 7: 관리 포인트 분석

팀원 이슈의 **summary, description(ADF), 전체 코멘트(담당자 외 포함)** 를 종합 분석.

판별 기준: 일정 지연/이관, 리소스 부족, 외부 의존성/차단, 의사결정 필요, 기술적 리스크, 범위 변경

> 코멘트 맥락을 종합 판단. 해당 사항 없으면 섹션 생략.

## Step 8: 파일 저장 및 결과 요약

```bash
mkdir -p ~/.tasks/reports
```
파일명: `issue-{PROJECT_KEY}-{YYMMDD-HHmm}.md` (KST, 특수문자 제거)

```
✅ 이슈 보고서 생성 완료
📁 파일: ~/.tasks/reports/issue-{PROJECT_KEY}-{timestamp}.md
📊 통계: 전체 {N}건 | 완료 {N}건 | 진행중 {N}건
📋 분류: {카테고리 파일에서 파싱한 섹션별} {N}건 | ... | 기타 {N}건
```

## 에러 처리

| 상황 | 대응 |
|------|------|
| 환경변수 미설정 | 설정 안내 후 중단 |
| 인증 실패 (401/403) | 토큰 확인 안내 후 중단 |
| 인자 형식 오류 | 사용 예시 제시 후 중단 |
| API 실패 (5xx) | 1회 재시도, 실패 시 에러 출력 |
| 이슈 0건 | "해당 기간에 이슈가 없습니다" |
| ADF 파싱 실패 | 해당 코멘트 무시, fallback 사용 |