feat(server): embed SPA dist with fallback handler; single-binary deploy

.gitignore

@@ -35,3 +35,8 @@ Thumbs.db
 
 # Internal docs (specs / plans should never be committed)
 /docs/superpowers/
+
+# Embedded SPA dist: ignore real built artifacts but keep the .gitkeep
+# placeholder so `go build ./cmd/server` succeeds before `make build` runs.
+/cmd/server/web/dist/*
+!/cmd/server/web/dist/.gitkeep

Makefile

@@ -9,6 +9,7 @@ dev:
 
 build:
 	cd web && pnpm install && pnpm build
+	rm -rf cmd/server/web/dist && mkdir -p cmd/server/web/dist && cp -r web/dist/. cmd/server/web/dist/
 	go build -o bin/server ./cmd/server
 
 test:

cmd/server/embed.go

@@ -0,0 +1,10 @@
+// Package main 的 embed.go 持有前端构建产物。
+// build 流程会先 pnpm build 再把 web/dist 复制到 cmd/server/web/dist/，
+// go:embed 在编译期把整个目录注入到二进制。.gitkeep 占位文件保证未跑
+// `make build` 时 go build 也能成功（embed 不接受空目录）。
+package main
+
+import "embed"
+
+//go:embed all:web/dist
+var distFS embed.FS

cmd/server/main.go

@@ -25,7 +25,7 @@ func main() {
 	rootCtx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer cancel()
 
-	a, err := app.New(rootCtx, cfg)
+	a, err := app.New(rootCtx, cfg, distFS)
 	if err != nil {
 		_, _ = fmt.Fprintln(os.Stderr, "app new:", err)
 		os.Exit(1)

internal/app/app.go

@@ -18,8 +18,10 @@ package app
 
 import (
 	"context"
+	"embed"
 	"errors"
 	"fmt"
+	"io/fs"
 	"log/slog"
 	"net/http"
 	"time"
@@ -43,7 +45,9 @@ type App struct {
 }
 
 // New 把所有模块按启动顺序拼装好。任何阶段失败都会返回错误，不留半成品资源。
-func New(ctx context.Context, cfg *config.Config) (*App, error) {
+// dist 是 cmd/server 用 //go:embed 注入的前端构建产物，根目录为 web/dist；
+// fs.Sub 之后交给 SPA handler 提供静态文件 + index.html 回退。
+func New(ctx context.Context, cfg *config.Config, dist embed.FS) (*App, error) {
 	log := logger.FromEnv(cfg.Env, nil)
 
 	// 跑 migrations 必须在开池前；否则首次启动连不存在的表会让 ping 失败。
@@ -68,6 +72,12 @@ func New(ctx context.Context, cfg *config.Config) (*App, error) {
 	// 通过 App 字段透出去，目前保留局部变量以避免暴露未稳定 API。
 	_ = notifyDispatcher
 
+	spaSub, err := fs.Sub(dist, "web/dist")
+	if err != nil {
+		return nil, fmt.Errorf("sub fs: %w", err)
+	}
+	spaHandler := httpx.NewSPAHandler(spaSub)
+
 	r := httpx.NewRouter(httpx.RouterDeps{
 		HealthCheck: func(req *http.Request) error {
 			return db.HealthCheck(req.Context(), pool)
@@ -75,6 +85,7 @@ func New(ctx context.Context, cfg *config.Config) (*App, error) {
 		ReadyCheck: func(req *http.Request) error {
 			return db.HealthCheck(req.Context(), pool)
 		},
+		SPAHandler: spaHandler,
 	})
 
 	// chi.Router 接口本身已经声明 Use，无需类型断言到 *chi.Mux。

internal/transport/http/router.go

@@ -17,6 +17,9 @@ type RouterDeps struct {
 	HealthCheck func(*http.Request) error
 	// ReadyCheck is invoked from GET /readyz with the same contract.
 	ReadyCheck func(*http.Request) error
+	// SPAHandler 为 nil 时禁用前端 fallback；非 nil 时挂到 chi NotFound，
+	// 把未匹配的请求交给 SPA handler 处理（静态文件 + index.html 回退）。
+	SPAHandler http.Handler
 }
 
 // NewRouter builds the application's chi.Router with the standard
@@ -46,5 +49,9 @@ func NewRouter(deps RouterDeps) chi.Router {
 		_, _ = w.Write([]byte("ok"))
 	})
 
+	if deps.SPAHandler != nil {
+		r.NotFound(deps.SPAHandler.ServeHTTP)
+	}
+
 	return r
 }

internal/transport/http/spa.go

@@ -0,0 +1,34 @@
+// Package httpx 内的 spa.go 提供 SPA 静态资源 + 404 fallback。
+// 命中文件直接 ServeFile；不存在但路径无后缀视为前端路由，回退 index.html；
+// /api/ 前缀始终返回 404（避免把 API 拼写错误掩盖成 HTML）。
+package httpx
+
+import (
+	"errors"
+	"io/fs"
+	"net/http"
+	"strings"
+)
+
+// NewSPAHandler 把 distFS 暴露成 SPA handler。
+func NewSPAHandler(distFS fs.FS) http.Handler {
+	fileServer := http.FileServer(http.FS(distFS))
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/api/") {
+			http.NotFound(w, r)
+			return
+		}
+		path := strings.TrimPrefix(r.URL.Path, "/")
+		if path == "" {
+			path = "index.html"
+		}
+		if _, err := fs.Stat(distFS, path); err != nil {
+			if errors.Is(err, fs.ErrNotExist) && !strings.Contains(path, ".") {
+				r.URL.Path = "/index.html"
+				fileServer.ServeHTTP(w, r)
+				return
+			}
+		}
+		fileServer.ServeHTTP(w, r)
+	})
+}