spark-server/AGENTS.md

spark-server agent notes

This repo is a Go 1.26 modular monolith IM server. Source of truth: docs/architecture-v3.md.

Before writing code:

1. Load .cursor/skills/spark-im-v3/SKILL.md
2. Follow .cursor/rules/ (always-on V3 invariants + file-scoped rules)
3. Keep functions within .golangci.yaml (funlen 100, lll 240)
4. HTTP and TCP share Application services under internal/module/{biz}/logic. Each module is entity / model (one file per table, GORM TableName() → t_*) / logic (one file per function, not per table). Gin handlers only bind and call those services (MVC). REST paths are /v1/{resource} grouped by business; admin ops use /api/admin/… (see skill http.md). Request DTOs use go-playground/validator (label / errmsg i18n keys). Context must carry reqctx.RealIP and the user language (zh-CN / en / zh-TW). Error msg and notification copy come from internal/pkg/i18n. Table and column COMMENT is required. Message content is serialized bytes, not a string.
5. MySQL: all tables t_*; migrations replay-all — details in .cursor/skills/spark-im-v3/mysql.md. After changing migrations/*.sql, run go run ./cmd/migrate -config configs/config.yaml yourself.
6. Before finishing any code change, run make test at the repo root (runs lint first, logic coverage ≥65%). Do not report the task as OK until it passes. Missing go / golangci-lint → fix toolchain first; never label verification as skipped. make deploy chains through test.
7. After edits that touch the repo, load .cursor/skills/daily-change-list/SKILL.md and append docs/daily/{yyyy}-{mm}-{dd}-change-list.md before handoff.
8. Before git commit, make test must pass; install enforcement with make install-git-hooks or make setup (see .cursor/rules/git-commit-gate.mdc). Do not use --no-verify unless the user explicitly asks.

Do not introduce Kafka, K8s, microservices, ConversationSeq, application-layer handshake crypto, or public gnet ports.