// 研究库文本 codec 适配:数据库用 SOH 转义 NUL,API 返回前还原原始文本。 package research import ( "database/sql" "errors" "strings" ) // Matches Paper Atlas repair 4e62710's nul-soh-v1 protocol: NUL -> SOH/SOH and literal // SOH -> SOH/STX. All other bytes retain their original binary ordering. const textCodec = "nul-soh-v1" // encodedSchema 仅识别精确协议版本;无标注视为普通文本,未知版本阻止启动,避免错误解码。 func encodedSchema(annotation sql.NullString) (bool, error) { const prefix = "paper-atlas:text-codec=" if !annotation.Valid || !strings.HasPrefix(annotation.String, prefix) { return false, nil } if strings.TrimPrefix(annotation.String, prefix) != textCodec { return false, errors.New("unsupported research text codec") } return true, nil } // encodeText 必须先转义 SOH 再转义 NUL,防止第二次替换改写刚生成的转义序列。 func encodeText(value string) string { return strings.ReplaceAll(strings.ReplaceAll(value, "\x01", "\x01\x02"), "\x00", "\x01\x01") } // decodeText 逐段复制普通字节,仅接受 SOH/SOH 与 SOH/STX;残缺或未知转义立即报错。 func decodeText(value string) (string, error) { if !strings.ContainsRune(value, '\x01') { return value, nil } var result strings.Builder for { position := strings.IndexByte(value, 1) if position < 0 { result.WriteString(value) return result.String(), nil } result.WriteString(value[:position]) if position+1 >= len(value) { return "", errors.New("invalid research text escape") } switch value[position+1] { case 1: result.WriteByte(0) case 2: result.WriteByte(1) default: return "", errors.New("invalid research text escape") } value = value[position+2:] } } // textColumn 实现 sql.Scanner,把可选 codec 与目标字段的 NULL 语义集中处理。 type textColumn struct { encoded bool target any } // Scan 先用 NullString 接收驱动值,再按 schema 解码;非空字符串目标不允许数据库 NULL。 func (column textColumn) Scan(source any) error { var value sql.NullString if err := value.Scan(source); err != nil { return err } if value.Valid && column.encoded { var err error value.String, err = decodeText(value.String) if err != nil { return err } } switch target := column.target.(type) { case *string: if !value.Valid { return errors.New("unexpected null research text") } *target = value.String case *sql.NullString: *target = value default: return errors.New("unsupported research text destination") } return nil } // text 在 scanPaper/enrich 中包装文本列,避免遗漏对来源元数据或主题的解码。 func (r *PostgresRepository) text(target any) sql.Scanner { return textColumn{encoded: r.encoded, target: target} }