gorig-cli 1.0.24 → 1.0.25

package/templates/service.go.ejs

@@ -1,93 +1,41 @@
 package <%= moduleName %>
 
 import (
-	"github.com/gin-gonic/gin"
-	"github.com/jom-io/gorig/apix/load"
-	"github.com/jom-io/gorig/domainx"
-	"github.com/jom-io/gorig/httpx"
+	"context"
+	"strings"
+
 	"github.com/jom-io/gorig/utils/errors"
 	"github.com/jom-io/gorig/utils/logger"
 	"go.uber.org/zap"
-	"<%= projectName %>/domain/<%= moduleName %>/api/req"
-	"<%= projectName %>/domain/<%= moduleName %>/internal"
-)
-
-var gService = &service{}
-
-type service struct {
-}
-
-func (s service) Save<%= ModuleName %>(ctx *gin.Context, req *req.<%= ModuleName %>Req) *errors.Error {
-	logger.Info(ctx, "Save<%= ModuleName %>", zap.Any("req", req))
-	<%= moduleName %>M := internal.<%= ModuleName %>()
-	if req.ID > 0 {
-		get<%= ModuleName %> := internal.<%= ModuleName %>()
-		if e := domainx.MustGetByID(get<%= ModuleName %>.Con, req.ID, get<%= ModuleName %>); e != nil {
-			return e
-		}
-		<%= moduleName %>M.ID = get<%= ModuleName %>.ID
-		<%= moduleName %>M.Options = get<%= ModuleName %>.Options
-	}
-	<%= moduleName %>M.ParseReq(req)
-	if _, e := domainx.Save(<%= moduleName %>M.Con, <%= moduleName %>M, 0); e != nil {
-		return e
-	}
-	return nil
-}
 
-func (s service) Page<%= ModuleName %>(ctx *gin.Context, pageReq *load.Page, filter *req.<%= ModuleName %>Req) (*load.PageResp, *errors.Error) {
-	logger.Info(ctx, "Page<%= ModuleName %>", zap.Any("pageReq", pageReq), zap.Any("filter", filter))
-	if filter == nil {
-		return nil, errors.Verify("参数错误")
-	}
-	query := domainx.Matches{}
-	query.Eq("user_id", httpx.GetUserIDInt64(ctx))
-	<%= moduleName %>Resp := new(load.PageResp)
-	<%= moduleName %> := internal.<%= ModuleName %>()
-	list := &[]internal.<%= ModuleName %>M{}
-	if e := domainx.FindByPageMatch(<%= moduleName %>.Con, query, pageReq, <%= moduleName %>Resp, list); e != nil {
-		return nil, e
-	}
-	<%= moduleName %>Resp.Result = <%= moduleName %>.ToRespList(list)
-	return <%= moduleName %>Resp, nil
-}
+	"<%= projectName %>/domain/<%= moduleName %>/model"
+)
 
-func (s service) List<%= ModuleName %>(ctx *gin.Context, filter *req.<%= ModuleName %>Req) ([]*req.<%= ModuleName %>Resp, *errors.Error) {
-	logger.Info(ctx, "List<%= ModuleName %>", zap.Any("filter", filter))
-	if filter == nil {
-		return nil, errors.Verify("参数错误")
+func BuildInfo(ctx context.Context, name string) (*InfoResp, *errors.Error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return nil, errors.Verify("name cannot be empty")
 	}
-	query := domainx.Matches{}
-	query.Eq("user_id", httpx.GetUserIDInt64(ctx))
-	<%= moduleName %> := internal.<%= ModuleName %>()
-	list := &[]internal.<%= ModuleName %>M{}
-	if e := domainx.FindByMatch(<%= moduleName %>.Con, query, list); e != nil {
-		return nil, e
-	}
-	return <%= moduleName %>.ToRespList(list), nil
-}
 
-func (s service) Get<%= ModuleName %>(ctx *gin.Context, id int64) (*req.<%= ModuleName %>Resp, *errors.Error) {
-	logger.Info(ctx, "Get<%= ModuleName %>", zap.Any("id", id))
-	<%= moduleName %>M := internal.<%= ModuleName %>()
-	if e := domainx.MustGetByID(<%= moduleName %>M.Con, id, <%= moduleName %>M); e != nil {
-		return nil, e
-	}
-	return <%= moduleName %>M.ToResp(), nil
+	logger.Info(ctx, "building <%= moduleName %> info", zap.String("name", name))
+	return &InfoResp{
+		Item: model.D{
+			ID:   "<%= moduleName %>",
+			Name: name,
+		},
+		Message: "hello " + name,
+	}, nil
 }
 
-func (s service) Delete<%= ModuleName %>(ctx *gin.Context, id int64) *errors.Error {
-	logger.Info(ctx, "Delete<%= ModuleName %>", zap.Any("id", id))
-	<%= moduleName %>M := internal.<%= ModuleName %>()
-	if e := domainx.MustGetByID(<%= moduleName %>M.Con, id, <%= moduleName %>M); e != nil {
-		return e
+func EchoMessage(ctx context.Context, req *EchoReq) (*EchoResp, *errors.Error) {
+	if req == nil {
+		return nil, errors.Verify("request cannot be nil")
 	}
-	if e := domainx.Delete(<%= moduleName %>M.Con, <%= moduleName %>M); e != nil {
-		return e
+	message := strings.TrimSpace(req.Message)
+	if message == "" {
+		return nil, errors.Verify("message cannot be empty")
 	}
-	return nil
-}
 
-func init() {
-	setService(gService)
+	logger.Info(ctx, "echo <%= moduleName %> message", zap.String("message", message))
+	return &EchoResp{Message: message}, nil
 }

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

@@ -0,0 +1,89 @@
+---
+name: gorig-backend
+description: Build, extend, review, test, troubleshoot, and deploy Go backend projects based on github.com/jom-io/gorig. Use for Gorig project initialization, environment configuration, Router-Controller-Service-Model modules, apix/httpx/serv/bootstrap usage, MySQL or MongoDB through domainx/dx, cache, cronx, messagex, SSE, token authentication, middleware, observability, deployment, and Gorig ecosystem integration. Resolve the target project's actual Gorig version before selecting APIs.
+---
+
+# Gorig Backend
+
+Develop Gorig projects from verified source behavior. Treat static examples as fallbacks, never as stronger evidence than the target project's dependency source.
+
+## Start Every Task
+
+1. Read `references/source-policy.md`.
+2. Read `references/onboarding-files.md` and inspect the target repository.
+3. Run `scripts/detect-gorig-context.sh [project-root]` when a shell is available.
+4. Read `references/capability-matrix.md` before selecting a component.
+5. If the user describes a business outcome rather than naming a precise framework component, read `references/business-scenarios.md`.
+6. Load only the references required by the request.
+
+If the project has no `go.mod`, treat the task as new-project design. Do not assume the latest Gorig API is compatible with an existing project.
+
+## Route the Request
+
+- Business feature requests in ordinary language, workflow automation, reminders, notifications, real-time UI updates, delayed processing, or performance complaints: read `references/business-scenarios.md` first, then route to the component references selected by the scenario analysis.
+- New runnable project or project initialization: read `references/project-bootstrap.md`, `references/configuration.md`, `references/service-lifecycle.md`, and `references/testing.md`.
+- Environment selection or configuration: read `references/configuration.md`.
+- Startup, shutdown, built-in services, or custom services: read `references/service-lifecycle.md`.
+- Persistent CRUD modules or MySQL/Mongo-backed business modules: read `references/persistent-crud.md`, `references/framework-api.md`, and `references/testing.md`. Add HTTP routes/controllers only when HTTP is in scope.
+- Advanced data access, aggregate reads, batch scans, indexes, direct-driver escape hatches, or transaction boundaries: read `references/advanced-data-access.md`, `references/framework-api.md`, and `references/testing.md`.
+- Cache, cache-aside, local cache persistence, Redis cache, counters, invalidation, or multi-level caching: read `references/cache.md`, `references/framework-api.md`, and `references/testing.md`.
+- Framework registration, non-CRUD HTTP APIs, logging, or generic middleware: read `references/framework-api.md`.
+- Authentication, login/logout, token refresh/revocation, protected routes, user context, roles, forbidden responses, CORS, debounce/rate protection, request signing, secrets, or sensitive logs: read `references/auth-security.md`, `references/framework-api.md`, and `references/testing.md`.
+- Outbound HTTP calls, external API integration, GET/form/JSON/XML requests, forwarded headers, context propagation, timeouts, bad upstream responses, or image fetching: read `references/outbound-http.md`, `references/framework-api.md`, and `references/testing.md`.
+- Scheduled tasks, cron expressions, delayed jobs, one-shot jobs, timeout, panic recovery, deduplication, or cron shutdown: read `references/scheduled-tasks.md`, `references/framework-api.md`, and `references/testing.md`.
+- Pub/sub messaging, local or Redis broker, sequential subscribers, retry, DLQ, replay, unsubscribe, or message-to-SSE composition: read `references/messaging.md`, `references/framework-api.md`, and `references/testing.md`.
+- Server-Sent Events, streaming routes, event/error payloads, disconnect handling, or SSE composition: read `references/sse.md`, `references/framework-api.md`, and `references/testing.md`.
+- Tests, smoke checks, or delivery validation: read `references/testing.md`.
+- Missing local source, upstream comparison, latest behavior, or ecosystem repositories: read `references/source-map.md`.
+- API documentation changes: use `assets/api-doc-template.md`.
+- Module behavior changes: use `assets/module-readme-template.md`.
+
+Detailed scenario references will be added phase by phase. Until a scenario has a dedicated verified reference, inspect the resolved framework source and its tests before implementation.
+
+## Use the Conversation as a Development Workflow
+
+For a new project or a material architecture, API, persistence, security, runtime behavior, configuration, external dependency, or deployment change:
+
+1. Restate the business goal, boundaries, and assumptions.
+2. If the request is business-language, decompose it into trigger, durability, audience, data, and operational needs before choosing components.
+3. Identify the Gorig and Go versions plus external dependencies.
+4. Present a recommended implementation in business language; list alternatives only when there is a real tradeoff.
+5. Separate minimum viable implementation from optional future expansion.
+6. Present the route, data, configuration, file, test, and deployment impact.
+7. Wait for explicit confirmation before the first material edit.
+8. Implement one runnable vertical slice at a time.
+9. Verify the business effect of each slice before adding the next component.
+
+For an explicitly requested narrow fix with no material design choice, inspect and implement directly.
+
+## Apply Core Framework Rules
+
+- Start applications with `bootstrap.StartUp()` unless the resolved version requires a different entry point.
+- Register custom lifecycle services with `serv.RegisterService`.
+- Register HTTP routes with `httpx.RegisterRouter` and the callback type used by the resolved source.
+- Add `defer apix.HandlePanic(ctx)` to controllers when consistent with the target project.
+- Bind and validate input with the resolved `apix` signatures.
+- Return the established response envelope and business error code.
+- Keep transport logic in controllers and business logic in services.
+- Propagate request context through services, data access, logs, and outbound calls.
+- Use `utils/errors` and structured `utils/logger` calls.
+- Prefer `domainx/dx` for supported data operations; use direct drivers only when the abstraction lacks the required behavior.
+- Push filtering, sorting, pagination, counting, and aggregation into the database or verified framework APIs. Do not load all records into memory and then filter, sort, or paginate in Go.
+- Register migrations and indexes according to the resolved framework implementation.
+- Never advertise `experimental` or `unsupported` capability as production-ready.
+
+## Verify Before Delivery
+
+Use the target repository's commands when documented. Otherwise run the applicable checks from `references/testing.md`.
+
+At minimum:
+
+- Format changed Go code.
+- Build the affected packages.
+- Run relevant tests, including failure paths.
+- Exercise the delivered behavior with a local smoke check.
+- Report exact commands and results.
+- Report skipped checks and concrete blockers.
+- Update API or module documentation when behavior changed.
+
+Deliver a concise summary containing changed files, effect verification, compatibility assumptions, known limitations, and safe next steps.

package/templates/skills/gorig-backend/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gorig Backend"
+  short_description: "Version-aware Gorig backend development and deployment"
+  default_prompt: "Use $gorig-backend to inspect the target project's Gorig version, plan the requested backend change, implement it with verified framework APIs, and validate the resulting behavior."

package/templates/skills/gorig-backend/assets/api-doc-template.md

@@ -0,0 +1,59 @@
+# <module> API Documentation
+
+## 1. Module Overview
+
+- Module name:
+- Business objective:
+- Dependent services/storage:
+- Gorig version:
+
+## 2. API List
+
+| Name | Method | Path | Auth | Description |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## 3. API Details
+
+### 3.1 <api name>
+
+- Method and path:
+- Controller：
+- Service：
+- Description:
+
+#### Request Parameters
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+|  |  |  |  |
+
+#### Response Example
+
+```json
+{
+  "code": 0,
+  "msg": "ok",
+  "data": {}
+}
+```
+
+#### Error Codes
+
+| code | Meaning | Trigger |
+|---|---|---|
+|  |  |  |
+
+## 4. Invocation and Verification
+
+```sh
+curl -X POST 'http://<host>/<path>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+## 5. Change Log
+
+| Date | Author | Description |
+|---|---|---|
+|  |  |  |

package/templates/skills/gorig-backend/assets/gorig.gitignore

@@ -0,0 +1,65 @@
+# Gorig runtime state
+.cache/
+.logs/
+logs/
+tmp/
+temp/
+.deploy/
+tokens.json
+*.log
+*.jsonl
+
+# Build and test output
+bin/
+dist/
+build/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+coverage.out
+coverage.html
+*.prof
+cpu.out
+mem.out
+trace.out
+
+# Local secrets and machine-specific overrides
+.env
+.env.*
+!.env.example
+*.pem
+*.crt
+*.key
+*.p12
+*.pfx
+_bin/*secret*.yaml
+_bin/*private*.yaml
+_bin/*override*.yaml
+_bin/*.local.yaml
+
+# Go local workspace/cache
+go.work
+go.work.sum
+.gocache/
+
+# Editors and operating systems
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+*~
+.DS_Store
+Thumbs.db
+
+# Optional local data dumps
+data_smoke/
+test/output/
+*.sqlite
+*.sqlite3
+*.db
+

package/templates/skills/gorig-backend/assets/module-readme-template.md

@@ -0,0 +1,58 @@
+# <module> Module README
+
+## 1. Module Responsibility
+
+- Objective:
+- Boundary:
+- Non-goals:
+- Gorig version:
+
+## 2. Directory Layout
+
+```text
+domain/<module>/
+├── router.go
+├── controller.go
+├── service.go
+├── dto.go
+└── model/
+```
+
+## 3. Request Flow
+
+1. Router registers endpoints and middleware.
+2. Controller handles parameters, panic handling, and responses.
+3. Service executes business logic and error handling.
+4. Model or dx performs data access.
+
+## 4. Data Model
+
+| Struct | Description | Key fields |
+|---|---|---|
+|  |  |  |
+
+## 5. External APIs
+
+| Name | Method | Path | Description |
+|---|---|---|---|
+|  |  |  |  |
+
+## 6. Configuration, Errors, and Logs
+
+- Configuration keys:
+- Error definition location:
+- Common error codes:
+- Key log fields:
+
+## 7. Tests and Effect Verification
+
+- Unit tests:
+- Integration tests:
+- Smoke test：
+- Known limitations:
+
+## 8. Maintenance Conventions
+
+- Naming:
+- Compatibility:
+- Documentation update rules:

package/templates/skills/gorig-backend/references/advanced-data-access.md

@@ -0,0 +1,275 @@
+# Advanced Data Access
+
+Use this reference when a task goes beyond baseline CRUD and needs complex filters, aggregate reads, projections, batch scans, indexes, direct database access, or transaction boundaries.
+
+Always inspect the target project's resolved Gorig source first. The examples below reflect the locally inspected Gorig `master` commit `35bbefb`.
+
+## Preferred API
+
+Prefer `github.com/jom-io/gorig/domainx/dx` for supported MySQL and MongoDB access.
+
+Use legacy `domainx` package functions only when:
+
+- the target project already uses them consistently,
+- the needed behavior is not exposed by `dx`, or
+- version inspection proves the target's `dx` facade lacks the method.
+
+When using legacy calls, keep the same guards as `dx`: update and delete operations must have a non-zero ID or a non-empty match list.
+
+## Optional Filter Semantics
+
+`Eq`, `Like`, `Gt`, `In`, and related methods accept optional `ignore ...bool`.
+
+In the inspected version, `ignore=true` means "ignore the empty-value check", so the zero or empty value is forced into the condition. For ordinary optional request filters, omit the boolean.
+
+```go
+q := dx.On[model.D](ctx).
+    Like("name", req.Name).     // empty req.Name is skipped by the framework
+    Eq("status", req.Status).   // empty req.Status is skipped by the framework
+    Sort("id")
+```
+
+Use `true` only when zero is an intentional filter value:
+
+```go
+q := dx.On[model.D](ctx).Eq("retry_count", 0, true)
+```
+
+## Complex Filters
+
+Common comparison and set operations:
+
+```go
+q := dx.On[model.D](ctx).
+    Eq("tenant_id", tenantID).
+    Ne("status", "deleted").
+    Gte("created_at", startAt).
+    Lt("created_at", endAt).
+    Like("name", keyword).
+    In("type", []string{"standard", "premium"}).
+    NotIn("status", []string{"archived", "blocked"}).
+    NEmpty("external_id")
+```
+
+Array field operations:
+
+```go
+q := dx.On[model.D](ctx).
+    Has("tags", "hot").
+    HasAny("tags", []string{"vip", "trial"}).
+    HasAll("flags", []string{"paid", "verified"})
+```
+
+MongoDB geo-spatial helpers:
+
+```go
+nearByLatLng := dx.On[model.D](ctx).Near("lat", "lng", lat, lng, 3000)
+nearByLocation := dx.On[model.D](ctx).NearLoc("location", lat, lng, 3000)
+```
+
+Verify indexes and backend behavior before using geo queries in production. MySQL and MongoDB differ in supported geo field shapes and index requirements.
+
+## Dynamic Conditions
+
+When building conditions from loops or composable policy blocks, use `domainx.NewMatches()` and `AddMatches`.
+
+```go
+matches := domainx.NewMatches().
+    Eq("tenant_id", tenantID).
+    Eq("status", req.Status).
+    Gte("score", req.MinScore, req.MinScore == 0)
+
+for _, tag := range req.Tags {
+    matches.Has("tags", tag)
+}
+
+list, err := dx.On[model.D](ctx).
+    AddMatches(matches).
+    Sort("id").
+    Find()
+```
+
+Be careful with `ignore=true` in dynamic builders. The example above forces `MinScore=0` only if the request explicitly treats zero as a valid minimum. Omit the third argument when an empty or zero request field should be skipped.
+
+## Sorting and Projection
+
+```go
+items, err := dx.On[model.D](ctx).
+    Eq("tenant_id", tenantID).
+    Select("id", "name", "status", "created_at").
+    Omit("secret_note").
+    Sort("created_at", true). // true means ascending
+    Find()
+```
+
+`Sort("field")` is descending by default. Projection is useful for large records, but verify backend-specific field names:
+
+- MySQL fields normally match `gorm:"column:<name>"`.
+- MongoDB fields normally match `bson:"<name>"`.
+- Do not project sensitive fields back into API responses just because storage returns them.
+
+## Reads, Aggregates, and Existence Checks
+
+```go
+one, err := dx.On[model.D](ctx).WithID(id).Get()
+exists, err := dx.On[model.D](ctx).Eq("code", code).Exists()
+count, err := dx.On[model.D](ctx).Eq("status", "active").Count()
+sum, err := dx.On[model.D](ctx).Eq("tenant_id", tenantID).Sum("amount")
+```
+
+Use `Get` only when a single record is expected. Use `Exists` for uniqueness checks instead of fetching full records when the value is not needed.
+
+## Memory-Safe Query Processing
+
+Query work must be pushed down to the database or handled through bounded framework iteration.
+
+Do not:
+
+- fetch all rows with `Find()` and then filter in Go;
+- fetch all rows with `Find()` and then sort in Go for an API response;
+- fetch all rows with `Find()` and then slice a page in Go;
+- fetch all rows to count, sum, or check existence;
+- scan an entire table in a background task without a restrictive match or operational reason.
+
+Use:
+
+- `Eq`, `Like`, `Gt/Gte/Lt/Lte`, `In`, `AddMatches`, and backend-specific filters before reading;
+- `Sort` before `Find` or `Page`;
+- `Page(page, size, lastID)` for API pagination;
+- `Select` or `Omit` for large records;
+- `Count`, `Sum`, and `Exists` for aggregate/existence checks;
+- `FindEach` or `AllEach` for bounded batch processing when a job must touch many records.
+
+If `dx` cannot express the needed query, use a direct driver with database-side `WHERE`/filter, `ORDER BY`, `LIMIT`, cursor, aggregation pipeline, or equivalent backend mechanism. The direct-driver path must include the same tenant/scope/time-range guards that a `dx` query would have.
+
+In-memory processing is acceptable only after the database has already applied the main filter and bound the result size.
+
+## Pagination and Batch Scans
+
+Cursor-aware paging:
+
+```go
+resp, err := dx.On[model.D](ctx).
+    Eq("tenant_id", tenantID).
+    Sort("id").
+    Page(req.Page, req.Size, req.LastID)
+```
+
+Safe full scans:
+
+```go
+err := dx.On[model.D](ctx).
+    Eq("tenant_id", tenantID).
+    AllEach(func(item *domainx.Complex[model.D]) *errors.Error {
+        // Process one item. Keep the handler idempotent.
+        return nil
+    })
+```
+
+`AllEach` pages by ID in batches of 1000 in the inspected implementation. Always include a restrictive match for tenant, scope, or job boundary. Do not use it as an unbounded production table scan without an operational reason.
+
+## Writes and Guards
+
+```go
+id, err := dx.On[model.D](ctx, &d).Save()
+
+err = dx.On[model.D](ctx).WithID(id).Updates(map[string]interface{}{
+    "status":     "done",
+    "updated_by": actorID,
+})
+
+err = dx.On[model.D](ctx).
+    Eq("tenant_id", tenantID).
+    Eq("expired", true, true).
+    Delete()
+```
+
+`Update`, `Updates`, `Delete`, `Get`, `Find`, `FindEach`, and `AllEach` guard against missing IDs or empty match lists in the inspected `dx` implementation. Preserve this behavior. Do not bypass it with direct drivers unless the replacement has an equal or stronger safety condition.
+
+## Migrations and Indexes
+
+Register indexes from `service.go` using `domainx.AutoMigrate`.
+
+```go
+func init() {
+    domainx.AutoMigrate(
+        func() domainx.ConTable {
+            return dx.On[model.D](context.Background()).Complex()
+        },
+        domainx.CtIdx(domainx.Unique, "tenant_id", "code"),
+        domainx.CtIdx(domainx.Idx, "tenant_id", "status", "created_at"),
+        domainx.CtIdx(domainx.Spatial2D, "lat", "lng"),
+    )
+}
+```
+
+Pass bare storage field names. Verify generated indexes against the selected backend:
+
+- MySQL uses GORM migration plus explicit index creation in the inspected source.
+- MongoDB maps fields through its own query builder and index implementation.
+- Compound and unique index names must be stable enough for repeated migration runs.
+- Geo-spatial indexes are backend-specific and must be proven with integration tests.
+
+## Direct Driver Escape Hatches
+
+Use direct database handles only when `dx` cannot express the required behavior, such as a backend-specific lock, transaction, aggregation pipeline, or raw SQL optimization.
+
+Available inspected escape hatches:
+
+```go
+con := dx.On[model.D](ctx).Complex().GetCon()
+raw, err := con.MustGetDB()
+if err != nil {
+    return err
+}
+```
+
+For MySQL, `raw` is expected to be `*gorm.DB`. For MongoDB, `raw` is expected to be `*qmgo.Client`.
+
+Project-level connection helpers also exist:
+
+```go
+mysqlDB := domainx.UseDbConn("Main")
+mongoClient := domainx.UseMongoDbConn("main")
+```
+
+Rules for escape hatches:
+
+- Keep direct-driver code inside the service or a small repository helper.
+- Require explicit type assertions and nil checks.
+- Keep tenant, ID, and match guards visible next to raw queries.
+- Add integration tests for the exact backend path.
+- Do not hide raw SQL or Mongo pipelines behind generic helper names.
+
+## Transactions
+
+The inspected `dx` facade does not expose a generic transaction wrapper. For MySQL-only work, use the direct `*gorm.DB` transaction API after verifying the target version:
+
+```go
+raw, err := dx.On[model.D](ctx).Complex().GetCon().MustGetDB()
+if err != nil {
+    return err
+}
+
+db, ok := raw.(*gorm.DB)
+if !ok || db == nil {
+    return errors.Sys("mysql connection is not available")
+}
+
+if txErr := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+    return tx.Table(model.Table).Where("id = ?", id).Update("status", "done").Error
+}); txErr != nil {
+    return errors.Sys(txErr.Error())
+}
+```
+
+MongoDB transaction behavior is not covered by the current verified skill baseline. Inspect the resolved `qmgo` version and run a MongoDB integration test before advertising Mongo transaction support.
+
+## Verification Checklist
+
+- Compile the affected package against the resolved Gorig version.
+- Run ordinary tests without external services.
+- Run tagged or container-backed integration tests for MySQL and MongoDB paths.
+- Verify optional filters with empty values and intentional zero values.
+- Verify sorting, projection, pagination, count/sum, update/delete guards, and index creation.
+- Record unsupported backend behavior and skipped checks explicitly.