db-core-codegen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

db-core Code Generation

db-core 代码生成

Use this skill when you need to generate or update any db-core layer in a module:

DB beans
Document beans
DAOs
DB/document converters
Procedures that call DAOs

This skill is designed to keep generation and scaffolding deterministic, schema-driven, and safe across module variants.

当你需要在模块中生成或更新任何db-core层时使用此技能：

DB beans
Document beans
DAOs
DB/document转换器
调用DAO的流程

此技能旨在确保在不同模块变体中，代码生成和搭建过程具备确定性、schema驱动且安全可靠。

What this skill guarantees

此技能的保障

Schema-first decisions: generation inputs and converter context fields are inferred from discovered schema/model files, not script aliases alone.
Capability-aware planning: generation resolves from module capabilities (or
```
generate
```
script), with DAO
```
--schemas
```
validation in both
```
--plan auto
```
and
```
--plan chain
```
.
Predictable converter scaffolds: defaults to
```
generated/beans/*
```
imports, enforces
```
convertFrom
```
/
```
convertTo
```
mapping rules, and preserves stable context parameter order.
Safe optional wrappers: validates and uses
```
src/beans/*
```
and
```
src/dao/*
```
only when those wrappers actually exist.
Procedure-safe boundaries: procedure APIs stay DB-oriented while DAO APIs stay document-oriented, with convention-aware scaffolding defaults.
Default audit ownership:
```
created_at
```
/
```
updated_at
```
ownership stays in DAO unless explicitly overridden.
Preflight pause/resume: pause only when
```
node_modules
```
is missing; ask the user to run
```
npm run install-snapshot
```
(override script name via
```
--install-script
```
), then resume after user confirmation.
Self-contained execution: command usage, contracts, and post-change checks are defined in this skill without requiring external definition docs.
Module-local context only: inference, examples, conventions, and edits are restricted to the selected
```
--module
```
root.

Schema优先决策：生成输入和转换器上下文字段从已发现的schema/model文件中推断，而非仅依赖脚本别名。
能力感知规划：基于模块能力（或
```
generate
```
脚本）解析生成流程，在
```
--plan auto
```
和
```
--plan chain
```
模式下均会验证DAO的
```
--schemas
```
参数。
可预测的转换器脚手架：默认导入
```
generated/beans/*
```
，强制执行
```
convertFrom
```
/
```
convertTo
```
映射规则，并保持稳定的上下文参数顺序。
安全的可选包装器：仅当
```
src/beans/*
```
和
```
src/dao/*
```
包装器实际存在时才会验证并使用它们。
流程安全边界：流程API保持面向DB的设计，而DAO API保持面向文档的设计，同时遵循约定优先的脚手架默认规则。
默认审计归属：
```
created_at
```
/
```
updated_at
```
的归属权默认由DAO管理，除非显式覆盖。
预检查暂停/恢复：仅当
```
node_modules
```
缺失时暂停流程；要求用户执行
```
npm run install-snapshot
```
（可通过
```
--install-script
```
覆盖脚本名称），待用户确认后再恢复。
自包含执行：命令用法、契约和变更后检查均在此技能中定义，无需依赖外部文档。
仅模块本地上下文：推断、示例、约定和编辑操作均限制在选定的
```
--module
```
根目录下。

NEVER do these (anti-patterns)

绝对禁止的操作（反模式）

NEVER manually edit generated artifacts under
```
generated/beans/*
```
or
```
generated/dao/*
```
.
1. Why: generators overwrite these files, so manual edits drift and are lost on regeneration.
2. Correct action: change schema/model inputs and rerun generation.
NEVER patch generated TypeScript to fix field/type/model mismatches.
1. Why: generated output is derivative; schema/datamodel files are the source of truth.
2. Correct action: update the schema/datamodel inputs first, then regenerate.
NEVER write or modify code outside the target
```
db-core
```
scope during this workflow.
1. Why: cross-scope edits create hidden coupling and unnecessary blast radius.
2. Exception: update code outside
```
db-core
```
  only when the user explicitly asks for it.
NEVER use sibling/other
```
db-core
```
modules for context inference, convention inference, or copy patterns.
1. Why: this introduces cross-module coupling and wrong conventions.
2. Correct action: infer only from files under the selected module root.

绝对禁止手动编辑
```
generated/beans/*
```
或
```
generated/dao/*
```
下的生成工件。
1. 原因：生成器会覆盖这些文件，手动修改会导致代码漂移，在重新生成时丢失。
2. 正确操作：修改schema/model输入后重新运行生成流程。
绝对禁止通过修补生成的TypeScript代码来修复字段/类型/模型不匹配问题。
1. 原因：生成的输出是衍生内容，schema/数据模型文件才是唯一可信源。
2. 正确操作：先更新schema/数据模型输入，再重新生成代码。
绝对禁止在此工作流中编写或修改db-core范围之外的代码。
1. 原因：跨范围编辑会引入隐藏耦合和不必要的影响范围。
2. 例外情况：仅当用户明确要求时，才可以修改db-core范围之外的代码。
绝对禁止从其他db-core模块中获取上下文推断、约定推断或代码复制模板。
1. 原因：这会引入跨模块耦合和错误的约定。
2. 正确操作：仅从选定模块的根目录下的文件中推断信息。

Inputs

输入信息

Collect these before making changes:

```
module selector
```
: exact module path or module hint.

scope

generation-only

converter-only

generation-and-converter

procedure-methods

, or

full-procedure

```
target entities
```
: DB bean + document + DAO + converter names.
```
persistence contract
```
: whether module uses direct
```
generated/dao
```
or optional
```
src/dao
```
wrappers.
```
schema locations
```
: discover from generation scripts when not explicitly provided.

在进行变更前需收集以下信息：

```
module selector
```
：精确的模块路径或模块提示词。

scope

：可选值包括

generation-only

、

converter-only

、

generation-and-converter

、

procedure-methods

或

full-procedure

。

```
target entities
```
：DB bean + document + DAO + 转换器的名称。
```
persistence contract
```
：模块是否使用直接的
```
generated/dao
```
或可选的
```
src/dao
```
包装器。
```
schema locations
```
：未明确提供时，从生成脚本中自动发现。

Module boundary protocol (mandatory)

模块边界协议（强制要求）

Treat the selected
```
--module
```
directory as the only allowed context root for module files.
Read/inspect only paths that are descendants of that module root when inferring schemas, conventions, converters, procedures, and DAO usage.
Reject any inferred/discovered path that resolves outside module root; do not use it for decisions.
Do not sample procedures/converters from other modules for style inference.
If required files are missing inside module root, report and stop or continue with explicit warning; do not substitute from another module.

将选定的
```
--module
```
目录视为模块文件的唯一允许上下文根目录。
推断schema、约定、转换器、流程和DAO用法时，仅读取和检查该模块根目录的子路径。
拒绝任何解析到模块根目录之外的推断/发现路径；不得将其用于决策。
不得从其他模块中采样流程/转换器来进行风格推断。
如果模块根目录内缺少必要文件，需报告并停止或带显式警告继续；不得从其他模块中替换缺失文件。

Reference loading protocol (mandatory)

参考加载协议（强制要求）

Before any implementation, select

scope

and load only the required references.

generation-only

MANDATORY - read entire
```
references/generation-checklist.md
```
.

Do NOT load

references/converter-cookbook.md

references/procedure-cookbook.md

converter-only

MANDATORY - read entire
```
references/converter-cookbook.md
```
.
OPTIONAL - read
```
references/generation-checklist.md
```
only if regeneration is also requested.
Do NOT load
```
references/procedure-cookbook.md
```
.

generation-and-converter

MANDATORY - read entire

references/generation-checklist.md

and

references/converter-cookbook.md

Do NOT load
```
references/procedure-cookbook.md
```
unless procedure scaffolding is explicitly requested.

```
procedure-methods
```
or
```
full-procedure
```
:
1. MANDATORY - read entire
```
references/procedure-cookbook.md
```
  .
2. OPTIONAL - read
```
references/generation-checklist.md
```
  only when generation is in scope.
3. Do NOT load
```
references/converter-cookbook.md
```
  unless converter changes are explicitly requested.
Always report which references were loaded and why before running commands.

在任何实现之前，需选定

scope

并仅加载所需的参考文档。

generation-only

：

强制要求 - 完整读取
```
references/generation-checklist.md
```
。

禁止加载

references/converter-cookbook.md

或

references/procedure-cookbook.md

。

converter-only

：

强制要求 - 完整读取
```
references/converter-cookbook.md
```
。
可选 - 仅当同时要求重新生成时，才读取
```
references/generation-checklist.md
```
。
禁止加载
```
references/procedure-cookbook.md
```
。

generation-and-converter

：

强制要求 - 完整读取

references/generation-checklist.md

和

references/converter-cookbook.md

。

禁止加载
```
references/procedure-cookbook.md
```
，除非显式要求搭建流程。

```
procedure-methods
```
或
```
full-procedure
```
：
1. 强制要求 - 完整读取
```
references/procedure-cookbook.md
```
  。
2. 可选 - 仅当生成在范围内时，才读取
```
references/generation-checklist.md
```
  。
3. 禁止加载
```
references/converter-cookbook.md
```
  ，除非显式要求修改转换器。
在运行命令前，需报告已加载的参考文档及其原因。

Discovery-first workflow (required)

发现优先工作流（必需）

Before creating/updating converters or procedures, do all of the following:

Apply
```
Reference loading protocol (mandatory)
```
and declare loaded files.

Parse module generation scripts and resolve schema/model paths:

document generator (for example

json-to-schemas --datamodel ... --out ...

)

DB generator (for example

jsonschema-to-typescript-objects --input ... --beans-path ...

)

DAO generator (for example

pdm-to-daos --datamodel ... --schemas ... --out ...

)

Resolve all script-relative paths against module root, verify they exist, and verify each resolved path stays within module root.
Read discovered schemas/models to capture per-entity:
1. required document keys (PK/SK/index keys)
2. ```
@entity
```
  discriminator/default
3. field requiredness and types
Infer converter context fields from schema requirements:
1. include required document keys not sourced from DB bean fields
2. prioritize partition/sort keys, then required index keys
3. keep parameter names consistent with existing module converter/procedure patterns
If multiple context-field candidates are plausible:
1. rank candidates with brief reasoning
2. choose the best candidate and proceed
3. surface the decision in output
Missing discovered model/schema files should fail inference (or be surfaced as warnings when non-blocking).

在创建/更新转换器或流程之前，需完成以下所有步骤：

遵循「参考加载协议（强制要求）」并声明已加载的文件。

解析模块生成脚本并解析schema/model路径：

文档生成器（例如

json-to-schemas --datamodel ... --out ...

）

DB生成器（例如

jsonschema-to-typescript-objects --input ... --beans-path ...

）

DAO生成器（例如

pdm-to-daos --datamodel ... --schemas ... --out ...

）

基于模块根目录解析所有脚本相对路径，验证它们是否存在，并确保每个解析后的路径都在模块根目录内。
读取已发现的schemas/models以捕获每个实体的以下信息：
1. 必需的文档键（PK/SK/索引键）
2. ```
@entity
```
  鉴别器/默认值
3. 字段的必填性和类型
从schema要求中推断转换器上下文字段：
1. 包含并非来自DB bean字段的必需文档键
2. 优先考虑分区键/排序键，其次是必需的索引键
3. 保持参数名称与现有模块的转换器/流程模式一致
如果存在多个合理的上下文字段候选：
1. 对候选进行排序并给出简要理由
2. 选择最佳候选并继续
3. 在输出中明确说明该决策
缺失已发现的model/schema文件会导致推断失败（或在非阻塞情况下显示为警告）。

Script commands

脚本命令

Run from repository root.

从仓库根目录运行。

Generation

代码生成

bash

python .agents/skills/db-core-codegen/scripts/run_dbcore_codegen.py \
  --module <module_root> \
  --plan auto

--plan auto

Uses
```
generate
```
script if available.
Otherwise resolves chain by capability (DB, document, DAO, optional tx DAO).

--plan chain

Always resolves chain by capability.
Requires DB + document + DAO capabilities.
Includes tx DAO only when available or explicitly requested.

Install preflight:

Before running generation scripts, checks

generated/beans/db

generated/beans/document

, and

generated/dao

Also checks whether
```
node_modules
```
exists.
If
```
node_modules
```
is missing, do not run install commands automatically; pause and ask the user to run
```
npm run install-snapshot
```
.
Missing/empty generated outputs are surfaced in preflight metadata, but generation still proceeds when
```
node_modules
```
exists.
Override install script name with
```
--install-script <script-name>
```
.

Pause/resume protocol:

On preflight failure, stop generation and report the exact command and module root to the user.
Do not execute install/setup commands on behalf of the user.
After user confirms completion, rerun the same generation command to resume.

bash

python .agents/skills/db-core-codegen/scripts/run_dbcore_codegen.py \
  --module <module_root> \
  --plan auto

--plan auto

：

如果可用则使用
```
generate
```
脚本。
否则根据能力解析流程链（DB、document、DAO、可选的tx DAO）。

--plan chain

：

始终根据能力解析流程链。
需要DB + document + DAO能力。
仅当可用或显式要求时才包含tx DAO。

预检查安装：

在运行生成脚本之前，检查

generated/beans/db

、

generated/beans/document

和

generated/dao

目录。

同时检查
```
node_modules
```
是否存在。
如果
```
node_modules
```
缺失，不得自动运行安装命令；需暂停并要求用户执行
```
npm run install-snapshot
```
。
预检查元数据中会显示缺失/空的生成输出，但只要
```
node_modules
```
存在，生成流程仍会继续。
可通过
```
--install-script <script-name>
```
覆盖安装脚本名称。

暂停/恢复协议：

预检查失败时，停止生成流程并向用户报告确切的命令和模块根目录。
不得代表用户执行安装/设置命令。
用户确认完成后，重新运行相同的生成命令以恢复流程。

Converter scaffolding

转换器脚手架

Flat converter layout:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir . \
  --db-type Account \
  --document-type Account \
  --entity-id com.example.document.account \
  --with-list

Nested converter layout:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir events/event-subscription \
  --db-type EventSubscription \
  --document-type EventSubscription \
  --entity-id com.example.document.event_subscription \
  --context-field user_id:userId

--context-field

is omitted, context fields are inferred from discovered schema/model metadata.

扁平化转换器布局：

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir . \
  --db-type Account \
  --document-type Account \
  --entity-id com.example.document.account \
  --with-list

嵌套转换器布局：

bash

python .agents/skills/db-core-codegen/scripts/generate_db_converter.py \
  --module <module_root> \
  --converter-dir events/event-subscription \
  --db-type EventSubscription \
  --document-type EventSubscription \
  --entity-id com.example.document.event_subscription \
  --context-field user_id:userId

如果省略

--context-field

，则从已发现的schema/model元数据中推断上下文字段。

Procedure scaffolding

流程脚手架

CRUD method scaffolding with convention-aware defaults:

bash

python .agents/skills/db-core-codegen/scripts/generate_db_procedure.py \
  --module <module_root> \
  --db-type Link \
  --document-type Link \
  --methods get,post,update

Common overrides:

```
--timestamp-strategy procedure|dao
```
to override timestamp ownership (default:
```
dao
```
).
```
--post-generate-id always|never
```
to force UUID generation behavior.

--beans-import-style index|entity

and

--dao-import-style index|entity

--dao-class <EntityDaoClass>

and

--dao-method-*

when DAO naming differs.

遵循约定优先默认规则的CRUD方法脚手架：

bash

python .agents/skills/db-core-codegen/scripts/generate_db_procedure.py \
  --module <module_root> \
  --db-type Link \
  --document-type Link \
  --methods get,post,update

常见覆盖配置：

```
--timestamp-strategy procedure|dao
```
：覆盖时间戳归属（默认值：
```
dao
```
）。
```
--post-generate-id always|never
```
：强制UUID生成行为。

--beans-import-style index|entity

和

--dao-import-style index|entity

。

```
--dao-class <EntityDaoClass>
```
和
```
--dao-method-*
```
：当DAO命名不符合约定时使用。

Contracts

契约

Generation contract

生成契约

Validate selected DAO/tx DAO scripts have correct
```
--schemas
```
usage.
Run install preflight checks before generation; pause for manual user action only when
```
node_modules
```
is missing.

Validate generated outputs:

```
generated/beans/db
```
```
generated/beans/document
```
```
generated/dao
```

Validate wrappers only if wrapper files exist.
Validate package export/type contracts when present.

验证选定的DAO/tx DAO脚本是否正确使用
```
--schemas
```
参数。
生成前运行安装预检查；仅当
```
node_modules
```
缺失时暂停，等待用户手动操作。

验证生成输出：

```
generated/beans/db
```
```
generated/beans/document
```
```
generated/dao
```

仅当包装器文件存在时才验证它们。
若存在包导出/类型契约，则进行验证。

Converter contract

转换器契约

```
convertFrom(document)
```
maps
```
Document -> DB
```
.
```
convertTo(db, ...context)
```
maps
```
DB -> Document
```
.
```
convertTo
```
must set
```
@entity
```
.
Context keys must come from schema-first inference and be explicit typed parameters.
Context parameter order should be stable:
1. partition key context
2. sort key context not available on DB bean
3. required index context
Failures must throw
```
ConverterException
```
.

```
convertFrom(document)
```
实现
```
Document -> DB
```
的映射。
```
convertTo(db, ...context)
```
实现
```
DB -> Document
```
的映射。
```
convertTo
```
必须设置
```
@entity
```
字段。
上下文键必须来自schema优先的推断，并且是显式的类型化参数。
上下文参数顺序应保持稳定：
1. 分区键上下文
2. DB bean中不存在的排序键上下文
3. 必需的索引键上下文
执行失败时必须抛出
```
ConverterException
```
。

Procedure contract

流程契约

Procedure boundary accepts/returns DB objects.
DAO boundary accepts/returns document objects.
Procedures should use DAOs via module capability:
1. ```
generated/dao
```
  by default.
2. ```
src/dao
```
  wrappers only when that capability exists in the module.
DAO selection must be explicit from method intent:
1. Use
```
TableDao
```
  for query/list/index pagination and non-atomic batch access.
2. Use
```
TransactionDao
```
  only when atomic all-or-nothing behavior or cross-item invariant enforcement is required.
3. If atomicity is not explicitly required, default to
```
TableDao
```
  (or
```
EntityDao
```
  for single-item key CRUD).
Capture and report DAO choice inputs when scaffolding procedure methods:
1. operation type (
```
query/list
```
  ,
```
single-item CRUD
```
  ,
```
multi-item mutation
```
  )
2. atomicity required (
```
true/false
```
  )
3. invariant scope (single item vs cross-item/cross-entity)
Audit timestamps (
```
created_at
```
/
```
updated_at
```
and camel variants) are DAO-managed by default.
1. Use
```
--timestamp-strategy procedure
```
  only when a module intentionally follows that non-default pattern.
2. Surface the chosen strategy in output.

流程边界接收/返回DB对象。
DAO边界接收/返回文档对象。
流程应通过模块能力使用DAO：
1. 默认使用
```
generated/dao
```
  。
2. 仅当模块具备该能力时才使用
```
src/dao
```
  包装器。
DAO的选择必须明确匹配方法意图：
1. 使用
```
TableDao
```
  处理查询/列表/索引分页和非原子批量访问。
2. 仅当需要原子化的全有或全无行为，或需要跨实体约束校验时才使用
```
TransactionDao
```
  。
3. 若未显式要求原子性，默认使用
```
TableDao
```
  （或针对单键CRUD使用
```
EntityDao
```
  ）。
搭建流程方法时，需捕获并报告DAO选择的输入依据：
1. 操作类型（
```
query/list
```
  、
```
单条数据CRUD
```
  、
```
多条数据变更
```
  ）
2. 是否需要原子性（
```
true/false
```
  ）
3. 约束范围（单条数据 vs 跨数据/跨实体）
审计时间戳（
```
created_at
```
/
```
updated_at
```
及其驼峰式变体）默认由DAO管理。
1. 仅当模块有意遵循非默认模式时，才使用
```
--timestamp-strategy procedure
```
  。
2. 在输出中明确说明所选的策略。

Output checklist

输出检查清单

After changes:

Generation plan is explicit and valid for detected module capabilities.
Converter files compile and exports are updated idempotently.
No hard failures due to absent optional wrapper files.
Discovered schema/model paths are reported.
Inferred context fields are reported per entity with brief reasoning.
Dry-run output is available (human +
```
--json
```
modes).

--json

output includes:

```
discovered_schema_paths
```
```
selected_script_paths
```
```
validated_schema_targets
```
```
inferred_context_fields
```
```
context_decisions
```
```
entity_metadata
```

install_preflight

(

script

script_exists

command

executed

manual_action_required

missing_outputs

missing_node_modules

)

Procedure scaffold output (when used) reports:
1. resolved conventions
2. resolved import styles
3. selected mutation strategy

Report

loaded_references

and

reference_selection_reason

Confirm no manual edits to generated files and no out-of-scope (
```
db-core
```
) changes unless explicitly requested by the user.
Report
```
module_root
```
and confirm all module-file context paths used for inference were under that root.

变更完成后：

生成计划明确且符合检测到的模块能力。
转换器文件可编译，且导出内容支持幂等更新。
不存在因可选包装器文件缺失导致的严重失败。
已报告发现的schema/model路径。
已按实体报告推断的上下文字段及简要理由。
提供试运行输出（人类可读 +
```
--json
```
模式）。

--json

输出包含：

```
discovered_schema_paths
```
```
selected_script_paths
```
```
validated_schema_targets
```
```
inferred_context_fields
```
```
context_decisions
```
```
entity_metadata
```

install_preflight

（

script

、

script_exists

、

command

、

executed

、

manual_action_required

、

missing_outputs

、

missing_node_modules

）

流程脚手架输出（若使用）需报告：
1. 解析后的约定
2. 解析后的导入风格
3. 选定的变更策略

报告

loaded_references

和

reference_selection_reason

。

确认未手动编辑生成文件，且未进行超出db-core范围的变更，除非用户明确要求。
报告
```
module_root
```
，并确认所有用于推断的模块文件上下文路径均在该根目录下。

References

参考文档

Load these only through the

Reference loading protocol (mandatory)

above.

```
references/generation-checklist.md
```
```
references/converter-cookbook.md
```
```
references/procedure-cookbook.md
```

仅可通过上述「参考加载协议（强制要求）」加载以下文档。

```
references/generation-checklist.md
```
```
references/converter-cookbook.md
```
```
references/procedure-cookbook.md
```