DillieDocs
dillie.work

진행 기록과 상태 전이

CLI 로 티켓에 작업 기록을 댓글로 남기고, 상태를 옮기고, 완료·취소로 닫는 법을 다룬다. 기록 없이 닫힌 티켓은 나중에 무엇을 했는지 아무것도 말해 주지 않는다.

예시의 ACME 는 자기 프로젝트 키로 바꿔 쓴다.

작업 기록 남기기

상태만 옮기면 무엇을 했는지가 남지 않는다. 몇 주 뒤에 “이거 어떻게 고쳤더라” 를 묻는 사람은 커밋 로그보다 티켓을 먼저 연다. 댓글에는 결과와 근거를 담는다.

  • 무엇을 바꿨는가 — 찾아갈 수 있는 이름으로
  • 왜 그렇게 했는가 — 다른 방법을 버린 이유가 있으면 그것
  • 무엇을 확인했는가 — 통과한 검증, 그리고 확인하지 못한 것

마지막 항목을 빼지 않는다. “확인하지 못했다” 고 적어 두면 그것이 검토 대상으로 남고, “확인했다” 로 뭉개면 아무도 다시 보지 않는다.

닫지 않고 진행 기록만 남기려면 messages create 를 쓴다.

dillie --agent project messages create ACME <itemId> --data '{"content":"스테이징에 배포했습니다. 결제 재시도는 아직 확인하지 못했습니다."}'

messages create 는 아이템을 UUID 로만 받는다. 이슈 키밖에 모르면 먼저 조회해 응답의 id 를 쓴다.

dillie --agent project tasks get ACME ACME-123

댓글 작성자 정하기

CLI 가 남기는 댓글(tasks complete·tasks cancel 의 노트와 messages create)은 기본적으로 그 사용자의 자동화 봇 이름으로 남는다. 봇 이름은 사용자 이름 뒤에 「자동화」가 붙은 꼴이다(예: 「홍길동 자동화」). 도구가 남긴 기록과 사람이 직접 쓴 말을 나중에 구분할 수 있게 하기 위해서다.

사람이 직접 쓴 말을 남길 때만 --as-me 를 붙인다.

dillie --agent project tasks complete ACME ACME-123 --note "수행 요약 …"                # 자동화 봇이 남긴다
dillie --agent project tasks complete ACME ACME-123 --note "직접 확인했습니다" --as-me  # 내 이름으로 남는다
  • --agent 는 출력 형식일 뿐 작성자와 무관하다. 작성자는 --as-me 만 정한다.
  • 요청 본문(--data)에 작성자를 정하는 키를 넣지 않는다. asBot 을 넣으면 CLI 가 실행을 멈추고, 그 밖의 모르는 키는 서버가 400 으로 거부한다.
  • 서버가 자동화 봇으로 남길 수 없으면 명령이 실패한다. 사람 이름으로 바뀌어 남지는 않는다.

파일 첨부하기

로컬 파일은 attachments upload 로 업로드와 첨부를 한 번에 한다.

dillie --agent project attachments upload ACME <itemId> ./error.log

이미 업로드된 파일(fileId)을 붙일 때는 attachments attach 를 쓴다. 두 명령 모두 아이템을 UUID 로 받는다.

파일을 실은 댓글을 남기려면 --as-me 가 필요하다. 자동화 봇은 파일을 첨부할 수 없어서, --data 에 fileId 를 넣고 --as-me 를 빼면 CLI 가 실행을 멈춘다. CLI 가 작성자를 대신 바꾸지 않는 것은, 자기 이름으로 남은 댓글을 나중에야 발견하는 일이 없게 하기 위해서다.

dillie --agent project messages create ACME <itemId> \
  --data '{"content":"로그 첨부합니다","fileId":"<fileId>"}' --as-me

완료·취소에 노트 붙이기

완료·취소 명령에 노트를 붙이면 닫기와 기록이 한 번에 된다. 아이템은 이슈 키로 지목할 수 있다.

dillie --agent project tasks complete ACME ACME-123 --note "수행 요약 …"
dillie --agent project tasks complete ACME ACME-123 --note-file ./done.md
  • 노트가 여러 줄이거나 따옴표가 들어가면 --note-file 로 넘긴다. --note 안의 \n 은 줄바꿈이 되지 않는다.
  • --note 와 --note-file 은 함께 쓸 수 없다. 앞뒤 공백을 뺀 노트가 비어 있거나 10,000자를 넘으면 거부된다.

노트가 먼저 남고, 그것이 성공해야 상태가 바뀐다. 노트를 남기지 못하면 아이템은 닫히지 않는다. 반대로 노트는 남았는데 전이가 실패하면 노트만 남는다. 그때 같은 명령을 그대로 다시 실행하면 노트가 한 번 더 남으므로, 원인을 고친 뒤 노트 옵션 없이 다시 실행한다.

이미 완료된 아이템에 complete 를, 이미 취소된 아이템에 cancel 을 실행하면 상태는 바뀌지 않는다. 노트를 붙였다면 노트는 그대로 남는다.

하지 않기로 한 일 닫기

중복·보류·무효인 일은 완료가 아니라 취소로 닫는다. 취소는 완료와 나란한 별도의 종결이고, 완료로 닫으면 한 일이 부풀어 보인다.

dillie --agent project tasks cancel ACME ACME-123 --note "ACME-98 과 중복이라 취소"

취소된 아이템은 진척률 계산에서 분모와 분자 모두에서 빠지고, 「내 할 일」에서도 사라진다.

되돌리려면 uncancel 을, 완료를 되돌리려면 uncomplete 를 쓴다. 둘 다 닫기 직전 상태가 아니라 STATUS 의 첫 미착수(unstarted) 옵션으로 돌아간다.

상태 값 조회하기

워크플로는 프로젝트마다 다르다. 다른 프로젝트에서 본 상태 이름이 여기 있다는 보장이 없으므로 매번 조회한다.

dillie --agent describe ACME --fields fieldMap

role 이 STATUS 인 필드의 options 가 쓸 수 있는 옵션 id 목록이다. 다만 describe 의 옵션에는 카테고리(미착수·완료·취소 등)와 전이 규칙이 없다. 그것은 리스트 상세에서 읽는다.

dillie --agent project lists get ACME
  • fields 중 role 이 STATUS 인 필드의 config.options 마다 category 가 있다. complete 는 첫 completed 옵션으로, cancel 은 첫 cancelled 옵션으로 옮긴다.
  • workProfile.config 의 transitions 는 현재 상태 → 갈 수 있는 상태, initial 은 상태 없이 시작할 때 들어갈 수 있는 상태다.

이 규칙이 적용되는지는 workProfile 이 정한다. 세 경우의 뜻은 프로젝트 만들기와 계층 — 계층 규칙 직접 조회하기에 있다. 여기에 더해, agileMode: true 라도 transitions 가 없거나 비어 있으면 상태 규칙이 없고 initial 도 적용되지 않는다. initial 이 비어 있으면 시작 상태에 제한이 없다.

상태 옮기기

완료·취소가 아닌 상태로 옮길 때는 update 로 STATUS 값을 바꾼다.

dillie --agent project tasks update ACME ACME-123 --data '{"values":{"status":"<STATUS 옵션 id>"}}'

update 는 한 번에 한 칸만 옮긴다. 목표 상태가 transitions 에서 바로 갈 수 없는 곳이면 거부되므로, 중간 상태를 하나씩 거쳐 옮긴다.

완료·취소는 update 가 아니라 complete·cancel 로 한다. 이 두 명령은 서버가 전이 규칙에서 가장 짧은 경로를 찾아 중간 상태를 자동으로 거친다. 애자일이 아닌 프로젝트에서는 바로 옮긴다.

생성 시 상태 정하기

상태를 지정하지 않고 만들면, 애자일 프로젝트이고 transitions 가 있을 때 서버가 initial 의 첫 옵션(STATUS 옵션 순서 기준)을 넣는다.

dillie --agent project tasks create ACME --data '{"values":{"title":"…","_description":"…"}}'

만들 때 상태를 지정하면 그 값은 initial 에 있어야 한다(initial 이 비어 있으면 제한이 없다). 다른 상태에서 시작해야 하면 만든 뒤 상태 옮기기대로 옮긴다. 만든 뒤에는 되읽어 실제 상태를 확인한다.

dillie --agent project tasks get ACME ACME-123

옵션 id 보내기

선택지가 정해진 필드(상태·이슈 타입·우선순위)에는 화면의 라벨이 아니라 옵션 id 를 보낸다. 라벨은 키를 status·issueType·priority 같은 별칭으로 줬을 때만 옵션 id 로 바뀌고, 리스트 안에서 유일하다는 보장도 없다. 필드 id 를 키로 쓸 때는 반드시 옵션 id 를 보낸다.

커스텀 봇으로 메시지 보내기

워크스페이스에 만들어 둔 커스텀 봇 이름으로, 그 봇이 참여한 채널에 메시지를 보낼 수 있다. 태스크 댓글을 남기는 자동화 봇과는 별개다.

dillie --agent bots list

hasWebhookSecret 은 서버가 서명 키를 갖고 있는지이고, localApiKey·localWebhookSecret 은 이 기기가 그 평문을 갖고 있는지다. 메시지를 보내려면 둘 다 필요하다. 두 값은 서버가 다시 돌려주지 않으므로, 잃으면 재발급·재회전한다.

dillie --agent bots keys issue <botId>
dillie --agent bots secret rotate <botId>

봇은 이미 참여한 채널에만 메시지를 보낼 수 있다. 메시지를 보낸다고 참여가 생기지 않으므로 먼저 참여시킨다. 그렇지 않으면 봇 키 하나가 그 워크스페이스 모든 채널의 열쇠가 된다.

dillie --agent bots channels add <botId> <channelId>

봇 id 와 채널 id 를 매번 옮겨 적지 않도록 그 쌍에 이름을 붙여 둔다.

dillie --agent bots targets set notice --bot <botId> --channel <channelId>
dillie --agent bots send notice --text "배포가 끝났습니다"
  • 봇 키와 이름은 로그인한 사람별로 이 기기에 보관된다. 다른 계정으로 로그인하면 앞 계정의 것이 보이지 않는다. dillie logout 은 세션과 함께 이 기기의 봇 자격증명도 지운다 — 봇 키는 세션 없이도 인증되므로, 남겨 두면 로그아웃으로 끊으려던 접근이 남는다.
  • 키 발급·폐기, secret 회전, 채널 참여·제거는 OAuth 로그인 세션으로 쓸 수 없다. 봇 관리 권한이 있는 역할로 dillie login --method email 처럼 자격증명 로그인한 세션이어야 한다. 같은 이유로 이 명령들은 --workspace 와 함께 쓸 수 없다 — --workspace 는 OAuth 로그인 세션에서만 동작한다. 조회와 메시지 보내기는 이 제약과 무관하다.

project tasks·project messages·bots 명령은 --workspace·DILLIE_WORKSPACE 로 그 실행만 다른 워크스페이스에서 할 수 있다(CLI 0.21.0 이상). 규칙은 dillie CLI 로 일하기 — 워크스페이스 정하기에 있다.

문제 해결

상태 코드 일반을 읽는 법은 dillie CLI 로 일하기 — 문제 해결에 있다. 아래 오류는 모두 400 이고, error.code 로 서로 구분한다. 같은 입력은 다시 보내도 통과하지 않는다.

{
  "error": {
    "message": "…",
    "status": 400,
    "code": "INVALID_STATUS_TRANSITION"
  }
}

상태 전이가 거부됐다

INVALID_STATUS_TRANSITION — 지금 상태에서 그 상태로 바로 갈 수 없거나, STATUS 옵션에 없는 값을 보냈다. 메시지 속 (initial) 은 「상태가 없는 데서」라는 뜻이다(만들 때 initial 에 없는 상태를 지정한 경우). 상태 값 조회하기대로 transitions·initial 을 읽고, 갈 수 있는 상태를 고르거나 중간 상태를 거친다.

완료·취소가 거부됐다

  • STATUS_TRANSITION_PATH_NOT_FOUND — 전이 규칙에 지금 상태에서 완료(또는 취소)까지 가는 경로가 없다.
  • STATUS_COMPLETED_OPTION_MISSING·STATUS_CANCELLED_OPTION_MISSING — STATUS 에 completed·cancelled 카테고리 옵션이 없다.
  • STATUS_FIELD_MISSING — 리스트에 STATUS 필드가 없다.

노트를 붙여 실행했다면 노트는 이미 남아 있다. 원인을 고친 뒤 노트 옵션 없이 다시 실행한다.

프로젝트를 찾을 수 없다

오류 메시지가 어느 워크스페이스에서 찾았는지 알려 준다. 다른 워크스페이스의 프로젝트라면 projects list --all-workspaces 로 찾고 --workspace 로 그 워크스페이스를 지정한다.