From cb55967ca647464f5c679bddeaeba79447d48d80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Sat, 28 Feb 2026 16:23:58 +0900
Subject: [PATCH 1/2] fix(app): add loading states, ARIA accessibility, and
 error handling

- Add loading state with disabled buttons and dynamic text during async ops
- Wrap ask() and runAction() in try-catch for network error resilience
- Add ARIA attributes: aria-live, aria-busy, aria-disabled, aria-labelledby
- Switch labels to htmlFor/id pattern for proper form accessibility
- Add input validation for upload (empty text check)
- Add hover, focus-visible, active, and disabled styles for buttons/inputs
- Add .message class for visual feedback on status messages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 app/app/globals.css |  36 ++++++++++
 app/app/page.tsx    | 161 +++++++++++++++++++++++++++-----------------
 2 files changed, 136 insertions(+), 61 deletions(-)

diff --git a/app/app/globals.css b/app/app/globals.css
index 1b662ef..59ef8fa 100644
--- a/app/app/globals.css
+++ b/app/app/globals.css
@@ -47,6 +47,15 @@ select {
   border: 1px solid #b9c6db;
   border-radius: 8px;
   padding: 0.65rem;
+  transition: border-color 0.15s, outline-color 0.15s;
+}
+
+input:focus,
+textarea:focus,
+select:focus {
+  border-color: #3b82f6;
+  outline: 2px solid #3b82f6;
+  outline-offset: -1px;
 }
 
 button {
@@ -56,6 +65,25 @@ button {
   border-radius: 8px;
   padding: 0.65rem 1rem;
   cursor: pointer;
+  transition: background 0.15s;
+}
+
+button:hover {
+  background: #1e40af;
+}
+
+button:active {
+  background: #1e3a8a;
+}
+
+button:focus-visible {
+  outline: 2px solid #3b82f6;
+  outline-offset: 2px;
+}
+
+button:disabled {
+  background: #93c5fd;
+  cursor: not-allowed;
 }
 
 pre {
@@ -65,3 +93,11 @@ pre {
   padding: 0.75rem;
   border-radius: 10px;
 }
+
+.message {
+  background: #eff6ff;
+  border: 1px solid #bfdbfe;
+  border-radius: 8px;
+  padding: 0.75rem 1rem;
+  margin-top: 1rem;
+}
diff --git a/app/app/page.tsx b/app/app/page.tsx
index 36cd5af..1c1e5b2 100644
--- a/app/app/page.tsx
+++ b/app/app/page.tsx
@@ -45,6 +45,7 @@ export default function HomePage() {
   const [queryResult, setQueryResult] = useState<QueryResponse | null>(null);
   const [actionResult, setActionResult] = useState<string>("");
   const [message, setMessage] = useState("");
+  const [loading, setLoading] = useState(false);
 
   useEffect(() => {
     void refreshAll();
@@ -67,7 +68,12 @@ export default function HomePage() {
 
   async function upload(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
+    if (!sourceText.trim()) {
+      setMessage("텍스트를 입력하세요");
+      return;
+    }
     setMessage("");
+    setLoading(true);
     const form = new FormData();
     form.set("project_id", projectId);
     form.set("source_text", sourceText);
@@ -85,6 +91,8 @@ export default function HomePage() {
       await refreshAll();
     } catch {
       setMessage("문서 업로드 실패");
+    } finally {
+      setLoading(false);
     }
   }
 
@@ -94,97 +102,126 @@ export default function HomePage() {
       setMessage("질문을 입력하세요");
       return;
     }
+    setMessage("");
+    setLoading(true);
 
-    const response = await fetch(ENDPOINT.queries, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        project_id: projectId,
-        question,
-      }),
-    });
-    if (!response.ok) {
-      setMessage("질의 처리 실패");
-      return;
+    try {
+      const response = await fetch(ENDPOINT.queries, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          project_id: projectId,
+          question,
+        }),
+      });
+      if (!response.ok) {
+        setMessage("질의 처리 실패");
+        return;
+      }
+      const payload: QueryResponse = await response.json();
+      setQueryResult(payload);
+      setQuestion("");
+      await refreshAll();
+    } catch {
+      setMessage("네트워크 오류가 발생했습니다. 잠시 후 다시 시도하세요.");
+    } finally {
+      setLoading(false);
     }
-    const payload: QueryResponse = await response.json();
-    setQueryResult(payload);
-    setQuestion("");
-    await refreshAll();
   }
 
   async function runAction() {
-    const response = await fetch(ENDPOINT.actions, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        project_id: projectId,
-        type: "summary",
-        payload: {
-          documents: documents.map((doc) => doc.id),
+    setLoading(true);
+    setActionResult("");
+
+    try {
+      const response = await fetch(ENDPOINT.actions, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
         },
-      }),
-    });
-    if (!response.ok) {
-      setActionResult("액션 실행 실패");
-      return;
+        body: JSON.stringify({
+          project_id: projectId,
+          type: "summary",
+          payload: {
+            documents: documents.map((doc) => doc.id),
+          },
+        }),
+      });
+      if (!response.ok) {
+        setActionResult("액션 실행 실패");
+        return;
+      }
+      const payload = await response.json();
+      setActionResult(payload.result);
+    } catch {
+      setActionResult("네트워크 오류가 발생했습니다. 잠시 후 다시 시도하세요.");
+    } finally {
+      setLoading(false);
     }
-    const payload = await response.json();
-    setActionResult(payload.result);
   }
 
   return (
     <main>
-      <h1>Knowledge Copilot</h1>
+      <h1 id="title">Knowledge Copilot</h1>
       <p>RAG, 액션형 AI, API 로그 추적까지 포함한 포트폴리오 프로젝트</p>
 
       <div className="grid">
-        <section className="card">
-          <h2>1) 문서 업로드</h2>
-          <form onSubmit={upload}>
-            <label className="form-field">
-              project_id
-              <input value={projectId} onChange={(e) => setProjectId(e.target.value)} />
-            </label>
-            <label className="form-field">
-              텍스트 문서
+        <section className="card" aria-labelledby="upload-heading">
+          <h2 id="upload-heading">1) 문서 업로드</h2>
+          <form onSubmit={upload} aria-busy={loading}>
+            <div className="form-field">
+              <label htmlFor="projectId">project_id</label>
+              <input
+                id="projectId"
+                value={projectId}
+                onChange={(e) => setProjectId(e.target.value)}
+              />
+            </div>
+            <div className="form-field">
+              <label htmlFor="sourceText">텍스트 문서</label>
               <textarea
+                id="sourceText"
                 rows={10}
                 value={sourceText}
                 onChange={(e) => setSourceText(e.target.value)}
                 placeholder="질문 답변의 근거가 될 텍스트를 넣어주세요"
               />
-            </label>
-            <button type="submit">문서 업로드</button>
+            </div>
+            <button type="submit" disabled={loading} aria-disabled={loading}>
+              {loading ? "업로드 중..." : "문서 업로드"}
+            </button>
           </form>
         </section>
 
-        <section className="card">
-          <h2>2) 질의</h2>
-          <form onSubmit={ask}>
-            <label className="form-field">
-              질문
+        <section className="card" aria-labelledby="query-heading">
+          <h2 id="query-heading">2) 질의</h2>
+          <form onSubmit={ask} aria-busy={loading}>
+            <div className="form-field">
+              <label htmlFor="question">질문</label>
               <textarea
+                id="question"
                 rows={5}
                 value={question}
                 onChange={(e) => setQuestion(e.target.value)}
                 placeholder="예: 이 문서의 핵심 결론은?"
               />
-            </label>
-            <button type="submit">질의 보내기</button>
+            </div>
+            <button type="submit" disabled={loading} aria-disabled={loading}>
+              {loading ? "질의 중..." : "질의 보내기"}
+            </button>
           </form>
         </section>
       </div>
 
-      {message ? <p>{message}</p> : null}
+      {message ? (
+        <p className="message" aria-live="polite">{message}</p>
+      ) : null}
 
       {queryResult ? (
-        <section className="card">
-          <h2>질의 응답</h2>
+        <section className="card" aria-labelledby="result-heading">
+          <h2 id="result-heading">질의 응답</h2>
           <p>{queryResult.answer}</p>
           <p>
             모델: {queryResult.model} / 지연: {queryResult.latency_ms}ms
@@ -193,14 +230,16 @@ export default function HomePage() {
         </section>
       ) : null}
 
-      <section className="card">
-        <h2>3) 액션</h2>
-        <button onClick={runAction}>문서 요약 액션 실행</button>
+      <section className="card" aria-labelledby="action-heading">
+        <h2 id="action-heading">3) 액션</h2>
+        <button onClick={runAction} disabled={loading} aria-disabled={loading}>
+          {loading ? "실행 중..." : "문서 요약 액션 실행"}
+        </button>
         {actionResult ? <pre>{actionResult}</pre> : null}
       </section>
 
-      <section className="card">
-        <h2>4) 문서/메트릭</h2>
+      <section className="card" aria-labelledby="metrics-heading">
+        <h2 id="metrics-heading">4) 문서/메트릭</h2>
         {metrics ? (
           <pre>
 {`문서: ${metrics.documents}\n청크: ${metrics.chunks}\n질의: ${metrics.queries}\n평균 응답: ${metrics.avg_query_latency_ms}ms\n피드백: ${metrics.feedback_count}건 / 평점 ${metrics.avg_feedback_rating ?? "N/A"}`}

From 2330423ca921a3c5717a515bddb469060066285b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Sat, 28 Feb 2026 16:27:20 +0900
Subject: [PATCH 2/2] fix(docs): escape special chars in Mermaid diagrams

Wrap parentheses and special characters in quotes to fix
GitHub Mermaid rendering parse errors.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 3454fea..3824b84 100644
--- a/README.md
+++ b/README.md
@@ -46,22 +46,22 @@
 
 ```mermaid
 flowchart LR
-    subgraph Frontend[Frontend (Vercel)]
+    subgraph Frontend["Frontend (Vercel)"]
         N[Next.js 14.2.15]
         React[React 18.3.1]
         TypeScript[TypeScript 5.5.4]
     end
 
-    subgraph Backend[Backend (Railway)]
+    subgraph Backend["Backend (Railway)"]
         FastAPI[FastAPI 0.112.0]
         PyEnv[Python 3.12]
         Uvicorn[Uvicorn 0.30.6]
-        SQLite[SQLite (파일 DB)]
+        SQLite["SQLite (파일 DB)"]
     end
 
     User[브라우저] --> N --> FastAPI
     FastAPI --> SQLite
-    FastAPI --> OpenAI[Embedding/Chat API]
+    FastAPI --> OpenAI["Embedding/Chat API"]
 ```
 
 ### 스택 정리
@@ -86,14 +86,14 @@ flowchart TD
     end
     subgraph API[API Layer]
         FAST[FastAPI]
-        ROUTES[REST endpoints /api/v1/*]
+        ROUTES["REST endpoints /api/v1/*"]
         DB[(SQLite)]
     end
 
     UI -->|HTTPS| ROUTES
     ROUTES --> FAST
     FAST --> DB
-    FAST --> OpenAI[(OpenAI API)]
+    FAST --> OpenAI[("OpenAI API")]
 ```
 
 ### API 엔드포인트