sync: 同步 v1.0.4 并脱敏配置与镜像

2026-10-29 14:36:49 +08:00
parent 743e8e6e6e
commit 2206a393f7
516 changed files with 18119 additions and 2253 deletions
@@ -0,0 +1,130 @@
+package exportcenter
+
+import (
+	"context"
+	"os"
+
+	"github.com/gogf/gf/v2/errors/gerror"
+	"time"
+
+	"github.com/gogf/gf/v2/database/gdb"
+	"github.com/gogf/gf/v2/frame/g"
+	"github.com/gogf/gf/v2/os/gctx"
+	"github.com/gogf/gf/v2/os/gtime"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/consts"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/dao"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model/entity"
+)
+
+const (
+	cleanupBatchSize = 200
+	cleanupInterval  = 5 * time.Minute
+)
+
+// RemoveTaskFile 清理文件与OSS记录，保留任务历史。
+// 文件删除不可事务回滚；数据库提交失败时保留索引，下次按文件不存在幂等重试。
+func RemoveTaskFile(ctx context.Context, taskID int64, reason string, validate func(*entity.TExportTask) error) (affected int64, err error) {
+	err = g.DB().Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
+		columns := dao.TExportTask.Columns()
+		task := &entity.TExportTask{}
+		if err := dao.TExportTask.Ctx(ctx).TX(tx).Where(columns.Id, taskID).LockUpdate().Scan(task); err != nil {
+			return err
+		}
+		if task.Id == 0 {
+			return gerror.New("导出任务不存在")
+		}
+		if err := validate(task); err != nil {
+			return err
+		}
+		if task.DeletedTime != nil {
+			return nil
+		}
+		if task.OssId > 0 {
+			oss := &entity.SysOss{}
+			if err := dao.SysOss.Ctx(ctx).TX(tx).Where(dao.SysOss.Columns().OssId, task.OssId).LockUpdate().Scan(oss); err != nil {
+				return err
+			}
+			if oss.OssId > 0 {
+				if info, statErr := os.Stat(oss.Path); statErr == nil {
+					if !info.Mode().IsRegular() {
+						return gerror.New("导出文件路径不是普通文件")
+					}
+					if err := os.Remove(oss.Path); err != nil && !os.IsNotExist(err) {
+						return err
+					}
+				} else if !os.IsNotExist(statErr) {
+					return statErr
+				}
+				if _, err := dao.SysOss.Ctx(ctx).TX(tx).Where(dao.SysOss.Columns().OssId, oss.OssId).Delete(); err != nil {
+					return err
+				}
+			}
+		}
+		var updateErr error
+		affected, updateErr = dao.TExportTask.Ctx(ctx).TX(tx).Where(columns.Id, task.Id).WhereNull(columns.DeletedTime).
+			Data(g.Map{columns.DeletedTime: gtime.Now(), columns.DeleteReason: reason, columns.OssId: 0}).UpdateAndGetAffected()
+		if updateErr != nil {
+			return updateErr
+		}
+		if affected != 1 {
+			return gerror.New("任务状态已变更，请刷新后重试")
+		}
+		return nil
+	})
+	return affected, err
+}
+
+// StartCleanup 每五分钟清理过期任务和失败任务残留文件。
+func StartCleanup(ctx context.Context) {
+	go func() {
+		ticker := time.NewTicker(cleanupInterval)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				cleanupOnce(gctx.New())
+			}
+		}
+	}()
+}
+
+func cleanupOnce(ctx context.Context) {
+	var lastID int64
+	for {
+		tasks := make([]*entity.TExportTask, 0, cleanupBatchSize)
+		if err := dao.TExportTask.Ctx(ctx).
+			WhereNull(dao.TExportTask.Columns().DeletedTime).
+			WhereIn(dao.TExportTask.Columns().Status, []int{consts.DownloadStatusGenerated, consts.DownloadStatusFailed}).
+			WhereLT(dao.TExportTask.Columns().ExpireTime, gtime.Now()).
+			WhereGT(dao.TExportTask.Columns().Id, lastID).
+			OrderAsc(dao.TExportTask.Columns().Id).
+			Limit(cleanupBatchSize).Scan(&tasks); err != nil {
+			g.Log().Errorf(ctx, "[exportcenter] 查询过期导出任务失败: %v", err)
+			return
+		}
+		progress := false
+		for _, task := range tasks {
+			affected, err := RemoveTaskFile(ctx, task.Id, "expired", func(locked *entity.TExportTask) error {
+				if (locked.Status != consts.DownloadStatusGenerated && locked.Status != consts.DownloadStatusFailed) || locked.ExpireTime == nil || !locked.ExpireTime.Before(gtime.Now()) {
+					return gerror.New("任务尚未过期或状态已变更")
+				}
+				return nil
+			})
+			if err != nil {
+				g.Log().Warningf(ctx, "[exportcenter] 清理过期任务失败 taskNo=%s err=%v", task.TaskNo, err)
+			} else if affected > 0 {
+				progress = true
+			}
+		}
+		if len(tasks) < cleanupBatchSize {
+			return
+		}
+		nextID := tasks[len(tasks)-1].Id
+		if !progress && nextID <= lastID {
+			return
+		}
+		lastID = nextID
+	}
+}
@@ -0,0 +1,335 @@
+package exportcenter
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"sync"
+
+	"github.com/gogf/gf/v2/encoding/gjson"
+	"github.com/gogf/gf/v2/frame/g"
+	"github.com/gogf/gf/v2/net/ghttp"
+	"github.com/gogf/gf/v2/util/gconv"
+
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model"
+)
+
+// fieldList 导出列字段名清单（json tag）。
+type fieldList []string
+
+// columnsFromRequest 从当前请求里读取导出列清单。
+// 前端统一传 exportColumnsJson（JSON 字符串）：导出接口多为 x-www-form-urlencoded，
+// 数组套对象会在表单编码时被拆散，字符串形式不会。
+// 这样各导出无需改参数结构即可支持「按页面显示列导出」。
+func columnsFromRequest(ctx context.Context) []model.ExportColumn {
+	r := ghttp.RequestFromCtx(ctx)
+	if r == nil {
+		return nil
+	}
+	if raw := strings.TrimSpace(r.Get("exportColumnsJson").String()); raw != "" {
+		cols := make([]model.ExportColumn, 0)
+		if err := gjson.New(raw).Scan(&cols); err == nil && len(cols) > 0 {
+			return cols
+		}
+	}
+	// 兼容直接传数组的调用（如 JSON 请求体）
+	if v := r.Get("exportColumns"); v != nil && !v.IsNil() {
+		cols := make([]model.ExportColumn, 0)
+		if err := gconv.Structs(v.Interface(), &cols); err == nil && len(cols) > 0 {
+			return cols
+		}
+	}
+	return nil
+}
+
+// resolveColumns 生成表头。
+// 有列清单时按清单顺序取 label 作表头，并按 field 逐行取值；
+// 没有列清单时沿用调用方给的 Tags（兼容未改造的导出）。
+func resolveColumns(req *Request) (header []interface{}, fields fieldList, err error) {
+	for _, c := range req.Columns {
+		field := strings.TrimSpace(c.Field)
+		if field == "" {
+			continue
+		}
+		label := strings.TrimSpace(c.Label)
+		if label == "" {
+			label = field
+		}
+		fields = append(fields, field)
+		header = append(header, label)
+	}
+	if len(fields) > 0 {
+		// 自定义取值的导出（ToRow）要按 RowFields 取列，字段名对不上会静默出空列，这里留一条日志。
+		if req.ToRow != nil && len(req.RowFields) > 0 {
+			if missing := missingRowFields(fields, req.RowFields); len(missing) > 0 {
+				g.Log().Warningf(context.Background(),
+					"[exportcenter] 导出列在 RowFields 中不存在，将输出空列 biz=%s fields=%v", req.BizKey, missing)
+			}
+		}
+		return header, fields, nil
+	}
+
+	tags, err := req.Tags()
+	if err != nil {
+		return nil, nil, err
+	}
+	header = make([]interface{}, len(tags))
+	for i, v := range tags {
+		header[i] = v
+	}
+	return header, nil, nil
+}
+
+// rowValues 按列清单取值；无列清单时保持原有转换方式。
+func rowValues(v interface{}, fields fieldList, req *Request) []interface{} {
+	if len(fields) > 0 {
+		// 自定义取值的导出（ToRow）按 RowFields 声明的位置取列，避免绕过原有格式化。
+		if req.ToRow != nil && len(req.RowFields) > 0 {
+			values := pickRowFields(req.ToRow(v), req.RowFields, fields)
+			i := 0
+			for _, column := range req.Columns {
+				if strings.TrimSpace(column.Field) == "" {
+					continue
+				}
+				// 字典列/固定值映射列始终取列表模型的原值，避免对 ToRow 已翻译的中文再次查 key。
+				if (column.DictType != "" || len(column.ValueMap) > 0) && v != nil {
+					values[i] = valuesByFields(v, fieldList{column.Field})[0]
+				}
+				i++
+			}
+			return values
+		}
+		values := valuesByFields(v, fields)
+		i := 0
+		for _, column := range req.Columns {
+			if strings.TrimSpace(column.Field) == "" {
+				continue
+			}
+			if column.FallbackField != "" && (values[i] == nil || gconv.String(values[i]) == "") {
+				values[i] = valuesByFields(v, fieldList{column.FallbackField})[0]
+			}
+			i++
+		}
+		return values
+	}
+	if req.ToRow != nil {
+		return req.ToRow(v)
+	}
+	return structValues(v)
+}
+
+// loadColumnDicts 每个任务一次性加载列表列使用的字典。
+func loadColumnDicts(ctx context.Context, columns []model.ExportColumn, load func(context.Context, []string) ([]model.SysDictDataListModel, error)) (map[string]map[string]string, error) {
+	types := make([]string, 0)
+	seen := make(map[string]bool)
+	for _, column := range columns {
+		typ := strings.TrimSpace(column.DictType)
+		if strings.TrimSpace(column.Field) != "" && typ != "" && !seen[typ] {
+			seen[typ] = true
+			types = append(types, typ)
+		}
+	}
+	result := make(map[string]map[string]string)
+	if len(types) == 0 {
+		return result, nil
+	}
+	items, err := load(ctx, types)
+	if err != nil {
+		return nil, err
+	}
+	for _, item := range items {
+		if result[item.DictType] == nil {
+			result[item.DictType] = make(map[string]string)
+		}
+		result[item.DictType][item.DictValue] = item.DictLabel
+	}
+	return result, nil
+}
+
+func translateRow(values []interface{}, columns []model.ExportColumn, dicts map[string]map[string]string) {
+	i := 0
+	for _, column := range columns {
+		if strings.TrimSpace(column.Field) == "" {
+			continue
+		}
+		if i >= len(values) {
+			return
+		}
+		value := values[i]
+		str := ""
+		if value != nil {
+			str = gconv.String(value)
+		}
+		// 固定值映射优先：页面用三元表达式渲染的列（非字典）直接出显示文案。
+		if len(column.ValueMap) > 0 {
+			if mapped, ok := column.ValueMap[str]; ok {
+				values[i] = mapped
+				i++
+				continue
+			}
+			if column.ValueDefault != "" {
+				values[i] = column.ValueDefault
+				i++
+				continue
+			}
+		}
+		if str != "" {
+			key := str
+			if normalized, ok := column.DictValueMap[key]; ok {
+				key = normalized
+			}
+			if label, ok := dicts[strings.TrimSpace(column.DictType)][key]; ok {
+				values[i] = label
+			}
+		}
+		i++
+	}
+}
+
+// missingRowFields 找出列清单里 RowFields 无法提供的字段。
+func missingRowFields(fields fieldList, rowFields []string) []string {
+	known := make(map[string]bool, len(rowFields))
+	for _, name := range rowFields {
+		known[name] = true
+	}
+	missing := make([]string, 0)
+	for _, name := range fields {
+		if !known[name] {
+			missing = append(missing, name)
+		}
+	}
+	return missing
+}
+
+// pickRowFields 从自定义行数据里按字段名取列：row 与 rowFields 顺序一一对应。
+func pickRowFields(row []interface{}, rowFields []string, fields fieldList) []interface{} {
+	index := make(map[string]int, len(rowFields))
+	for i, name := range rowFields {
+		index[name] = i
+	}
+	out := make([]interface{}, len(fields))
+	for i, name := range fields {
+		pos, ok := index[name]
+		if !ok || pos < 0 || pos >= len(row) {
+			out[i] = ""
+			continue
+		}
+		out[i] = row[pos]
+	}
+	return out
+}
+
+// jsonFieldIndexCache 缓存「结构体类型 -> json tag 到字段下标的映射」，
+// 导出大结果集时避免每行重复解析 tag。
+var jsonFieldIndexCache sync.Map
+
+func jsonFieldIndexes(t reflect.Type) map[string]int {
+	if cached, ok := jsonFieldIndexCache.Load(t); ok {
+		return cached.(map[string]int)
+	}
+	indexes := make(map[string]int, t.NumField())
+	for i := 0; i < t.NumField(); i++ {
+		field := t.Field(i)
+		if field.PkgPath != "" { // 未导出字段
+			continue
+		}
+		name := strings.Split(field.Tag.Get("json"), ",")[0]
+		if name == "" || name == "-" {
+			continue
+		}
+		if _, exists := indexes[name]; !exists {
+			indexes[name] = i
+		}
+	}
+	jsonFieldIndexCache.Store(t, indexes)
+	return indexes
+}
+
+// valuesByFields 按字段名（json tag）从结构体取值，缺失字段留空。
+// 支持 "createdBySumma.name" 这类嵌套路径（列表页常按嵌套字段显示）。
+func valuesByFields(v interface{}, fields fieldList) []interface{} {
+	out := make([]interface{}, len(fields))
+	rv := reflect.ValueOf(v)
+	for rv.IsValid() && rv.Kind() == reflect.Ptr {
+		if rv.IsNil() {
+			return out
+		}
+		rv = rv.Elem()
+	}
+	if !rv.IsValid() || rv.Kind() != reflect.Struct {
+		return out
+	}
+	for i, name := range fields {
+		if value, ok := structFieldValue(rv, name); ok {
+			out[i] = exportCellValue(value)
+		} else {
+			out[i] = ""
+		}
+	}
+	return out
+}
+
+// structFieldValue 按 "a.b.c" 的 json tag 路径逐层取值。
+func structFieldValue(rv reflect.Value, path string) (reflect.Value, bool) {
+	cur := rv
+	for _, name := range strings.Split(path, ".") {
+		for cur.IsValid() {
+			if (cur.Kind() == reflect.Ptr || cur.Kind() == reflect.Interface) && cur.IsNil() {
+				return reflect.Value{}, false
+			}
+			if cur.CanInterface() {
+				if object, ok := cur.Interface().(interface{ Map() map[string]interface{} }); ok {
+					cur = reflect.ValueOf(object.Map())
+					break
+				}
+			}
+			if cur.Kind() != reflect.Ptr && cur.Kind() != reflect.Interface {
+				break
+			}
+			cur = cur.Elem()
+		}
+		if !cur.IsValid() {
+			return reflect.Value{}, false
+		}
+		if cur.Kind() == reflect.Map && cur.Type().Key().Kind() == reflect.String {
+			cur = cur.MapIndex(reflect.ValueOf(name))
+			if !cur.IsValid() {
+				return reflect.Value{}, false
+			}
+			continue
+		}
+		if cur.Kind() != reflect.Struct {
+			return reflect.Value{}, false
+		}
+		pos, ok := jsonFieldIndexes(cur.Type())[name]
+		if !ok {
+			return reflect.Value{}, false
+		}
+		cur = cur.Field(pos)
+	}
+	return cur, true
+}
+
+// exportCellValue 把字段值转成可写入单元格的值。
+// 指针为空、时间、嵌套结构都要处理，避免把内存地址写进 Excel。
+func exportCellValue(v reflect.Value) interface{} {
+	for v.IsValid() && v.Kind() == reflect.Ptr {
+		if v.IsNil() {
+			return ""
+		}
+		v = v.Elem()
+	}
+	if !v.IsValid() || !v.CanInterface() {
+		return ""
+	}
+	switch v.Kind() {
+	case reflect.Struct, reflect.Map, reflect.Slice, reflect.Array:
+		// 时间等有 String() 的类型交给 gconv，其余复合类型同样转字符串。
+		if s, ok := v.Interface().(interface{ String() string }); ok {
+			return s.String()
+		}
+		return gconv.String(v.Interface())
+	default:
+		return v.Interface()
+	}
+}
@@ -0,0 +1,268 @@
+package exportcenter
+
+import (
+	"context"
+	"errors"
+	"github.com/gogf/gf/v2/encoding/gjson"
+	"github.com/xuri/excelize/v2"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gogf/gf/v2/os/gtime"
+
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model"
+)
+
+func TestSubmitQueueBoundedBeforePersistence(t *testing.T) {
+	for len(slots) < cap(slots) {
+		slots <- struct{}{}
+	}
+	defer func() {
+		for len(slots) > 0 {
+			<-slots
+		}
+	}()
+	_, err := Submit(context.Background(), &Request{
+		BizKey: "test", BizName: "test", Tags: func() ([]string, error) { return nil, nil },
+		Fetch: func(context.Context, int, int) ([]interface{}, int, error) {
+			return []interface{}{1}, 1, nil
+		},
+	})
+	if err == nil || !strings.Contains(err.Error(), "排队已满") {
+		t.Fatalf("队列满时应拒绝提交: %v", err)
+	}
+}
+
+func TestColumnDictBatchAndExcel(t *testing.T) {
+	columns := []model.ExportColumn{{Field: "status", DictType: "enabled"}, {Field: "", DictType: "ignored"}, {Field: "other", DictType: "enabled"}, {Field: "inverse", DictType: "yes", DictValueMap: map[string]string{"0": "1", "1": "0"}}}
+	calls := 0
+	dicts, err := loadColumnDicts(context.Background(), columns, func(_ context.Context, types []string) ([]model.SysDictDataListModel, error) {
+		calls++
+		if !reflect.DeepEqual(types, []string{"enabled", "yes"}) {
+			t.Fatalf("字典未去重: %v", types)
+		}
+		return []model.SysDictDataListModel{{DictType: "enabled", DictValue: "0", DictLabel: "启用"}, {DictType: "enabled", DictValue: "1", DictLabel: "停用"}, {DictType: "yes", DictValue: "1", DictLabel: "否"}}, nil
+	})
+	if err != nil || calls != 1 {
+		t.Fatalf("批量加载失败: %v %d", err, calls)
+	}
+	for _, tc := range []struct{ input, want interface{} }{{0, "启用"}, {"0", "启用"}, {1, "停用"}, {"", ""}, {nil, nil}, {"未知", "未知"}, {"启用", "启用"}} {
+		values := []interface{}{tc.input, "保留", 0}
+		translateRow(values, columns, dicts)
+		if !reflect.DeepEqual(values, []interface{}{tc.want, "保留", "否"}) {
+			t.Fatalf("映射 %v 得到 %v", tc.input, values)
+		}
+	}
+	f := excelize.NewFile()
+	defer f.Close()
+	stream, err := f.NewStreamWriter("Sheet1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	values := []interface{}{0, "未知", 0}
+	translateRow(values, columns, dicts)
+	if err = stream.SetRow("A1", values); err != nil {
+		t.Fatal(err)
+	}
+	if err = stream.Flush(); err != nil {
+		t.Fatal(err)
+	}
+	buffer, err := f.WriteToBuffer()
+	if err != nil {
+		t.Fatal(err)
+	}
+	read, err := excelize.OpenReader(buffer)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer read.Close()
+	rows, err := read.GetRows("Sheet1")
+	if err != nil || !reflect.DeepEqual(rows, [][]string{{"启用", "未知", "否"}}) {
+		t.Fatalf("xlsx 内容: %v %v", rows, err)
+	}
+}
+
+func TestColumnDictNoMetadataAndLoadFailure(t *testing.T) {
+	called := false
+	_, err := loadColumnDicts(context.Background(), nil, func(context.Context, []string) ([]model.SysDictDataListModel, error) { called = true; return nil, nil })
+	if called || err != nil {
+		t.Fatal("旧页面不应加载字典")
+	}
+	failure := errors.New("字典加载失败")
+	_, err = loadColumnDicts(context.Background(), []model.ExportColumn{{Field: "status", DictType: "x"}}, func(context.Context, []string) ([]model.SysDictDataListModel, error) { return nil, failure })
+	if !errors.Is(err, failure) {
+		t.Fatal("应传播字典加载错误")
+	}
+}
+
+func TestNestedDictFieldsAndFormattedRow(t *testing.T) {
+	row := struct {
+		BatchInfo *gjson.Json `json:"batchInfo"`
+	}{gjson.New(map[string]interface{}{"inboundOptions": map[string]interface{}{"status": 0}, "legacy": 1})}
+	columns := []model.ExportColumn{{Field: "batchInfo.inboundOptions.status"}, {Field: "batchInfo.inboundOptions.missing", FallbackField: "batchInfo.legacy"}}
+	req := &Request{Columns: columns}
+	_, fields, _ := resolveColumns(req)
+	values := rowValues(row, fields, req)
+	if !reflect.DeepEqual(values, []interface{}{0, 1}) {
+		t.Fatalf("JSON 嵌套与备用字段: %v", values)
+	}
+	req = &Request{Columns: []model.ExportColumn{{Field: "status", DictType: "x"}}, RowFields: []string{"status"}, ToRow: func(interface{}) []interface{} { return []interface{}{"已销户"} }}
+	values = rowValues(struct {
+		Status int `json:"status"`
+	}{9}, fieldList{"status"}, req)
+	translateRow(values, req.Columns, map[string]map[string]string{"x": {"9": "已销户"}})
+	if values[0] != "已销户" {
+		t.Fatalf("已中文行被改变: %v", values)
+	}
+}
+
+type columnSampleRow struct {
+	Iccid      string      `json:"iccid"`
+	DeptName   string      `json:"deptName"`
+	UsedFlowMb float64     `json:"usedFlowMb"`
+	ActiveAt   *gtime.Time `json:"activeAt"`
+	Extra      *string     `json:"extra"`
+}
+
+func TestResolveColumnsUsesRequestedOrder(t *testing.T) {
+	req := &Request{
+		Columns: []model.ExportColumn{
+			{Field: "deptName", Label: "所属企业"},
+			{Field: "iccid"},
+			{Field: "  ", Label: "空字段忽略"},
+			{Field: "usedFlowMb", Label: "已用流量(MB)"},
+		},
+		Tags: func() ([]string, error) {
+			t.Fatal("有列清单时不应回退到 Tags")
+			return nil, nil
+		},
+	}
+
+	header, fields, err := resolveColumns(req)
+	if err != nil {
+		t.Fatalf("resolveColumns error: %v", err)
+	}
+	wantHeader := []interface{}{"所属企业", "iccid", "已用流量(MB)"}
+	if len(header) != len(wantHeader) {
+		t.Fatalf("header len = %d, want %d", len(header), len(wantHeader))
+	}
+	for i := range wantHeader {
+		if header[i] != wantHeader[i] {
+			t.Fatalf("header[%d] = %v, want %v", i, header[i], wantHeader[i])
+		}
+	}
+	wantFields := fieldList{"deptName", "iccid", "usedFlowMb"}
+	if len(fields) != len(wantFields) {
+		t.Fatalf("fields len = %d, want %d", len(fields), len(wantFields))
+	}
+	for i := range wantFields {
+		if fields[i] != wantFields[i] {
+			t.Fatalf("fields[%d] = %q, want %q", i, fields[i], wantFields[i])
+		}
+	}
+}
+
+func TestResolveColumnsFallsBackToTags(t *testing.T) {
+	req := &Request{
+		Tags: func() ([]string, error) { return []string{"ICCID", "所属企业"}, nil },
+	}
+	header, fields, err := resolveColumns(req)
+	if err != nil {
+		t.Fatalf("resolveColumns error: %v", err)
+	}
+	if fields != nil {
+		t.Fatalf("fields should be nil when no columns, got %v", fields)
+	}
+	if len(header) != 2 || header[0] != "ICCID" || header[1] != "所属企业" {
+		t.Fatalf("unexpected header: %v", header)
+	}
+}
+
+func TestValuesByFields(t *testing.T) {
+	activeAt := gtime.NewFromTime(time.Date(2026, 10, 19, 15, 4, 5, 0, time.Local))
+	row := &columnSampleRow{
+		Iccid:      "8986001",
+		DeptName:   "测试企业",
+		UsedFlowMb: 12.5,
+		ActiveAt:   activeAt,
+	}
+
+	values := valuesByFields(row, fieldList{"deptName", "missingField", "usedFlowMb", "activeAt", "extra"})
+	if len(values) != 5 {
+		t.Fatalf("values len = %d, want 5", len(values))
+	}
+	if values[0] != "测试企业" {
+		t.Fatalf("deptName = %v", values[0])
+	}
+	if values[1] != "" {
+		t.Fatalf("missing field should be empty, got %v", values[1])
+	}
+	if values[2] != 12.5 {
+		t.Fatalf("usedFlowMb = %v", values[2])
+	}
+	if values[3] != "2026-10-19 15:04:05" {
+		t.Fatalf("activeAt = %v", values[3])
+	}
+	if values[4] != "" {
+		t.Fatalf("nil pointer should be empty, got %v", values[4])
+	}
+}
+
+func TestValuesByFieldsKeepsRowOrder(t *testing.T) {
+	row := &columnSampleRow{Iccid: "A", DeptName: "B"}
+	values := valuesByFields(row, fieldList{"iccid", "deptName"})
+	if values[0] != "A" || values[1] != "B" {
+		t.Fatalf("unexpected values: %v", values)
+	}
+}
+
+// TestValueMapColumn 覆盖非字典的固定值映射（页面用三元表达式渲染的列）。
+func TestValueMapColumn(t *testing.T) {
+	columns := []model.ExportColumn{
+		{
+			Field:        "isFlowPool",
+			ValueMap:     map[string]string{"1": "池卡", "0": "单卡"},
+			ValueDefault: "单卡",
+		},
+		{Field: "status", DictType: "common_status"},
+		{Field: "keep", ValueMap: map[string]string{"1": "是"}},
+	}
+	dicts := map[string]map[string]string{"common_status": {"1": "正常", "0": "停用"}}
+
+	// 1/0 命中映射；9 未命中走兜底；状态列仍走字典
+	values := []interface{}{1, 1, 1}
+	translateRow(values, columns, dicts)
+	if !reflect.DeepEqual(values, []interface{}{"池卡", "正常", "是"}) {
+		t.Fatalf("命中映射失败: %v", values)
+	}
+
+	// 0 必须映射，不能被当成空值跳过
+	values = []interface{}{0, "0", 1}
+	translateRow(values, columns, dicts)
+	if values[0] != "单卡" || values[1] != "停用" {
+		t.Fatalf("0 值映射失败: %v", values)
+	}
+
+	// 未命中且无兜底时保留原值
+	values = []interface{}{9, "", 7}
+	translateRow(values, columns, dicts)
+	if values[0] != "单卡" {
+		t.Fatalf("兜底失败: %v", values)
+	}
+	if values[2] != 7 {
+		t.Fatalf("无兜底应保留原值: %v", values)
+	}
+}
+
+// TestMissingRowFields 自定义 ToRow 导出：列 field 必须能在 RowFields 里找到。
+func TestMissingRowFields(t *testing.T) {
+	rowFields := []string{"iccid", "createdBy"}
+	if missing := missingRowFields(fieldList{"iccid"}, rowFields); len(missing) != 0 {
+		t.Fatalf("不应有缺失: %v", missing)
+	}
+	if missing := missingRowFields(fieldList{"iccid", "createdBySumma"}, rowFields); !reflect.DeepEqual(missing, []string{"createdBySumma"}) {
+		t.Fatalf("缺失识别错误: %v", missing)
+	}
+}
@@ -0,0 +1,498 @@
+package exportcenter
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime/debug"
+	"strings"
+	"time"
+
+	"github.com/gogf/gf/v2/crypto/gmd5"
+	"github.com/gogf/gf/v2/database/gdb"
+	"github.com/gogf/gf/v2/errors/gerror"
+	"github.com/gogf/gf/v2/frame/g"
+	"github.com/gogf/gf/v2/os/gctx"
+	"github.com/gogf/gf/v2/os/gtime"
+	"github.com/xuri/excelize/v2"
+
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/consts"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/dao"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/library/contexts"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model/entity"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/service"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/utility/hash"
+)
+
+// slots 在提交时预留容量，避免无限积压等待执行的 goroutine。
+var slots = make(chan struct{}, MaxConcurrent+MaxQueued)
+
+// sem 限制同时执行的导出任务数，避免把 DB 连接与磁盘打满。
+var sem = make(chan struct{}, MaxConcurrent)
+
+func run(taskNo string, req *Request) {
+	defer func() { <-slots }()
+	baseCtx := gctx.New()
+	var task *entity.TExportTask
+	var generatedPath string
+	defer func() {
+		if p := recover(); p != nil {
+			g.Log().Errorf(baseCtx, "[exportcenter] 导出协程异常 taskNo=%s panic=%v stack=%s", taskNo, p, debug.Stack())
+			if task == nil || task.Id == 0 {
+				task = &entity.TExportTask{}
+				if err := dao.TExportTask.Ctx(baseCtx).Where(dao.TExportTask.Columns().TaskNo, taskNo).Scan(task); err != nil {
+					g.Log().Errorf(baseCtx, "[exportcenter] panic 后加载任务失败 taskNo=%s err=%v", taskNo, err)
+				}
+			}
+			if task != nil && task.Id > 0 {
+				markFailed(baseCtx, task, gerror.Newf("导出任务执行异常: %v", p))
+			}
+		}
+	}()
+	sem <- struct{}{}
+	defer func() { <-sem }()
+
+	task = &entity.TExportTask{}
+	if err := dao.TExportTask.Ctx(baseCtx).
+		Where(dao.TExportTask.Columns().TaskNo, taskNo).
+		Scan(task); err != nil || task.Id <= 0 {
+		g.Log().Errorf(baseCtx, "[exportcenter] 加载任务失败 taskNo=%s err=%v", taskNo, err)
+		return
+	}
+
+	// CAS 抢占：只有把 0 改成 2 的协程才能执行
+	now := gtime.Now()
+	affected, err := dao.TExportTask.Ctx(baseCtx).
+		Data(g.Map{
+			dao.TExportTask.Columns().Status:    consts.DownloadStatusRunning,
+			dao.TExportTask.Columns().StartTime: now,
+		}).
+		Where(dao.TExportTask.Columns().Id, task.Id).
+		WhereNull(dao.TExportTask.Columns().DeletedTime).
+		Where(dao.TExportTask.Columns().Status, consts.DownloadStatusPending).
+		UpdateAndGetAffected()
+	if err != nil {
+		g.Log().Errorf(baseCtx, "[exportcenter] 抢占任务失败 taskNo=%s err=%v", taskNo, err)
+		return
+	}
+	if affected == 0 {
+		return
+	}
+
+	execCtx, cancel := context.WithTimeout(restoreContext(baseCtx, task), TaskTimeout)
+	defer cancel()
+
+	markBatchRunning(execCtx, taskNo)
+
+	if err = generate(execCtx, task, req, &generatedPath); err != nil {
+		g.Log().Errorf(execCtx, "[exportcenter] 导出失败 taskNo=%s err=%v", taskNo, err)
+		markFailed(baseCtx, task, err)
+	}
+}
+
+// restoreContext 用提交时的身份快照还原 ctx，保证 FilterAuth 仍按提交人范围过滤。
+func restoreContext(base context.Context, task *entity.TExportTask) context.Context {
+	snap := &model.ExportIdentitySnapshot{}
+	if task.IdentitySnapshot != nil {
+		if err := task.IdentitySnapshot.Scan(snap); err != nil {
+			g.Log().Warningf(base, "[exportcenter] 身份快照解析失败 taskNo=%s err=%v", task.TaskNo, err)
+		}
+	}
+	if snap.UserId <= 0 {
+		snap.UserId = task.OwnerUserId
+		snap.DeptId = task.DeptId
+		snap.TenantId = task.TenantId
+	}
+
+	identity := &model.Identity{}
+	identity.ID = snap.UserId
+	identity.DeptId = snap.DeptId
+	identity.TenantId = snap.TenantId
+	identity.Roles = snap.Roles
+	identity.AccessCodeList = snap.AccessCodeList
+
+	data := g.Map{}
+	if snap.CurrentRoleId != "" {
+		data["currentRoleId"] = snap.CurrentRoleId
+	}
+	if snap.CurrentRoleDataScope != "" {
+		data["currentRoleDataScope"] = snap.CurrentRoleDataScope
+	}
+
+	return contexts.Set(base, &model.Context{User: identity, Data: data})
+}
+
+func generate(ctx context.Context, task *entity.TExportTask, req *Request, generatedPath *string) (err error) {
+	header, fields, err := resolveColumns(req)
+	if err != nil {
+		return gerror.Wrap(err, "生成表头失败")
+	}
+
+	dicts, err := loadColumnDicts(ctx, req.Columns, func(ctx context.Context, types []string) ([]model.SysDictDataListModel, error) {
+		return service.SysDictData().GetDictListByTypes(ctx, types)
+	})
+	if err != nil {
+		return gerror.Wrap(err, "加载导出字典失败")
+	}
+
+	sheet := req.SheetName
+	if sheet == "" {
+		sheet = req.BizName
+	}
+	sheet = truncateSheetName(sheet)
+
+	f := excelize.NewFile()
+	defer f.Close()
+	if err = f.SetSheetName(f.GetSheetName(0), sheet); err != nil {
+		return gerror.Wrap(err, "设置工作表名称失败")
+	}
+	stream, err := f.NewStreamWriter(sheet)
+	if err != nil {
+		return gerror.Wrap(err, "创建工作表流失败")
+	}
+
+	if err = stream.SetRow("A1", header); err != nil {
+		return gerror.Wrap(err, "写入表头失败")
+	}
+
+	rowNum := 2
+	written := 0
+	for page := 1; ; page++ {
+		rows, total, fetchErr := req.Fetch(ctx, page, DefaultPageSize)
+		if fetchErr != nil {
+			// 页码只留给日志排查；对用户展示业务侧给出的可读原因，不暴露分页与驱动细节。
+			g.Log().Errorf(ctx, "[exportcenter] 第 %d 页取数失败 taskNo=%s err=%v", page, task.TaskNo, fetchErr)
+			return fetchErr
+		}
+		if len(rows) == 0 {
+			break
+		}
+		for _, v := range rows {
+			cell, _ := excelize.CoordinatesToCellName(1, rowNum)
+			values := rowValues(v, fields, req)
+			translateRow(values, req.Columns, dicts)
+			if err = stream.SetRow(cell, values); err != nil {
+				return gerror.Wrapf(err, "写入第 %d 行失败", rowNum)
+			}
+			rowNum++
+			written++
+			if written > MaxRows {
+				return gerror.Newf("导出行数超过上限 %d 行", MaxRows)
+			}
+		}
+		// 已取满或不足一页，结束
+		if len(rows) < DefaultPageSize || (total > 0 && written >= total) {
+			break
+		}
+	}
+	if err = stream.Flush(); err != nil {
+		return gerror.Wrap(err, "刷新工作表失败")
+	}
+
+	content, err := toBytes(f)
+	if err != nil {
+		return err
+	}
+	if int64(len(content)) > MaxFileSize {
+		return gerror.Newf("导出文件超过 %d MB 上限，请缩小筛选范围", MaxFileSize>>20)
+	}
+
+	oss, err := savePrivateExport(ctx, task, content)
+	if err != nil {
+		return gerror.Wrap(err, "保存导出文件失败")
+	}
+	*generatedPath = oss.Path
+	task.OssId = oss.OssId
+	if err = markSuccess(ctx, task, oss, written, req); err != nil {
+		return err
+	}
+	*generatedPath = ""
+	return nil
+}
+
+func savePrivateExport(ctx context.Context, task *entity.TExportTask, content []byte) (*model.SysOssSaveContentModel, error) {
+	uploadRoot := strings.TrimSpace(g.Cfg().MustGet(ctx, "system.upload.local.path").String())
+	if uploadRoot == "" {
+		return nil, gerror.New("上传路径未配置")
+	}
+	root, err := filepath.Abs(uploadRoot)
+	if err != nil {
+		return nil, err
+	}
+	// 私有目录必须与上传静态根目录隔离，不能生成可访问的 OSS URL。
+	path := filepath.Join(filepath.Dir(root), "private-export", task.TenantId, task.TaskNo+".xlsx")
+	if err = os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return nil, err
+	}
+	registered := false
+	defer func() {
+		if !registered {
+			if removeErr := os.Remove(path); removeErr != nil && !os.IsNotExist(removeErr) {
+				g.Log().Errorf(gctx.New(), "[exportcenter] 清理未登记文件失败 path=%s err=%v", path, removeErr)
+			}
+		}
+	}()
+	if err = os.WriteFile(path, content, 0600); err != nil {
+		return nil, err
+	}
+	md5, err := gmd5.EncryptFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var ossId int64
+	// 这里仅登记元数据；通用 OSS API 拒绝导出文件，实际下载走下载中心。
+	err = g.DB().Transaction(gctx.New(), func(ctx context.Context, tx gdb.TX) error {
+		var insertErr error
+		ossId, insertErr = dao.SysOss.Ctx(ctx).TX(tx).Data(g.Map{
+			dao.SysOss.Columns().TenantId:     task.TenantId,
+			dao.SysOss.Columns().FileName:     task.FileName,
+			dao.SysOss.Columns().OriginalName: task.FileName,
+			dao.SysOss.Columns().FileSuffix:   "xlsx",
+			dao.SysOss.Columns().Path:         path,
+			dao.SysOss.Columns().Url:          "",
+			dao.SysOss.Columns().CreatedDept:  task.DeptId,
+			dao.SysOss.Columns().CreatedBy:    task.OwnerUserId,
+			dao.SysOss.Columns().CreatedAt:    gtime.Now(),
+			dao.SysOss.Columns().Service:      "local",
+			dao.SysOss.Columns().Md5:          md5,
+			dao.SysOss.Columns().FileSize:     len(content),
+			dao.SysOss.Columns().FileCrc16:    hash.Crc16ChecksumFile(path),
+			dao.SysOss.Columns().FileSum:      hash.Sum16ChecksumFile(path),
+		}).InsertAndGetId()
+		if insertErr != nil {
+			return insertErr
+		}
+		affected, updateErr := dao.TExportTask.Ctx(ctx).TX(tx).
+			Data(g.Map{dao.TExportTask.Columns().OssId: ossId}).
+			Where(dao.TExportTask.Columns().Id, task.Id).
+			Where(dao.TExportTask.Columns().Status, consts.DownloadStatusRunning).UpdateAndGetAffected()
+		if updateErr != nil {
+			return updateErr
+		}
+		if affected != 1 {
+			return gerror.New("登记导出文件失败：任务状态已变更")
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	registered = true
+	task.OssId = ossId
+	return &model.SysOssSaveContentModel{SysOss: &entity.SysOss{OssId: ossId, Path: path, FileSize: len(content), Md5: md5}}, nil
+}
+
+func structValues(v interface{}) []interface{} {
+	rv := reflect.ValueOf(v)
+	for rv.Kind() == reflect.Ptr {
+		if rv.IsNil() {
+			return nil
+		}
+		rv = rv.Elem()
+	}
+	if rv.Kind() != reflect.Struct {
+		return []interface{}{v}
+	}
+	fields := rv.NumField()
+	out := make([]interface{}, fields)
+	for i := 0; i < fields; i++ {
+		out[i] = rv.Field(i).Interface()
+	}
+	return out
+}
+
+func toBytes(f *excelize.File) ([]byte, error) {
+	tmp, err := os.CreateTemp("", "iotlcm-export-*.xlsx")
+	if err != nil {
+		return nil, gerror.Wrap(err, "创建临时文件失败")
+	}
+	name := tmp.Name()
+	defer os.Remove(name)
+	defer tmp.Close()
+
+	if err = f.Write(tmp); err != nil {
+		return nil, gerror.Wrap(err, "写入临时文件失败")
+	}
+	if err = tmp.Sync(); err != nil {
+		return nil, gerror.Wrap(err, "刷新临时文件失败")
+	}
+	content, err := os.ReadFile(name)
+	if err != nil {
+		return nil, gerror.Wrap(err, "读取临时文件失败")
+	}
+	return content, nil
+}
+
+func truncateSheetName(name string) string {
+	if name == "" {
+		return "Sheet1"
+	}
+	rs := []rune(name)
+	if len(rs) > 31 {
+		rs = rs[:31]
+	}
+	return string(rs)
+}
+
+func markBatchRunning(ctx context.Context, taskNo string) {
+	_, err := dao.BatchMain.Ctx(ctx).
+		Data(g.Map{
+			dao.BatchMain.Columns().BatchAsyncStatus: consts.BatchAsyncStatusProcessing,
+			dao.BatchMain.Columns().RunResult:        consts.BatchRunResultRunning,
+			dao.BatchMain.Columns().StartTime:        gtime.Now(),
+		}).
+		Where(dao.BatchMain.Columns().BatchNo, taskNo).
+		Update()
+	if err != nil {
+		g.Log().Warningf(ctx, "[exportcenter] 更新执行日志开始状态失败 taskNo=%s err=%v", taskNo, err)
+	}
+}
+
+func markSuccess(ctx context.Context, task *entity.TExportTask, oss *model.SysOssSaveContentModel, written int, req *Request) error {
+	now := gtime.Now()
+	// 默认按全部成功回填；查询类导出可通过 Request.Result 改判为部分成功/失败并写汇总说明。
+	// 注意：即使判定为失败，文件本身仍已生成并可下载（文件里写明每条失败原因），
+	// 因此这里只改执行日志的 async_status/run_result，不改 t_export_task 的下载状态。
+	runResult := consts.BatchRunResultSuccess
+	asyncStatus := consts.BatchAsyncStatusSuccess
+	summary := ""
+	if req != nil && req.Result != nil {
+		if result, text := req.Result(written); result > 0 {
+			runResult = result
+			summary = text
+			switch result {
+			case consts.BatchRunResultPartialSuccess:
+				asyncStatus = consts.BatchAsyncStatusPartialSuccess
+				summary = text
+			case consts.BatchRunResultFailed:
+				asyncStatus = consts.BatchAsyncStatusFailed
+				summary = text
+			default:
+				asyncStatus = consts.BatchAsyncStatusSuccess
+			}
+		}
+	}
+	// 文件已写磁盘，两张表必须同一事务提交；失败保留 OSS 索引供过期清理重试。
+	return g.DB().Transaction(gctx.New(), func(ctx context.Context, tx gdb.TX) error {
+		affected, err := dao.TExportTask.Ctx(ctx).TX(tx).
+			Data(g.Map{
+				dao.TExportTask.Columns().Status:     consts.DownloadStatusGenerated,
+				dao.TExportTask.Columns().OssId:      oss.OssId,
+				dao.TExportTask.Columns().FileSize:   oss.FileSize,
+				dao.TExportTask.Columns().FileMd5:    oss.Md5,
+				dao.TExportTask.Columns().TotalCount: written,
+				dao.TExportTask.Columns().FinishTime: now,
+				dao.TExportTask.Columns().ExpireTime: now.AddDate(0, 0, ExpireDays),
+			}).
+			Where(dao.TExportTask.Columns().Id, task.Id).
+			Where(dao.TExportTask.Columns().Status, consts.DownloadStatusRunning).
+			UpdateAndGetAffected()
+		if err != nil {
+			return gerror.Wrap(err, "回填导出任务失败")
+		}
+		if affected != 1 {
+			return gerror.New("回填导出任务失败：任务状态已变更")
+		}
+		affected, err = dao.BatchMain.Ctx(ctx).TX(tx).
+			Data(g.Map{
+				dao.BatchMain.Columns().BatchAsyncStatus: asyncStatus,
+				dao.BatchMain.Columns().RunResult:        runResult,
+				dao.BatchMain.Columns().FailReason:       summary,
+				dao.BatchMain.Columns().ResultOssId:      oss.OssId,
+				dao.BatchMain.Columns().TotalCount:       written,
+				dao.BatchMain.Columns().EndTime:          now,
+			}).
+			Where(dao.BatchMain.Columns().BatchNo, task.TaskNo).
+			UpdateAndGetAffected()
+		if err != nil {
+			return gerror.Wrap(err, "回填执行日志失败")
+		}
+		if affected != 1 {
+			return gerror.New("回填执行日志失败：记录不存在")
+		}
+		return nil
+	})
+}
+
+func markFailed(ctx context.Context, task *entity.TExportTask, cause error) {
+	// 失败也要落库，用独立 ctx 避免任务 ctx 已超时
+	ctx = gctx.New()
+	msg := cause.Error()
+	if len([]rune(msg)) > 1900 {
+		msg = string([]rune(msg)[:1900])
+	}
+	now := gtime.Now()
+
+	affected, err := dao.TExportTask.Ctx(ctx).
+		Data(g.Map{
+			dao.TExportTask.Columns().Status:       consts.DownloadStatusFailed,
+			dao.TExportTask.Columns().ErrorMessage: msg,
+			dao.TExportTask.Columns().FinishTime:   now,
+		}).
+		Where(dao.TExportTask.Columns().Id, task.Id).
+		WhereNull(dao.TExportTask.Columns().DeletedTime).
+		WhereIn(dao.TExportTask.Columns().Status, []int{consts.DownloadStatusPending, consts.DownloadStatusRunning}).
+		UpdateAndGetAffected()
+	if err != nil {
+		g.Log().Errorf(ctx, "[exportcenter] 回填失败状态失败 taskNo=%s err=%v", task.TaskNo, err)
+		return
+	}
+	if affected == 0 {
+		current := &entity.TExportTask{}
+		if err := dao.TExportTask.Ctx(ctx).Where(dao.TExportTask.Columns().Id, task.Id).Scan(current); err != nil {
+			g.Log().Errorf(ctx, "[exportcenter] 核对失败状态失败 taskNo=%s err=%v", task.TaskNo, err)
+			return
+		}
+		if current.Id == 0 || current.Status != consts.DownloadStatusFailed {
+			return
+		}
+	}
+
+	_, err = dao.BatchMain.Ctx(ctx).
+		Data(g.Map{
+			dao.BatchMain.Columns().BatchAsyncStatus: consts.BatchAsyncStatusFailed,
+			dao.BatchMain.Columns().RunResult:        consts.BatchRunResultFailed,
+			dao.BatchMain.Columns().FailReason:       msg,
+			dao.BatchMain.Columns().EndTime:          now,
+		}).
+		Where(dao.BatchMain.Columns().BatchNo, task.TaskNo).
+		Update()
+	if err != nil {
+		g.Log().Errorf(ctx, "[exportcenter] 回填执行日志失败状态失败 taskNo=%s err=%v", task.TaskNo, err)
+	}
+}
+
+// RecoverOnStart 进程启动时把残留的「排队中/生成中」任务标记为失败。
+// 进程内任务不跨重启恢复，失败后用户可在下载中心点重试重新提交。
+func RecoverOnStart(ctx context.Context) {
+	now := time.Now()
+	_, err := dao.TExportTask.Ctx(ctx).
+		Data(g.Map{
+			dao.TExportTask.Columns().Status:       consts.DownloadStatusFailed,
+			dao.TExportTask.Columns().ErrorMessage: "服务重启，任务已中断，请重新导出",
+			dao.TExportTask.Columns().FinishTime:   now,
+		}).
+		WhereNull(dao.TExportTask.Columns().DeletedTime).
+		WhereIn(dao.TExportTask.Columns().Status, []int{consts.DownloadStatusPending, consts.DownloadStatusRunning}).
+		Update()
+	if err != nil {
+		g.Log().Errorf(ctx, "[exportcenter] 启动补偿失败: %v", err)
+		return
+	}
+
+	_, err = dao.BatchMain.Ctx(ctx).
+		Data(g.Map{
+			dao.BatchMain.Columns().BatchAsyncStatus: consts.BatchAsyncStatusFailed,
+			dao.BatchMain.Columns().RunResult:        consts.BatchRunResultFailed,
+			dao.BatchMain.Columns().FailReason:       "服务重启，任务已中断",
+			dao.BatchMain.Columns().EndTime:          now,
+		}).
+		Where(dao.BatchMain.Columns().BatchType, consts.BatchTypeExport).
+		WhereIn(dao.BatchMain.Columns().BatchAsyncStatus, []int{consts.BatchAsyncStatusCreated, consts.BatchAsyncStatusProcessing}).
+		Update()
+	if err != nil {
+		g.Log().Errorf(ctx, "[exportcenter] 启动补偿执行日志失败: %v", err)
+	}
+}
@@ -0,0 +1,173 @@
+package exportcenter
+
+import (
+	"context"
+	"time"
+
+	"github.com/gogf/gf/v2/database/gdb"
+	"github.com/gogf/gf/v2/encoding/gjson"
+	"github.com/gogf/gf/v2/errors/gerror"
+	"github.com/gogf/gf/v2/frame/g"
+	"github.com/gogf/gf/v2/util/gconv"
+
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/consts"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/dao"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/library/batchimport"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/library/batchmetadata"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/library/contexts"
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model"
+)
+
+func snapshot(ctx context.Context) (*model.ExportIdentitySnapshot, error) {
+	user := contexts.GetUser(ctx)
+	if user == nil || user.ID <= 0 {
+		return nil, gerror.New("登录状态已失效，请重新登录")
+	}
+	snap := &model.ExportIdentitySnapshot{
+		UserId:         user.ID,
+		DeptId:         user.DeptId,
+		TenantId:       user.TenantId,
+		Roles:          user.Roles,
+		AccessCodeList: user.AccessCodeList,
+	}
+	if v := contexts.GetDataValue(ctx, "currentRoleId"); v != nil {
+		snap.CurrentRoleId = gconv.String(v)
+	}
+	if v := contexts.GetDataValue(ctx, "currentRoleDataScope"); v != nil {
+		snap.CurrentRoleDataScope = gconv.String(v)
+	}
+	return snap, nil
+}
+
+// Submit 提交一次导出任务：预校验行数、落任务与执行日志、投递后台执行。
+func Submit(ctx context.Context, req *Request) (res *SubmitResult, err error) {
+	if req == nil || req.Tags == nil || req.Fetch == nil {
+		return nil, gerror.New("导出配置不完整")
+	}
+	if req.BizKey == "" || req.BizName == "" {
+		return nil, gerror.New("导出业务标识不能为空")
+	}
+
+	// 提交前占用执行/排队容量，避免高峰期无限创建等待执行的 goroutine。
+	select {
+	case slots <- struct{}{}:
+	default:
+		return nil, gerror.New("导出任务排队已满，请稍后重试")
+	}
+	ownershipTransferred := false
+	defer func() {
+		if !ownershipTransferred {
+			<-slots
+		}
+	}()
+
+	snap, err := snapshot(ctx)
+	if err != nil {
+		return nil, failSubmit(ctx, "snapshot", req.BizKey, err)
+	}
+
+	// 预校验：只取 1 行，拿到筛选条件下的总行数。
+	// 业务侧可能返回 -1 表示「提交阶段还无法确定条数」（如按号段/按公司圈卡，
+	// 需要后台实际查库才知道命中多少），此时放行，最终条数以实际写出为准。
+	// total=0 也放行：空结果同样要产出文件（至少带表头与失败原因列），
+	// 让用户能拿到「查了但没命中」的凭据，而不是只看到一句报错。
+	_, total, err := req.Fetch(ctx, 1, 1)
+	if err != nil {
+		return nil, failSubmit(ctx, "count", req.BizKey, gerror.Wrap(err, "统计导出数据失败"))
+	}
+	if total > MaxRows {
+		return nil, gerror.Newf("本次导出 %d 行，超过单次上限 %d 行，请缩小筛选范围", total, MaxRows)
+	}
+	// 未知条数不写入任务记录，避免 -1 出现在列表与执行日志里。
+	recordedTotal := total
+	if recordedTotal < 0 {
+		recordedTotal = 0
+	}
+
+	taskNo, err := batchimport.NextBatchNo(consts.BatchNoPrefixExport)
+	if err != nil {
+		return nil, failSubmit(ctx, "batch_no", req.BizKey, gerror.Wrap(err, "生成任务编号失败"))
+	}
+
+	// 列清单直接影响导出内容，留痕便于排查「导出列与页面不一致」。
+	if len(req.Columns) == 0 {
+		req.Columns = columnsFromRequest(ctx)
+	}
+	g.Log().Infof(ctx, "[exportcenter] 提交导出 biz=%s user=%d columns=%d", req.BizKey, snap.UserId, len(req.Columns))
+
+	now := time.Now()
+	expire := now.AddDate(0, 0, ExpireDays)
+	fileName := taskNo + ".xlsx"
+
+	batchInfo := gjson.New(g.Map{
+		"exportBizKey":  req.BizKey,
+		"exportBizName": req.BizName,
+		"permCode":      req.PermCode,
+	})
+
+	var taskId int64
+	err = g.DB().Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
+		id, insertErr := dao.TExportTask.Ctx(ctx).TX(tx).Data(g.Map{
+			dao.TExportTask.Columns().TaskNo:           taskNo,
+			dao.TExportTask.Columns().BizKey:           req.BizKey,
+			dao.TExportTask.Columns().BizName:          req.BizName,
+			dao.TExportTask.Columns().PermCode:         req.PermCode,
+			dao.TExportTask.Columns().QueryParams:      gjson.New(req.QueryParam),
+			dao.TExportTask.Columns().IdentitySnapshot: gjson.New(snap),
+			dao.TExportTask.Columns().Status:           consts.DownloadStatusPending,
+			dao.TExportTask.Columns().TotalCount:       recordedTotal,
+			dao.TExportTask.Columns().FileName:         fileName,
+			dao.TExportTask.Columns().OwnerUserId:      snap.UserId,
+			dao.TExportTask.Columns().DeptId:           snap.DeptId,
+			dao.TExportTask.Columns().TenantId:         snap.TenantId,
+			dao.TExportTask.Columns().CreatedDept:      snap.DeptId,
+			dao.TExportTask.Columns().CreatedBy:        snap.UserId,
+			dao.TExportTask.Columns().CreatedAt:        now,
+			dao.TExportTask.Columns().ExpireTime:       expire,
+		}).InsertAndGetId()
+		if insertErr != nil {
+			return gerror.Wrap(insertErr, "创建导出任务失败")
+		}
+		taskId = id
+
+		_, insertErr = dao.BatchMain.Ctx(ctx).TX(tx).Data(g.Map{
+			dao.BatchMain.Columns().BatchNo:          taskNo,
+			dao.BatchMain.Columns().BatchType:        consts.BatchTypeExport,
+			dao.BatchMain.Columns().BatchStatus:      consts.BatchStatusNormal,
+			dao.BatchMain.Columns().BatchAsyncStatus: consts.BatchAsyncStatusCreated,
+			dao.BatchMain.Columns().SourceChannel:    batchmetadata.Console,
+			dao.BatchMain.Columns().ExecutionMode:    batchmetadata.Bulk,
+			dao.BatchMain.Columns().RunResult:        consts.BatchRunResultPending,
+			dao.BatchMain.Columns().TotalCount:       recordedTotal,
+			dao.BatchMain.Columns().BatchInfo:        batchInfo,
+			dao.BatchMain.Columns().TenantId:         snap.TenantId,
+			dao.BatchMain.Columns().CreatedDept:      snap.DeptId,
+			// dept_id 必须与 created_dept 一致。
+			// FilterAuth 对 batch_main 优先用 dept_id 过滤，留空(NUL)会让提交人自己也看不到
+			// 这条执行日志（只有全部数据权限的管理员能看到），表现为「导出了但日志里没有」。
+			dao.BatchMain.Columns().DeptId:    snap.DeptId,
+			dao.BatchMain.Columns().CreatedBy: snap.UserId,
+			dao.BatchMain.Columns().CreatedAt: now,
+		}).Insert()
+		if insertErr != nil {
+			return gerror.Wrap(insertErr, "写导出执行日志失败")
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, failSubmit(ctx, "persist", req.BizKey, err)
+	}
+
+	go run(taskNo, req)
+	ownershipTransferred = true
+
+	return &SubmitResult{TaskId: taskId, TaskNo: taskNo, Total: total}, nil
+}
+
+// failSubmit 统一记录提交失败的环节与原因。
+// 框架会把未带错误码的 error 统一转成「内部服务器错误」，真实原因只能从日志看，
+// 所以这里必须把 step 打出来，否则线上无法定位。
+func failSubmit(ctx context.Context, step, bizKey string, err error) error {
+	g.Log().Errorf(ctx, "[exportcenter] 提交导出失败 step=%s biz=%s err=%+v", step, bizKey, err)
+	return err
+}
@@ -0,0 +1,76 @@
+// Package exportcenter 通用异步导出中心。
+//
+// 调用方在导出接口里只负责描述「怎么取一页数据」，提交、排队、生成文件、
+// 落 OSS、写执行日志、失败回填都由本包完成。
+//
+// 注意事项：
+//   - 异步执行不持有 HTTP 上下文，必须靠提交时的身份快照还原 ctx，
+//     否则 FilterAuth 取不到用户会漏掉部门数据权限。
+//   - 导出批次只写 batch_main，不写 batch_detail；执行日志中的运行结果
+//     跟随导出任务状态更新，因此不会出现在批次管理页，只出现在执行日志页。
+package exportcenter
+
+import (
+	"context"
+	"time"
+
+	"git.5iot.com/iotlcm-public/iotlcm-admin-svr/internal/model"
+)
+
+const (
+	// DefaultPageSize 每次从业务侧取多少行
+	DefaultPageSize = 2000
+	// MaxRows 单任务行数上限（Excel 硬上限 104 万，留出余量）
+	MaxRows = 500000
+	// MaxFileSize 单文件大小上限
+	MaxFileSize int64 = 100 << 20
+	// MaxConcurrent 同时执行的导出任务数
+	MaxConcurrent = 2
+	// MaxQueued 允许等待执行的导出任务数（单实例）
+	MaxQueued = 20
+	// ExpireDays 文件保留天数
+	ExpireDays = 3
+	// TaskTimeout 单任务超时
+	TaskTimeout = 10 * time.Minute
+)
+
+// Request 一次导出请求的完整描述
+type Request struct {
+	BizKey     string      // 业务标识，如 tSimCardInfo
+	BizName    string      // 业务名称，如 卡信息
+	PermCode   string      // 接口权限码快照，K1 用
+	SheetName  string      // Excel sheet 名，留空则用 BizName
+	QueryParam interface{} // 筛选条件快照，落库备查
+	// Columns 可选：前端传入的「当前列表显示列」，顺序即导出列顺序。
+	// 非空时按 Field（列表模型 json tag）逐行取值、Label 作表头；
+	// 为空时沿用 Tags + 结构体字段顺序（兼容尚未改造的导出）。
+	Columns []model.ExportColumn
+	// RowFields 可选：自定义 ToRow 取值时，声明 ToRow 返回值与字段名的对应顺序，
+	// 这样按列表列导出时仍能复用 ToRow 的格式化结果。为空则直接从结构体取值。
+	RowFields []string
+	// Tags 表头，通常 convert.GetEntityDescTags(model.XxxExportModel{})
+	Tags func() ([]string, error)
+	// Fetch 取一页数据。page 从 1 开始；返回的 total 必须为筛选条件下的总行数。
+	// rows 里每个元素应是结构体或结构体指针，字段顺序即列顺序。
+	Fetch func(ctx context.Context, page, pageSize int) (rows []interface{}, total int, err error)
+	// ToRow 可选：自定义「结构体 -> 行」的转换（如需要状态名、时间格式化）。
+	// 为空时按结构体字段顺序取值。
+	ToRow func(v interface{}) []interface{}
+	// Result 可选：文件生成完成后回填执行结果汇总。
+	// 用于「按输入逐条反馈」的查询类导出：全部命中记为成功，部分未命中记为部分成功。
+	// 返回的 runResult 取 consts.BatchRunResult*；summary 写入执行日志的失败原因/汇总说明。
+	// 为空时保持历史行为（一律成功）。
+	Result func(written int) (runResult int, summary string)
+}
+
+// SubmitResult 提交结果
+type SubmitResult struct {
+	TaskId int64  `json:"taskId" dc:"任务ID"`
+	TaskNo string `json:"taskNo" dc:"任务编号"`
+	Total  int    `json:"total" dc:"预计导出行数"`
+}
+
+// Snapshot 由 ctx 生成身份快照
+func Snapshot(ctx context.Context) (*model.ExportIdentitySnapshot, error) {
+	return snapshot(ctx)
+}