feat: implement AI service infrastructure, admin dashboard, and gRPC communication layer

Author: hicancan

.github/actions/setup-web/action.yml

@@ -3,7 +3,6 @@ description: "Sets up node, restores cache, and installs dependencies for web jo
 runs:
   using: "composite"
   steps:
-    - uses: actions/checkout@v4
     - name: Setup Node
       uses: actions/setup-node@v4
       with:

.github/workflows/ci.yml

@@ -186,16 +186,18 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
-      - name: Setup Python
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.5.x"
+      - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
-      - name: Install uv
-        run: python -m pip install --upgrade pip uv
+          python-version-file: "apps/ai-service/.python-version"
       - name: Sync dependencies with uv
-        run: uv sync --project apps/ai-service --python 3.12 --group dev
+        run: uv sync --project apps/ai-service --group dev
       - name: Run pytest
-        run: uv run --project apps/ai-service --python 3.12 pytest -q
+        run: uv run --project apps/ai-service pytest -q
 
   secrets-scan:
     runs-on: ubuntu-latest

.gitignore

@@ -57,4 +57,13 @@ error.txt
 doc/papers/
 
 # Root-level Playwright dependencies
-/node_modules/
+/node_modules/
+/package-lock.json
+
+# CI / debug artefacts (never commit)
+ci_jobs.json
+ci_status*.json
+failed_logs.txt
+gh_log*.txt
+mvn_test_err.txt
+*_jobs.json

apps/ai-service/ai_service/app.py

@@ -52,6 +52,12 @@ async def lifespan(_: FastAPI):
             serve_grpc(llm_service, kb_service, worker, idempotency_store, settings)
         )
 
+        def _grpc_err(t: asyncio.Task) -> None:
+            if not t.cancelled() and t.exception():
+                logger.error("gRPC server failed: %s", t.exception())
+
+        grpc_task.add_done_callback(_grpc_err)
+
         yield
 
         await llm_service.aclose()

apps/ai-service/ai_service/llm.py

@@ -308,16 +308,23 @@ async def embed(self, text: str) -> list[float]:
         if not cleaned:
             return [0.0 for _ in range(self.settings.embedding_dim)]
 
+        embed_timeout = 30.0
         errors: list[str] = []
         try:
-            vector = await self._ollama.embed(cleaned, self.settings.ollama_embed_model)
+            vector = await asyncio.wait_for(
+                self._ollama.embed(cleaned, self.settings.ollama_embed_model),
+                timeout=embed_timeout,
+            )
             return self._normalize_dimension(vector)
         except Exception as ex:
             errors.append(f"ollama:{ex}")
 
         if self.settings.openai_api_key:
             try:
-                vector = await self._openai.embed(cleaned, self.settings.openai_embed_model)
+                vector = await asyncio.wait_for(
+                    self._openai.embed(cleaned, self.settings.openai_embed_model),
+                    timeout=embed_timeout,
+                )
                 return self._normalize_dimension(vector)
             except Exception as ex:
                 errors.append(f"openai:{ex}")

apps/api/pom.xml

@@ -145,11 +145,6 @@
       <artifactId>jakarta.annotation-api</artifactId>
       <version>3.0.0</version>
     </dependency>
-    <dependency>
-      <groupId>javax.annotation</groupId>
-      <artifactId>javax.annotation-api</artifactId>
-      <version>1.3.2</version>
-    </dependency>
   </dependencies>
 
   <build>

apps/api/src/main/java/com/edunexus/api/config/GrpcServerRunner.java

@@ -30,7 +30,7 @@ public GrpcServerRunner(
     public void start() {
         try {
             server = ServerBuilder.forPort(port).addService(jobStatusService).build().start();
-            log.info("gRPC Server started, listening on " + port);
+            log.info("gRPC Server started, listening on {}", port);
             isRunning = true;
         } catch (IOException e) {
             log.error("Failed to start gRPC server", e);
@@ -42,6 +42,14 @@ public void start() {
     public void stop() {
         if (server != null) {
             server.shutdown();
+            try {
+                if (!server.awaitTermination(10, java.util.concurrent.TimeUnit.SECONDS)) {
+                    server.shutdownNow();
+                }
+            } catch (InterruptedException e) {
+                server.shutdownNow();
+                Thread.currentThread().interrupt();
+            }
         }
         isRunning = false;
     }

apps/api/src/main/java/com/edunexus/api/service/AiClient.java

@@ -114,7 +114,15 @@ public AiClient(
     @PreDestroy
     public void shutdown() {
         if (grpcChannel != null) {
-            grpcChannel.shutdownNow();
+            grpcChannel.shutdown();
+            try {
+                if (!grpcChannel.awaitTermination(5, TimeUnit.SECONDS)) {
+                    grpcChannel.shutdownNow();
+                }
+            } catch (InterruptedException e) {
+                grpcChannel.shutdownNow();
+                Thread.currentThread().interrupt();
+            }
         }
     }
 

apps/api/src/main/resources/application.yml

@@ -32,6 +32,8 @@ app:
   refresh-token-expires-in: ${REFRESH_TOKEN_EXPIRES_IN:14d}
   ai-service-grpc-host: ${AI_SERVICE_GRPC_HOST:127.0.0.1}
   ai-service-grpc-port: ${AI_SERVICE_GRPC_PORT:50051}
+  ai-service-http-host: ${AI_SERVICE_HOST:127.0.0.1}
+  ai-service-http-port: ${AI_SERVICE_PORT:8000}
   ai-service-token: ${AI_SERVICE_TOKEN:change-this-in-local-too}
   ai-question-timeout-seconds: ${AI_QUESTION_TIMEOUT_SECONDS:180}
   lesson-plan-timeout-seconds: ${LESSON_PLAN_TIMEOUT_SECONDS:90}

apps/web/src/pages/admin/AdminDashboardPage.vue

@@ -528,6 +528,7 @@ onMounted(loadMetrics);
   display: flex;
   gap: 14px;
   align-items: center;
+  margin-top: 0 !important;
 }
 
 .metric-icon {