schema-dsl 1.1.0 → 1.1.2

package/STATUS.md

@@ -1,13 +1,15 @@
 # schema-dsl 项目状态
 
-> **最后更新**: 2026-01-04  
-> **当前版本**: v1.0.9  
-> **项目状态**: ✅ 全部完成，测试100%通过（725个测试）  
+> **最后更新**: 2026-01-06  
+> **当前版本**: v1.1.1  
+> **项目状态**: ✅ 全部完成，测试100%通过（921个测试）  
 
 ---
 
 ## 📋 目录
 
+- [v1.1.1](#v111) - 2026-01-06 ✅ 已完成
+- [v1.1.0](#v110) - 2026-01-05 ✅ 已完成
 - [v1.0.9](#v109) - 2026-01-04 ✅ 已完成
 - [v1.0.8](#v108) - 2026-01-04 ✅ 已完成
 - [v1.0.7](#v107) - 2026-01-04 ✅ 已完成
@@ -23,6 +25,66 @@
 
 ## 版本发布计划
 
+### v1.1.1
+
+**发布日期**: 2026-01-06  
+**状态**: ✅ 已完成  
+**类型**: 🎉 新功能 - ConditionalBuilder 独立消息 + I18nError 多语言错误  
+**进度**: 100%完成 | 测试: 921个通过 | 新增: 52个测试
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| ConditionalBuilder 独立消息 | ✅ 完成 | P1 | `.and()/.or()` 后可调用 `.message()` |
+| I18nError 多语言错误 | ✅ 完成 | P1 | 统一的多语言错误抛出机制 |
+| dsl.error 快捷方法 | ✅ 完成 | P1 | create/throw/assert 三个方法 |
+| TypeScript 类型定义 | ✅ 完成 | P0 | I18nError + dsl.error 类型 |
+| 测试用例 | ✅ 完成 | P0 | 52个新测试（24+28） |
+| 文档更新 | ✅ 完成 | P0 | README + CHANGELOG + examples |
+| 语言包扩充 | ✅ 完成 | P1 | 中英文 20+ 错误消息 |
+
+**实现状态统计**:
+- ✅ 完成: 7个
+- 🔄 进行中: 0个
+- ⏳ 待完成: 0个
+
+**核心变更**:
+- ✅ **新增**: ConditionalBuilder 支持 `.and()/.or()` 独立消息
+- ✅ **新增**: I18nError 类 (lib/errors/I18nError.js)
+- ✅ **新增**: dsl.error 快捷方法 (create/throw/assert)
+- ✅ **新增**: 20+ 内置错误代码（通用/账户/用户/订单）
+- ✅ **新增**: examples/i18n-error.examples.js 示例文件
+- ✅ **更新**: README FAQ Q7/Q8
+- ✅ **更新**: CHANGELOG v1.1.1 完整记录
+- ✅ **更新**: index.d.ts TypeScript 类型定义
+
+---
+
+### v1.1.0
+
+**发布日期**: 2026-01-05  
+**状态**: ✅ 已完成  
+**类型**: 🎉 重大功能 - 跨类型联合验证 + 插件系统增强  
+**进度**: 100%完成
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| 跨类型联合验证 | ✅ 完成 | P1 | `types:string|number` 语法 |
+| 插件 DSL 类型注册 | ✅ 完成 | P1 | 插件可注册自定义 DSL 类型 |
+| DslBuilder.registerType | ✅ 完成 | P0 | 静态方法供插件使用 |
+| 文档更新 | ✅ 完成 | P0 | README + CHANGELOG |
+
+**实现状态统计**:
+- ✅ 完成: 4个
+- 🔄 进行中: 0个
+- ⏳ 待完成: 0个
+
+**核心变更**:
+- ✅ **新增**: `types:` 语法支持跨类型联合验证
+- ✅ **增强**: 插件系统支持 DSL 类型注册
+- ✅ **新增**: DslBuilder.registerType() 静态方法
+
+---
+
 ### v1.0.9
 
 **发布日期**: 2026-01-04  

package/docs/conditional-api.md

@@ -1,7 +1,7 @@
 # 链式条件 API - ConditionalBuilder
 
-> **版本**: v1.1.0  
-> **更新日期**: 2026-01-05  
+> **版本**: v1.1.1  
+> **更新日期**: 2026-01-06  
 > **状态**: ✅ 稳定
 
 ---
@@ -9,6 +9,7 @@
 ## 📋 目录
 
 - [概述](#概述)
+- [🆕 v1.1.1 新功能](#-v110-新功能)
 - [快速开始](#快速开始)
 - [API 参考](#api-参考)
 - [使用场景](#使用场景)
@@ -26,11 +27,153 @@
 - ✅ **链式调用** - 流畅的 API，类似 JavaScript if-else
 - ✅ **运行时执行** - 在验证时根据实际数据判断
 - ✅ **多条件组合** - 支持 and/or 逻辑组合
+- ✅ **🆕 独立消息** - v1.1.1+ 每个 .and()/.or() 可有独立错误消息
 - ✅ **else 可选** - 不写 else 就不验证
 - ✅ **简化设计** - message 自动抛错，无需 throwError()
 - ✅ **完全兼容** - 不影响现有 API
 
-### 与现有方法的区别
+---
+
+## 🆕 v1.1.1 新功能
+
+### 独立消息支持 - `.and()/.or()` 后可调用 `.message()`
+
+**每个条件都可以有自己的错误消息**
+
+v1.1.1 开始，支持在 `.and()` 和 `.or()` 后调用 `.message()` 设置独立的错误消息，让错误提示更精确。
+
+#### 基础用法
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// ✅ v1.1.1+ 新功能：每个条件独立消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 'ACCOUNT_NOT_FOUND'
+// - 第二个条件为 true → 返回 'INSUFFICIENT_TRADABLE_CREDITS'
+// - 所有条件为 false → 验证成功
+```
+
+#### 多个 .and() 条件
+
+```javascript
+// 多层验证，每层都有清晰的错误消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('ACCOUNT_INACTIVE')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+
+// 依次检查，第一个为 true 的条件返回其消息
+```
+
+#### .or() 条件独立消息
+
+```javascript
+// OR 条件也支持独立消息
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .or(d => d.isBlocked)
+  .message('账户已被封禁')
+  .assert(data);
+
+// 任一条件为 true 就失败，返回对应消息
+```
+
+#### 链式检查模式
+
+v1.1.1 引入了**链式检查模式**，当满足以下条件时自动启用：
+
+1. 使用 `.message()` 模式（不是 `.then()`/`.else()`）
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
+
+**链式检查模式特点**：
+- 依次检查每个条件
+- 第一个为 `true` 的条件失败，返回其消息
+- 所有条件为 `false` 时验证通过
+
+**示例对比**：
+
+```javascript
+// ✅ 启用链式检查（纯 AND 场景）
+dsl.if(d => !d).message('A').and(d => d < 100).message('B')
+
+// ❌ 不启用（有 .or()，使用传统 AND/OR 逻辑）
+dsl.if(d => !d).message('A').and(d => d < 100).or(d => d > 200).message('B')
+
+// ❌ 不启用（使用 .then()/.else()，不是 message 模式）
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').then('email!')
+```
+
+#### 向后兼容性
+
+**100% 向后兼容**，不影响现有代码：
+
+```javascript
+// ✅ 原有用法继续工作
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').message('不符合条件')
+
+// ✅ .and() 后不调用 .message() 也可以
+dsl.if(d => !d).message('整体错误').and(d => d < 100).assert(50)
+// → 使用整体消息 '整体错误'
+```
+
+#### 实际应用场景
+
+**场景1：账户验证**
+```javascript
+function validateAccount(account, amount) {
+  dsl.if(d => !d)
+    .message('ACCOUNT_NOT_FOUND')
+    .and(d => d.status !== 'active')
+    .message('ACCOUNT_INACTIVE')
+    .and(d => d.balance < amount)
+    .message('INSUFFICIENT_BALANCE')
+    .assert(account);
+}
+
+// 每个失败点都有清晰的错误消息
+```
+
+**场景2：用户权限验证**
+```javascript
+function validateUserPermission(user) {
+  dsl.if(d => d.role !== 'admin')
+    .message('NO_ADMIN_PERMISSION')
+    .and(d => !d.isVerified)
+    .message('USER_NOT_VERIFIED')
+    .and(d => d.isBanned)
+    .message('USER_BANNED')
+    .assert(user);
+}
+```
+
+**场景3：订单状态检查**
+```javascript
+function validateOrder(order) {
+  dsl.if(d => d.status !== 'paid')
+    .message('ORDER_NOT_PAID')
+    .and(d => !d.payment)
+    .message('PAYMENT_INFO_MISSING')
+    .and(d => !d.shippingAddress)
+    .message('SHIPPING_ADDRESS_MISSING')
+    .assert(order);
+}
+```
+
+---
+
+## 与现有方法的区别
 
 `dsl.if()` 提供两种使用方式，根据参数类型自动选择：
 
@@ -180,19 +323,59 @@ dsl.if((data) => data.status === 'active' && data.verified)
 
 添加 AND 条件（与前一个条件组合）。
 
+> **v1.1.1+** 支持在 `.and()` 后调用 `.message()` 设置独立的错误消息
+
 **参数**:
 - `condition` {Function} - 条件函数
 
 **返回**: `this` - 支持链式调用
 
-**示例**:
+**基础示例**:
 ```javascript
+// 传统用法：所有条件共享一个消息
 dsl.if((data) => data.age >= 18)
   .and((data) => data.userType === 'admin')
-  .then('email!')
+  .message('不符合条件')
+```
+
+**v1.1.1+ 独立消息**:
+```javascript
+// ✅ 每个条件都有自己的错误消息
+dsl.if((data) => !data)
+  .message('账户不存在')
+  .and((data) => data.balance < 100)
+  .message('余额不足')
+  .assert(account);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 '账户不存在'
+// - 第二个条件为 true → 返回 '余额不足'
+// - 所有条件为 false → 验证成功
+```
+
+**多个 .and() 条件**:
+```javascript
+// 支持多个 .and() 条件，每个都有独立消息
+dsl.if(d => !d)
+  .message('NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('INACTIVE')
+  .and(d => d.balance < 100)
+  .message('INSUFFICIENT')
+  .assert(account);
+
+// 依次检查，第一个为 true 的条件返回其消息
 ```
 
-**逻辑**: `(condition1 AND condition2)`
+**逻辑**: 
+- 传统模式：`(condition1 AND condition2)` - 所有条件为 true 才失败
+- 链式检查模式 (v1.1.1+)：依次检查，第一个为 true 的失败
+
+**链式检查模式触发条件**:
+1. 使用 `.message()` 模式
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
 
 ---
 
@@ -200,19 +383,41 @@ dsl.if((data) => data.age >= 18)
 
 添加 OR 条件（与前一个条件组合）。
 
+> **v1.1.1+** 支持在 `.or()` 后调用 `.message()` 设置独立的错误消息
+
 **参数**:
 - `condition` {Function} - 条件函数
 
 **返回**: `this` - 支持链式调用
 
-**示例**:
+**基础示例**:
 ```javascript
+// 传统用法：所有条件共享一个消息
 dsl.if((data) => data.age < 18)
   .or((data) => data.status === 'blocked')
   .message('不允许注册')
 ```
 
-**逻辑**: `(condition1 OR condition2)`
+**v1.1.1+ 独立消息**:
+```javascript
+// ✅ 每个 OR 条件都有自己的错误消息
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .or(d => d.isBlocked)
+  .message('账户已被封禁')
+  .assert(data);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 '未成年用户不能注册'
+// - 第二个条件为 true → 返回 '账户已被封禁'
+// - 所有条件为 false → 验证成功
+```
+
+**逻辑**: `(condition1 OR condition2)` - 任一条件为 true 就失败
+
+**注意**: 
+- 如果有 `.or()` 条件，不会启用链式检查模式
+- 使用传统 AND/OR 组合逻辑
 
 ---
 
@@ -242,14 +447,16 @@ dsl.if((data) => data.userType === 'admin')
 
 设置错误消息（支持多语言 key）。
 
+> **v1.1.1+** 支持为 `.and()` 和 `.or()` 条件设置独立消息
+
 **参数**:
 - `msg` {string} - 错误消息或多语言 key
 
 **返回**: `this` - 支持链式调用
 
-**行为**: 不满足条件时自动抛出此错误（无需 `.throwError()`）
+**行为**: 条件为 true 时自动抛出此错误（无需 `.throwError()`）
 
-**示例**:
+**基础示例**:
 ```javascript
 dsl.if((data) => data.age >= 18)
   .message('未成年用户不能注册')
@@ -259,6 +466,45 @@ dsl.if((data) => data.age >= 18)
   .message('error.underage')
 ```
 
+**v1.1.1+ 为 .and() 设置独立消息**:
+```javascript
+// ✅ 每个条件都有自己的错误消息
+dsl.if((data) => !data)
+  .message('账户不存在')
+  .and((data) => data.balance < 100)
+  .message('余额不足')
+  .assert(account);
+```
+
+**v1.1.1+ 为 .or() 设置独立消息**:
+```javascript
+// ✅ OR 条件也支持独立消息
+dsl.if(d => d.age < 18)
+  .message('未成年')
+  .or(d => d.isBlocked)
+  .message('已封禁')
+  .assert(data);
+```
+
+**链式检查模式说明** (v1.1.1+):
+
+当满足以下条件时，自动启用链式检查模式：
+1. 使用 `.message()` 模式（不是 `.then()`/`.else()`）
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
+
+```javascript
+// ✅ 启用链式检查（纯 AND 场景）
+dsl.if(d => !d).message('A').and(d => d < 100).message('B')
+
+// ❌ 不启用（有 .or()）
+dsl.if(d => !d).message('A').and(d => d < 100).or(d => d > 200).message('B')
+
+// ❌ 不启用（使用 .then()/.else()）
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').then('email!')
+```
+
 ---
 
 ### .then(schema)
@@ -1011,7 +1257,7 @@ validate(contactSchema, '13800138000');       // ✅ 作为手机号验证
 
 ## 更新日志
 
-### v1.1.0 (2026-01-05)
+### v1.1.1 (2026-01-05)
 
 - ✅ 新增 `ConditionalBuilder` 类
 - ✅ 新增 `dsl.if()` 链式条件 API