gorig-cli 1.0.14 → 1.0.23

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

@@ -0,0 +1,189 @@
+---
+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.
+---
+
+# Gorig Backend
+
+Implement backend work in gorig with strict framework conventions, deterministic workflow, and mandatory confirmation before coding.
+
+## Load Context First
+Read `~/.codex/skills/gorig-backend/references/onboarding-files.md`.
+Build a concrete mental model from local code before proposing changes.
+Treat code behavior as the source of truth for all framework APIs and helper methods.
+State uncertainty explicitly and ask focused questions instead of guessing.
+
+## Confirm Change Plan Before Coding
+Provide a concise plan and wait for explicit user confirmation before editing code.
+Include:
+- Business objective and boundary.
+- Data structures and persistence impact.
+- Route list with request/response and error code shape.
+- File-level change list in `Router -> Controller -> Service -> Model/Domainx`.
+- Test and documentation update plan.
+
+Do not start implementation until confirmation is received.
+
+## Implement With Framework Rules
+Follow these hard constraints:
+- Register services with `serv.RegisterService`; start with `bootstrap.StartUp()`.
+- Register routes with `httpx.RegisterRouter`; reuse existing `httpx` middleware.
+- Add `defer apix.HandlePanic(ctx)` in controllers.
+- Parse request params with `apix.BindParams` or `apix.GetParam*`.
+- Return responses with `apix.HandleData`.
+- Keep business logic in service layer.
+- Use `utils/errors` for errors.
+- Use `utils/logger` or global logger helpers for logging.
+- Do not use `fmt.Println` for runtime logging.
+- Prefer `domainx/dx` APIs for DB operations; align usage with `test/dx_test.go`.
+- Keep names short and clear; avoid long camel-case identifiers.
+- 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
+The model `D` struct only needs fields and `DConfig()`. Do NOT add `M` type alias or `NewM()` factory:
+```go
+// CORRECT
+type D struct {
+    AgentID string `bson:"agent_id" json:"agent_id"`
+    // ...
+}
+func (d *D) DConfig() (domainx.ConType, string, string) {
+    return domainx.Mongo, global.QuantSageDB, Table
+}
+
+// WRONG - do not add these
+type M = domainx.Complex[D]
+func NewM() *M { return domainx.UseComplex[D](...) }
+```
+
+### 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:
+```go
+func init() {
+    domainx.AutoMigrate(
+        func() domainx.ConTable { return domainx.UseComplex[model.D](domainx.Mongo, global.DB, model.Table) },
+        domainx.CtIdx(domainx.Idx, "field_a", "field_b", "field_c"), // compound index
+        domainx.CtIdx(domainx.Unique, "unique_field"),               // unique index
+    )
+}
+```
+
+### dx query API
+```go
+// 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]
+if err != nil { return nil, err }
+for i := range result {
+    if result[i] != nil && result[i].Data != nil {
+        // use result[i].Data
+    }
+}
+
+// Get single record
+item, err := dx.On[model.D](ctx).Eq("agent_id", agentID).Sort("id", true).Get()
+
+// Save (create or update)
+_, err := dx.On[model.D](ctx, &d).Save()
+
+// Update single field
+err := dx.On[model.D](ctx).WithID(id).Update("field", value)
+```
+
+## 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.
+
+## 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`.
+
+## Go Test Convention
+
+**All tests live in `go/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
+```
+
+`init.go` starts MongoDB before any test runs. Tests that bypass this package lose the DB connection.
+
+**New test file boilerplate:**
+
+```go
+package test
+
+import (
+    "testing"
+
+    "quantsage/domain/{module}"                       // import target domain
+    {module}model "quantsage/domain/{module}/model"   // if model types needed
+)
+
+func TestXxx_场景描述(t *testing.T) {
+    // arrange
+    input := ...
+
+    // act - only exported functions are accessible from package test
+    got := {module}.ExportedFunction(input)
+
+    // assert
+    if got != want {
+        t.Fatalf("ExportedFunction() = %v, want %v", got, want)
+    }
+}
+```
+
+**Rules:**
+- Functions under test must be **exported** (capitalized) - `package test` cannot access unexported symbols.
+- Use standard `testing` only. No testify or other assertion libraries.
+- 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
+```
+
+## Validate and Deliver
+Run `go build ./... && go test ./test/... -v` after every change.
+If tests cannot run, explain the exact blocker and provide a minimal verification plan.
+Deliver results in concise engineering format:
+- Change summary.
+- Key file paths.
+- Test status and suggestions.
+- Unknowns plus minimal assumptions.
+
+## Provide Database Recommendation
+When asked to choose storage, recommend based on:
+- Existing dependencies and `dx` compatibility.
+- Read/write pattern and query complexity.
+- Transaction consistency requirements.
+- Operational cost and team familiarity.
+
+Present recommendation with clear rationale and trade-offs.
+
+## Resources
+- `~/.codex/skills/gorig-backend/references/onboarding-files.md`: Required code-reading checklist for gorig and news.
+- `~/.codex/skills/gorig-backend/assets/api-doc-template.md`: API documentation template.
+- `~/.codex/skills/gorig-backend/assets/module-readme-template.md`: Module README template.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gorig Backend"
+  short_description: "Go backend execution for gorig framework"
+  default_prompt: "Act as a senior Go backend engineer in gorig. Read required local files first, propose a change plan and wait for confirmation, then implement Router-Controller-Service-Model changes with tests and docs."

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

@@ -0,0 +1,50 @@
+# <module> API 文档
+
+## 1. 模块说明
+- 模块名：
+- 业务目标：
+- 依赖服务/存储：
+
+## 2. 接口清单
+| 名称 | 方法 | 路径 | 鉴权 | 说明 |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## 3. 接口详情
+
+### 3.1 <接口名>
+- 方法与路径：
+- Controller：
+- Service：
+- 说明：
+
+#### 请求参数
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+#### 响应示例
+```json
+{
+  "code": 0,
+  "msg": "ok",
+  "data": {}
+}
+```
+
+#### 错误码
+| code | 含义 | 触发场景 |
+| --- | --- | --- |
+|  |  |  |
+
+## 4. 调用样例
+```bash
+curl -X POST 'http://<host>/<path>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+## 5. 变更记录
+| 日期 | 变更人 | 说明 |
+| --- | --- | --- |
+|  |  |  |

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

@@ -0,0 +1,46 @@
+# <module> 模块说明
+
+## 1. 模块职责
+- 目标：
+- 边界：
+- 非目标：
+
+## 2. 目录结构
+```text
+domain/<module>/
+├── router.go
+├── controller.go
+├── service.go
+└── model/
+```
+
+## 3. 请求处理流程
+1. Router 注册入口与中间件。
+2. Controller 参数处理、panic 保护、返回封装。
+3. Service 业务逻辑与错误处理。
+4. Model 或 dx 数据访问。
+
+## 4. 数据模型
+| 结构体 | 说明 | 关键字段 |
+| --- | --- | --- |
+|  |  |  |
+
+## 5. 对外接口
+| 名称 | 方法 | 路径 | 说明 |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## 6. 错误与日志
+- 错误定义位置：
+- 常见错误码：
+- 日志关键字段：
+
+## 7. 测试与验证
+- 单测：
+- 集成测试：
+- 手工验证步骤：
+
+## 8. 维护约定
+- 命名：
+- 兼容性：
+- 文档更新规则：

package/templates/skills/codex/gorig-backend/references/onboarding-files.md

@@ -0,0 +1,38 @@
+# Onboarding File Checklist
+
+Read these files before implementation.
+
+## gorig (target project)
+- `AGENTS.md`
+- `README.md`
+- `bootstrap/startup.go`
+- `httpx/serv.go`
+- `httpx/tool.go`
+- `apix/handle.go`
+- `apix/params.go`
+- `domainx/*`
+- `domainx/dx/*`
+- `serv/serv.go`
+- `utils/errors/*`
+- `utils/logger/*`
+- `test/dx_test.go`
+
+## news (reference project, do not modify)
+- `_cmd/api/main.go`
+- `domain/init.go`
+- `domain/**/router.go`
+- `domain/**/controller.go`
+- `domain/**/service.go`
+- `domain/**/model/*.go`
+- `test/*`
+
+## Working Paths
+- Target to modify: `/Users/doz/Desktop/project/open/gorig`
+- Reference only: `/Users/doz/Desktop/project/personal/news`
+
+## Reading Strategy
+1. Trace startup and service registration.
+2. Trace a complete request path: router -> controller -> service -> model/dx.
+3. Confirm panic handling, param binding, and response helpers in real code.
+4. Confirm error and logger usage from existing modules.
+5. Reuse existing patterns before introducing new abstractions.