From b05d26c9c6bd2d285161d0a5909a336555bef6b6 Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Tue, 9 Jun 2026 13:42:06 +0800
Subject: [PATCH] docs: add package and exported symbol comments for revive
 lint compliance

---
 internal/apps/admin/auth_source/routers.go |  3 +++
 internal/apps/admin/errs.go                |  2 ++
 internal/apps/admin/middlewares.go         |  1 +
 internal/apps/admin/system_config/errs.go  |  2 ++
 internal/apps/admin/task/errs.go           |  2 ++
 internal/apps/admin/template/errs.go       |  2 ++
 internal/apps/admin/user/errs.go           |  1 +
 internal/apps/cap/errs.go                  |  1 +
 internal/apps/health/routers.go            |  1 +
 internal/apps/oauth/audit.go               |  2 ++
 internal/apps/oauth/constants.go           |  3 +++
 internal/apps/oauth/errs.go                |  1 +
 internal/apps/risk_control/middleware.go   |  1 +
 internal/apps/upload/errs.go               |  2 ++
 internal/common/constants.go               |  1 +
 internal/common/errs.go                    |  2 ++
 internal/db/idgen/snowflake.go             |  2 ++
 internal/db/postgres.go                    |  1 +
 internal/db/redis.go                       |  1 +
 internal/logger/errs.go                    |  1 +
 internal/model/auth_source.go              | 19 +++++++++++++++++++
 internal/model/system_configs.go           |  1 +
 internal/model/task_execution.go           |  1 +
 internal/model/templates.go                |  4 ++++
 internal/model/uploads.go                  |  1 +
 internal/otel_trace/propagator.go          |  1 +
 internal/otel_trace/trace.go               |  3 +++
 internal/storage/errs.go                   |  3 +++
 internal/storage/s3.go                     |  2 ++
 internal/task/handler.go                   |  3 +++
 internal/task/handlers/register.go         |  1 +
 internal/task/scheduler/errs.go            |  1 +
 internal/task/worker/middlewares.go        |  1 +
 internal/testhelper/test_helper.go         |  1 +
 internal/util/cap/prng.go                  |  6 ++++++
 internal/util/context.go                   |  1 +
 internal/util/custom_types.go              |  2 ++
 internal/util/mail/errs.go                 |  1 +
 internal/util/password.go                  |  2 ++
 main.go                                    |  1 +
 40 files changed, 87 insertions(+)

diff --git a/internal/apps/admin/auth_source/routers.go b/internal/apps/admin/auth_source/routers.go
index 57a71d61..a00966b3 100644
--- a/internal/apps/admin/auth_source/routers.go
+++ b/internal/apps/admin/auth_source/routers.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package auth_source 提供认证源管理功能
 package auth_source
 
 import (
@@ -27,6 +28,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// AuthSourceRequest 创建或更新认证源的请求参数
 type AuthSourceRequest struct {
 	Name               string `json:"name"`
 	Type               string `json:"type"`
@@ -39,6 +41,7 @@ type AuthSourceRequest struct {
 	IconURL            string `json:"icon_url"`
 }
 
+// ToggleAuthSourceRequest 切换认证源启用状态的请求参数
 type ToggleAuthSourceRequest struct {
 	IsActive bool `json:"is_active"`
 }
diff --git a/internal/apps/admin/errs.go b/internal/apps/admin/errs.go
index 15c9668f..cf4db141 100644
--- a/internal/apps/admin/errs.go
+++ b/internal/apps/admin/errs.go
@@ -15,8 +15,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package admin 提供管理后台功能
 package admin
 
+// 管理后台错误消息常量
 const (
 	AdminRequired          = "未经授权访问"
 	InvalidAuthSourceID    = "认证源 ID 无效"
diff --git a/internal/apps/admin/middlewares.go b/internal/apps/admin/middlewares.go
index 2b1e946a..62f88540 100644
--- a/internal/apps/admin/middlewares.go
+++ b/internal/apps/admin/middlewares.go
@@ -29,6 +29,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// LoginAdminRequired 返回管理员权限校验中间件
 func LoginAdminRequired() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		// init trace
diff --git a/internal/apps/admin/system_config/errs.go b/internal/apps/admin/system_config/errs.go
index a2ab435d..9b7b5446 100644
--- a/internal/apps/admin/system_config/errs.go
+++ b/internal/apps/admin/system_config/errs.go
@@ -15,8 +15,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package system_config 提供系统配置管理功能
 package system_config
 
+// 系统配置错误消息常量
 const (
 	SystemConfigNotFound = "系统配置不存在"
 	ConfigKeyRequired    = "配置键不能为空"
diff --git a/internal/apps/admin/task/errs.go b/internal/apps/admin/task/errs.go
index aa58db5e..03094ca0 100644
--- a/internal/apps/admin/task/errs.go
+++ b/internal/apps/admin/task/errs.go
@@ -15,8 +15,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package task 提供任务管理接口
 package task
 
+// 任务管理相关错误消息
 const (
 	InvalidTaskType      = "无效的任务类型"
 	InvalidTimeRange     = "无效的时间范围"
diff --git a/internal/apps/admin/template/errs.go b/internal/apps/admin/template/errs.go
index ba4ceeca..5ff787fa 100644
--- a/internal/apps/admin/template/errs.go
+++ b/internal/apps/admin/template/errs.go
@@ -14,8 +14,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package template 提供模板管理功能
 package template
 
+// 模板管理相关错误消息
 const (
 	TemplateNotFound              = "模板不存在"
 	TemplateKeyRequired           = "模板标识符不能为空"
diff --git a/internal/apps/admin/user/errs.go b/internal/apps/admin/user/errs.go
index de42bd7c..b49ec5ce 100644
--- a/internal/apps/admin/user/errs.go
+++ b/internal/apps/admin/user/errs.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package user 提供用户管理功能
 package user
 
 const (
diff --git a/internal/apps/cap/errs.go b/internal/apps/cap/errs.go
index 8a521e14..2a52506a 100644
--- a/internal/apps/cap/errs.go
+++ b/internal/apps/cap/errs.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package cap 提供人机验证中间件
 package cap
 
 const (
diff --git a/internal/apps/health/routers.go b/internal/apps/health/routers.go
index c8870f38..abe131ed 100644
--- a/internal/apps/health/routers.go
+++ b/internal/apps/health/routers.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package health 提供健康检查端点
 package health
 
 import (
diff --git a/internal/apps/oauth/audit.go b/internal/apps/oauth/audit.go
index f67649ee..1df2e2f9 100644
--- a/internal/apps/oauth/audit.go
+++ b/internal/apps/oauth/audit.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package oauth 提供 OAuth/OIDC 认证与会话管理
 package oauth
 
 import (
@@ -26,6 +27,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// LogForAudit 将登录鉴权审计日志写入 Logger
 func LogForAudit(ctx context.Context, user *model.User, c *gin.Context) {
 	auditLog := loginRequiredAuditLog{
 		UserID:     user.ID,
diff --git a/internal/apps/oauth/constants.go b/internal/apps/oauth/constants.go
index 8f586963..4311e6e7 100644
--- a/internal/apps/oauth/constants.go
+++ b/internal/apps/oauth/constants.go
@@ -22,6 +22,7 @@ import (
 	"time"
 )
 
+// Session 用户信息字段 Key
 const (
 	UserNameKey                     = "username"
 	UserIDKey                       = "user_id"
@@ -32,11 +33,13 @@ const (
 	PendingOAuthEmailKey            = "pending_oauth_email"
 )
 
+// OAuth State 缓存 Key 格式与过期时间
 const (
 	OAuthStateCacheKeyFormat     = "oauth:state:%s"
 	OAuthStateCacheKeyExpiration = 10 * time.Minute
 )
 
+// OAuth 授权用途常量
 const (
 	OAuthPurposeLogin = "login"
 	OAuthPurposeBind  = "bind"
diff --git a/internal/apps/oauth/errs.go b/internal/apps/oauth/errs.go
index 690f6a82..d4071f1c 100644
--- a/internal/apps/oauth/errs.go
+++ b/internal/apps/oauth/errs.go
@@ -17,6 +17,7 @@ limitations under the License.
 
 package oauth
 
+// OAuth 认证相关错误消息
 const (
 	InvalidState                    = "非法登录请求"
 	IDTokenVerifyFailed             = "ID Token 验证失败"
diff --git a/internal/apps/risk_control/middleware.go b/internal/apps/risk_control/middleware.go
index 8b75bda1..596f8755 100644
--- a/internal/apps/risk_control/middleware.go
+++ b/internal/apps/risk_control/middleware.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package risk_control 提供风险控制中间件
 package risk_control
 
 import (
diff --git a/internal/apps/upload/errs.go b/internal/apps/upload/errs.go
index 855e1271..4a963fb3 100644
--- a/internal/apps/upload/errs.go
+++ b/internal/apps/upload/errs.go
@@ -15,8 +15,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package upload 提供文件上传与下载功能
 package upload
 
+// 上传模块错误消息常量
 const (
 	ErrNoFileSelected                = "请选择要上传的文件"
 	ErrInvalidUploadType             = "无效的上传类型"
diff --git a/internal/common/constants.go b/internal/common/constants.go
index 2ec5a89c..f614ed37 100644
--- a/internal/common/constants.go
+++ b/internal/common/constants.go
@@ -15,4 +15,5 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package common 提供跨模块共享的常量、错误定义和通用工具函数。
 package common
diff --git a/internal/common/errs.go b/internal/common/errs.go
index 3f15975d..03371302 100644
--- a/internal/common/errs.go
+++ b/internal/common/errs.go
@@ -17,6 +17,7 @@ limitations under the License.
 
 package common
 
+// 通用业务错误消息常量
 const (
 	BannedAccount               = "账号已被封禁"
 	AmountMustBeGreaterThanZero = "金额必须大于0"
@@ -32,6 +33,7 @@ const (
 	UnAuthorized                = "未登录"
 )
 
+// 保护期相关错误消息
 const (
 	GetProtectionDaysFailed = "获取新用户保护期配置失败"
 )
diff --git a/internal/db/idgen/snowflake.go b/internal/db/idgen/snowflake.go
index 640274a7..ddef14c7 100644
--- a/internal/db/idgen/snowflake.go
+++ b/internal/db/idgen/snowflake.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package idgen 提供分布式 ID 生成器
 package idgen
 
 import (
@@ -41,6 +42,7 @@ func init() {
 	log.Printf("[Snowflake] initialized with node ID: %d, epoch: 2025-12-01\n", nodeID)
 }
 
+// NextUint64ID 生成下一个分布式唯一 ID
 func NextUint64ID() uint64 {
 	return uint64(node.Generate().Int64())
 }
diff --git a/internal/db/postgres.go b/internal/db/postgres.go
index 3860c306..954900d8 100644
--- a/internal/db/postgres.go
+++ b/internal/db/postgres.go
@@ -203,6 +203,7 @@ func buildDSN(host string, port int, username, password string) string {
 	return pqURL.String()
 }
 
+// DB 返回带上下文追踪的 GORM 数据库实例
 func DB(ctx context.Context) *gorm.DB {
 	if db == nil {
 		return nil
diff --git a/internal/db/redis.go b/internal/db/redis.go
index 3987f55f..74ddd9a1 100644
--- a/internal/db/redis.go
+++ b/internal/db/redis.go
@@ -32,6 +32,7 @@ import (
 )
 
 var (
+	// Redis 全局 Redis 客户端实例
 	Redis redis.UniversalClient
 )
 
diff --git a/internal/logger/errs.go b/internal/logger/errs.go
index 4b5dc948..075690fb 100644
--- a/internal/logger/errs.go
+++ b/internal/logger/errs.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package logger 提供结构化日志封装
 package logger
 
 const (
diff --git a/internal/model/auth_source.go b/internal/model/auth_source.go
index 836d54d7..3d2a6639 100644
--- a/internal/model/auth_source.go
+++ b/internal/model/auth_source.go
@@ -27,12 +27,14 @@ import (
 	"gorm.io/gorm"
 )
 
+// 认证源类型
 const (
 	AuthSourceTypeOIDC = "oidc"
 )
 
 var authSourceNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$`)
 
+// AuthSource 认证源实体
 type AuthSource struct {
 	ID                     uint64    `json:"id" gorm:"primaryKey"`
 	Name                   string    `json:"name" gorm:"uniqueIndex;size:80;not null"`
@@ -49,6 +51,7 @@ type AuthSource struct {
 	ClientSecretConfigured bool      `json:"client_secret_configured" gorm:"-"`
 }
 
+// ExternalAccount 外部账号绑定实体
 type ExternalAccount struct {
 	ID               uint64    `json:"id" gorm:"primaryKey"`
 	AuthSourceID     uint64    `json:"auth_source_id" gorm:"uniqueIndex:idx_external_accounts_source_external,priority:1;index"`
@@ -60,6 +63,7 @@ type ExternalAccount struct {
 	UpdatedAt        time.Time `json:"updated_at"`
 }
 
+// ExternalAccountView 外部帐号绑定视图（脱敏展示用）
 type ExternalAccountView struct {
 	ID               uint64    `json:"id"`
 	AuthSourceID     uint64    `json:"auth_source_id"`
@@ -71,6 +75,7 @@ type ExternalAccountView struct {
 	CreatedAt        time.Time `json:"created_at"`
 }
 
+// Normalize 对认证源字段进行标准化处理
 func (source *AuthSource) Normalize() {
 	source.Type = strings.ToLower(strings.TrimSpace(source.Type))
 	source.Name = strings.TrimSpace(source.Name)
@@ -88,6 +93,7 @@ func (source *AuthSource) Normalize() {
 	}
 }
 
+// Validate 校验认证源字段合法性
 func (source *AuthSource) Validate() error {
 	source.Normalize()
 	if source.Name == "" {
@@ -108,11 +114,13 @@ func (source *AuthSource) Validate() error {
 	return nil
 }
 
+// Sanitize 脱敏处理，将 ClientSecret 清空并设置 ClientSecretConfigured 标志
 func (source *AuthSource) Sanitize() {
 	source.ClientSecretConfigured = source.ClientSecret != ""
 	source.ClientSecret = ""
 }
 
+// GetAuthSources 获取所有认证源（已脱敏）
 func GetAuthSources() ([]AuthSource, error) {
 	var sources []AuthSource
 	if err := db.DB(context.Background()).Order("id asc").Find(&sources).Error; err != nil {
@@ -124,6 +132,7 @@ func GetAuthSources() ([]AuthSource, error) {
 	return sources, nil
 }
 
+// GetActiveAuthSources 获取所有已启用的认证源（已脱敏）
 func GetActiveAuthSources() ([]AuthSource, error) {
 	var sources []AuthSource
 	if err := db.DB(context.Background()).Where("is_active = ?", true).Order("id asc").Find(&sources).Error; err != nil {
@@ -135,6 +144,7 @@ func GetActiveAuthSources() ([]AuthSource, error) {
 	return sources, nil
 }
 
+// GetAuthSourceByID 根据 ID 获取认证源
 func GetAuthSourceByID(id uint64) (*AuthSource, error) {
 	if id == 0 {
 		return nil, errors.New(errAuthSourceIDRequired)
@@ -147,6 +157,7 @@ func GetAuthSourceByID(id uint64) (*AuthSource, error) {
 	return &source, nil
 }
 
+// GetAuthSourceByName 根据名称获取认证源
 func GetAuthSourceByName(name string) (*AuthSource, error) {
 	name = strings.TrimSpace(name)
 	if name == "" {
@@ -160,6 +171,7 @@ func GetAuthSourceByName(name string) (*AuthSource, error) {
 	return &source, nil
 }
 
+// CreateAuthSource 创建认证源
 func CreateAuthSource(source *AuthSource) error {
 	if err := source.Validate(); err != nil {
 		return err
@@ -167,6 +179,7 @@ func CreateAuthSource(source *AuthSource) error {
 	return db.DB(context.Background()).Create(source).Error
 }
 
+// UpdateAuthSource 更新认证源，keepSecret 为 true 时保留原密钥
 func UpdateAuthSource(source *AuthSource, keepSecret bool) error {
 	if source.ID == 0 {
 		return errors.New(errAuthSourceIDRequired)
@@ -194,6 +207,7 @@ func UpdateAuthSource(source *AuthSource, keepSecret bool) error {
 	}).Error
 }
 
+// ToggleAuthSource 切换认证源启用状态
 func ToggleAuthSource(id uint64, isActive bool) error {
 	source, err := GetAuthSourceByID(id)
 	if err != nil {
@@ -206,6 +220,7 @@ func ToggleAuthSource(id uint64, isActive bool) error {
 	return db.DB(context.Background()).Model(&AuthSource{}).Where("id = ?", id).Update("is_active", isActive).Error
 }
 
+// DeleteAuthSource 删除认证源及其关联的外部帐号绑定
 func DeleteAuthSource(id uint64) error {
 	if id == 0 {
 		return errors.New(errAuthSourceIDRequired)
@@ -218,6 +233,7 @@ func DeleteAuthSource(id uint64) error {
 	})
 }
 
+// FindExternalAccount 查找外部帐号绑定记录
 func FindExternalAccount(sourceID uint64, externalID string) (*ExternalAccount, error) {
 	var account ExternalAccount
 	if err := db.DB(context.Background()).Where("auth_source_id = ? AND external_id = ?", sourceID, externalID).First(&account).Error; err != nil {
@@ -226,6 +242,7 @@ func FindExternalAccount(sourceID uint64, externalID string) (*ExternalAccount,
 	return &account, nil
 }
 
+// BindExternalAccount 绑定外部帐号（已存在时更新用户名和邮箱）
 func BindExternalAccount(account *ExternalAccount) error {
 	if account.UserID == 0 || strings.TrimSpace(account.ExternalID) == "" {
 		return errors.New(errExternalAccountBindingIncomplete)
@@ -253,6 +270,7 @@ func BindExternalAccount(account *ExternalAccount) error {
 	})
 }
 
+// ListExternalAccountsByUserID 获取指定用户的所有外部帐号绑定视图
 func ListExternalAccountsByUserID(userID uint64) ([]ExternalAccountView, error) {
 	if userID == 0 {
 		return nil, errors.New(errUserIDRequired)
@@ -294,6 +312,7 @@ func ListExternalAccountsByUserID(userID uint64) ([]ExternalAccountView, error)
 	return views, nil
 }
 
+// DeleteExternalAccountForUser 删除指定用户的外部帐号绑定
 func DeleteExternalAccountForUser(id uint64, userID uint64) error {
 	if id == 0 || userID == 0 {
 		return errors.New(errExternalAccountBindingIDRequired)
diff --git a/internal/model/system_configs.go b/internal/model/system_configs.go
index ba754173..bf37ccb8 100644
--- a/internal/model/system_configs.go
+++ b/internal/model/system_configs.go
@@ -63,6 +63,7 @@ const (
 	SystemConfigRedisHashKey = "system:system_configs"
 )
 
+// SystemConfig 系统配置实体
 type SystemConfig struct {
 	Key         string    `json:"key" gorm:"primaryKey;size:64;not null"`
 	Value       string    `json:"value" gorm:"size:255;not null"`
diff --git a/internal/model/task_execution.go b/internal/model/task_execution.go
index 07f7635f..5e2c4fbd 100644
--- a/internal/model/task_execution.go
+++ b/internal/model/task_execution.go
@@ -30,6 +30,7 @@ import (
 // TaskExecutionStatus 任务执行状态
 type TaskExecutionStatus string
 
+// 任务执行状态
 const (
 	TaskExecutionStatusPending   TaskExecutionStatus = "pending"
 	TaskExecutionStatusRunning   TaskExecutionStatus = "running"
diff --git a/internal/model/templates.go b/internal/model/templates.go
index bd2e7b69..ed5ffaee 100644
--- a/internal/model/templates.go
+++ b/internal/model/templates.go
@@ -28,6 +28,7 @@ import (
 	"github.com/Rain-kl/Wavelet/internal/db"
 )
 
+// Template 邮件/消息模板实体
 type Template struct {
 	ID          uint64    `json:"id" gorm:"primaryKey;autoIncrement"`
 	Key         string    `json:"key" gorm:"uniqueIndex;size:80;not null"`
@@ -41,6 +42,7 @@ type Template struct {
 	UpdatedAt   time.Time `json:"updated_at" gorm:"autoUpdateTime;index"`
 }
 
+// Normalize 规范化模板字段
 func (t *Template) Normalize() {
 	t.Key = strings.TrimSpace(t.Key)
 	t.Name = strings.TrimSpace(t.Name)
@@ -53,6 +55,7 @@ func (t *Template) Normalize() {
 	}
 }
 
+// Validate 校验模板必填字段
 func (t *Template) Validate() error {
 	t.Normalize()
 	if t.Key == "" {
@@ -67,6 +70,7 @@ func (t *Template) Validate() error {
 	return nil
 }
 
+// Render 渲染模板的 Subject 和 Content
 func (t *Template) Render(data any) (string, string, error) {
 	// Render Subject
 	var subject string
diff --git a/internal/model/uploads.go b/internal/model/uploads.go
index bed2f3c0..e69ca252 100644
--- a/internal/model/uploads.go
+++ b/internal/model/uploads.go
@@ -24,6 +24,7 @@ import (
 // UploadStatus 上传状态
 type UploadStatus string
 
+// 上传状态
 const (
 	UploadStatusPending UploadStatus = "pending" // 待使用
 	UploadStatusUsed    UploadStatus = "used"    // 已使用
diff --git a/internal/otel_trace/propagator.go b/internal/otel_trace/propagator.go
index 382c8c51..daa20e8d 100644
--- a/internal/otel_trace/propagator.go
+++ b/internal/otel_trace/propagator.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package otel_trace 提供 OpenTelemetry 链路追踪封装工具
 package otel_trace
 
 import "go.opentelemetry.io/otel/propagation"
diff --git a/internal/otel_trace/trace.go b/internal/otel_trace/trace.go
index d513095a..95fc654e 100644
--- a/internal/otel_trace/trace.go
+++ b/internal/otel_trace/trace.go
@@ -25,6 +25,7 @@ import (
 	"go.opentelemetry.io/otel/trace"
 )
 
+// Tracer 全局 OpenTelemetry Tracer 实例
 var Tracer trace.Tracer
 var shutdownFuncs []func(context.Context) error
 
@@ -45,6 +46,7 @@ func init() {
 	Tracer = tracerProvider.Tracer("github.com/Rain-kl/Wavelet")
 }
 
+// Shutdown 关闭所有 Trace Provider
 func Shutdown(ctx context.Context) {
 	for _, fn := range shutdownFuncs {
 		_ = fn(ctx)
@@ -52,6 +54,7 @@ func Shutdown(ctx context.Context) {
 	shutdownFuncs = nil
 }
 
+// Start 创建一个新的 Trace Span
 func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span) {
 	return Tracer.Start(ctx, name, opts...)
 }
diff --git a/internal/storage/errs.go b/internal/storage/errs.go
index e91be4bd..e9240506 100644
--- a/internal/storage/errs.go
+++ b/internal/storage/errs.go
@@ -14,14 +14,17 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package storage 提供文件存储抽象层，包括 S3 兼容存储和本地缓存。
 package storage
 
+// ErrS3InitializationFailed S3 存储初始化失败错误
 type ErrS3InitializationFailed struct{}
 
 func (e ErrS3InitializationFailed) Error() string {
 	return errS3InitializationFailed
 }
 
+// LocalCacheError 本地缓存错误
 type LocalCacheError struct{}
 
 func (e LocalCacheError) Error() string {
diff --git a/internal/storage/s3.go b/internal/storage/s3.go
index 34a00417..2c57c47d 100644
--- a/internal/storage/s3.go
+++ b/internal/storage/s3.go
@@ -75,10 +75,12 @@ func init() {
 	log.Printf("[Storage] S3 storage initialized (bucket: %s, prefix: %s, cdn: %s)\n", bucket, keyPrefix, cdnURL)
 }
 
+// IsEnabledFunc 检查 S3 存储是否已初始化（可替换用于测试）
 var IsEnabledFunc = func() bool {
 	return client != nil
 }
 
+// IsEnabled 检查 S3 存储是否可用
 func IsEnabled() bool {
 	return IsEnabledFunc()
 }
diff --git a/internal/task/handler.go b/internal/task/handler.go
index 2d2eb1b3..a368cbb3 100644
--- a/internal/task/handler.go
+++ b/internal/task/handler.go
@@ -20,6 +20,7 @@ package task
 import "context"
 
 // TaskResult 任务执行结果
+//nolint:revive // TaskResult 保留完整名称以避免与通用 Result 混淆
 type TaskResult struct {
 	Message string // 结果摘要，如 "共清理 120 个文件，耗时 3.2s"
 	Detail  string // 可选的详细结果 JSON
@@ -37,6 +38,8 @@ type PayloadValidator interface {
 //
 // 开发者只需实现 Execute 方法编写业务逻辑，在方法内通过 task.AppendLog(ctx, ...) 追加执行日志。
 // 任务的创建、状态更新、错误记录、重试计数全部由框架透明处理。
+//
+//nolint:revive // TaskHandler 保留完整名称以避免与通用 Handler 混淆
 type TaskHandler interface {
 	// Execute 执行任务业务逻辑
 	//   - ctx: 已注入 Trace Span 和 taskID 的上下文
diff --git a/internal/task/handlers/register.go b/internal/task/handlers/register.go
index 0588a0c1..0ee9f4b5 100644
--- a/internal/task/handlers/register.go
+++ b/internal/task/handlers/register.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package handlers 注册异步任务处理器
 package handlers
 
 import (
diff --git a/internal/task/scheduler/errs.go b/internal/task/scheduler/errs.go
index 27cbc96c..b2b8f858 100644
--- a/internal/task/scheduler/errs.go
+++ b/internal/task/scheduler/errs.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package scheduler 提供定时任务调度功能
 package scheduler
 
 const (
diff --git a/internal/task/worker/middlewares.go b/internal/task/worker/middlewares.go
index 80fe8015..a37dd8ec 100644
--- a/internal/task/worker/middlewares.go
+++ b/internal/task/worker/middlewares.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package worker 提供 Asynq 任务处理服务器与中间件
 package worker
 
 import (
diff --git a/internal/testhelper/test_helper.go b/internal/testhelper/test_helper.go
index 8f640dae..2edf1ecf 100644
--- a/internal/testhelper/test_helper.go
+++ b/internal/testhelper/test_helper.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package testhelper 提供测试辅助工具
 package testhelper
 
 import (
diff --git a/internal/util/cap/prng.go b/internal/util/cap/prng.go
index aa21a61d..b011e096 100644
--- a/internal/util/cap/prng.go
+++ b/internal/util/cap/prng.go
@@ -22,6 +22,8 @@ import (
 )
 
 // fnv1a returns the 32-bit FNV-1a hash of a string
+//
+//nolint:mnd // FNV-1a 算法位移常量
 func fnv1a(str string) uint32 {
 	var hash uint32 = 2166136261
 	for i := 0; i < len(str); i++ {
@@ -32,6 +34,8 @@ func fnv1a(str string) uint32 {
 }
 
 // fnv1aResume resumes FNV-1a hashing from a given state
+//
+//nolint:mnd // FNV-1a 算法位移常量
 func fnv1aResume(state uint32, str string) uint32 {
 	h := state
 	for i := 0; i < len(str); i++ {
@@ -42,6 +46,8 @@ func fnv1aResume(state uint32, str string) uint32 {
 }
 
 // prngFromHash generates a hex string of specified length using an initial hash state
+//
+//nolint:mnd // xorshift 算法位移常量
 func prngFromHash(initialHash uint32, length int) string {
 	state := initialHash
 	var result strings.Builder
diff --git a/internal/util/context.go b/internal/util/context.go
index 4e4dcd83..7da4660d 100644
--- a/internal/util/context.go
+++ b/internal/util/context.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package util 提供通用工具函数
 package util
 
 import "github.com/gin-gonic/gin"
diff --git a/internal/util/custom_types.go b/internal/util/custom_types.go
index b817b437..cf73a2cb 100644
--- a/internal/util/custom_types.go
+++ b/internal/util/custom_types.go
@@ -26,6 +26,7 @@ import (
 // StringArray custom type for handling JSON arrays
 type StringArray []string
 
+// Scan 实现 sql.Scanner 接口，从数据库读取 JSON 数组
 func (sa *StringArray) Scan(value interface{}) error {
 	bytesValue, ok := value.([]byte)
 	if !ok {
@@ -34,6 +35,7 @@ func (sa *StringArray) Scan(value interface{}) error {
 	return json.Unmarshal(bytesValue, sa)
 }
 
+// Value 实现 driver.Valuer 接口，将 JSON 数组序列化为数据库存储值
 func (sa StringArray) Value() (driver.Value, error) {
 	return json.Marshal(sa)
 }
diff --git a/internal/util/mail/errs.go b/internal/util/mail/errs.go
index 75c3690d..6affbbe6 100644
--- a/internal/util/mail/errs.go
+++ b/internal/util/mail/errs.go
@@ -14,6 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package mail 提供 SMTP 邮件发送功能。
 package mail
 
 const (
diff --git a/internal/util/password.go b/internal/util/password.go
index 4647f025..38cc172d 100644
--- a/internal/util/password.go
+++ b/internal/util/password.go
@@ -18,6 +18,7 @@ package util
 
 import "golang.org/x/crypto/bcrypt"
 
+// HashPassword 使用 bcrypt 对密码进行哈希处理
 func HashPassword(password string) (string, error) {
 	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
 	if err != nil {
@@ -26,6 +27,7 @@ func HashPassword(password string) (string, error) {
 	return string(hash), nil
 }
 
+// CheckPasswordHash 比较 bcrypt 哈希值与明文密码是否匹配
 func CheckPasswordHash(hash, password string) bool {
 	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(password)) == nil
 }
diff --git a/main.go b/main.go
index bb7f8fce..a957c042 100644
--- a/main.go
+++ b/main.go
@@ -15,6 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package main 是 Wavelet 平台的程序入口
 package main
 
 import "github.com/Rain-kl/Wavelet/internal/cmd"