docs: Add CLAUDE.md with codebase guidance

Create comprehensive documentation for future Claude Code instances working in this repository, including:
- Development commands for testing, building, and code quality
- Core architecture overview of the SQL query builder system
- Directory structure and component explanations
- Testing patterns and conventions
- Key dependencies and their purposes

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

exec/scanner.go

@@ -2,11 +2,11 @@ package exec
 
 import (
 	"database/sql"
+	"encoding/json"
 	"reflect"
 
-	"git.fsdpf.net/go/db/v2/exp"
-	"git.fsdpf.net/go/db/v2/internal/errors"
-	"git.fsdpf.net/go/db/v2/internal/util"
+	"git.fsdpf.net/go/db/internal/errors"
+	"git.fsdpf.net/go/db/internal/util"
 )
 
 type (
@@ -17,6 +17,8 @@ type (
 		ScanStructs(i interface{}) error
 		ScanVal(i interface{}) error
 		ScanVals(i interface{}) error
+		GetRecord() (map[string]any, error)
+		GetRecords() ([]map[string]any, error)
 		Close() error
 		Err() error
 	}
@@ -49,6 +51,86 @@ func (s *scanner) Err() error {
 	return s.rows.Err()
 }
 
+func (s *scanner) GetRecords() ([]map[string]any, error) {
+	records := []map[string]any{}
+	for s.Next() {
+		row, err := s.GetRecord()
+		if err != nil {
+			return records, err
+		}
+		records = append(records, row)
+	}
+
+	return records, s.Err()
+}
+
+func (s *scanner) GetRecord() (record map[string]any, err error) {
+	// Setup columns, but only once.
+	if s.columns == nil || s.columnMap == nil {
+		colsType, err := s.rows.ColumnTypes()
+		if err != nil {
+			return nil, err
+		}
+
+		s.columns = make([]string, len(colsType))
+		s.columnMap = util.ColumnMap{}
+		for i := range colsType {
+			s.columns[i] = colsType[i].Name()
+
+			typ := colsType[i].ScanType()
+
+			// 强制日期时间为字符串
+			if typ == reflect.TypeOf(sql.NullTime{}) {
+				typ = reflect.TypeOf(sql.Null[[]uint8]{})
+			}
+
+			s.columnMap[colsType[i].Name()] = util.ColumnData{
+				ColumnName: colsType[i].Name(),
+				GoType:     typ,
+			}
+		}
+	}
+
+	scans := make([]interface{}, len(s.columns))
+
+	for i, col := range s.columns {
+		scans[i] = reflect.New(s.columnMap[col].GoType).Interface()
+	}
+
+	if err := s.rows.Scan(scans...); err != nil {
+		return nil, err
+	}
+
+	record = make(map[string]interface{}, len(s.columns))
+	for i, col := range s.columns {
+		var vv any
+		switch v := scans[i].(type) {
+		case *sql.Null[[]uint8]: // 强制日期时间为字符串
+			if vv, err = v.Value(); err == nil && vv != nil {
+				vv = string(vv.([]uint8))
+			}
+		case *sql.RawBytes:
+			if len(*v) > 1 {
+				if rune((*v)[0]) == rune('[') || rune((*v)[0]) == rune('{') {
+					err = json.Unmarshal(*v, &vv)
+				} else {
+					vv = string(*v)
+				}
+			} else {
+				vv = string(*v)
+			}
+		default:
+			vv = reflect.Indirect(reflect.ValueOf(v)).Interface()
+		}
+		if err != nil {
+			return
+		}
+		record[col] = vv
+	}
+
+	return record, s.Err()
+}
+
 // ScanStruct will scan the current row into i.
 func (s *scanner) ScanStruct(i interface{}) error {
 	// Setup columnMap and columns, but only once.
@@ -63,35 +145,37 @@ func (s *scanner) ScanStruct(i interface{}) error {
 			return err
 		}
 
+		// 补全未知字段类型
+		if len(cols) != len(cm) {
+			colTypes, err := s.rows.ColumnTypes()
+			if err != nil {
+				return err
+			}
+			for _, t := range colTypes {
+				if _, ok := cm[t.Name()]; !ok {
+					cm[t.Name()] = util.ColumnData{
+						ColumnName: t.Name(),
+						GoType:     t.ScanType(),
+					}
+				}
+			}
+		}
+
 		s.columnMap = cm
 		s.columns = cols
 	}
 
-	scans := make([]interface{}, 0, len(s.columns))
-	for _, col := range s.columns {
-		data, ok := s.columnMap[col]
+	scans, err := createColumnScans(s.columns, s.columnMap)
 
-		if !ok {
-			return unableToFindFieldError(col)
-		}
-		// 处理 converting NULL to string is unsupported
-		// 前面将 string 和 int 类型转为了 *string 和 *int
-		switch data.GoType.Kind() {
-		case reflect.String,
-			reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
-			reflect.Float32, reflect.Float64,
-			reflect.Bool:
-			scans = append(scans, reflect.New(reflect.PointerTo(data.GoType)).Interface())
-		default:
-			scans = append(scans, reflect.New(data.GoType).Interface())
-		}
+	if err != nil {
+		return err
 	}
 
 	if err := s.rows.Scan(scans...); err != nil {
 		return err
 	}
 
-	record := exp.Record{}
+	record := map[string]interface{}{}
 	for index, col := range s.columns {
 		record[col] = scans[index]
 	}
@@ -175,3 +259,30 @@ func checkScanValsTarget(i interface{}) (reflect.Value, error) {
 	}
 	return val, nil
 }
+
+func createColumnScans(cols []string, cm util.ColumnMap) (scans []interface{}, err error) {
+	scans = make([]interface{}, 0, len(cols))
+
+	for _, col := range cols {
+		data, ok := cm[col]
+
+		if !ok {
+			return scans, unableToFindFieldError(col)
+		}
+		// 处理 converting NULL to string is unsupported
+		// 前面将 string 和 int 类型转为了 *string 和 *int
+		switch data.GoType.Kind() {
+		case reflect.String,
+			reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
+			reflect.Float32, reflect.Float64,
+			reflect.Bool:
+			scans = append(scans, reflect.New(reflect.PointerTo(data.GoType)).Interface())
+		case reflect.Map, reflect.Slice, reflect.Struct:
+			scans = append(scans, reflect.New(reflect.PointerTo(reflect.TypeOf(json.RawMessage{}))).Interface())
+		default:
+			scans = append(scans, reflect.New(data.GoType).Interface())
+		}
+	}
+
+	return scans, nil
+}