DEV-MERGE-LEGACY-BACKEND-2026/cmd/api/main.go

// 命令 api：统一 Go 后端单二进制入口（ADR-011 模块化单体，ADR-015 单机双实例）。
//
// 职责（架构规格 §2.1 HTTP 接入层 + §7.3 部署形态）：
//  1. 解析 -env（dev/prod）加载配置（internal/infra/config，12-factor：
//     config/{env}.json + CONFIG_* 环境变量覆盖；敏感字段必须走环境变量）；
//  2. 幂等创建运行目录（log/{instanceId}/、tmp/{instanceId}/，双实例同机隔离）；
//  3. 装配 zap 结构化日志（trace_id 贯穿，§3.3）；
//  4. 装配 Fiber app + 中间件链（Recover→RequestID→...，§2.2）；
//  5. 注册 /healthz 存活探针（ADR-015：nginx upstream 健康检查 + systemd Watchdog）；
//  6. 各业务域路由挂载（org/academic/teaching/ai 域就绪后在此注册，
//     公开路由须在 Auth Group 之前——铁律 8 路由纪律）；
//  7. 任务工作池启动与优雅退出（task 域，GracePeriodSec 内排空在途任务，§3.7）。
//
// 当前状态：域模块尚未实现（internal/{org,academic,teaching,ai} 为空），
// 本入口提供"配置加载 + 健康检查 + 优雅退出"骨架，保证 go build ./... 全绿、
// 部署链路（systemd/nginx/Dockerfile）可先演练。
//
// 启动方式（dev）：
//
//	cp config/dev.example.json config/dev.json   # 填入 DSN 等（或走环境变量）
//	go run ./cmd/api -env=dev
package main

import (
	"crypto/rand"
	"encoding/hex"
	"flag"
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/fiber/v2/middleware/requestid"
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"

	"yuansiwei/unified-backend/internal/infra/config"
)

// main 进程入口：装配 → 监听 → 信号驱动优雅退出。
//
// 入参（命令行 flag）：
//   - env string：环境名（"dev"/"prod"），决定加载 config/{env}.json；默认 "dev"。
//
// 出参：进程退出码（0 正常；1 装配/运行失败）。
//
// 异常场景：
//   - 配置缺失/必填字段未填：fail-fast 退出（config.Load 返回错误，输出到 stderr 后 exit 1）；
//   - SIGTERM/SIGINT：在 GracePeriodSec 内排空存量请求后退出（ADR-015 滚动重启语义）。
func main() {
	env := flag.String("env", "dev", "运行环境（dev/prod），决定读取 config/{env}.json")
	flag.Parse()

	cfg, err := config.Load(*env)
	if err != nil {
		fmt.Fprintf(os.Stderr, "fatal: 配置加载失败: %v\n（提示：可复制 config/%s.example.json 为 config/%s.json 并填敏感字段）\n",
			err, *env, *env)
		os.Exit(1)
	}
	if err := config.EnsureRuntimeDirs(cfg.Server.InstanceID); err != nil {
		fmt.Fprintf(os.Stderr, "fatal: %v\n", err)
		os.Exit(1)
	}

	logger, err := newLogger(cfg.Log.Level)
	if err != nil {
		fmt.Fprintf(os.Stderr, "fatal: 初始化日志失败: %v\n", err)
		os.Exit(1)
	}
	defer func() { _ = logger.Sync() }()
	logger.Info("统一 Go 后端启动",
		zap.String("env", *env),
		zap.String("instance", cfg.Server.InstanceID),
		zap.String("addr", cfg.Server.Addr))

	app := fiber.New(fiber.Config{
		AppName:               "yuansiwei-unified-backend",
		ReadTimeout:           time.Duration(cfg.Server.ReadTimeoutSec) * time.Second,
		DisableStartupMessage: true,
		// 请求体上限 10MB：费用凭证/作业图片走 OSS 直传，接口侧只收元数据
		BodyLimit: 10 << 20,
	})

	// 中间件链（§2.2 顺序铁律：Recover 最前兜底 panic → RequestID 生成/透传 trace_id）
	app.Use(recoverMiddleware(logger))
	app.Use(requestid.New(requestid.Config{Generator: newTraceID}))

	// 存活探针（ADR-015：nginx upstream healthcheck + K8s 预留 liveness）
	app.Get("/healthz", func(c *fiber.Ctx) error {
		return c.JSON(fiber.Map{
			"status":   "ok",
			"instance": cfg.Server.InstanceID,
			"time":     time.Now().Format(time.RFC3339),
		})
	})

	// 业务域路由挂载点（域模块实现后在此注册；公开路由须在 Auth Group 之前——铁律 8）：
	//
	//	app.Get("/auth/jwks", identityHandler.JWKS)            // 公开
	//	auth := app.Group("/", middleware.Auth(logger))        // 以下全部需登录
	//	auth.Get("/auth/me", identityHandler.Me)
	//	auth.Get("/admin/courses/:id", academicHandler.Get)    // PC 端
	//	auth.Get("/student/homeworks", teachingHandler.List)   // 移动端

	// 优雅退出（SIGTERM/SIGINT；GracePeriodSec 内排空存量请求，§7.3）
	grace := time.Duration(cfg.Server.GracePeriodSec) * time.Second
	if grace <= 0 {
		grace = 30 * time.Second
	}
	done := make(chan struct{})
	go func() {
		sig := make(chan os.Signal, 1)
		signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
		s := <-sig
		logger.Info("收到退出信号，开始优雅停机", zap.String("signal", s.String()), zap.Duration("grace", grace))
		close(done)
	}()

	errCh := make(chan error, 1)
	go func() { errCh <- app.Listen(cfg.Server.Addr) }()

	select {
	case err := <-errCh:
		if err != nil {
			logger.Error("HTTP 服务异常退出", zap.Error(err))
			os.Exit(1)
		}
	case <-done:
		if err := app.ShutdownWithTimeout(grace); err != nil {
			logger.Warn("优雅退出超时，强制关闭", zap.Error(err))
		} else {
			logger.Info("服务已优雅退出")
		}
	}
}

// recoverMiddleware 全局 panic 兜底（§3.2 规则 4）：未捕获 panic 统一降级为
// body code=5001（HTTP 仍 200，铁律 6）+ 结构化日志（带堆栈 + trace_id），
// **绝不**把 panic 信息/堆栈透传给前端。
//
// 入参：
//   - logger *zap.Logger：进程级结构化日志器。
//
// 出参：
//   - fiber.Handler：Fiber 中间件（返回后继续 c.Next() 链）。
//
// 说明：骨架期直接写 5001 信封（不引入 infra/response 依赖，避免 main 包耦合具体域）；
// 域模块就绪后切换为 response.Fail 统一出口。
func recoverMiddleware(logger *zap.Logger) fiber.Handler {
	return func(c *fiber.Ctx) (err error) {
		defer func() {
			if p := recover(); p != nil {
				logger.Error("panic 已兜底",
					zap.String("trace_id", c.Get("X-Request-ID")),
					zap.String("path", c.Path()),
					zap.Any("panic", p))
				err = c.Status(fiber.StatusOK).JSON(fiber.Map{
					"code":    5001,
					"message": "系统繁忙",
					"success": false,
				})
			}
		}()
		return c.Next()
	}
}

// newTraceID 生成请求 trace_id（§3.3：nginx 透传 X-Request-ID 时 requestid 中间件不再生成，
// 缺失时以 crypto/rand 32 字节 hex 兜底；跨 Python Agent 调用时透传同一值）。
//
// 入参：无。
// 出参：
//   - string：64 字符 hex；crypto/rand 故障（概率≈0）时以时间戳兜底，不阻断请求。
func newTraceID() string {
	b := make([]byte, 32)
	if _, err := rand.Read(b); err != nil {
		return fmt.Sprintf("%064x", uint64(time.Now().UnixNano()))
	}
	return hex.EncodeToString(b)
}

// newLogger 按级别构造 zap 生产级 logger（JSON 编码，ts 用 RFC3339——访问日志与 trace 对齐，§3.3）。
//
// 入参：
//   - level string："debug"/"info"/"warn"/"error"（大小写不敏感；空/非法值按 info 处理）。
//
// 出参：
//   - *zap.Logger：就绪日志器（NewDevelopment 风格控制台可读 + 生产字段结构）。
//   - error：仅当 zap 构造失败时非 nil。
func newLogger(level string) (*zap.Logger, error) {
	var l zapcore.Level
	switch level {
	case "debug":
		l = zapcore.DebugLevel
	case "warn":
		l = zapcore.WarnLevel
	case "error":
		l = zapcore.ErrorLevel
	case "info", "":
		l = zapcore.InfoLevel
	default:
		l = zapcore.InfoLevel // 非法级别不阻断启动，按 info 兜底（配置错误由部署期自检发现）
	}
	cfg := zap.NewProductionConfig()
	cfg.Level = zap.NewAtomicLevelAt(l)
	cfg.EncoderConfig.TimeKey = "ts"
	cfg.EncoderConfig.EncodeTime = zapcore.RFC3339TimeEncoder
	return cfg.Build()
}