[feat] 拓展 database-ptc-object 增加快捷操作工具

[FxRayHughes]

改动说明

为 database-ptc-object 模块进行全面扩展，新增类型安全的 DataMapper 层、关联表查询、分页、游标、IndexedEnum 等功能。

---

一、DataMapper 接口与类型安全 CRUD（核心新增）

引入 DataMapper<T> 接口及 DataMapperImpl 实现，提供类型安全的数据操作层：

• 基础 CRUD：find、findOne、findAll、insert、update、delete、has、count
• 基于 @key 的复合定位：findByKey、findOneByKey、hasByKey、updateByKey
• 批量操作：findByIds、deleteByIds、updateBatch、insertBatch
• 排序查询：sort、sortDescending
• 条件操作：deleteWhere（按 Filter 条件删除）
• 自增主键返回：insertAndGenerateKey、insertBatchAndGenerateKeys
• 通过自增行 ID 操作：findByRowId、deleteByRowId

二、MapperDelegate（mapper 委托）

新增 mapper() 委托函数，简化 DataMapper 的获取方式：

val playerMapper by container.mapper<PlayerData>(cache = true)

三、事务支持（TransactionalDataMapper）

新增 TransactionalDataMapper，在 transaction {} 块中提供完整的 DataMapper 操作，事务内所有操作共享同一数据库连接，不使用缓存。

四、QueryCache 缓存系统

新增两级缓存机制：

• Bean Cache：按 @id 值缓存单个对象
• Query Cache：按查询条件缓存查询结果列表
• 精确的缓存失效策略：写操作自动清除相关缓存

五、@linktable 关联表查询

新增 @LinkTable 注解，支持数据类之间的关联关系：

• 查询时自动生成 LEFT JOIN，递归展开多层嵌套关联（A→B→C→...）
• 写入时自动级联保存关联对象（深度优先）
• 自动检测循环引用并跳过
• 支持子查询连接（innerJoin、leftJoin、rightJoin 带参数版本）
• 新增 SubQuery 类和 subQuery DSL 构建子查询

六、分页查询（Page）

新增 Page<T> 数据类，封装分页结果：

val page = mapper.findPage(page = 1, size = 10) { "level" gte 5 }
// page.content, page.total, page.totalPages, page.hasNext, page.hasPrevious

• findPage、sortPage、sortDescendingPage
• 支持 Filter 条件过滤、L2 缓存、@LinkTable JOIN 查询

七、游标查询（Cursor）

新增 Cursor<T> 类，实现 Iterable<T> + Closeable，流式逐行遍历大数据集：

container.transaction {
    mapper.selectCursor().forEach { item -> /* 逐行处理 */ }
}

• selectCursor、sortCursor、sortDescendingCursor
• 必须在 transaction {} 块中使用，支持提前终止和自动关闭

八、IndexedEnum 接口

新增 IndexedEnum 接口，枚举以数值 index 存储到数据库：

enum class AccountType(override val index: Long) : IndexedEnum {
    NORMAL(0), VIP(1), ADMIN(2)
}

• 自动识别列类型（SQL: BIGINT，SQLite: INTEGER）
• Filter DSL 中 WHERE 条件自动转换参数（convertParam）

九、注解增强

• @ColumnType（新增）：显式指定字段的 SQL / SQLite 列类型
• 所有注解补充完整 KDoc 文档和 @Target 约束
• 补充 SQLite 与 SQL 行为差异说明

十、ActionSelect 扩展

• 新增带参数的 innerJoin、leftJoin、rightJoin 方法，支持子查询作为 JOIN 条件

---

修改文件清单

文件	操作	说明
Annotations.kt	修改	新增 @ColumnType、@linktable，补充 KDoc 和 @target
ContainerOperator.kt	修改	新增分页、游标、批量操作等抽象方法
ContainerOperatorImpl.kt	修改	实现所有新增方法，含 LinkTable JOIN、convertParam
ContainerSQL.kt	修改	IndexedEnum 列类型映射、@ColumnType 支持
ContainerSQLite.kt	修改	IndexedEnum 列类型映射、@ColumnType 支持
Container.kt	修改	事务上下文支持
AnalyzedClass.kt	修改	IndexedEnum 序列化/反序列化、LinkTable 递归解析
AnalyzedClassMember.kt	修改	新增 isIndexedEnum 属性
JoinQuery.kt	修改	子查询连接、selectAs、IndexedEnum 值转换
PersistentContainer.kt	修改	事务 API 扩展
DataMapper.kt	新增	DataMapper 接口定义
DataMapperImpl.kt	新增	DataMapper 实现（带缓存）
TransactionalDataMapper.kt	新增	事务内 DataMapper 实现
TransactionContext.kt	新增	事务上下文类
MapperDelegate.kt	新增	mapper() 委托函数
QueryCache.kt	新增	两级缓存系统
Page.kt	新增	分页结果数据类
Cursor.kt	新增	游标查询类
IndexedEnum.kt	新增	枚举数值存储接口
LinkTableTest.kt	新增	LinkTable 关联查询单元测试
TestHelper.kt	修改	测试辅助工具扩展
ActionSelect.kt	修改	带参数的 JOIN 方法
Join.kt	修改	params 参数支持

Closes #656