ent-schema-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ent Schema Generator

将需求输入整理成可直接落地到

sphere-layout

的 DB schema 方案，强调可执行性与可审查性。

Consolidate requirement inputs into a DB schema solution that can be directly implemented in

sphere-layout

, emphasizing executability and auditability.

AI-First Workflow

Gather inputs from all available sources.

读取提示词、需求文档（
```
.md
```
）、接口定义（
```
.proto
```
）、现有 schema、service/dao/render 代码。
如有 demo 行为，先抽取对象、状态流转、关键动作。

Extract entities and lifecycle.

从业务名词与 API 资源抽候选实体。
每个实体明确：status/state、关键时间点、关键约束。
仅在明确必要时拆表（可选字段组、低频大字段、写热点冲突）。

Design fields and null strategy.

schema 与关键字段必须有业务注释。
每个字段必须明确 Optional/Nillable/Unique/Immutable/Default。
状态字段使用 Ent 原生
```
field.Enum
```
，并设置默认值。
统一
```
created_at/updated_at
```
；仅在需要软删时添加
```
deleted_at
```
。
缺失语义优先
```
NULL
```
，避免空字符串哨兵。

Apply ID policy.

默认不在 schema 手写
```
id
```
。
优先使用 ent generator 集中 ID 配置。
仅在业务明确需要时手写自定义
```
id
```
，并说明对 bind/proto 的影响。

Choose relation strategy.

关系字段优先弱关联 ID（如
```
user_id
```
/
```
order_id
```
）。
many-to-many 优先级固定：relation-entity > array(确认方言支持) > join table > JSON(最后兜底)。
JSON 不是常规方案，必须写明 typed/array/join table 不可行原因。

Plan indexes from real query paths.

基于真实 list/filter/sort/query 使用路径设计索引。
优先主键/唯一、高选择性过滤、分页排序复合索引。
避免仅建低基数 status 单列索引（除非有明确收益）。

Produce Ent + Go implementation guidance.

Ent 侧优先 ID 字段表达关系，不强制 edge。
Go 侧给出批量查询方案：收集 IDs -> 去重 ->
```
IDIn(...)
```
-> map 回填。
IDs 很大时给出 chunk 策略与跨服务
```
BatchGet*
```
建议。

Add evolution and consistency safeguards.

读优化可加快照冗余字段（如 name/price snapshot）。
优先 typed/array 结构；JSON 只作例外。
弱关联场景必须给出 dangling refs 校验点。

Gather inputs from all available sources.

Read prompts, requirement documents (
```
.md
```
), interface definitions (
```
.proto
```
), existing schemas, service/dao/render code.
If there is demo behavior, first extract objects, state transitions, and key actions.

Extract entities and lifecycle.

Extract candidate entities from business nouns and API resources.
For each entity, clearly define: status/state, key time points, key constraints.
Split tables only when clearly necessary (optional field groups, low-frequency large fields, write hot spot conflicts).

Design fields and null strategy.

Schemas and key fields must have business comments.
Each field must clearly specify Optional/Nillable/Unique/Immutable/Default.
Use Ent's native
```
field.Enum
```
for status fields and set default values.
Unify
```
created_at/updated_at
```
; add
```
deleted_at
```
only when soft deletion is required.
Prioritize
```
NULL
```
for missing semantics, avoid empty string sentinels.

Apply ID policy.

Do not manually write
```
id
```
in the schema by default.
Prioritize using the ent generator for centralized ID configuration.
Manually write custom
```
id
```
only when explicitly required by the business, and explain the impact on bind/proto.

Choose relation strategy.

Prioritize weak association IDs (e.g.,
```
user_id
```
/
```
order_id
```
) for relation fields.
Fixed priority for many-to-many: relation-entity > array (confirm dialect support) > join table > JSON (last resort).
JSON is not a regular solution; must explain why typed/array/join table is not feasible.

Plan indexes from real query paths.

Design indexes based on real list/filter/sort/query usage paths.
Prioritize primary key/unique, high-selectivity filtering, and composite indexes for pagination and sorting.
Avoid creating single-column indexes for low-cardinality status unless there is a clear benefit.

Produce Ent + Go implementation guidance.

On the Ent side, prioritize expressing relationships with ID fields, do not enforce edges.
On the Go side, provide batch query solutions: collect IDs -> deduplicate ->
```
IDIn(...)
```
-> map backfill.
Provide chunking strategies and cross-service
```
BatchGet*
```
recommendations when IDs are large.

Add evolution and consistency safeguards.

For read optimization, allow redundant fields (e.g., name/price snapshot).
Prioritize typed/array structures; JSON is only an exception.
For weak association scenarios, must provide dangling refs checkpoints.

Repository Contract (sphere-layout)

必须显式对齐以下生成链路与接入点：

Ent 生成入口：
```
cmd/tools/ent/main.go
```
Bind/Mapper 生成入口：
```
cmd/tools/bind/main.go
```
统一后置命令：
```
make gen/proto
```

输出中必须判断并说明：

```
ent tool config impact
```
：
```
IDType
```
/ ent features / autoproto 影响。
```
bind registration impact
```
：是否需要更新
```
createFilesConf
```
。
```
render/dao/service touchpoints
```
：哪些层要补代码。

Must explicitly align with the following generation links and access points:

Ent generation entry:
```
cmd/tools/ent/main.go
```
Bind/Mapper generation entry:
```
cmd/tools/bind/main.go
```
Unified post-command:
```
make gen/proto
```

The output must include judgments and explanations for:

```
ent tool config impact
```
: Impact on
```
IDType
```
/ ent features / autoproto.
```
bind registration impact
```
: Whether
```
createFilesConf
```
needs to be updated.
```
render/dao/service touchpoints
```
: Which layers need code supplements.

新增实体必改清单

New Entity Mandatory Modification Checklist

如果方案引入新实体，必须逐项检查并在输出中写明：

新 schema 文件与字段/索引。
```
cmd/tools/bind/main.go
```
中
```
createFilesConf
```
注册。
render 层（
```
entmap
```
/
```
entbind
```
消费点）接入。
DAO 层批量查询 helper 与去重策略。
service 层分页/查询/映射接入。
生成命令执行与变更 diff 消费（entpb/proto/bind/map）。

If the scheme introduces new entities, must check each item and specify in the output:

New schema files and fields/indexes.
Registration in
```
createFilesConf
```
in
```
cmd/tools/bind/main.go
```
.
Integration with the render layer (consumption points for
```
entmap
```
/
```
entbind
```
).
DAO layer batch query helpers and deduplication strategies.
Service layer pagination/query/mapping integration.
Execution of generation commands and consumption of change diffs (entpb/proto/bind/map).

失败处理约束

Failure Handling Constraints

以下情况不允许视为完成：

只改 schema，未评估或未说明 bind 注册影响。
涉及绑定字段但未补
```
WithIgnoreFields
```
影响说明（例如
```
created_at/updated_at
```
或敏感字段）。
输出缺少 post-change commands 或 generation diff checklist。

The following cases are not considered complete:

Only modifying the schema without evaluating or explaining the impact on bind registration.
Not supplementing the impact explanation of
```
WithIgnoreFields
```
when involving bound fields (e.g.,
```
created_at/updated_at
```
or sensitive fields).
Output lacks post-change commands or generation diff checklists.

Output Format

使用

references/output-template.md

。

最终输出必须包含：

11 段结构化内容。
sphere-layout 生成链路影响说明。
post-change commands（至少
```
make gen/proto
```
与测试命令）。
generation diff checklist。

Use

references/output-template.md

The final output must include:

11 sections of structured content.
Explanation of impacts on the sphere-layout generation link.
Post-change commands (at least
```
make gen/proto
```
and test commands).
Generation diff checklist.

Resources

```
references/best-practices.md
```
```
references/output-template.md
```
```
references/go-ent-service-patterns.md
```
```
references/ent-schema-examples.md
```

```
references/best-practices.md
```
```
references/output-template.md
```
```
references/go-ent-service-patterns.md
```
```
references/ent-schema-examples.md
```

Notes

本 skill 是 AI 推理驱动，不依赖本地脚本自动生成草稿。
语言默认中文说明 + 英文技术关键词（命令/类型/API 名不翻译）。

This skill is driven by AI reasoning and does not rely on local scripts to automatically generate drafts.
The default language is Chinese explanations + English technical keywords (commands/types/API names are not translated).