From ec9dfb0d3f6d2b19f1b7aa612feec928c3c446cf Mon Sep 17 00:00:00 2001
From: erio <asakifeng@gmail.com>
Date: Sun, 15 Mar 2026 19:25:43 +0800
Subject: [PATCH 1/2] feat(web): support local file override for embedded
 static assets

Add override directory (data/public/) that takes precedence over
embed FS, allowing per-deployment static file customization via
docker volume mounts without rebuilding the image.
---
 backend/internal/web/embed_on.go | 65 +++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 10 deletions(-)

diff --git a/backend/internal/web/embed_on.go b/backend/internal/web/embed_on.go
index 41ce4d48bd..aa5bb60dc1 100644
--- a/backend/internal/web/embed_on.go
+++ b/backend/internal/web/embed_on.go
@@ -10,6 +10,8 @@ import (
 	"io"
 	"io/fs"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -32,11 +34,12 @@ type PublicSettingsProvider interface {
 
 // FrontendServer serves the embedded frontend with settings injection
 type FrontendServer struct {
-	distFS     fs.FS
-	fileServer http.Handler
-	baseHTML   []byte
-	cache      *HTMLCache
-	settings   PublicSettingsProvider
+	distFS      fs.FS
+	fileServer  http.Handler
+	baseHTML    []byte
+	cache       *HTMLCache
+	settings    PublicSettingsProvider
+	overrideDir string // local file override directory
 }
 
 // NewFrontendServer creates a new frontend server with settings injection
@@ -62,11 +65,12 @@ func NewFrontendServer(settingsProvider PublicSettingsProvider) (*FrontendServer
 	cache.SetBaseHTML(baseHTML)
 
 	return &FrontendServer{
-		distFS:     distFS,
-		fileServer: http.FileServer(http.FS(distFS)),
-		baseHTML:   baseHTML,
-		cache:      cache,
-		settings:   settingsProvider,
+		distFS:      distFS,
+		fileServer:  http.FileServer(http.FS(distFS)),
+		baseHTML:    baseHTML,
+		cache:       cache,
+		settings:    settingsProvider,
+		overrideDir: filepath.Join("data", "public"),
 	}, nil
 }
 
@@ -99,6 +103,11 @@ func (s *FrontendServer) Middleware() gin.HandlerFunc {
 			return
 		}
 
+		// Try local override first
+		if s.tryServeOverride(c, cleanPath) {
+			return
+		}
+
 		// Serve static files normally
 		s.fileServer.ServeHTTP(c.Writer, c.Request)
 		c.Abort()
@@ -114,6 +123,22 @@ func (s *FrontendServer) fileExists(path string) bool {
 	return true
 }
 
+// tryServeOverride checks if a local override file exists and serves it.
+// Files in overrideDir take precedence over embedded files.
+func (s *FrontendServer) tryServeOverride(c *gin.Context, cleanPath string) bool {
+	if s.overrideDir == "" {
+		return false
+	}
+	filePath := filepath.Join(s.overrideDir, filepath.Clean("/"+cleanPath))
+	info, err := os.Stat(filePath)
+	if err != nil || info.IsDir() {
+		return false
+	}
+	c.File(filePath)
+	c.Abort()
+	return true
+}
+
 func (s *FrontendServer) serveIndexHTML(c *gin.Context) {
 	// Get nonce from context (generated by SecurityHeaders middleware)
 	nonce := middleware.GetNonceFromContext(c)
@@ -196,6 +221,7 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 		panic("failed to get dist subdirectory: " + err.Error())
 	}
 	fileServer := http.FileServer(http.FS(distFS))
+	overrideDir := filepath.Join("data", "public")
 
 	return func(c *gin.Context) {
 		path := c.Request.URL.Path
@@ -212,6 +238,10 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 
 		if file, err := distFS.Open(cleanPath); err == nil {
 			_ = file.Close()
+			// Try local override first
+			if tryServeOverrideFile(c, overrideDir, cleanPath) {
+				return
+			}
 			fileServer.ServeHTTP(c.Writer, c.Request)
 			c.Abort()
 			return
@@ -221,6 +251,21 @@ func ServeEmbeddedFrontend() gin.HandlerFunc {
 	}
 }
 
+// tryServeOverrideFile is a standalone version of tryServeOverride for legacy usage.
+func tryServeOverrideFile(c *gin.Context, overrideDir, cleanPath string) bool {
+	if overrideDir == "" {
+		return false
+	}
+	filePath := filepath.Join(overrideDir, filepath.Clean("/"+cleanPath))
+	info, err := os.Stat(filePath)
+	if err != nil || info.IsDir() {
+		return false
+	}
+	c.File(filePath)
+	c.Abort()
+	return true
+}
+
 func shouldBypassEmbeddedFrontend(path string) bool {
 	trimmed := strings.TrimSpace(path)
 	return strings.HasPrefix(trimmed, "/api/") ||

From 8688e4b78e11ef8cd0a6de12d54fc961e14b640e Mon Sep 17 00:00:00 2001
From: erio <asakifeng@gmail.com>
Date: Sun, 15 Mar 2026 19:26:04 +0800
Subject: [PATCH 2/2] chore: bump version to 0.1.99.7

---
 backend/cmd/server/VERSION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend/cmd/server/VERSION b/backend/cmd/server/VERSION
index 96a4f2f67c..1909a763b3 100644
--- a/backend/cmd/server/VERSION
+++ b/backend/cmd/server/VERSION
@@ -1 +1 @@
-0.1.99.6
+0.1.99.7