docs(명세): 「제품 흐름 밖 화면」 절을 만들고 /console 을 올린다 (#522 · #594 후속)

[gitIt-sehyeon]

#594 리뷰에서 제 몫으로 받은 자리입니다. /console 이 머지돼서(62f1ed4) 조건이 찼습니다.

Refs #522 · #594 · #600

무엇이 문제였나

8절의 문단 하나가 화면 하나만 다뤘는데, 같은 성격의 화면이 둘이 됐습니다.

전   "번호 없는 화면 — 사용 가이드(`/guide`)"      한 문단 · 화면 하나
후   "### 제품 흐름 밖 화면 — 번호를 주지 않는다"     절 · 표로 둘

문단을 절로 올리고 표로 갈랐습니다.

경로	무엇	누가	왜 흐름 밖인가
/guide	사용 가이드	제한 없음	제품이 아니라 제품 설명이다
/console	운영 콘솔 (F-OPS-001)	ADMIN	운영 상태를 보는 자리다

번호를 안 주는 근거는 그대로 살렸습니다 — 얹으면 명세에 없는 화면이 명세 화면인 척하고, 8절 표가 답하는 질문("고객·판매자가 어느 순서로 무엇을 하나")에 이 둘이 섞입니다.

❗/console 에는 근거가 하나 더 있습니다 — 권한

/guide 는 "제품이 아니라 문서라서" 흐름 밖인데, /console 은 그것 말고 제품 흐름에서 링크하면 안 되는 이유가 따로 있습니다.

ops:status:read   ADMIN 뿐이다 (rbac_policy.yaml)
판매자 화면에 걸면  누르는 사람 대부분에게 403

#594 리뷰에서 정리된 "링크가 있다 ≠ 그 API 를 부를 권한이 있다" 를 그 자리에 적었습니다. 근거가 다르면 나중에 하나가 바뀌어도 다른 하나가 남는데, 한 문장으로 뭉치면 그게 안 보입니다.

❗「닿을 수 있다」를 안 쓴 상태로 두지 않았습니다

이 파일은 CLAUDE.md 상 구현 완료 시점의 명세입니다. 그래서 지금 상태를 그대로 적었습니다.

❗대신 지금은 어디서도 안 걸린다(이슈 #600) — 닿는 길이 주소 직접 입력뿐이라 /upload 와 같은 상태다(#406).

안 적으면 "제품 흐름에서만 안 건다" 로 읽혀서 다른 어딘가에 링크가 있다고 믿습니다. #594 가 범위를 좁히며 /guide 한 줄을 뺐고 그 진입점은 #600 이 들고 있습니다.

12.1 알려진 한계에도 9번으로 올렸습니다 — 데모 전에 남아 있는지 목록에서 보여야 하는 종류입니다.

검증

server ./gradlew test    816건 통과

ErrorCodeContractTest 가 이 파일의 §9 코드 목록 · 「오류 코드 N종」 · 「N 벌」을 읽습니다. 8절만 바뀌어서 셋 다 안 흔들립니다 — 확인했습니다(오류 코드 14종 … 여섯 벌 그대로).

범위 밖

• /console 진입점 — #600
• tokens.css 규칙 1 의 3색 예외 — #601

둘 다 web/ 이라 오준서 님 자리입니다.

@junseo2323 @hd0rable @yoonjiseok

[hd0rable]

승인합니다. 번호를 안 주는 이유를 「표가 답하는 질문」으로 적은 것이 이 절의 값입니다 —
"고객·판매자가 어느 순서로 무엇을 하나" 에 운영 콘솔이 섞이면 그 표가 답을 못 합니다.
/guide 하나였던 문단을 둘 이상이 들어갈 수 있는 절로 바꾼 것도 맞습니다.

대조한 것

rbac_policy.yaml:220     ops:status:read → roles: [ADMIN]        「판매자 화면에서 걸면 403」 ✓
App.tsx:25-37            /guide · /console 둘 다 SCREENS 밖       ✓ 이 절의 표와 같다
Guide.tsx                console·콘솔 언급 0건                    ✓ 「지금은 어디서도 안 걸린다」
이슈 #600                OPEN · 담당 오준서                       ✓ 그 사실이 추적되고 있다

「링크가 있다는 것과 그 API 를 부를 권한이 있다는 것은 다르다」 가 정확합니다. 제가
#594 리뷰에서 같은 자리를 짚었는데, 그건 «제품 흐름에서 링크하지 않는 이유» 이고 이 절은
그것을 명세의 문장으로 옮긴 것이라 자리가 맞습니다.

그리고 /upload 와 같은 상태라고 적은 것이 좋습니다 — 「진입점이 없다」를 결함으로
남기지 않고 이미 있는 같은 상태(#406)에 붙여서, 다음 사람이 둘을 한 번에 봅니다.

❗한 자리 — 요약표 행이 아직 가이드만 듭니다

:550 입니다.

| 화면 | S-01~S-08 | S-01 은 범위 밖 · 번호 없는 사용 가이드(`/guide`) |

이 PR 이 「번호 없는 화면이 둘」로 바꿨는데 그 행은 하나만 듭니다. 같은 문서 안에서
8절은 둘, 요약표는 하나라, 요약만 보는 사람은 /console 이 없는 것으로 읽습니다.

| 화면 | S-01~S-08 | S-01 은 범위 밖 · 번호 없는 화면 둘(`/guide` · `/console`) |

이 레포가 계속 밟는 「한 값이 두 곳에 있고 한쪽만 고쳐진다」와 같은 모양이라 짚습니다 —
#583(에러 코드 수)·#599(볼륨 목록)가 이번 주에 같은 부류였습니다. 한 줄이라 이 PR 에
얹는 쪽이 싸 보입니다.

곁가지 — 그 요약표에 진입점을 안 적는 것이 맞습니다

「미결 9」로 12.1 표에 올리신 것이 맞는 자리입니다. 요약표는 «무엇이 있나» 이고 진입점은
«닿을 수 있나» 라 층이 다릅니다 — 둘을 한 칸에 적으면 다음에 진입점이 생겼을 때 고칠 자리가
둘이 됩니다.

나머지 — 이견 없습니다

• S-00(/admin) 문단을 그대로 남긴 것 — 지운 화면의 기록이라 새 절 안에 있어야 합니다.
• 표에 「왜 흐름 밖인가」 열을 둔 것 — 다음에 셋째가 생길 때 그 칸을 채우면서 «정말
  흐름 밖인가» 를 스스로 묻게 됩니다. 열 이름이 그 판단을 요구합니다.
• F-OPS-001 · GET /ops/status 를 경로 옆에 적은 것 — 명세에서 화면과 기능·엔드포인트가
  같이 보이는 유일한 자리라 그게 필요합니다.

[gitIt-sehyeon]

요약표도 고쳤습니다(a750eee). 짚어 주신 그대로 8절만 바꾸고 부록을 두고 왔습니다.

8절      번호 없는 화면 둘 (/guide · /console)
요약표    번호 없는 사용 가이드(/guide)          ← 낡았다

이 레포가 계속 밟는 「한 값이 두 곳에 있고 한쪽만 고쳐진다」와 같은 모양

맞습니다. 그리고 제가 이번 주에 그 부류를 두 번 봤으면서 같은 걸 했습니다 — #599(볼륨 목록)를 낸 것이 바로 그 이유였고, 거기서도 윤지석 님이 «두 자리 목록이 갈렸다» 를 다시 짚어 주셨습니다. 같은 문서 안이면 더 안 보이는 것 같습니다.

진입점을 요약표에 안 적는 판단에도 동의합니다 — 그 표는 «무엇이 있나» 이고 진입점은 «닿을 수 있나» 라, 한 칸에 적으면 #600 이 닫힐 때 고칠 자리가 둘이 됩니다. 12.1 의 9번이 그 층입니다.

검증: server 816건 통과(§9·「N 벌」·「N종」 그대로).

@junseo2323 님 리뷰만 남았습니다.

[gitIt-sehyeon]

main 을 병합해 충돌을 풀었습니다(bca1a22). #591 이 들어가면서 같은 표의 인접 행과 부딪혔습니다.

| API  | … 오류 코드 14종 → **15종** 여섯 벌 대조 |          ← #591 (DOCUMENT_UNREACHABLE)
| 화면 | … 번호 없는 **화면 둘**(/guide · /console) |        ← 이 PR

둘 다 살렸습니다. 각각의 행을 고친 것이라 내용 충돌은 없고, git 이 같은 hunk 로 본 것뿐입니다.

❗그런데 이게 이 PR 이 고치는 것과 같은 표입니다. 부록 요약표 한 칸에 «에러 코드 수» 와 «화면 목록» 이 나란히 있어서, 서로 무관한 두 PR 이 같은 자리를 건드립니다. @hd0rable 님이 짚어 주신 «8절만 고치면 요약표가 낡는다» 와 짝인 성질입니다 — 요약이라 값이 모여 있고, 그래서 모이는 만큼 자주 부딪힙니다. 지금 규모에서는 충돌이 곧 신호이므로(둘 다 보게 된다) 손댈 것은 없다고 봅니다.

검증

server ./gradlew test    822건 통과   (#591 의 +1 · #592 의 +5 포함)
§9                       「오류 코드 15종」 · DOCUMENT_UNREACHABLE 포함 — main 그대로
부록 요약표               15종 · 화면 둘

충돌 상태에서는 pull_request_review 가 유실돼 승인이 들어와도 워크플로가 안 돕니다(CLAUDE.md). 이 푸시의 synchronize 로 다시 돌 것입니다.

@junseo2323 님 리뷰만 남았습니다.

[junseo2323]

절을 만든 판단과 「번호를 주지 않는다」 근거는 이견 없습니다. 그런데 셋째가 있습니다 — /audit.

시점 문제라 놓칠 자리였습니다. 이 브랜치가 main 을 머지한 것이 08:54Z 이고, #604(감사 기록 화면)가 머지된 것이 16분 뒤 09:10Z 입니다. 지금 이 PR 은 /audit 이 없는 main 위에 서 있습니다.

git log origin/main ^pr-602      72ebbfe Merge pull request #604 …   ← 이 브랜치에 없다
web/src/App.tsx:46               <Route path="/audit" element={<AuditPage />} />

/audit 은 정확히 이 절이 말하는 그 자리입니다

제 화면이라 App.tsx 에 근거를 적어 뒀는데, 그 문면이 이 PR 의 문면과 같습니다.

App.tsx:39   "감사 기록. /console 과 같은 자리다 — 제품 흐름 밖이고 SCREENS 에 안 넣는다"
권한          audit:read · audit:verify — COMPL 뿐 (rbac_policy.yaml)
진입점        없다. 주소 직접 입력뿐 — /console · /upload 와 같은 상태다
명세 8절 표    없다 (grep 0건)

그래서 머지되는 순간 이 문서의 세 자리가 틀립니다.

369행  "그 흐름 밖에 둘이 더 있고, 둘 다 화면 번호가 없다"        → 셋
표     /guide · /console 두 행                                → /audit 행이 빠졌다
565행  "번호 없는 화면 둘(/guide · /console)"                   → 셋

제안 — 표에 한 행, 두 문면에 「셋」

| `/audit` | 감사 기록 (F-CMN-002 · `GET /dashboard/audit-summary`·`audit-verify`) | COMPL | **그 기록을 믿을 수 있는가**를 보는 자리다. S-08 안의 탭으로 두지 않는다 — 그쪽은 `aggregate:*`(COMPL `org` · MGR `branch`)이고 여기는 COMPL 뿐이라 얹으면 MGR 에게 상시 403 인 탭이 생긴다 |

/console 문단이 "링크가 있다는 것과 그 API 를 부를 권한이 있다는 것은 다르다" 로 세워 둔 근거가 /audit 에도 그대로 걸립니다 — 오히려 더 좁습니다(ADMIN 하나가 아니라 COMPL 하나).

12.1 의 9번 행도 같이 봐 주세요

지금 "운영 콘솔(/console)에 진입점이 없다" 인데, /audit 도 같은 상태이고 원인도 같습니다(제 두 PR 이 각각 범위를 좁히며 링크를 안 냈습니다). 한 행으로 묶든("제품 흐름 밖 화면에 진입점이 없다 — /console · /audit") 행을 하나 더 들든 그쪽 판단에 맡기겠습니다. 어느 쪽이든 제 몫이 맞습니다(#600).

나머지는 그대로 좋습니다

/console 을 안 링크하는 이유를 권한으로 적은 것, #600 을 ❗로 같은 문단에 세운 것, S-00 문단을 그대로 유지한 것 — 다 맞습니다. 위 세 자리만 고쳐 주시면 바로 승인하겠습니다.

[junseo2323]

줄 번호 하나 정정합니다 — "그 흐름 밖에 둘이 더 있고" 는 374행입니다(369 는 S-07 행). 565행 과 표 위치는 그대로입니다.

[gitIt-sehyeon]

다섯 자리를 고쳤습니다 (d256a5c). 시점 지적이 정확합니다 — main 을 다시 머지하고 맞췄습니다.

이 브랜치가 main 머지    08:54Z
#604(/audit) 머지        09:10Z    ← 16분 뒤. 절을 쓰는 동안 화면이 하나 더 들어왔습니다

고친 자리

374행   "둘이 더 있고, 둘 다 번호가 없다"     → 셋
표      /audit 행 추가                      제안하신 문면 그대로
383행   링크 안 하는 이유를 둘로 넓힘         /console ADMIN · /audit COMPL
479행   §12.1 9번을 한 행으로 묶음
565행   "번호 없는 화면 둘"                  → 셋

표 행은 주신 문면을 그대로 썼습니다. "S-08 안의 탭으로 두지 않는다 — 그쪽은 aggregate:*(COMPL org · MGR branch)이고 여기는 COMPL 뿐이라 얹으면 MGR 에게 상시 403 인 탭이 생긴다" 가 제가 /console 에 쓴 근거보다 한 칸 구체적입니다. 제 쪽은 "누르는 사람 대부분에게 403" 이었는데, MGR 이라는 특정 역할이 상시 403 을 본다는 것이 S-08 탭 안이라는 자리에서만 나오는 이야기라 그렇습니다.

§12.1 9번 — 한 행으로 묶었습니다

한 행으로 묶든 행을 하나 더 들든 그쪽 판단에 맡기겠습니다.

묶었습니다. 원인이 같고(범위를 좁히며 링크를 안 냄) 담당도 같습니다(#600). 나누면 같은 일을 두 번 추적하게 되고, 둘 중 하나만 닫히는 상태가 생깁니다.

| 9 | 제품 흐름 밖 화면에 진입점이 없다 — `/console` · `/audit` 둘 다 닿는 길이 주소
      직접 입력뿐이다 | #594 가 범위를 좁히며 `/guide` 한 줄을 뺐고, `#604`(`/audit`)도
      같은 상태로 들어왔다 | 오준서 (#600) |

❗셋 중 하나는 원인이 다릅니다 — 그 구분을 문단에 넣었습니다

고치면서 보니 /guide 만 성격이 다릅니다.

/console   ADMIN 뿐    링크를 안 건 것이 **판단**이다 (걸면 대부분 403)
/audit     COMPL 뿐    같다
/guide     제한 없음    링크를 안 건 것이 **결과**다 — #594 가 좁히며 한 줄을 뺐다

#600 이 추적하는 것은 사실 /guide 쪽 성격입니다 — 권한 때문에 안 건 것이 아니라 실수로 빠진 것이니까요. 이 구분이 없으면 #600 을 닫을 때 "셋 다 어디선가 링크하면 되나" 로 읽힐 수 있어서 한 문단 넣었습니다.

「셋」이 맞는지 라우트를 전수로 확인했습니다

흐름 밖      /guide · /console · /audit                     셋 ✅
번호 있음    /upload = S-01 (범위 밖이지만 번호가 있다)
제품 흐름    / · /interview · /simulator · /judgment
            · /override · /report · /dashboard             일곱 (S-02~S-08)

/upload 가 «번호 없는 화면» 에 안 드는 것이 565행의 "S-01 은 범위 밖" 과 짝이 맞습니다 — 범위 밖인 것과 번호가 없는 것은 다릅니다.

검증

server 전체        BUILD SUCCESSFUL · 825건
npm run build      통과
main 재머지         0a9c27f (#593 · #596 · #603 이 들어왔습니다 — 이 문서와 겹치는 파일 0건)

[junseo2323]

요청한 다섯 자리는 전부 반영됐습니다 — 전수로 확인했습니다. 그런데 그때 같이 넣으신 /guide 문단이 제 커밋과 반대 방향입니다. 한 문단이라 고쳐 주시면 바로 승인합니다.

먼저 — 고치신 자리는 다 맞습니다

374행   "그 흐름 밖에 셋이 더 있고, 셋 다 화면 번호가 없다"        ✅
표      /audit 행 (COMPL · S-08 탭으로 두지 않는 이유)            ✅
384행   링크 안 하는 이유를 둘로 (ADMIN · COMPL)                  ✅
484행   §12.1 9번 한 행으로 묶음                                  ✅
570행   요약표 "번호 없는 화면 셋"                                ✅

「셋」이 맞는지 main 라우트로 다시 셌습니다 — /guide·/console·/audit 셋, /upload 는 번호(S-01)가 있고, 제품 흐름 일곱(S-02~S-08)입니다. §12.1 을 한 행으로 묶은 판단에도 동의합니다: 원인도 담당도 같아서 나누면 하나만 닫힙니다.

❗그런데 /guide 는 닿습니다

390행  `/guide` 는 다르다. 권한 제한이 없으므로 **링크를 안 건 것이 판단이 아니라 결과**다
       — `#594` 가 범위를 좁히며 그 한 줄을 뺐고, 그것이 `#600` 이 추적하는 일이다.

/guide 는 S-02 가 걸고 있습니다. 9/6 부터이고 지금 main 에 그대로 있습니다.

web/src/pages/S02_SessionStart.tsx:267   <Link className="ss__navlink" to="/guide">
                                           처음이신가요? 사용 가이드
a48268b (9/6)  feat(web): 사용 가이드 화면 — 목차가 못 메우는 자리를 캡처로 메운다

바로 위 주석이 왜 하필 S-02 인지까지 적어 뒀습니다 — "BrandBar 는 세션 중에 습관적으로 눌렀다가 세션 밖으로 나가는 사고 때문에 안 걸고, S-02 는 태블릿을 넘기기 전이라 그 사고가 없다".

❗빠진 한 줄은 /guide 안에 있던 /console 진입점입니다

제가 낸 커밋이라 확실합니다.

63d91f7 (9/10, 오준서)  feat(F-OPS-001): 범위를 콘솔 화면 하나로 좁힌다
                        — /guide 진입점과 tokens.css 예외 문면을 뺀다

  - web/src/pages/Guide.tsx   「여기서 자주 막혀요」 진입점 한 줄   ← /guide → /console
  - web/src/styles/tokens.css 판정 3색 예외 문단

「/guide 진입점」은 「/guide 로 가는 링크」가 아니라 「/guide 에 있던 (콘솔로 가는) 진입점」입니다. 커밋 메시지가 줄임말이라 뒤집혀 읽히는 자리인데, 지운 줄은 Guide.tsx 안에 있었고 그것이 가리키던 곳이 /console 입니다. #600 의 제목이 "/console 이 어디서도 안 걸린다" 인 이유가 그것입니다.

무엇이 나쁜가 — #600 을 닫을 사람이 엉뚱한 자리를 봅니다

이 문서는 구현 완료 시점의 명세이고, 이 절 전체가 「어느 화면에 어떻게 닿나」를 말합니다. 지금 문면대로면 #600 을 닫는 사람(접니다)이 /guide 로 가는 링크를 어딘가에 걸려고 합니다 — 이미 걸려 있는데요. 되돌릴 자리는 Guide.tsx 의 그 한 줄입니다.

덤으로, 고치면 이 절의 논지가 더 깔끔해집니다. 「권한이 있으면 안 건다 / 없으면 건다」가 셋에 그대로 적용되니까요.

/console · /audit   권한이 좁다 → 제품 흐름에 안 건다 (판단)      + 지금은 아무 데서도 안 걸린다 (#600)
/guide              권한 제한 없음 → 제품 흐름(S-02)이 건다 ✅

고칠 모양

`/guide` 는 다르다 — **닿는다.** 권한 제한이 없으므로 제품 흐름에 걸 수 있고, 실제로 S-02 가
「처음이신가요? 사용 가이드」로 건다(BrandBar 가 아닌 이유는 그 자리 주석에 있다). `#594` 가
범위를 좁히며 뺀 한 줄은 `/guide` 로 가는 링크가 아니라 **`/guide` 안에 있던 `/console`
진입점**이고(「여기서 자주 막혀요」), 그것이 `#600` 이 추적하는 일이다 — 되돌릴 자리도 거기다.

§12.1 9번 근거 칸의 "#594 가 범위를 좁히며 /guide 한 줄을 뺐고" 도 같이 보시면 좋겠습니다 — /guide 의 /console 진입점 한 줄로 적으면 두 자리가 같은 말을 합니다.