gorig-cli 1.0.23 → 1.0.24

package/templates/skills/codex/gorig-backend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gorig-backend
-description: Senior Go backend development expert for the gorig framework. Use when tasks involve implementing or reviewing gorig services, routers, controllers, services, models, domain modules, dx-based data access, API contract changes, test additions, or module documentation updates. Apply this skill when strict adherence to local gorig/news code patterns and real API behavior is required.
+description: Senior Go backend development expert for the gorig framework. Use when tasks involve implementing or reviewing gorig services, routers, controllers, services, models, domain modules, dx-based data access, cache, cronx scheduled tasks, messagex pub/sub, SSE streaming, API contract changes, test additions, or module documentation updates. Apply this skill when strict adherence to local gorig/news code patterns and real API behavior is required.
 ---
 
 # Gorig Backend
@@ -40,11 +40,10 @@ Follow these hard constraints:
 - Use snake_case for storage fields and CamelCase for model fields.
 - Keep module layout under `domain/<module>/{router.go, controller.go, service.go, model/*.go}`.
 - Put shared logic in `domain/common`.
-- When a route should bypass the built-in 429 debounce middleware, add it in `router.go` with `httpx.DebouceAw(...)` before `httpx.RegisterRouter(...)`. Example: `httpx.DebouceAw("/api/catalog/markets", "/api/catalog/agents")`.
 
 ## Data Access Patterns
 
-### Model layer - minimal structure
+### Model layer — minimal structure
 The model `D` struct only needs fields and `DConfig()`. Do NOT add `M` type alias or `NewM()` factory:
 ```go
 // CORRECT
@@ -56,74 +55,647 @@ func (d *D) DConfig() (domainx.ConType, string, string) {
     return domainx.Mongo, global.QuantSageDB, Table
 }
 
-// WRONG - do not add these
+// WRONG — do not add these
 type M = domainx.Complex[D]
 func NewM() *M { return domainx.UseComplex[D](...) }
 ```
 
-### Index registration - always in service.go init()
+### Index registration — always in service.go init()
 Indexes are registered in `service.go` via `domainx.AutoMigrate`, never in the model file.
-Fields are automatically prefixed with `data.` by the framework - pass bare field names:
+Fields are automatically prefixed with `data.` by the framework — pass bare field names.
+`AutoMigrate` accepts `dx.On[T](ctx).Complex()` as the ConTable factory:
 ```go
 func init() {
     domainx.AutoMigrate(
-        func() domainx.ConTable { return domainx.UseComplex[model.D](domainx.Mongo, global.DB, model.Table) },
+        func() domainx.ConTable { return dx.On[model.D](context.Background()).Complex() },
         domainx.CtIdx(domainx.Idx, "field_a", "field_b", "field_c"), // compound index
         domainx.CtIdx(domainx.Unique, "unique_field"),               // unique index
+        domainx.CtIdx(domainx.Spatial2D, "lat", "lng"),              // 2D spatial index
     )
 }
 ```
 
-### dx query API
+### dx query API — filters
+
+All filter methods accept an optional `ignore bool` trailing param. When `true`, the filter is skipped if value is zero/empty — useful for optional query params:
+```go
+dx.On[model.D](ctx).Eq("status", status, status == "")  // skip filter if status is empty
+```
+
+**Comparison operators:**
+```go
+.Eq("field", value)          // ==
+.Ne("field", value)          // !=
+.Gt("field", value)          // >
+.Gte("field", value)         // >=
+.Lt("field", value)          // <
+.Lte("field", value)         // <=
+.Like("field", "keyword")    // LIKE / regex contains
+.In("field", []T{...})       // IN list
+.NotIn("field", []T{...})    // NOT IN list
+.NEmpty("field")             // field is not empty / not null
+.WithID(id)                  // shorthand for Eq("id", id)
+```
+
+**Array field operators** (for `[]string` / JSON array fields):
+```go
+.Has("tags", "go")                      // array contains "go"
+.HasAny("tags", []string{"go","rust"})  // array contains any of the values
+.HasAll("tags", []string{"go","rust"})  // array contains all of the values
+```
+
+**Geo-spatial operators** (Mongo only):
+```go
+.Near("lat", "lng", lat, lng, distanceMeters)  // separate lat/lng fields
+.NearLoc("location", lat, lng, distanceMeters) // embedded GeoJSON location field
+```
+
+**Dynamic condition composition** (when conditions are built in a loop):
+```go
+// Build Matches dynamically, then pass to AddMatches
+m := domainx.NewMatches().
+    Eq("type", t).
+    Gte("score", minScore, minScore == 0)  // ignore param works here too
+dx.On[model.D](ctx).AddMatches(m).Sort("id").Find()
+```
+
+### dx query API — sorting & projection
 ```go
+.Sort("created_at")        // default descending
+.Sort("created_at", true)  // ascending (true = ASC)
+.Sort("id")                // sort by id descending
+
+.Select("id", "name")      // fetch only these fields
+.Omit("secret_field")      // exclude these fields
+```
+
+### dx query API — read operations
+```go
+// Get single record (by ID or by filters)
+item, err := dx.On[model.D](ctx).WithID(id).Get()
+item, err := dx.On[model.D](ctx).Eq("code", code).Sort("id").Get()
+if err != nil { return nil, err }
+if item.IsNil() { /* not found */ }
+_ = item.Data  // *model.D
+
 // Find multiple records
-result, err := dx.On[model.D](ctx).
-    Eq("agent_id", agentID).
-    Gte("date", startDate).
-    Sort("id", true).   // true=desc, false=asc
-    Find()              // returns domainx.ComplexList[D] = []*domainx.Complex[D]
+results, err := dx.On[model.D](ctx).Eq("status", "active").Sort("id").Find()
 if err != nil { return nil, err }
-for i := range result {
-    if result[i] != nil && result[i].Data != nil {
-        // use result[i].Data
+for _, m := range results.List() {  // List() returns []*model.D
+    _ = m
+}
+
+// Count
+count, err := dx.On[model.D](ctx).Eq("type", t).Count()
+
+// Sum a numeric field
+total, err := dx.On[model.D](ctx).Eq("user_id", uid).Sum("amount")
+
+// Existence check (works with WithID or filters)
+exists, err := dx.On[model.D](ctx).Eq("email", email).Exists()
+
+// Cursor-based pagination (lastID = 0 on first page)
+pageResp, err := dx.On[model.D](ctx).Eq("user_id", uid).Sort("id").Page(page, size, lastID)
+// pageResp.Result   *[]*domainx.Complex[D]
+// pageResp.Total.Get()
+// pageResp.LastID
+// pageResp.Page, pageResp.Size
+
+// Iterate over filtered results one by one
+err := dx.On[model.D](ctx).Eq("flag", true).FindEach(func(item *domainx.Complex[model.D]) *errors.Error {
+    // process item.Data
+    return nil
+})
+
+// Batch-paginated full scan (1000 per batch, safe for large collections)
+err := dx.On[model.D](ctx).Eq("type", t).AllEach(func(item *domainx.Complex[model.D]) *errors.Error {
+    // process item.Data
+    return nil
+})
+```
+
+### dx query API — write operations
+```go
+// Save (insert or update based on ID)
+id, err := dx.On[model.D](ctx, &d).Save()
+
+// Manual ID generation before save
+id, err := dx.On[model.D](ctx, &d).GenerateID().Save()
+
+// Update single field (by ID or by filters)
+err := dx.On[model.D](ctx).WithID(id).Update("status", "done")
+err := dx.On[model.D](ctx).Eq("code", code).Update("count", newCount)
+
+// Update multiple fields at once
+err := dx.On[model.D](ctx).WithID(id).Updates(map[string]interface{}{
+    "status": "done",
+    "count":  newCount,
+})
+
+// Delete (by ID or by filters)
+err := dx.On[model.D](ctx).WithID(id).Delete()
+err := dx.On[model.D](ctx).Eq("expired", true).Delete()
+```
+
+## Cache Package
+
+Use `cache.New[T]` to create a typed cache backed by Memory, JSON file, SQLite, or Redis:
+
+```go
+import "github.com/jom-io/gorig/cache"
+
+// In-memory (go-cache), args: defaultExpiration, cleanupInterval
+c := cache.New[MyStruct](cache.Memory, 5*time.Minute, 10*time.Minute)
+
+// JSON file (persisted to .cache/<name>.json)
+c := cache.New[MyStruct](cache.JSON, "my_cache_name")
+
+// SQLite (persisted to .cache/<name>.db)
+c := cache.New[MyStruct](cache.Sqlite, "my_cache_name")
+
+// Redis (uses configured Redis instance)
+c := cache.New[MyStruct](cache.Redis)
+```
+
+**Cache interface operations:**
+```go
+err := c.Set("key", value, 5*time.Minute)  // 0 = no expiry
+val, err := c.Get("key")                   // returns (T, error); error on miss
+ok, err := c.Exists("key")
+err = c.Del("key")
+err = c.Expire("key", 2*time.Minute)       // update TTL
+n, err := c.Incr("counter")               // atomic increment, returns new int64
+err = c.Flush()                            // clear all keys
+err = c.RPush("queue", value)              // push to list tail
+val, err = c.BRPop(timeout, "queue")       // blocking pop from list tail
+```
+
+**Multi-level cache with singleflight** (prevents cache stampede):
+```go
+l1 := cache.New[MyStruct](cache.Memory, time.Minute, time.Minute)
+l2 := cache.New[MyStruct](cache.Redis)
+tool := cache.NewCacheTool[MyStruct](ctx, []cache.Cache[MyStruct]{l1, l2}, func(key string) (MyStruct, error) {
+    // loader: called only on full miss, result stored in all layers
+    return fetchFromDB(key)
+})
+val, err := tool.Get("key", 5*time.Minute)
+tool.Set("key", val, 5*time.Minute)
+tool.Delete("key")
+```
+
+**SQLite paged cache** — for time-series or queryable local storage with auto-indexed fields:
+```go
+// Struct tags: `idx:"field"` = single index, `idx_group:"group_name"` = compound index
+type Stat struct {
+    At     int64  `json:"at"     idx:"at"`
+    Method string `json:"method" idx_group:"method_uri"`
+    URI    string `json:"uri"    idx_group:"method_uri"`
+    Count  int64  `json:"count"`
+}
+pg, err := cache.NewSQLiteCachePage[Stat]("stat_cache")
+```
+
+## Scheduled Tasks (cronx)
+
+`cronx` is a service registered automatically. Enable it by including `"CRON"` in service startup or via `bootstrap.StartUp()`.
+
+```go
+import "github.com/jom-io/gorig/cronx"
+
+// Standard cron expression — with optional timeout context
+cronx.AddCronTask("0 * * * * *", func(ctx context.Context) {
+    // ctx is canceled on timeout; check ctx.Done() for long tasks
+}, 30*time.Second)  // optional: task-level timeout
+
+// Interval-based shorthand
+cronx.AddEveryTask(5*time.Minute, func(ctx context.Context) {
+    // runs every 5 minutes
+})
+
+// One-shot delayed task (runs once after delay)
+cronx.AddDelayTask(10*time.Second, func(ctx context.Context) {
+    // runs once 10s after registration
+})
+
+// One-shot at specific time
+cronx.AddOnceTask(time.Now().Add(time.Hour), func(ctx context.Context) {
+    // runs once at the specified time, then removes itself
+})
+```
+
+**Built-in behaviors:**
+- Panic recovery: panics are caught, logged, and sent to DingTalk.
+- Timeout: if timeout is set and exceeded, `ctx` is canceled and an error is logged.
+- Duplicate deduplication: same spec+func combination is ignored with a warning.
+- `AddTask(spec, func())` is deprecated — use `AddCronTask` for context support.
+
+**Lifecycle** (if managing manually without bootstrap):
+```go
+go cronx.Startup("CRON", "")
+// ...
+cronx.Shutdown("CRON", context.Background())
+```
+
+## Message Broker (messagex)
+
+In-process pub/sub (Local) or Redis-backed for cross-process messaging.
+
+```go
+import "github.com/jom-io/gorig/mid/messagex"
+
+// Get broker instance
+svc := messagex.Ins(messagex.Local)   // in-memory
+svc := messagex.Ins(messagex.Redis)   // Redis-backed
+
+// Or use package-level helpers (Local broker)
+messagex.RegisterTopic(...)
+messagex.PublishNewMsg(...)
+messagex.UnSubscribe(...)
+```
+
+**Concurrent subscriber** (messages dispatched in parallel):
+```go
+subID, err := svc.RegisterTopic("order.created", func(msg *messagex.Message) *errors.Error {
+    name := msg.GetValue("name")           // interface{}
+    age  := msg.GetValueInt64("age")       // int64
+    amt  := msg.GetValueFloat64("amount")  // float64
+    return nil
+})
+defer svc.UnRegisterTopic("order.created", subID)
+```
+
+**Sequential subscriber** (messages processed in publish order, one at a time):
+```go
+subID, err := svc.RegisterTopicSeq("order.created", func(msg *messagex.Message) *errors.Error {
+    // handler called serially; return error to trigger retry/DLQ
+    return nil
+}, messagex.WithMaxRetry(3), messagex.WithRetryIntervals(500*time.Millisecond))
+```
+
+**Publish:**
+```go
+// payload can be any struct or map[string]any
+svc.PublishNewMsg(ctx, "order.created", OrderCreatedEvent{UserID: uid, Amount: 99.9})
+```
+
+**Dead Letter Queue (sequential only):**
+```go
+// Replay up to 10 failed messages back into the topic queue
+err := svc.ReplayDLQ("order.created", 10)  // limit <= 0 = replay all
+```
+
+**Multiple subscribers** — all registered subscribers receive every published message independently.
+
+## SSE — Server-Sent Events
+
+Use `ssex` middleware and helpers for streaming responses:
+
+```go
+import "github.com/jom-io/gorig/httpx/ssex"
+
+// Route registration — SSE endpoint must be GET
+router.GET("/stream/events", ssex.Mid(), controller.StreamEvents)
+
+// In controller — ssex.Mid() sets headers and enforces GET-only (returns 405 otherwise)
+func (c *Controller) StreamEvents(ctx *gin.Context) {
+    err := ssex.SendOK(ctx, "update", map[string]interface{}{"value": 42})
+    if err != nil { return }
+
+    err = ssex.SendError(ctx, "update", "something went wrong")
+    if err != nil { return }
+}
+```
+
+## Logging
+
+Use `utils/logger` everywhere. Never use `fmt.Println` for runtime output.
+
+```go
+import (
+    "github.com/jom-io/gorig/utils/logger"
+    "go.uber.org/zap"
+)
+```
+
+**Log levels:**
+```go
+logger.Debug(ctx, "cache miss", zap.String("key", key))
+logger.Info(ctx, "order created", zap.Int64("id", id), zap.Float64("amount", amount))
+logger.Warn(ctx, "retry attempt", zap.Int("attempt", n), zap.Error(err))
+logger.Error(ctx, "db write failed", zap.Error(err))
+logger.DPanic(ctx, "unexpected state") // panic in dev, error in prod
+```
+
+- All calls auto-inject `traceID` and `userID` from ctx — pass ctx from controller all the way down.
+- Passing `nil` ctx is safe; traceID will be `"no traceid"`.
+- `*gin.Context` is accepted directly as ctx.
+
+**Create a standalone context with trace ID** (for background jobs / init):
+```go
+ctx := logger.NewCtx()                   // auto-generates xid trace ID
+ctx := logger.NewCtx("my-trace-id")     // custom trace ID
+traceID := logger.GetTraceID(ctx)
+```
+
+**Structured fields** — always use zap typed constructors, never `zap.Any` for typed values:
+```go
+zap.String("field", val)
+zap.Int64("id", id)
+zap.Float64("amount", amt)
+zap.Bool("ok", flag)
+zap.Error(err)            // for error values
+zap.Any("data", obj)      // fallback for unknown types
+```
+
+**Log files** are written to `.logs/commons/commons.jsonl` by default (lumberjack rotation).
+Config keys in yaml: `logger.commons.root`, `logger.commons.level`, `logger.commons.file`.
+
+### Scenario 6 — Logging across layers
+
+```go
+// controller.go — ctx carries traceID + userID from middleware
+func (c *Controller) Create(ctx *gin.Context) {
+    defer apix.HandlePanic(ctx)
+    logger.Info(ctx, "create request received")
+
+    userID := apix.GetParamInt64(ctx, "user_id")
+    id, err := Create(ctx, userID, 99.9)
+    if err != nil {
+        logger.Error(ctx, "create failed", zap.Error(err))
+        apix.HandleData(ctx, nil, err)
+        return
     }
+    logger.Info(ctx, "create success", zap.Int64("id", id))
+    apix.HandleData(ctx, id, nil)
 }
 
-// Get single record
-item, err := dx.On[model.D](ctx).Eq("agent_id", agentID).Sort("id", true).Get()
+// service.go — forward ctx, never create a new one mid-request
+func Create(ctx context.Context, userID int64, amount float64) (int64, *errors.Error) {
+    logger.Debug(ctx, "saving order", zap.Int64("user_id", userID))
+    d := model.D{UserID: userID, Amount: amount, Status: "pending"}
+    id, err := dx.On[model.D](ctx, &d).Save()
+    if err != nil {
+        logger.Error(ctx, "save order failed", zap.Int64("user_id", userID), zap.Error(err))
+        return 0, err
+    }
+    return id, nil
+}
 
-// Save (create or update)
-_, err := dx.On[model.D](ctx, &d).Save()
+// cronx / background — use logger.NewCtx() since there is no request ctx
+func syncExpiredOrders(ctx context.Context) {
+    logger.Info(ctx, "sync started")
+    count, err := cancelExpired(ctx)
+    if err != nil {
+        logger.Error(ctx, "sync failed", zap.Error(err))
+        return
+    }
+    logger.Info(ctx, "sync done", zap.Int64("cancelled", count))
+}
+```
+
+## Middleware
 
-// Update single field
-err := dx.On[model.D](ctx).WithID(id).Update("field", value)
+```go
+import "github.com/jom-io/gorig/httpx"
+
+// Panic recovery middleware — returns HTTP 500 with JSON error body
+router.Use(httpx.Recovery())
 ```
 
 ## Execution Strategy
 
-For small changes (< ~20 lines, 1-2 files): implement directly.
-
-For larger or pattern-repeatable changes (3+ files, bulk updates): delegate only when it helps Codex move work in parallel.
-- Keep the critical path local when the next step depends on the result.
-- Give delegated workers disjoint file ownership and keep `gorig-backend` conventions in scope.
-- Verify with `go build ./...` and `go test ./...` after delegated work lands.
+Implement directly using Read/Edit/Write tools.
+Verify with `go build ./... && go test ./test/... -v` after every change.
 
 ## Maintain Documentation
 When API changes exist, create or update `doc/<module>.md` using `~/.codex/skills/gorig-backend/assets/api-doc-template.md`.
 When module behavior changes, update `domain/<module>/README.md` using `~/.codex/skills/gorig-backend/assets/module-readme-template.md`.
 
+## Complete Scenario Examples
+
+### Scenario 1 — CRUD module (HTTP API)
+
+```
+domain/order/
+├── router.go
+├── controller.go
+├── service.go
+└── model/
+    └── order.go
+```
+
+**model/order.go**
+```go
+package model
+
+import "github.com/jom-io/gorig/domainx"
+
+const Table = "order"
+
+type D struct {
+    UserID int64  `bson:"user_id" json:"user_id"`
+    Status string `bson:"status"  json:"status"`
+    Amount float64 `bson:"amount" json:"amount"`
+}
+
+func (d *D) DConfig() (domainx.ConType, string, string) {
+    return domainx.Mongo, "main", Table
+}
+```
+
+**service.go**
+```go
+package order
+
+import (
+    "context"
+    "github.com/jom-io/gorig/domainx"
+    "github.com/jom-io/gorig/domainx/dx"
+    "github.com/jom-io/gorig/utils/errors"
+    "yourproject/domain/order/model"
+)
+
+func init() {
+    domainx.AutoMigrate(
+        func() domainx.ConTable { return dx.On[model.D](context.Background()).Complex() },
+        domainx.CtIdx(domainx.Idx, "user_id", "status"),
+    )
+}
+
+func Create(ctx context.Context, userID int64, amount float64) (int64, *errors.Error) {
+    d := model.D{UserID: userID, Status: "pending", Amount: amount}
+    id, err := dx.On[model.D](ctx, &d).Save()
+    if err != nil {
+        return 0, err
+    }
+    return id, nil
+}
+
+func ListByUser(ctx context.Context, userID int64) ([]*model.D, *errors.Error) {
+    results, err := dx.On[model.D](ctx).Eq("user_id", userID).Sort("id").Find()
+    if err != nil {
+        return nil, err
+    }
+    return results.List(), nil
+}
+
+func Complete(ctx context.Context, id int64) *errors.Error {
+    return dx.On[model.D](ctx).WithID(id).Update("status", "done")
+}
+```
+
+**controller.go**
+```go
+package order
+
+import (
+    "github.com/gin-gonic/gin"
+    "github.com/jom-io/gorig/apix"
+)
+
+type Controller struct{}
+
+func (c *Controller) Create(ctx *gin.Context) {
+    defer apix.HandlePanic(ctx)
+    userID := apix.GetParamInt64(ctx, "user_id")
+    amount := apix.GetParamFloat64(ctx, "amount")
+    id, err := Create(ctx, userID, amount)
+    apix.HandleData(ctx, id, err)
+}
+
+func (c *Controller) List(ctx *gin.Context) {
+    defer apix.HandlePanic(ctx)
+    userID := apix.GetParamInt64(ctx, "user_id")
+    list, err := ListByUser(ctx, userID)
+    apix.HandleData(ctx, list, err)
+}
+```
+
+**router.go**
+```go
+package order
+
+import "github.com/jom-io/gorig/httpx"
+
+func init() {
+    c := &Controller{}
+    httpx.RegisterRouter(func(r httpx.Router) {
+        g := r.Group("/order")
+        g.POST("/create", c.Create)
+        g.GET("/list",   c.List)
+    })
+}
+```
+
+---
+
+### Scenario 2 — Scheduled task
+
+```go
+package sync
+
+import (
+    "context"
+    "github.com/jom-io/gorig/cronx"
+    "yourproject/domain/order"
+)
+
+func init() {
+    // Run every day at 02:00
+    cronx.AddCronTask("0 0 2 * * *", syncExpiredOrders, 5*time.Minute)
+}
+
+func syncExpiredOrders(ctx context.Context) {
+    // business logic; ctx is canceled after 5 min timeout
+    _ = order.CancelExpired(ctx)
+}
+```
+
+---
+
+### Scenario 3 — Event-driven with messagex
+
+```go
+// Publisher (in order service)
+func Create(ctx context.Context, ...) (int64, *errors.Error) {
+    // ... save logic ...
+    messagex.PublishNewMsg(ctx, "order.created", map[string]any{
+        "order_id": id,
+        "user_id":  userID,
+    })
+    return id, nil
+}
+
+// Subscriber (in notify service init)
+func init() {
+    messagex.RegisterTopic("order.created", func(msg *messagex.Message) *errors.Error {
+        orderID := msg.GetValueInt64("order_id")
+        return sendPushNotification(orderID)
+    })
+}
+```
+
+---
+
+### Scenario 4 — SSE streaming endpoint
+
+```go
+// router.go
+g.GET("/stream/status", ssex.Mid(), c.StreamStatus)
+
+// controller.go
+func (c *Controller) StreamStatus(ctx *gin.Context) {
+    defer apix.HandlePanic(ctx)
+    orderID := apix.GetParamInt64(ctx, "order_id")
+
+    status, err := order.GetStatus(ctx, orderID)
+    if err != nil {
+        ssex.SendError(ctx, "status", err.Error())
+        return
+    }
+    ssex.SendOK(ctx, "status", map[string]any{"status": status})
+}
+```
+
+---
+
+### Scenario 5 — Cache-aside pattern
+
+```go
+var orderCache = cache.New[model.D](cache.Redis)
+
+func GetByID(ctx context.Context, id int64) (*model.D, *errors.Error) {
+    key := fmt.Sprintf("order:%d", id)
+
+    // L1: Redis cache
+    if cached, err := orderCache.Get(key); err == nil {
+        return &cached, nil
+    }
+
+    // L2: DB
+    result, err := dx.On[model.D](ctx).WithID(id).Get()
+    if err != nil || result.IsNil() {
+        return nil, err
+    }
+    _ = orderCache.Set(key, *result.Data, 5*time.Minute)
+    return result.Data, nil
+}
+```
+
+---
+
 ## Go Test Convention
 
-**All tests live in `go/test/`, `package test`. Never place test files inside domain packages.**
+**All tests live in `test/`, `package test`. Never place test files inside domain packages.**
 
-```text
-go/test/
-|-- init.go              <- Shared MongoDB init - DO NOT modify
-|-- _bin/local.yaml      <- Test DB config - DO NOT modify
-`-- {feature}_test.go    <- Add new test files here
+```
+test/
+├── init.go              ← Shared DB init — DO NOT modify
+├── _bin/local.yaml      ← Test DB config — DO NOT modify
+└── {feature}_test.go    ← Add new test files here
 ```
 
-`init.go` starts MongoDB before any test runs. Tests that bypass this package lose the DB connection.
+`init.go` starts the DB connection before any test runs. Tests that bypass this package lose the connection.
 
 **New test file boilerplate:**
 
@@ -131,36 +703,41 @@ go/test/
 package test
 
 import (
+    "context"
     "testing"
-
-    "quantsage/domain/{module}"                       // import target domain
-    {module}model "quantsage/domain/{module}/model"   // if model types needed
 )
 
 func TestXxx_场景描述(t *testing.T) {
-    // arrange
-    input := ...
+    ctx := context.Background()
 
-    // act - only exported functions are accessible from package test
-    got := {module}.ExportedFunction(input)
+    // arrange — hardcode inline, no external files
+    id, err := SomeModule.Create(ctx, 1, 99.9)
+    if err != nil {
+        t.Fatalf("Create failed: %v", err)
+    }
+
+    // act
+    result, err := SomeModule.GetByID(ctx, id)
 
     // assert
-    if got != want {
-        t.Fatalf("ExportedFunction() = %v, want %v", got, want)
+    if err != nil {
+        t.Fatalf("GetByID failed: %v", err)
+    }
+    if result == nil {
+        t.Fatal("expected result, got nil")
     }
 }
 ```
 
 **Rules:**
-- Functions under test must be **exported** (capitalized) - `package test` cannot access unexported symbols.
-- Use standard `testing` only. No testify or other assertion libraries.
+- Functions under test must be **exported** (capitalized) — `package test` cannot access unexported symbols.
+- Use standard `testing` only (testify is available but prefer stdlib assertions).
 - Use `t.Fatalf` / `t.Errorf` for assertions.
 - Hardcode test data inline; do not read external files.
 
 **Run commands:**
 
 ```bash
-cd go
 go test ./test/... -v              # all tests
 go test ./test/... -run TestXxx -v # single test
 ```