91 lines
5.3 KiB
Markdown
91 lines
5.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Run
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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.
|