POP 내역 총 보유 · 예약 · 사용 가능 3구분 · 온보딩 추천인 코드

app/lib/features/auth/onboarding_screens.dart

@@ -165,6 +165,10 @@ class _OnboardingFlowState extends State<OnboardingFlow> {
   /// ② 에서 서버에 기록한 동의 항목. ③ 에서 뒤로 오면 이 상태로 체크해 보여 준다.
   Set<String>? _agreed;
 
+  /// ③ 에서 서버에 귀속한 추천인 코드. ④ 에서 뒤로 와 다시 「다음」이면 또 부르지 않는다
+  /// (서버는 1인 1회라 두 번째 호출을 거절한다).
+  String? _referred;
+
   /// ④ 에서 고른 팬덤 — 고른 순서. 첫 번째가 대표(Primary).
   final _picked = <OnboardingFandom>[];
 
@@ -241,6 +245,8 @@ class _OnboardingFlowState extends State<OnboardingFlow> {
       ),
       _Step.profile => _ProfileStep(
         repository: widget.repository,
+        referred: _referred,
+        onReferred: (code) => _referred = code,
         onBack: _back,
         onDone: () => setState(() => _step = _Step.artist),
       ),
@@ -287,11 +293,17 @@ class _OnboardingFlowState extends State<OnboardingFlow> {
 class _ProfileStep extends StatefulWidget {
   const _ProfileStep({
     required this.repository,
+    required this.referred,
+    required this.onReferred,
     required this.onDone,
     required this.onBack,
   });
 
   final OnboardingRepository repository;
+
+  /// 이미 귀속한 추천인 코드(뒤로 왔을 때 채워 보여 준다).
+  final String? referred;
+  final ValueChanged<String> onReferred;
   final VoidCallback onDone;
   final VoidCallback onBack;
 
@@ -301,7 +313,7 @@ class _ProfileStep extends StatefulWidget {
 
 class _ProfileStepState extends State<_ProfileStep> {
   final _nickname = TextEditingController();
-  final _referral = TextEditingController();
+  late final _referral = TextEditingController(text: widget.referred);
   String? _country = _deviceCountry();
   Locale? _locale;
   String? _nicknameError;
@@ -360,11 +372,20 @@ class _ProfileStepState extends State<_ProfileStep> {
       );
       if (_locale != null) await scope?.select(_locale!);
       final code = _referral.text.trim().toUpperCase();
-      if (code.isNotEmpty) {
+      if (code.isNotEmpty && code != widget.referred) {
         try {
           await widget.repository.attributeReferral(code);
+          widget.onReferred(code);
         } on BackendException catch (e) {
-          if (mounted) setState(() => _referralError = e.message);
+          // 거절 사유(형식 · 없는 코드 · 본인 · 상호 · 이미 등록 · 7일 경과)는 Figma `511:86845`
+          // 문구 하나로 보인다(C-119 「오류 문구 재사용」). 통신 실패만 서버 문구 그대로.
+          if (mounted) {
+            setState(
+              () => _referralError = e.code == 'E-SYS-01'
+                  ? e.message
+                  : l10n.onbReferralInvalid,
+            );
+          }
           return;
         }
       }
@@ -440,6 +461,8 @@ class _ProfileStepState extends State<_ProfileStep> {
           onChanged: (v) => setState(() => _locale = v),
         ),
         const SizedBox(height: AppSpace.s3),
+        // 추천인 코드 입력칸 — Figma 이메일 가입 `333:18620`(입력칸) · `511:86845`(오류) ·
+        // `511:86809`(선택 입력). 10/3 통합회신 7항으로 가입 직후 온보딩에 둔다(C-119).
         TextField(
           controller: _referral,
           textCapitalization: TextCapitalization.characters,
@@ -447,7 +470,6 @@ class _ProfileStepState extends State<_ProfileStep> {
           onChanged: (_) => setState(() => _referralError = null),
           decoration: InputDecoration(
             labelText: l10n.onbReferral,
-            helperText: l10n.onbReferralHint,
             errorText: _referralError,
           ),
         ),