schema-dsl 1.2.2 → 1.2.4

package/.eslintignore

@@ -1,10 +1,11 @@
-node_modules/
-coverage/
-.nyc_output/
-dist/
-build/
-*.log
-.DS_Store
-.temp/
-reports/
-
+node_modules/
+coverage/
+.nyc_output/
+dist/
+build/
+*.log
+.DS_Store
+.temp/
+reports/
+*.d.ts
+

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-02-06
+> **最后更新**: 2026-03-03
 
 ---
 
@@ -9,6 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.2.3](./changelogs/v1.2.3.md) | 2026-03-03 | 🚀 新功能：i18n 子目录合并 - 多人协作独立维护语言文件，自动递归合并 + 冲突检测 | [查看](./changelogs/v1.2.3.md) |
 | [v1.2.2](./changelogs/v1.2.2.md) | 2026-02-06 | 🚀 重大功能：智能类型转换 - 字符串数字自动转换，完美支持 Web API | [查看](./changelogs/v1.2.2.md) |
 | [v1.1.8](./changelogs/v1.1.8.md) | 2026-01-30 | 🚀 新功能：智能参数识别 - 支持简化语法 `dsl.error.throw('key', 'locale')` | [查看](./changelogs/v1.1.8.md) |
 | [v1.1.7](./changelogs/v1.1.7.md) | 2026-01-27 | 🐛 Bug修复：错误消息路径显示优化 - 所有错误类型的 message 只显示字段名 | [查看](./changelogs/v1.1.7.md) |
@@ -31,7 +32,7 @@
 | [v1.0.0](./changelogs/v1.0.0.md) | 2025-12-29 | 初始发布版本 | [查看](./changelogs/v1.0.0.md) |
 
 > 💡 **提示**: 重要版本的详细变更记录在 [changelogs/](./changelogs/) 目录中。  
-> 当前已有详细文档的版本：v1.2.2, v1.1.8, v1.1.7, v1.1.6, v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
+> 当前已有详细文档的版本：v1.2.3, v1.2.2, v1.1.8, v1.1.7, v1.1.6, v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
 > 其他版本的详细变更信息请参考项目提交历史或联系维护者。
 
 ---
@@ -40,7 +41,7 @@
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.2.x | 1 | 智能类型转换、Web API 完美支持 |
+| v1.2.x | 2 | i18n子目录合并、智能类型转换、Web API 完美支持 |
 | v1.1.x | 9 | 智能参数识别、Bug修复、错误消息优化、错误配置增强、TypeScript类型完善、多语言支持、数字运算符、联合类型 |
 | v1.0.x | 10 | 核心功能、验证器、测试覆盖、文档完善 |
 

package/STATUS.md

@@ -1,13 +1,14 @@
 # schema-dsl 项目状态
 
-> **最后更新**: 2026-01-17  
-> **当前版本**: v1.1.5  
-> **项目状态**: ✅ 全部完成，测试100%通过（955个测试）  
+> **最后更新**: 2026-03-03  
+> **当前版本**: v1.2.3  
+> **项目状态**: ✅ 全部完成，测试100%通过（1003个测试）  
 
 ---
 
 ## 📋 目录
 
+- [v1.2.3](#v123) - 2026-03-03 ✅ 已完成
 - [v1.1.5](#v115) - 2026-01-17 ✅ 已完成
 - [v1.1.4](#v114) - 2026-01-13 ✅ 已完成
 - [v1.1.3](#v113) - 2026-01-09 ✅ 已完成
@@ -28,6 +29,30 @@
 
 ## 版本发布计划
 
+### v1.2.3
+
+**发布日期**: 2026-03-03  
+**状态**: ✅ 已完成  
+**类型**: 🚀 功能增强 + 🐛 Bug修复  
+**进度**: 100%完成 | 测试: 1003个通过 (100%)
+
+| 需求标题 | 状态 | 优先级 | 详细 |
+|---------|------|--------|------|
+| i18n 子目录递归扫描 | ✅ 完成 | P0 | index.js `loadLocalesFromDir` |
+| 同名 key 冲突检测（WARN + strict 模式）| ✅ 完成 | P1 | index.js |
+| 语言文件名格式校验 | ✅ 完成 | P1 | index.js |
+| localesPath 对象用法修复 | ✅ 完成 | P1 | index.js |
+| TypeScript 类型扩展（I18nConfig + strict）| ✅ 完成 | P0 | index.d.ts |
+| 新增单元测试（20个） | ✅ 完成 | P0 | test/unit/i18n-subdir.test.js |
+| 修复跨文件测试状态污染（3个 failing → 0）| ✅ 完成 | P0 | test/unit/i18n-subdir.test.js |
+| 更新文档 | ✅ 完成 | P1 | docs/add-custom-locale.md |
+| 更新 CHANGELOG | ✅ 完成 | P0 | changelogs/v1.2.3.md |
+| 更新 STATUS | ✅ 完成 | P0 | STATUS.md |
+
+**向后兼容性**: ✅ 100% 向后兼容
+
+---
+
 ### v1.1.5
 
 **发布日期**: 2026-01-17  

package/changelogs/v1.2.3.md

@@ -0,0 +1,124 @@
+# schema-dsl v1.2.3 变更日志
+
+> **发布日期**: 2026-03-03  
+> **类型**: 功能增强 🚀 + Bug修复 🐛  
+> **重要性**: ⭐⭐⭐⭐⭐
+
+---
+
+## 📋 本版本概览
+
+### 🎯 核心更新
+
+**1. i18n 多语言子目录合并支持（新功能）**
+
+多人协作开发时，支持将多语言文件按模块拆分到子目录，启动时自动递归合并，解决 code 码冲突和 Git merge 冲突问题。
+
+**2. 三个测试状态污染 Bug 修复**
+
+修复全量测试时因跨文件 `Locale` 状态污染导致的 3 个 failing，1003 个测试全部通过。
+
+---
+
+## ✨ 新功能：i18n 子目录合并
+
+### F1：递归子目录扫描
+
+`dsl.config({ i18n: path })` 现在支持递归扫描子目录，每个子目录作为模块组织层，同语言文件自动合并：
+
+```javascript
+// 目录结构
+locales/
+├── core/zh-CN.js       // 公共 code: 1000-1999
+├── account/zh-CN.js    // 账户模块 code: 10000-10999（开发者A）
+├── order/zh-CN.js      // 订单模块 code: 20000-20999（开发者B）
+└── payment/zh-CN.js    // 支付模块 code: 30000-30999（开发者C）
+
+// 一行配置，自动递归合并
+dsl.config({
+  i18n: path.join(__dirname, 'locales')
+});
+```
+
+### F2：同名 key 冲突检测
+
+默认模式打印 WARN，`strict: true` 直接抛错阻断启动（推荐 CI 环境）：
+
+```javascript
+// 默认：WARN 日志
+dsl.config({ i18n: './locales' });
+// [schema-dsl] i18n key 冲突 in locale 'zh-CN'
+//   冲突 key: account.notFound
+//   来源文件: /project/locales/account/zh-CN.js
+
+// 严格模式：抛出 Error
+dsl.config({ i18n: './locales', strict: true });
+```
+
+### F3：语言文件名格式校验
+
+只加载符合语言代码格式（`zh-CN.js`、`en.js` 等）的文件，自动跳过 `index.js`、`utils.js`、`CODE-SEGMENTS.js` 等工具文件。
+
+### 兼容修复：`localesPath` 对象用法真正生效
+
+文档中记载的 `{ localesPath: './path' }` 对象用法之前静默失败，现在已修复：
+
+```javascript
+// 之前：静默失败（localesPath 被当成语言 key 处理）
+// 现在：真正生效
+dsl.config({
+  i18n: { localesPath: path.join(__dirname, 'locales') }
+});
+```
+
+---
+
+## 🐛 Bug 修复：测试状态污染
+
+### 问题根因
+
+`test/unit/i18n-subdir.test.js` 使用了根级别的 `beforeEach(() => Locale.reset())`，导致全量测试时清除了其他测试文件 `before()` 中注册的自定义语言 key，造成以下 3 个测试 failing：
+
+| 测试文件 | 失败原因 |
+|---------|---------|
+| `test/unit/core/custom-features.test.js` | `min` key 被 reset 后走内置消息而非自定义 `太短` |
+| `test/unit/error-message-interpolation.test.js` | `zh-CN` enum 消息在 reset 后丢失 |
+| `test/unit/label-translation.test.js` | `label.test_field` key 被 reset 清除 |
+
+### 修复方案
+
+将 `i18n-subdir.test.js` 的所有测试包裹在顶级 `describe('i18n 子目录合并')` 内，将 `beforeEach(Locale.reset)` 改为 `describe` 作用域内的 `afterEach(Locale.reset)`，确保状态清理严格限制在本文件的测试范围内，不泄漏到其他文件。
+
+---
+
+## 📊 测试统计
+
+| 指标 | v1.2.2 | v1.2.3 | 变化 |
+|------|--------|--------|------|
+| 通过 | 989 | **1003** | +14 |
+| 失败 | 14 | **0** | -14 ✅ |
+| 新增测试 | — | 20 (i18n-subdir) | +20 |
+
+---
+
+## 📁 变更文件
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `index.js` | 修改 | 新增 `loadLocalesFromDir` 内部函数，支持递归扫描 + 冲突检测 |
+| `index.d.ts` | 修改 | `I18nConfig` 类型扩展 + `strict?: boolean` 选项 |
+| `test/unit/i18n-subdir.test.js` | 新增 | 20 个单元测试（F1/F2/F3 + 向后兼容回归）|
+| `docs/add-custom-locale.md` | 修改 | 新增子目录多人协作章节 + Code 段划分建议 |
+
+---
+
+## 🔄 向后兼容性
+
+✅ **100% 向后兼容**，现有所有用法零改动：
+
+| 现有用法 | 兼容性 |
+|---------|--------|
+| `i18n: '/path'`（平铺目录）| ✅ 完全兼容（行为超集）|
+| `i18n: { 'zh-CN': {...} }` | ✅ 完全兼容 |
+| `strict` 未传 | ✅ 默认 false，现有行为零变化 |
+

package/docs/add-custom-locale.md

@@ -1,7 +1,7 @@
 # 添加自定义语言包指南
 
-**版本**: v1.0.9  
-**最后更新**: 2026-01-04
+**版本**: v1.2.3  
+**最后更新**: 2026-03-03
 
 ---
 
@@ -11,6 +11,94 @@
 
 ---
 
+## 🏗️ 多人协作：子目录拆分语言包（v1.2.3 新增）⭐
+
+> **适用场景**：多人/多模块开发，避免所有语言 key 堆在同一文件产生 Git 冲突和 code 码冲突。
+
+### 目录结构
+
+```bash
+project/
+├── locales/
+│   ├── core/               # 公共 code 段：1000-1999（框架层维护）
+│   │   ├── zh-CN.js
+│   │   └── en-US.js
+│   ├── account/            # 账户模块 code 段：10000-10999（开发者A）
+│   │   ├── zh-CN.js
+│   │   └── en-US.js
+│   ├── order/              # 订单模块 code 段：20000-20999（开发者B）
+│   │   ├── zh-CN.js
+│   │   └── en-US.js
+│   └── payment/            # 支付模块 code 段：30000-30999（开发者C）
+│       ├── zh-CN.js
+│       └── en-US.js
+└── app.js
+```
+
+### 每个模块独立维护自己的语言文件
+
+```javascript
+// locales/account/zh-CN.js — 开发者A 独立维护，互不干扰
+module.exports = {
+  'account.notFound': { code: 10001, message: '账户不存在' },
+  'account.locked':   { code: 10002, message: '账户已锁定' },
+};
+
+// locales/order/zh-CN.js — 开发者B 独立维护
+module.exports = {
+  'order.notFound': { code: 20001, message: '订单不存在' },
+  'order.notPaid':  { code: 20002, message: '订单未支付' },
+};
+```
+
+### 应用启动：一行配置，自动递归合并
+
+```javascript
+// app.js
+const { dsl, validate } = require('schema-dsl');
+const path = require('path');
+
+// 自动递归扫描 locales/ 下所有子目录，同语言文件合并为一个完整语言包
+dsl.config({
+  i18n: path.join(__dirname, 'locales')
+});
+```
+
+> - 子目录名（`account/`、`order/`）仅作为**模块组织层**，不影响最终语言 key 命名
+> - 加载顺序：按文件系统字母序递归扫描
+> - 同语言 key 出现重复时：默认打 `WARN` 日志，可开启严格模式阻断启动
+
+### 严格模式：key 冲突时阻断启动（推荐 CI 环境）
+
+```javascript
+dsl.config({
+  i18n: path.join(__dirname, 'locales'),
+  strict: true   // 同名 key 冲突时直接抛 Error，防止静默覆盖
+});
+
+// 冲突示例输出：
+// Error: [schema-dsl] i18n key 冲突 in locale 'zh-CN'
+//   冲突 key: account.notFound
+//   来源文件: /project/locales/account/zh-CN.js
+```
+
+### Code 段划分建议
+
+多人开发时建议在项目根目录维护一份 `locales/CODE-SEGMENTS.md`，约定各模块的 code 号段：
+
+| 模块 | code 范围 | 负责人 |
+|------|----------|--------|
+| core（公共） | 1000–1999 | 框架组 |
+| account | 10000–10999 | 开发者A |
+| order | 20000–20999 | 开发者B |
+| payment | 30000–30999 | 开发者C |
+
+> `CODE-SEGMENTS.md` / `CODE-SEGMENTS.js` 等非语言文件会被自动跳过，无需担心被误加载。
+
+---
+
+
+
 ## 🚀 快速开始
 
 ### 推荐方式：配置语言包目录（一次性加载所有语言）⭐