writing-backend-resources
Hướng dẫn quy trình 6 bước TẠO MỚI resource backend Go (entity, dao, repository, service, handler, router, DTO, module layout) cho ERP Cluvix. Dùng skill này TRƯỚC KHI tạo resource CRUD mới hoặc module mới trong internal/modules/, khi cần biết Handler DI/Router/Repository Reader/DTO pattern chuẩn, hoặc trước khi đụng module service (status filter 2 tầng, cascade, optimistic lock). KHÔNG dùng skill này để debug/sửa query đang sai — xem debugging-backend-queries cho việc đó.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-02
- Stars
- ★ 21
- Forks
- 20
01 前言 Front Matter
- name
- writing-backend-resources
- description
- Hướng dẫn quy trình 6 bước TẠO MỚI resource backend Go (entity, dao, repository, service, handler, router, DTO, module layout) cho ERP Cluvix. Dùng skill này TRƯỚC KHI tạo resource CRUD mới hoặc module mới trong internal/modules/, khi cần biết Handler DI/Router/Repository Reader/DTO pattern chuẩn, hoặc trước khi đụng module service (status filter 2 tầng, cascade, optimistic lock). KHÔNG dùng skill này để debug/sửa query đang sai — xem debugging-backend-queries cho việc đó.
02 资源文件 2
- 参考文档reference/patterns-arch.md5.9 KB
- 参考文档reference/service.md14.4 KB
03 SKILL.md 正文
Tạo resource backend mới (Go)
Kiến trúc DI/Handler/Router/DTO chi tiết:
reference/patterns-arch.mdPattern module Service (status filter 2 tầng, cascade, optimistic lock, service_material):reference/service.md
Layout chuẩn (Plan 03 / Plan 08 + restructure 4 nhóm 2026-07-28):
- Resource web-app mới ở
internal/modules/webapp/<domain>/<resource>/(client/mobile/public có nhóm riêng — xem Hard Rules)- Entity trong
dao/entity.go- KHÔNG tạo file mới trong
internal/models/(chỉbase.goở đó)internal/handlers/vàinternal/services/đã XOÁ (Plan 07)
Bước 1 — Migration
# Tạo file BẰNG TAY — KHÔNG dùng `-cmd=create` (nó sinh kèm `.down.sql`, trái rule)
cd backend && ls migrations | sort | tail -3 # timestamp mới phải lớn hơn file mới nhất
touch migrations/$(date +%Y%m%d%H%M%S)_create_{table_name}.up.sql
Viết .up.sql:
CREATE TABLEvới đầy đủ columns, index, comment tiếng Việtcreated_at,updated_at:BIGINT(Unix), KHÔNGDATETIMEBaseModelembed: cầnid,status,created_by,updated_by,created_at,updated_at(KHÔNG còncompany_id— D15/story-62;branch_idkhai riêng trong entity nếu bảng có chi nhánh)SimpleModelembed: cầnid,status,created_at,updated_atstatus TINYINT(1) DEFAULT 1nếu cần show/hidesort_order INT DEFAULT 0nếu cần sắp xếp- KHÔNG tạo
.down.sql(chi tiết:skills/writing-mysql-migrations/SKILL.md)
cd backend && go run cmd/migrate/main.go -cmd=up
Bước 2 — Entity (dao/entity.go)
Template đầy đủ entity.go + dao.go → Xem skill/skills/writing-backend-resources/reference/patterns-arch.md §Dao/ Pattern.
- Chỉ GORM struct + TableName() — không có method, không business logic
- Embed
models.BaseModel(tenant table) hoặcmodels.SimpleModel(shared table) - camelCase DB column →
gorm:"column:xxx" - JSON column →
datatypes.JSON, KHÔNGstring - Nullable fields → pointer
*Type - KHÔNG tạo entity ở
internal/models/{module}/
Bước 3 — Dao (dao/dao.go)
IDao + Dao + BaseRepo + var _ IDao = (*Dao)(nil) — code → Xem skill/skills/writing-backend-resources/reference/patterns-arch.md §Dao/ Pattern.
Bỏ qua khi: _shared/dao (types/constants chung) hoặc readonly view.
Bước 4 — Service (service/service.go) — chỉ khi có business logic
Tạo khi có: validate business, side effects, optimistic locking.
package service
import (
dao "{domain}/{resource}/dao"
"gorm.io/gorm"
)
type Service struct {
db *gorm.DB
dao dao.IDao
}
func New(db *gorm.DB) *Service {
return &Service{db: db, dao: dao.New(db)}
}
Bỏ qua nếu CRUD đơn giản không có side effect.
Bước 5 — Handler (handler/handler.go)
package handler
import (
"gorm.io/gorm"
dao "{resource_import_path}/dao"
"erpCluvix/pkg/helpers"
"erpCluvix/pkg/pagination"
"erpCluvix/pkg/response"
"erpCluvix/pkg/tenant"
"github.com/gin-gonic/gin"
"net/http"
"strings"
)
type Deps struct {
DB *gorm.DB
}
type Handler struct {
Deps
}
func New(d Deps) *Handler { return &Handler{Deps: d} }
func (h *Handler) List{Resource}(c *gin.Context) {
query := tenant.ScopedDBNullBranch(c, h.DB, "{table_name}").Model(&dao.{Resource}{})
if keyword := c.Query("_keyword"); keyword != "" {
like := "%" + strings.TrimSpace(keyword) + "%"
query = query.Where("{searchable_column} LIKE ?", like)
// {searchable_column} PHẢI khớp cột thật trên entity — 2 lần lỗi 1054 production
// (warranty_code, supplier_service) vì copy nguyên "name" không có trên bảng
}
query = query.Order("sort_order DESC")
var items []dao.{Resource}
result := pagination.Paginate(c, query, &items)
c.JSON(http.StatusOK, result)
}
func (h *Handler) Get{Resource}(c *gin.Context) { ... response.Data(c, item) }
func (h *Handler) Create{Resource}(c *gin.Context) { ... response.Created(c, item) }
func (h *Handler) Update{Resource}(c *gin.Context) { ... response.Updated(c, item) }
func (h *Handler) Delete{Resource}(c *gin.Context) { ... response.Deleted(c) }
- Tenant table →
tenant.ScopedDBNullBranch(c, h.DB, "{table_name}") - Bảng dùng chung không có
branch_id(danh mục toàn thương hiệu) →ScopedDBNullBranchvẫn an toàn (bảng không đăng kýbranchTables⇒ không thêm điều kiện); GET/UPDATE/DELETE theo id vẫn đi qua nó theo Hard Rules - Sau CUD config:
dexie.BumpDexieTable(h.DB, "<dexie_table_key>") - Update: typed DTO với pointer fields (nil = omit)
- KHÔNG import
db.DBglobal
Bước 6 — Route (route.go)
package {resource}
import (
"erpCluvix/internal/modules/webapp/{domain}/{resource}/handler"
"github.com/gin-gonic/gin"
)
func RegisterRoutes(authed gin.IRouter, db *gorm.DB) {
h := handler.New(handler.Deps{DB: db})
g := authed.Group("/{resource-path}")
g.GET("", h.List{Resource})
g.GET("/:id", h.Get{Resource})
g.POST("", h.Create{Resource})
g.PUT("/:id", h.Update{Resource})
g.DELETE("/:id", h.Delete{Resource})
}
Đăng ký trong internal/router/ hoặc domain router.go.
Màn chỉ-đọc cần hình dạng response khác → thêm GET /:id/detail RIÊNG:
- KHÔNG đổi
GET /:idđang phục vụ form sửa — đổi hình dạng ở đó là đụng luồng ghi và mọi màn khác đang tiêu thụ. - Endpoint mới viết
Selecttường minh theo đúng field màn cần; đối chiếu schema sau migration, không chép cột từ baseline. - Đăng ký sau
GET /:idtrong cùng group; thêm vàoroute_perm_map.jsonbằng edit additive.
Layout tổng thể
internal/modules/webapp/{domain}/{resource}/
├── route.go
├── handler/
│ ├── handler.go # Deps + Handler + New
│ ├── find.go # List + Get
│ ├── upsert.go # Create + Update
│ ├── delete.go # Delete
│ └── dto.go # DTO structs (optional)
├── service/
│ └── service.go # Business logic (bỏ qua nếu CRUD thuần)
└── dao/
├── entity.go # GORM struct + TableName
└── dao.go # IDao + Dao + BaseRepo
Pilot: internal/modules/webapp/crm/order_plan/
Checklist sau khi tạo xong
- [ ] Migration đã chạy thành công
- [ ] Entity ở
dao/entity.go, không phảiinternal/models/ - [ ]
dao/dao.gocó IDao + Dao +var _ IDao = (*Dao)(nil) - [ ] Handler dùng Deps struct +
h.DB - [ ] List + single-record đều qua
tenant.ScopedDBNullBranch - [ ] Bảng có
branch_id(là quyền sở hữu của dòng) → đã đăng kýbranchTablestrongpkg/tenant/scope.go(tenantTables/company đã xoá, story-41); verifygrep '"<table>"' pkg/tenant/scope.gora 1 hit (thiếu =ScopedDBNullBranchno-op câm lặng → IDOR; xemskill/skills/backend-hard-rules/reference/security-patterns.md) - [ ] Sau CUD:
dexie.BumpDexieTablenếu là config table - [ ] Route đã đăng ký đủ endpoints
- [ ]
go build ./...clean - [ ] Không có magic string/number — constants trong
pkg/define/
FE form patterns (CRITICAL)
Validators cho FK fields
Validators.required của Angular chấp nhận 0 là valid. FK = 0 → BE vỡ FK constraint.
// ❌ NEVER cho FK / select id
emr_department_id: [model.emr_department_id, Validators.required]
// ✅ ALWAYS dùng [required, min(1)]
emr_department_id: [model.emr_department_id, [Validators.required, Validators.min(1)]]
department_type: [model.department_type, [Validators.required, Validators.min(1)]]
Visual invalid indicator
<app-foo-autocomplete-form-control
[class.ng-invalid]="isFieldInvalid('foo_id')"
class="ng-dirty"
formControlName="foo_id"
/>
<label for="foo_id">Tên field <span class="text-red-500">*</span></label>
isFieldInvalid ở BaseForm:
return !!c && c.invalid && (c.dirty || c.touched || this.submitted());
BE defense-in-depth — KHÔNG phụ thuộc FE validate
// Sentinel error = i18n key, KHÔNG hardcode string tiếng Việt
var errEmrDepartmentRequired = errors.New("emr_department_required") // key có trong pkg/i18n/*
func resolveDepartmentTypeForUpdates(tx *gorm.DB, updates map[string]interface{}) error {
edid, ok := updates["emr_department_id"]
if !ok || edid == nil { return errEmrDepartmentRequired }
if helpers.ToInt64(edid) <= 0 { return errEmrDepartmentRequired }
// ...auto-derive department_type
}
if err := resolveDepartmentTypeForUpdates(tx, updates); err != nil {
if errors.Is(err, errEmrDepartmentRequired) {
response.HandleError(c, err) // sentinel → i18n.TryT → 422
} else {
response.ServerError(c, err) // 500
}
return
}
Reference: internal/modules/webapp/config/service/handler/handler.go (errEmrDepartmentRequired).
Data trong IndexedDB — KHÔNG attach từ BE
- BE trả raw FK id (
service_id,branch_id) - FE lookup qua helper:
servicesHelper.getServiceInfo(id)/branchHelper.getBranchInfo(id) - Nếu resource KHÔNG có IndexedDB cache → mới attach qua
attachRelationở handler
04 同仓库更多 Skills
writing-mysql-migrations
Viết migration MySQL cho Cluvix (golang-migrate, Go + GORM): quy ước timestamp, idempotent ADD/DROP COLUMN, FK constraint thật, decimal tiền, MySQL 9.7 LTS syntax mới/cũ, và luật CẤM tuyệt đối test/migrate chạm DB dev/prod thật. Dùng skill này TRƯỚC KHI tạo file migration mới, sửa schema, thêm cột/FK, backfill dữ liệu, hoặc trước khi chạy `cmd/migrate`/integration test đụng tới database — kể cả migration chỉ 1-2 dòng.
working-on-ops
Hướng dẫn nghiệp vụ dashboard CRM, export, và import dữ liệu trong module ops của backend Cluvix. Dùng skill này KHI đụng report/dashboard CRM, thêm cột export (`?columns=`), hoặc import khách hàng (migration onboard SAAS client) — đọc trước khi đổi bất kỳ hành vi nào trong các luồng này.
working-on-hr
Quy tắc và pattern nghiệp vụ HR Cluvix trong CRM standalone: user nội bộ, role/RBAC, đổi/đặt lại mật khẩu, import user. Dùng skill này KHI làm feature/sửa bug đụng module hr (chỉ còn `hr/user`) — trước khi đọc code.
working-on-crm
Quy tắc và pattern nghiệp vụ CRM Cluvix: khách hàng, lịch hẹn, liệu trình, đơn hàng, thanh toán. Dùng skill này KHI làm feature/sửa bug đụng module crm (customer, appointment, order, treatment, payment) — trước khi đọc code, để tránh phá vỡ business rule đã có (tái khai thác, customer status IN(...)).
working-on-config
Quy tắc và pattern nghiệp vụ Config Cluvix còn sống trong CRM standalone: mẫu in (print_template), control field trong bảng (control_field_in_table), IndexedDB sync của config. Dùng skill này KHI làm feature/sửa bug đụng các module đó — trước khi đọc code. Tổng đài/chữ ký số/AI config đã bỏ (chỉ còn mô tả lịch sử trong skill, KHÔNG áp dụng).
testing-backend
Hạ tầng test Go: unit test, integration test với TEST_MYSQL_DSN (MySQL disposable thật, KHÔNG dockertest), FreshTenant helper, HTTP handler test qua httptest, và mutation test (`go test -overlay`) để chứng minh test thật sự neo hành vi. Dùng skill này TRƯỚC KHI viết test mới cho backend Go, khi cần biết cách dựng DB test sạch mỗi lần chạy, trước khi báo một AC dạng phủ định/mặc định là Done, hoặc trước khi verify build/test theo Development Protocol bước 4 (Validate).