# G. ModuleSpec 声明速查

:::tip 说明
`ModuleSpec[Item, LItem, DRes]` 全部声明字段速查。泛型三参数：行结构、列表元素（树形可不同）、详情结构。
:::

## 数据源与查询（applyFilters 固定顺序生效）

| 字段 | 序 | 行为 |
|---|---|---|
| Model | 1 | 数据源工厂（必填），通常 `NewXxxRepo().Ctx(ctx)` |
| LikeFields | 2 | 逐列 LIKE 请求同名字段，空串跳过 |
| EqFields | 3 | 等值过滤（列名转 lowerCamel），零值跳过 |
| KeywordFields | 4 | keyword 对多列 LIKE，括号包成单个 AND |
| Filter | 5 | 复杂条件追加（勿重复前四项已覆盖条件） |
| DataScope | 6 | 数据权限（ApplyDataScope 工厂），最后一步 |

排序：请求 orderField 命中 `OrderableFields` 白名单时前端排序生效；否则 `OrderBy`（List 专属可用 `ListOrderBy`）。

## 输出声明

| 字段 | 行为 |
|---|---|
| IsTree + ParentOf | 树形输出（仅 List 建树；ParentOf 返回 0 表根） |
| ChildSetter | 子级写入器（缺省反射写 Children 字段） |
| SerializeMaps | 枚举 → 字典编码，读侧回填 {field}Text |
| FileFields | 单文件：写侧转正、读侧补域名 |
| MultiFileFields | 逗号分隔多文件 |
| ContentFields | 富文本：写侧占位符化、读侧还原 |
| FileSaveDir | 三类文件共用的转正子目录 |
| FieldLabels | 唯一校验提示标签覆盖 |

## 业务规则

| 字段 | 行为 |
|---|---|
| UniqueFields | Add/Update 前逐条预检（并发以 uk 索引为准） |
| ToData | req → 落库 map（不映射审计字段） |

## 钩子（错误原样上抛；禁 HTTP/IO、禁 append）

| 钩子 | 时机 |
|---|---|
| BeforeAdd / AfterAdd | 新增前后 |
| BeforeUpdate / AfterUpdate | 修改前后 |
| BeforeDelete / AfterDelete | 删除前后 |
| BeforeBatchDelete / AfterBatchDelete | 批量删除前后 |
| AfterPageList | 分页查询后 |
| AfterDetail | 详情查询后 |

## 标准方法签名

```go
spec.Page(ctx, req, pageNo, pageSize) (*Item, total, error)   // 返回切片 + 总数
spec.List(ctx, req) ([]*LItem, error)
spec.Detail(ctx, id, req) (*DRes, error)
spec.Add(ctx, req) (int64, error)
spec.Update(ctx, id, req) error
spec.Delete(ctx, id) error
spec.BatchDelete(ctx, ids) error
```

## 使用要点

- 声明变量命名 `{模块}Spec`，包级 var
- 手写方法可复用 `spec.applyFilters(ctx, spec.Model(ctx), req)`（导出场景）
- 钩子内修改 data/元素可以，append 不行

## 相关

- [3.5 业务层开发（service）](/zh/guide/service.html)
- [4.7 基座与公共体系](/zh/architecture/base-system.html)