BO 与 VO

查询 BO 必须单开一型

// SysXxxQueryBo Xxx 列表查询条件（query 参数）。
//
// 与 SysXxxBo 分开而非复用：查询条件全部可选，而 SysXxxBo 的 binding:"required"
// 是新增场景的契约。Go 的 binding tag 没有校验分组概念，一个结构体只能有一套规则。
type SysXxxQueryBo struct {
	Name   string `form:"name"`
	Status string `form:"status"`
	// BeginTime/EndTime 创建时间区间，闭区间，两端须同时给出才生效。
	//
	// tag 里的方括号不是笔误：前端 fieldMappingTime 把日期区间摊平成
	// params[beginTime]/params[endTime] 两个 query 参数，gin 按字面量匹配 form tag。
	BeginTime string `form:"params[beginTime]"`
	EndTime   string `form:"params[endTime]"`
}

• 查询 BO 用 form tag（走 query），写入 BO 用 json tag（走 body）。
• 查询 BO 不加 binding:"required"。
• 只放真正参与筛选的字段，不构造无效的查询能力。
• 入参字段偏离写入 BO 时（如只收 2 个字段）， 另开一型并在 doc 里写清为什么。

VO 的 excel tag

type SysXxxVo struct {
	XxxID  int64  `json:"xxxId" excel:"参数主键"`
	Name   string `json:"name" excel:"名称"`
	// 导出时按 excelDict 转标签，对齐 Java @ExcelDictFormat。
	Status string `json:"status" excel:"状态" excelDict:"0=正常,1=停用"`
}

• excel tag 的值 = Java @ExcelProperty(value = ...) 的原文， 逐字抄。
• @ExcelDictFormat(dictType = "sys_yes_no") → excelDict:"Y=是,N=否"；其它字典去 script/sql/ry_vue.sql 搜 sys_dict_data 取 label/value。
• 没有 excel tag 的字段不导出（等价 Java @ExcelIgnoreUnannotated）。
• ID 字段 保持裸 int64，pkg/excel 自动按位数转字符串保精度。

详见 编码约定 / 雪花 ID 与 pkg 参考 / excel。