# 统一招聘行业目录对接说明

适用对象：前后端联调工程师。范围：目录、企业资料、岗位筛选、求职意向、推荐及技能映射；不包含前端实现、线上数据回填或发布授权。

本批为本地后端改动，不能据此认为当前线上已支持。最终验证状态以本批验收报告为准。

## 目录及字段参考

唯一主目录为 `catalog/industries-v1.json`，版本 `recruitment-industry-v1`。这是项目招聘场景目录，不宣称是国家行业标准。共18个大类、78个细分类；目录版本和编码稳定，调整展示名称不改变编码。新增、停用或拆分类别需单独审核兼容策略，不复用已发出的编码。

大类覆盖互联网/信息技术、金融、制造、汽车、消费品与零售、医疗健康、教育、建筑与房地产、物流与交通、能源、专业服务、生活服务、文化传媒、农林牧渔、公共与社会服务、通信、旅游与住宿、环保。

`GET /api/v1/jobs/industry-catalog?scope=ALL` 无需登录，返回标准 `ApiResponse`。`data`：

```json
{
  "version": "recruitment-industry-v1",
  "scope": "ALL",
  "countScope": "GLOBAL_PUBLISHED_NOT_FILTERED_BY_CITY",
  "items": [
    {"code":"FINANCE","parentCode":null,"name":"金融","level":1,"publishedJobCount":2,"skillIndustryCode":null},
    {"code":"FINANCE_BANKING","parentCode":"FINANCE","name":"银行","level":2,"publishedJobCount":2,"skillIndustryCode":null}
  ],
  "unmappedPublishedJobCount": 1
}
```

示例仅演示部分条目和计数，不是实际环境数据。全局序列化可能省略空值字段，前端需兼容 `null` 和字段缺省。例如已有金融技能集时 FINANCE 的 `skillIndustryCode` 是 FINANCE。

- `ALL`：完整两级目录，包括零岗位类别。企业资料和求职意向必须用此目录。
- `WITH_JOBS`：只返回当前存在已发布岗位的类别及其大类，不能作为可填写的完整行业范围。
- `publishedJobCount` 为全站 PUBLISHED 岗位数，不叠加当前城市等筛选。大类包含自身和细分类，父子数不可相加当作岗位总数。
- `unmappedPublishedJobCount`：无法可靠映射行业的已发布岗位数；不强塞进“其他”。
- 未知 scope 返回400；不发送中文“不限”作为编码。

## 企业、岗位及求职意向接入

### 企业

企业创建、更新、企业注册内的 `company` 对象可传：

```json
{"industryCode":"FINANCE_BANKING"}
```

旧 `industry` 名称参数保留。若同时传编码和名称，名称必须精确映射到该编码，否则400；不做模糊猜测。更新两字段都缺省表示保留；`industryCode:""` 且名称缺省/空白表示清空。未知非空编码400。

企业自查、公开企业摘要、岗位列表/详情内企业摘要增加 `industryCode`。已存编码时展示目录现行名称；旧数据能精确映射时可在读取时返回编码，但不写回数据库；未知旧名称原样展示，编码为空或缺省。

岗位行业继承所属企业，不新增岗位独立行业字段。企业行业修改会影响其岗位的行业筛选与计数。不要从岗位标题推导行业。

### 岗位筛选

`GET /api/v1/jobs/search?industryCode=FINANCE,MANUFACTURING`。

最多20个去重编码、每项64字符、整个参数最多4096字符。大类包含全部细分类，同维度OR，与城市/学历等维度AND。未知编码或空分隔项400。编码匹配优先用企业已存编码；旧数据只使用精确别名匹配，未知数据仍可在不限定行业时看到。

旧 `industry` 名称精确筛选语义不变；新旧参数同时提供时AND，建议新前端只用 `industryCode`。旧 `/jobs/filters.industries` 仍是有岗名称选项，不是完整目录。

### 求职意向

`PUT /api/v1/profile/me/preferences` 和在线简历 `content.jobIntention` 增加 `preferredIndustryCodes` 字符串数组，最多20项。例如：

```json
{"preferredIndustryCodes":["FINANCE_BANKING","INTERNET"],"revision":7}
```

偏好局部更新中编码和旧名称都缺省则保留，只传编码 `[]` 明确清空。只传旧名称会保留原文，并生成可确定的编码；同时传两组选择时，可确定的编码集合必须一致，否则400且不部分写入。两组同时带有待确认旧名称时保留未知名称，使 GET→编辑其他字段→保存不会丢失历史内容；要连同这些未知名称一起删除，请把两组数组都置为 `[]`。

偏好读取返回 `preferredIndustryCodes`，并以 `unmappedPreferredIndustries` 列出未知旧名称；旧名称列表仍保留。在线简历也返回编码数组；不能静默删掉旧名称。旧客户端整份保存没有编码字段时根据名称做确定映射，保持兼容。

原有 revision 并发保护不变：已有在线简历的旧偏好更新必须携带最新 revision，冲突仍409/6002。此功能不绕开版本校验。

## 推荐与技能映射

推荐行业引用同一主目录，数据库 `job_recommendation_taxonomies` 的 INDUSTRY 行是兼容投影，非第二套自主维护的字典。旧六个编码保留；新增编码由 V65 提供。推荐偏好按编码和大类展开参与原有偏好评分，不改变城市/薪资硬筛选规则。

岗位推荐和人才发现使用同一评分映射，同时归一化偏好与目标的旧别名；未知旧偏好保留为未匹配条件，不能静默移除其评分权重。岗位匹配诊断的行业参考项读取岗位所属企业的编码，不再用岗位描述猜行业；原有10分参考权重与城市/薪资门槛不变。个人数据导出同时携带已存的行业编码。

行业与职位类别独立。FINANCE_BANKING（银行）可以搭配 IT_SOFTWARE（软件职位类别）；JOB_FAMILY 不再返回行业父级以限制选择。职位类别本身仍需已启用、类型正确。推荐配置里的行业需与业务实际保持一致，不能根据职位类别推断。

技能仍使用现有 `industryId + occupationId` 数据集查询方式，不把行业编码当数字ID。目录条目的 `skillIndustryCode` 仅在数据库确有对应技能集时提供；当前已有互联网、金融、教育数据，其余行业不虚构词云或学习路径。

技能的 occupation 与 industry 绑定表示现有数据集范围，不是“该行业只能招聘这些职业”的业务限制。前端没有可用技能映射时应明确展示“该行业技能数据暂未覆盖”，不能把它隐藏出行业选择器，也不能随意套用互联网技能。

## 旧数据待确认与验收限制

V65 仅新增企业编码/偏好编码列、索引和新增推荐行业条目，不批量回填或改写旧名称，不修改历史迁移。旧名称仅按中央目录精确别名表解析，未知或混合业务名称保留待确认。名称别名新增必须检查冲突；不得为消除待确认而统归“其他”。

发布前在隔离副本汇总现有企业行业、求职意向名称的映射结果供业务确认；生产回填须单独授权，不在本批自动执行。

联调需覆盖：完整目录与有岗目录差异、零岗位类别、编码保存重读、金融大类筛选银行、城市条件联用、未知旧名称保留、清空、revision冲突、银行招聘软件工程师、技能未覆盖提示。岗位数量无结果应展示真实空态，不能回退到全行业结果。

本批不修改前端，不发起真实AI/短信/地图调用；定向测试、真实MySQL、全量构建和同次JAR验证分别记账，不互相冒充。