---
name: lgucorp-confluence-docs
version: 1.0.4
description: lgucorp Confluence 문서를 작성, 갱신, 검토하고 사용자가 명시적으로 승인한 token metadata table을 지정된 draft/page에 동기화하는 운영 절차. Confluence 문서 작성, 컨플 문서 생성·수정·검토, Lab2 위키 업데이트, 승인된 token metadata table 동기화 요청에 사용한다.
---

# lgucorp-confluence-docs

## 목적

`lgucorp.atlassian.net`의 Lab2 기본 폴더 아래에서 Confluence 문서를 안전하게 작성, 갱신, 검토한다. 기본 대상은 [Lab2 폴더](https://lgucorp.atlassian.net/wiki/spaces/Lab2/folder/650886407)이며, 사용자 요청이 없으면 이 폴더 밖에 문서를 만들거나 이동하지 않는다.

## 언제 호출할지

- Confluence 또는 컨플 문서를 Lab2에 새로 작성해야 할 때
- Lab2 Confluence 문서를 수정하거나 최신 내용으로 갱신해야 할 때
- 기존 Lab2 Confluence 문서의 내용, 구조, 링크, 상위 폴더를 검토해야 할 때

## 입력

- `operation`: `create`, `update`, `review`, `sync-token-metadata-table` 중 하나 (필수)
- `title`: 새 문서 제목 또는 갱신·검토할 문서 제목 (create 필수)
- `page_id` 또는 `page_url`: 갱신·검토 대상. 제목만으로 대상이 하나로 확정될 때는 생략 가능 (update/review 필수)
- `content`: 작성·갱신할 최종 본문. Confluence storage 형식 또는 변환 가능한 Markdown/HTML (create/update 필수)
- `target_folder_id`: 기본값 `650886407`. 사용자가 다른 위치를 명시할 때만 변경 (선택)
- `atlassian_user`: HTTP Basic 사용자 식별자는 `leedongmyung@lguplus.co.kr`로 고정한다. Git 사용자 정보나 추정값으로 대체하지 않는다. (필수)
- `secret_store_path`: `sync-token-metadata-table`의 ignored user-key source file. raw token은 추출·전달하지 않고 user key 집합 대조에만 사용한다. (선택)
- `sync_target_path`: `sync-token-metadata-table`의 ignored target URL file. 이 파일은 user-approved exact target 하나만 가진다. (선택)

## 먼저 확인할 것

- [ ] repo root의 `token/.lgu-atlassian-token`이 존재하고, 내용은 한 개의 raw token뿐이며 mode가 `0600`인지 확인한다.
- [ ] `git check-ignore -q token/.lgu-atlassian-token`이 성공하고 `git ls-files --error-unmatch token/.lgu-atlassian-token`이 실패하는지 확인한다.
- [ ] API 호출은 `leedongmyung@lguplus.co.kr`와 token 파일을 사용한 HTTP Basic 인증으로 수행한다. 이 토큰에는 Bearer 인증을 사용하지 않는다.
- [ ] `GET /wiki/rest/api/user/current`과 `GET /wiki/api/v2/folders/650886407`으로 인증과 기본 폴더 접근을 확인한다. folder 응답에서 실제 `spaceId`를 읽는다.
- [ ] update/review는 `GET /wiki/api/v2/pages/{page-id}?body-format=storage`으로 대상 page id, 현재 title, version, parentId를 먼저 확인한다. 제목만으로 대상이 둘 이상이면 쓰기 작업을 중단하고 page id 또는 URL을 요청한다.
- [ ] create는 `GET /wiki/api/v2/folders/650886407/direct-children`을 페이지네이션까지 확인해 같은 제목의 문서가 없는지 검사한다. 같은 제목이 있으면 중복 생성하지 않고 update 대상으로 전환할지 확인한다.
- [ ] `sync-token-metadata-table`은 사용자가 지정한 local user-key source와 active IOP mapping metadata가 1:1로 대조되고, exact target이 명시된 경우에만 수행한다. source/target 모두 `0600`, ignored, untracked인지 확인한다.
- [ ] target이 draft URL이면 `draftId`를 추출해 `GET /wiki/api/v2/pages/{draftId}?body-format=storage`으로 title, status, version, parentId, storage body를 먼저 읽는다. raw token과 storage body 원문은 출력하지 않는다.

## 실행 절차

1. **안전한 인증 준비**
   - token은 `token/.lgu-atlassian-token`에서만 읽고, shell trace를 켜지 않는다.
   - `atlassian_user`는 반드시 `leedongmyung@lguplus.co.kr`를 사용한다. `git config user.email`, Git 사용자명, 환경별 추정값으로 대체하지 않는다. 최종 보고에는 실제 이메일을 쓰지 않는다.
   - 모든 요청의 host는 `https://lgucorp.atlassian.net`, base path는 `/wiki`로 고정한다.
   - token 원문을 shell 인자, curl verbose 출력, 파일명, JSON payload, tracked 문서, 최종 보고에 남기지 않는다.

2. **대상 폴더와 문서 식별**
   - 기본 parent는 folder id `650886407`이며 URL은 `https://lgucorp.atlassian.net/wiki/spaces/Lab2/folder/650886407`이다.
   - folder v2 응답의 `spaceId`와 대상 page의 `parentId`를 사용해 Lab2 기본 폴더 범위를 확인한다.
   - 기본 폴더 밖의 page id, URL, 폴더 이동 요청은 사용자가 명시적으로 허용한 경우에만 처리한다.

3. **문서 작성 또는 갱신**
   - create는 `POST /wiki/api/v2/pages`로 `spaceId`, `status: current`, `title`, `parentId: 650886407`, `body.representation: storage`, `body.value`를 보낸다. JSON은 `jq -n` 또는 동등한 구조화 생성기로 만들고, 본문이 JSON escape 오류 없이 전달되는지 확인한다.
   - update는 현재 page의 `version.number`와 `status`를 읽은 뒤 `PUT /wiki/api/v2/pages/{page-id}`로 `id`, 현재 `status`, `title`, storage body, `version.number: 현재값 + 1`을 보낸다. 명시적 요청이 없으면 title과 parent를 변경하지 않는다.
   - 본문 갱신은 전체 storage body를 교체하므로, 동시 편집 또는 draft가 있으면 최신 본문을 다시 읽고 사용자 요청 내용과 충돌하는지 검토한 뒤에만 쓴다.
   - HTTP 401/403/404/409 또는 예상하지 않은 2xx 외 응답에서는 재시도 쓰기를 하지 않고, 상태 코드와 민감값 없는 오류 요약만 보고한다.
   - `sync-token-metadata-table`은 user key와 active mapping metadata를 `principal_ref` 기준으로 대조한 뒤 `사용자`, `principal alias`, `token ref`, `상태`, `동기화 시각`만 storage table로 stream 생성한다. target body가 비어 있으면 표 body 전체를 쓰고, 비어 있지 않은 body는 전용 동기화 heading이 있는 경우에만 해당 섹션을 교체한다.
   - draft target은 `PUT /wiki/api/v2/pages/{draftId}`에 동일 id, 기존 title, 현재 `status: draft`, storage body, `version.number: 현재값 + 1`을 보낸다. Basic 인증과 JSON body는 non-logging stream으로 전달하며 raw token을 shell 인자·payload에 넣지 않는다.

4. **문서 검토**
   - review는 읽기 전용으로 수행한다. title, status, version, parentId, storage body의 heading 구조, 빈 섹션, 깨진 내부 링크 후보, 중복 제목, 사용자 요청과의 차이를 확인한다.
   - 검토 결과는 수정 권고와 근거를 분리해 보고하며, review 요청만으로 페이지를 수정하지 않는다.

5. **작성 후 검증과 보고**
   - create/update 뒤 `GET /wiki/api/v2/pages/{page-id}?body-format=storage`으로 id, title, status, version, parentId가 기대값인지 확인한다.
   - create는 `parentId=650886407`과 Lab2의 `spaceId`를 확인하고, update는 의도하지 않은 title 또는 parent 변경이 없는지 확인한다.
   - 결과에는 operation, page id, title, version, parent folder, page URL, 검토 결과 또는 검증 상태만 기록한다.

## 실행 결과 검증

- [ ] token 파일은 mode `0600`, ignored, untracked 상태를 유지한다.
- [ ] 기본 폴더 id `650886407`이 Lab2에서 조회되고 실제 `spaceId`를 확인했다.
- [ ] create/update 결과 page의 id, title, status, version, parentId를 재조회해 확인했다.
- [ ] review는 페이지 쓰기 요청 없이 끝났다.
- [ ] `sync-token-metadata-table`은 content id·status·version을 재조회하고, table의 행 수·사용자/alias/ref/status metadata가 active mapping과 일치하는지 내부 비교한다. 비교 결과만 기록하고 raw cell 값은 출력하지 않는다.
- [ ] raw token, Basic 인증 header, 전체 응답 본문이 tracked 파일이나 최종 보고에 남지 않았다.
- 검증 실패 시: 생성·갱신 완료로 보고하지 않고, 실패 단계와 HTTP 상태만 민감값 없이 보고한다. 이미 쓴 변경은 자동 삭제하거나 되돌리지 않는다.

## 출력 형식

```text
Confluence Lab2 docs
- operation: <create|update|review|sync-token-metadata-table>
- page: <page id and title>
- parent_folder: 650886407
- page_url: <canonical URL>
- result: <created|updated|reviewed|blocked>
- verification: <folder/auth/page re-read result>
- review_notes: <none or concise findings>
- raw_token_reported: no
```

## 금지 사항

- `token/.lgu-atlassian-token`의 원문 또는 Authorization header를 출력, 추적, 공유하지 않는다.
- `atlassian_user`에 `leedongmyung@lguplus.co.kr` 이외의 값이나 Git 사용자 정보를 사용하지 않는다.
- `sync-token-metadata-table`은 raw token, token hash, Authorization 값, provider credential, draft share URL을 Confluence storage table·payload·첨부 파일·로그·최종 보고에 쓰지 않는다.
- 기본 Lab2 폴더 밖에 새 문서를 만들거나 기존 문서를 이동하지 않는다. 예외는 사용자가 명시한 대상뿐이다.
- 제목이 모호하거나 동시 변경 충돌을 확인하지 못한 상태에서 update하지 않는다.
- review 요청만으로 쓰기 API를 호출하지 않는다.
- 삭제, purge, 폴더 삭제, 권한 변경을 이 스킬 범위에 포함하지 않는다.
