@kne/fastify-intl-admin 0.1.0 → 0.1.2

package/libs/controllers/lang-lib.js

@@ -1,5 +1,13 @@
 const fp = require('fastify-plugin');
+const pick = require('lodash/pick');
 const schema = require('../schema/lang-lib');
+const { empty } = require('../schema/response');
+
+const TAG = '国际化管理后台-语言库';
+const RUNTIME_TAG = '国际化-运行时';
+
+// save 只透传客户端可修改的字段，避免 userId、deletedAt 等未声明字段写进数据库
+const SAVE_FIELDS = ['id', 'target', 'status'];
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -10,8 +18,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib'),
       schema: {
+        tags: [TAG],
         summary: '语言库词条列表',
-        query: schema.listQuery
+        description: '分页查询语言词条，每条附带默认语言源文（sourceTarget）便于对照翻译',
+        query: schema.listQuery,
+        response: schema.listResponse
       }
     },
     async request => services.langLib.list(request.userInfo || {}, request.query)
@@ -22,7 +33,10 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib'),
       schema: {
-        summary: '语言库命名空间列表'
+        tags: [TAG],
+        summary: '语言库命名空间列表',
+        description: '列出语言库中已有词条的全部命名空间（去重）',
+        response: schema.namespacesResponse
       }
     },
     async request => services.langLib.namespaces(request.userInfo || {}, request.query)
@@ -33,8 +47,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '批量添加语言词条',
-        body: schema.addPackageBody
+        description: '为同一命名空间 + 编码一次创建多种语言的词条。手动模式用 targets 填译文，均直接审核通过；aiGenerate 模式由 generateTargets 生成非默认语言译文，默认语言词条直接通过，其他语言为待审核',
+        body: schema.addPackageBody,
+        response: schema.addPackageResponse
       }
     },
     async request => services.langLib.addPackage(request.userInfo || {}, request.body)
@@ -45,12 +62,15 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '保存语言词条',
-        body: schema.saveBody
+        description: '修改词条译文与状态；命名空间、编码、语言不可修改。译文变化时默认语言词条直接审核通过，其他语言重置为待审核并清空审核备注；未声明的字段（如 userId、reviewStatus）会被忽略',
+        body: schema.saveBody,
+        response: empty('保存成功，返回空对象')
       }
     },
     async request => {
-      await services.langLib.save(request.userInfo || {}, request.body);
+      await services.langLib.save(request.userInfo || {}, pick(request.body, SAVE_FIELDS));
       return {};
     }
   );
@@ -60,8 +80,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '删除语言词条',
-        body: schema.removeBody
+        description: '按 id 或 ids 删除词条，均不存在时报错',
+        body: schema.removeBody,
+        response: empty('删除成功，返回空对象')
       }
     },
     async request => {
@@ -75,8 +98,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '设置语言词条状态',
-        body: schema.setStatusBody
+        description: '按 id 或 ids 批量启用或禁用词条；禁用的词条不出现在运行时语言包中',
+        body: schema.setStatusBody,
+        response: empty('设置成功，返回空对象')
       }
     },
     async request => {
@@ -90,8 +116,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '审核语言词条',
-        body: schema.reviewBody
+        description: '按 id 或 ids 批量审核词条；只有审核通过的词条会出现在运行时语言包中',
+        body: schema.reviewBody,
+        response: empty('审核成功，返回空对象')
       }
     },
     async request => {
@@ -105,8 +134,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '重新生成待审核词条译文',
-        body: schema.regenerateBody
+        description: '对待审核或已通过的非默认语言词条，按默认语言源文重新调用 generateTargets 生成译文，结果重置为待审核；未配置 generateTargets、缺少源文或包含默认语言词条时报错',
+        body: schema.regenerateBody,
+        response: empty('重新生成成功，返回空对象')
       }
     },
     async request => {
@@ -120,8 +152,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '复制词条到新命名空间',
-        body: schema.copyToNamespaceBody
+        description: '把选中的词条（含译文、审核状态、启用状态）复制到目标命名空间；目标下已存在同编码同语言的词条会被跳过，全部跳过时报错',
+        body: schema.copyToNamespaceBody,
+        response: schema.copyToNamespaceResponse
       }
     },
     async request => services.langLib.copyToNamespace(request.userInfo || {}, request.body)
@@ -132,8 +167,11 @@ module.exports = fp(async (fastify, options) => {
     {
       // 运行时语言包：允许未登录访问
       schema: {
+        tags: [RUNTIME_TAG],
         summary: '运行时语言包（扁平 code→文案，无需登录）',
-        query: schema.messagesQuery
+        description: '前端运行时拉取语言包，返回 { code: 译文 }，可直接给 @kne/react-intl 使用；只包含已启用且审核通过的词条，无需登录',
+        query: schema.messagesQuery,
+        response: schema.messagesResponse
       }
     },
     async request => services.langLib.messages(request.userInfo || {}, request.query)
@@ -144,8 +182,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib'),
       schema: {
+        tags: [TAG],
         summary: '导出语言库 i18n 文件',
-        query: schema.exportQuery
+        description: '按命名空间 + 语言分组导出 i18n 文件内容（JSON 返回文件名与正文，不是文件下载），包含全部状态的词条',
+        query: schema.exportQuery,
+        response: schema.exportResponse
       }
     },
     async request => services.langLib.exportI18n(request.userInfo || {}, request.query)
@@ -156,8 +197,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langLib:manage'),
       schema: {
+        tags: [TAG],
         summary: '导入语言库 i18n 文件',
-        body: schema.importBody
+        description: '导入一个或多个 i18n 文件；已存在的词条覆盖译文，新词条直接创建，导入的词条均为启用且审核通过',
+        body: schema.importBody,
+        response: schema.importResponse
       }
     },
     async request => services.langLib.importI18n(request.userInfo || {}, request.body)

package/libs/controllers/lang-type.js

@@ -1,5 +1,12 @@
 const fp = require('fastify-plugin');
+const pick = require('lodash/pick');
 const schema = require('../schema/lang-type');
+const { empty } = require('../schema/response');
+
+const TAG = '国际化管理后台-语言类型';
+
+// save 只透传客户端可修改的字段，避免 userId、deletedAt 等未声明字段写进数据库
+const SAVE_FIELDS = ['id', 'name', 'params', 'description', 'status'];
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -10,8 +17,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType'),
       schema: {
+        tags: [TAG],
         summary: '语言类型列表',
-        query: schema.listQuery
+        description: '分页查询语言类型，附带每种语言的词条数与默认语言词条数，可用于展示翻译完成度',
+        query: schema.listQuery,
+        response: schema.listResponse
       }
     },
     async request => services.langType.list(request.userInfo || {}, request.query)
@@ -22,8 +32,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '创建语言类型',
-        body: schema.createBody
+        description: '新增一种语言；语言编码唯一且创建后不可修改，系统中第一条语言自动成为默认语言',
+        body: schema.createBody,
+        response: schema.createResponse
       }
     },
     async request => services.langType.create(request.userInfo || {}, request.body)
@@ -34,12 +47,15 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '保存语言类型',
-        body: schema.saveBody
+        description: '修改语言名称、参数提示、描述、状态；语言编码、默认标记和排序不能通过此接口修改，未声明的字段（如 userId）会被忽略',
+        body: schema.saveBody,
+        response: empty('保存成功，返回空对象')
       }
     },
     async request => {
-      await services.langType.save(request.userInfo || {}, request.body);
+      await services.langType.save(request.userInfo || {}, pick(request.body, SAVE_FIELDS));
       return {};
     }
   );
@@ -49,8 +65,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '删除语言类型',
-        body: schema.removeBody
+        description: '删除语言类型；语言库中仍有该语言的词条时报错。删除的是默认语言时，最早创建的剩余语言自动成为默认',
+        body: schema.removeBody,
+        response: empty('删除成功，返回空对象')
       }
     },
     async request => {
@@ -64,8 +83,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '设置语言类型状态',
-        body: schema.setStatusBody
+        description: '启用或禁用语言；禁用的语言不能新增词条，也不能补译',
+        body: schema.setStatusBody,
+        response: empty('设置成功，返回空对象')
       }
     },
     async request => {
@@ -79,8 +101,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '设置默认语言',
-        body: schema.setDefaultBody
+        description: '把指定语言设为默认语言，并清除其他语言的默认标记；默认语言是 AI 翻译与补译的源语言',
+        body: schema.setDefaultBody,
+        response: empty('设置成功，返回空对象')
       }
     },
     async request => {
@@ -94,8 +119,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '语言类型上移/下移',
-        body: schema.moveBody
+        description: '与相邻语言交换排序位置；已在首位上移或末位下移时不做修改',
+        body: schema.moveBody,
+        response: schema.moveResponse
       }
     },
     async request => services.langType.move(request.userInfo || {}, request.body)
@@ -106,8 +134,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: getAuth('langType:manage'),
       schema: {
+        tags: [TAG],
         summary: '补译目标语言缺失词条',
-        body: schema.translateRemainingBody
+        description: '为目标语言补齐默认语言已有但目标语言缺失的词条：非 global 命名空间优先复用 global 同编码的目标语言译文（直接审核通过），其余一次性调用 generateTargets 生成译文（待审核）。未配置 generateTargets 且需要 AI 翻译时报错',
+        body: schema.translateRemainingBody,
+        response: schema.translateRemainingResponse
       }
     },
     async request => services.langType.translateRemaining(request.userInfo || {}, request.body)

package/libs/schema/lang-lib.js

@@ -1,13 +1,24 @@
+const { obj, arr, str, num, success, langLib, langLibListItem, importResultFields } = require('./response');
+
+const ID = { description: '单个词条 ID；与 ids 二选一，同时传时以非空的 ids 为准' };
+const IDS = {
+  type: 'array',
+  items: { description: '词条 ID' },
+  description: '批量操作的词条 ID 列表；非空时忽略 id'
+};
+
 const listQuery = {
   type: 'object',
   properties: {
-    filter: { type: 'object', default: {} },
-    keyword: { type: 'string' },
-    namespace: { type: 'string' },
-    locale: { type: 'string' },
-    reviewStatus: { type: 'string', enum: ['approved', 'pending', 'rejected'] },
-    perPage: { type: 'number', default: 20 },
-    currentPage: { type: 'number', default: 1 }
+    filter: { type: 'object', default: {}, description: '筛选条件对象，可含 keyword、namespace、locale、reviewStatus、status、code；与顶层同名字段同时传时以 filter 为准' },
+    keyword: { type: 'string', description: '关键字，模糊匹配命名空间、词条编码、译文' },
+    namespace: { type: 'string', description: '按命名空间精确筛选' },
+    locale: { type: 'string', description: '按语言编码精确筛选' },
+    reviewStatus: { type: 'string', enum: ['approved', 'pending', 'rejected'], description: '按审核状态筛选：approved 已通过，pending 待审核，rejected 已驳回' },
+    status: { description: '按状态筛选：open 启用，closed 禁用' },
+    code: { description: '按词条编码精确筛选' },
+    perPage: { type: 'number', default: 20, description: '每页条数，非正数按 20 处理' },
+    currentPage: { type: 'number', default: 1, description: '页码，从 1 开始，非正数按 1 处理' }
   }
 };
 
@@ -15,17 +26,22 @@ const addPackageBody = {
   type: 'object',
   required: ['namespace', 'code', 'locales'],
   properties: {
-    namespace: { type: 'string' },
-    code: { type: 'string' },
+    namespace: { type: 'string', description: '命名空间，去除首尾空白后不能为空' },
+    code: { type: 'string', description: '词条编码，去除首尾空白后不能为空' },
     locales: {
       type: 'array',
       minItems: 1,
-      items: { type: 'string' }
+      items: { type: 'string', description: '语言编码' },
+      description: '要创建词条的语言编码列表，须均为已启用的语言，且同命名空间同编码下不能已存在'
     },
-    aiGenerate: { type: 'boolean', default: false },
-    sourceTarget: { type: 'string' },
-    defaultLocale: { type: 'string' },
-    targets: { type: 'object', additionalProperties: { type: 'string' } }
+    aiGenerate: { type: 'boolean', default: false, description: '是否调用 generateTargets 用 AI 生成非默认语言译文；AI 生成的词条为待审核' },
+    sourceTarget: { type: 'string', description: '默认语言源文；aiGenerate 为 true 时必填，作为默认语言译文并作为 AI 翻译源' },
+    defaultLocale: { type: 'string', description: '默认语言编码；不传使用系统默认语言' },
+    targets: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: '手动填写的译文，键为语言编码、值为译文；aiGenerate 为 true 时忽略'
+    }
   }
 };
 
@@ -33,23 +49,20 @@ const saveBody = {
   type: 'object',
   required: ['id'],
   properties: {
-    id: {},
-    target: { type: 'string' },
-    namespace: { type: 'string' },
-    code: { type: 'string' },
-    locale: {},
-    status: { type: 'string', enum: ['open', 'closed'] }
+    id: { description: '词条 ID' },
+    target: { type: 'string', description: '译文；不传保持原值。译文变化时默认语言词条直接审核通过，其他语言重置为待审核' },
+    namespace: { type: 'string', description: '命名空间，不可修改，传入会被忽略' },
+    code: { type: 'string', description: '词条编码，不可修改，传入会被忽略' },
+    locale: { description: '语言编码，不可修改，传入会被忽略' },
+    status: { type: 'string', enum: ['open', 'closed'], description: '状态：open 启用，closed 禁用；不传保持原值' }
   }
 };
 
 const removeBody = {
   type: 'object',
   properties: {
-    id: {},
-    ids: {
-      type: 'array',
-      items: {}
-    }
+    id: ID,
+    ids: IDS
   }
 };
 
@@ -57,12 +70,9 @@ const setStatusBody = {
   type: 'object',
   required: ['status'],
   properties: {
-    id: {},
-    ids: {
-      type: 'array',
-      items: {}
-    },
-    status: { type: 'string', enum: ['open', 'closed'] }
+    id: ID,
+    ids: IDS,
+    status: { type: 'string', enum: ['open', 'closed'], description: '目标状态：open 启用，closed 禁用' }
   }
 };
 
@@ -70,24 +80,18 @@ const reviewBody = {
   type: 'object',
   required: ['reviewStatus'],
   properties: {
-    id: {},
-    ids: {
-      type: 'array',
-      items: {}
-    },
-    reviewStatus: { type: 'string', enum: ['approved', 'rejected'] },
-    reviewRemark: { type: 'string', maxLength: 500 }
+    id: ID,
+    ids: IDS,
+    reviewStatus: { type: 'string', enum: ['approved', 'rejected'], description: '审核结果：approved 通过，rejected 驳回' },
+    reviewRemark: { type: 'string', maxLength: 500, description: '审核备注；不传保持原备注' }
   }
 };
 
 const regenerateBody = {
   type: 'object',
   properties: {
-    id: {},
-    ids: {
-      type: 'array',
-      items: {}
-    }
+    id: ID,
+    ids: IDS
   }
 };
 
@@ -95,12 +99,9 @@ const copyToNamespaceBody = {
   type: 'object',
   required: ['namespace'],
   properties: {
-    namespace: { type: 'string' },
-    id: {},
-    ids: {
-      type: 'array',
-      items: {}
-    }
+    namespace: { type: 'string', description: '目标命名空间；与源命名空间相同或目标下已存在同编码同语言的词条会被跳过' },
+    id: ID,
+    ids: IDS
   }
 };
 
@@ -108,40 +109,111 @@ const messagesQuery = {
   type: 'object',
   required: ['locale'],
   properties: {
-    locale: { type: 'string' },
-    namespace: { type: 'string', default: 'global' }
+    locale: { type: 'string', description: '语言编码，如 zh-CN' },
+    namespace: { type: 'string', default: 'global', description: '命名空间，默认 global' }
   }
 };
 
 const exportQuery = {
   type: 'object',
   properties: {
-    namespace: { type: 'string' }
+    namespace: { type: 'string', description: '只导出该命名空间；不传导出全部' }
   }
 };
 
 const importFileItem = {
   type: 'object',
   required: ['filename', 'content'],
+  description: 'i18n 文件',
   properties: {
-    filename: { type: 'string' },
-    content: { type: 'string' }
+    filename: { type: 'string', description: '文件名：namespace.locale.i18n，或 locale.i18n（命名空间为 global）' },
+    content: { type: 'string', description: '文件内容，每行 code="target"，译文支持 \\" 与 \\\\ 转义，空行忽略' }
   }
 };
 
 const importBody = {
   type: 'object',
   properties: {
-    filename: { type: 'string' },
-    content: { type: 'string' },
+    filename: { type: 'string', description: '单文件导入的文件名，格式同 files[].filename；传了非空 files 时忽略' },
+    content: { type: 'string', description: '单文件导入的文件内容，格式同 files[].content' },
     files: {
       type: 'array',
       minItems: 1,
-      items: importFileItem
+      items: importFileItem,
+      description: '批量导入的文件列表'
     }
   }
 };
 
+const listResponse = success('语言词条分页列表，按命名空间、编码、语言升序', {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    pageData: arr('当前页词条', langLibListItem),
+    totalCount: num('符合条件的词条总数')
+  }
+});
+
+const namespacesResponse = success('全部命名空间，global 排在最前，其余按名称排序', {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    pageData: arr('命名空间列表', obj('命名空间', { namespace: str('命名空间名称') })),
+    totalCount: num('命名空间数量')
+  }
+});
+
+const addPackageResponse = success('新建的词条列表，每种语言一条', arr(undefined, langLib));
+
+const copyToNamespaceResponse = success(
+  '复制结果统计',
+  obj(undefined, {
+    createdCount: num('新建的词条数'),
+    skippedCount: num('跳过的词条数（源命名空间与目标相同，或目标下已存在）')
+  })
+);
+
+const messagesResponse = success('扁平语言包：键为词条编码，值为译文；只包含已启用且审核通过的词条', {
+  type: 'object',
+  additionalProperties: true
+});
+
+const exportResponse = success(
+  '导出的 i18n 文件列表，按命名空间 + 语言分组',
+  obj(undefined, {
+    pageData: arr(
+      'i18n 文件',
+      obj('i18n 文件', {
+        filename: str('文件名：namespace.locale.i18n'),
+        content: str('文件内容，每行 code="target"')
+      })
+    )
+  })
+);
+
+const importResponse = success(
+  '导入结果统计；已存在的词条会被覆盖并直接审核通过',
+  obj(
+    undefined,
+    Object.assign({}, importResultFields, {
+      pageData: arr(
+        '每个文件的导入结果',
+        obj(
+          '单个文件导入结果',
+          Object.assign(
+            {
+              filename: str('文件名'),
+              namespace: str('解析出的命名空间'),
+              locale: str('解析出的语言编码')
+            },
+            importResultFields
+          )
+        )
+      )
+    })
+  )
+);
+
 module.exports = {
   listQuery,
   addPackageBody,
@@ -153,5 +225,12 @@ module.exports = {
   copyToNamespaceBody,
   messagesQuery,
   exportQuery,
-  importBody
+  importBody,
+  listResponse,
+  namespacesResponse,
+  addPackageResponse,
+  copyToNamespaceResponse,
+  messagesResponse,
+  exportResponse,
+  importResponse
 };

package/libs/schema/lang-type.js

@@ -1,12 +1,17 @@
+const { obj, arr, num, bool, success, langType, langTypeListItem } = require('./response');
+
+const ID = { description: '语言类型 ID' };
+
 const listQuery = {
   type: 'object',
   properties: {
-    filter: { type: 'object', default: {} },
-    keyword: { type: 'string' },
-    namespace: { type: 'string' },
-    isDefault: { type: 'boolean' },
-    perPage: { type: 'number', default: 20 },
-    currentPage: { type: 'number', default: 1 }
+    filter: { type: 'object', default: {}, description: '筛选条件对象，可含 keyword、status、isDefault、namespace；与顶层同名字段同时传时以 filter 为准' },
+    keyword: { type: 'string', description: '关键字，模糊匹配语言名称、编码、描述' },
+    status: { description: '按状态筛选：open 启用，closed 禁用' },
+    namespace: { type: 'string', description: '命名空间；只影响 entryCount / defaultEntryCount 的统计范围，不过滤语言类型' },
+    isDefault: { type: 'boolean', description: '按是否默认语言筛选' },
+    perPage: { type: 'number', default: 20, description: '每页条数，非正数按 20 处理' },
+    currentPage: { type: 'number', default: 1, description: '页码，从 1 开始，非正数按 1 处理' }
   }
 };
 
@@ -14,11 +19,11 @@ const createBody = {
   type: 'object',
   required: ['name', 'code'],
   properties: {
-    name: { type: 'string' },
-    code: { type: 'string' },
-    params: { type: 'string' },
-    description: { type: 'string' },
-    status: { type: 'string', enum: ['open', 'closed'] }
+    name: { type: 'string', description: '语言名称，如 中文（简体）' },
+    code: { type: 'string', description: '语言编码，如 zh-CN；去除首尾空白后不能为空且不能与已有语言重复，创建后不可修改' },
+    params: { type: 'string', description: '翻译参数提示，供 AI 翻译时参考' },
+    description: { type: 'string', description: '描述' },
+    status: { type: 'string', enum: ['open', 'closed'], description: '状态：open 启用，closed 禁用；不传为 open' }
   }
 };
 
@@ -26,11 +31,11 @@ const saveBody = {
   type: 'object',
   required: ['id'],
   properties: {
-    id: {},
-    name: { type: 'string' },
-    params: { type: 'string' },
-    description: { type: 'string' },
-    status: { type: 'string', enum: ['open', 'closed'] }
+    id: ID,
+    name: { type: 'string', description: '语言名称；不传保持原值' },
+    params: { type: 'string', description: '翻译参数提示；不传保持原值' },
+    description: { type: 'string', description: '描述；不传保持原值' },
+    status: { type: 'string', enum: ['open', 'closed'], description: '状态：open 启用，closed 禁用；不传保持原值' }
   }
 };
 
@@ -38,7 +43,7 @@ const removeBody = {
   type: 'object',
   required: ['id'],
   properties: {
-    id: {}
+    id: { description: '语言类型 ID；仍有关联词条时不能删除，删除默认语言后最早创建的语言自动成为默认' }
   }
 };
 
@@ -46,8 +51,8 @@ const setStatusBody = {
   type: 'object',
   required: ['id', 'status'],
   properties: {
-    id: {},
-    status: { type: 'string', enum: ['open', 'closed'] }
+    id: ID,
+    status: { type: 'string', enum: ['open', 'closed'], description: '目标状态：open 启用，closed 禁用' }
   }
 };
 
@@ -55,7 +60,7 @@ const setDefaultBody = {
   type: 'object',
   required: ['id'],
   properties: {
-    id: {}
+    id: { description: '要设为默认的语言类型 ID；其他语言的默认标记会被清除' }
   }
 };
 
@@ -63,8 +68,8 @@ const moveBody = {
   type: 'object',
   required: ['id', 'direction'],
   properties: {
-    id: {},
-    direction: { type: 'string', enum: ['up', 'down'] }
+    id: ID,
+    direction: { type: 'string', enum: ['up', 'down'], description: '移动方向：up 上移，down 下移（与相邻项交换排序）' }
   }
 };
 
@@ -72,12 +77,37 @@ const translateRemainingBody = {
   type: 'object',
   required: ['id'],
   properties: {
-    id: {},
-    namespace: { type: 'string' },
-    limit: { type: 'integer', minimum: 1, maximum: 500 }
+    id: { description: '目标语言类型 ID，须为已启用的非默认语言' },
+    namespace: { type: 'string', description: '只补译该命名空间的缺失词条；不传补译全部命名空间' },
+    limit: { type: 'integer', minimum: 1, maximum: 500, description: '本次最多处理的词条数，用于分批补译；不传一次处理全部' }
   }
 };
 
+const listResponse = success('语言类型分页列表，按排序、创建时间升序', {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    pageData: arr('当前页语言类型', langTypeListItem),
+    totalCount: num('符合条件的语言类型总数')
+  }
+});
+
+const createResponse = success('新建的语言类型；系统第一条语言自动设为默认，新建语言排在最后', langType);
+
+const moveResponse = success('移动结果', obj(undefined, { moved: bool('是否发生了移动；已在首位上移或末位下移时为 false') }));
+
+const translateRemainingResponse = success(
+  '补译结果统计',
+  obj(undefined, {
+    createdCount: num('本次新建的目标语言词条数'),
+    copiedCount: num('非 global 命名空间词条直接复用 global 同编码译文的条数（直接审核通过）'),
+    generatedCount: num('调用 generateTargets 生成译文的条数（待审核）'),
+    remainingCount: num('因 limit 限制本次未处理、仍可继续补译的条数'),
+    remainingSkipped: num('默认语言源文为空而跳过的缺失词条数'),
+    totalProcessable: num('本次调用前可补译的缺失词条总数')
+  })
+);
+
 module.exports = {
   listQuery,
   createBody,
@@ -86,5 +116,9 @@ module.exports = {
   setStatusBody,
   setDefaultBody,
   moveBody,
-  translateRemainingBody
+  translateRemainingBody,
+  listResponse,
+  createResponse,
+  moveResponse,
+  translateRemainingResponse
 };

package/libs/schema/response.js

@@ -0,0 +1,92 @@
+// 响应 schema 只用于 OpenAPI 文档：字段可空、对象允许额外字段，避免序列化改变实际输出
+const str = description => ({ type: 'string', nullable: true, description });
+const num = description => ({ type: 'number', nullable: true, description });
+const bool = description => ({ type: 'boolean', nullable: true, description });
+// ID（BIGINT）、外键与日期可能是 number / string / Date，不声明类型，原样输出
+const any = description => ({ description });
+const obj = (description, properties) => ({ type: 'object', nullable: true, additionalProperties: true, description, properties });
+const arr = (description, items) => ({ type: 'array', items, description });
+
+const success = (description, schema) => ({ 200: Object.assign({}, schema || { type: 'object', additionalProperties: true }, { description }) });
+const empty = description => success(description || '操作成功，返回空对象');
+
+const STATUS = '状态：open 启用，closed 禁用';
+const REVIEW_STATUS = '审核状态：approved 已通过，pending 待审核，rejected 已驳回';
+
+const createdUser = obj('添加人（账号插件的用户记录）');
+
+const langTypeFields = {
+  id: any('语言类型 ID'),
+  name: str('语言名称'),
+  code: str('语言编码，如 zh-CN'),
+  params: str('翻译参数提示'),
+  description: str('描述'),
+  status: str(STATUS),
+  isDefault: bool('是否为默认语言（全局唯一）'),
+  sort: num('排序，越小越靠前'),
+  userId: any('添加人用户 ID'),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间'),
+  deletedAt: any('删除时间，未删除为 null')
+};
+
+const langType = obj('语言类型', langTypeFields);
+
+const langTypeListItem = obj(
+  '语言类型（含词条统计）',
+  Object.assign({}, langTypeFields, {
+    createdUser,
+    entryCount: num('该语言的词条数（传 namespace 时只统计该命名空间）'),
+    defaultEntryCount: num('默认语言的词条数（统计口径同 entryCount），用于计算翻译完成度')
+  })
+);
+
+const langLibFields = {
+  id: any('词条 ID'),
+  namespace: str('命名空间'),
+  code: str('词条编码'),
+  locale: str('语言编码'),
+  target: str('译文'),
+  reviewStatus: str(REVIEW_STATUS),
+  reviewRemark: str('审核备注'),
+  status: str(STATUS),
+  userId: any('添加人用户 ID'),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间'),
+  deletedAt: any('删除时间，未删除为 null')
+};
+
+const langLib = obj('语言词条', langLibFields);
+
+const langLibListItem = obj(
+  '语言词条（含默认语言源文）',
+  Object.assign({}, langLibFields, {
+    createdUser,
+    sourceTarget: str('同命名空间、同编码的默认语言译文；当前词条即默认语言时为自身译文，未设置默认语言或无源文时为空字符串'),
+    defaultLocale: str('当前默认语言编码，未设置时为空字符串')
+  })
+);
+
+const importResultFields = {
+  createdCount: num('新增词条数'),
+  updatedCount: num('覆盖更新的已有词条数'),
+  skippedCount: num('跳过的词条数')
+};
+
+module.exports = {
+  str,
+  num,
+  bool,
+  any,
+  obj,
+  arr,
+  success,
+  empty,
+  STATUS,
+  REVIEW_STATUS,
+  langType,
+  langTypeListItem,
+  langLib,
+  langLibListItem,
+  importResultFields
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-intl-admin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Fastify 业务插件：国际化语言类型与语言库管理（lang-type / lang-lib）",
   "main": "index.js",
   "scripts": {