refactor: remove outdated NOTES.md and enhance type annotation

.cursor/rules/general.mdc

@@ -0,0 +1,15 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+description: Prefer using uv and pnpm for terminal operations, and always set proxy env vars for install commands. Chat responses should be in Chinese; code and comments in English.
+globs: 
+alwaysApply: true
+
+- Prefer using 'uv' for Python-related operations and 'pnpm' for Node.js tasks in terminal commands.
+- For commands that strongly rely on the external network, prepend with:
+  `export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890;`
+- All code comments, prompts, and code completions should be in English.
+- All Chat replies should be in Chinese.
+- use `docker compose` not `docker-compose`

.cursor/rules/github-operation.mdc

@@ -0,0 +1,19 @@
+---
+description: Any operations involving issues and pulls on GitHub
+globs: 
+alwaysApply: false
+---
+**Repository Resolution Logic:**
+
+- If owner and repo are explicitly provided, use them.
+- Otherwise, default to:
+
+    owner: telepace
+
+    repo: nexus
+
+    (i.e., https://github.com/telepace/nexus)
+
+- The language chosen for raising an issue: Chinese- 
+- Be careful not to be too AI in your tone.
+- Pay attention to choosing the appropriate labels and types. And select the latest Milestone

.env.example

@@ -24,16 +24,16 @@ DOMAIN=localhost.nip.io
 
 # Frontend Host: The full URL of the frontend application.
 # Used by the backend to generate links (e.g., in emails).
-# Example for local development: http://localhost:5173
+# Example for local development: http://localhost:8000
 # Example for production: https://dashboard.yourdomain.com
-FRONTEND_HOST=http://localhost:5173
+FRONTEND_HOST=http://localhost:8000
 
 # -- Backend Settings --
 
 # Backend CORS Origins: A comma-separated list of allowed origins for Cross-Origin Resource Sharing.
 # Include frontend URLs for local, staging, and production environments.
-# Example: http://localhost:5173,https://dashboard.yourdomain.com,https://staging.yourdomain.com
-BACKEND_CORS_ORIGINS="http://localhost,http://localhost:5173,https://localhost,https://localhost:5173,https://localhost:5174,http://localhost:5174,http://localhost.nip.io"
+# Example: http://localhost:8000,https://dashboard.yourdomain.com,https://staging.yourdomain.com
+BACKEND_CORS_ORIGINS="http://localhost,http://localhost:8000,https://localhost,https://localhost:8000,http://localhost.nip.io"
 
 # Secret Key: A strong, unique secret key for cryptographic signing (e.g., JWTs).
 # Generate a secure key using tools like `openssl rand -hex 32`.
@@ -153,12 +153,16 @@ DOCKER_IMAGE_BACKEND=backend
 # Docker Image Frontend: Name/tag of the frontend Docker image.
 DOCKER_IMAGE_FRONTEND=frontend
 
+# Docker Image Admin: Name/tag of the admin Docker image.
+DOCKER_IMAGE_ADMIN=admin
+
 # -- LiteLLM Settings --
 # Configuration for LiteLLM proxy service
 
 # LiteLLM DB Name: Name of the database for LiteLLM.
 # This will be created as a separate database in the main PostgreSQL instance.
 LITELLM_DB_NAME=litellm
+LITELLM_MASTER_KEY="sk-1234"
 
 # LiteLLM Port: Port number for the LiteLLM proxy service.
 LITELLM_PORT=4000
@@ -183,27 +187,38 @@ OPENAI_API_KEY=
 # KEEP THIS SECRET.
 ANTHROPIC_API_KEY=
 
+# OpenRouter
+OR_SITE_URL="https://openrouter.ai/api/v1"
+OR_APP_NAME="LiteLLM Nexus app"
+OR_API_KEY="sk-or-api03-1234567890"
+
 # Test environment configuration example (port number +1), multiple sets of services are deployed simultaneously on the same machine
 # TRAEFIK_HTTP_PORT=81
 # TRAEFIK_HTTPS_PORT=444
 # PROXY_HTTP_PORT=81
 # PROXY_DASHBOARD_PORT=8091
 # DB_PORT=5433
 # PGADMIN_PORT=5051
-# ADMINER_PORT=8081
 # BACKEND_PORT=8001
 # MAILCATCHER_WEB_PORT=1081
 # MAILCATCHER_SMTP_PORT=1026
-# FRONTEND_PORT=5174
+# FRONTEND_PORT=8000
 # PLAYWRIGHT_PORT=9324
 # BACKEND_PORT=8001
 # BACKEND_API_URL=http://localhost:8001
 # MAILCATCHER_WEB_PORT=1081
 # MAILCATCHER_HOST=http://localhost:1081
 
-# ADMINER_CONTAINER_PORT=8081
 # BACKEND_CONTAINER_PORT=8001
-# FRONTEND_CONTAINER_PORT=81
+# FRONTEND_CONTAINER_PORT=3001
+# ADMIN_CONTAINER_PORT=5174
 
 # -- Production Settings --
-# PRODUCTION_API_URL=https://api.yourdomain.com
+# PRODUCTION_API_URL=https://api.yourdomain.com
+
+# -- Google OAuth Settings --
+# Google OAuth client ID and secret for authentication
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8000/api/v1/login/google/callback
+FRONTEND_URL=http://localhost:3000

.github/workflows/docker-build.yml

@@ -12,6 +12,7 @@ on:
       - 'v*.*.*-*'
     paths:
       - 'backend/**'
+      - 'admin/**'
       - 'frontend/**'
       - '.github/workflows/docker-build.yml'
   workflow_dispatch:
@@ -98,7 +99,7 @@ jobs:
           cache-to: type=gha,mode=max
           provenance: true
 
-  build-and-push-frontend:
+  build-and-push-admin:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -140,14 +141,14 @@ jobs:
             echo "API_URL=https://api.${DOMAIN:-example.com}" >> $GITHUB_OUTPUT
           fi
 
-      - name: Get Docker metadata for frontend
-        id: metadata-frontend
+      - name: Get Docker metadata for admin
+        id: metadata-admin
         uses: docker/[email protected]
         with:
           images: |
-            docker.io/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env.outputs.ENV_SUFFIX }}
-            registry.cn-hangzhou.aliyuncs.com/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env.outputs.ENV_SUFFIX }}
-            ghcr.io/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env.outputs.ENV_SUFFIX }}
+            docker.io/${{ github.repository_owner }}/nexus-admin${{ steps.set-env.outputs.ENV_SUFFIX }}
+            registry.cn-hangzhou.aliyuncs.com/${{ github.repository_owner }}/nexus-admin${{ steps.set-env.outputs.ENV_SUFFIX }}
+            ghcr.io/${{ github.repository_owner }}/nexus-admin${{ steps.set-env.outputs.ENV_SUFFIX }}
           tags: |
             type=ref,event=tag
             type=schedule
@@ -159,18 +160,18 @@ jobs:
             type=semver,pattern={{major}}
             type=sha
 
-      - name: Build frontend
+      - name: Build admin
         uses: docker/build-push-action@v6
         with:
-          context: ./frontend
-          file: ./frontend/Dockerfile
+          context: ./admin
+          file: ./admin/Dockerfile
           build-args: |
             VITE_API_URL=${{ steps.set-env.outputs.API_URL }}
             SKIP_TS_CHECK=true
           platforms: linux/amd64,linux/arm64
           push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.metadata-frontend.outputs.tags }}
-          labels: ${{ steps.metadata-frontend.outputs.labels }}
+          tags: ${{ steps.metadata-admin.outputs.tags }}
+          labels: ${{ steps.metadata-admin.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
           provenance: true
@@ -239,8 +240,8 @@ jobs:
       - name: Build playwright
         uses: docker/build-push-action@v6
         with:
-          context: ./frontend
-          file: ./frontend/Dockerfile.playwright
+          context: ./admin
+          file: ./admin/Dockerfile.playwright
           build-args: |
             VITE_API_URL=${{ steps.set-env-playwright.outputs.API_URL }}
             CI=true
@@ -251,3 +252,79 @@ jobs:
           cache-from: type=gha
           cache-to: type=gha,mode=max
           provenance: true
+
+  build-and-push-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Log in to AliYun Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: registry.cn-hangzhou.aliyuncs.com
+          username: ${{ secrets.ALIREGISTRY_USERNAME }}
+          password: ${{ secrets.ALIREGISTRY_TOKEN }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set environment variables
+        id: set-env-frontend
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ github.event.inputs.environment }}" == "testing" ]]; then
+            echo "ENV_SUFFIX=-testing" >> $GITHUB_OUTPUT
+            echo "API_URL=http://127.0.0.1:8000" >> $GITHUB_OUTPUT
+          else
+            echo "ENV_SUFFIX=" >> $GITHUB_OUTPUT
+            echo "API_URL=https://api.${DOMAIN:-example.com}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Get Docker metadata for frontend
+        id: metadata-frontend
+        uses: docker/[email protected]
+        with:
+          images: |
+            docker.io/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env-frontend.outputs.ENV_SUFFIX }}
+            registry.cn-hangzhou.aliyuncs.com/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env-frontend.outputs.ENV_SUFFIX }}
+            ghcr.io/${{ github.repository_owner }}/nexus-frontend${{ steps.set-env-frontend.outputs.ENV_SUFFIX }}
+          tags: |
+            type=ref,event=tag
+            type=schedule
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern=v{{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha
+
+      - name: Build frontend
+        uses: docker/build-push-action@v6
+        with:
+          context: ./frontend
+          file: ./frontend/Dockerfile
+          build-args: |
+            NEXT_PUBLIC_API_URL=${{ steps.set-env-frontend.outputs.API_URL }}
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.metadata-frontend.outputs.tags }}
+          labels: ${{ steps.metadata-frontend.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: true

.github/workflows/generate-client.yml

@@ -29,12 +29,17 @@ jobs:
           # token: ${{ (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && secrets.YOUR_PAT_OR_GITHUB_TOKEN || '' }}
 
       # 2. Setup Environment
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: lts/*
-          cache: 'npm' # Enable npm caching
-          cache-dependency-path: frontend/package-lock.json
+          cache: 'pnpm'
+          cache-dependency-path: frontend/pnpm-lock.yaml
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -49,7 +54,7 @@ jobs:
 
       # 3. Install Dependencies
       - name: Install Frontend Dependencies
-        run: npm ci
+        run: pnpm install
         working-directory: frontend
 
       # 安装所有后端依赖项

.github/workflows/playwright.yml

@@ -47,9 +47,14 @@ jobs:
       fail-fast: false
     steps:
     - uses: actions/checkout@v4
+    - name: Install pnpm
+      uses: pnpm/action-setup@v2
+      with:
+        version: 8
     - uses: actions/setup-node@v4
       with:
         node-version: lts/*
+        cache: 'pnpm'
     - uses: actions/setup-python@v5
       with:
         python-version: '3.10'
@@ -65,7 +70,7 @@ jobs:
         enable-cache: true
     - run: uv sync
       working-directory: backend
-    - run: npm ci
+    - run: pnpm install --frozen-lockfile
       working-directory: frontend
     - run: uv run bash scripts/generate-client.sh
       env:
@@ -108,7 +113,7 @@ jobs:
       with:
         node-version: 20
     - name: Install dependencies
-      run: npm ci
+      run: pnpm install --frozen-lockfile
       working-directory: frontend
     - name: Download blob reports from GitHub Actions Artifacts
       uses: actions/download-artifact@v4

.github/workflows/test-docker-compose.yml

@@ -39,7 +39,7 @@ jobs:
         run: |
           docker compose down -v --remove-orphans
           docker compose build
-          docker compose up -d --wait backend frontend adminer
+          docker compose up -d --wait backend frontend pgadmin
 
       - name: Test backend is up
         run: curl http://localhost:8000/api/v1/utils/health-check