feat(admin): 新增客服手动录单功能与仪表盘今日录单统计

- 做了什么： - 新增客服手动录单数据库迁移 000084 及对应模型，支持编号唯一校验、客服快照绑定与 CRUD 操作； - 后端提供 csmanualentry 业务模块及相关 API，并在仪表盘摘要中聚合今日各客服录单数量； - 前端增加客服手动录单视图页面、路由与侧边栏导航，支持录单二次确认与细粒度权限控制； - 管理后台仪表盘增加今日客服手动录单卡片展示。 - 为什么： - 满足客服在后台手动登记外部业务编号需求，并便于运营按客服统计今日录单业绩和追溯对账。 - 验证方式： - 执行后端全量测试 go test ./... 与静态检查 go vet ./... 全部通过； - 执行前端代码门禁 npm run check 与 vite build 全部通过； - 执行 goose down/up 迁移回滚与应用测试通过，角色权限分配正确； - 本地 dev 联调 POST /api/admin/manual-entries 录单成功返回 201。
2026-10-12 14:52:24 +08:00
parent 5840b7da40
commit cca40940d5
20 changed files with 1267 additions and 12 deletions
@@ -0,0 +1,220 @@
+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, remark string) (*EntryDTO, error) {
+	row := model.CSManualEntry{
+		EntryNo:       entryNo,
+		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, remark string) (*EntryDTO, error) {
+	result := r.db.WithContext(ctx).Model(&model.CSManualEntry{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"entry_no": entryNo,
+			"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 ?", 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
+}
+
+func parseDay(value string, loc *time.Location) (time.Time, error) {
+	return time.ParseInLocation("2006-01-02", value, loc)
+}
+
+// isDuplicateEntry 判断错误是否为 entry_no 唯一键冲突。
+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,
+		AdminID:       row.AdminID,
+		AdminName:     row.AdminName,
+		AdminUsername: row.AdminUsername,
+		Remark:        row.Remark,
+		CreatedAt:     row.CreatedAt,
+	}
+}