chore(init): 初始化解忧商行项目并完成 Phase 0 基座

2026-10-30 11:46:10 +08:00
commit 8d9481c251
689 changed files with 138703 additions and 0 deletions
@@ -0,0 +1,96 @@
+package csmanualentry
+
+import "time"
+
+// 录单选项类型。
+const (
+	OptionTypePlatform = "platform" // 平台
+	OptionTypeOperator = "operator" // 操作人
+)
+
+// CreateRequest 客服手动录单请求。
+type CreateRequest struct {
+	EntryNo  string `json:"entry_no" binding:"required"`
+	Platform string `json:"platform"`
+	Operator string `json:"operator"`
+	Remark   string `json:"remark"`
+}
+
+// UpdateRequest 管理员修正录单请求。
+type UpdateRequest struct {
+	EntryNo  string `json:"entry_no" binding:"required"`
+	Platform string `json:"platform"`
+	Operator string `json:"operator"`
+	Remark   string `json:"remark"`
+}
+
+// EntryDTO 录单记录。
+type EntryDTO struct {
+	ID            uint64    `json:"id"`
+	EntryNo       string    `json:"entry_no"`
+	Platform      string    `json:"platform"`
+	Operator      string    `json:"operator"`
+	AdminID       uint64    `json:"admin_id"`
+	AdminName     string    `json:"admin_name"`
+	AdminUsername string    `json:"admin_username"`
+	Remark        string    `json:"remark"`
+	CreatedAt     time.Time `json:"created_at"`
+}
+
+// ListQuery 录单查询条件。
+type ListQuery struct {
+	EntryNo   string
+	Keyword   string
+	AdminID   uint64
+	StartDate string // YYYY-MM-DD（北京时间，闭区间）
+	EndDate   string // YYYY-MM-DD（北京时间，闭区间）
+	Page      int
+	PageSize  int
+}
+
+// PaginatedResult 分页结果。
+type PaginatedResult struct {
+	Items    []EntryDTO `json:"items"`
+	Total    int64      `json:"total"`
+	Page     int        `json:"page"`
+	PageSize int        `json:"page_size"`
+}
+
+// AgentDayStatsDTO 某客服某日录单统计。
+type AgentDayStatsDTO struct {
+	Date      string `json:"date"` // YYYY-MM-DD（北京时间）
+	AdminID   uint64 `json:"admin_id"`
+	AdminName string `json:"admin_name"`
+	Count     int64  `json:"count"`
+}
+
+// CreateResult 录单结果。
+type CreateResult struct {
+	Entry EntryDTO `json:"entry"`
+}
+
+// OptionDTO 录单可选项（平台 / 操作人）。
+type OptionDTO struct {
+	ID        uint64    `json:"id"`
+	Type      string    `json:"type"`
+	Name      string    `json:"name"`
+	SortOrder int       `json:"sort_order"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// OptionListDTO 平台与操作人选项集合，供录单表单下拉直接使用。
+type OptionListDTO struct {
+	Platforms []OptionDTO `json:"platforms"`
+	Operators []OptionDTO `json:"operators"`
+}
+
+// CreateOptionRequest 新增平台 / 操作人选项。
+type CreateOptionRequest struct {
+	Type string `json:"type" binding:"required"`
+	Name string `json:"name" binding:"required"`
+}
+
+// UpdateOptionRequest 重命名平台 / 操作人选项。
+type UpdateOptionRequest struct {
+	Name string `json:"name" binding:"required"`
+}
@@ -0,0 +1,15 @@
+package csmanualentry
+
+import "errors"
+
+var (
+	ErrDependencyUnavailable = errors.New("dependency unavailable")
+	ErrEntryNoExists         = errors.New("manual entry number already exists")
+	ErrEntryNoInvalid        = errors.New("entry number is invalid")
+	ErrEntryNotFound         = errors.New("manual entry not found")
+	ErrAdminNotFound         = errors.New("admin not found")
+	ErrOptionTypeInvalid     = errors.New("manual entry option type is invalid")
+	ErrOptionNameInvalid     = errors.New("manual entry option name is invalid")
+	ErrOptionExists          = errors.New("manual entry option already exists")
+	ErrOptionNotFound        = errors.New("manual entry option not found")
+)
@@ -0,0 +1,248 @@
+package csmanualentry
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"hfb_sys/backend/internal/middleware"
+	"hfb_sys/backend/pkg/response"
+
+	"github.com/gin-gonic/gin"
+)
+
+type Handler struct {
+	service *Service
+}
+
+func NewHandler(service *Service) *Handler {
+	return &Handler{service: service}
+}
+
+func (h *Handler) Create(c *gin.Context) {
+	adminID, ok := currentAdminID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	var req CreateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "录单参数不正确")
+		return
+	}
+	result, err := h.service.Create(c.Request.Context(), adminID, req)
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.Created(c, result)
+}
+
+func (h *Handler) List(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	page, pageSize := parsePagination(c)
+	query := ListQuery{
+		EntryNo:   strings.TrimSpace(c.Query("entry_no")),
+		Keyword:   strings.TrimSpace(c.Query("keyword")),
+		StartDate: strings.TrimSpace(c.Query("start_date")),
+		EndDate:   strings.TrimSpace(c.Query("end_date")),
+		Page:      page,
+		PageSize:  pageSize,
+	}
+	if raw := c.Query("admin_id"); raw != "" {
+		adminID, err := strconv.ParseUint(raw, 10, 64)
+		if err != nil {
+			response.BadRequest(c, "客服 ID 不正确")
+			return
+		}
+		query.AdminID = adminID
+	}
+	result, err := h.service.List(c.Request.Context(), query)
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+func (h *Handler) TodayAgentStats(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	items, err := h.service.TodayAgentStats(c.Request.Context())
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, items)
+}
+
+func (h *Handler) Update(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.BadRequest(c, "ID 不正确")
+		return
+	}
+	var req UpdateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "录单参数不正确")
+		return
+	}
+	entry, err := h.service.Update(c.Request.Context(), id, req)
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, entry)
+}
+
+func (h *Handler) Delete(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.BadRequest(c, "ID 不正确")
+		return
+	}
+	if err := h.service.Delete(c.Request.Context(), id); err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, gin.H{"deleted": true})
+}
+
+// ListOptions 返回平台与操作人选项，供录单表单下拉使用。
+func (h *Handler) ListOptions(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	result, err := h.service.ListOptions(c.Request.Context())
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+// CreateOption 新增平台 / 操作人选项。
+func (h *Handler) CreateOption(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	var req CreateOptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "选项参数不正确")
+		return
+	}
+	option, err := h.service.CreateOption(c.Request.Context(), req)
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.Created(c, option)
+}
+
+// UpdateOption 重命名平台 / 操作人选项。
+func (h *Handler) UpdateOption(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.BadRequest(c, "ID 不正确")
+		return
+	}
+	var req UpdateOptionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "选项参数不正确")
+		return
+	}
+	option, err := h.service.UpdateOption(c.Request.Context(), id, req)
+	if err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, option)
+}
+
+// DeleteOption 删除平台 / 操作人选项。
+func (h *Handler) DeleteOption(c *gin.Context) {
+	if _, ok := currentAdminID(c); !ok {
+		response.Unauthorized(c, "缺少管理员上下文")
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.BadRequest(c, "ID 不正确")
+		return
+	}
+	if err := h.service.DeleteOption(c.Request.Context(), id); err != nil {
+		writeManualEntryError(c, err)
+		return
+	}
+	response.OK(c, gin.H{"deleted": true})
+}
+
+func currentAdminID(c *gin.Context) (uint64, bool) {
+	value, ok := c.Get(middleware.ContextAdminID)
+	if !ok {
+		return 0, false
+	}
+	adminID, ok := value.(uint64)
+	return adminID, ok
+}
+
+func parsePagination(c *gin.Context) (int, int) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	return page, pageSize
+}
+
+func writeManualEntryError(c *gin.Context, err error) {
+	response.RecordError(c, err)
+	switch {
+	case errors.Is(err, ErrDependencyUnavailable):
+		response.ServiceUnavailable(c, "数据库未连接")
+	case errors.Is(err, ErrAdminNotFound):
+		response.Unauthorized(c, "客服账号不存在")
+	case errors.Is(err, ErrEntryNoInvalid):
+		response.BadRequest(c, "编号格式不正确")
+	case errors.Is(err, ErrEntryNotFound):
+		response.NotFound(c, "录单记录不存在")
+	case errors.Is(err, ErrEntryNoExists):
+		response.Error(c, http.StatusConflict, "entry_no_exists", "该编号已被登记")
+	case errors.Is(err, ErrOptionTypeInvalid):
+		response.BadRequest(c, "选项类型不正确")
+	case errors.Is(err, ErrOptionNameInvalid):
+		response.BadRequest(c, "选项名称不正确")
+	case errors.Is(err, ErrOptionNotFound):
+		response.NotFound(c, "选项不存在")
+	case errors.Is(err, ErrOptionExists):
+		response.Error(c, http.StatusConflict, "option_exists", "该选项已存在")
+	default:
+		response.Error(c, http.StatusInternalServerError, "internal_error", "录单服务暂时不可用")
+	}
+}
@@ -0,0 +1,327 @@
+package csmanualentry
+
+import (
+	"context"
+	"errors"
+	"sort"
+	"strings"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/timeutil"
+
+	"gorm.io/gorm"
+)
+
+type Repository struct {
+	db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+	return &Repository{db: db}
+}
+
+// FindAdminSnapshot 读取客服的昵称与登录名，用于录单时绑定快照。
+func (r *Repository) FindAdminSnapshot(ctx context.Context, adminID uint64) (name, username string, err error) {
+	var admin model.AdminUser
+	if err := r.db.WithContext(ctx).First(&admin, adminID).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return "", "", ErrAdminNotFound
+		}
+		return "", "", err
+	}
+	return admin.Nickname, admin.Username, nil
+}
+
+// Create 写入一条录单记录。
+func (r *Repository) Create(ctx context.Context, adminID uint64, adminName, adminUsername, entryNo, platform, operator, remark string) (*EntryDTO, error) {
+	row := model.CSManualEntry{
+		EntryNo:       entryNo,
+		Platform:      platform,
+		Operator:      operator,
+		AdminID:       adminID,
+		AdminName:     adminName,
+		AdminUsername: adminUsername,
+		Remark:        remark,
+	}
+	if err := r.db.WithContext(ctx).Create(&row).Error; err != nil {
+		if isDuplicateEntry(err) {
+			return nil, ErrEntryNoExists
+		}
+		return nil, err
+	}
+	dto := toDTO(row)
+	return &dto, nil
+}
+
+// FindByID 按 ID 查询单条录单记录。
+func (r *Repository) FindByID(ctx context.Context, id uint64) (*EntryDTO, error) {
+	var row model.CSManualEntry
+	if err := r.db.WithContext(ctx).First(&row, id).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, ErrEntryNotFound
+		}
+		return nil, err
+	}
+	dto := toDTO(row)
+	return &dto, nil
+}
+
+// Update 修正录单的编号、平台、操作人与备注。编号唯一冲突返回 ErrEntryNoExists。
+func (r *Repository) Update(ctx context.Context, id uint64, entryNo, platform, operator, remark string) (*EntryDTO, error) {
+	result := r.db.WithContext(ctx).Model(&model.CSManualEntry{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"entry_no": entryNo,
+			"platform": platform,
+			"operator": operator,
+			"remark":   remark,
+		})
+	if result.Error != nil {
+		if isDuplicateEntry(result.Error) {
+			return nil, ErrEntryNoExists
+		}
+		return nil, result.Error
+	}
+	if result.RowsAffected == 0 {
+		var count int64
+		if err := r.db.WithContext(ctx).Model(&model.CSManualEntry{}).Where("id = ?", id).Count(&count).Error; err != nil {
+			return nil, err
+		}
+		if count == 0 {
+			return nil, ErrEntryNotFound
+		}
+	}
+	return r.FindByID(ctx, id)
+}
+
+// Delete 删除一条录单记录。
+func (r *Repository) Delete(ctx context.Context, id uint64) error {
+	result := r.db.WithContext(ctx).Delete(&model.CSManualEntry{}, id)
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return ErrEntryNotFound
+	}
+	return nil
+}
+
+// List 按条件分页查询录单记录。
+func (r *Repository) List(ctx context.Context, query ListQuery) (*PaginatedResult, error) {
+	db := r.db.WithContext(ctx).Model(&model.CSManualEntry{})
+	countDB := r.db.WithContext(ctx).Model(&model.CSManualEntry{})
+
+	if query.EntryNo != "" {
+		db = db.Where("entry_no = ?", query.EntryNo)
+		countDB = countDB.Where("entry_no = ?", query.EntryNo)
+	}
+	if query.AdminID > 0 {
+		db = db.Where("admin_id = ?", query.AdminID)
+		countDB = countDB.Where("admin_id = ?", query.AdminID)
+	}
+	if kw := strings.TrimSpace(query.Keyword); kw != "" {
+		like := "%" + kw + "%"
+		cond := r.db.Where(
+			"entry_no LIKE ? OR admin_name LIKE ? OR admin_username LIKE ? OR platform LIKE ? OR operator LIKE ?",
+			like, like, like, like, like,
+		)
+		db = db.Where(cond)
+		countDB = countDB.Where(cond)
+	}
+	loc := timeutil.ShanghaiLocation()
+	if query.StartDate != "" {
+		if start, err := parseDay(query.StartDate, loc); err == nil {
+			db = db.Where("created_at >= ?", start)
+			countDB = countDB.Where("created_at >= ?", start)
+		}
+	}
+	if query.EndDate != "" {
+		if end, err := parseDay(query.EndDate, loc); err == nil {
+			next := end.AddDate(0, 0, 1)
+			db = db.Where("created_at < ?", next)
+			countDB = countDB.Where("created_at < ?", next)
+		}
+	}
+
+	var total int64
+	if err := countDB.Count(&total).Error; err != nil {
+		return nil, err
+	}
+
+	offset := (query.Page - 1) * query.PageSize
+	rows := make([]model.CSManualEntry, 0)
+	if err := db.Order("id DESC").Offset(offset).Limit(query.PageSize).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	items := make([]EntryDTO, 0, len(rows))
+	for _, row := range rows {
+		items = append(items, toDTO(row))
+	}
+	return &PaginatedResult{Items: items, Total: total, Page: query.Page, PageSize: query.PageSize}, nil
+}
+
+// TodayAgentStats 统计指定日期（北京时间自然日）各客服的录单量。
+func (r *Repository) TodayAgentStats(ctx context.Context, day time.Time) ([]AgentDayStatsDTO, error) {
+	loc := timeutil.ShanghaiLocation()
+	start := time.Date(day.Year(), day.Month(), day.Day(), 0, 0, 0, 0, loc)
+	end := start.AddDate(0, 0, 1)
+
+	type row struct {
+		AdminID   uint64
+		AdminName string
+		Count     int64
+	}
+	rows := make([]row, 0)
+	if err := r.db.WithContext(ctx).Table("cs_manual_entries").
+		Select("admin_id, MAX(admin_name) AS admin_name, COUNT(*) AS count").
+		Where("created_at >= ? AND created_at < ?", start, end).
+		Group("admin_id").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	sort.Slice(rows, func(i, j int) bool {
+		if rows[i].Count != rows[j].Count {
+			return rows[i].Count > rows[j].Count
+		}
+		return rows[i].AdminName < rows[j].AdminName
+	})
+	date := start.Format("2006-01-02")
+	items := make([]AgentDayStatsDTO, 0, len(rows))
+	for _, item := range rows {
+		items = append(items, AgentDayStatsDTO{
+			Date:      date,
+			AdminID:   item.AdminID,
+			AdminName: item.AdminName,
+			Count:     item.Count,
+		})
+	}
+	return items, nil
+}
+
+// ListOptions 返回某类型（平台 / 操作人）的全部可选项。
+func (r *Repository) ListOptions(ctx context.Context, optionType string) ([]OptionDTO, error) {
+	if !IsValidOptionType(optionType) {
+		return nil, ErrOptionTypeInvalid
+	}
+	rows := make([]model.CSManualEntryOption, 0)
+	if err := r.db.WithContext(ctx).
+		Where("type = ?", optionType).
+		Order("sort_order ASC, id ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	items := make([]OptionDTO, 0, len(rows))
+	for _, row := range rows {
+		items = append(items, toOptionDTO(row))
+	}
+	return items, nil
+}
+
+// ListAllOptions 返回平台与操作人两组可选项，供录单表单直接使用。
+func (r *Repository) ListAllOptions(ctx context.Context) (*OptionListDTO, error) {
+	platforms, err := r.ListOptions(ctx, OptionTypePlatform)
+	if err != nil {
+		return nil, err
+	}
+	operators, err := r.ListOptions(ctx, OptionTypeOperator)
+	if err != nil {
+		return nil, err
+	}
+	return &OptionListDTO{Platforms: platforms, Operators: operators}, nil
+}
+
+// CreateOption 新增一个平台 / 操作人选项，重名返回 ErrOptionExists。
+func (r *Repository) CreateOption(ctx context.Context, optionType, name string) (*OptionDTO, error) {
+	if !IsValidOptionType(optionType) {
+		return nil, ErrOptionTypeInvalid
+	}
+	row := model.CSManualEntryOption{Type: optionType, Name: name}
+	if err := r.db.WithContext(ctx).Create(&row).Error; err != nil {
+		if isDuplicateEntry(err) {
+			return nil, ErrOptionExists
+		}
+		return nil, err
+	}
+	dto := toOptionDTO(row)
+	return &dto, nil
+}
+
+// UpdateOption 重命名一个选项，重名返回 ErrOptionExists。
+func (r *Repository) UpdateOption(ctx context.Context, id uint64, name string) (*OptionDTO, error) {
+	var row model.CSManualEntryOption
+	if err := r.db.WithContext(ctx).First(&row, id).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, ErrOptionNotFound
+		}
+		return nil, err
+	}
+	result := r.db.WithContext(ctx).Model(&model.CSManualEntryOption{}).
+		Where("id = ?", id).
+		Update("name", name)
+	if result.Error != nil {
+		if isDuplicateEntry(result.Error) {
+			return nil, ErrOptionExists
+		}
+		return nil, result.Error
+	}
+	row.Name = name
+	dto := toOptionDTO(row)
+	return &dto, nil
+}
+
+// DeleteOption 删除一个选项（历史录单里的名称快照不受影响）。
+func (r *Repository) DeleteOption(ctx context.Context, id uint64) error {
+	result := r.db.WithContext(ctx).Delete(&model.CSManualEntryOption{}, id)
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return ErrOptionNotFound
+	}
+	return nil
+}
+
+// IsValidOptionType 判断选项类型是否合法。
+func IsValidOptionType(optionType string) bool {
+	return optionType == OptionTypePlatform || optionType == OptionTypeOperator
+}
+
+func parseDay(value string, loc *time.Location) (time.Time, error) {
+	return time.ParseInLocation("2006-01-02", value, loc)
+}
+
+// isDuplicateEntry 判断错误是否为唯一键冲突。
+func isDuplicateEntry(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrDuplicatedKey) {
+		return true
+	}
+	return strings.Contains(err.Error(), "1062")
+}
+
+func toDTO(row model.CSManualEntry) EntryDTO {
+	return EntryDTO{
+		ID:            row.ID,
+		EntryNo:       row.EntryNo,
+		Platform:      row.Platform,
+		Operator:      row.Operator,
+		AdminID:       row.AdminID,
+		AdminName:     row.AdminName,
+		AdminUsername: row.AdminUsername,
+		Remark:        row.Remark,
+		CreatedAt:     row.CreatedAt,
+	}
+}
+
+func toOptionDTO(row model.CSManualEntryOption) OptionDTO {
+	return OptionDTO{
+		ID:        row.ID,
+		Type:      row.Type,
+		Name:      row.Name,
+		SortOrder: row.SortOrder,
+		CreatedAt: row.CreatedAt,
+	}
+}
@@ -0,0 +1,156 @@
+package csmanualentry
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"hfb_sys/backend/internal/database"
+	"hfb_sys/backend/internal/model"
+
+	"gorm.io/gorm"
+)
+
+func newManualEntryTestRepo(t *testing.T) (*Repository, *gorm.DB) {
+	t.Helper()
+	db := database.NewTestDB()
+	if err := database.AutoMigrateIfMissing(db,
+		&model.AdminUser{},
+		&model.CSManualEntry{},
+		&model.CSManualEntryOption{},
+	); err != nil {
+		t.Fatalf("迁移测试表失败: %v", err)
+	}
+	return NewRepository(db), db
+}
+
+func TestNormalizeOptionName(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr error
+	}{
+		{name: "trim", input: "  网易大神  ", want: "网易大神"},
+		{name: "empty allowed", input: "   ", want: ""},
+		{name: "inner space kept", input: "网易 大神", want: "网易 大神"},
+		{name: "64 runes", input: strings.Repeat("游", 64), want: strings.Repeat("游", 64)},
+		{name: "65 runes", input: strings.Repeat("游", 65), wantErr: ErrOptionNameInvalid},
+		{name: "newline", input: "网易\n大神", wantErr: ErrOptionNameInvalid},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := normalizeOptionName(tt.input)
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("normalizeOptionName(%q) error = %v, want %v", tt.input, err, tt.wantErr)
+			}
+			if tt.wantErr == nil && got != tt.want {
+				t.Fatalf("normalizeOptionName(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRepositoryOptionCRUDAndEntryPlatformOperator(t *testing.T) {
+	repo, db := newManualEntryTestRepo(t)
+	ctx := t.Context()
+
+	admin := model.AdminUser{Username: "cs001", Nickname: "客服小张", PasswordHash: "x"}
+	if err := db.Create(&admin).Error; err != nil {
+		t.Fatalf("创建管理员失败: %v", err)
+	}
+
+	// 1. 选项 CRUD
+	platform, err := repo.CreateOption(ctx, OptionTypePlatform, "网易大神")
+	if err != nil {
+		t.Fatalf("创建平台选项失败: %v", err)
+	}
+	// 同类型第二个平台，用于验证重命名撞名（唯一键是 type+name，跨类型不算冲突）
+	if _, err := repo.CreateOption(ctx, OptionTypePlatform, "交易猫"); err != nil {
+		t.Fatalf("创建第二个平台选项失败: %v", err)
+	}
+	operator, err := repo.CreateOption(ctx, OptionTypeOperator, "技术测试")
+	if err != nil {
+		t.Fatalf("创建操作人选项失败: %v", err)
+	}
+	if _, err := repo.CreateOption(ctx, OptionTypePlatform, "网易大神"); !errors.Is(err, ErrOptionExists) {
+		t.Fatalf("重复平台应返回 ErrOptionExists, got %v", err)
+	}
+	if _, err := repo.CreateOption(ctx, "unknown", "x"); !errors.Is(err, ErrOptionTypeInvalid) {
+		t.Fatalf("非法类型应返回 ErrOptionTypeInvalid, got %v", err)
+	}
+	// 与平台同名的操作人是允许的（不同 type）
+	if _, err := repo.CreateOption(ctx, OptionTypeOperator, "网易大神"); err != nil {
+		t.Fatalf("跨类型同名应允许: %v", err)
+	}
+
+	if _, err := repo.UpdateOption(ctx, platform.ID, "网易"); err != nil {
+		t.Fatalf("重命名选项失败: %v", err)
+	}
+	if _, err := repo.UpdateOption(ctx, platform.ID, "交易猫"); !errors.Is(err, ErrOptionExists) {
+		t.Fatalf("重命名撞同类型已有名应返回 ErrOptionExists, got %v", err)
+	}
+	if _, err := repo.UpdateOption(ctx, 999999, "任何"); !errors.Is(err, ErrOptionNotFound) {
+		t.Fatalf("重命名不存在选项应返回 ErrOptionNotFound, got %v", err)
+	}
+
+	options, err := repo.ListAllOptions(ctx)
+	if err != nil {
+		t.Fatalf("读取选项列表失败: %v", err)
+	}
+	if len(options.Platforms) != 2 || options.Platforms[0].Name != "网易" {
+		t.Fatalf("平台选项 = %+v, want 2 条且首条为网易", options.Platforms)
+	}
+	if len(options.Operators) != 2 {
+		t.Fatalf("操作人选项 = %+v, want 2 条", options.Operators)
+	}
+
+	// 2. 录单写入平台 / 操作人
+	entry, err := repo.Create(ctx, admin.ID, "客服小张", "cs001", "202610130001", "网易", "技术测试", "备注1")
+	if err != nil {
+		t.Fatalf("录单失败: %v", err)
+	}
+	if entry.Platform != "网易" || entry.Operator != "技术测试" {
+		t.Fatalf("录单平台/操作人 = %q/%q", entry.Platform, entry.Operator)
+	}
+
+	// 修正录单的平台与操作人
+	updated, err := repo.Update(ctx, entry.ID, "202610130001", "网易", "客服小李", "备注2")
+	if err != nil {
+		t.Fatalf("修正录单失败: %v", err)
+	}
+	if updated.Operator != "客服小李" || updated.Remark != "备注2" {
+		t.Fatalf("修正后 = %+v", updated)
+	}
+
+	// 3. 关键字命中平台 / 操作人
+	list, err := repo.List(ctx, ListQuery{Keyword: "客服小李", Page: 1, PageSize: 20})
+	if err != nil {
+		t.Fatalf("按操作人查询失败: %v", err)
+	}
+	if list.Total != 1 {
+		t.Fatalf("按操作人查询命中 %d 条, want 1", list.Total)
+	}
+	list, err = repo.List(ctx, ListQuery{Keyword: "网易", Page: 1, PageSize: 20})
+	if err != nil {
+		t.Fatalf("按平台查询失败: %v", err)
+	}
+	if list.Total != 1 {
+		t.Fatalf("按平台查询命中 %d 条, want 1", list.Total)
+	}
+
+	// 4. 删除选项不影响历史录单（记录里是名称快照）
+	if err := repo.DeleteOption(ctx, operator.ID); err != nil {
+		t.Fatalf("删除操作人选项失败: %v", err)
+	}
+	if err := repo.DeleteOption(ctx, operator.ID); !errors.Is(err, ErrOptionNotFound) {
+		t.Fatalf("重复删除应返回 ErrOptionNotFound, got %v", err)
+	}
+	after, err := repo.FindByID(ctx, entry.ID)
+	if err != nil {
+		t.Fatalf("删除选项后读取录单失败: %v", err)
+	}
+	if after.Operator != "客服小李" {
+		t.Fatalf("删除选项后历史录单操作人 = %q, want 客服小李", after.Operator)
+	}
+}
@@ -0,0 +1,175 @@
+package csmanualentry
+
+import (
+	"context"
+	"strings"
+	"unicode/utf8"
+
+	"hfb_sys/backend/internal/timeutil"
+)
+
+const (
+	maxEntryNoLength    = 64
+	maxOptionNameLength = 64
+)
+
+type Service struct {
+	repo *Repository
+}
+
+func NewService(repo *Repository) *Service {
+	return &Service{repo: repo}
+}
+
+// Create 校验编号并落库。客服身份由 handler 从登录上下文注入。
+func (s *Service) Create(ctx context.Context, adminID uint64, req CreateRequest) (*CreateResult, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	entryNo, err := normalizeEntryNo(req.EntryNo)
+	if err != nil {
+		return nil, err
+	}
+	platform, err := normalizeOptionName(req.Platform)
+	if err != nil {
+		return nil, err
+	}
+	operator, err := normalizeOptionName(req.Operator)
+	if err != nil {
+		return nil, err
+	}
+	adminName, adminUsername, err := s.repo.FindAdminSnapshot(ctx, adminID)
+	if err != nil {
+		return nil, err
+	}
+	if adminName == "" {
+		adminName = adminUsername
+	}
+	entry, err := s.repo.Create(ctx, adminID, adminName, adminUsername, entryNo, platform, operator, strings.TrimSpace(req.Remark))
+	if err != nil {
+		return nil, err
+	}
+	return &CreateResult{Entry: *entry}, nil
+}
+
+// Update 管理员修正录单记录。
+func (s *Service) Update(ctx context.Context, id uint64, req UpdateRequest) (*EntryDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	entryNo, err := normalizeEntryNo(req.EntryNo)
+	if err != nil {
+		return nil, err
+	}
+	platform, err := normalizeOptionName(req.Platform)
+	if err != nil {
+		return nil, err
+	}
+	operator, err := normalizeOptionName(req.Operator)
+	if err != nil {
+		return nil, err
+	}
+	return s.repo.Update(ctx, id, entryNo, platform, operator, strings.TrimSpace(req.Remark))
+}
+
+// Delete 管理员删除录单记录。
+func (s *Service) Delete(ctx context.Context, id uint64) error {
+	if s.repo == nil {
+		return ErrDependencyUnavailable
+	}
+	return s.repo.Delete(ctx, id)
+}
+
+// List 分页查询录单记录。
+func (s *Service) List(ctx context.Context, query ListQuery) (*PaginatedResult, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.List(ctx, query)
+}
+
+// TodayAgentStats 返回今日（北京时间）各客服录单统计。
+func (s *Service) TodayAgentStats(ctx context.Context) ([]AgentDayStatsDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.TodayAgentStats(ctx, timeutil.ShanghaiNow())
+}
+
+// ListOptions 返回平台与操作人两组可选项。
+func (s *Service) ListOptions(ctx context.Context) (*OptionListDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.ListAllOptions(ctx)
+}
+
+// CreateOption 新增平台 / 操作人选项。
+func (s *Service) CreateOption(ctx context.Context, req CreateOptionRequest) (*OptionDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	optionType := strings.TrimSpace(req.Type)
+	if !IsValidOptionType(optionType) {
+		return nil, ErrOptionTypeInvalid
+	}
+	name, err := normalizeOptionName(req.Name)
+	if err != nil {
+		return nil, err
+	}
+	if name == "" {
+		return nil, ErrOptionNameInvalid
+	}
+	return s.repo.CreateOption(ctx, optionType, name)
+}
+
+// UpdateOption 重命名平台 / 操作人选项。
+func (s *Service) UpdateOption(ctx context.Context, id uint64, req UpdateOptionRequest) (*OptionDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	name, err := normalizeOptionName(req.Name)
+	if err != nil {
+		return nil, err
+	}
+	if name == "" {
+		return nil, ErrOptionNameInvalid
+	}
+	return s.repo.UpdateOption(ctx, id, name)
+}
+
+// DeleteOption 删除平台 / 操作人选项。
+func (s *Service) DeleteOption(ctx context.Context, id uint64) error {
+	if s.repo == nil {
+		return ErrDependencyUnavailable
+	}
+	return s.repo.DeleteOption(ctx, id)
+}
+
+// normalizeEntryNo 去除首尾空白并做基础校验。
+func normalizeEntryNo(raw string) (string, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return "", ErrEntryNoInvalid
+	}
+	if len(value) > maxEntryNoLength {
+		return "", ErrEntryNoInvalid
+	}
+	if strings.ContainsAny(value, " \t\r\n") {
+		return "", ErrEntryNoInvalid
+	}
+	return value, nil
+}
+
+// normalizeOptionName 规整平台 / 操作人名称：去首尾空白、按字符数限长。
+// 允许为空（录单时平台与操作人选填），但内部不允许换行等控制字符。
+func normalizeOptionName(raw string) (string, error) {
+	value := strings.TrimSpace(raw)
+	if utf8.RuneCountInString(value) > maxOptionNameLength {
+		return "", ErrOptionNameInvalid
+	}
+	if strings.ContainsAny(value, "\t\r\n") {
+		return "", ErrOptionNameInvalid
+	}
+	return value, nil
+}
@@ -0,0 +1,45 @@
+package csmanualentry
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestNormalizeEntryNo(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr error
+	}{
+		{name: "trim", input: " 202610120013 ", want: "202610120013"},
+		{name: "plain", input: "202610120013", want: "202610120013"},
+		{name: "empty", input: "   ", wantErr: ErrEntryNoInvalid},
+		{name: "inner space", input: "2026 1001", wantErr: ErrEntryNoInvalid},
+		{name: "too long", input: strings.Repeat("1", 65), wantErr: ErrEntryNoInvalid},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := normalizeEntryNo(tt.input)
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("normalizeEntryNo(%q) error = %v, want %v", tt.input, err, tt.wantErr)
+			}
+			if tt.wantErr == nil && got != tt.want {
+				t.Fatalf("normalizeEntryNo(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsDuplicateEntry(t *testing.T) {
+	if isDuplicateEntry(nil) {
+		t.Fatal("nil should not be duplicate")
+	}
+	if !isDuplicateEntry(errors.New("Error 1062 (23000): Duplicate entry")) {
+		t.Fatal("1062 error should be duplicate")
+	}
+	if isDuplicateEntry(errors.New("some other error")) {
+		t.Fatal("unrelated error should not be duplicate")
+	}
+}