censor

README

Censor - 强大的业务审核系统

Censor 是一个功能强大的内容审核 Go 组件库，支持多云厂商（阿里云、华为云、腾讯云）、多种内容类型（文字、图片、视频）、灵活的审核策略和业务回调机制。

特性

• 多云厂商支持: 阿里云、华为云、腾讯云内容审核 API 集成
• 多内容类型: 文字（同步）、图片（同步/异步）、视频（异步）
• 智能文本合并: 多段文本合并审核，节省 API 调用次数
• 多厂商串联: 先阿里后华为，可配置触发条件和合并策略
• 人工审核对接: 统一的人审接口，支持工单系统集成
• 违规内容留存: 完整的违规证据保存，支持申诉和审计
• 业务状态回调: Hook 机制驱动业务状态变更，无需硬编码
• 多数据库支持: MySQL、PostgreSQL、TiDB、ScyllaDB
• 可见性策略: 灵活的内容展示策略（全部通过/部分允许/创作者可见）

安装

go get github.com/heibot/censor

快速开始

1. 初始化数据库

选择适合你的数据库，执行对应的 SQL 文件：

# MySQL
mysql -u root -p your_database < store/migrations/mysql.sql

# PostgreSQL
psql -U postgres -d your_database -f store/migrations/postgres.sql

# TiDB
mysql -h tidb-host -P 4000 -u root -D your_database < store/migrations/tidb.sql

# ScyllaDB
cqlsh -f store/migrations/scylla.cql

2. 创建 Censor 客户端

package main

import (
    "context"
    "database/sql"
    "log"

    censor "github.com/heibot/censor"
    "github.com/heibot/censor/client"
    "github.com/heibot/censor/hooks"
    "github.com/heibot/censor/providers"
    "github.com/heibot/censor/providers/aliyun"
    "github.com/heibot/censor/providers/huawei"
    sqlstore "github.com/heibot/censor/store/sql"

    _ "github.com/go-sql-driver/mysql"
)

func main() {
    // 连接数据库
    db, _ := sql.Open("mysql", "user:pass@tcp(localhost:3306)/censor")
    store := sqlstore.NewWithDB(db, sqlstore.DialectMySQL)

    // 初始化云厂商
    ali := aliyun.New(aliyun.Config{
        ProviderConfig: providers.ProviderConfig{
            AccessKeyID:     "your-key",
            AccessKeySecret: "your-secret",
        },
    })

    hw := huawei.New(huawei.DefaultConfig())

    // 实现业务回调
    myHooks := hooks.FuncHooks{
        OnBizDecisionChangedFunc: func(ctx context.Context, e hooks.BizDecisionChangedEvent) error {
            // 在这里更新你的业务状态
            switch e.Outcome.Decision {
            case censor.DecisionPass:
                // 发布内容
            case censor.DecisionBlock:
                // 隐藏或替换内容
            case censor.DecisionReview:
                // 进入人工审核队列
            }
            return nil
        },
    }

    // 创建客户端
    cli, _ := client.New(client.Options{
        Store:     store,
        Hooks:     myHooks,
        Providers: []providers.Provider{ali, hw},
        Pipeline: client.PipelineConfig{
            Primary:   "aliyun",
            Secondary: "huawei",
            Trigger:   client.DefaultTriggerRule(),
            Merge:     client.MergeMostStrict,
        },
    })

    // 提交审核
    result, _ := cli.Submit(context.Background(), client.SubmitInput{
        Biz: censor.BizContext{
            BizType: censor.BizNoteBody,
            BizID:   "note_123",
            Field:   "body",
        },
        Resources: []censor.Resource{
            {ResourceID: "r1", Type: censor.ResourceText, ContentText: "内容..."},
            {ResourceID: "r2", Type: censor.ResourceImage, ContentURL: "https://..."},
        },
    })

    log.Printf("Review ID: %s", result.BizReviewID)
}

架构设计

┌─────────────────────────────────────────────────────────────────┐
│                         业务系统                                  │
│  (用户服务、笔记服务、聊天服务...)                                 │
└─────────────────────────────────────────────────────────────────┘
                              │ Submit
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Censor Client                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  Pipeline   │  │ TextMerge   │  │   Dedup     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Aliyun    │      │   Huawei    │      │  Tencent    │
│  Provider   │      │  Provider   │      │  Provider   │
└─────────────┘      └─────────────┘      └─────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Violation Translator                          │
│  (统一违规语义层 - 将厂商标签转换为内部标准)                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Hooks                                    │
│  OnBizDecisionChanged  │  OnViolationDetected  │  ...           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Store                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ MySQL    │  │ Postgres │  │  TiDB    │  │ ScyllaDB │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
└─────────────────────────────────────────────────────────────────┘

核心概念

资源类型 (ResourceType)

类型	说明	同步支持	异步支持
text	文本内容	✓	✓
image	图片	✓	✓
video	视频	✗	✓

业务类型 (BizType)

BizUserAvatar   // 用户头像
BizUserNickname // 用户昵称
BizUserBio      // 用户简介
BizNoteTitle    // 笔记标题
BizNoteBody     // 笔记正文
BizNoteImages   // 笔记图片
BizNoteVideos   // 笔记视频
BizChatMessage  // 聊天消息
BizDanmaku      // 弹幕
// ...

审核决策 (Decision)

决策	说明	建议处理
pass	通过	正常展示
review	需人审	暂不展示或创作者可见
block	拦截	隐藏或替换
error	错误	重试或人工介入

替换策略 (ReplacePolicy)

策略	说明
none	不替换，直接隐藏
default_value	使用默认值替换
mask	打码处理

多厂商串联

Pipeline: client.PipelineConfig{
    Primary:   "aliyun",   // 主审核厂商
    Secondary: "huawei",   // 二次审核厂商
    Trigger: client.TriggerRule{
        OnDecisions: map[censor.Decision]bool{
            censor.DecisionBlock:  true,  // 阿里拦截时，触发华为
            censor.DecisionReview: true,  // 阿里人审时，触发华为
        },
    },
    Merge: client.MergeMostStrict, // 取最严格的结果
}

合并策略

策略	说明
most_strict	取最严格结果 (block > review > pass)
majority	多数表决
any	任一拦截即拦截
all	全部拦截才拦截

文本合并优化

// 多段文本合并审核，通过则全部通过，拦截再拆分定位
cli.Submit(ctx, client.SubmitInput{
    Biz: biz,
    Resources: []censor.Resource{
        {ResourceID: "title", Type: censor.ResourceText, ContentText: "标题"},
        {ResourceID: "body",  Type: censor.ResourceText, ContentText: "正文"},
        {ResourceID: "tag1",  Type: censor.ResourceText, ContentText: "标签1"},
    },
    EnableTextMerge: true, // 开启合并
})

可见性策略

import "github.com/heibot/censor/visibility"

renderer := visibility.NewRenderer()

// 渲染用户资料
result := renderer.RenderUserProfile(
    visibility.ViewerPublic,  // 查看者角色
    "viewer_id",
    "user_id",
    "原始昵称",
    "原始简介",
    "avatar_url",
    bindings, // 从数据库获取的绑定状态
)

if result.Visible {
    for field, rendered := range result.Fields {
        if rendered.IsReplaced {
            // 使用替换后的值
            display(rendered.Value)
        } else {
            display(rendered.Value)
        }
    }
}

可见性策略类型

策略	说明
all_or_nothing	任一不通过，整体不可见
partial_allowed	部分不通过，其他仍可见
creator_only_during_review	审核中仅创作者可见
always_visible	始终可见（使用替换值）

处理异步回调

// HTTP 处理器
func handleAliyunCallback(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    headers := make(map[string]string)
    for k, v := range r.Header {
        headers[k] = v[0]
    }

    err := censorClient.HandleCallback(r.Context(), "aliyun", headers, body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    w.WriteHeader(http.StatusOK)
}

统一违规语义

Censor 提供统一的违规语义层，将不同厂商的标签转换为内部标准：

import "github.com/heibot/censor/violation"

// 违规领域
violation.DomainPornography  // 色情
violation.DomainViolence     // 暴力
violation.DomainPolitics     // 政治
violation.DomainSpam         // 垃圾信息
// ...

// 违规标签
violation.TagNudity          // 裸露
violation.TagHateRace        // 种族仇恨
violation.TagSpamAds         // 广告
// ...

目录结构

censor/
├── consts.go           # 常量定义
├── types.go            # 核心类型
├── errors.go           # 错误定义
├── client/             # 客户端
│   ├── client.go       # 主客户端
│   ├── options.go      # 配置选项
│   └── pipeline.go     # 审核流水线
├── providers/          # 云厂商适配
│   ├── provider.go     # 接口定义
│   ├── aliyun/         # 阿里云
│   ├── huawei/         # 华为云
│   ├── tencent/        # 腾讯云
│   └── manual/         # 人工审核
├── store/              # 数据存储
│   ├── store.go        # 接口定义
│   ├── sql/            # SQL 实现
│   └── migrations/     # 数据库脚本
├── hooks/              # 业务回调
│   ├── hooks.go        # 接口定义
│   └── event.go        # 事件类型
├── violation/          # 违规语义
│   ├── domain.go       # 违规领域
│   ├── tag.go          # 违规标签
│   ├── unified.go      # 统一模型
│   └── translator.go   # 翻译器
├── visibility/         # 可见性
│   ├── policy.go       # 策略定义
│   └── render.go       # 渲染器
├── utils/              # 工具函数
│   ├── hash.go         # 哈希
│   ├── textmerge.go    # 文本合并
│   └── idgen.go        # ID 生成
└── example/            # 使用示例
    └── main.go

数据库表

表名	说明
biz_review	业务审核单
resource_review	资源审核记录
provider_task	厂商任务记录
censor_binding	当前绑定状态
censor_binding_history	状态变更历史
violation_snapshot	违规证据快照

最佳实践

1. 使用 Hook 而非硬编码: 业务状态变更通过 Hook 实现，保持解耦
2. 启用内容去重: 相同内容无需重复审核，节省成本
3. 合理配置文本合并: 短文本合并可显著减少 API 调用
4. 串联多厂商: 重要内容建议多厂商交叉验证
5. 保留违规证据: 便于申诉和法务需求
6. 监控异步任务: 定期轮询未完成的异步任务

License

MIT License - 详见 LICENSE

贡献

欢迎提交 Issue 和 Pull Request！

支持

• 文档: https://github.com/heibot/censor
• Issues: https://github.com/heibot/censor/issues

Documentation

Overview

Package censor provides a powerful content moderation system supporting multiple cloud providers (Aliyun, Huawei, Tencent), multiple content types (text, image, video), and flexible review policies.

Index

• Constants
• Variables
• func IsAuthError(err error) bool
• func IsConfigError(err error) bool
• func IsNetworkError(err error) bool
• func IsProviderError(err error) bool
• func IsRateLimitError(err error) bool
• func IsRetryable(err error) bool
• func IsStoreError(err error) bool
• func IsValidationError(err error) bool
• func WrapNetworkError(err error) error
• type BizContext
• type BizReview
• type BizType
• type CensorBinding
• type CensorBindingHistory
• type Decision
• type ErrorCategory
  • func GetErrorCategory(err error) ErrorCategory
• type FinalOutcome
• type HistorySource
• type MergedText
• type PartIndex
• type PendingTask
• type ProviderError
  • func NewProviderError(provider, code, message string) *ProviderError
  • func (e *ProviderError) Error() string
  • func (e *ProviderError) Unwrap() error
  • func (e *ProviderError) WithCategory(cat ErrorCategory) *ProviderError
  • func (e *ProviderError) WithCause(err error) *ProviderError
  • func (e *ProviderError) WithRaw(raw any) *ProviderError
  • func (e *ProviderError) WithStatusCode(code int) *ProviderError
• type ProviderTask
• type Reason
• type ReplacePolicy
• type Resource
• type ResourceReview
• type ResourceType
• type ReviewResult
• type ReviewStatus
• type RiskLevel
  • func (r RiskLevel) String() string
• type StoreError
  • func NewStoreError(operation, table string, err error) *StoreError
  • func (e *StoreError) Error() string
  • func (e *StoreError) Unwrap() error
• type TextMergeStrategy
• type ValidationError
  • func NewValidationError(field, message string) *ValidationError
  • func (e *ValidationError) Error() string
• type ViolationSnapshot

Constants

const (
	DefaultTextMergeMaxLen    = 1800
	DefaultTextMergeSeparator = "\n---\n"
	DefaultAsyncPollInterval  = 5  // seconds
	DefaultAsyncPollTimeout   = 60 // seconds
)

Default configuration values

Variables

var (
	ErrNoResources        = errors.New("censor: no resources provided")
	ErrInvalidResource    = errors.New("censor: invalid resource")
	ErrProviderNotFound   = errors.New("censor: provider not found")
	ErrStoreNotConfigured = errors.New("censor: store not configured")
	ErrTaskNotFound       = errors.New("censor: task not found")
	ErrCallbackInvalid    = errors.New("censor: callback signature invalid")
	ErrTimeout            = errors.New("censor: operation timeout")
	ErrRateLimited        = errors.New("censor: rate limited by provider")
	ErrContentTooLarge    = errors.New("censor: content exceeds size limit")
	ErrUnsupportedType    = errors.New("censor: unsupported resource type")
	ErrDuplicateSubmit    = errors.New("censor: duplicate submission")
	ErrRevisionConflict   = errors.New("censor: revision conflict, stale update")

	// Network errors
	ErrNetworkUnreachable = errors.New("censor: network unreachable")
	ErrConnectionRefused  = errors.New("censor: connection refused")
	ErrDNSResolution      = errors.New("censor: DNS resolution failed")

	// Auth errors
	ErrAuthFailed        = errors.New("censor: authentication failed")
	ErrPermissionDenied  = errors.New("censor: permission denied")
	ErrInvalidCredential = errors.New("censor: invalid credentials")

	// Config errors
	ErrMissingConfig    = errors.New("censor: missing required configuration")
	ErrInvalidConfig    = errors.New("censor: invalid configuration")
	ErrProviderDisabled = errors.New("censor: provider is disabled")
)

Common errors

Functions

func IsAuthError

func IsAuthError(err error) bool

IsAuthError checks if an error is an authentication/authorization error.

func IsConfigError

func IsConfigError(err error) bool

IsConfigError checks if an error is a configuration error.

func IsNetworkError

func IsNetworkError(err error) bool

IsNetworkError checks if an error is a network-related error.

func IsProviderError

func IsProviderError(err error) bool

IsProviderError checks if an error is a provider error.

func IsRateLimitError

func IsRateLimitError(err error) bool

IsRateLimitError checks if an error is a rate limit error.

func IsRetryable

func IsRetryable(err error) bool

IsRetryable checks if an error is retryable.

func IsStoreError

func IsStoreError(err error) bool

IsStoreError checks if an error is a store error.

func IsValidationError

func IsValidationError(err error) bool

IsValidationError checks if an error is a validation error.

func WrapNetworkError

func WrapNetworkError(err error) error

WrapNetworkError wraps a network error with appropriate sentinel error.

Types

type BizContext

type BizContext struct {
	BizType     BizType   `json:"biz_type"`     // Business type (user_avatar, note_body, etc.)
	BizID       string    `json:"biz_id"`       // Business object ID (userID, noteID, etc.)
	Field       string    `json:"field"`        // Specific field (title, body, avatar, etc.)
	SubmitterID string    `json:"submitter_id"` // Who submitted the content
	TraceID     string    `json:"trace_id"`     // Request trace ID for debugging
	CreatedAt   time.Time `json:"created_at"`   // When the content was created
}

BizContext represents the business context for a review request.

type BizReview

type BizReview struct {
	ID          string       `json:"id" db:"id"`
	BizType     BizType      `json:"biz_type" db:"biz_type"`
	BizID       string       `json:"biz_id" db:"biz_id"`
	Field       string       `json:"field" db:"field"`
	SubmitterID string       `json:"submitter_id" db:"submitter_id"`
	TraceID     string       `json:"trace_id" db:"trace_id"`
	Decision    Decision     `json:"decision" db:"decision"`
	Status      ReviewStatus `json:"status" db:"status"`
	CreatedAt   int64        `json:"created_at" db:"created_at"`
	UpdatedAt   int64        `json:"updated_at" db:"updated_at"`
}

BizReview represents a business-level review record.

type BizType

type BizType string

BizType represents different business scenarios for content review.

const (
	// User profile related
	BizUserAvatar   BizType = "user_avatar"
	BizUserNickname BizType = "user_nickname"
	BizUserBio      BizType = "user_bio"

	// Note/Post related
	BizNoteTitle  BizType = "note_title"
	BizNoteBody   BizType = "note_body"
	BizNoteImages BizType = "note_images"
	BizNoteVideos BizType = "note_videos"

	// Team related
	BizTeamName    BizType = "team_name"
	BizTeamIntro   BizType = "team_intro"
	BizTeamBgImage BizType = "team_bg_image"

	// Communication related
	BizChatMessage BizType = "chat_message"
	BizDanmaku     BizType = "danmaku"
	BizComment     BizType = "comment"
)

type CensorBinding

type CensorBinding struct {
	ID             string `json:"id" db:"id"`
	BizType        string `json:"biz_type" db:"biz_type"`
	BizID          string `json:"biz_id" db:"biz_id"`
	Field          string `json:"field" db:"field"`
	ResourceID     string `json:"resource_id" db:"resource_id"`
	ResourceType   string `json:"resource_type" db:"resource_type"`
	ContentHash    string `json:"content_hash" db:"content_hash"`
	ReviewID       string `json:"review_id" db:"review_id"`
	Decision       string `json:"decision" db:"decision"`
	ReplacePolicy  string `json:"replace_policy" db:"replace_policy"`
	ReplaceValue   string `json:"replace_value" db:"replace_value"`
	ViolationRefID string `json:"violation_ref_id" db:"violation_ref_id"`
	ReviewRevision int    `json:"review_revision" db:"review_revision"`
	UpdatedAt      int64  `json:"updated_at" db:"updated_at"`
}

CensorBinding represents the current moderation state binding for a business field.

type CensorBindingHistory

type CensorBindingHistory struct {
	ID             string `json:"id" db:"id"`
	BizType        string `json:"biz_type" db:"biz_type"`
	BizID          string `json:"biz_id" db:"biz_id"`
	Field          string `json:"field" db:"field"`
	ResourceID     string `json:"resource_id" db:"resource_id"`
	ResourceType   string `json:"resource_type" db:"resource_type"`
	Decision       string `json:"decision" db:"decision"`
	ReplacePolicy  string `json:"replace_policy" db:"replace_policy"`
	ReplaceValue   string `json:"replace_value" db:"replace_value"`
	ViolationRefID string `json:"violation_ref_id" db:"violation_ref_id"`
	ReviewRevision int    `json:"review_revision" db:"review_revision"`
	ReasonJSON     string `json:"reason_json" db:"reason_json"`
	Source         string `json:"source" db:"source"`           // auto/manual/recheck/policy_upgrade/appeal
	ReviewerID     string `json:"reviewer_id" db:"reviewer_id"` // Who made the decision (for manual review)
	Comment        string `json:"comment" db:"comment"`         // Reviewer's comment
	CreatedAt      int64  `json:"created_at" db:"created_at"`
}

CensorBindingHistory represents historical moderation state changes.

type Decision

type Decision string

Decision represents the review decision for a resource.

const (
	DecisionPending Decision = "pending" // Awaiting review
	DecisionPass    Decision = "pass"    // Content approved
	DecisionReview  Decision = "review"  // Needs manual review
	DecisionBlock   Decision = "block"   // Content blocked
	DecisionError   Decision = "error"   // Review failed with error
)

type ErrorCategory

type ErrorCategory string

ErrorCategory represents the category of an error for handling decisions.

const (
	ErrorCategoryNetwork    ErrorCategory = "network"    // Network connectivity issues
	ErrorCategoryRateLimit  ErrorCategory = "rate_limit" // Rate limiting
	ErrorCategoryTimeout    ErrorCategory = "timeout"    // Request timeout
	ErrorCategoryAuth       ErrorCategory = "auth"       // Authentication/authorization
	ErrorCategoryConfig     ErrorCategory = "config"     // Configuration issues
	ErrorCategoryValidation ErrorCategory = "validation" // Input validation
	ErrorCategoryProvider   ErrorCategory = "provider"   // Provider-specific errors
	ErrorCategoryInternal   ErrorCategory = "internal"   // Internal errors
)

func GetErrorCategory

func GetErrorCategory(err error) ErrorCategory

GetErrorCategory returns the category of an error.

type FinalOutcome

type FinalOutcome struct {
	Decision      Decision      `json:"decision"`       // Final decision
	ReplacePolicy ReplacePolicy `json:"replace_policy"` // How to handle if blocked
	ReplaceValue  string        `json:"replace_value"`  // Replacement value if applicable
	Reasons       []Reason      `json:"reasons"`        // All reasons from all providers
	RiskLevel     RiskLevel     `json:"risk_level"`     // Overall risk level
}

FinalOutcome represents the final decision after all provider reviews.

type HistorySource

type HistorySource string

HistorySource represents the source of a review history entry.

const (
	SourceAuto          HistorySource = "auto"           // Automatic review
	SourceManual        HistorySource = "manual"         // Manual review
	SourceRecheck       HistorySource = "recheck"        // Re-review
	SourcePolicyUpgrade HistorySource = "policy_upgrade" // Policy upgrade triggered
	SourceAppeal        HistorySource = "appeal"         // User appeal
)

type MergedText

type MergedText struct {
	Merged string      // The merged text
	Parts  []string    // Original parts
	Index  []PartIndex // Index mapping for each part
}

MergedText represents the result of merging multiple texts.

type PartIndex

type PartIndex struct {
	Start int // Start position in merged text
	End   int // End position in merged text
}

PartIndex represents the position of a part in the merged text.

type PendingTask

type PendingTask struct {
	ProviderTaskID string `json:"provider_task_id" db:"id"`
	Provider       string `json:"provider" db:"provider"`
	RemoteTaskID   string `json:"remote_task_id" db:"remote_task_id"`
}

PendingTask represents an async task waiting for result.

type ProviderError

type ProviderError struct {
	Provider   string        // Provider name (aliyun, huawei, tencent)
	Code       string        // Error code from provider
	Message    string        // Error message
	StatusCode int           // HTTP status code if applicable
	Category   ErrorCategory // Error category for handling
	Retryable  bool          // Whether this error is retryable
	Raw        any           // Raw error response
	Err        error         // Underlying error
}

ProviderError represents an error from a cloud provider.

func NewProviderError

func NewProviderError(provider, code, message string) *ProviderError

NewProviderError creates a new provider error.

func (*ProviderError) Error

func (e *ProviderError) Error() string

func (*ProviderError) Unwrap

func (e *ProviderError) Unwrap() error

func (*ProviderError) WithCategory

func (e *ProviderError) WithCategory(cat ErrorCategory) *ProviderError

WithCategory sets the error category.

func (*ProviderError) WithCause

func (e *ProviderError) WithCause(err error) *ProviderError

WithCause sets the underlying error.

func (*ProviderError) WithRaw

func (e *ProviderError) WithRaw(raw any) *ProviderError

WithRaw sets the raw error response.

func (*ProviderError) WithStatusCode

func (e *ProviderError) WithStatusCode(code int) *ProviderError

WithStatusCode sets the HTTP status code.

type ProviderTask

type ProviderTask struct {
	ID               string `json:"id" db:"id"`
	ResourceReviewID string `json:"resource_review_id" db:"resource_review_id"`
	Provider         string `json:"provider" db:"provider"`
	Mode             string `json:"mode" db:"mode"` // sync/async
	RemoteTaskID     string `json:"remote_task_id" db:"remote_task_id"`
	Done             bool   `json:"done" db:"done"`
	ResultJSON       string `json:"result_json" db:"result_json"`
	RawJSON          string `json:"raw_json" db:"raw_json"`
	CreatedAt        int64  `json:"created_at" db:"created_at"`
	UpdatedAt        int64  `json:"updated_at" db:"updated_at"`
}

ProviderTask represents a task submitted to a provider.

type Reason

type Reason struct {
	Code     string         `json:"code"`     // Reason code
	Message  string         `json:"message"`  // Human-readable message
	Provider string         `json:"provider"` // Which provider detected this
	HitTags  []string       `json:"hit_tags"` // Tags that were hit
	Raw      map[string]any `json:"raw"`      // Raw provider response (trimmed)
}

Reason represents the reason for a review decision.

type ReplacePolicy

type ReplacePolicy string

ReplacePolicy defines how to handle blocked content.

const (
	ReplacePolicyNone    ReplacePolicy = "none"          // No replacement, hide content
	ReplacePolicyDefault ReplacePolicy = "default_value" // Replace with default value
	ReplacePolicyMask    ReplacePolicy = "mask"          // Mask sensitive parts
)

type Resource

type Resource struct {
	ResourceID  string            `json:"resource_id"`  // Unique identifier for the resource
	Type        ResourceType      `json:"type"`         // text/image/video
	ContentText string            `json:"content_text"` // Text content (for text type)
	ContentURL  string            `json:"content_url"`  // URL for image/video
	ContentHash string            `json:"content_hash"` // Hash for deduplication
	Extra       map[string]string `json:"extra"`        // Additional metadata
}

Resource represents a content resource to be reviewed.

type ResourceReview

type ResourceReview struct {
	ID           string       `json:"id" db:"id"`
	BizReviewID  string       `json:"biz_review_id" db:"biz_review_id"`
	ResourceID   string       `json:"resource_id" db:"resource_id"`
	ResourceType ResourceType `json:"resource_type" db:"resource_type"`
	ContentHash  string       `json:"content_hash" db:"content_hash"`
	ContentText  string       `json:"content_text" db:"content_text"`
	ContentURL   string       `json:"content_url" db:"content_url"`
	Decision     Decision     `json:"decision" db:"decision"`
	OutcomeJSON  string       `json:"outcome_json" db:"outcome_json"`
	CreatedAt    int64        `json:"created_at" db:"created_at"`
	UpdatedAt    int64        `json:"updated_at" db:"updated_at"`
}

ResourceReview represents a resource-level review record.

type ResourceType

type ResourceType string

ResourceType represents the type of content being reviewed.

const (
	ResourceText  ResourceType = "text"
	ResourceImage ResourceType = "image"
	ResourceVideo ResourceType = "video"
)

type ReviewResult

type ReviewResult struct {
	Decision   Decision  `json:"decision"`    // pass/review/block/error
	Confidence float64   `json:"confidence"`  // Confidence score (0-1)
	Reasons    []Reason  `json:"reasons"`     // Reasons for the decision
	Provider   string    `json:"provider"`    // Provider name
	ReviewedAt time.Time `json:"reviewed_at"` // When the review was completed
}

ReviewResult represents the result from a single provider review.

type ReviewStatus

type ReviewStatus string

ReviewStatus represents the status of a review task.

const (
	StatusPending  ReviewStatus = "pending"
	StatusRunning  ReviewStatus = "running"
	StatusDone     ReviewStatus = "done"
	StatusFailed   ReviewStatus = "failed"
	StatusCanceled ReviewStatus = "canceled"
)

type RiskLevel

type RiskLevel int

RiskLevel represents the severity of a violation.

const (
	RiskLow RiskLevel = iota + 1
	RiskMedium
	RiskHigh
	RiskSevere
)

func (RiskLevel) String

func (r RiskLevel) String() string

String returns the string representation of RiskLevel.

type StoreError

type StoreError struct {
	Operation string // Operation that failed (create, update, query)
	Table     string // Table/collection name
	Err       error  // Underlying error
}

StoreError represents a database/store error.

func NewStoreError

func NewStoreError(operation, table string, err error) *StoreError

NewStoreError creates a new store error.

func (*StoreError) Error

func (e *StoreError) Error() string

func (*StoreError) Unwrap

func (e *StoreError) Unwrap() error

type TextMergeStrategy

type TextMergeStrategy struct {
	MaxLen    int    // Maximum length for merged text
	Separator string // Separator between merged texts
}

TextMergeStrategy defines how to merge multiple text resources.

type ValidationError

type ValidationError struct {
	Field   string // Field that failed validation
	Message string // Validation error message
}

ValidationError represents a validation error.

func NewValidationError

func NewValidationError(field, message string) *ValidationError

NewValidationError creates a new validation error.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type ViolationSnapshot

type ViolationSnapshot struct {
	ID           string `json:"id" db:"id"`
	BizType      string `json:"biz_type" db:"biz_type"`
	BizID        string `json:"biz_id" db:"biz_id"`
	Field        string `json:"field" db:"field"`
	ResourceID   string `json:"resource_id" db:"resource_id"`
	ResourceType string `json:"resource_type" db:"resource_type"`
	ContentHash  string `json:"content_hash" db:"content_hash"`
	ContentText  string `json:"content_text" db:"content_text"`
	ContentURL   string `json:"content_url" db:"content_url"`
	OutcomeJSON  string `json:"outcome_json" db:"outcome_json"`
	CreatedAt    int64  `json:"created_at" db:"created_at"`
}

ViolationSnapshot stores the evidence for blocked/review content.