docs: add package and exported symbol comments for revive lint compliance

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

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"

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)
 }

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 (

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
 }