增加导出数据到Excel的方法

factory/factory.go

@@ -10,6 +10,7 @@ import (
 
 	"git.toowon.com/jimmy/go-common/config"
 	"git.toowon.com/jimmy/go-common/email"
+	"git.toowon.com/jimmy/go-common/excel"
 	commonhttp "git.toowon.com/jimmy/go-common/http"
 	"git.toowon.com/jimmy/go-common/i18n"
 	"git.toowon.com/jimmy/go-common/logger"
@@ -121,6 +122,7 @@ type Factory struct {
 	db      *gorm.DB        // 数据库连接（延迟初始化）
 	redis   *redis.Client   // Redis客户端（延迟初始化）
 	i18n    *i18n.I18n      // 国际化工具（延迟初始化）
+	excel   *excel.Excel    // Excel导出器（延迟初始化）
 }
 
 // NewFactory 创建工厂实例
@@ -1553,3 +1555,109 @@ func (f *Factory) GetMessage(lang, code string, args ...interface{}) string {
 func (f *Factory) GetI18n() (*i18n.I18n, error) {
 	return f.getI18n()
 }
+
+// ========== Excel 导出工具（黑盒模式，推荐使用） ==========
+//
+// 这些方法提供数据导出到Excel的功能，支持结构体切片和自定义数据格式。
+
+// getExcelClient 获取Excel导出器实例（内部方法，延迟初始化）
+func (f *Factory) getExcelClient() (*excel.Excel, error) {
+	if f.excel != nil {
+		return f.excel, nil
+	}
+
+	f.excel = excel.NewExcel()
+	return f.excel, nil
+}
+
+// GetExcel 获取Excel导出器对象（高级功能时使用）
+// 返回已初始化的Excel导出器对象
+//
+// ℹ️  推荐使用黑盒方法：
+//   - ExportToExcel()：导出到Writer
+//   - ExportToExcelFile()：导出到文件
+//
+// 仅在需要使用高级功能时获取对象：
+//   - 多工作表操作
+//   - 自定义样式
+//   - 图表、公式等高级功能
+//
+// 示例（常用操作，推荐）：
+//
+//	fac.ExportToExcel(w, "用户列表", columns, users)
+//
+// 示例（高级功能）：
+//
+//	excel, _ := fac.GetExcel()
+//	file := excel.GetFile()
+//	file.NewSheet("Sheet2")
+func (f *Factory) GetExcel() (*excel.Excel, error) {
+	return f.getExcelClient()
+}
+
+// ExportColumn Excel导出列定义（暴露给外部项目使用）
+// 外部项目可以直接使用 factory.ExportColumn 创建列定义
+type ExportColumn = excel.ExportColumn
+
+// ExportToExcel 导出数据到Writer（黑盒模式，推荐使用）
+// w: Writer对象（如http.ResponseWriter）
+// sheetName: 工作表名称（可选，默认为"Sheet1"）
+// columns: 列定义
+// data: 数据列表（可以是结构体切片或实现了ExportData接口的对象）
+// 返回错误信息
+//
+// 示例1：导出结构体切片
+//
+//	type User struct {
+//	    ID    int    `json:"id"`
+//	    Name  string `json:"name"`
+//	    Email string `json:"email"`
+//	}
+//
+//	users := []User{
+//	    {ID: 1, Name: "Alice", Email: "alice@example.com"},
+//	    {ID: 2, Name: "Bob", Email: "bob@example.com"},
+//	}
+//
+//	columns := []factory.ExportColumn{
+//	    {Header: "ID", Field: "ID"},
+//	    {Header: "姓名", Field: "Name"},
+//	    {Header: "邮箱", Field: "Email"},
+//	}
+//
+//	fac.ExportToExcel(w, "用户列表", columns, users)
+//
+// 示例2：使用格式化函数
+//
+//	columns := []factory.ExportColumn{
+//	    {Header: "ID", Field: "ID"},
+//	    {Header: "姓名", Field: "Name"},
+//	    {Header: "创建时间", Field: "CreatedAt", Format: excel.FormatDateTimeDefault},
+//	}
+//
+//	fac.ExportToExcel(w, "用户列表", columns, users)
+func (f *Factory) ExportToExcel(w io.Writer, sheetName string, columns []ExportColumn, data interface{}) error {
+	e, err := f.getExcelClient()
+	if err != nil {
+		return err
+	}
+	return e.ExportToWriter(w, sheetName, columns, data)
+}
+
+// ExportToExcelFile 导出数据到文件（黑盒模式，推荐使用）
+// filePath: 文件路径
+// sheetName: 工作表名称（可选，默认为"Sheet1"）
+// columns: 列定义
+// data: 数据列表
+// 返回错误信息
+//
+// 示例：
+//
+//	fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
+func (f *Factory) ExportToExcelFile(filePath string, sheetName string, columns []ExportColumn, data interface{}) error {
+	e, err := f.getExcelClient()
+	if err != nil {
+		return err
+	}
+	return e.ExportToFile(filePath, sheetName, columns, data)
+}