fix: 코드 리뷰 지적사항 8건 수정

[🔴 심각]
- env.py 신설: _get_secret → get_secret 공개 API로 전환
db.py, config.py, teacher_auth.py, teacher_dashboard.py 임포트 일괄 정리
- app.py: 의견 제출 Rate Limiting 추가 (10초 제한)

[🟡 경고]
- validators.py: validate_opinion_content에 allowed_pattern=None 적용
(특수문자·이모지 허용, 길이만 체크)
- validators.py: _validate_text_field 길이 체크를 truncate 이전에 수행
(TOO_LONG 오류가 절대 발생하지 않던 버그 수정)
- utils.py: get_kst_now()를 timezone-aware KST datetime 반환으로 변경
- app.py: DB 저장 전 IP를 SHA-256 해시(16자)로 처리

[🔵 개선]
- tests/ 신설: validators, utils 단위 테스트 24개 (pytest)
- CI에 test job 추가
- teacher_dashboard.py를 hint/summary/records 3개 컴포넌트로 분리
- wordcloud.py: max_words 75→40으로 축소 (O(n²) 성능 개선)
- utils.py: compact_ai_report_output 이중 치환 버그 → 정규식으로 수정

https://claude.ai/code/session_01BRbPoMBBfvgN58bGkNhmv7

.github/workflows/ci.yml

@@ -24,6 +24,7 @@ jobs:
         run: |
           python -m py_compile app.py
           python -m py_compile auth.py
+          python -m py_compile env.py
           python -m py_compile db.py
           python -m py_compile config.py
           python -m py_compile validators.py
@@ -37,4 +38,23 @@ jobs:
           python -m py_compile components/sidebar.py
           python -m py_compile components/chat_board.py
           python -m py_compile components/teacher_dashboard.py
+          python -m py_compile components/teacher_hint.py
+          python -m py_compile components/teacher_summary.py
+          python -m py_compile components/teacher_records.py
           echo "✅ 문법 점검 통과!"
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Python 설정
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: 의존성 설치
+        run: pip install -r requirements.txt pytest
+
+      - name: 단위 테스트
+        run: pytest tests/ -v

app.py

@@ -1,4 +1,6 @@
+import hashlib
 import logging
+import time
 
 import streamlit as st
 
@@ -140,6 +142,10 @@ with col_stt:
     )
 
 if st.button("의견 제출", use_container_width=True, type="primary"):
+    last_submit = st.session_state.get('last_submit_ts', 0)
+    if time.time() - last_submit < 10:
+        st.warning("⏳ 10초 후 다시 제출할 수 있습니다.")
+        st.stop()
     input_ok, safe_input, input_error_code, input_error_message = validate_opinion_content(user_input, max_len=700)
     student_ok, safe_student_name, student_error_code, student_error_message = validate_student_name(student_name, max_len=MAX_STUDENT_NAME_LEN)
     student_number_ok, safe_student_number, _, student_number_error_message = validate_student_name(student_number, max_len=20)
@@ -157,11 +163,13 @@ if st.button("의견 제출", use_container_width=True, type="primary"):
             "content": safe_input, "sentiment": sentiment, "author_role": author_role_for_submit,
         }
         if debate_ip_column_available() and client_ip:
-            insert_payload["ip_address"] = client_ip
+            hashed_ip = hashlib.sha256(client_ip.encode()).hexdigest()[:16]
+            insert_payload["ip_address"] = hashed_ip
         try:
             res = submit_opinion(supabase, insert_payload)
             if res is None:
                 st.stop()
+            st.session_state['last_submit_ts'] = time.time()
             fetch_live_messages.clear()
             log_audit(
                 "opinion_submitted",

components/teacher_auth.py

@@ -6,8 +6,8 @@ from db import (
     request_teacher_account,
     upgrade_teacher_password,
     using_service_role_key,
-    _get_secret,
 )
+from env import get_secret
 from validators import validate_teacher_credential
 from utils import to_bool_flag
 
@@ -53,7 +53,7 @@ def _handle_login(supabase, teacher_id_input, teacher_pw_input):
                 "등록된 계정도 미등록으로 보일 수 있습니다."
             )
         try:
-            supabase_url = str(_get_secret("SUPABASE_URL", ""))
+            supabase_url = str(get_secret("SUPABASE_URL", ""))
             project_ref = supabase_url.split("//", 1)[-1].split(".", 1)[0] if supabase_url else ""
             if project_ref:
                 st.caption(f"현재 앱 연결 DB 프로젝트: `{project_ref}`")

components/teacher_dashboard.py

@@ -1,31 +1,15 @@
-import html
-import io
 import logging
 
-import pandas as pd
 import plotly.express as px
 import streamlit as st
 
-from db import (
-    create_teacher_hint,
-    delete_student_record,
-    destroy_room_data,
-    fetch_live_messages,
-    fetch_student_records,
-    save_student_record,
-    _get_secret,
-)
-from services.ai import generate_ai_response, build_hint_prompt, build_summary_prompt, build_record_prompt
+from db import destroy_room_data, fetch_live_messages
 from validators import with_fallback_author_role
-from utils import compact_ai_report_output, get_kst_now, get_kst_now_str, log_audit
-from config import (
-    AI_MODEL_NAME,
-    AI_HINT_ENABLED,
-    DASHBOARD_FETCH_LIMIT,
-    RECORDS_FETCH_LIMIT,
-    ROOM_DESTROY_ENABLED,
-    UI_FONT_FAMILY,
-)
+from utils import log_audit
+from config import DASHBOARD_FETCH_LIMIT, ROOM_DESTROY_ENABLED, UI_FONT_FAMILY
+from components.teacher_hint import render_hint_section
+from components.teacher_summary import render_summary_section
+from components.teacher_records import render_records_section
 
 logger = logging.getLogger("talk_trace_ai")
 
@@ -64,173 +48,11 @@ def render_teacher_dashboard(supabase, room_name, user_role, student_name, curre
         st.info(f"{act_type} 데이터가 없습니다.")
 
     st.divider()
-
-    @st.fragment
-    def teacher_hint_section():
-        st.subheader(f"💡 AI {act_type} 촉진 (Teacher-in-the-loop)")
-        st.info("AI 제안을 수정 후 전송하세요.")
-
-        def send_hint():
-            val = st.session_state.get('hint_input_widget', '').strip()
-            if val:
-                now = get_kst_now_str()
-                try:
-                    res = create_teacher_hint(supabase, {
-                        "room_name": room_name, "timestamp": now,
-                        "student_name": "👨‍🏫 선생님 (AI 보조)",
-                        "content": val, "sentiment": "❓ 질문", "author_role": "교사"
-                    })
-                    if res is None:
-                        return
-                    fetch_live_messages.clear()
-                    log_audit("teacher_hint_sent", room_name=room_name, actor_name=student_name, role=user_role)
-                    st.session_state['hint_input_widget'] = ""
-                except Exception as e:
-                    st.error(f"힌트 전송 실패: {e}")
-
-        if AI_HINT_ENABLED:
-            if st.button("🪄 AI 힌트 초안 생성", use_container_width=True):
-                st.toast("👀 AI가 대화 맥락을 읽고 있습니다...", icon="⏳")
-                with st.spinner("✍️ 예리한 질문을 작성하고 있습니다..."):
-                    context = "\n".join(df_all['content'].tail(5).tolist()) if not df_all.empty else "대화 없음"
-                    prompt = build_hint_prompt(act_type, current_topic, context)
-                    res_text = generate_ai_response(
-                        prompt, model_name=AI_MODEL_NAME, api_key=_get_secret("GEMINI_API_KEY", ""),
-                        log_message="AI 힌트 생성 실패", room_name=room_name,
-                    )
-                    if res_text:
-                        st.session_state['hint_input_widget'] = res_text.strip().split('\n')[0]
-                        st.session_state['ai_hint_manual_mode'] = False
-                        st.toast("✅ 힌트 작성 완료!", icon="🎉")
-                    else:
-                        st.session_state['ai_hint_manual_mode'] = True
-                        st.toast("🚨 AI 호출 오류: 수동 모드로 전환되었습니다.", icon="❌")
-        else:
-            st.session_state['ai_hint_manual_mode'] = True
-
-        col_edit_txt, col_edit_btn = st.columns([8, 2])
-        with col_edit_txt:
-            st.text_input("선생님의 검토 및 수정", key="hint_input_widget", label_visibility="collapsed", placeholder="여기에 AI 힌트가 나타납니다.")
-        with col_edit_btn:
-            st.button("🚀 학생 화면 전송", use_container_width=True, type="primary", on_click=send_hint)
-
-    teacher_hint_section()
+    render_hint_section(supabase, room_name, user_role, student_name, current_topic, act_type, df_all)
     st.divider()
-
-    @st.fragment
-    def teacher_summary_section():
-        st.subheader(f"📝 수업 종료 및 전체 {act_type} 요약 리포트")
-        if st.button(f"{act_type} 요약 및 베스트 발언 추출 🪄", use_container_width=True):
-            st.toast("👀 AI가 전체 기록을 꼼꼼히 읽고 있습니다...", icon="⏳")
-            with st.spinner("✍️ 요약 리포트를 작성하고 있습니다..."):
-                if not df_all.empty:
-                    full_history = "\n".join([
-                        f"[{row['student_name']} - {row['sentiment']}] {row['content']}"
-                        for _, row in df_all.iterrows()
-                    ])
-                    prompt = build_summary_prompt(act_type, current_topic, full_history)
-                    res_text = generate_ai_response(
-                        prompt, model_name=AI_MODEL_NAME, api_key=_get_secret("GEMINI_API_KEY", ""),
-                        log_message="AI 요약 리포트 생성 실패", room_name=room_name,
-                    )
-                    if res_text:
-                        st.session_state['ai_report_text'] = compact_ai_report_output(res_text)
-                        st.toast("✅ 리포트 작성 완료!", icon="🎉")
-                    else:
-                        st.toast("🚨 AI 호출 오류가 발생했습니다.", icon="❌")
-                else:
-                    st.toast("🚨 분석할 데이터가 없습니다.", icon="⚠️")
-        if st.session_state.get('ai_report_text'):
-            st.info(f"📊 **AI 수업 {act_type} 요약 리포트**")
-            report_html = html.escape(st.session_state['ai_report_text']).replace("\n", "<br>")
-            st.markdown(f"<div style='line-height:1.8;'>{report_html}</div>", unsafe_allow_html=True)
-
-    teacher_summary_section()
+    render_summary_section(room_name, act_type, current_topic, df_all)
     st.divider()
-
-    @st.fragment
-    def teacher_record_section():
-        def delete_selected_record():
-            del_id = st.session_state.get('del_record_dropdown')
-            if del_id:
-                try:
-                    if delete_student_record(supabase, del_id) is None:
-                        return
-                    log_audit("record_deleted", room_name=room_name, actor_name=student_name, role=user_role, record_id=del_id)
-                    st.toast("기록이 삭제되었습니다.", icon="🗑️")
-                except Exception as e:
-                    st.error(f"기록 삭제 실패: {e}")
-
-        col3, col4 = st.columns([1, 1])
-        with col3:
-            st.subheader("📥 활동 데이터 다운로드")
-            if not df_all.empty:
-                buffer = io.BytesIO()
-                with pd.ExcelWriter(buffer, engine='openpyxl') as writer:
-                    df_all.to_excel(writer, index=False)
-                st.download_button(
-                    f"{act_type} 전체 활동 로그 (Excel)",
-                    data=buffer.getvalue(),
-                    file_name=f"{room_name}_log_{get_kst_now().strftime('%Y%m%d_%H%M')}.xlsx",
-                )
-
-        with col4:
-            st.subheader("🤖 개인별 AI 세특 초안 생성")
-            student_list = student_only_df['student_name'].unique() if not student_only_df.empty else []
-            if len(student_list) > 0:
-                selected_student = st.selectbox("학생을 선택하세요", student_list)
-                if st.button(f"'{selected_student}' 세특 생성 🪄", use_container_width=True):
-                    st.toast(f"👀 AI가 '{selected_student}' 학생의 활동을 분석합니다...", icon="⏳")
-                    with st.spinner(f"✍️ '{selected_student}' 학생의 세특 초안 작성 중..."):
-                        try:
-                            student_data = df_all[df_all['student_name'] == selected_student]
-                            debate_history = "\n".join([f"- [{row['sentiment']}] {row['content']}" for _, row in student_data.iterrows()])
-                            prompt = build_record_prompt(act_type, current_topic, selected_student, debate_history)
-                            res_text = generate_ai_response(
-                                prompt, model_name=AI_MODEL_NAME, api_key=_get_secret("GEMINI_API_KEY", ""),
-                                log_message="AI 세특 생성 실패", room_name=room_name, student=selected_student,
-                            )
-                            if res_text:
-                                st.session_state['ai_result_text'] = res_text
-                                now = get_kst_now_str()
-                                save_res = save_student_record(supabase, {
-                                    "room_name": room_name, "timestamp": now,
-                                    "student_name": selected_student, "content": res_text,
-                                })
-                                if save_res is None:
-                                    raise RuntimeError("보관함 저장 실패")
-                                st.toast("✅ 세특 생성 및 보관함 저장 완료!", icon="🎉")
-                            else:
-                                raise RuntimeError("AI 응답 비어있음")
-                        except Exception:
-                            logger.exception("세특 생성 후처리 실패")
-                            st.toast("🚨 오류가 발생했습니다. 다시 시도해주세요.", icon="❌")
-                if st.session_state.get('ai_result_text'):
-                    st.success("🤖 **개인별 세특 초안** (보관함에 자동 저장되었습니다)")
-                    st.text_area("내용 수정 후 복사하여 사용하세요", value=st.session_state['ai_result_text'], height=200, label_visibility="collapsed")
-            else:
-                st.info("실명 참여 학생이 없습니다.")
-
-        st.divider()
-        st.subheader("📂 저장된 세특 기록 보관함")
-        records_df = fetch_student_records(supabase, room_name, RECORDS_FETCH_LIMIT)
-        if not records_df.empty:
-            records_display_df = records_df.rename(columns={"id": "No.", "content": "세특 내용"})
-            records_html = records_display_df.to_html(index=False, escape=True)
-            st.markdown(f"<div class='records-db-table-wrap'>{records_html}</div>", unsafe_allow_html=True)
-            col_down, col_del = st.columns([1, 1])
-            with col_down:
-                buffer_records = io.BytesIO()
-                with pd.ExcelWriter(buffer_records, engine='openpyxl') as writer:
-                    records_df.drop(columns=['id']).to_excel(writer, index=False)
-                st.download_button("📥 세특 보관함 다운로드 (Excel)", data=buffer_records.getvalue(), file_name=f"{room_name}_세특보관함.xlsx")
-            with col_del:
-                st.selectbox("🗑️ 삭제할 '고유 번호(No.)' 선택", records_df['id'].tolist(), key="del_record_dropdown")
-                st.button("선택한 세특 기록 영구 삭제", type="primary", on_click=delete_selected_record)
-        else:
-            st.info("저장된 기록이 없습니다.")
-
-    teacher_record_section()
+    render_records_section(supabase, room_name, user_role, student_name, act_type, current_topic, df_all, student_only_df)
 
     st.divider()
     st.subheader("🚨 위험 구역 (방 폭파)")

components/teacher_hint.py

@@ -0,0 +1,57 @@
+import streamlit as st
+
+from db import create_teacher_hint, fetch_live_messages
+from env import get_secret
+from services.ai import generate_ai_response, build_hint_prompt
+from utils import get_kst_now_str, log_audit
+from config import AI_MODEL_NAME, AI_HINT_ENABLED
+
+
+@st.fragment
+def render_hint_section(supabase, room_name, user_role, student_name, current_topic, act_type, df_all):
+    st.subheader(f"💡 AI {act_type} 촉진 (Teacher-in-the-loop)")
+    st.info("AI 제안을 수정 후 전송하세요.")
+
+    def send_hint():
+        val = st.session_state.get('hint_input_widget', '').strip()
+        if val:
+            now = get_kst_now_str()
+            try:
+                res = create_teacher_hint(supabase, {
+                    "room_name": room_name, "timestamp": now,
+                    "student_name": "👨‍🏫 선생님 (AI 보조)",
+                    "content": val, "sentiment": "❓ 질문", "author_role": "교사"
+                })
+                if res is None:
+                    return
+                fetch_live_messages.clear()
+                log_audit("teacher_hint_sent", room_name=room_name, actor_name=student_name, role=user_role)
+                st.session_state['hint_input_widget'] = ""
+            except Exception as e:
+                st.error(f"힌트 전송 실패: {e}")
+
+    if AI_HINT_ENABLED:
+        if st.button("🪄 AI 힌트 초안 생성", use_container_width=True):
+            st.toast("👀 AI가 대화 맥락을 읽고 있습니다...", icon="⏳")
+            with st.spinner("✍️ 예리한 질문을 작성하고 있습니다..."):
+                context = "\n".join(df_all['content'].tail(5).tolist()) if not df_all.empty else "대화 없음"
+                prompt = build_hint_prompt(act_type, current_topic, context)
+                res_text = generate_ai_response(
+                    prompt, model_name=AI_MODEL_NAME, api_key=get_secret("GEMINI_API_KEY", ""),
+                    log_message="AI 힌트 생성 실패", room_name=room_name,
+                )
+                if res_text:
+                    st.session_state['hint_input_widget'] = res_text.strip().split('\n')[0]
+                    st.session_state['ai_hint_manual_mode'] = False
+                    st.toast("✅ 힌트 작성 완료!", icon="🎉")
+                else:
+                    st.session_state['ai_hint_manual_mode'] = True
+                    st.toast("🚨 AI 호출 오류: 수동 모드로 전환되었습니다.", icon="❌")
+    else:
+        st.session_state['ai_hint_manual_mode'] = True
+
+    col_edit_txt, col_edit_btn = st.columns([8, 2])
+    with col_edit_txt:
+        st.text_input("선생님의 검토 및 수정", key="hint_input_widget", label_visibility="collapsed", placeholder="여기에 AI 힌트가 나타납니다.")
+    with col_edit_btn:
+        st.button("🚀 학생 화면 전송", use_container_width=True, type="primary", on_click=send_hint)

components/teacher_records.py

@@ -0,0 +1,96 @@
+import io
+import logging
+
+import pandas as pd
+import streamlit as st
+
+from db import delete_student_record, fetch_student_records, save_student_record
+from env import get_secret
+from services.ai import generate_ai_response, build_record_prompt
+from utils import get_kst_now, get_kst_now_str, log_audit
+from config import AI_MODEL_NAME, RECORDS_FETCH_LIMIT
+
+logger = logging.getLogger("talk_trace_ai")
+
+
+@st.fragment
+def render_records_section(supabase, room_name, user_role, student_name, act_type, current_topic, df_all, student_only_df):
+    def delete_selected_record():
+        del_id = st.session_state.get('del_record_dropdown')
+        if del_id:
+            try:
+                if delete_student_record(supabase, del_id) is None:
+                    return
+                log_audit("record_deleted", room_name=room_name, actor_name=student_name, role=user_role, record_id=del_id)
+                st.toast("기록이 삭제되었습니다.", icon="🗑️")
+            except Exception as e:
+                st.error(f"기록 삭제 실패: {e}")
+
+    col3, col4 = st.columns([1, 1])
+    with col3:
+        st.subheader("📥 활동 데이터 다운로드")
+        if not df_all.empty:
+            buffer = io.BytesIO()
+            with pd.ExcelWriter(buffer, engine='openpyxl') as writer:
+                df_all.to_excel(writer, index=False)
+            st.download_button(
+                f"{act_type} 전체 활동 로그 (Excel)",
+                data=buffer.getvalue(),
+                file_name=f"{room_name}_log_{get_kst_now().strftime('%Y%m%d_%H%M')}.xlsx",
+            )
+
+    with col4:
+        st.subheader("🤖 개인별 AI 세특 초안 생성")
+        student_list = student_only_df['student_name'].unique() if not student_only_df.empty else []
+        if len(student_list) > 0:
+            selected_student = st.selectbox("학생을 선택하세요", student_list)
+            if st.button(f"'{selected_student}' 세특 생성 🪄", use_container_width=True):
+                st.toast(f"👀 AI가 '{selected_student}' 학생의 활동을 분석합니다...", icon="⏳")
+                with st.spinner(f"✍️ '{selected_student}' 학생의 세특 초안 작성 중..."):
+                    try:
+                        student_data = df_all[df_all['student_name'] == selected_student]
+                        debate_history = "\n".join([f"- [{row['sentiment']}] {row['content']}" for _, row in student_data.iterrows()])
+                        prompt = build_record_prompt(act_type, current_topic, selected_student, debate_history)
+                        res_text = generate_ai_response(
+                            prompt, model_name=AI_MODEL_NAME, api_key=get_secret("GEMINI_API_KEY", ""),
+                            log_message="AI 세특 생성 실패", room_name=room_name, student=selected_student,
+                        )
+                        if res_text:
+                            st.session_state['ai_result_text'] = res_text
+                            now = get_kst_now_str()
+                            save_res = save_student_record(supabase, {
+                                "room_name": room_name, "timestamp": now,
+                                "student_name": selected_student, "content": res_text,
+                            })
+                            if save_res is None:
+                                raise RuntimeError("보관함 저장 실패")
+                            st.toast("✅ 세특 생성 및 보관함 저장 완료!", icon="🎉")
+                        else:
+                            raise RuntimeError("AI 응답 비어있음")
+                    except Exception:
+                        logger.exception("세특 생성 후처리 실패")
+                        st.toast("🚨 오류가 발생했습니다. 다시 시도해주세요.", icon="❌")
+            if st.session_state.get('ai_result_text'):
+                st.success("🤖 **개인별 세특 초안** (보관함에 자동 저장되었습니다)")
+                st.text_area("내용 수정 후 복사하여 사용하세요", value=st.session_state['ai_result_text'], height=200, label_visibility="collapsed")
+        else:
+            st.info("실명 참여 학생이 없습니다.")
+
+    st.divider()
+    st.subheader("📂 저장된 세특 기록 보관함")
+    records_df = fetch_student_records(supabase, room_name, RECORDS_FETCH_LIMIT)
+    if not records_df.empty:
+        records_display_df = records_df.rename(columns={"id": "No.", "content": "세특 내용"})
+        records_html = records_display_df.to_html(index=False, escape=True)
+        st.markdown(f"<div class='records-db-table-wrap'>{records_html}</div>", unsafe_allow_html=True)
+        col_down, col_del = st.columns([1, 1])
+        with col_down:
+            buffer_records = io.BytesIO()
+            with pd.ExcelWriter(buffer_records, engine='openpyxl') as writer:
+                records_df.drop(columns=['id']).to_excel(writer, index=False)
+            st.download_button("��� 세특 보관함 다운로드 (Excel)", data=buffer_records.getvalue(), file_name=f"{room_name}_세특보관함.xlsx")
+        with col_del:
+            st.selectbox("🗑️ 삭제할 '고유 번호(No.)' 선택", records_df['id'].tolist(), key="del_record_dropdown")
+            st.button("선택한 세특 기록 영구 삭제", type="primary", on_click=delete_selected_record)
+    else:
+        st.info("저장된 기록이 없습니다.")

components/teacher_summary.py

@@ -0,0 +1,37 @@
+import html
+
+import streamlit as st
+
+from env import get_secret
+from services.ai import generate_ai_response, build_summary_prompt
+from utils import compact_ai_report_output
+from config import AI_MODEL_NAME
+
+
+@st.fragment
+def render_summary_section(room_name, act_type, current_topic, df_all):
+    st.subheader(f"📝 수업 종료 및 전체 {act_type} 요약 리포트")
+    if st.button(f"{act_type} 요약 및 베스트 발언 추출 🪄", use_container_width=True):
+        st.toast("👀 AI가 전체 기록을 꼼꼼히 읽고 있습니다...", icon="⏳")
+        with st.spinner("✍️ 요약 리포트를 작성하고 있습니다..."):
+            if not df_all.empty:
+                full_history = "\n".join([
+                    f"[{row['student_name']} - {row['sentiment']}] {row['content']}"
+                    for _, row in df_all.iterrows()
+                ])
+                prompt = build_summary_prompt(act_type, current_topic, full_history)
+                res_text = generate_ai_response(
+                    prompt, model_name=AI_MODEL_NAME, api_key=get_secret("GEMINI_API_KEY", ""),
+                    log_message="AI 요약 리포트 생성 실패", room_name=room_name,
+                )
+                if res_text:
+                    st.session_state['ai_report_text'] = compact_ai_report_output(res_text)
+                    st.toast("✅ 리포트 작성 완료!", icon="🎉")
+                else:
+                    st.toast("🚨 AI 호출 오류가 발생했습니다.", icon="❌")
+            else:
+                st.toast("🚨 분석할 데이터가 없습니다.", icon="⚠️")
+    if st.session_state.get('ai_report_text'):
+        st.info(f"📊 **AI 수업 {act_type} 요약 리포트**")
+        report_html = html.escape(st.session_state['ai_report_text']).replace("\n", "<br>")
+        st.markdown(f"<div style='line-height:1.8;'>{report_html}</div>", unsafe_allow_html=True)

config.py

@@ -1,13 +1,13 @@
-from db import _get_secret
+from env import get_secret
 
 AI_MODEL_NAME = "gemini-2.5-flash"
 LIVE_BOARD_FETCH_LIMIT = 300
 DASHBOARD_FETCH_LIMIT = 2000
 RECORDS_FETCH_LIMIT = 500
 LIVE_REFRESH_INTERVAL = "5s"
-AI_HINT_ENABLED = str(_get_secret("AI_HINT_ENABLED", "true")).lower() not in ("false", "0", "no")
-ROOM_DESTROY_ENABLED = str(_get_secret("ROOM_DESTROY_ENABLED", "true")).lower() not in ("false", "0", "no")
-AUTO_JOIN_ON_REFRESH = str(_get_secret("AUTO_JOIN_ON_REFRESH", "false")).lower() not in ("false", "0", "no")
+AI_HINT_ENABLED = str(get_secret("AI_HINT_ENABLED", "true")).lower() not in ("false", "0", "no")
+ROOM_DESTROY_ENABLED = str(get_secret("ROOM_DESTROY_ENABLED", "true")).lower() not in ("false", "0", "no")
+AUTO_JOIN_ON_REFRESH = str(get_secret("AUTO_JOIN_ON_REFRESH", "false")).lower() not in ("false", "0", "no")
 MAX_ROOM_NAME_LEN = 60
 MAX_STUDENT_NAME_LEN = 30
 MAX_TOPIC_LEN = 120

db.py

@@ -1,11 +1,11 @@
 import logging
-import os
 
 import pandas as pd
 import streamlit as st
 from supabase import Client, create_client
 
 from auth import _hash_password, _is_hashed, _verify_password  # noqa: F401
+from env import get_secret
 
 logger = logging.getLogger("talk_trace_ai")
 
@@ -19,42 +19,22 @@ def upgrade_teacher_password(supabase: Client, account_id: int, plain: str):
     )
 
 
-# ==========================================
-# [0] 환경변수 → st.secrets 통합 읽기 헬퍼
-# ==========================================
-
-def _get_secret(key: str, default: str = "") -> str:
-    """
-    환경변수(HF Spaces) → st.secrets(Streamlit Cloud) 순서로 값을 읽습니다.
-    두 플랫폼 모두 코드 수정 없이 동작합니다.
-    """
-    # 1순위: 환경변수 (Hugging Face Spaces)
-    env_val = os.environ.get(key, "").strip()
-    if env_val:
-        return env_val
-    # 2순위: st.secrets (Streamlit Cloud)
-    try:
-        return str(st.secrets.get(key, default)).strip()
-    except Exception:
-        return default
-
-
 # ==========================================
 # [1] DB 초기화 및 인증
 # ==========================================
 
 @st.cache_resource
 def init_db() -> Client:
-    supabase_url = _get_secret("SUPABASE_URL")
+    supabase_url = get_secret("SUPABASE_URL")
     supabase_key = (
-        _get_secret("SUPABASE_SERVICE_ROLE_KEY")
-        or _get_secret("SUPABASE_KEY")
+        get_secret("SUPABASE_SERVICE_ROLE_KEY")
+        or get_secret("SUPABASE_KEY")
     )
     return create_client(supabase_url, supabase_key)
 
 
 def using_service_role_key() -> bool:
-    return bool(_get_secret("SUPABASE_SERVICE_ROLE_KEY"))
+    return bool(get_secret("SUPABASE_SERVICE_ROLE_KEY"))
 
 
 def ensure_db_login(supabase: Client) -> bool:
@@ -71,8 +51,8 @@ def ensure_db_login(supabase: Client) -> bool:
     try:
         supabase.auth.sign_in_with_password(
             {
-                "email": _get_secret("SUPABASE_APP_EMAIL"),
-                "password": _get_secret("SUPABASE_APP_PASSWORD"),
+                "email": get_secret("SUPABASE_APP_EMAIL"),
+                "password": get_secret("SUPABASE_APP_PASSWORD"),
             }
         )
         return True

env.py

@@ -0,0 +1,14 @@
+import os
+
+import streamlit as st
+
+
+def get_secret(key: str, default: str = "") -> str:
+    """환경변수(HF Spaces) → st.secrets(Streamlit Cloud) 순서로 값을 읽습니다."""
+    env_val = os.environ.get(key, "").strip()
+    if env_val:
+        return env_val
+    try:
+        return str(st.secrets.get(key, default)).strip()
+    except Exception:
+        return default

tests/test_utils.py

@@ -0,0 +1,27 @@
+from datetime import timezone
+from utils import get_kst_now, compact_ai_report_output
+
+
+def test_get_kst_now_is_aware():
+    dt = get_kst_now()
+    assert dt.tzinfo is not None
+    assert dt.utcoffset().seconds == 9 * 3600
+
+
+def test_compact_ai_report_output_empty():
+    assert compact_ai_report_output("") == ""
+    assert compact_ai_report_output(None) == ""
+
+
+def test_compact_ai_report_output_no_double_newline():
+    text = "핵심요약 1: A 핵심요약 2: B 핵심요약 3: C 베스트 학생: D 선정 이유: E"
+    result = compact_ai_report_output(text)
+    assert "\n\n" not in result
+    lines = result.splitlines()
+    assert len(lines) <= 5
+
+
+def test_compact_ai_report_output_strips_headers():
+    text = "# 제목\n핵심요약 1: 내용\n핵심요약 2: 내용2"
+    result = compact_ai_report_output(text)
+    assert "# 제목" not in result

tests/test_validators.py

@@ -0,0 +1,134 @@
+import pytest
+from validators import (
+    ValidationError,
+    validate_opinion_content,
+    validate_room_name,
+    validate_student_name,
+    validate_entry_code,
+    validate_teacher_credential,
+    normalize_user_text,
+    normalize_room_name,
+    mask_ip_for_teacher,
+)
+
+
+# ── validate_opinion_content ──────────────────────────────────────
+
+def test_opinion_empty():
+    ok, _, code, _ = validate_opinion_content("")
+    assert not ok
+    assert code == ValidationError.EMPTY
+
+
+def test_opinion_valid():
+    ok, safe, _, _ = validate_opinion_content("인공지능은 교육에 도움이 됩니다.")
+    assert ok
+    assert safe == "인공지능은 교육에 도움이 됩니다."
+
+
+def test_opinion_special_chars_allowed():
+    ok, _, _, _ = validate_opinion_content("좋아요! 이 의견 → 매우 중요합니다… 🎉")
+    assert ok
+
+
+def test_opinion_too_long():
+    ok, _, code, _ = validate_opinion_content("a" * 701)
+    assert not ok
+    assert code == ValidationError.TOO_LONG
+
+
+# ── validate_room_name ────────────────────────────────────────────
+
+def test_room_name_valid():
+    ok, safe, _, _ = validate_room_name("1학년 3반")
+    assert ok
+    assert safe == "1학년 3반"
+
+
+def test_room_name_empty():
+    ok, _, code, _ = validate_room_name("")
+    assert not ok
+    assert code == ValidationError.EMPTY
+
+
+def test_room_name_forbidden():
+    ok, _, code, _ = validate_room_name("관리자방")
+    assert not ok
+    assert code == ValidationError.FORBIDDEN
+
+
+def test_room_name_collapse_spaces():
+    ok, safe, _, _ = validate_room_name("1학년   3반")
+    assert ok
+    assert safe == "1학년 3반"
+
+
+# ── validate_student_name ─────────────────────────────────────────
+
+def test_student_name_valid():
+    ok, safe, _, _ = validate_student_name("홍길동")
+    assert ok
+    assert safe == "홍길동"
+
+
+def test_student_name_forbidden_admin():
+    ok, _, code, _ = validate_student_name("admin")
+    assert not ok
+    assert code == ValidationError.FORBIDDEN
+
+
+# ── validate_entry_code ───────────────────────────────────────────
+
+def test_entry_code_empty_allowed():
+    ok, safe, _, _ = validate_entry_code("")
+    assert ok
+    assert safe == ""
+
+
+def test_entry_code_valid():
+    ok, safe, _, _ = validate_entry_code("secret123!")
+    assert ok
+    assert safe == "secret123!"
+
+
+# ── validate_teacher_credential ───────────────────────────────────
+
+def test_credential_valid():
+    ok, safe, _, _ = validate_teacher_credential("teacher01", field_name="교사 ID")
+    assert ok
+    assert safe == "teacher01"
+
+
+def test_credential_empty():
+    ok, _, code, _ = validate_teacher_credential("", field_name="교사 ID")
+    assert not ok
+    assert code == ValidationError.EMPTY
+
+
+# ── normalize helpers ─────────────────────────────────────────────
+
+def test_normalize_user_text_strips():
+    assert normalize_user_text("  hello  ") == "hello"
+
+
+def test_normalize_user_text_truncates():
+    assert normalize_user_text("abc", max_len=2) == "ab"
+
+
+def test_normalize_room_name_collapses_whitespace():
+    assert normalize_room_name("a   b") == "a b"
+
+
+# ── mask_ip_for_teacher ───────────────────────────────────────────
+
+def test_mask_ipv4():
+    assert mask_ip_for_teacher("1.2.3.4") == "1.XXX.XXX.4"
+
+
+def test_mask_ipv6():
+    result = mask_ip_for_teacher("2001:db8:85a3:0:0:8a2e:370:7334")
+    assert "XXXX" in result
+
+
+def test_mask_empty():
+    assert mask_ip_for_teacher("") == ""

utils.py

@@ -1,4 +1,5 @@
 import logging
+import re
 from datetime import datetime, timedelta, timezone
 
 import streamlit as st
@@ -7,10 +8,11 @@ logger = logging.getLogger("talk_trace_ai")
 
 DATETIME_FMT = "%Y-%m-%d %H:%M:%S"
 DISPLAY_DATETIME_FMT = "%Y-%m-%d %p %I:%M:%S"
+KST = timezone(timedelta(hours=9))
 
 
 def get_kst_now():
-    return datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(hours=9)
+    return datetime.now(tz=KST)
 
 
 def get_kst_now_str():
@@ -84,11 +86,7 @@ def compact_ai_report_output(text):
     cleaned = [line for line in raw_lines if line and not line.startswith("#")]
     if not cleaned:
         return ""
-    report_labels = ("핵심요약 1:", "핵심요약 2:", "핵심요약 3:", "베스트 학생:", "선정 이유:")
     normalized_text = " ".join(cleaned)
-    if report_labels[0] in normalized_text:
-        for label in report_labels[1:]:
-            normalized_text = normalized_text.replace(f" {label}", f"\n{label}")
-            normalized_text = normalized_text.replace(label, f"\n{label}")
+    normalized_text = re.sub(r"\s*(핵심요약 [123]:|베스트 학생:|선정 이유:)", r"\n\1", normalized_text)
     normalized_lines = [line.strip() for line in normalized_text.splitlines() if line.strip()]
     return "\n".join(normalized_lines[:5])

validators.py

@@ -142,9 +142,9 @@ def _validate_text_field(
     -------
     (ok: bool, safe_text: str, error_code: str | None, error_message: str | None)
     """
-    normalized = normalize_user_text(raw_text, max_len=max_len)
+    stripped = (raw_text or "").strip()
 
-    if not normalized:
+    if not stripped:
         if allow_empty:
             return True, "", None, None
         return (
@@ -153,7 +153,7 @@ def _validate_text_field(
             VALIDATION_MESSAGES[ValidationError.EMPTY].format(field=field_name),
         )
 
-    if len(normalized) > max_len:
+    if len(stripped) > max_len:
         return (
             False, "",
             ValidationError.TOO_LONG,
@@ -162,6 +162,8 @@ def _validate_text_field(
             ),
         )
 
+    normalized = stripped
+
     if allowed_pattern and not allowed_pattern.match(normalized):
         return (
             False, "",
@@ -217,13 +219,14 @@ def validate_opinion_content(raw_text, max_len=700):
     """
     의견 내용 검증.
     - 최대 700자
-    - 허용 문자 패턴 적용
+    - 길이만 체크 (특수문자·이모지 허용)
     """
     return _validate_text_field(
         raw_text,
         field_name="의견 내용",
         max_len=max_len,
         allow_empty=False,
+        allowed_pattern=None,
     )
 
 

wordcloud.py

@@ -39,7 +39,7 @@ def build_word_frequencies(text_series):
     return Counter(tokens)
 
 
-def build_circular_wordcloud_html(frequencies, max_words=75, width=760, height=520):
+def build_circular_wordcloud_html(frequencies, max_words=40, width=760, height=520):
     if not frequencies:
         return ""
     sorted_words = sorted(frequencies.items(), key=lambda item: (-item[1], item[0]))[:max_words]