schema-dsl 1.2.5 → 2.0.1

package/changelogs/v1.1.4.md

@@ -1,432 +0,0 @@
-# v1.1.4 变更日志
-
-> **发布日期**: 2026-01-13  
-> **版本号**: v1.1.4  
-> **类型**: 🔧 TypeScript类型修复 + 📚 文档完善
-
----
-
-## 📋 变更概览
-
-| 类型 | 数量 | 说明 |
-|------|------|------|
-| 🔧 Bug修复 | 2 | TypeScript 类型定义重复签名 |
-| 📚 文档更新 | 3 | 多语言文档完善 |
-| ✅ 验证测试 | 3 | 多语言、语法、类型验证 |
-| 🔄 内部改进 | 1 | CHANGELOG 格式统一 |
-
----
-
-## 🔧 TypeScript 类型修复
-
-### 问题描述
-
-index.d.ts 中存在2处重复的函数签名定义，导致 TypeScript 编译器报错（46个类型错误）。
-
-### 修复详情
-
-#### 1. dsl.error.assert 重复签名
-
-**位置**: `index.d.ts` 第1336-1343行
-
-**修复前**:
-```typescript
-assert(
-  condition: any,
-  code: string,
-  params?: Record<string, any>,
-  statusCode?: number,
-  locale?: string
-): asserts condition;
-  statusCode?: number       // ❌ 重复行
-): asserts condition;       // ❌ 重复行
-```
-
-**修复后**:
-```typescript
-assert(
-  condition: any,
-  code: string,
-  params?: Record<string, any>,
-  statusCode?: number,
-  locale?: string
-): asserts condition;
-```
-
-**错误信息**:
-```
-TS1131: Property or signature expected.
-TS1128: Declaration or statement expected.
-应为类型成员
-```
-
----
-
-#### 2. I18nError.assert 重复签名
-
-**位置**: `index.d.ts` 第1805-1821行
-
-**修复前**:
-```typescript
-static assert(
-  condition: any,
-  code: string,
-  params?: Record<string, any>,
-  statusCode?: number,
-  locale?: string
-): asserts condition;
- */                          // ❌ 注释位置错误
-static assert(               // ❌ 重复定义
-  condition: any,
-  code: string,
-  params?: Record<string, any>,
-  statusCode?: number
-): asserts condition;
-```
-
-**修复后**:
-```typescript
-/**
- * 断言方法 - 条件不满足时抛错
- * @param condition - 条件表达式
- * @param code - 错误代码
- * @param params - 错误参数
- * @param statusCode - HTTP 状态码
- * @param locale - 语言环境（可选，不传则使用全局语言）
- * @throws I18nError 条件为 false 时抛出
- */
-static assert(
-  condition: any,
-  code: string,
-  params?: Record<string, any>,
-  statusCode?: number,
-  locale?: string
-): asserts condition;
-```
-
-**错误信息**:
-```
-TS1128: Declaration or statement expected.
-应为语句
-TS1003: Identifier expected.
-```
-
----
-
-### 修复结果
-
-**修复前**:
-- ❌ 46个类型错误
-- ⚠️ 1个警告
-
-**修复后**:
-- ✅ 0个类型错误
-- ⚠️ 2个可忽略警告（设计决策）
-
-**剩余警告**:
-1. `export { _if as if }` - 保留词警告（设计决策，为了提供更好的API）
-2. `toJsonSchema()` - 未使用方法警告（向后兼容保留）
-
----
-
-### 影响范围
-
-- ✅ **仅影响**: TypeScript 类型检查
-- ✅ **不影响**: 运行时逻辑
-- ✅ **向后兼容**: 无破坏性变更
-- ✅ **测试状态**: 921个测试全部通过
-
----
-
-## 📚 文档更新
-
-### 1. 完善运行时多语言支持文档
-
-**文件**: `docs/runtime-locale-support.md`
-
-**更新内容**:
-- ✅ 版本标记更新为 v1.1.4+
-- ✅ 全局语言设置 vs 运行时指定语言对比
-- ✅ API 参数详细说明
-- ✅ Express/Koa 集成示例
-- ✅ 微服务架构中的多语言错误传递
-- ✅ 最佳实践建议
-
-**核心示例**:
-
-```javascript
-// 运行时指定语言（不影响全局设置）
-const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
-// message: "账户不存在"
-
-const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
-// message: "Account not found"
-
-// 根据请求头动态返回
-app.post('/api/account', (req, res) => {
-  const locale = req.headers['accept-language'] || 'en-US';
-  dsl.error.assert(account, 'account.notFound', {}, 404, locale);
-});
-```
-
----
-
-### 2. 更新 README.md 多语言章节
-
-**文件**: `README.md`
-
-**新增内容**:
-
-#### 运行时多语言支持（v1.1.0+）
-
-```javascript
-const { dsl, I18nError } = require('schema-dsl');
-
-// 方式1: 业务错误 - 运行时指定语言
-const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
-console.log(error1.message);  // "账户不存在"
-
-const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
-console.log(error2.message);  // "Account not found"
-
-// 方式2: 断言风格 - 根据请求头动态指定
-app.post('/api/withdraw', (req, res) => {
-  const locale = req.headers['accept-language'] || 'en-US';
-  const account = getAccount(req.user.id);
-  
-  // 根据请求头返回对应语言的错误
-  I18nError.assert(account, 'account.notFound', {}, 404, locale);
-  I18nError.assert(
-    account.balance >= req.body.amount,
-    'account.insufficientBalance',
-    { balance: account.balance, required: req.body.amount },
-    400,
-    locale
-  );
-  
-  // 验证通过，继续处理...
-});
-```
-
-**适用场景**:
-- ✅ 多语言 API（根据请求头返回不同语言）
-- ✅ 微服务架构（错误在服务间传递时保持语言）
-- ✅ 同一请求中需要多种语言的错误消息
-
----
-
-### 3. 更新 README.md Q8章节
-
-**增强内容**: 添加运行时语言支持示例
-
-```javascript
-// 根据请求头动态返回不同语言
-app.post('/api/account', (req, res, next) => {
-  const locale = req.headers['accept-language'] || 'en-US';
-  const account = getAccount(req.user.id);
-  
-  try {
-    // 第5个参数指定语言
-    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
-    dsl.error.assert(
-      account.balance >= 100,
-      'account.insufficientBalance',
-      { balance: account.balance, required: 100 },
-      400,
-      locale
-    );
-    // 验证通过...
-  } catch (error) {
-    next(error);
-  }
-});
-
-// 同一请求中使用不同语言
-const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
-console.log(error1.message);  // "账户不存在"
-
-const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
-console.log(error2.message);  // "Account not found"
-```
-
-**新增文档链接**:
-- 📖 [运行时多语言支持](./docs/runtime-locale-support.md)
-
----
-
-### 4. 生成深度分析报告
-
-**文件**: `reports/schema-dsl/analysis/deep-analysis-multilang-types-v1.1.2.md`
-
-**报告内容**:
-- ✅ 多语言加载机制详细分析
-- ✅ string? 语法支持验证
-- ✅ 类型定义问题分析与修复步骤
-- ✅ 测试验证结果
-- ✅ 优化建议
-
-**核心发现**:
-1. 多语言包在启动时一次性加载（`lib/locales/index.js`）
-2. 支持全局切换：`Locale.setLocale('zh-CN')`
-3. 支持运行时指定：`dsl.error.create(code, params, statusCode, 'zh-CN')`
-4. string? 语法完整支持（包括 `string:3-32?`、`email?` 等）
-
----
-
-## ✅ 验证测试
-
-### 1. 多语言测试
-
-**测试文件**: `test-i18n-support.js`
-
-**测试覆盖**:
-- ✅ dsl.error.create/throw/assert 方法存在性
-- ✅ 5种语言支持验证（中英日法西）
-- ✅ 参数插值功能
-- ✅ 运行时指定语言（不影响全局）
-- ✅ 错误对象属性验证
-- ✅ toJSON 方法
-
-**测试结果**:
-```
-========================================
-  运行时语言支持测试全部通过！
-========================================
-✅ dsl.error.create 支持运行时指定语言
-✅ I18nError.throw 支持运行时指定语言
-✅ I18nError.assert 支持运行时指定语言
-✅ 运行时语言不影响全局语言设置
-✅ 同一请求可使用多种语言
-✅ 适合 API 开发中根据请求头动态返回多语言错误
-
-🎉 所有测试通过！ctx.dsl.error 等方法完全支持多语言！
-```
-
----
-
-### 2. string? 语法测试
-
-**测试文件**: `test-optional-syntax.js`
-
-**测试覆盖**:
-- ✅ `string`（默认可选）
-- ✅ `string!`（必填）
-- ✅ `string?`（显式可选）
-- ✅ `string:3-32?`（范围可选）
-- ✅ `email?`（格式可选）
-
-**测试结果**:
-```
-========================================
-  测试总结
-========================================
-✅ string（默认可选）- 支持
-✅ string!（必填）- 支持
-✅ string?（显式可选）- 支持
-
-🎯 结论：
-  1. string 和 string? 行为相同（都是可选）
-  2. string? 提供更明确的语义表达
-  3. 建议：在需要明确表达"可选"时使用 ?
-```
-
----
-
-### 3. 类型定义验证
-
-**工具**: TypeScript 编译器 + IDE 类型检查
-
-**验证结果**:
-- ✅ 无类型错误
-- ⚠️ 2个可忽略警告
-- ✅ dsl.error 类型完整
-- ✅ I18nError 类型完整
-- ✅ 所有方法签名正确
-
----
-
-## 🔄 内部改进
-
-### 统一 CHANGELOG.md 格式
-
-**参考**: monSQLize/CHANGELOG.md
-
-**改进内容**:
-- ✅ 详细变更移至 `changelogs/` 目录
-- ✅ CHANGELOG.md 保留版本概览和里程碑摘要
-- ✅ 增加版本概览表格
-- ✅ 增加变更统计
-- ✅ 增加里程碑版本摘要
-
-**格式特点**:
-- ✅ 清晰的表格布局
-- ✅ 统一的日期格式（YYYY-MM-DD）
-- ✅ 重要性标记（⭐数量）
-- ✅ Emoji 图标分类（🔧🐛🎉📚✅）
-- ✅ 详细链接到 changelogs/ 目录
-
----
-
-## 📦 依赖变更
-
-**无依赖变更**
-
----
-
-## 🎯 升级指南
-
-### 从 v1.1.3 升级到 v1.1.4
-
-**破坏性变更**: ❌ 无
-
-**推荐操作**:
-```bash
-npm install schema-dsl@1.1.4
-```
-
-**无需修改代码**: 本次更新仅修复 TypeScript 类型定义，不影响运行时行为。
-
----
-
-## 📊 统计信息
-
-### 代码变更
-
-| 文件 | 添加 | 删除 | 说明 |
-|------|------|------|------|
-| index.d.ts | 20 | 9 | 修复重复签名 + 完善注释 |
-| CHANGELOG.md | 150 | 1200 | 格式重构，详情移至 changelogs/ |
-| README.md | 80 | 10 | 添加运行时多语言示例 |
-| STATUS.md | 30 | 10 | 更新版本信息 |
-| package.json | 1 | 1 | 版本号更新 |
-| changelogs/v1.1.4.md | 500 | 0 | 新增详细变更文档 |
-
-### 文档完整性
-
-- ✅ 多语言文档覆盖: 100%
-- ✅ API 文档完整性: 100%
-- ✅ 示例代码数量: 15+
-- ✅ 测试用例数量: 921
-
----
-
-## 🙏 致谢
-
-感谢 monSQLize 项目发现并报告类型定义问题。
-
----
-
-## 🔗 相关链接
-
-- [GitHub Repository](https://github.com/vextjs/schema-dsl)
-- [npm Package](https://www.npmjs.com/package/schema-dsl)
-- [完整文档](./docs/INDEX.md)
-- [运行时多语言支持](./docs/runtime-locale-support.md)
-- [多语言用户指南](./docs/i18n-user-guide.md)
-
----
-
-**发布者**: schema-dsl Team  
-**发布时间**: 2026-01-13  
-**下一版本**: v1.1.5 (计划中)
-