DbContext中只改写let 字段

.gitignore

@@ -3,5 +3,9 @@ target/
 # 宏编译产物（构建时自动生成，不入库）
 src/macros/*.cjo
 src/macros/*.dll
+src/tests/*.cj.macrocall
 # 临时/日志
 *.log
+.arts/
+.cache/
+.codegraph/

README.md

@@ -4,7 +4,7 @@
 
 > 仓颉版 ORM：**基于数据模型（POCO + 注解）的映射、增删改查、数据库迁移**。
 
-面向多数据库的方言架构：内置 PostgreSQL（`PostgreSqlDialect`）与 openGauss（`OpenGaussDialect`，继承 PG）方言（对接 [opengauss-driver](../opengauss-driver)），可通过实现 `ISqlDialect` 接口接入 sqlite / mysql 等新数据库。包本身零外部依赖。
+面向多数据库的方言架构：内置 PostgreSQL（`PostgreSqlDialect`）与 openGauss（`OpenGaussDialect`，继承 PG）方言（对接 [opengauss-driver](../opengauss-driver)），可通过实现 `SqlDialect` 接口接入 sqlite / mysql 等新数据库。包本身零外部依赖。
 
 ---
 
@@ -42,7 +42,7 @@ public class User {
 
 ### 2. 定义 DbContext 并增删改查
 
-用 `@DbContext` 宏（推荐）：纯声明类即可，宏自动补 `<: DbContext`、把每个 `DbSet<T>` 声明变成 `public prop` 并注入 `this.set<T>()`、生成 `(driverName, connStr)` 构造与 `migrations()` override：
+用 `@DbContext` 宏（推荐）：纯声明类即可，宏自动补 `<: DbContext`、把每个 **`let` 前缀**的 `DbSet<T>` 字段改写成 `public prop` 并注入 `this.set<T>()`（`var` / `prop` 前缀一律不改动，交给用户自行管理）、生成 `(driverName, connStr)` 构造与 `migrations()` override：
 
 ```cangjie
 import std.database.sql.*
@@ -52,8 +52,8 @@ import simcu::orm.macros.*
 
 @DbContext
 public class AppDbContext {
-    prop users: DbSet<User>
-    prop orders: DbSet<Order>
+    let users: DbSet<User>
+    let orders: DbSet<Order>
 }
 
 main() {
@@ -93,9 +93,9 @@ main() {
 ```cangjie
 import simcu::orm.migrations.*
 
-// 定义迁移（migrationId 用 "yyyyMMddHHmmss_名称"，按字典序应用）
-public class InitialCreate <: Migration {
-    public init() { super("20250701000000_InitialCreate", "创建用户表") }
+// 定义迁移（migrationId 按字典序应用；CLI 生成 "yyyyMMddHHmmss" 时间戳格式，类名 MigrationId<时间戳>）
+public class MigrationId20250701000000 <: Migration {
+    public init() { super("20250701000000", "创建用户表") }
     public override func up(builder: MigrationBuilder): Unit {
         builder.createTable("users") { tb =>
             tb.column("id", ColumnTypes.BigIntCol).primary().autoInc().notNull()
@@ -137,7 +137,7 @@ main() {
     let models = ArrayList<EntityModel>()
     models.add(ModelCache.get<User>())
     models.add(ModelCache.get<Product>())
-    let m0 = gen.initial("20250701000000_InitialCreate", "初始建表", models)
+    let m0 = gen.initial("20250701000000", "初始建表", models)
     Migrator(datasource).migrate([m0])
 
     // 2. 模型变更后：旧模型快照(上次的 models) vs 新模型 → 增量迁移（表/列增删改）
@@ -166,7 +166,7 @@ main() {
 }
 ```
 
-- 快照 JSON 结构:`{"version":1,"models":[{"table":"users","columns":[{...}]}]}`,含表名、列名、类型、主键/自增/必填/最大长度;
+- 快照 JSON 结构:`{"version":4,"models":[{"table":"users","columns":[{...}],"indexes":[{...}]}]}`,含表名、列名、类型、主键/自增/必填/最大长度,以及实体级索引(名称/列/唯一/过滤条件);
 - `ModelSnapshot` 也提供 `capture(models)` / `toJson()` / `fromJson(text)` / `save(path)` / `load(path)`(文件不存在返回 `None`),可自行接入版本化/比较逻辑;
 - 零依赖:`MiniJson` 内置迷你 JSON 解析/序列化,不引入第三方包。
 
@@ -175,7 +175,7 @@ main() {
 - **增量**：`diff(id, desc, oldModels, newModels)` → 新增表 `CreateTable`、删除表 `DropTable`、列增删改（`AddColumn`/`DropColumn`/`AlterColumn`），`down` 自动按 up 逆序反转；
 - **同名列修改数据结构**：`Migrator` 执行 `AddColumn`/`AlterColumn` 前先查 `information_schema`，若库中已有同名列且类型与目标不一致，则**先 `DROP COLUMN` 再 `ADD COLUMN`**（重建该字段）；类型一致时 `AddColumn` 幂等跳过、`AlterColumn` 正常执行（处理非空/长度等变化）；
 - 字段类型 → 列类型映射：`String→TextCol`、`Bool→BoolCol`、`Int8/16/32/64→Tiny/Small/Int/BigIntCol`、`Float32→RealCol`、`Float64→FloatCol`、`DateTime→DateTimeCol`、`Decimal→DecimalCol`、`Array<Byte>→BinaryCol`、`Rune→IntCol`、`Duration→BigIntCol`；`Option<X>` 按内层类型 X 映射且列可空（`None` ↔ `NULL`）；
-- **不支持**（抛异常提示手写迁移）：主键列名变更、主键/自增属性变更；`@Ignore`/`@Column`/`@Required`/`@MaxLength`/`@AutoIncrement`/`@Index` 均会反映到 DDL（`@Index` 生成 `CREATE INDEX`）。
+- **不支持**（抛异常提示手写迁移）：主键列名变更、主键/自增属性变更；`@Ignore`/`@Column`/`@Required`/`@MaxLength`/`@AutoIncrement`/`@Index` 均会反映到 DDL（`@Index` 生成 `CREATE INDEX`）；类级 `@TableIndex` 生成对应的 `CREATE [UNIQUE] INDEX ... [WHERE filter]`（复合/唯一/部分索引），字段级与实体级索引统一走 `IndexSpec` diff（快照 v4 持久化）。
 
 ### 迁移 CLI
 
@@ -190,8 +190,8 @@ import simcu::orm.macros.*
 
 @DbContext
 public class MyDbContext {
-    prop users: DbSet<User>
-    prop orders: DbSet<Order>
+    let users: DbSet<User>
+    let orders: DbSet<Order>
 }
 
 main(args: Array<String>) {
@@ -209,8 +209,8 @@ main(args: Array<String>) {
 
 | 命令 | 作用 |
 |------|------|
-| `cjpm run -- orm add <迁移名>` | 从模型生成迁移 .cj 文件 + 更新注册文件 + 写入快照；模型无变化则跳过 |
-| `cjpm run -- orm rm <迁移名或id>` | 移除已生成的迁移（删除迁移文件 + 注册条目；注册表清空时重置快照） |
+| `cjpm run -- orm add [描述]` | 从模型生成迁移 .cj 文件 + 更新注册文件 + 写入快照（描述可空，仅写入注释与历史记录）；模型无变化则跳过 |
+| `cjpm run -- orm rm <迁移id或类名>` | 移除已生成的迁移（删除迁移文件 + 注册条目；注册表清空时重置快照） |
 | `cjpm run -- orm update` | 连接数据库，按 `migrationId` 字典序应用所有未执行的迁移 |
 | `cjpm run -- orm downgrade [目标]` | 回退迁移：无目标=回退最近一个；有目标=回退到该迁移之后（含该迁移的 down） |
 | `cjpm run -- orm list` | 列出已注册迁移（需真实连接读取历史表） |
@@ -225,6 +225,7 @@ main(args: Array<String>) {
 - **首次使用（无迁移）**：不需要建 `src/migrations/` 目录，也不要写 `import <应用包名>.migrations.*`（该子包不存在会导致编译失败）；首次 `add` 时 CLI 自动创建目录并生成迁移文件 + 注册文件；
 - **生成后手动加 import**：执行 `add` 生成首个迁移后，在 `main()` 所在文件手动加一行 `import <应用包名>.migrations.*`（如 `import myapp.migrations.*`）——注册文件在子包内惰性加载，只有 import 触发后 `update/downgrade/list` 才能看到迁移；之后新增迁移无需再动这行；
 - 迁移 / 注册文件生成在 `src/migrations/`，该目录是**子包**，文件头 `package <应用包名>.migrations`（如应用包 `myapp` → `package myapp.migrations`）；
+- 迁移文件命名为 **id 的蛇形形式**（如 `20250701000000.cj`），仅含 migrationId，不包含描述；CLI 生成的 migrationId 为 `yyyyMMddHHmmss` 时间戳，**迁移类名自动为 `MigrationId<时间戳>`**（如 `MigrationId20250701000000`）；迁移描述可空，写入文件头部 `// 描述: ...` 注释与迁移类 `super("...", "...")` 中；
 - `add` 只生成不执行；执行迁移用 `update`（回退用 `downgrade`），或在应用启动时直接 `db.migrate()`；
 - 快照持久化在 `src/migrations/snapshot.json`；`add` 用「旧快照 vs 当前模型」做 diff，所以**改模型后重新编译应用再 `add`** 即生成增量迁移；
 - 生成源码文本已包含 `import std.collection.*` 等标准库引用，应用无需额外配置。
@@ -272,14 +273,14 @@ public class InitGames {
 orm-cj/
 ├── cjpm.toml                  # 包配置（name = orm, organization = simcu）
 ├── src/
-│   ├── Orm.cj                 # 聚合导出：import simcu::orm.* 即全部可见
-│   ├── annotations/           # @Table / @Column / @Key / @AutoIncrement / @Ignore / @Required / @MaxLength
+│   ├── orm.cj                 # 聚合导出：import simcu::orm.* 即全部可见
+│   ├── annotations/           # @Table / @Column / @Key / @AutoIncrement / @Ignore / @Required / @MaxLength / @Index / @TableIndex
 │   ├── macros/                # @DbContext 类级宏 + @Seed 数据填充宏（自动注册，无需手写注册表）
 │   ├── seeds/                 # Seed 基类 + 进程级填充注册表（registerSeed / allSeeds）
 │   ├── model/                 # EntityModel（反射映射）、ModelCache（模型缓存）、
 │   │                          #   ColumnNamingPolicy（列命名策略）、ValueReader、ParamBinder、GuidUtil
 │   ├── tracking/              # ChangeTracker（操作队列）、EntityState、EntityEntry
-│   ├── sql/                   # ISqlDialect 接口（独立文件）+ PostgreSqlDialect（PG 实现）+
+│   ├── sql/                   # SqlDialect 接口（独立文件）+ PostgreSqlDialect（PG 实现）+
 │   │                          #   OpenGaussDialect（继承 PG）、ColumnTypes（列类型）
 │   ├── query/                 # QueryBuilder<T>（条件/排序/分页）、PagedResult<T>
 │   ├── db/                    # DbContext（连接 + 提交 + 物化 + 数据库存在性/迁移状态检查）、DbSet<T>
@@ -308,6 +309,7 @@ orm-cj/
 | `@Required` | 字段 | 非空列（仅影响建表 DDL） |
 | `@MaxLength[100]` | 字段 | 字符串列最大长度（仅影响建表 DDL） |
 | `@Index` | 字段 | 对该列建索引（索引名默认 `ix_<表名>_<列名>`，迁移 add 自动生成 CREATE INDEX） |
+| `@TableIndex["col1,col2", true, "cond"]` | 类 | 类级复合/唯一/条件索引（对齐 .NET 类级 `[Index(...)]`）；`columns` 为逗号分隔的列/字段名（字段名自动映射为列名），`unique` 是否唯一，`filter` 非空时生成 `... WHERE cond` 部分索引；索引名可省略（`name` 置于末位，留空则按 `ix_<表名>_<首列>` 自动生成），支持 `[columns]`、`[columns, unique]`、`[columns, unique, filter]`、`[columns, unique, filter, name]` 四种用法 |
 
 ### 2. 模型映射约定
 
@@ -322,7 +324,7 @@ orm-cj/
 
 ### 3. DbContext / DbSet
 
-**推荐：`@DbContext` 宏**。把 `DbSet` 声明为 `prop`，宏自动补继承/构造/注入/`migrations()`：
+**推荐：`@DbContext` 宏**。把 `DbSet` 声明为 **`let` 前缀**（`let xxx: DbSet<T>`），宏只处理这种形式：改写成 `public prop xxx: DbSet<T> { get() { this.set<T>() } }`（public getter 保证反射可枚举）；`var` / `prop` 前缀一律不改动。同时自动补继承/构造/`migrations()`：
 
 ```cangjie
 import simcu::orm.*
@@ -332,8 +334,8 @@ import std.collection.*          // migrations() 签名需要 ArrayList
 
 @DbContext
 public class AppDbContext {
-    prop users: DbSet<User>
-    prop orders: DbSet<Order>
+    let users: DbSet<User>
+    let orders: DbSet<Order>
 }
 
 // 用法（宏生成 (driverName, connStr) 构造）
@@ -352,8 +354,12 @@ if (!db.databaseExists() || db.hasPendingMigrations()) { db.migrate() }
 
 ```cangjie
 public class AppDbContext <: DbContext {
-    public let users: DbSet<User>
-    public let orders: DbSet<Order>
+    public prop users: DbSet<User> {
+        get() { this.set<User>() }
+    }
+    public prop orders: DbSet<Order> {
+        get() { this.set<Order>() }
+    }
 
     public init(driverName: String, connStr: String) { super(driverName, connStr) }
     public init(datasource: Datasource) { super(datasource) }
@@ -407,7 +413,7 @@ qb.page(2, 10)                               // PagedResult<User>（items/total/
 
 ### 5. 迁移
 
-- `Migration` 基类：`super("20250701000000_InitialCreate", "描述")`，实现 `up` / `down`；
+- `Migration` 基类：`super("20250701000000", "描述")`，实现 `up` / `down`；
 - `MigrationBuilder`：`createTable` / `dropTable` / `addColumn` / `dropColumn` / `alterColumn` / `renameColumn` / `createIndex` / `dropIndex` / `rawSql`；
 - `ColumnDefinition` 链式：`.primary()` `.autoInc()` `.notNull()` `.withUnique()` `.withMaxLength(n)` `.withDefault(value)`；
 - `ColumnTypes`（定义于 `simcu::orm.sql`）：`BigIntCol`（openGauss 自增 → BIGSERIAL）/ `IntCol`（自增 → SERIAL）/ `SmallIntCol` / `TinyIntCol` / `TextCol`（VARCHAR，默认 255）/ `BoolCol` / `FloatCol`（DOUBLE PRECISION）/ `RealCol` / `DateTimeCol` / `DecimalCol`（DECIMAL(18,6)）/ `BinaryCol`（BYTEA）；实际 DDL 映射由方言 `columnTypeSql` 决定；
@@ -438,7 +444,7 @@ cjpm test    # 纯逻辑单元测试（模型映射/SQL 生成/DDL 生成/QueryB
 - 不支持导航属性 / 延迟加载 / 级联删除（这些能力属于 v2+）；
 - 不支持 LINQ 表达式树，查询以 `filter` 条件方法 + SQL 片段组合；
 - `QueryBuilder` 的 SQL 片段形式（`filter(condition, params)`）需自行保证列名合法（会做标识符引号包裹校验外的处理）——推荐优先使用三参属性形式；
-- 自增主键回读依赖驱动 `RETURNING` 支持（openGauss/PostgreSQL 原生支持；换方言时由 `ISqlDialect.buildInsert` 决定回读策略）。
+- 自增主键回读依赖驱动 `RETURNING` 支持（openGauss/PostgreSQL 原生支持；换方言时由 `SqlDialect.buildInsert` 决定回读策略）。
 
 ---
 
@@ -449,7 +455,7 @@ cjpm test    # 纯逻辑单元测试（模型映射/SQL 生成/DDL 生成/QueryB
 | 数据库驱动（使用者引入，如 `opengauss` → `../opengauss-driver`） | 实现 `std.database.sql` 的 `Datasource`/`Connection`/`Statement` |
 | `stdx`（CANGJIE_STDX_PATH） | 标准扩展库（std.database.sql 接口） |
 
-> orm-cj 包本身零依赖：连接层走 `std.database.sql` 标准接口，SQL/DDL 生成走 `ISqlDialect` 方言接口。新数据库接入 = 实现 `ISqlDialect`（CRUD + 列类型映射 + 差异 DDL 语句）+ 提供对应 `std.database.sql` 驱动。
+> orm-cj 包本身零依赖：连接层走 `std.database.sql` 标准接口，SQL/DDL 生成走 `SqlDialect` 方言接口。新数据库接入 = 实现 `SqlDialect`（CRUD + 列类型映射 + 差异 DDL 语句）+ 提供对应 `std.database.sql` 驱动。
 
 ---
 

cjpm.toml

@@ -1,22 +1,22 @@
 [package]
-  cjc-version = "1.1.3"
-  name = "orm"
-  organization = "simcu"
-  description = "SimApi 数据访问层 ORM：数据模型映射 + 增删改查 + 数据库迁移；多方言架构，内置 openGauss/PostgreSQL 方言"
-  version = "1.2.1"
-  target-dir = ""
-  output-type = "static"
+cjc-version = "1.1.3"
+name = "orm"
+organization = "simcu"
+description = "SimApi 数据访问层 ORM：数据模型映射 + 增删改查 + 数据库迁移；多方言架构，内置 openGauss/PostgreSQL 方言"
+version = "1.4.1"
+target-dir = ""
+output-type = "static"
 
 [target]
-  [target.x86_64-w64-mingw32]
-    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
-    [target.x86_64-w64-mingw32.bin-dependencies]
-      path-option = [ "${CANGJIE_STDX_PATH}" ]
-  [target.x86_64-unknown-linux-gnu]
-    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
-    [target.x86_64-unknown-linux-gnu.bin-dependencies]
-      path-option = [ "${CANGJIE_STDX_PATH}" ]
-  [target.aarch64-unknown-linux-gnu]
-    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
-    [target.aarch64-unknown-linux-gnu.bin-dependencies]
-      path-option = [ "${CANGJIE_STDX_PATH}" ]
+[target.x86_64-w64-mingw32]
+compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
+[target.x86_64-w64-mingw32.bin-dependencies]
+path-option = ["${CANGJIE_STDX_PATH}"]
+[target.x86_64-unknown-linux-gnu]
+compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
+[target.x86_64-unknown-linux-gnu.bin-dependencies]
+path-option = ["${CANGJIE_STDX_PATH}"]
+[target.aarch64-unknown-linux-gnu]
+compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated"
+[target.aarch64-unknown-linux-gnu.bin-dependencies]
+path-option = ["${CANGJIE_STDX_PATH}"]

src/annotations/annotations.cj

@@ -101,3 +101,55 @@ public class MaxLength {
 public class Index {
     public const init() {}
 }
+
+/**
+ * 类级复合/条件索引（对齐 .NET 类级 [Index(...)]，支持多列 + 唯一 + 部分索引）。
+ * 标注在实体类上，一个类声明一个复合索引（Cangjie 反射 findAnnotation 在同类多标注时读不到）。
+ *
+ * 用法：
+ *   @TableIndex["source_server,name", true, "kind = 'Passport'"]
+ *   public class Asset { ... }
+ *
+ * 参数（顺序）：
+ *   - columns 逗号分隔的列名/字段名（字段名自动映射为列名，如 "source_server,name" 或 "_sourceServer,_name"）
+ *   - unique  是否唯一索引，默认 false
+ *   - filter  部分索引过滤条件（原始 SQL，如 "kind = 'Passport'"；空串表示全表索引，不生成 WHERE），默认空
+ *   - name    索引名，可为空；为空时自动生成 ix_<表名>_<首列名>
+ *
+ * 重载：@TableIndex[columns]（全默认）、[columns, unique]、[columns, unique, filter]、[columns, unique, filter, name]。
+ */
+@Annotation[target: [Type]]
+public class TableIndex {
+    public let columns: String
+    public let unique: Bool
+    public let filter: String
+    public let name: String
+
+    public const init(columns: String, unique: Bool, filter: String, name: String) {
+        this.columns = columns
+        this.unique = unique
+        this.filter = filter
+        this.name = name
+    }
+
+    public const init(columns: String, unique: Bool, filter: String) {
+        this.columns = columns
+        this.unique = unique
+        this.filter = filter
+        this.name = ""
+    }
+
+    public const init(columns: String, unique: Bool) {
+        this.columns = columns
+        this.unique = unique
+        this.filter = ""
+        this.name = ""
+    }
+
+    public const init(columns: String) {
+        this.columns = columns
+        this.unique = false
+        this.filter = ""
+        this.name = ""
+    }
+}

src/cli/cli_context.cj

@@ -20,7 +20,7 @@ public interface CliContext {
     /// 应用主数据源
     func getDatasource(): Datasource
     /// SQL 方言
-    func getDialect(): ISqlDialect
+    func getDialect(): SqlDialect
     /// 迁移列表（子类 override migrations() 提供）
     func getMigrations(): ArrayList<Migration>
     /// 应用所有迁移

src/cli/migration_cli.cj

@@ -13,7 +13,7 @@
  *   - 模型:反射收集实例的 DbSet<T> 属性(getModels())
  *   - 连接/驱动/方言:构造参数
  *   - 迁移列表:子类 override migrations()(宏默认返回 orm-cj 全局注册表,
- *     CLI 生成的 src/migrations/MigrationRegistry.cj 在模块加载时自动注册)
+ *     CLI 生成的 src/migrations/migration_registry.cj 在模块加载时自动注册)
  *
  * 注意:应用侧(DataContext.cj 或 main.cj)需要一行
  *   import <应用包名>.migrations.*
@@ -21,8 +21,8 @@
  * 才会在 main() 前执行并注册迁移;新项目需先建 src/migrations/ 目录(空包)。
  *
  * 命令:
- *   add <迁移名>        模型 → 迁移 .cj 文件(落盘) + 更新快照 + 更新迁移注册文件
- *   rm <迁移名/id>      移除已生成的迁移(删除迁移文件 + 注册条目 + 快照回退到前一状态)
+ *   add [描述]          模型 → 迁移 .cj 文件(落盘) + 更新快照 + 更新迁移注册文件(描述可空,仅写入注释与历史记录)
+ *   rm <迁移id/类名>    移除已生成的迁移(删除迁移文件 + 注册条目 + 快照回退到前一状态)
  *   update              应用所有未执行的迁移
  *   downgrade [目标]    回退迁移(执行 down;无目标=回退最近一个,有目标=回退到该迁移之后)
  *   list                列出已应用/待应用迁移
@@ -55,7 +55,7 @@ public class MigrationCli {
     // 注册文件与迁移文件同目录(src/migrations/,package = 应用包名.migrations)。
     // 子包默认惰性加载,顶层 let 不会执行;应用侧需一行
     // `import <应用包名>.migrations.*` 触发加载后,注册才生效。
-    private var _registryPath = "src/migrations/MigrationRegistry.cj"
+    private var _registryPath = "src/migrations/migration_registry.cj"
 
     public init() {}
 
@@ -94,7 +94,7 @@ public class MigrationCli {
 
     private func dispatch(args: ArrayList<String>, models: () -> ArrayList<EntityModel>,
         datasource: () -> Datasource, migrations: () -> ArrayList<Migration>,
-        dialect: ISqlDialect, seedCtx: ?Any): Int64 {
+        dialect: SqlDialect, seedCtx: ?Any): Int64 {
         if (args.size == 0) {
             printHelp()
             return 0
@@ -122,7 +122,7 @@ public class MigrationCli {
 
     /// database <子命令>:数据库级操作(不需要迁移注册)
     private func cmdDatabase(args: ArrayList<String>, datasource: () -> Datasource,
-        dialect: ISqlDialect): Int64 {
+        dialect: SqlDialect): Int64 {
         if (args.size < 2) {
             println("用法: simcu::orm database <truncate|drop>")
             return 1
@@ -137,7 +137,7 @@ public class MigrationCli {
     }
 
     /// database truncate:清空所有业务表数据(保留表结构与迁移历史)
-    private func cmdTruncate(datasource: () -> Datasource, dialect: ISqlDialect): Int64 {
+    private func cmdTruncate(datasource: () -> Datasource, dialect: SqlDialect): Int64 {
         try {
             let migrator = Migrator(datasource(), dialect)
             let n = migrator.truncateAll()
@@ -151,7 +151,7 @@ public class MigrationCli {
     }
 
     /// database drop:删除所有表(含迁移历史),完全清空数据库;之后可 update 重建
-    private func cmdDrop(datasource: () -> Datasource, dialect: ISqlDialect): Int64 {
+    private func cmdDrop(datasource: () -> Datasource, dialect: SqlDialect): Int64 {
         try {
             let migrator = Migrator(datasource(), dialect)
             let n = migrator.dropAllTables()
@@ -164,33 +164,29 @@ public class MigrationCli {
         }
     }
 
-    /// add <迁移名>:模型 → 迁移文件 + 快照 + 注册
+    /// add [描述]:模型 → 迁移文件 + 快照 + 注册。
+    /// 描述可空(多词自动拼接),仅写入迁移文件头注释与迁移历史记录,不参与命名;
+    /// migrationId = 时间戳(如 20250701000000),类名自动生成 MigrationId<时间戳>。
     private func cmdAdd(args: ArrayList<String>, models: () -> ArrayList<EntityModel>): Int64 {
-        if (args.size < 2) {
-            println("用法: simcu::orm add <迁移名>")
-            return 1
-        }
-        let name = args[1]
-        if (!isValidIdentifier(name)) {
-            println("simcu::orm: 迁移名 '${name}' 不是合法标识符(字母/数字/下划线,首字符不能是数字)")
-            return 1
-        }
-        // 迁移名以 test 结尾会生成 *_test.cj 文件,cjc 会把 *_test.cj 当作测试文件,
-        // 在 cjpm build(非 test)时排除,导致注册文件引用不到该类而编译失败。
-        if (name.endsWith("test")) {
-            println("simcu::orm: 迁移名 '${name}' 以 test 结尾,生成的 *_test.cj 会被编译器当作测试文件排除;请换一个名称")
-            return 1
+        var description = ""
+        if (args.size >= 2) {
+            for (i in 1..args.size) {
+                if (i > 1) {
+                    description = description + " "
+                }
+                description = description + args[i]
+            }
         }
         let appPkg = detectPackage()
         let ts = DateTime.now().format("yyyyMMddHHmmss")
-        let id = "${ts}_${name}"
+        let id = ts
         let gen = MigrationGenerator()
         let current = models()
         var m: Migration
         if (let Some(snap) <- ModelSnapshot.load(_snapshotPath)) {
-            m = gen.diff(id, name, snap.toModels(), current)
+            m = gen.diff(id, description, snap.toModels(), current)
         } else {
-            m = gen.initial(id, name, current)
+            m = gen.initial(id, description, current)
         }
         // 无变化检测(对齐 dotnet ef:模型未变则不生成)
         let probe = MigrationBuilder()
@@ -205,9 +201,11 @@ public class MigrationCli {
         let migPkg = "${appPkg}.migrations"
         let fg = MigrationFileGenerator()
         let path = fg.writeMigration(migPkg, m, _migrationsDir)
-        fg.updateRegistry(migPkg, _registryPath, MigrationFileGenerator.classNameOf(id))
+        let className = MigrationFileGenerator.classNameOf(id)
+        fg.updateRegistry(migPkg, _registryPath, className)
         ModelSnapshot.capture(current).save(_snapshotPath)
         println("simcu::orm: 已生成迁移 ${id}")
+        println("  迁移类: ${className}")
         println("  迁移文件: ${path}")
         println("  注册文件: ${_registryPath}")
         println("  快照: ${_snapshotPath}")
@@ -217,7 +215,7 @@ public class MigrationCli {
 
     /// update:应用所有未执行的迁移
     private func cmdUpdate(datasource: () -> Datasource,
-        migrations: () -> ArrayList<Migration>, dialect: ISqlDialect): Int64 {
+        migrations: () -> ArrayList<Migration>, dialect: SqlDialect): Int64 {
         let list = migrations()
         if (list.size == 0) {
             println("simcu::orm: 未注册任何迁移(检查 ${_registryPath})")
@@ -231,7 +229,7 @@ public class MigrationCli {
 
     /// downgrade [目标]:回退迁移（执行 down + 删除历史记录；无目标 = 回退最近一个）
     private func cmdDowngrade(datasource: () -> Datasource, migrations: () -> ArrayList<Migration>,
-        dialect: ISqlDialect, args: ArrayList<String>): Int64 {
+        dialect: SqlDialect, args: ArrayList<String>): Int64 {
         let list = migrations()
         if (list.size == 0) {
             println("simcu::orm: 未注册任何迁移(检查 ${_registryPath})")
@@ -257,7 +255,7 @@ public class MigrationCli {
     /// rm <迁移名或id>:移除已生成的迁移(删除迁移文件 + 注册条目 + 快照回退)
     private func cmdRm(args: ArrayList<String>): Int64 {
         if (args.size < 2) {
-            println("用法: simcu::orm rm <迁移名或id>")
+            println("用法: simcu::orm rm <迁移id或类名>")
             return 1
         }
         let target = args[1]
@@ -266,12 +264,12 @@ public class MigrationCli {
             println("simcu::orm: 迁移目录不存在(${_migrationsDir}),没有可移除的迁移")
             return 1
         }
-        // 扫描迁移目录,收集迁移 id(文件名去 .cj;排除注册文件/占位文件)
+        // 扫描迁移目录,收集迁移 id(文件名去 .cj = migrationId;排除注册文件/占位文件)
         let ids = ArrayList<String>()
         for (f in Directory.readFrom(dir)) {
             if (f.isRegular()) {
                 let name = f.name
-                if (name.endsWith(".cj") && name != "MigrationRegistry.cj" && name != "_placeholder.cj") {
+                if (name.endsWith(".cj") && name != "migration_registry.cj" && name != "_placeholder.cj") {
                     ids.add(name[..name.size - 3])
                 }
             }
@@ -334,7 +332,7 @@ public class MigrationCli {
 
     /// list:显示已应用/待应用迁移(空库/全新库时全部显示为待应用)
     private func cmdList(datasource: () -> Datasource, migrations: () -> ArrayList<Migration>,
-        dialect: ISqlDialect): Int64 {
+        dialect: SqlDialect): Int64 {
         let list = migrations()
         if (list.size == 0) {
             println("simcu::orm: 未注册任何迁移(检查 ${_registryPath})")
@@ -365,7 +363,7 @@ public class MigrationCli {
 
     /// seed:列出/运行数据填充(@Seed 标注的类,按 seedId 唯一前缀匹配;--all 全部;无参=列出)
     private func cmdSeed(datasource: () -> Datasource, migrations: () -> ArrayList<Migration>,
-        dialect: ISqlDialect, args: ArrayList<String>, seedCtx: ?Any): Int64 {
+        dialect: SqlDialect, args: ArrayList<String>, seedCtx: ?Any): Int64 {
         let list = allSeeds()
         if (list.size == 0) {
             println("simcu::orm: 未注册任何填充(检查 @Seed 标注的类是否存在,并确认应用已 import 对应包)")
@@ -524,29 +522,6 @@ public class MigrationCli {
         b == 0x20 || b == 0x09 || b == 0x0D || b == 0x0A
     }
 
-    /// 合法标识符:字母/数字/下划线,首字符不能是数字
-    private static func isValidIdentifier(s: String): Bool {
-        if (s.isEmpty()) {
-            return false
-        }
-        let bytes = s.toArray()
-        var i: Int64 = 0
-        while (i < bytes.size) {
-            let b = bytes[i]
-            let isDigit = b >= 0x30 && b <= 0x39
-            let isLetter = (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A)
-            let isUnderscore = b == 0x5F
-            if (i == 0 && isDigit) {
-                return false
-            }
-            if (!isDigit && !isLetter && !isUnderscore) {
-                return false
-            }
-            i += 1
-        }
-        true
-    }
-
     private static func printHelp(): Unit {
         println("simcu::orm cli - 数据库迁移管理程序")
         println("")
@@ -559,8 +534,8 @@ public class MigrationCli {
             return
         }
         println("用法:")
-        println("  add <迁移名>          从模型生成迁移 .cj 文件,更新快照与注册(无变化则跳过)")
-        println("  rm <迁移名或id>       移除已生成的迁移(删除迁移文件 + 注册条目 + 快照回退)")
+        println("  add [描述]            从模型生成迁移 .cj 文件,更新快照与注册(描述可空;无变化则跳过)")
+        println("  rm <迁移id或类名>     移除已生成的迁移(删除迁移文件 + 注册条目 + 快照回退)")
         println("  update                应用所有未执行的迁移")
         println("  downgrade [目标]      回退迁移:无目标=回退最近一个;有目标=回退到该迁移之后")
         println("  list                  列出已应用/待应用迁移")

src/cli/migration_file_generator.cj

@@ -2,7 +2,7 @@
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
  * 迁移落盘生成器(对齐 dotnet ef migrations add):
  * - Migration 对象 → .cj 源文件文本(迁移类 up/down 用 MigrationBuilder 声明式重建),
- * - 自动维护迁移注册文件 MigrationRegistry.cj(add 时插入新迁移实例)。
+ * - 自动维护迁移注册文件 migration_registry.cj(add 时插入新迁移实例)。
  *
  * 生成文件的格式:
  *   // 此文件由 simcu::orm CLI 自动生成,请勿手动编辑
@@ -11,8 +11,8 @@
  *   import simcu::orm.migrations.*
  *   import simcu::orm.sql.*
  *
- *   public class InitialCreate <: Migration {
- *       public init() { super("20250701000000_InitialCreate", "初始建表") }
+ *   public class MigrationId20250701000000 <: Migration {
+ *       public init() { super("20250701000000", "初始建表") }
  *       public override func up(builder: MigrationBuilder): Unit {
  *           builder.createTable("users") { tb =>
  *               tb.column("id", ColumnTypes.BigIntCol).primary().autoInc().notNull()
@@ -62,6 +62,9 @@ public class MigrationFileGenerator {
         }
         let sb = StringBuilder()
         sb.append("// 此文件由 simcu::orm CLI 自动生成,请勿手动编辑\n")
+        if (!m.description.isEmpty()) {
+            sb.append("// 描述: ${commentSafe(m.description)}\n")
+        }
         sb.append("package ${appPackage}\n\n")
         sb.append("import std.collection.*\n")
         sb.append("import simcu::orm.migrations.*\n")
@@ -80,15 +83,12 @@ public class MigrationFileGenerator {
         sb.toString()
     }
 
-    /// migrationId "20250701000000_InitialCreate" → 类名 "InitialCreate"
+    /// migrationId(纯时间戳) → 类名: "20250701000000" → "MigrationId20250701000000"
     public static func classNameOf(migrationId: String): String {
-        if (let Some(idx) <- migrationId.lastIndexOf("_")) {
-            return migrationId[idx + 1..]
-        }
-        migrationId
+        "MigrationId${migrationId}"
     }
 
-    /// migrationId → 文件名 "20250701000000_InitialCreate.cj"
+    /// migrationId → 文件名: "20250701000000" → "20250701000000.cj"
     public static func fileNameOf(migrationId: String): String {
         "${migrationId}.cj"
     }
@@ -148,6 +148,19 @@ public class MigrationFileGenerator {
         (b >= 0x30 && b <= 0x39) || (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) || b == 0x5F
     }
 
+    /// 注释安全化:换行/回车替换为空格,避免破坏行注释
+    private static func commentSafe(s: String): String {
+        var out = StringBuilder()
+        for (c in s.runes()) {
+            if (c == Rune(0x0A) || c == Rune(0x0D)) {
+                out.append(" ")
+            } else {
+                out.append(c)
+            }
+        }
+        out.toString()
+    }
+
     /// 追加注册:旧文件 + 新类名 → 完整注册文件源码(已写新文件并返回路径)
     public func updateRegistry(appPackage: String, registryPath: String, newClassName: String): String {
         var entries = ArrayList<String>()
@@ -211,7 +224,10 @@ public class MigrationFileGenerator {
                 sb.append("${indent}builder.renameColumn(\"${escape(op.tableName)}\", \"${escape(op.columnName)}\", \"${escape(op.newColumnName)}\")\n")
             case MigrationOperationKind.CreateIndex =>
                 sb.append("${indent}builder.createIndex(\"${escape(op.indexName)}\", \"${escape(op.tableName)}\", ArrayList<String>([${colList(op.columnNames)}])")
-                if (op.unique) {
+                if (op.filter != "") {
+                    let uniqueLiteral = if (op.unique) { "true" } else { "false" }
+                    sb.append(", ${uniqueLiteral}, \"${escape(op.filter)}\"")
+                } else if (op.unique) {
                     sb.append(", true")
                 }
                 sb.append(")\n")

src/db/db_context.cj

@@ -41,13 +41,13 @@ import simcu::orm.migrations.{Migrator, Migration}
  */
 public open class DbContext <: CliContext {
     internal let datasource: Datasource
-    internal let dialect: ISqlDialect
+    internal let dialect: SqlDialect
     internal let tracker = ChangeTracker()
     private let _sets = HashMap<String, Any>()
     private var _driverName: String
     private var _connString: String
 
-    public init(datasource: Datasource, dialect: ISqlDialect) {
+    public init(datasource: Datasource, dialect: SqlDialect) {
         this.datasource = datasource
         this.dialect = dialect
         this._driverName = ""
@@ -59,7 +59,7 @@ public open class DbContext <: CliContext {
     }
 
     /// 便捷构造：由连接字符串创建 Datasource（驱动构建收敛在 DatasourceFactory）
-    public init(connStr: String, dialect: ISqlDialect) {
+    public init(connStr: String, dialect: SqlDialect) {
         this(DatasourceFactory.create(connStr), dialect)
         this._driverName = DatasourceFactory.detectDriver(connStr, DatasourceFactory.DEFAULT_DRIVER)
         this._connString = connStr
@@ -70,7 +70,7 @@ public open class DbContext <: CliContext {
     }
 
     /// 便捷构造：显式指定驱动类型（如 "pgsql"）+ 连接字符串
-    public init(driverName: String, connStr: String, dialect: ISqlDialect) {
+    public init(driverName: String, connStr: String, dialect: SqlDialect) {
         this(DatasourceFactory.create(connStr, driverName), dialect)
         this._driverName = DatasourceFactory.normalizeDriverName(driverName)
         this._connString = connStr
@@ -200,7 +200,7 @@ public open class DbContext <: CliContext {
     }
 
     /// 当前方言（子类/应用可读取）
-    public func getDialect(): ISqlDialect {
+    public func getDialect(): SqlDialect {
         dialect
     }
 

src/macros/db_context_macro.cj

@@ -5,13 +5,14 @@
  * 用法（对齐 EF Core 声明式体验）：
  *   @DbContext
  *   public class DataContext {
- *       public var users: DbSet<User>
- *       public var bots: DbSet<Bot>
+ *       let users: DbSet<User>
+ *       let bots: DbSet<Bot>
  *   }
  *
  * 展开行为：
  *   - 自动补 `<: DbContext`（标注的类不能自带继承）
- *   - 每个 DbSet<T> 字段/无 getter prop -> `public prop name: DbSet<T> { get() { this.set<T>() } }`
+ *   - 只处理「let 前缀」的 DbSet<T> 字段 -> `public prop name: DbSet<T> { get() { this.set<T>() } }`；
+ *     var / prop 一律不改动（交给用户自行管理）
  *   - 自动生成 `init(driverName: String, connStr: String)` 调用 super
  *   - 自动生成 `migrations()` override，返回 orm-cj 全局注册表 allMigrations()
  *     （CLI 生成的 src/migrations/MigrationRegistry.cj 在模块加载时自动注册；
@@ -44,24 +45,21 @@ public macro DbContext(input: Tokens): Tokens {
         cd.superTypes.add(RefType(cangjieLex("DbContext")))
         cd.upperBound = Token(TokenKind.UPPERBOUND)
 
-        // 2. DbSet<T> 字段/无 getter prop -> public prop { get() { this.set<T>() } }
+        // 2. 只处理「let 前缀」的 DbSet<T> 字段 -> `public prop { get() { this.set<T>() } }`；
+        //    var / prop 一律不改动（交给用户自行管理）
         let newDecls = ArrayList<Decl>()
         for (d in cd.body.decls) {
             match (d) {
                 case vd: VarDecl =>
                     let typeName = vd.declType.toTokens().toString()
-                    if (isDbSetType(typeName)) {
+                    if (isDbSetType(typeName) && declIsLet(vd.toTokens().toString())) {
                         newDecls.add(buildSetProp(vd.identifier.value, typeName))
                     } else {
                         newDecls.add(d)
                     }
                 case pd: PropDecl =>
-                    let typeName = pd.declType.toTokens().toString()
-                    if (isDbSetType(typeName)) {
-                        newDecls.add(buildSetProp(pd.identifier.value, typeName))
-                    } else {
-                        newDecls.add(d)
-                    }
+                    // prop 一律不改动
+                    newDecls.add(d)
                 case _ => newDecls.add(d)
             }
         }
@@ -86,6 +84,22 @@ private func isDbSetType(t: String): Bool {
     t.indexOf("DbSet") == Some(0) && t.indexOf("<").getOrThrow() > 0
 }
 
+/// 判断声明关键字是否为 let（保留字 let/var 只会独立出现在声明词位置，
+/// 按词边界匹配避免误伤类型名/泛型实参里的子串）。
+/// prop 是 PropDecl（非 VarDecl），根本不会走到这里。
+private func declIsLet(t: String): Bool {
+    hasWord(t, "let") && !hasWord(t, "var")
+}
+
+/// 判断字符串中 w 是否作为独立词出现（textified 输出用单个空格分隔词）
+private func hasWord(s: String, w: String): Bool {
+    let padded = " " + s + " "
+    match (padded.indexOf(" " + w + " ")) {
+        case Some(_) => true
+        case None => false
+    }
+}
+
 /// 生成 `public prop name: DbSet<T> { get() { this.set<T>() } }`
 private func buildSetProp(name: String, typeName: String): Decl {
     let inner = extractInnerType(typeName)

src/migrations/migration_generator.cj

@@ -214,72 +214,70 @@ public class MigrationGenerator {
         diffIndexes(upOps, downOps, old, cur)
     }
 
-    /// 索引 diff：按 indexName 匹配，处理新增/删除/变更（变更 = up 先 DROP 再 CREATE，down 反之）
+    /// 索引 diff：按 indexName 匹配，处理新增/删除/变更（变更 = up 先 DROP 再 CREATE，down 反之）。
+    /// 统一处理字段级(@Index)与实体级(@TableIndex)索引，均归一为 IndexSpec。
     private static func diffIndexes(upOps: ArrayList<MigrationOperation>, downOps: ArrayList<MigrationOperation>,
         old: EntityModel, cur: EntityModel): Unit {
-        var oldIdx = HashMap<String, PropertyModel>()
-        for (p in old.properties) {
-            if (p.isIndex) {
-                oldIdx[p.indexName] = p
-            }
+        var oldIdx = HashMap<String, IndexSpec>()
+        for (s in collectIndexSpecs(old)) {
+            oldIdx[s.indexName] = s
         }
-        var curIdx = HashMap<String, PropertyModel>()
-        for (p in cur.properties) {
-            if (p.isIndex) {
-                curIdx[p.indexName] = p
-            }
+        var curIdx = HashMap<String, IndexSpec>()
+        for (s in collectIndexSpecs(cur)) {
+            curIdx[s.indexName] = s
         }
         // 新增 / 变更
-        for (p in cur.properties) {
-            if (!p.isIndex) {
-                continue
-            }
-            if (let Some(op) <- oldIdx.get(p.indexName)) {
-                if (!sameIndex(op, p)) {
-                    upOps.add(dropIndexOp(cur.tableName, p.indexName))
-                    downOps.add(createIndexOp(old.tableName, op))
-                    upOps.add(createIndexOp(cur.tableName, p))
-                    downOps.add(dropIndexOp(old.tableName, p.indexName))
+        for (s in collectIndexSpecs(cur)) {
+            if (let Some(os) <- oldIdx.get(s.indexName)) {
+                if (!sameIndex(os, s)) {
+                    upOps.add(dropIndexOp(cur.tableName, s.indexName))
+                    downOps.add(createIndexOp(os))
+                    upOps.add(createIndexOp(s))
+                    downOps.add(dropIndexOp(old.tableName, s.indexName))
                 }
             } else {
-                upOps.add(createIndexOp(cur.tableName, p))
-                downOps.add(dropIndexOp(cur.tableName, p.indexName))
+                upOps.add(createIndexOp(s))
+                downOps.add(dropIndexOp(cur.tableName, s.indexName))
             }
         }
         // 删除
-        for (p in old.properties) {
-            if (!p.isIndex) {
-                continue
-            }
-            if (!curIdx.contains(p.indexName)) {
-                upOps.add(dropIndexOp(old.tableName, p.indexName))
-                downOps.add(createIndexOp(old.tableName, p))
+        for (s in collectIndexSpecs(old)) {
+            if (!curIdx.contains(s.indexName)) {
+                upOps.add(dropIndexOp(old.tableName, s.indexName))
+                downOps.add(createIndexOp(s))
             }
         }
     }
 
-    private static func sameIndex(a: PropertyModel, b: PropertyModel): Bool {
-        a.columnName == b.columnName && a.indexUnique == b.indexUnique
+    private static func sameIndex(a: IndexSpec, b: IndexSpec): Bool {
+        if (a.unique != b.unique || a.filter != b.filter) {
+            return false
+        }
+        if (a.columnNames.size != b.columnNames.size) {
+            return false
+        }
+        for (i in 0..a.columnNames.size) {
+            if (a.columnNames[i] != b.columnNames[i]) {
+                return false
+            }
+        }
+        true
     }
 
-    /// 该模型所有索引列 → CREATE INDEX op（up 用）
+    /// 该模型所有索引（字段级 + 实体级）→ CREATE INDEX op（up 用）
     private static func createIndexOpsFor(model: EntityModel): ArrayList<MigrationOperation> {
         let ops = ArrayList<MigrationOperation>()
-        for (p in model.properties) {
-            if (p.isIndex) {
-                ops.add(createIndexOp(model.tableName, p))
-            }
+        for (s in collectIndexSpecs(model)) {
+            ops.add(createIndexOp(s))
         }
         ops
     }
 
-    /// 该模型所有索引列 → DROP INDEX op（down 用，与 createIndexOpsFor 同序）
+    /// 该模型所有索引（字段级 + 实体级）→ DROP INDEX op（down 用，与 createIndexOpsFor 同序）
     private static func dropIndexOpsFor(model: EntityModel): ArrayList<MigrationOperation> {
         let ops = ArrayList<MigrationOperation>()
-        for (p in model.properties) {
-            if (p.isIndex) {
-                ops.add(dropIndexOp(model.tableName, p.indexName))
-            }
+        for (s in collectIndexSpecs(model)) {
+            ops.add(dropIndexOp(model.tableName, s.indexName))
         }
         ops
     }
@@ -307,6 +305,35 @@ public class MigrationGenerator {
         }
     }
 
+    /// 收集模型上的全部索引规格：先字段级(@Index)，再实体级(@TableIndex)。
+    /// 顺序即生成顺序，down 与之对应逆序销毁。
+    private static func collectIndexSpecs(model: EntityModel): ArrayList<IndexSpec> {
+        let specs = ArrayList<IndexSpec>()
+        for (p in model.properties) {
+            if (p.isIndex) {
+                let s = IndexSpec()
+                s.table = model.tableName
+                s.indexName = p.indexName
+                s.unique = p.indexUnique
+                s.filter = ""
+                s.columnNames.add(p.columnName)
+                specs.add(s)
+            }
+        }
+        for (e in model.indexes) {
+            let s = IndexSpec()
+            s.table = model.tableName
+            s.indexName = e.indexName
+            s.unique = e.unique
+            s.filter = e.filter
+            for (c in e.columnNames) {
+                s.columnNames.add(c)
+            }
+            specs.add(s)
+        }
+        specs
+    }
+
     private static func indexByTable(models: ArrayList<EntityModel>): HashMap<String, EntityModel> {
         let map = HashMap<String, EntityModel>()
         for (model in models) {
@@ -362,12 +389,15 @@ public class MigrationGenerator {
         op
     }
 
-    private static func createIndexOp(table: String, p: PropertyModel): MigrationOperation {
+    private static func createIndexOp(s: IndexSpec): MigrationOperation {
         let op = MigrationOperation(MigrationOperationKind.CreateIndex)
-        op.tableName = table
-        op.indexName = p.indexName
-        op.unique = p.indexUnique
-        op.columnNames.add(p.columnName)
+        op.tableName = s.table
+        op.indexName = s.indexName
+        op.unique = s.unique
+        op.filter = s.filter
+        for (c in s.columnNames) {
+            op.columnNames.add(c)
+        }
         op
     }
 
@@ -378,3 +408,21 @@ public class MigrationGenerator {
         op
     }
 }
+
+/**
+ * 内部统一的索引规格：把字段级(@Index)与实体级(@TableIndex)索引归一为同构描述，便于 diff 与生成。
+ */
+public class IndexSpec {
+    /// 所属表名
+    public var table: String = ""
+    /// 索引名
+    public var indexName: String = ""
+    /// 列名列表
+    public var columnNames: ArrayList<String> = ArrayList()
+    /// 是否唯一
+    public var unique: Bool = false
+    /// 部分索引过滤条件（空串表示全表索引）
+    public var filter: String = ""
+
+    public init() {}
+}

src/migrations/migrations.cj

@@ -107,6 +107,8 @@ public class MigrationOperation {
     public var indexName: String = ""
     public var columnNames: ArrayList<String> = ArrayList()
     public var unique: Bool = false
+    /// 部分索引过滤条件（CREATE ... WHERE filter；空串表示全表索引）
+    public var filter: String = ""
     public var sql: String = ""
 
     public init(kind: MigrationOperationKind) {
@@ -202,11 +204,18 @@ public class MigrationBuilder {
 
     public func createIndex(indexName: String, table: String, columns: ArrayList<String>,
         unique: Bool): MigrationBuilder {
+        createIndex(indexName, table, columns, unique, "")
+    }
+
+    /// 创建索引（可指定部分索引过滤条件；filter 非空时生成 CREATE ... WHERE filter）
+    public func createIndex(indexName: String, table: String, columns: ArrayList<String>,
+        unique: Bool, filter: String): MigrationBuilder {
         let op = MigrationOperation(MigrationOperationKind.CreateIndex)
         op.indexName = indexName
         op.tableName = table
         op.columnNames = columns
         op.unique = unique
+        op.filter = filter
         operations.add(op)
         this
     }
@@ -228,7 +237,7 @@ public class MigrationBuilder {
 }
 
 /**
- * 迁移基类：migrationId 形如 "20250701000000_InitialCreate"（时间戳_名称），按字典序应用。
+ * 迁移基类：migrationId 按字典序应用（CLI 生成 "yyyyMMddHHmmss" 时间戳）。
  * 两种使用方式：
  * 1. 子类 override up/down 手写声明式操作（MigrationBuilder）；
  * 2. 由 MigrationGenerator 从模型生成时注入 preset 操作，基类 up/down 自动重放。
@@ -266,12 +275,12 @@ public open class Migration {
 }
 
 /**
- * DDL SQL 工厂：MigrationOperation → SQL（类型映射与差异语法委托给 ISqlDialect）。
+ * DDL SQL 工厂：MigrationOperation → SQL（类型映射与差异语法委托给 SqlDialect）。
  */
 public class DdlFactory {
     public init() {}
 
-    public func toSql(op: MigrationOperation, dialect: ISqlDialect): String {
+    public func toSql(op: MigrationOperation, dialect: SqlDialect): String {
         match (op.kind) {
             case MigrationOperationKind.CreateTable => createTableSql(op, dialect)
             case MigrationOperationKind.DropTable => "DROP TABLE IF EXISTS ${dialect.quoteName(op.tableName)}"
@@ -294,7 +303,7 @@ public class DdlFactory {
     ///   - 有同名列且类型一致 → AddColumn 幂等跳过（空列表）；AlterColumn 保留原 SQL（处理非空/长度等变化）
     ///   - 有同名列但类型不同 → 先 DROP COLUMN 再 ADD COLUMN（重建该字段）
     /// existingType 来自 information_schema.data_type；None 表示列不存在。
-    public func resolveColumnSqls(op: MigrationOperation, dialect: ISqlDialect,
+    public func resolveColumnSqls(op: MigrationOperation, dialect: SqlDialect,
         existingType: ?String): ArrayList<String> {
         let result = ArrayList<String>()
         let col = op.column.getOrThrow()
@@ -360,7 +369,7 @@ public class DdlFactory {
         sb.toString()
     }
 
-    private func createTableSql(op: MigrationOperation, dialect: ISqlDialect): String {
+    private func createTableSql(op: MigrationOperation, dialect: SqlDialect): String {
         let sb = StringBuilder()
         sb.append("CREATE TABLE IF NOT EXISTS ${dialect.quoteName(op.tableName)} (\n")
         var first = true
@@ -375,7 +384,7 @@ public class DdlFactory {
         sb.toString()
     }
 
-    private func createIndexSql(op: MigrationOperation, dialect: ISqlDialect): String {
+    private func createIndexSql(op: MigrationOperation, dialect: SqlDialect): String {
         let sb = StringBuilder()
         sb.append("CREATE ")
         if (op.unique) {
@@ -391,10 +400,13 @@ public class DdlFactory {
             first = false
         }
         sb.append(")")
+        if (op.filter != "") {
+            sb.append(" WHERE ${op.filter}")
+        }
         sb.toString()
     }
 
-    private func columnDefSql(col: ColumnDefinition, dialect: ISqlDialect): String {
+    private func columnDefSql(col: ColumnDefinition, dialect: SqlDialect): String {
         let sb = StringBuilder()
         sb.append(dialect.quoteName(col.name))
         sb.append(" ${dialect.columnTypeSql(col.columnType, col.autoIncrement, col.maxLength)}")

src/migrations/migrator.cj

@@ -3,7 +3,7 @@
  * 迁移执行器：历史表 + 按 migrationId 排序应用未执行的迁移（事务内）。
  *
  * 历史表 simcu_orm_migrations (id VARCHAR(64) PK, name VARCHAR(256), applied_at TIMESTAMP)，
- * 应用顺序 = migrationId 字典序（建议用 "yyyyMMddHHmmss_名称" 命名）。
+ * 应用顺序 = migrationId 字典序（CLI 生成的 migrationId 为 "yyyyMMddHHmmss" 时间戳）。
  */
 
 package simcu::orm.migrations
@@ -18,10 +18,10 @@ import simcu::orm.sql.*
  */
 public class Migrator {
     private let _datasource: Datasource
-    private let _dialect: ISqlDialect
+    private let _dialect: SqlDialect
     private let _historyTable = "simcu_orm_migrations"
 
-    public init(datasource: Datasource, dialect: ISqlDialect) {
+    public init(datasource: Datasource, dialect: SqlDialect) {
         this._datasource = datasource
         this._dialect = dialect
     }

src/migrations/model_snapshot.cj

@@ -10,11 +10,12 @@
  *   // 模型变更后：快照存在 → 载入旧模型 diff，并覆盖保存新快照
  *   gen.ensure("20250801000000_AddAge", "新增 age 列", "snapshot.json", models1)
  *
- * 快照 JSON 结构（版本 3，较 v2 新增索引标记 idx/ixName/ixUnique）：
- *   {"version":3,"models":[{"table":"users","columns":[
+ * 快照 JSON 结构（版本 4，较 v3 新增实体级 indexes 数组；v3 的 idx/ixName/ixUnique 为字段级索引标记）：
+ *   {"version":4,"models":[{"table":"users","columns":[
  *     {"name":"id","column":"id","type":"Int64","key":true,"auto":true,
  *      "client":false,"required":false,"maxLen":0,"enum":false,
- *      "idx":false,"ixName":"","ixUnique":false}]}]}
+ *      "idx":false,"ixName":"","ixUnique":false}],
+ *     "indexes":[{"name":"ux","columns":["a","b"],"unique":true,"filter":"kind = 'Passport'"}]}]}
  */
 
 package simcu::orm.migrations
@@ -31,7 +32,7 @@ public class ModelSnapshot {
     /// 快照内的轻量模型列表
     public var models: ArrayList<EntityModel> = ArrayList()
     /// 快照格式版本
-    public static let formatVersion: Int64 = 3
+    public static let formatVersion: Int64 = 4
 
     public init() {}
 
@@ -64,6 +65,16 @@ public class ModelSnapshot {
                     }
                 }
             }
+            for (e in m.indexes) {
+                let li = EntityIndex()
+                li.indexName = e.indexName
+                li.unique = e.unique
+                li.filter = e.filter
+                for (c in e.columnNames) {
+                    li.columnNames.add(c)
+                }
+                lm.indexes.add(li)
+            }
             snap.models.add(lm)
         }
         snap
@@ -100,6 +111,20 @@ public class ModelSnapshot {
                 cols.add(JObject(co))
             }
             mo["columns"] = JArray(cols)
+            let idxs = ArrayList<JsonValue>()
+            for (e in m.indexes) {
+                let io = HashMap<String, JsonValue>()
+                io["name"] = JString(e.indexName)
+                let icols = ArrayList<JsonValue>()
+                for (c in e.columnNames) {
+                    icols.add(JString(c))
+                }
+                io["columns"] = JArray(icols)
+                io["unique"] = JBool(e.unique)
+                io["filter"] = JString(e.filter)
+                idxs.add(JObject(io))
+            }
+            mo["indexes"] = JArray(idxs)
             modelsArr.add(JObject(mo))
         }
         root["models"] = JArray(modelsArr)
@@ -146,6 +171,26 @@ public class ModelSnapshot {
                                             }
                                         case _ => throw Exception("simcu::orm: 快照 models[].columns 必须是数组")
                                     }
+                                    // 实体级索引（v4 开始存在；缺失时容忍为空，兼容旧快照）
+                                    match (mo.get("indexes")) {
+                                        case Some(JArray(idxs)) =>
+                                            for (i in idxs) {
+                                                match (i) {
+                                                    case JObject(io) =>
+                                                        let li = EntityIndex()
+                                                        li.indexName = getString(io, "name")
+                                                        li.unique = getBool(io, "unique")
+                                                        li.filter = getString(io, "filter")
+                                                        for (c in getStringArray(io, "columns")) {
+                                                            li.columnNames.add(c)
+                                                        }
+                                                        lm.indexes.add(li)
+                                                    case _ => throw Exception(
+                                                        "simcu::orm: 快照 indexes[] 项必须是 object")
+                                                }
+                                            }
+                                        case _ => ()
+                                    }
                                     snap.models.add(lm)
                                 case _ => throw Exception("simcu::orm: 快照 models[] 项必须是 object")
                             }
@@ -201,4 +246,20 @@ public class ModelSnapshot {
             case _ => 0
         }
     }
+
+    /// 读取字符串数组（如索引列名列表）；缺失或类型不符时返回空列表
+    private static func getStringArray(o: HashMap<String, JsonValue>, k: String): ArrayList<String> {
+        let list = ArrayList<String>()
+        match (o.get(k)) {
+            case Some(JArray(arr)) =>
+                for (e in arr) {
+                    match (e) {
+                        case JString(s) => list.add(s)
+                        case _ => ()
+                    }
+                }
+            case _ => ()
+        }
+        list
+    }
 }

src/model/entity_model.cj

@@ -103,6 +103,22 @@ public class PropertyModel {
     }
 }
 
+/**
+ * 类级声明的实体索引（复合/条件索引，来自 @TableIndex 注解或快照反序列化）。
+ */
+public class EntityIndex {
+    /// 索引名（空则按 ix_<表名>_<首列名> 自动生成）
+    public var indexName: String = ""
+    /// 列名列表（已映射为数据库列名）
+    public var columnNames: ArrayList<String> = ArrayList()
+    /// 是否唯一索引
+    public var unique: Bool = false
+    /// 部分索引过滤条件（空串表示全表索引）
+    public var filter: String = ""
+
+    public init() {}
+}
+
 /**
  * 实体模型：一个实体类 ↔ 一张表。
  */
@@ -115,6 +131,8 @@ public class EntityModel {
     public var properties: ArrayList<PropertyModel> = ArrayList()
     /// 主键映射
     public var keyProperty: ?PropertyModel = None
+    /// 类级声明的实体索引（复合/条件索引）
+    public var indexes: ArrayList<EntityIndex> = ArrayList()
 
     /// 轻量构造：快照反序列化 / 人工组装时使用，createInstance 不可用
     public init() {}
@@ -266,6 +284,21 @@ public class ModelCache {
             }
             model.properties.add(propM)
         }
+        // 类级复合/条件索引（@TableIndex）：列名映射为数据库列名
+        if (let Some(ti) <- ct.findAnnotation<TableIndex>()) {
+            let idx = EntityIndex()
+            if (ti.name != "") {
+                idx.indexName = ti.name
+            } else {
+                // 首个列名决定默认索引名
+                let firstCol = mapFirstColumn(ti.columns)
+                idx.indexName = "ix_${model.tableName}_${firstCol}"
+            }
+            idx.columnNames = splitColumns(ti.columns, model)
+            idx.unique = ti.unique
+            idx.filter = ti.filter
+            model.indexes.add(idx)
+        }
         // 主键校验（v1 仅支持单主键）
         var keys = ArrayList<PropertyModel>()
         for (p in model.properties) {
@@ -299,6 +332,60 @@ public class ModelCache {
         }
     }
 
+    /// 把逗号分隔的列名/字段名字符串拆成数据库列名列表（"source_server,name"、"_sourceServer, _name"）。
+    /// 每一项先经 mapColumn 映射：字段名或列名都转到数据库列名。
+    private static func splitColumns(columns: String, model: EntityModel): ArrayList<String> {
+        var list = ArrayList<String>()
+        var sb = StringBuilder()
+        for (c in columns.runes()) {
+            if (c == Rune(0x2C)) {
+                // 逗号：收尾当前列
+                let col = model.mapColumn(trimWhitespace(sb.toString()))
+                if (col != "") {
+                    list.add(col)
+                }
+                sb = StringBuilder()
+            } else {
+                sb.append(c)
+            }
+        }
+        let col = model.mapColumn(trimWhitespace(sb.toString()))
+        if (col != "") {
+            list.add(col)
+        }
+        list
+    }
+
+    /// 取逗号分隔列串中的首个列（用于默认索引名）。
+    private static func mapFirstColumn(columns: String): String {
+        var sb = StringBuilder()
+        for (c in columns.runes()) {
+            if (c == Rune(0x2C)) {
+                break
+            }
+            sb.append(c)
+        }
+        trimWhitespace(sb.toString())
+    }
+
+    /// 去除字符串首尾空白（仅空格/tab/换行，避免依赖 std.String.trim）
+    private static func trimWhitespace(s: String): String {
+        var start: Int64 = 0
+        var end = s.size
+        while (start < end && isWsAt(s, start)) {
+            start += 1
+        }
+        while (end > start && isWsAt(s, end - 1)) {
+            end -= 1
+        }
+        s[start..end]
+    }
+
+    private static func isWsAt(s: String, i: Int64): Bool {
+        let c = s[i]
+        c == 0x20 || c == 0x09 || c == 0x0A || c == 0x0D
+    }
+
     /// 应用列命名策略
     public static func applyNamingPolicy(fieldName: String, policy: ColumnNamingPolicy): String {
         match (policy) {

src/query/query_builder.cj

@@ -48,7 +48,7 @@ public class PagedResult<T> {
  */
 public class QueryBuilder<T> {
     private let _model: EntityModel
-    private let _dialect: ISqlDialect
+    private let _dialect: SqlDialect
     private let _executor: (String, ArrayList<Any>) -> ArrayList<T>
     private let _counter: (String, ArrayList<Any>) -> Int64
 
@@ -58,7 +58,7 @@ public class QueryBuilder<T> {
     private var _skip: Int64 = 0
     private var _take: Int64 = 0
 
-    public init(model: EntityModel, dialect: ISqlDialect, executor: (String, ArrayList<Any>) -> ArrayList<T>,
+    public init(model: EntityModel, dialect: SqlDialect, executor: (String, ArrayList<Any>) -> ArrayList<T>,
         counter: (String, ArrayList<Any>) -> Int64) {
         this._model = model
         this._dialect = dialect

src/sql/column_types.cj

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
- * 列类型：与具体数据库无关的抽象，DDL 映射由 ISqlDialect 决定。
+ * 列类型：与具体数据库无关的抽象，DDL 映射由 SqlDialect 决定。
  */
 
 package simcu::orm.sql

src/sql/postgre_sql_dialect.cj

@@ -13,7 +13,7 @@ import std.collection.*
 /**
  * PostgreSQL 方言。
  */
-public open class PostgreSqlDialect <: ISqlDialect {
+public open class PostgreSqlDialect <: SqlDialect {
     public init() {}
 
     public func quoteName(name: String): String {

src/sql/sql_dialect.cj

@@ -1,9 +1,9 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
- * SQL 方言接口（I 前缀命名，对齐 EF Core 接口风格）：标识符引用、增删改查 SQL 生成、DDL 类型/语句生成。
+ * SQL 方言接口：标识符引用、增删改查 SQL 生成、DDL 类型/语句生成。
  *
- * 新数据库接入：实现 ISqlDialect 即可（参考 PostgreSqlDialect / OpenGaussDialect）。
- * 内置实现见 PostgreSqlDialect.cj（PostgreSQL）、OpenGaussDialect.cj（openGauss，继承 PG）。
+ * 新数据库接入：实现 SqlDialect 即可（参考 PostgreSqlDialect / OpenGaussDialect）。
+ * 内置实现见 postgre_sql_dialect.cj（PostgreSQL）、open_gauss_dialect.cj（openGauss，继承 PG）。
  */
 
 package simcu::orm.sql
@@ -13,7 +13,7 @@ import std.collection.*
 /**
  * SQL 方言接口。
  */
-public interface ISqlDialect {
+public interface SqlDialect {
     /// 引用标识符（表名/列名）
     func quoteName(name: String): String
 
@@ -51,6 +51,3 @@ public interface ISqlDialect {
     /// 探测数据库是否存在的 SELECT（返回带 ? 占位符的语句，库名作为参数值传入避免拼接注入）
     func databaseExistsSql(): String
 }
-
-/// 兼容别名：旧名称 SqlDialect 仍可用（新代码请使用 ISqlDialect）
-public type SqlDialect = ISqlDialect

src/tests/db_context_macro_test.cj

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2025 SimcuTeam. All rights reserved.
+ * @DbContext 宏回归测试：只处理「let 前缀」的 DbSet<T> 字段，var/prop 一律不改动。
+ *
+ * 通过注册一个 FakeDriver，让宏生成的 `init(driverName, connStr)` 走通
+ * `super(...) -> DatasourceFactory.create(connStr, driverName)` 这条真实路径，
+ * 从而验证：let 字段被改写为 `public prop { get() { this.set<T>() } }`（public 可被
+ * std.reflect 枚举），getModels() 能反射采集到模型；手写 prop DbSet 保持原样不被改写。
+ */
+
+package simcu::orm.tests
+
+import std.collection.*
+import std.database.sql.*
+import std.time.*
+import std.unittest.*
+import std.unittest.testmacro.*
+import simcu::orm.*
+import simcu::orm.macros.*
+
+// ---------- 复用 sim_orm_test.cj 的实体 ----------
+// User / Order 已在同包定义，这里直接引用。
+
+// ---------- 假驱动 ----------
+class FakeDriver <: Driver {
+    public prop name: String {
+        get() { "fake" }
+    }
+    public prop version: String {
+        get() { "0.0.1" }
+    }
+    public prop preferredPooling: Bool {
+        get() { false }
+    }
+    public func open(_: String, _: Array<(String, String)>): Datasource {
+        FakeDatasource()
+    }
+    public func getDriverStartTime(): DateTime {
+        DateTime.now()
+    }
+}
+
+let _ = {
+    =>
+    DriverManager.register("fake", FakeDriver())
+}()
+
+// ---------- 宏应用：仅含 let 字段 ----------
+@DbContext
+class MacroCtx {
+    let users: DbSet<User>
+    let orders: DbSet<Order>
+}
+
+// ---------- 宏应用：let 与手写 prop 混用 ----------
+// let 字段被宏改写为 public prop；手写 prop（含 getter）保持原样、不改写。
+@DbContext
+class MixedCtx {
+    let users: DbSet<User>
+    prop todos: DbSet<Order> {
+        get() { this.set<Order>() }
+    }
+}
+
+@Test
+public class DbContextMacroTests {
+    @TestCase
+    public func testMacroGeneratesInitAndDbSets(): Unit {
+        let ctx = MacroCtx("fake", "postgres://localhost/db")
+        // 宏生成的 init 已把 let 字段初始化为 set<T>()，可直接使用
+        let users = ctx.users
+        let orders = ctx.orders
+        @Expect(users is DbSet<User>, true)
+        @Expect(orders is DbSet<Order>, true)
+        // DbSet 连通到 context 的变更队列
+        users.add(User())
+        @Expect(ctx.pendingCount(), 1)
+        orders.add(Order())
+        @Expect(ctx.pendingCount(), 2)
+        // 默认方言为 openGauss（继承 PG）
+        @Expect(ctx.getDialect().quoteName("users"), "\"users\"")
+    }
+
+    @TestCase
+    public func testMacroModelsCollectedFromLetFields(): Unit {
+        let ctx = MacroCtx("fake", "postgres://localhost/db")
+        // 宏把 let DbSet 字段统一提升为 public，getModels() 反射可采集到模型
+        let models = ctx.getModels()
+        @Expect(models.size, 2)
+        // 模型采集自 let 字段（users -> User, orders -> Order）
+        var gotUser = false
+        var gotOrder = false
+        for (m in models) {
+            if (m.tableName == "users") {
+                gotUser = true
+            }
+            if (m.tableName == "orders") {
+                gotOrder = true
+            }
+        }
+        @Expect(gotUser, true)
+        @Expect(gotOrder, true)
+    }
+
+    @TestCase
+    public func testPropDbSetIsNotRewritten(): Unit {
+        let ctx = MixedCtx("fake", "postgres://localhost/db")
+        // let 字段被改写为 public prop，反射可采集 -> 1 个模型（users）
+        let models = ctx.getModels()
+        @Expect(models.size, 1)
+        // 手写 prop（internal，含 getter）保持原样：可正常使用，
+        // 但不会被宏改写成 public prop，因而不会重复进入模型采集
+        let todos = ctx.todos
+        @Expect(todos is DbSet<Order>, true)
+        todos.add(Order())
+        @Expect(ctx.pendingCount(), 1)
+    }
+}

src/tests/migration_cli_test.cj

@@ -17,7 +17,7 @@ import simcu::orm.cli.*
 /// 手写迁移（验证源码生成覆盖索引与 rawSql 转义）
 class HandWrittenMigration <: Migration {
     public init() {
-        super("20250801000000_HandWritten", "手写迁移")
+        super("20250801000000", "手写迁移")
     }
     public override func up(builder: MigrationBuilder): Unit {
         builder.createTable("tags") { tb =>
@@ -34,6 +34,22 @@ class HandWrittenMigration <: Migration {
     }
 }
 
+/// 手写迁移（验证部分索引 filter 还原：createIndex 5 参带 filter）
+class FilteredIndexMigration <: Migration {
+    public init() {
+        super("20250802000000", "部分唯一索引")
+    }
+    public override func up(builder: MigrationBuilder): Unit {
+        let cols = ArrayList<String>()
+        cols.add("source_server")
+        cols.add("name")
+        builder.createIndex("ux_assets_passport_name", "assets", cols, true, "kind = 'Passport'")
+    }
+    public override func down(builder: MigrationBuilder): Unit {
+        builder.dropIndex("ux_assets_passport_name", "assets")
+    }
+}
+
 @Test
 class MigrationFileGeneratorTests {
     private func buildUserModel(): EntityModel {
@@ -75,9 +91,9 @@ class MigrationFileGeneratorTests {
 
     @TestCase
     public func testClassNameAndFileName(): Unit {
-        @Expect(MigrationFileGenerator.classNameOf("20250701000000_InitialCreate") == "InitialCreate")
-        @Expect(MigrationFileGenerator.fileNameOf("20250701000000_InitialCreate") == "20250701000000_InitialCreate.cj")
-        @Expect(MigrationFileGenerator.classNameOf("NoTimestamp") == "NoTimestamp")
+        // 时间戳 id → 类名 MigrationId<时间戳>,文件名 = id
+        @Expect(MigrationFileGenerator.classNameOf("20250701000000") == "MigrationId20250701000000")
+        @Expect(MigrationFileGenerator.fileNameOf("20250701000000") == "20250701000000.cj")
     }
 
     @TestCase
@@ -85,11 +101,12 @@ class MigrationFileGeneratorTests {
         let models = ArrayList<EntityModel>()
         models.add(buildUserModel())
         let gen = MigrationGenerator()
-        let m = gen.initial("20250701000000_InitialCreate", "初始建表", models)
+        let m = gen.initial("20250701000000", "初始建表", models)
         let src = MigrationFileGenerator.migrationSource("app", MigrationFileGenerator.classNameOf(m.migrationId), m)
+        @Expect(src.contains("// 描述: 初始建表"))
         @Expect(src.contains("package app"))
-        @Expect(src.contains("public class InitialCreate <: Migration"))
-        @Expect(src.contains("super(\"20250701000000_InitialCreate\", \"初始建表\")"))
+        @Expect(src.contains("public class MigrationId20250701000000 <: Migration"))
+        @Expect(src.contains("super(\"20250701000000\", \"初始建表\")"))
         @Expect(src.contains("builder.createTable(\"users\") { tb =>"))
         @Expect(src.contains("tb.column(\"id\", ColumnTypes.BigIntCol).primary().autoInc().notNull()"))
         @Expect(src.contains("tb.column(\"name\", ColumnTypes.TextCol).notNull().withMaxLength(100)"))
@@ -104,7 +121,7 @@ class MigrationFileGeneratorTests {
         newModels.add(buildUserModel())
         newModels.add(buildOrderModel())
         let gen = MigrationGenerator()
-        let m = gen.diff("20250801000000_AddOrders", "新增 orders 表", oldModels, newModels)
+        let m = gen.diff("20250801000000", "新增 orders 表", oldModels, newModels)
         let src = MigrationFileGenerator.migrationSource("app", MigrationFileGenerator.classNameOf(m.migrationId), m)
         @Expect(src.contains("builder.createTable(\"orders\") { tb =>"))
         @Expect(src.contains("tb.column(\"oid\", ColumnTypes.TextCol).primary().notNull()"))
@@ -123,6 +140,16 @@ class MigrationFileGeneratorTests {
         @Expect(src.contains("builder.dropTable(\"tags\")"))
     }
 
+    @TestCase
+    public func testFilteredIndexMigrationSource(): Unit {
+        let m = FilteredIndexMigration()
+        let src = MigrationFileGenerator.migrationSource("app", MigrationFileGenerator.classNameOf(m.migrationId), m)
+        // 生成的迁移源码应还原带 filter 的 5 参 createIndex（含 WHERE 条件）
+        @Expect(src.contains(
+            "builder.createIndex(\"ux_assets_passport_name\", \"assets\", ArrayList<String>([\"source_server\", \"name\"]), true, \"kind = 'Passport'\")"))
+        @Expect(src.contains("builder.dropIndex(\"ux_assets_passport_name\", \"assets\")"))
+    }
+
     @TestCase
     public func testRegistryRoundTrip(): Unit {
         let entries = ArrayList<String>()
@@ -153,22 +180,24 @@ class MigrationFileGeneratorTests {
             let models = ArrayList<EntityModel>()
             models.add(buildUserModel())
             let gen = MigrationGenerator()
-            let m = gen.initial("20250701000000_InitialCreate", "初始建表", models)
+            let m = gen.initial("20250701000000", "初始建表", models)
             let fg = MigrationFileGenerator()
             let path = fg.writeMigration("testpkg", m, dir)
             @Expect(exists(Path(path)))
+            @Expect(path.endsWith("20250701000000.cj"))
             let text = String.fromUtf8(File.readFrom(Path(path)))
             @Expect(text.contains("package testpkg"))
-            @Expect(text.contains("public class InitialCreate <: Migration"))
+            @Expect(text.contains("public class MigrationId20250701000000 <: Migration"))
 
             // 注册文件：首次创建 + 追加 + 幂等
-            let registryPath = "${dir}/MigrationRegistry.cj"
-            fg.updateRegistry("testpkg", registryPath, "InitialCreate")
-            fg.updateRegistry("testpkg", registryPath, "AddAge")
-            fg.updateRegistry("testpkg", registryPath, "AddAge")
+            let registryPath = "${dir}/migration_registry.cj"
+            let cls = MigrationFileGenerator.classNameOf(m.migrationId)
+            fg.updateRegistry("testpkg", registryPath, cls)
+            fg.updateRegistry("testpkg", registryPath, cls)
             let reg = String.fromUtf8(File.readFrom(Path(registryPath)))
             @Expect(reg.contains("package testpkg"))
-            @Expect(MigrationFileGenerator.extractRegistryEntries(reg).size == 2)
+            @Expect(reg.contains("registerMigration(MigrationId20250701000000())"))
+            @Expect(MigrationFileGenerator.extractRegistryEntries(reg).size == 1)
         } finally {
             if (exists(Path(dir))) {
                 remove(Path(dir), recursive: true)
@@ -196,12 +225,13 @@ class MigrationCliDispatchTests {
     }
 
     @TestCase
-    public func testAddMissingNameReturnsOne(): Unit {
+    public func testAddWithoutDescriptionIsOk(): Unit {
+        // add 无参数 = 描述可空;模型为空 → 无变化 → 跳过生成,返回 0
         let args = ArrayList<String>()
         args.add("add")
         let rc = MigrationCli.run(args, { => ArrayList<EntityModel>() },
             { => throw Exception("不应调用 datasource") }, { => ArrayList<Migration>() })
-        @Expect(rc == 1)
+        @Expect(rc == 0)
     }
 
     @TestCase
@@ -226,7 +256,7 @@ class MigrationCliDispatchTests {
     public func testDowngradeWithTargetConsumesArgs(): Unit {
         let args = ArrayList<String>()
         args.add("downgrade")
-        args.add("20260819061048_InitialCreate")
+        args.add("20260819061048")
         let rc = MigrationCli.run(args, { => ArrayList<EntityModel>() },
             { => throw Exception("不应调用 datasource") }, { => ArrayList<Migration>() })
         @Expect(rc == 1)

src/tests/sim_orm_test.cj

@@ -301,7 +301,7 @@ class ChangeTrackerTests {
 // ---------- OpenGaussDialect SQL 生成 ----------
 
 @Test
-class ISqlDialectTests {
+class SqlDialectTests {
     @TestCase
     public func testQuoteInsertUpdateDelete(): Unit {
         let d = OpenGaussDialect()
@@ -709,7 +709,7 @@ class MigrationGeneratorTests {
         MigrationGenerator()
     }
 
-    private func upSql(m: Migration, dialect: ISqlDialect): ArrayList<String> {
+    private func upSql(m: Migration, dialect: SqlDialect): ArrayList<String> {
         let builder = MigrationBuilder()
         m.up(builder)
         let f = DdlFactory()
@@ -720,7 +720,7 @@ class MigrationGeneratorTests {
         sqls
     }
 
-    private func downSql(m: Migration, dialect: ISqlDialect): ArrayList<String> {
+    private func downSql(m: Migration, dialect: SqlDialect): ArrayList<String> {
         let builder = MigrationBuilder()
         m.down(builder)
         let f = DdlFactory()
@@ -987,7 +987,7 @@ class AppDbContext <: DbContext {
         orders = set<Order>()
     }
 
-    init(ds: Datasource, dialect: ISqlDialect) {
+    init(ds: Datasource, dialect: SqlDialect) {
         super(ds, dialect)
         users = set<User>()
         orders = set<Order>()
@@ -1044,7 +1044,7 @@ class ModelSnapshotTests {
         ms
     }
 
-    private func upSql(m: Migration, dialect: ISqlDialect): ArrayList<String> {
+    private func upSql(m: Migration, dialect: SqlDialect): ArrayList<String> {
         let builder = MigrationBuilder()
         m.up(builder)
         let f = DdlFactory()