cid/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run

# Build (Docker)
docker build -t cid .

# Run locally (requires Go 1.26)
go mod download && go mod tidy
go run main.go

# Build binary
go build -ldflags="-s -w" -o main ./main.go

# Test
go test ./...

GoFrame CLI (optional)

# Install gf CLI
go install github.com/gogf/gf/v2/cmd/gf/v2@latest

# Generate DAO/Model from DB
gf gen dao -c config.yml

Project Overview

CID is a content moderation service that submits advertising images/videos to Netease Yidun (易盾) for automated content review. It provides REST APIs, a scheduled batch-checking scheduler, and a frontend management UI.

Core Flow

1. Material sources: tencent_image / tencent_video tables in the dataengine PostgreSQL database (external system)
2. Detection: Submit media to Yidun API for content moderation (async callback mode or sync polling mode)
3. Result handling: Yidun pushes results to callback endpoints, or the service polls Yidun for results
4. Logging: Results recorded in material_verify_log table (cid DB) with status backfilled to source tables

Architecture

controller/         HTTP handlers (GoFrame controller + ghttp.Request handlers)
├── yidun/          Content detection API (text/image/video submit, callback receive, result polling)
├── dataengine/     Material verification UI API (list, stats, manual verify, batch verify, export, callback)
service/            Business logic layer
├── yidun/          Yidun SDK wrappers (text/image/video detection, callback processing)
├── dataengine/     Material verification pipeline, content check scheduler, callback handling
dao/                Data access layer (GoFrame ORM + custom gfdb wrapper)
├── dataengine/     DAOs for tencent_image, tencent_video, material_verify_log, etc.
model/              Entity/DTO definitions
├── entity/dataengine/  DB entity structs with field constants
├── dto/yidun/          Request/response DTOs
consts/             Constants
├── dataengine/     Table names, check statuses, suggestion values
├── public/         Shared constants (currently empty)
resource/frontend/  Static frontend HTML (material-verify.html)
sql/                DDL and migration scripts

Two Detection Modes

Configured via yidun.callback_mode in config.yml:

• Callback mode (true): Yidun pushes results to /yidun/callback/receiveImage / /yidun/callback/receiveVideo after async detection completes. Requires a public-facing callback URL configured in yidun.image.callback_url / yidun.video.callback_url.
• Polling mode (false): After submitting content, the service immediately calls Yidun's sync image API (for images) or queries results via callback API (for video). Manual polling endpoints are also available.

Scheduled Content Check

The content_check section in config.yml controls a background scheduler (tencent_content_check_service.go) that periodically fetches pending media from source tables and submits them for verification. Configurable via batch_size, interval_seconds, image_enabled, video_enabled, scheduler_enabled.

Key Design Decisions

• Snowflake IDs: DAO Create() methods generate IDs client-side via Snowflake because GoFrame v2.10's pgsql driver doesn't support RETURNING / LastInsertId.
• Dual database: The cid DB holds verification logs; the dataengine DB holds source material tables. The db.go helper (Model(tableName)) selects the dataEngine DB group.
• Mixed ORM: Some DAOs use g.DB("dataEngine").Model() (standard GoFrame), others use gfdb.DB(ctx, "cid").Model(ctx, ...) (custom common library wrapper that passes context to DB operations). Both access the same underlying gdb engine.
• Singleton pattern: All controllers, services, and DAOs are package-level global singletons (e.g., var MaterialVerify = new(MaterialVerifyService)).
• Context user: Each controller method injects a hardcoded beans.User into context (ctx = context.WithValue(ctx, "user", &beans.User{UserName: "admin", TenantId: 1})). No real auth.
• Verify status values: PENDING → SUBMITTING → VERIFIED / REJECTED / REVIEW. Source tables use a different set: PENDING / SUBMITTING / SUCCESS / FAILED / COMPLETED.

API Routes

Routes are registered in main.go via http.RouteRegister() (from the common library). Key endpoint groups:

• Yidun detection (controller/yidun): POST /yidun/detectText, /yidun/detectImage, /yidun/detectVideo — submit content for detection
• Yidun callback (controller/yidun): POST /yidun/callback/receiveImage, /yidun/callback/receiveVideo — receive Yidun push results; POST /yidun/callback/poll, /yidun/callback/pollImage, /yidun/callback/pollVideo — manual polling
• Material verify (controller/dataengine): POST /dataengine/listImage, /dataengine/listVideo, /dataengine/statsImage, /dataengine/statsVideo, /dataengine/manualVerifyImage, /dataengine/batchVerifyImage, /dataengine/exportRejected, /dataengine/imageCallback, etc.
• Content check (controller/yidun): POST /contentCheck/start, /contentCheck/stop, /contentCheck/status, /contentCheck/manualSubmitImageByID, etc.