wok-server 0.7.1 → 0.8.0

package/documentation/en/mysql.md

@@ -154,13 +154,29 @@ The type mapping logic cannot be modified. Here is the mapping table:
 
 | JavaScript Type   | MySQL Field Type                                                          |
 | :---------------- | :------------------------------------------------------------------------ |
-| Boolean           | TINYINT                                                                   |
 | Number            | TINYINT, SMALLINT, INT, MEDIUMINT, YEAR, FLOAT, DOUBLE, BIGINT           |
 | Date              | TIMESTAMP, DATE, DATETIME                                                 |
 | Buffer            | TINYBLOB, MEDIUMBLOB, LONGBLOB, BLOB, BINARY, VARBINARY, BIT             |
 | String            | CHAR, VARCHAR, TINYTEXT, MEDIUMTEXT, LONGTEXT, TEXT, ENUM, SET, DECIMAL, TIME |
 | Object or Array   | JSON                                                                      |
 
+> **⚠️ Safety note about `boolean` type**
+>
+> MySQL's `BOOLEAN` is actually `TINYINT(1)`. The driver returns `0` or `1` (number type), **not** `true`/`false`. If you declare the field as `boolean` in your entity, comparing query results with `true`/`false` using `===` will produce bugs.
+>
+> The framework does **not** support automatic type mapping and never will. Even if it did, hand-written `query()` custom SQL would still return `0`/`1`, creating a persistent type mismatch between the application layer and the database — a risk that no framework can fully eliminate.
+>
+> **The safest approach** is to declare such fields as `0 | 1`, using the database's native return type directly:
+>
+> ```ts
+> export interface User {
+>   // Recommended: use 0 | 1, matching the database return value
+>   is_active: 0 | 1
+> }
+> ```
+>
+> `0 | 1` behaves almost identically to `boolean` in conditionals — `if (user.is_active)` and `user.is_active ? '是' : '否'` both work as expected. The only thing to avoid is `=== true` comparison. This way, the returned values are consistent across both CRUD methods and custom SQL — a one-time fix.
+
 For nullable fields, define them as nullable in TypeScript:
 
 ```ts
@@ -227,13 +243,6 @@ await manager.insert(tableUser, {
   nickname: '小明',
   balance: 1
 })
-// Insert with expressions
-await manager.insert(tableUser, {
-  id: 'in002',
-  nickname: '小红',
-  balance: ['expr', '?? * ?', ['score', 2]],
-  createAt: ['now']
-})
 // Batch insert
 await manager.insertMany(tableUser, [
   { id: 'im001', nickname: '张飞', balance: 0 },
@@ -342,26 +351,6 @@ await manager.modify(`update user set nickname='无名' where nickname='佚名'`
 | query           | Custom SQL query, returns record list, supports prepared statements         |
 | modify          | Execute custom SQL, returns affected rows, supports prepared statements     |
 
-### Insert Expressions
-
-Starting from version 0.7.0, `insert`, `insertMany`, `upsert` and other insert methods accept `InsertValue` type,
-allowing expressions in the VALUES clause:
-
-```ts
-await manager.insert(tableUser, {
-  id: 'in001',
-  nickname: '小明',
-  // Set to NOW()
-  createAt: ['now'],
-  // Resolve conflict: set field to the array ['setNull'] (not the setNull operation)
-  extra: ['set', ['setNull']],
-  // Custom expression: balance = score * 2
-  balance: ['expr', '?? * ?', ['score', 2]],
-  // Expression without parameters
-  balance2: ['expr', 'RAND() * 100']
-})
-```
-
 ### Order By Expressions
 
 Starting from version 0.7.0, the `orderBy` parameter is upgraded to `OrderBy<T>` type, supporting custom
@@ -630,17 +619,21 @@ In actual development, table and column names don't necessarily need to be param
 
 As introduced in environment variables, MYSQL_VERSION_CONTROL_ENABLED enables version management, and MYSQL_VERSION_CONTROL_DIR sets the version directory. Currently, absolute paths or relative paths from the process working directory are supported.
 
-In the version directory, all files follow the format "numeric version number.sql".
+In the version directory, file names must start with a digit, optionally followed by descriptive text.
 
 Example version directory file listing:
 
 ```
-1.sql
-2.sql
-3.sql
+1.sql                   # maps to version 1
+2_init.sql              # maps to version 2
+3_add_user_index.sql    # maps to version 3
 ```
 
-Version numbers start from 1 and increment sequentially. **For program iterations, new versions must add new files, not modify existing ones.** The component does not have file validation to prevent modification of old files, nor does it support version comments. These need to be handled through project code version control.
+Version numbers start from 1 and increment sequentially. Names like `v1.sql` or `init_v1.sql` (not starting with a digit) are not supported.
+
+> **⚠️ Duplicate version check**: If two files resolve to the same version number (e.g., `1_init.sql` and `1_create_table.sql` both map to version 1), the startup will throw an exception clearly indicating the conflicting file paths.
+
+**For program iterations, new versions must add new files, not modify existing ones.** The component does not have file validation to prevent modification of old files. These need to be handled through project code version control.
 
 **Note: Do not execute time-consuming SQL in version management. Each version's SQL should be as short as possible.** This is mainly because version management executes within a transaction. Too long execution times may cause transaction timeout and failure, and program startup time will be very long. For time-consuming operations like creating indexes on large tables, manual database operations are required and cannot be completed through version management.
 

package/documentation/zh-cn/mysql.md

@@ -154,13 +154,29 @@ export const tableUser: Table<User> = {
 
 | js 原生类型     | mysql 字段类型                                                       |
 | :-------------- | :------------------------------------------------------------------- |
-| Boolean         | TINYINT                                                              |
 | Number          | TINYINT,SMALLINT,INT,MEDIUMINT,YEAR.FLOAT,DOUBLE,BIGINT              |
 | Date            | TIMESTAMP,DATE,DATETIME                                              |
 | Buffer          | TINYBLOB,MEDIUMBLOB,LONGBLOB,BLOB,BINARY,VARBINARY,BIT               |
 | String          | CHAR,VARCHAR,TINYTEXT,MEDIUMTEXT,LONGTEXT,TEXT,ENUM,SET,DECIMAL,TIME |
 | Object 或 Array | JSON                                                                 |
 
+> **⚠️ 关于 `boolean` 类型的安全提示**
+>
+> MySQL 中的 `BOOLEAN` 实际是 `TINYINT(1)`，驱动返回的是 `0` 或 `1`（number 类型），**不是 `true`/`false`**。如果你在实体类中将字段声明为 `boolean`，查询结果的值和 `true`/`false` 做 `===` 全等比较时就会产生 bug。
+>
+> 框架**不支持**类型自动映射，也不会提供。因为即使框架帮你做了映射，手写 `query()` 自定义 SQL 查出来的结果仍然是 `0`/`1`，始终存在应用层与数据库层之间的类型断裂，这是框架层面无法消除的安全隐患。
+>
+> **最安全的做法**是将这类字段的类型声明为 `0 | 1`，直接使用数据库返回的真实类型：
+>
+> ```ts
+> export interface User {
+>   // 推荐：使用 0 | 1，与数据库返回的真实值一致
+>   is_active: 0 | 1
+> }
+> ```
+>
+> `0 | 1` 在条件判断中的表现和 `boolean` 几乎一样——`if (user.is_active)`、`user.is_active ? '是' : '否'` 都能正常工作。唯一需要注意的就是避免 `=== true` 这种全等比较。这样无论是单表操作方法还是自定义 SQL，查出来的值始终一致，一劳永逸。
+
 对于可空字段，可以在 ts 里也定义为可空：
 
 ```ts
@@ -228,13 +244,6 @@ await manager.insert(tableUser, {
   nickname: '小明',
   balance: 1
 })
-// 插入时使用表达式
-await manager.insert(tableUser, {
-  id: 'in002',
-  nickname: '小红',
-  balance: ['expr', '?? * ?', ['score', 2]],
-  createAt: ['now']
-})
 // 批量插入
 await manager.insertMany(tableUser, [
   { id: 'im001', nickname: '张飞', balance: 0 },
@@ -343,26 +352,6 @@ await manager.modify(`update user set nickname='无名' where nickname='佚名'`
 | query           | 自定义 sql 查询，返回记录列表，支持预编译 sql                                       |
 | modify          | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                                     |
 
-### 插入表达式
-
-从 0.7.0 版本开始，`insert`、`insertMany`、`upsert` 等插入方法的 data 参数支持 `InsertValue` 类型，
-可以在 VALUES 子句中使用表达式：
-
-```ts
-await manager.insert(tableUser, {
-  id: 'in001',
-  nickname: '小明',
-  // 设置为 NOW()
-  createAt: ['now'],
-  // 解决冲突：将字段设置为 ['setNull'] 这个数组值（而非执行 setNull 操作）
-  extra: ['set', ['setNull']],
-  // 自定义表达式：balance = score * 2
-  balance: ['expr', '?? * ?', ['score', 2]],
-  // 无参数表达式
-  balance2: ['expr', 'RAND() * 100']
-})
-```
-
 ### 排序表达式
 
 从 0.7.0 版本开始，`orderBy` 参数升级为 `OrderBy<T>` 类型，除了普通列排序外，还支持自定义表达式排序。
@@ -639,18 +628,22 @@ update `user` set `name` = 'tom' where `id` = '001'
 前面环境变量有介绍，变量 MYSQL_VERSION_CONTROL_ENABLED 启用管理，变量 MYSQL_VERSION_CONTROL_DIR 设置版本目录，
 目前支持绝对路径或者相对于进程工作目录的相对路径。
 
-在版本目录中，所有的文件的格式都是“数字版本号加.sql”。
+在版本目录中，文件名必须以数字开头，数字后可加描述文字。
 
 版本管理目录文件列表示例：
 
 ```
-1.sql
-2.sql
-3.sql
+1.sql                   # 等价于版本号 1
+2_init.sql              # 等价于版本号 2
+3_add_user_index.sql    # 等价于版本号 3
 ```
 
-版本号是从 1 开始的，逐个递增。**程序迭代，新版本必须添加新的文件，而不能改动已有的版本文件。**
-组件并没有文件校验功能，来防止改动旧文件，也不支持为版本加注释，这些需要在项目中做作好代码的版本控制。
+版本号是从 1 开始的，逐个递增。不支持 `v1.sql` 或 `init_v1.sql` 这类不以数字开头的命名。
+
+> **⚠️ 重复版本号校验**：如果有两个文件解析出版本号相同（如 `1_init.sql` 和 `1_create_table.sql` 都对应版本 1），启动时会抛异常，并明确指出冲突的文件路径。
+
+**程序迭代，新版本必须添加新的文件，而不能改动已有的版本文件。**
+组件并没有文件校验功能，来防止改动旧文件，这些需要在项目中做作好代码的版本控制。
 
 **注意不要在版本管理中执行耗时较久的 sql，每个版本的 sql 都尽可能要短。**这主要是因为版本管理在执行在事务中的，
 时间太长会因事务会超导致失败，程序的启动时间也会很长。对于大表创建索引等非常耗时的场景，只能手动操作数据库，无法在版本管理中完成。

package/documentation/zh-cn/philosophy.md

@@ -0,0 +1,433 @@
+# wok-server 设计哲学
+
+wok-server 不是又一个模仿现有框架的轮子。它的设计没有参考 TypeORM、Prisma 或 Sequelize，而是基于 Java 和 Node.js 的工程经验，选择最直接、最透明、学习成本最低的方案。
+
+核心原则只有一个：**实用主义**。
+
+下面以 MySQL 组件为例，说明这些设计决策背后的思考。
+
+---
+
+## 为什么不做装饰器
+
+主流 ORM（TypeORM、NestJS 的 MikroORM）大量使用装饰器：
+
+```ts
+@Entity()
+class User {
+  @PrimaryGeneratedColumn()
+  id: number
+
+  @Column({ type: 'varchar', length: 100 })
+  name: string
+}
+```
+
+装饰器的问题：
+
+- **不是 JavaScript 原生特性**，需要 `experimentalDecorators` + `reflect-metadata` + `emitDecoratorMetadata` 三个开关，运行时还要 polyfill
+- **元数据不透明**，实体和数据库的映射关系分散在多个装饰器调用中，调试时看不到全貌，出问题只能猜
+- **学习成本高**，要理解装饰器执行顺序、反射 API、参数化装饰器工厂
+- **强制 OOP 风格**，实体必须是 `class`，不能用 `interface` 或纯对象
+
+wok-server 用纯对象配置：
+
+```ts
+export interface User {
+  id: string
+  name: string
+}
+
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['name']
+}
+```
+
+所有映射信息在一个对象里，出问题直接看这一个文件。不需要学框架特有的语法，没有运行时依赖。
+
+Prisma 虽然也不用装饰器，但发明了 Prisma Schema Language（PSL），学习成本转移到了另一套 DSL 上。wok-server 没有框架特有的语法，配置就是普通 TypeScript 对象。
+
+---
+
+## 为什么不做跨数据库支持
+
+TypeORM 宣传"支持 10 个数据库"，Sequelize 和 Prisma 也走跨数据库路线。但真实情况是：
+
+- **项目几乎从不换数据库**。迁移涉及数据、存储过程、触发器、权限、性能调优，ORM 抽象层解决不了。
+- **真要换就是重构**，框架很可能也换了。
+- **跨数据库必然复杂**。需要统一 `VARCHAR`、`TEXT`、`STRING` 的语义差异，只能支持各数据库的"交集"特性，高级特性（如 MySQL 的 `ON DUPLICATE KEY UPDATE`、PostgreSQL 的 `JSONB` 操作符）无法暴露。
+
+wok-server-mysql 是 MySQL 专用工具，可以：
+
+- 充分利用 MySQL 特性（`JSON_EXTRACT`、`ON DUPLICATE KEY UPDATE`、`LIMIT` 语法）
+- 类型映射直接对应 MySQL 的 JS 类型（`TINYINT` → `boolean`）
+- 迁移 SQL 直接写 MySQL 方言，不需要抽象
+- 维护成本只测 MySQL 即可
+
+"支持 10 个数据库"是营销卖点，不是技术必然。wok-server 选择深度做好一个数据库。
+
+---
+
+## 为什么用纯 SQL 迁移
+
+TypeORM 的迁移是 TypeScript 文件：
+
+```ts
+export class AddUserIndex1640000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`CREATE INDEX ...`)
+  }
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX ...`)
+  }
+}
+```
+
+Sequelize 用 `queryInterface` API：
+
+```ts
+await queryInterface.addColumn('Users', 'age', {
+  type: DataTypes.INTEGER,
+  allowNull: true
+})
+```
+
+Prisma 用声明式 schema 生成：
+
+```bash
+npx prisma migrate dev --name add_age
+```
+
+这些方案的代价：
+
+- **API 数量爆炸**。`addColumn`、`removeColumn`、`changeColumn`、`renameColumn`、`addIndex`... 几十个方法要学。
+- **表达能力不足**。复杂 DDL（如 `ALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE`）无法表达，必须 drop 到 raw SQL。
+- **不透明**。`queryInterface.addColumn` 在 MySQL 和 PostgreSQL 生成的 SQL 不同，出问题更难调试。
+- **DBA 无法审查**。给 DBA 看 TypeScript 代码或 schema 文件？不如直接给 SQL。
+
+wok-server 的迁移：
+
+```sql
+-- 001_init.sql
+CREATE TABLE `user` (
+  `id` varchar(32) NOT NULL PRIMARY KEY,
+  `nickname` varchar(100) DEFAULT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- 002_add_age.sql
+ALTER TABLE `user` ADD COLUMN `age` int DEFAULT NULL AFTER `nickname`;
+```
+
+零学习成本（会 SQL 就会写迁移），完全透明（执行的就是你写的 SQL），DBA 可直接审查，表达能力无限（任何数据库特性都能用）。
+
+迁移是一次性脚本，框架只负责"按顺序执行 + 版本记录"，不应该试图替代 SQL。
+
+---
+
+## 为什么多数据源是显式的
+
+TypeORM 支持自动读写分离：
+
+```ts
+new DataSource({
+  replication: {
+    master: { host: 'server1', ... },
+    slaves: [{ host: 'server2', ... }, { host: 'server3', ... }]
+  }
+})
+```
+
+默认行为：读操作随机路由到 slave，写操作走 master。
+
+问题：**写后读可能读到旧数据**。主从同步有延迟，刚写入的数据在 slave 上可能还没同步。自动路由的"魔法"让开发者不知道 SQL 发到了哪里，出了问题难定位。
+
+wok-server 的读写分离：
+
+```ts
+await enableMysql('master')
+await enableMysql('slave')
+
+const masterMgr = getMysqlManager('master')
+const slaveMgr = getMysqlManager('slave')
+
+// 写操作显式用 master
+await masterMgr.insert(tableUser, { id: '001', nickname: 'jack' })
+
+// 读操作显式用 slave
+const user = await slaveMgr.findById(tableUser, '001')
+```
+
+代码多一点，但**完全可控**。业务代码决定走哪个库，不会出现"写后读"的意外。调试时清晰知道 SQL 发到了哪里。
+
+---
+
+## 为什么复杂查询直接写 SQL
+
+wok-server 封装了单表 CRUD，但不做关联自动加载。任何 join 场景直接写 SQL：
+
+```ts
+const list = await manager.query<{ author: string; book: string }>(
+  'select u.nickname as author, b.name as book from ?? u left join ?? b on u.id=b.author_id',
+  ['user', 'book']
+)
+```
+
+TypeORM 的关联查询：
+
+```ts
+await repo.find({
+  relations: { profile: true, posts: { comments: true } },
+  where: { posts: { comments: { author: { name: 'Timber' } } } }
+})
+```
+
+嵌套对象在深层关联时极易写错，生成的 SQL 不透明，N+1 问题隐蔽。wok-server 不做这个抽象，复杂查询直接写 SQL，反而更可控。
+
+---
+
+## 元组表达式：解决歧义的简洁方案
+
+更新操作有个经典问题：如何区分"不更新这个字段"和"把这个字段设为 null"？
+
+wok-server 用元组：
+
+```ts
+await manager.partialUpdate(tableUser, {
+  id: 'pu000',
+  balance: ['inc', 22],      // 自增 22
+  nickname: ['setNull'],      // 设为 NULL
+  avatar: undefined           // 不更新（忽略）
+})
+```
+
+不需要像 TypeORM 那样 drop 到 `QueryBuilder` 或 raw SQL：
+
+```ts
+await repo.update('pu000', { balance: () => 'balance + 22' })
+```
+
+元组表达式（`['inc']`、`['setNull']`、`['expr', '...']`）是跨数据库可复用的设计，简洁且没有歧义。
+
+---
+
+## 符合直觉的 API 设计
+
+wok-server 的 API 设计遵循一个原则：**减少记忆负担，增加类型约束，但不做类型体操**。
+
+### 链式条件比操作符类更直觉
+
+TypeORM 的条件查询：
+
+```ts
+import { Like, MoreThan, Between } from 'typeorm'
+
+await repo.find({
+  where: {
+    name: Like('Bob%'),
+    age: MoreThan(18),
+    score: Between(60, 100)
+  }
+})
+```
+
+需要记忆 `Like`、`MoreThan`、`Between` 等操作符类，还要正确 import。
+
+wok-server 的链式条件：
+
+```ts
+await mgr.findFirst(tableUser, c =>
+  c.like('name', 'Bob%').gt('age', 18).between('score', 60, 100)
+)
+```
+
+方法名就是自然语言（`like`、`gt`、`between`），不需要 import 任何东西，也不需要记忆操作符类名。
+
+### 统一模式减少 API 记忆
+
+wok-server 的查询 API 遵循统一模式：
+
+| 操作 | 单条 | 列表 | 分页 | 部分字段 |
+|------|------|------|------|---------|
+| 查询 | `findFirst` | `find` | `paginate` | `findSelect` / `paginateSelect` |
+| 条件 | `criteria` / 链式回调 | `criteria` / 链式回调 | `criteria` / 链式回调 | `criteria` / 链式回调 |
+| 排序 | `orderBy` 参数 | `orderBy` 参数 | `orderBy` 参数 | `orderBy` 参数 |
+
+学会一个，其他都是同一模式。不需要记忆 `findOne`、`findOneById`、`findOneOrFail`、`findAndCount` 等几十个变体。
+
+### 类型约束但无类型体操
+
+wok-server 的类型系统简单直接：
+
+```ts
+// Table<T> 定义实体和表的映射
+const tableUser: Table<User> = { ... }
+
+// findById 返回 User | undefined
+const user = await mgr.findById(tableUser, '001')
+// user 类型是 User | undefined
+
+// insert 参数是 User 类型，必填字段必须存在
+await mgr.insert(tableUser, { id: '001', name: 'Bob' })
+
+// findSelect 返回 Pick<User, K>
+const list = await mgr.findSelect(tableUser, ['id', 'name'], { ... })
+// list 类型是 Array<Pick<User, 'id' | 'name'>>
+```
+
+没有复杂的条件类型、没有映射类型体操、没有 `DeepPartial` 或 `EntityTarget` 等抽象概念。类型是**约束工具**，不是**智力游戏**。
+
+Prisma 的类型推断最强，但依赖 `prisma generate` 生成大量类型定义文件。TypeORM 的 `SelectQueryBuilder` 类型链式调用时容易类型丢失。wok-server 用简单的泛型参数实现类型安全，AI 和人类都容易理解。
+
+---
+
+## 与主流框架的对比
+
+| 维度 | wok-server | TypeORM | Prisma | Sequelize |
+|------|-----------|---------|--------|-----------|
+| 实体配置 | 纯对象 | 装饰器 | PSL 文件 | 模型定义 |
+| 学习成本 | **低** | 高 | 高 | 中 |
+| 迁移方式 | 纯 SQL | TS 套壳 | 声明式生成 | API 抽象 |
+| 迁移透明度 | **高** | 低 | 低 | 低 |
+| 跨数据库 | 不支持（MySQL 专用） | 支持 | 支持 | 支持 |
+| 关联查询 | 手写 SQL | 自动加载 | 自动加载 | 自动加载 |
+| 读写分离 | 显式 manager | 自动路由 | 无原生支持 | 需自行实现 |
+| 类型安全 | 中 | 高 | **高** | 低 |
+
+wok-server 的定位是"内部团队的单表 CRUD 工具 + SQL 兜底"，在这个定位上，设计是优秀的：没有过度设计，不做关联 ORM、不做自动路由、不做 schema 生成，透明度和可控性优先于便利性。
+
+---
+
+## 对 AI 编程友好
+
+wok-server 的简单透明设计，在 AI 辅助编程时代有天然优势。
+
+### 纯对象配置 = AI 容易理解上下文
+
+装饰器的问题：
+
+```ts
+@Entity()
+class User {
+  @PrimaryGeneratedColumn()
+  id: number
+
+  @Column({ type: 'varchar', length: 100 })
+  name: string
+
+  @OneToMany(() => Post, post => post.author)
+  posts: Post[]
+}
+```
+
+AI 需要理解：
+- `@Entity()` 是什么意思
+- `@PrimaryGeneratedColumn()` 的参数有哪些
+- `@OneToMany` 的回调函数 `post => post.author` 是什么关系
+- `Post` 实体在哪里定义
+- 这些装饰器在运行时生成什么 SQL
+
+wok-server 的纯对象：
+
+```ts
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['name', 'email']
+}
+```
+
+AI 看到的就是**一个普通对象**，没有魔法。字段名、表名、列名一目了然，不需要理解框架特有的元数据系统。
+
+### 显式调用 = AI 不会"猜错"
+
+TypeORM 的自动路由：
+
+```ts
+// AI 怎么知道这条查询走 master 还是 slave？
+const user = await repo.findOne({ where: { id: 1 } })
+```
+
+AI 无法从代码中推断出连接路由逻辑，因为路由规则在 `DataSource` 配置里，和查询代码分离。
+
+wok-server 的显式选择：
+
+```ts
+// AI 明确知道：这是读操作，用 slaveMgr
+const user = await slaveMgr.findById(tableUser, '001')
+
+// AI 明确知道：这是写操作，用 masterMgr
+await masterMgr.insert(tableUser, { id: '002', name: 'Bob' })
+```
+
+AI 从代码本身就能理解意图，不需要追踪隐式的配置。
+
+### 纯 SQL 迁移 = AI 直接生成可执行代码
+
+Prisma 的迁移流程：
+
+```bash
+# AI 需要理解：改 schema → 生成迁移 → 应用迁移
+npx prisma migrate dev --name add_age
+# 然后还要处理 shadow database、冲突提示...
+```
+
+AI 生成的 schema 变更可能触发 Prisma 的交互式提示（"是否重置数据库？"），AI 无法处理这种交互。
+
+wok-server 的迁移：
+
+```sql
+-- 003_add_age.sql
+ALTER TABLE `user` ADD COLUMN `age` int DEFAULT NULL;
+```
+
+AI 直接生成 SQL 文件，放到 `db_migration/` 目录，按数字命名。没有生成步骤、没有交互、没有黑盒转换。**AI 生成什么，就是什么**。
+
+### 无关联 ORM = AI 不会制造 N+1 陷阱
+
+TypeORM 的关联查询：
+
+```ts
+// AI 生成这段代码看起来合理
+const users = await repo.find({ relations: { posts: true } })
+
+// 但可能触发 N+1：先查 users，再对每个 user 查 posts
+// AI 很难从代码层面发现这个性能问题
+```
+
+wok-server 不做关联自动加载，AI 写 join 时必须显式写 SQL：
+
+```ts
+const list = await mgr.query(
+  'select u.*, p.title from user u left join post p on u.id=p.user_id'
+)
+```
+
+SQL 的性能问题（如缺少索引、大表全扫描）是**数据库层面的知识**，AI 更容易从 SQL 本身识别，而不是从 ORM 的隐式行为中推断。
+
+### 统一的元组表达式 = AI 有明确模式
+
+```ts
+// AI 学习一次模式，到处复用
+{ balance: ['inc', 22] }      // 自增
+{ status: ['setNull'] }        // 置空
+{ score: ['expr', '?? * ?', ['base', 2]] }  // 自定义表达式
+```
+
+模式统一、可组合，AI 不容易混淆。相比之下，TypeORM 的更新：
+
+```ts
+// 不同场景用不同 API
+repo.update(id, { balance: () => 'balance + 22' })  // raw SQL
+repo.increment(id, 'balance', 22)                    // 专用方法
+repo.save(entity)                                     // 完整实体
+```
+
+AI 需要记忆多个 API 和它们的适用场景。
+
+---
+
+## 一句话总结
+
+wok-server 的每一个设计决策，都是在"简单透明"和"功能强大"之间选择了前者。不是因为做不到，而是因为**选择不做**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {