docs(gateway): gateway 剩余文件注释改中文(逐行 1:1,代码零字节改动)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

主人 2026-10-03 拍板「注释一律中文」;gateway 至此整包注释中文化完成(本会话共 3 批:
已推库 16 个文件 + 本批剩余文件)。
校验:机械校验(非注释改动行)= 空;剥注释后代码文本逐行比对全等(不一致文件数 0);
全树 go test ./... 58 包 ok / 0 FAIL;交叉编译绿。
This commit is contained in:
AskaEth committed 2026-10-03 22:28:25 +08:00
1 parent 91e8d7a029
commit 074ffc4ebf
73 files changed
+2529 -2529

No files matched your search

@@ -9,7 +9,7 @@ import (
"time"
)
// AuditRecord is one persisted admin audit entry (who/what/when/result).
// AuditRecord 是一条持久化的管理审计条目(who/what/when/result)。
type AuditRecord struct {
ID int64 `json:"id"`
Who string `json:"who"`
@@ -18,33 +18,33 @@ type AuditRecord struct {
Result string `json:"result"`
}
// AuditStore persists the admin audit trail. Implementations must be safe for
// concurrent use. *SQLiteAuditStore is the production implementation (wired by the
// composition root over a.db); when none is injected the gateway falls back to an
// in-memory store so the endpoint always returns data.
// AuditStore 持久化管理审计链。实现必须对
// 并发使用安全。*SQLiteAuditStore 是生产实现(由
// 组合根接到 a.db 上);未注入任何实现时网关回退到
// 内存存储,因此端点总能返回数据。
type AuditStore interface {
// Append persists one audit entry at ts.
// Append 在 ts 持久化一条审计条目。
Append(ctx context.Context, who, what, result string, ts time.Time) error
// List returns at most limit most-recent entries, newest first. A non-positive
// limit selects the default.
// List 返回至多 limit 条最近条目,最新优先。非正的
// limit 选用默认值。
List(ctx context.Context, limit int) ([]AuditRecord, error)
}
// memoryAuditStore is the nil-injection fallback: it holds the audit trail in
// process memory so the admin endpoint works before the composition root injects a
// SQLite store. It is concurrency-safe.
// memoryAuditStore 是未注入时的回退:它把审计链放在
// 进程内存中,使管理端点在组合根注入 SQLite 存储
// 之前也能工作。它对并发安全。
type memoryAuditStore struct {
mu sync.Mutex
records []AuditRecord
seq int64
}
// newMemoryAuditStore builds an empty in-memory audit store.
// newMemoryAuditStore 构建一个空的内存审计存储。
func newMemoryAuditStore() *memoryAuditStore {
return &memoryAuditStore{records: make([]AuditRecord, 0, 64)}
}
// Append stores one entry with a monotonically increasing id.
// Append 用单调递增的 id 存一条条目。
func (m *memoryAuditStore) Append(ctx context.Context, who, what, result string, ts time.Time) error {
if err := ctx.Err(); err != nil {
return err
@@ -58,7 +58,7 @@ func (m *memoryAuditStore) Append(ctx context.Context, who, what, result string,
return nil
}
// List returns the most recent entries, newest first.
// List 返回最近的条目,最新优先。
func (m *memoryAuditStore) List(ctx context.Context, limit int) ([]AuditRecord, error) {
if err := ctx.Err(); err != nil {
return nil, err
@@ -84,9 +84,9 @@ func (m *memoryAuditStore) List(ctx context.Context, limit int) ([]AuditRecord,
return out, nil
}
// audit DDL for a self-contained SQLite store (no migration bookkeeping), the
// same pattern channel/session and backthink use. recorded_at is the UTC RFC3339
// wall-clock of the audited action.
// 自包含 SQLite 存储的审计 DDL(无需迁移记账),与
// channel/session 与 backthink 所用模式相同。recorded_at 是被审计
// 动作的 UTC RFC3339 墙钟时间。
const (
createAuditSQL = `
CREATE TABLE IF NOT EXISTS audit_logs (
@@ -102,16 +102,16 @@ CREATE TABLE IF NOT EXISTS audit_logs (
selectAuditSQL = `SELECT id, who, what, result, recorded_at FROM audit_logs ORDER BY id DESC LIMIT ?`
)
// SQLiteAuditStore persists the admin audit trail in SQLite. It is safe for
// concurrent use by virtue of the underlying *sql.DB.
// SQLiteAuditStore 把管理审计链持久化在 SQLite 中。凭借底层的
// *sql.DB,它对并发使用安全。
type SQLiteAuditStore struct {
db *sql.DB
log *slog.Logger
}
// NewSQLiteAuditStore builds a SQLite-backed audit store over db, guaranteeing the
// audit_logs table and index exist. It returns an error when db is nil or the DDL
// fails. The composition root wires this over the primary *sql.DB (a.db).
// NewSQLiteAuditStore 在 db 上构建 SQLite 审计存储,保证
// audit_logs 表与索引存在。db 为 nil 或 DDL 失败时
// 返回错误。组合根把它接到主 *sql.DB(a.db)上。
func NewSQLiteAuditStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*SQLiteAuditStore, error) {
if db == nil {
return nil, fmt.Errorf("gateway: audit store: nil database")
@@ -125,7 +125,7 @@ func NewSQLiteAuditStore(ctx context.Context, db *sql.DB, log *slog.Logger) (*SQ
return &SQLiteAuditStore{db: db, log: sourcedLog(log)}, nil
}
// Append persists one audit entry at ts.
// Append 在 ts 持久化一条审计条目。
func (s *SQLiteAuditStore) Append(ctx context.Context, who, what, result string, ts time.Time) error {
if _, err := s.db.ExecContext(ctx, insertAuditSQL, who, what, result, ts.UTC().Format(time.RFC3339Nano)); err != nil {
return fmt.Errorf("gateway: insert audit: %w", err)
@@ -133,7 +133,7 @@ func (s *SQLiteAuditStore) Append(ctx context.Context, who, what, result string,
return nil
}
// List returns the most recent entries, newest first.
// List 返回最近的条目,最新优先。
func (s *SQLiteAuditStore) List(ctx context.Context, limit int) ([]AuditRecord, error) {
if limit <= 0 {
limit = defaultObsLimit