서버 모드 로그인 흐름 — 결정: A(서버 모드 데모 계정 매핑) — W4-09c 구현
2026-10-13, PC-B W1 4단계 5차 worker.
docs/fullstack-feature-layout.md§8 의 「실제 로그인 흐름(이메일 IdP →fitness_account매핑 생성)은 DEFERRED」를 그대로 두지 않고, 실행 계약(execution-contract §2 —DEFERRED는 승인 · 후속 필수)에 따라 근거 · 대안을 적고 코디네이터 승인을 요청했다. 2026-10-13 코디네이터 결정: A 승인 — W4-09c(다음 묶음). 상태는 DEFERRED 가 아니라 「결정: A — W4-09c」다(아래 §5 조건). 2026-10-13 W4-09c 구현 — §6.
1. 지금 상태(실측)
| 층 | 있는 것 | 없는 것 |
|---|---|---|
| 호스트 서버 인증 | configureFitnessAuth — Serverpod 인증 모듈 JWT · 이메일 IdP 조립(개발 · 시험 모드는 인증 코드를 콘솔에 찍음) |
— |
| 호스트 호출자 resolver | 운영 resolver: JWT 의 AuthUser → 신원 매핑 FitnessAccount → 업무 주체 · scope(bindFitnessHost) |
AuthUser ↔ FitnessAccount 매핑을 만드는 경로(가입 · 첫 로그인 · 데모 계정 연결) |
| 시험 | 생성 SDK 통합 86 · 계약 동등성 63 단계 — 시험 경계 토큰 demo:<계정>(FitnessItServer — 시험 전용, endpoint · 서비스를 대신하지 않음), realAuth 경로는 운영 resolver 를 쓴다 |
실제 IdP 로그인으로 매핑을 만든 뒤 업무를 부르는 시험 |
| 앱 · 콘솔 서버 모드 | registerFitnessServer() — 서버 fitnessAccount.me() 로 행위자, 로그인 · 매핑이 없으면 scope 없는 손님(업무가 실패 상태로 그려짐) |
서버 모드의 로그인 화면 · 역할 진입 |
| 공개 Pages(6표면) | localOnly 고정(COB_DEMO_ONLY=true) — 역할 버튼(FR-001) |
— (서버 모드는 공개 표면이 아니다) |
2. 근거
- PRD #662 — 로그인 FR 이 없다. 진입은 FR-001 「역할 버튼(회원 윤하린 · 매니저 배소율)」이고 §10 계정은 「회원 윤하린(데모) ·
매니저 배소율(데모)」, §11 은 역할별 scope(회원
fitness.book·fitness.cancel, 매니저fitness.cancel·fitness.attend·fitness.pass_admin, 강사fitness.attend)만 정한다. FB-4: 「공개 6표면은 localOnly · 업무 네트워크 0건, localOnly 와 실제 SDK Repository 가 같은 도메인 계약 · 시드/시계 fixture · 업무 결과를 충족하며 기존 투어 · 초기화 · 역할 전환이 통과」. §14 capability 는 외부 발송(푸시 · 알림톡)을 데모에서 빼고 알림함 기록으로 대체한다 — 이메일 인증 코드 발송도 같은 부류다. - S-19 · ADR v2 — AD-2 「인증 provider · 교차 기능 업무 · 통합 테스트는 호스트 소유」, AD-4 「(신원) 매핑 · 삭제 수명주기 · 접근 정책은 호스트 소유」. 기능 모듈(class_booking 등)은 세션 인지 호출자 포트만 받으므로 로그인 방식이 바뀌어도 기능 코드는 바뀌지 않는다.
- POC 선례 — demo-ecommerce-grocery(#659)도 서버 통합을 시험 경계 토큰으로 검증하고 로그인 UI 는 두지 않았다(같은 범위).
3. 대안
| # | 내용 | 비용 · 위험 | FR/FB 영향 |
|---|---|---|---|
| A(권장) | 서버 모드 데모 계정 매핑 — 호스트 소유 endpoint(demoSignIn(account))가 시드 계정(M-001 윤하린 · 매니저 배소율 · 강사)에 대응하는 AuthUser 를 만들거나 찾아 FitnessAccount 매핑을 보장하고 JWT 를 발급한다. 서버 모드 앱 · 콘솔의 진입 화면은 localOnly 와 같은 역할 버튼이 이 endpoint 를 부른다. 운영 모드(runMode == production)와 설정 플래그가 없으면 endpoint 가 fail-closed(403). 시험: 생성 SDK 통합에 「역할 버튼 → JWT → me() → 업무 → 타 계정 거부 · 운영 모드 거부」, 서버 모드 widget 시험 1편 |
M(호스트 endpoint · 매핑 보장 · 앱/콘솔 서버 진입 · 시험) · 데모 전용 경로가 운영 빌드로 새는 위험 → 운영 모드 거부를 시험으로 고정 | FR-001(역할 진입)을 서버 모드에서도 같은 UI 로 만족 · FB-4 「역할 전환」 동등성 · 시험 경계 토큰 의존을 인증 경로 시험에서 걷어냄 |
| B | 실제 이메일 IdP 로그인 — 이메일 · 인증 코드 화면 + 첫 로그인 때 매핑 생성(관리자 연결 또는 시드 이메일 매칭) | L · 인증 코드 발송은 §14 상 외부 발송(데모 제외) — 개발 모드 콘솔 출력에 기대야 해 공개 · 데모 재현성이 낮다 · PRD 에 없는 화면 추가 | PRD 밖 화면(FR 추가 필요) |
| C | 현 상태 승인(N/A 화) — 서버 모드 로그인은 PRD 범위 밖으로 승인받고, 서버 검증은 시험 경계 토큰 + realAuth resolver 시험으로 유지 |
0 · DEFERRED 가 「승인된 범위 밖」으로 바뀔 뿐 서버 모드 앱은 손님으로만 뜬다 | FB-4 의 「역할 전환」은 localOnly 에서만 증명 |
4. 요청(2026-10-13 orchestration question)
- 결정: A 를 권장한다(PRD 의 역할 진입과 S-19 호스트 소유 인증을 함께 만족하고, 공개 표면 · 기능 모듈은 그대로).
- 승인되면 담당 작업: W4-09c(새 행 — FB-4 서버 모드 진입, 선행 W4-09b 머지 완료 · 크기 M) — 이번 5차 묶음(W4-07 · W4-08 · FR 대조) 뒤 다음 묶음. FR 대조표에는 FR-001 AC1 서버 모드 시험을 W4-09c 가 더한다(localOnly 시험은 이미 묶임).
- C 를 고르면
docs/fullstack-feature-layout.md§8 의 DEFERRED 를 「범위 밖 — 승인(날짜 · 근거)」으로 바꾼다.
5. 결정과 조건(2026-10-13 코디네이터 — 이 조건이 W4-09c 의 수락 기준이다)
결정: A 승인. B 는 인증 코드 발송이 제외 capability(외부 발송)라 PRD 밖, C 는 FB-4 동등성을 깨므로 쓰지 않는다.
| # | 조건 | W4-09c 에서의 구현 · 시험 |
|---|---|---|
| 1 | demoSignIn 은 명시 데모 플래그(예: passwords.yaml/환경 FITNESS_DEMO_SIGN_IN=true)가 켜졌을 때만 동작, 기본은 꺼짐 — run mode 와 무관하게 플래그 없으면 403 fail-closed. production run mode 는 플래그가 있어도 거부한다 — 근거: 데모 전용 신원 발급 경로가 운영 배포에 실수로 켜지는 것을 설정 하나로 막지 않고 두 겹(플래그 + run mode)으로 막는다. 공개 표면(Pages)은 localOnly 라 production 서버가 이 경로를 쓸 일이 없다 |
생성 SDK 통합: 플래그 없음 → 403 · production + 플래그 → 403 · development/staging + 플래그 → JWT |
| 2 | 시드 데모 계정(PRD 지정 인물 — 회원 윤하린 · 매니저 배소율 · 강사)만 — 임의 계정 · 자유 입력 금지, JWT 는 짧은 TTL, 토큰 · 비밀 값을 로그 · 산출물 · Pages 에 쓰지 않는다(S-16) | endpoint 인자는 계정 열거 값만(시드 밖 → 거부 시험) · TTL 단언 · 자격 증명 스캔 2겹 유지 |
| 3 | 문서 · UI 문구에 「데모 로그인(실제 인증 아님)」 명시 · 이 문서 상태 = 「결정: A — W4-09c」 | 서버 모드 진입 화면 문구(11개 언어) · widget 시험이 문구를 단언 |
| 4 | 서버 모드 앱 · 콘솔 진입은 localOnly 와 같은 역할 버튼, 계약 동등성 시험(FB-4)에 역할 전환 단계 추가 | package/fitness_binding/contract_test 에 역할 전환(회원 → 매니저 → 회원) 단계 · 서버 모드 widget 시험 |
6. 구현(W4-09c — 2026-10-13)
| §5 조건 | 구현 | 시험(단언) |
|---|---|---|
| 1 플래그 · production 두 겹 | FitnessDemoSignInPolicy — FITNESS_DEMO_SIGN_IN 이 정확히 true 이고 run mode ≠ production 일 때만(부팅 판정), endpoint 가 요청 때 서버 인스턴스 run mode 를 다시 본다. 정책은 bindFitnessHost(demoSignIn:) 로 인스턴스마다 묶이고 기본은 꺼짐. 거부는 NotAuthorizedException(insufficientAccess) → 403 |
backend fitness_demo_sign_in_sdk_test.dart — 정책 표(플래그 값 6 × run mode 4) · 플래그 없음 → 403 · production + 플래그 → 403 · 신원 매핑 0 |
| 2 시드 계정만 · 짧은 TTL · 비밀 값 기록 금지 | endpoint fitnessDemoSignIn.signIn(FitnessDemoRole) — 인자는 열거(member · manager · instructor)뿐, 계정 · 역할 · 회원/강사 코드 · scope 는 시드(FitnessDemoSeed.accounts)에서. AuthUser 와 fitness_account 매핑을 보장(계정마다 하나 — 재로그인은 같은 AuthUser)하고 JWT 접근 토큰만 준다(갱신 토큰 없음 — 수명 ≤ 10분, FitnessDemoSignInPolicy.tokenLifetime). 로그는 역할 → 계정만 |
같은 시험 — 갱신 토큰 null · 만료 ≤ 10분 · scope = 시드 · 열거 밖 값(admin · member-yoon · 빈 값) 거부 · 매핑 0. Serverpod 4.0.3 은 열거 역직렬화 실패를 400 이 아니라 500 으로 답한다(endpoint 에 닿기 전 — 토큰 · 매핑 없음, 시험이 그 값을 고정) |
| 3 「데모 로그인(실제 인증 아님)」 표시 | 앱 진입(DemoEntryPage) · 콘솔(ConsoleSignInPanel) 서버 모드 문구 — 11개 언어(demo_sign_in_notice · demo_sign_in_failed) |
app demo_entry_server_mode_test.dart(ko · en · ar 문구) · console console_sign_in_test.dart |
| 4 같은 역할 버튼 · 역할 전환 동등성 | FitnessDemoSignIn(fitness_binding) — 역할 버튼 → 서버 로그인 → ServerpodService.signedIn(인증 세션 관리자) → fitnessAccount.me() 로 세션 행위자 교체. 앱: 「회원 윤하린으로 시작」(서버 로그인 → 시간표) · 「매니저 배소율 — 콘솔 열기」(localOnly 와 같은 키). 콘솔: 로그인 전 패널(매니저 · 강사) → 로그인 뒤 셸 위 역할 전환 줄 |
계약 동등성 4 시나리오 · 72 단계 — 서버 쪽은 시험 경계 토큰 대신 이 데모 로그인(계약 서버 = 실행 서버와 같은 JWT 조립 + 플래그), 새 시나리오 「역할 전환 — 회원 → 매니저 → 회원」(전환마다 행위자 · 앞 역할의 쓰기가 다음 역할에 보임) · fitness_demo_sign_in_test.dart(세션 전환 · 거절 시 그대로) · 서버 모드 widget(앱 4 · 콘솔 3) |
- 공개 Pages 는 그대로 localOnly(
COB_DEMO_ONLY=true) — 서버 모드 진입 화면은 공개 표면이 아니다. - 실행 서버에서 쓰려면
FITNESS_DEMO_SIGN_IN=true와 development/staging run mode(backend/…_server/README.md).
2026-10-14 갱신(cocode#1259) — 진입 · 역할 전환 UI 가 로그인 화면으로 모였다: 역할 버튼 문구는 「윤하린 · 회원」 · 「배소율 · 매니저(콘솔)」, 콘솔의 「로그인 뒤 셸 위 역할 전환 줄」은 없어지고 계정 메뉴 「로그아웃」(
FitnessDemoSignIn.signOut— 클라이언트 토큰만 내림) 뒤 로그인 화면에서 다른 데모 계정을 고른다. 서버 계약(fitnessDemoSignIn· 403 두 겹 · TTL)은 그대로다. 자세한 것은 demo-chrome-login-decision.md.