feat: add standalone EXE packaging support (via PyInstaller)

Author: unitagain

.gitignore

@@ -0,0 +1,44 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+
+a = Analysis(
+    ['backend\\app\\main.py'],
+    pathex=[],
+    binaries=[],
+    datas=[('backend/static', 'static')],
+    hiddenimports=['uvicorn.logging', 'uvicorn.loops', 'uvicorn.loops.auto', 'uvicorn.protocols', 'uvicorn.protocols.http', 'uvicorn.protocols.http.auto', 'uvicorn.lifespan', 'uvicorn.lifespan.on', 'engineio.async_drivers.aiohttp'],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='NOVIX',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='NOVIX',
+)

NOVIX.spec

@@ -45,6 +45,12 @@ class Settings(BaseSettings):
     novix_agent_writer_provider: str = os.getenv("NOVIX_AGENT_WRITER_PROVIDER", "")
     novix_agent_reviewer_provider: str = os.getenv("NOVIX_AGENT_REVIEWER_PROVIDER", "")
     novix_agent_editor_provider: str = os.getenv("NOVIX_AGENT_EDITOR_PROVIDER", "")
+    
+    # Storage Configuration / 存储路径配置
+    # Note: Will be calculated in load_config logic if needed, but here we set default
+    # If using absolute path in .env, use it. Otherwise relative.
+    # We need a dynamic property for this in usage.
+    data_dir: str = "../data"  # Default relative path
 
 
 def load_config(config_path: str = "config.yaml") -> Dict[str, Any]:
@@ -57,7 +63,18 @@ def load_config(config_path: str = "config.yaml") -> Dict[str, Any]:
     Returns:
         Configuration dictionary / 配置字典
     """
-    config_file = Path(__file__).parent.parent / config_path
+    import sys
+    
+    # Determine root path: Dev or Frozen (EXE)
+    if getattr(sys, 'frozen', False):
+        # Running as PyInstaller Bundle
+        # The config file should be next to the EXE
+        root_path = Path(sys.executable).parent
+    else:
+        # Running as Source Code
+        root_path = Path(__file__).parent.parent
+
+    config_file = root_path / config_path
 
     if not config_file.exists():
         raise FileNotFoundError(f"Config file not found: {config_file}")
@@ -86,6 +103,19 @@ def _replace_env_vars(obj: Any) -> Any:
     return obj
 
 
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        # Dynamic path resolution for data_dir
+        import sys
+        if getattr(sys, 'frozen', False):
+             # Frozen: data dir is next to EXE
+             root = Path(sys.executable).parent
+             self.data_dir = str(root / "data")
+        else:
+             # Dev: data dir is relative to source
+             # Although default is "../data", we can make it absolute for clarity
+             pass
+
 # Global settings instance / 全局设置实例
 settings = Settings()
 config = load_config()

backend/app/config.py

@@ -35,38 +35,125 @@
 )
 
 # Register routers / 注册路由
-app.include_router(projects_router)
-app.include_router(cards_router)
-app.include_router(canon_router)
-app.include_router(drafts_router)
-app.include_router(session_router)
-app.include_router(config_router)
-app.include_router(websocket_router)
-app.include_router(fanfiction_router)
-
-
-@app.get("/")
-async def root():
-    """Root endpoint / 根路径"""
-    return {
-        "message": "NOVIX API is running",
-        "version": "0.1.0",
-        "status": "healthy",
-        "docs": "/docs"
-    }
+# Register routers / 注册路由
+# Strategy: Dual Mount
+# Mount at root "/" for Dev mode (where Vite proxy strips /api)
+# Mount at "/api" for Prod/EXE mode (where frontend calls /api directly)
+routers = [
+    projects_router,
+    cards_router,
+    canon_router,
+    drafts_router,
+    session_router,
+    config_router,
+    websocket_router,
+    fanfiction_router
+]
+
+for router in routers:
+    app.include_router(router)              # Dev: http://localhost:8000/projects
+    app.include_router(router, prefix="/api") # Prod: http://localhost:8000/api/projects
+
+
+
 
 
 @app.get("/health")
 async def health_check():
     """Health check endpoint / 健康检查"""
     return {"status": "ok"}
 
+@app.on_event("startup")
+async def on_startup():
+    """Startup event handler / 启动事件处理"""
+    import sys
+    import webbrowser
+    import asyncio
+    
+    # Auto-open browser in a separate thread to not block startup
+    # But webbrowser.open is usually fire-and-forget
+    if getattr(sys, 'frozen', False):
+        url = f"http://localhost:{settings.port}"
+        print(f"[Main] Auto-opening browser at {url} ...")
+        # Small delay to ensure server is ready
+        async def open_browser():
+            await asyncio.sleep(1.5)
+            webbrowser.open(url)
+        asyncio.create_task(open_browser())
+
+# --- Static Files / SPA Support (Added for Packaging) ---
+import sys
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pathlib import Path
+
+# Check where static files are located
+if getattr(sys, 'frozen', False):
+    # Running as PyInstaller Bundle
+    base_path = getattr(sys, '_MEIPASS', Path(sys.executable).parent)
+    static_dir = Path(base_path) / "static"
+else:
+    # Dev: Look for backend/static if it exists (for testing build script without freezing)
+    static_dir = Path(__file__).parent.parent / "static"
+
+if static_dir.exists():
+    print(f"[Main] Serving static files from: {static_dir}")
+    
+    # 1. Mount assets (css, js, images)
+    app.mount("/assets", StaticFiles(directory=str(static_dir / "assets")), name="assets")
+    
+    # 2. Serve Index at Root
+    @app.get("/")
+    async def serve_root():
+        return FileResponse(static_dir / "index.html")
+
+    # 3. Catch-all for SPA routes (Serve index.html)
+    @app.get("/{full_path:path}")
+    async def serve_spa(full_path: str):
+        # Safety: If request asks for /api/..., and we reached here, it's a 404.
+        # Don't return HTML, otherwise frontend crashes (SyntaxError).
+        if full_path.startswith("api/") or full_path.startswith("api"):
+            from fastapi import HTTPException
+            raise HTTPException(status_code=404, detail="API Endpoint Not Found")
+
+        # Check if file exists in static (e.g. favicon.ico)
+        file_path = static_dir / full_path
+        if file_path.exists() and file_path.is_file():
+            return FileResponse(file_path)
+            
+        # Otherwise serve index.html for SPA routing
+        return FileResponse(static_dir / "index.html")
+else:
+    print("[Main] Static directory not found. Running in API-only mode (Dev).")
+
 
 if __name__ == "__main__":
     import uvicorn
-    uvicorn.run(
-        "app.main:app",
-        host=settings.host,
-        port=settings.port,
-        reload=settings.debug
-    )
+    import multiprocessing
+    
+    # Critical for Windows EXE to prevent infinite spawn loop
+    multiprocessing.freeze_support()
+    
+    # Determine execution mode
+    is_frozen = getattr(sys, 'frozen', False)
+    
+    if is_frozen:
+        # Prod/EXE: Run directly with app instance, NO RELOAD
+        # Reloading in frozen mode causes infinite subprocess spawning
+        print("[Main] Running in Frozen (EXE) Mode")
+        uvicorn.run(
+            app,  # Pass app instance directly, not string
+            host=settings.host, 
+            port=settings.port, 
+            reload=False,
+            log_level="info"
+        )
+    else:
+        # Dev: Run with reload
+        print("[Main] Running in Dev Mode")
+        uvicorn.run(
+            "app.main:app",
+            host=settings.host,
+            port=settings.port,
+            reload=settings.debug
+        )

backend/app/main.py

@@ -14,14 +14,15 @@
 class BaseStorage:
     """Base storage class with common file operations / 带通用文件操作的存储基类"""
 
-    def __init__(self, data_dir: str = "../data"):
+    def __init__(self, data_dir: Optional[str] = None):
         """
         Initialize storage
         
         Args:
             data_dir: Root data directory / 数据根目录
         """
-        self.data_dir = Path(data_dir)
+        from app.config import settings
+        self.data_dir = Path(data_dir or settings.data_dir)
         self.encoding = "utf-8"
 
     def get_project_path(self, project_id: str) -> Path: