第 06 章

术语库

术语增删改查、多维检索、分类统计、CSV / Excel 批量导入与导出，以及术语对翻译质量与润色的增强机制。

6.1 术语库在翻译链路中的作用

建库通过本章接口维护「源术语 → 目标术语」映射（含分类 / 领域 / 备注），按用户隔离（createdBy 取当前登录用户）。
翻译时命中文本 / 文档 / 对话翻译开启 useTerminology 后，RAG 阶段按语言对与领域检索术语，命中项注入引擎提示词强制对齐译法；响应中 usedTerminology=true、terminologyCount 为命中条数。
润色时强制对齐 POST /api/translation/polish 返回 termHits 命中明细与 appliedTermsCount 应用数。
批量迁移 CSV / Excel 批量导入已有术语资产；导出用于备份或迁移到其他系统。

术语分类（category 合法值，正则校验）

TECHNOLOGY 科技 BUSINESS 商务 MEDICAL 医疗 LEGAL 法律 FINANCE 金融 EDUCATION 教育 SCIENCE 科学 GENERAL 通用

创建时缺省分类自动填 GENERAL；未提供的其他字段填空字符串。

6.2 接口总览（前缀 /api/terminology）

GET/api/terminology/list术语分页查询（多维筛选）

POST/api/terminology/create新增术语

PUT/api/terminology/{id}更新术语

DELETE/api/terminology/{id}删除术语

GET/api/terminology/stats术语统计

POST/api/terminology/import批量导入（CSV / xlsx）

GET/api/terminology/export?format=导出（csv / excel）

6.3 接口详情

GET

/api/terminology/list

分页查询当前登录用户的术语（createdBy 由服务端从 UserContext 注入，不受客户端控制）。

Query 参数

参数	必填	说明
`keyword`	可选	术语关键词（源 / 目标模糊匹配）
`sourceLanguage / targetLanguage`	可选	语言代码过滤
`category`	可选	分类过滤（8 个合法值之一）
`domain`	可选	领域过滤
`page`	可选	默认 0（0 起始）
`size`	可选	默认 10

响应 data（TerminologyListResponse）

{
  "data": [ { "id": 1, "sourceTerm": "AI", "targetTerm": "人工智能",
              "sourceLanguage": "en", "targetLanguage": "zh",
              "category": "TECHNOLOGY", "domain": "科技",
              "definition": "人工智能缩写", "context": "", "createdBy": "1" } ],
  "page": 0, "size": 10, "totalPages": 3, "totalElements": 25
}

POST

/api/terminology/create

新增一条术语。

请求体（TerminologyCreateRequest）

字段	类型	必填	说明
`sourceTerm`	String	必填	源术语
`targetTerm`	String	必填	目标术语（期望译法）
`sourceLanguage`	String	必填	源语言代码
`targetLanguage`	String	必填	目标语言代码
`category`	String	可选	正则限定 8 个分类之一；缺省填 `GENERAL`
`domain`	String	可选	领域标签；缺省填空串
`definition`	String	可选	术语释义；缺省填空串
`context`	String	可选	使用语境示例；缺省填空串
`createdBy`	String	忽略	服务端强制以当前登录用户覆盖

PUT

/api/terminology/{id}

更新术语内容（TerminologyUpdateRequest：sourceTerm / targetTerm / category / domain / definition）。context 字段强制清空，不接受更新。

DELETE

/api/terminology/{id}

删除一条术语（校验归属当前用户）。

GET

/api/terminology/stats

当前用户术语库统计。

响应 data（TerminologyStatsResponse）

{
  "totalEntries": 25,                    // 总条数（别名 totalTerms）
  "categoryCounts": { "TECHNOLOGY": 10, "GENERAL": 8, ... },   // 按分类
  "languagePairCounts": { "en-zh": 18, "zh-ja": 7 },            // 按语言对
  "categoryCount": 4                     // 涉及分类数（别名 categoryCount）
}

POST

/api/terminology/import

批量导入术语。上传 CSV 或 xlsx 文件，逐行处理并逐行报告失败原因；重复术语计数但不会重复插入。

请求

multipart/form-data 上传 file。列顺序固定为：

源术语, 目标术语, 源语言, 目标语言, 分类, 领域, 备注

响应 data（TerminologyImportResponse）

{
  "successCount": 48, "failureCount": 2, "totalCount": 50,
  "duplicateCount": 3, "newCount": 45, "updateCount": 0,
  "processingTime": 820,                       // 毫秒
  "importTime": "2026-09-06 10:30:00",
  "status": "COMPLETED",
  "fileName": "术语表.xlsx", "fileSize": 20480,
  "errors": [
    { "rowNumber": 12, "errorMessage": "分类不合法",
      "sourceTerm": "cloud", "targetTerm": "云" }
  ]
}

GET

/api/terminology/export?format=csv

导出当前用户全部术语。响应为文件流（不经过统一包装）。

Query 参数

参数	必填	说明
`format`	必填	`csv` 或 `excel`；文件名 `terminology_{yyyy-MM-dd}.csv / .xlsx`

6.4 调用示例

# 新增术语
curl -X POST http://localhost:8090/api/terminology/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceTerm":"AI","targetTerm":"人工智能","sourceLanguage":"en","targetLanguage":"zh","category":"TECHNOLOGY"}'

# 导入术语文件
curl -X POST http://localhost:8090/api/terminology/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./术语表.csv"

# 导出 Excel
curl -o terminology.xlsx "http://localhost:8090/api/terminology/export?format=excel" \
  -H "Authorization: Bearer $TOKEN"