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）。
//
// 当前状态：
//   - identity 模块（两步登录 / me / refresh / logout）已装配（T4-6），含 DB 连接 + 核心表 AutoMigrate
//     （guarded：仅 UNIFIED_AUTO_MIGRATE=1 时执行，生产幂等不漂移）、Redis 连接 + token 存储 +
//     RS256 签发器 + 仓储 + AuthService + Handler + 验签中间件 + /auth/* 路由；
//   - org 模块（机构/校区只读 + RBAC 矩阵配置 `/org/role-permissions`）已装配（T6）；
//   - academic 模块 AC-14 第一批已接线（40 个端点：财务 16 + 账单/仪表盘 2 + 活动 16 + 分账 6），
//     注册表与运行期断言在 `internal/academic/handler/route.go`，装配见 `wiring_academic.go`
//     的 `registerAcademicRoutes`（main 只调这一个函数）；
//   - teaching/ai 域尚未实现，域模块就绪后在"业务域路由挂载点"注册。
//
// 启动方式（dev）：
//
//	cp config/dev.example.json config/dev.json   # 填入 DSN/Redis/私钥（或走环境变量）
//	export UNIFIED_AUTO_MIGRATE=1                # 首次：建核心表（生产默认关，防 schema 漂移）
//	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/identity/handler"
	"yuansiwei/unified-backend/internal/identity/model"
	"yuansiwei/unified-backend/internal/identity/repository"
	"yuansiwei/unified-backend/internal/identity/service"
	"yuansiwei/unified-backend/internal/identity/token"
	"yuansiwei/unified-backend/internal/identity/wechat"
	"yuansiwei/unified-backend/internal/infra/config"
	"yuansiwei/unified-backend/internal/infra/db"
	"yuansiwei/unified-backend/internal/infra/redis"
	"yuansiwei/unified-backend/internal/infra/tz"
	orghandler "yuansiwei/unified-backend/internal/org/handler"
	orgmodel "yuansiwei/unified-backend/internal/org/model"
	"yuansiwei/unified-backend/internal/org/rbac"
	orgrepo "yuansiwei/unified-backend/internal/org/repository"
	orgservice "yuansiwei/unified-backend/internal/org/service"
)

// 编译期断言：*rbac.Resolver 须满足 identity 的 MenuProvider 接口（签名漂移即编译失败，
// 杜绝"装配注入了但方法签名不匹配"的隐蔽错误——生产注入点见 main() 内 service.Config.MenuProvider）。
var _ service.MenuProvider = (*rbac.Resolver)(nil)

// 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() {
	// ① 进程时区**最先固定**（任何 time.Now() / DB 连接之前）：财务账期按本地日历日结算，
	// UTC 容器会让跨日/跨月统计整体错位；前端契约也已定死时间字段为 RFC3339 带 +08:00。
	// 与 DSN 的 loc=Asia%2FShanghai 由 infra/db 统一收口，二者必须同区（详见 internal/infra/tz）。
	loc := tz.Apply()

	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),
		zap.String("timezone", loc.String()))

	// ---- 基础设施装配（fail-fast：DB/Redis 连不上不允许启动）----
	gdb, err := db.NewDB(cfg.DB)
	if err != nil {
		logger.Error("数据库连接失败", zap.Error(err))
		os.Exit(1)
	}
	defer func() { _ = db.Close(gdb) }()

	// 核心表建表（guarded：UNIFIED_AUTO_MIGRATE=1 才执行）。
	// 生产默认关闭——schema 演进走受控迁移（W2 割接脚本 / DDL 变更评审），
	// 启动时 AutoMigrate 会按 GORM model 增列，与"目标态 DDL 先行"纪律冲突（ADR-013/D1）。
	if os.Getenv("UNIFIED_AUTO_MIGRATE") == "1" {
		// identity 域 4 表 + org 域核心表（t_membership/t_institution/t_campus 等）
		// ——登录链路引用 membership→institution，缺一即登录查不到作用域
		tables := append(model.AllTables(), orgmodel.AllTables()...)
		if err := db.Migrate(gdb, tables...); err != nil {
			logger.Error("核心表 AutoMigrate 失败", zap.Error(err))
			os.Exit(1)
		}
		logger.Info("核心表已 AutoMigrate（UNIFIED_AUTO_MIGRATE=1）")
	}

	rc, err := redis.NewClient(cfg.Redis)
	if err != nil {
		logger.Error("Redis 连接失败", zap.Error(err))
		os.Exit(1)
	}
	defer func() { _ = rc.Close() }()

	// ---- identity 模块装配（T4-6）----
	refreshStore := redis.NewRefreshStore(rc)
	revocation := redis.NewRevocationStore(rc, cfg.Auth.RevocationKeyPrefix)
	tickets := redis.NewLoginTicketStore(rc)
	// 微信扫码登录状态机存储（per-state 会话，双实例共享；与 tickets 同一 Redis）
	wxStates := redis.NewWechatQrcodeStore(rc)

	accessTTL := time.Duration(cfg.Auth.AccessTokenTTLMin) * time.Minute
	if accessTTL <= 0 {
		accessTTL = 30 * time.Minute // 缺省兜底（架构规格 §7.2 固定 30min）
	}
	refreshTTL := time.Duration(cfg.Auth.RefreshTokenTTLDay) * 24 * time.Hour
	if refreshTTL <= 0 {
		refreshTTL = 30 * 24 * time.Hour
	}
	issuer, err := token.NewIssuer(cfg.Auth.PrivateKeyPEM, cfg.Auth.Issuer, accessTTL, refreshTTL, refreshStore, revocation)
	if err != nil {
		logger.Error("RS256 签发器装配失败（私钥解析？）", zap.Error(err))
		os.Exit(1)
	}
	// 验签公钥：未配置 PublicKeysPEM 时从私钥派生（单机双实例 ADR-015 共享同一密钥对）
	pubKeys := cfg.Auth.PublicKeysPEM
	if len(pubKeys) == 0 {
		derived, derr := token.PublicKeysFromPrivateKey(cfg.Auth.PrivateKeyPEM)
		if derr != nil {
			logger.Error("验签公钥派生失败", zap.Error(derr))
			os.Exit(1)
		}
		pubKeys = []string{derived}
		logger.Warn("Auth.PublicKeysPEM 未配置，已从 PrivateKeyPEM 派生公钥（生产建议显式配置以支持密钥轮换）")
	}

	// RBAC 解析器（T6.5：role→菜单树/权限码；平台级 PermissionRepo 直连 gdb，TTL 取 0 走缺省 30s）
	// 作为 identity 的 MenuProvider 注入：/auth/issue 与 /auth/me 据此下发 menuTree + permissions。
	rbacResolver := rbac.NewResolver(orgrepo.NewPermissionRepo(gdb), 0)

	authSvc, err := service.NewAuthService(service.Config{
		Users:        repository.NewUserRepo(gdb),
		Identities:   repository.NewIdentityRepo(gdb),
		Memberships:  repository.NewMembershipRepo(gdb),
		Issuer:       issuer,
		Tickets:      tickets,
		AccessTTL:    accessTTL,
		PublicKeys:   pubKeys,
		IssuerStr:    cfg.Auth.Issuer,
		Revocation:   revocation,
		MenuProvider: rbacResolver,
	})
	if err != nil {
		logger.Error("AuthService 装配失败", zap.Error(err))
		os.Exit(1)
	}
	// 微信扫码登录服务（可选装配：仅当配齐 per-campus appid + 对外回调地址时注入；
	// 未配齐时 Handler.wechat 为 nil，/auth/wechat/* 端点返回 4004"未配置"——不阻断其他登录链路）。
	var wechatSvc *service.WechatService
	if len(cfg.WeChat.Campuses) > 0 && cfg.WeChat.CallbackURL != "" {
		campusCfgs := make([]service.WechatCampus, 0, len(cfg.WeChat.Campuses))
		for _, cp := range cfg.WeChat.Campuses {
			campusCfgs = append(campusCfgs, service.WechatCampus{
				CampusID: cp.CampusID, AppID: cp.AppID, Secret: cp.Secret,
			})
		}
		ws, werr := service.NewWechatService(service.WechatConfig{
			Client:      wechat.NewHTTPClient(),
			States:      wxStates,
			Tickets:     tickets,
			Identities:  repository.NewIdentityRepo(gdb),
			Memberships: repository.NewMembershipRepo(gdb),
			Campuses:    campusCfgs,
			CallbackURL: cfg.WeChat.CallbackURL,
		})
		if werr != nil {
			logger.Error("WechatService 装配失败（微信扫码登录将不可用，不影响账密登录）", zap.Error(werr))
		} else {
			wechatSvc = ws
			logger.Info("微信扫码登录已启用", zap.Int("campuses", len(campusCfgs)))
		}
	} else {
		logger.Warn("微信扫码登录未配置（缺 per-campus appid 或回调地址），/auth/wechat/* 端点将返回 4004")
	}

	authH, err := handler.New(handler.Config{Svc: authSvc, Wechat: wechatSvc, Log: logger})
	if err != nil {
		logger.Error("Handler 装配失败", zap.Error(err))
		os.Exit(1)
	}
	authMw, err := handler.NewAuth(handler.AuthConfig{PublicKeys: pubKeys, Revocation: revocation, Issuer: cfg.Auth.Issuer})
	if err != nil {
		logger.Error("验签中间件装配失败", zap.Error(err))
		os.Exit(1)
	}

	// ---- org 模块装配（T6：机构/校区只读 + 作用域越权拦截）----
	orgSvc, err := orgservice.NewOrgService(gdb)
	if err != nil {
		logger.Error("OrgService 装配失败", zap.Error(err))
		os.Exit(1)
	}
	orgH, err := orghandler.New(orghandler.Config{Svc: orgSvc})
	if err != nil {
		logger.Error("org Handler 装配失败", zap.Error(err))
		os.Exit(1)
	}
	// RBAC 矩阵配置服务 + handler（T6.5-e 超管可配置后台；平台级，不走 scoping）
	// 保存成功后经 rbacResolver.Invalidate() 清本实例缓存（跨实例靠 TTL 30s 自然一致）。
	rbacSvc, err := orgservice.NewRolePermissionService(gdb, orgrepo.NewPermissionRepo(gdb), rbacResolver)
	if err != nil {
		logger.Error("RBAC 矩阵配置服务装配失败", zap.Error(err))
		os.Exit(1)
	}
	rbacH, err := orghandler.NewRBAC(orghandler.RBACConfig{Svc: rbacSvc})
	if err != nil {
		logger.Error("RBAC Handler 装配失败", zap.Error(err))
		os.Exit(1)
	}

	// academic 域服务装配（AC-11）：DivideService 的「首次扣费上课记录」端口在此注入 ——
	// 这是 divide_into_log_delete 的 D11「改绑保留分成」分支在生产生效的前提
	// （未注入 → 撤销首扣订单会误走"回滚删除"，把真实分成整组冲掉）。详见 wiring_academic.go。
	academicSvc := newAcademicServices(gdb)
	logger.Info("academic 服务装配完成",
		zap.Bool("divideService", academicSvc.Divide != nil),
		zap.Bool("firstChargedReaderInjected", academicSvc.FirstChargedInjected))

	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）----
	// 公开（无需登录态）：两步登录①② + refresh 轮换 + 微信（PC 扫码二维码/状态轮询、移动 webview 授权、回调）
	app.Post("/auth/login", authH.Login)
	app.Post("/auth/issue", authH.Issue)
	app.Post("/auth/refresh", authH.Refresh)
	app.Get("/auth/wechat/qrcode", authH.WechatQrcode)
	app.Get("/auth/wechat/authorize", authH.WechatAuthorize)
	app.Get("/auth/wechat/status", authH.WechatStatus)
	app.Get("/auth/wechat/callback", authH.WechatCallback)

	// 受保护（前置验签中间件：验签 + 作用域注入）
	auth := app.Group("/auth")
	auth.Use(authMw)
	auth.Get("/me", authH.Me)
	auth.Post("/logout", authH.Logout)

	// org 域（机构/校区只读 + 作用域越权拦截，经同一验签中间件；作用域由中间件注入，
	// Repository Scoping 强制机构/校区过滤——跨校区越权防线，架构规格 §3.5）
	// 路由角色白名单（T6.5-d 接口强制层）：机构/校区目录对 staff 角色开放
	// （academic 教务 / finance 财务 / teacher 老师），业务级 student/parent 拒绝（1003），
	// 超管经 SuperAdmin 恒放行。与 e2e TestOrgE2E_RouteRoleWhitelist 白名单一致。
	org := app.Group("/org")
	org.Use(authMw)
	org.Use(handler.RequireRole("academic", "finance", "teacher"))
	org.Get("/institutions", orgH.Institutions)
	org.Get("/institutions/:institutionId", orgH.Institution)
	org.Get("/campuses", orgH.Campuses)
	org.Get("/campuses/:campusId", orgH.Campus)

	// RBAC 矩阵配置（T6.5-e 超管可配置后台）：平台级，不走 scoping；独立兄弟组，仅超管可读写。
	// 与上面的 /org 组并列（不继承其 staff 白名单），自带 authMw + RequireRole("super_admin")：
	// 超管经 SuperAdmin 恒放行；其他任何角色（含 academic/finance/teacher）在子组白名单处被 1003。
	rbacCfg := app.Group("/org/role-permissions")
	rbacCfg.Use(authMw)
	rbacCfg.Use(handler.RequireRole("super_admin"))
	rbacCfg.Get("/:roleCode", rbacH.RolePermissions)
	rbacCfg.Put("/:roleCode", rbacH.SaveRolePermissions)

	// academic 域路由接线（AC-14 第一批：财务 16 + 账单/仪表盘 2 + 活动 16 + 分账 6 = 40 个端点）。
	// 端点清单、注册顺序（静态段先于 `:id`）、角色白名单全部收在
	// `internal/academic/handler/route.go` 的注册表里；本处**只调用一个注册函数**。
	// 注册函数内当场跑两条运行期断言：① 全局 `method+path` 唯一（Fiber 对重复注册是
	// "先注册优先、后者静默失效"）；② academic 一级段 ⊆ {/admin,/student,/pay}。
	// 任一断言失败 → 进程起不来（这类缺陷在运行期不可见、只能靠启动期 fail-fast 暴露）。
	if err := registerAcademicRoutes(app, gdb, authMw, logger); err != nil {
		logger.Error("academic 路由挂载失败", zap.Error(err))
		os.Exit(1)
	}

	// 其余域（teaching/ai）路由挂载点（域模块实现后在此注册）：
	//
	//	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()
}