AskaEth
e5e0944d26
## 日志（用户要求：分级 + 每个拦截都要有指出代码行的调试日志 + 两类文件）
- 新增 internal/logging：拦截点捕获（file:line + 函数名，相对路径）、两类文件轮转、
按级别/类别分流。httpapi 与 middleware 各自薄封装，无循环依赖。
- 两类目录（数据目录下）：
operations/ 放行类（INFO「操作已放行」+ 常规运行日志，按 log.level）
interceptions/ 拦截类（WARN 中文原因 + 拦截点 + method/path/actor/role/requestId、
DEBUG 上下文、ERROR 服务端异常）—— **固定 debug 采集**，
否则默认 info 下"每次拦截的调试日志"根本看不见
- 命名 operations-YYYYMMDD[.N].log，按天+按大小轮转，每类保留 keepFiles 份；写盘失败
降级只写控制台且只 Warn 一次。
- 所有业务错误统一走 newAPIError 捕获拦截点（11 处内联 &apiError{} 已收进构造函数，
防止绕过）；中间件层拦截（401/403/CSRF/未改初始密码/429）也留痕，响应体与状态码一字未变。
- config.yaml 的 log 段新增 dir / maxSizeMB / keepFiles（留空即默认）。
- 服务端包数 12 → 13（新增 internal/logging）。
## 成绩录入（用户实机踩坑）
- 真因一：成绩格 placeholder 是光秃秃的 `1:06.33`，而全仓库没有任何 ::placeholder 样式，
示例文本与真实输入长得一样 → 用户把灰字当成已填内容，那 13 格其实是空的。
- 真因二：2 条报错是秒位 ≥ 60（1:70）或全角冒号（1：06）；1:06 与 1:06.00 在解析器里
本来就等价（都 = 66），格式不是问题。
- 真因三：成绩格没有宽度定义（旁边名次 72px、状态 110px 都有），被挤到第 4 位数字看不见。
修复：parseSecondsDetail 区分 empty/seconds-overflow/unrecognized；新增 entryGuards.ts
纯函数（录入页与审核页共用），报错**打出那一格的实际内容**并说明原因；解析器新认全角
冒号/全角数字/1分06秒 等写法；成绩格 min-width 112px（按 fontTools 实测文本宽度定）；
示例文本改 `例 1:06.33` 等并给录入表格内的 ::placeholder 加淡色斜体；新增
onBeforeRouteLeave 离开守卫（原来切菜单会静默丢未保存成绩）。
测试：服务端 13 包全绿（372 个测试函数）；前端 vue-tsc 通过、205 例全过；Console 18 文件。
docs/ 与 devdocs/ 同步（FAQ 到 Q76，部署指南新增第 10 节「服务端日志与拦截复盘」）。
311 lines
13 KiB
Go
311 lines
13 KiB
Go
// Package httpapi 提供 REST 接口、静态资源托管与统一响应结构。
|
||
package httpapi
|
||
|
||
import (
|
||
"database/sql"
|
||
"io/fs"
|
||
"log/slog"
|
||
"net/http"
|
||
"path/filepath"
|
||
"strings"
|
||
"time"
|
||
|
||
"git.yeij.top/AskaEth/Scoreboard/server/internal/auth"
|
||
"git.yeij.top/AskaEth/Scoreboard/server/internal/export"
|
||
"git.yeij.top/AskaEth/Scoreboard/server/internal/middleware"
|
||
"git.yeij.top/AskaEth/Scoreboard/server/internal/webui"
|
||
)
|
||
|
||
// DisplaySender 把大屏控制命令推给实时层；未接入时命令只记审计、不影响接口可用性。
|
||
type DisplaySender interface {
|
||
// SendDisplayCommand 下发一条大屏指令。targets 为空表示广播给所有大屏（公告靠它），
|
||
// 否则只发给这些实例 id（GET /api/display/instances 里的 id），并返回命中的实例数。
|
||
SendDisplayCommand(action string, payload any, targets []string) (matched int, err error)
|
||
}
|
||
|
||
// Options 是构建路由所需的依赖。
|
||
type Options struct {
|
||
Logger *slog.Logger
|
||
Version string
|
||
// System 是系统库连接（users/sessions）。
|
||
System *sql.DB
|
||
// Event 是赛事库连接（teams/events/results/ledger/audit…）。
|
||
Event *sql.DB
|
||
// Auth 可选；为空时用 System 自动构建。
|
||
Auth *auth.Service
|
||
// DataDir 用于备份目录 data/backups。
|
||
DataDir string
|
||
// Backup 可选，手动/发布前备份共用的服务；为空时按 System/Event/DataDir 自动构建。
|
||
Backup *export.Service
|
||
// Shutdown 可选，由 main 注入：触发与 SIGINT/SIGTERM 相同的优雅关闭流程。
|
||
// 为空时 POST /api/shutdown 返回 503，避免把「没接关闭」误报成已受理。
|
||
Shutdown func()
|
||
// Display 可选，实时层接入后传入。
|
||
Display DisplaySender
|
||
// Realtime 可选，实时层接入后传入：写事务提交后推送变更，并提供在线大屏实例。
|
||
Realtime Realtime
|
||
// WS 可选，实时层的 WebSocket 处理器，挂到 /ws。
|
||
WS http.Handler
|
||
// ProjectDir 可选，当前赛事项目目录（含 uploads/），用于赛事包导出。
|
||
ProjectDir string
|
||
// WebFS 可选，默认使用内嵌前端资源。
|
||
WebFS fs.FS
|
||
}
|
||
|
||
type server struct {
|
||
logger *slog.Logger
|
||
version string
|
||
sys *sql.DB
|
||
ev *sql.DB
|
||
auth *auth.Service
|
||
dataDir string
|
||
projectDir string
|
||
backups *export.Service
|
||
shutdown func()
|
||
display DisplaySender
|
||
realtime Realtime
|
||
idem *idempotencyStore
|
||
}
|
||
|
||
// New 组装并返回服务端的 HTTP 处理器。
|
||
func New(opts Options) http.Handler {
|
||
logger := opts.Logger
|
||
if logger == nil {
|
||
logger = slog.Default()
|
||
}
|
||
svc := opts.Auth
|
||
if svc == nil {
|
||
svc = auth.New(opts.System, auth.Options{Logger: logger})
|
||
}
|
||
backups := opts.Backup
|
||
if backups == nil {
|
||
dir := ""
|
||
if strings.TrimSpace(opts.DataDir) != "" {
|
||
dir = filepath.Join(opts.DataDir, "backups")
|
||
}
|
||
backups = export.NewService(opts.System, opts.Event, dir, 0, logger)
|
||
}
|
||
|
||
s := &server{
|
||
logger: logger,
|
||
version: opts.Version,
|
||
sys: opts.System,
|
||
ev: opts.Event,
|
||
auth: svc,
|
||
dataDir: opts.DataDir,
|
||
projectDir: opts.ProjectDir,
|
||
backups: backups,
|
||
shutdown: opts.Shutdown,
|
||
display: opts.Display,
|
||
realtime: opts.Realtime,
|
||
idem: newIdempotencyStore(10 * time.Minute),
|
||
}
|
||
|
||
mux := http.NewServeMux()
|
||
s.routes(mux)
|
||
s.exportRoutes(mux)
|
||
s.projectRoutes(mux)
|
||
s.rulesRoutes(mux)
|
||
s.systemRoutes(mux)
|
||
if opts.WS != nil {
|
||
mux.Handle("/ws", opts.WS)
|
||
}
|
||
|
||
assets := opts.WebFS
|
||
if assets == nil {
|
||
var err error
|
||
assets, err = webui.FS()
|
||
if err != nil {
|
||
logger.Error("前端资源不可用", "err", err)
|
||
}
|
||
}
|
||
if assets != nil {
|
||
mux.Handle("/", staticHandler(assets))
|
||
}
|
||
|
||
var h http.Handler = mux
|
||
h = s.broadcastChanges(h)
|
||
h = middleware.NewAuditor(opts.Event, logger).Middleware(h)
|
||
h = middleware.RateLimitWrite(svc, logger)(h)
|
||
h = middleware.CSRF(logger, h)
|
||
h = middleware.MustChangePassword(logger, h)
|
||
h = middleware.Authenticate(svc, logger)(h)
|
||
h = middleware.Log(logger)(h)
|
||
h = middleware.Recover(logger)(h)
|
||
h = middleware.RequestID(h)
|
||
return h
|
||
}
|
||
|
||
func middlewareUserID(r *http.Request) int64 {
|
||
u := middleware.User(r.Context())
|
||
if u.Role == auth.RoleGuest {
|
||
return 0
|
||
}
|
||
return u.ID
|
||
}
|
||
|
||
// public 注册公开接口（guest 可读）。
|
||
func (s *server) public(fn handler) http.HandlerFunc { return s.handle(fn) }
|
||
|
||
// read 注册「guest 也不可读」的接口，权限不足一律 403。
|
||
func (s *server) read(role auth.Role, fn handler) http.HandlerFunc {
|
||
return middleware.RequireRole(s.logger, role)(s.handle(fn)).ServeHTTP
|
||
}
|
||
|
||
// write 注册写接口：未登录 401，角色不足 403；成功后按 X-Request-Id 支持幂等回放。
|
||
func (s *server) write(role auth.Role, fn handler) http.HandlerFunc {
|
||
return middleware.RequireWrite(s.logger, role)(s.cached(s.handle(fn))).ServeHTTP
|
||
}
|
||
|
||
// writeVoid 注册无返回体的写接口。
|
||
func (s *server) writeVoid(role auth.Role, fn func(w http.ResponseWriter, r *http.Request) error) http.HandlerFunc {
|
||
return middleware.RequireWrite(s.logger, role)(s.cached(s.handleVoid(fn))).ServeHTTP
|
||
}
|
||
|
||
func (s *server) routes(mux *http.ServeMux) {
|
||
// 健康检查不走 {ok,data} 包装（05 第 7 节）。
|
||
mux.HandleFunc("GET /api/health", func(w http.ResponseWriter, r *http.Request) {
|
||
writeJSON(w, http.StatusOK, map[string]any{"ok": true, "version": s.version})
|
||
})
|
||
|
||
// 认证
|
||
mux.HandleFunc("POST /api/auth/login", s.handle(s.login))
|
||
mux.HandleFunc("POST /api/auth/logout", s.handle(s.logout))
|
||
mux.HandleFunc("GET /api/auth/me", s.handle(s.me))
|
||
mux.HandleFunc("POST /api/auth/password", s.handle(s.changePassword))
|
||
|
||
// 系统配置（guest 一律 403）
|
||
mux.HandleFunc("GET /api/settings", s.read(auth.RoleAdmin, s.getSettingsHandler))
|
||
mux.HandleFunc("PUT /api/settings", s.write(auth.RoleAdmin, s.updateSettingsHandler))
|
||
|
||
// 基础配置
|
||
mux.HandleFunc("GET /api/teams", s.public(s.listTeamsHandler))
|
||
mux.HandleFunc("POST /api/teams", s.write(auth.RoleRecorder, s.createTeamHandler))
|
||
mux.HandleFunc("GET /api/teams/{id}", s.public(s.getTeamHandler))
|
||
mux.HandleFunc("PUT /api/teams/{id}", s.write(auth.RoleRecorder, s.updateTeamHandler))
|
||
mux.HandleFunc("DELETE /api/teams/{id}", s.writeVoid(auth.RoleRecorder, s.deleteTeamHandler))
|
||
|
||
mux.HandleFunc("GET /api/sports", s.public(s.listSportsHandler))
|
||
mux.HandleFunc("POST /api/sports", s.write(auth.RoleRecorder, s.createSportHandler))
|
||
mux.HandleFunc("GET /api/sports/{id}", s.public(s.getSportHandler))
|
||
mux.HandleFunc("PUT /api/sports/{id}", s.write(auth.RoleRecorder, s.updateSportHandler))
|
||
mux.HandleFunc("DELETE /api/sports/{id}", s.writeVoid(auth.RoleRecorder, s.deleteSportHandler))
|
||
|
||
mux.HandleFunc("GET /api/events", s.public(s.listEventsHandler))
|
||
mux.HandleFunc("POST /api/events", s.write(auth.RoleRecorder, s.createEventHandler))
|
||
mux.HandleFunc("GET /api/events/{id}", s.public(s.getEventHandler))
|
||
mux.HandleFunc("PUT /api/events/{id}", s.write(auth.RoleRecorder, s.updateEventHandler))
|
||
mux.HandleFunc("DELETE /api/events/{id}", s.writeVoid(auth.RoleRecorder, s.deleteEventHandler))
|
||
mux.HandleFunc("GET /api/events/{id}/entries", s.public(s.listEntriesHandler))
|
||
mux.HandleFunc("GET /api/events/{id}/categories", s.public(s.listCategoriesHandler))
|
||
mux.HandleFunc("PUT /api/events/{id}/categories", s.write(auth.RoleRecorder, s.replaceCategoriesHandler))
|
||
mux.HandleFunc("GET /api/events/{id}/channels", s.public(s.listChannelsHandler))
|
||
mux.HandleFunc("PUT /api/events/{id}/channels", s.write(auth.RoleRecorder, s.replaceChannelsHandler))
|
||
|
||
mux.HandleFunc("GET /api/scoring-profiles", s.public(s.listProfilesHandler))
|
||
mux.HandleFunc("POST /api/scoring-profiles", s.write(auth.RoleRecorder, s.createProfileHandler))
|
||
mux.HandleFunc("GET /api/scoring-profiles/{id}", s.public(s.getProfileHandler))
|
||
mux.HandleFunc("PUT /api/scoring-profiles/{id}", s.write(auth.RoleRecorder, s.updateProfileHandler))
|
||
|
||
mux.HandleFunc("GET /api/athletes", s.public(s.listAthletesHandler))
|
||
mux.HandleFunc("POST /api/athletes", s.write(auth.RoleRecorder, s.createAthleteHandler))
|
||
mux.HandleFunc("GET /api/athletes/{id}", s.public(s.getAthleteHandler))
|
||
mux.HandleFunc("PUT /api/athletes/{id}", s.write(auth.RoleRecorder, s.updateAthleteHandler))
|
||
mux.HandleFunc("DELETE /api/athletes/{id}", s.write(auth.RoleRecorder, s.deleteAthleteHandler))
|
||
|
||
mux.HandleFunc("POST /api/entries/import", s.write(auth.RoleRecorder, s.importEntriesHandler))
|
||
mux.HandleFunc("POST /api/entries/import/resolve", s.write(auth.RoleRecorder, s.resolveImportHandler))
|
||
|
||
// 成绩
|
||
mux.HandleFunc("GET /api/results", s.public(s.listResultsHandler))
|
||
mux.HandleFunc("PUT /api/results/draft", s.write(auth.RoleRecorder, s.saveDraftHandler))
|
||
mux.HandleFunc("POST /api/results/publish", s.write(auth.RoleRecorder, s.publishHandler))
|
||
mux.HandleFunc("POST /api/results/unpublish", s.write(auth.RoleRecorder, s.unpublishHandler))
|
||
mux.HandleFunc("POST /api/results/{id}/void", s.write(auth.RoleRecorder, s.voidResultHandler))
|
||
|
||
// 积分与排名
|
||
mux.HandleFunc("GET /api/standings", s.public(s.standingsHandler))
|
||
mux.HandleFunc("GET /api/standings/athletes", s.public(s.athleteStandingsHandler))
|
||
mux.HandleFunc("GET /api/standings/teams/{id}/breakdown", s.public(s.breakdownHandler))
|
||
mux.HandleFunc("GET /api/adjustments", s.public(s.listAdjustmentsHandler))
|
||
mux.HandleFunc("POST /api/adjustments", s.write(auth.RoleRecorder, s.createAdjustmentHandler))
|
||
mux.HandleFunc("POST /api/adjustments/{id}/void", s.write(auth.RoleRecorder, s.voidAdjustmentHandler))
|
||
|
||
// 纪录
|
||
mux.HandleFunc("GET /api/records", s.public(s.listRecordsHandler))
|
||
mux.HandleFunc("POST /api/record-breaks", s.write(auth.RoleRecorder, s.createRecordBreakHandler))
|
||
mux.HandleFunc("POST /api/record-breaks/{id}/approve", s.write(auth.RoleRecorder, s.approveRecordBreakHandler))
|
||
|
||
// 大屏控制与运维
|
||
mux.HandleFunc("POST /api/display/command", s.write(auth.RoleRecorder, s.displayCommandHandler))
|
||
mux.HandleFunc("GET /api/display/instances", s.read(auth.RoleRecorder, s.displayInstancesHandler))
|
||
mux.HandleFunc("GET /api/audit-logs", s.read(auth.RoleAdmin, s.listAuditLogsHandler))
|
||
mux.HandleFunc("POST /api/backup", s.write(auth.RoleAdmin, s.backupHandler))
|
||
|
||
// 用户管理（系统配置，仅 admin；guest 读 403、写 401）
|
||
mux.HandleFunc("GET /api/users", s.read(auth.RoleAdmin, s.listUsersHandler))
|
||
mux.HandleFunc("POST /api/users", s.write(auth.RoleAdmin, s.createUserHandler))
|
||
mux.HandleFunc("PUT /api/users/{id}", s.write(auth.RoleAdmin, s.updateUserHandler))
|
||
mux.HandleFunc("POST /api/users/{id}/password", s.write(auth.RoleAdmin, s.resetUserPasswordHandler))
|
||
|
||
// 变更历史（recorder 及以上可读）
|
||
mux.HandleFunc("GET /api/revisions", s.read(auth.RoleRecorder, s.listRevisionsHandler))
|
||
mux.HandleFunc("GET /api/revisions/{id}", s.read(auth.RoleRecorder, s.getRevisionDetailHandler))
|
||
|
||
// 图片上传与静态访问（会标/背景/单位图标）。上传落 <ProjectDir>/uploads/，随赛事包导出；
|
||
// 静态访问要匿名放行，大屏的 <img> 才能不带会话直接取图。
|
||
mux.HandleFunc("POST /api/uploads", s.write(auth.RoleRecorder, s.uploadHandler))
|
||
mux.HandleFunc("GET /uploads/{name}", s.serveUpload)
|
||
|
||
// 字体：4 款内置字体（前端 @font-face）由 GET /api/fonts 列出，上传的落
|
||
// <项目目录>/uploads/fonts/，随赛事包导出；静态访问同样是匿名放行——大屏的
|
||
// @font-face 不带会话。字体目录比图片多一层，静态路由必须单独注册。
|
||
mux.HandleFunc("GET /api/fonts", s.read(auth.RoleRecorder, s.listFontsHandler))
|
||
mux.HandleFunc("POST /api/fonts", s.write(auth.RoleAdmin, s.uploadFontHandler))
|
||
mux.HandleFunc("DELETE /api/fonts/{name}", s.writeVoid(auth.RoleAdmin, s.deleteFontHandler))
|
||
mux.HandleFunc("GET /uploads/fonts/{name}", s.serveFont)
|
||
|
||
// 由其他模块负责的接口：先占位，避免落到静态资源处理器。
|
||
mux.HandleFunc("/api/export/", s.notWired("导出"))
|
||
mux.HandleFunc("/api/rules/", s.notWired("规则导入导出"))
|
||
mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
|
||
s.writeAPIError(w, r, notFound("接口不存在"))
|
||
})
|
||
}
|
||
|
||
// notWired 为待接线的接口返回 501，避免请求被静态资源兜底成 HTML。
|
||
func (s *server) notWired(name string) http.HandlerFunc {
|
||
return func(w http.ResponseWriter, r *http.Request) {
|
||
s.writeAPIError(w, r, notImplemented(name+"接口尚未接入"))
|
||
}
|
||
}
|
||
|
||
// staticHandler 把 URL 映射到多页面前端产物。
|
||
//
|
||
// / → index.html
|
||
// /display → display.html
|
||
// /admin → admin.html
|
||
// /其他 → 按文件路径查找
|
||
func staticHandler(assets fs.FS) http.Handler {
|
||
files := http.FileServerFS(assets)
|
||
|
||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||
p := strings.TrimPrefix(r.URL.Path, "/")
|
||
|
||
switch p {
|
||
case "", "index.html":
|
||
http.ServeFileFS(w, r, assets, "index.html")
|
||
case "display", "display/":
|
||
http.ServeFileFS(w, r, assets, "display.html")
|
||
case "admin", "admin/":
|
||
http.ServeFileFS(w, r, assets, "admin.html")
|
||
default:
|
||
if _, err := fs.Stat(assets, p); err != nil {
|
||
http.NotFound(w, r)
|
||
return
|
||
}
|
||
files.ServeHTTP(w, r)
|
||
}
|
||
})
|
||
}
|