Ptium v1.69.34

Ptium 1.69.34

화면이 없던 안내서

지금까지 안내는 docs/user-guide.md 한 장이었습니다. 글로만 적혀 있어서, 처음 쓰는 사람은
"편집기 오른쪽 패널"이 어느 것인지 화면을 열어 놓고 짐작해야 했고, 서버를 띄우고 지키는
사람을 위한 안내는 README 곳곳에 흩어져 있었습니다.

이번 릴리즈는 안내서를 둘로 나누고, 설명하는 화면마다 실제 화면을 붙였습니다.

문서	읽는 사람	담은 것
docs/USER_GUIDE.md (+ PDF)	화면을 쓰는 사람	제품이 하는 일, 처음 5분, 화면별 사용법, 자주 하는 작업, 막혔을 때 만나는 메시지와 대처, 용어
docs/ADMIN_GUIDE.md (+ PDF)	서버를 띄우고 지키는 사람	구성 요소, 붙여 넣을 수 있는 설치, config.go 와 auth/config.go 가 읽는 환경 변수 전부, 콘솔이 보관하는 설정, 역할, 운영, 장애와 그때 남는 로그 줄, 보안

docs/user-guide.md 는 정본을 가리키는 짧은 안내로 남고, README 도 새 문서를 가리킵니다.

사진은 제품에서 찍었습니다

docs/assets/guide/ 의 서른세 장은 손으로 찍은 것이 아닙니다. scripts/guide/screenshots.py 가
v1.69.32 릴리즈 이미지를 일회용 데이터베이스 위에 띄우고, 예시 덱을 채우고,
hong@example.com 으로 들어가 한 번의 실행으로 모든 화면을 찍었습니다. 그래서 사진끼리
서로 어긋나지 않습니다 — 대시보드에 보이는 덱이 목록에도, 편집기에도 같은 이름으로 있습니다.

이 스크립트는 다른 스크립트와 겹치지 않는 자기만의 변수에서 대상과 비밀을 읽고, 그것이
비어 있거나 이 기계 밖을 가리키면 멈춥니다. 서비스 설정은 바꾸지 않고, 자기가 심은 것에 표시를
남겨 두 번째 실행에서는 아무것도 더하지 않습니다.

실패한 덱이 있어야 보이는 화면

대기열, 오류 센터, 편집기의 실패 화면, 공유 목록 — 이 네 화면은 새 배포에는 아무것도 없어서
찍을 수 없었습니다. 빈 목록은 안내서에 싣지 않는 것이 기준이고, 오류 센터 사진 하나는 있었지만
오류가 없는 배포의 것이었습니다. 화면이 제 일을 하지 않는 순간의 사진입니다.

그래서 스크립트가 생성이 실패한 덱 하나를 직접 만듭니다. 모델 호스트가 그냥 꺼져 있으면 되지
않습니다 — 그때는 작성기가 오프라인으로 덱을 완성하고 그렇다고 말합니다. 대신 한 번의 생성에 한해
모델 주소를 배포 자신의 API 로 돌립니다. 그곳은 completions 호출에 401 과 JSON 본문으로 답하므로,
잘못 설정된 모델이라는, 운영자에게 실제로 닿는 종류의 실패가 됩니다. 옮긴 설정 두 개는
먼저 읽어 두었다가 finally 에서 되돌리고(scripts/e2e/withmodel.py 와 같은 방식), 두 번째
실행은 이미 실패한 덱을 찾아 설정에 손대지 않습니다.

그 결과로 다섯 장이 더 생겼습니다 — 실패한 덱과 사유가 보이는 대기열, 401 이 열린 오류 센터,
그 사건의 서랍, 공유 목록, 그리고 같은 실패를 보는 작성자 쪽 화면. 안내서는 이제 그 화면을
앞에 두고 말합니다: 작성자가 보는 사유 그대로의 다시 넣기·취소, 열림에서 해결까지의 상태
흐름(API 는 "조사 중"을 acknowledged 로 적는다는 것까지), 링크 회수. 사용자 안내서의 실패 항목은
버튼을 화면에 적힌 대로 생성 다시 시도라고 부르고, 관리자가 같은 덱을 대기열에서 보고
있다고 말합니다.

지키는 장치

internal/docs/told_test.go 는 제품이 읽는 모든 형식이 제품이 읽는다고 말하는 형식인지
봅니다. 안내서가 옮겨 가면서 이 검사는 정본이 아니라 안내문 한 줄을 읽고 있었고, 형식 이름이
하나도 없으니 제대로 실패했습니다. 이제 올릴 파일을 고르는 사람이 실제로 여는
USER_GUIDE.md 를 읽습니다.