63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
# 新华社工商信息同步接入实施计划
|
||
|
||
## 1. 实施目标
|
||
|
||
接入新华社同步工商接口 `POST /api/service/interface/invokeService/LSFXXHS`，开发环境仅连接本地 FastAPI Mock，生产环境连接真实接口。接口响应直接读取 `data.mappingOutputFields`，统一社会信用代码字段固定为 `creditCode`。
|
||
|
||
本次不实现异步结果查询、任务 Key 提取、轮询、结果缓存接口，也不接入 `LSFXXHSstockrelation`。
|
||
|
||
## 2. 接口与日志
|
||
|
||
- 使用 `application/x-www-form-urlencoded` 提交 `entName`、`serialNum`、`orgCode=999000`、`runType=1`。
|
||
- `serialNum` 格式为 `CCDI_GS_时间戳_UUID`，仅作为请求流水号。
|
||
- 依次校验 HTTP、JSON、外层状态、业务状态、非空结果对象、企业名称和 `creditCode`；任一校验失败均不得写缓存及业务数据。
|
||
- 所有外部 HTTP 调用显式携带不可变 `CallerContext`，异步链路沿用原始发起用户。
|
||
- 每次实际外呼写入一条 `sys_api_log`；缓存命中不写日志。日志独立事务保存，日志失败不影响业务请求。
|
||
- 接口日志仅提供列表和详情，不提供删除、清空或导出。
|
||
|
||
## 3. 数据与解析
|
||
|
||
- 新增工商原始响应缓存、实体完整股东、项目对手方企业、项目对手方股东和接口日志表。
|
||
- 缓存键为 `TRIM(entName) + EnterpriseProfile`，有效期为成功调用时间后 180 天，`query_result` 保存完整原始 JSON。
|
||
- 实体表补充注册资本、注册日期、区域、从业人数、缓存关联和工商同步时间。
|
||
- 映射 `creditCode`、注册资本、日期、机构类型、行业、区域、注册地址、从业人数、法定代表人和股东字段。
|
||
- `stock_percent` 去除 `%` 后按百分数值保存，`should_capi` 单位固定为“万元”。文档未提供字段不推断。
|
||
- `holders` 为空时整体清空旧股东和实体表前五股东字段。
|
||
|
||
## 4. 实体库同步
|
||
|
||
- 新增、导入、关系自动补全和名称变更均在原事务提交后异步执行。
|
||
- 单批按去除首尾空格后的名称去重，同名只查询一次。
|
||
- 仅在返回名称与请求名称一致且返回 `creditCode` 与实体主键完全一致时回写。
|
||
- 同名但信用代码不一致的实体不更新；成功缓存保留，历史任务记录为跳过。
|
||
- 工商字段、缓存关联、同步时间和 `data_source=API` 在短事务内更新，完整股东整体替换。
|
||
- 不覆盖风险等级、企业来源、企业性质、经营状态和业务关系。
|
||
|
||
## 5. 项目对手方同步
|
||
|
||
- 流水上传、平台拉取和历史导入在整个批次完成后各触发一次 reconcile。
|
||
- 当前项目全部非空对手方名称去重后按每批 100 条处理，外呼共用最大并发数为 3 的专用执行器。
|
||
- 按“项目 ID + 对手方名称”更新或新增，信用代码变化时更新同一记录，并事务性替换股东。
|
||
- 单项失败保留旧成功数据；批次结束后删除已不在当前流水集合中的项目工商数据。
|
||
- 删除流水后基于剩余流水同步；空集合直接清空且不外呼。删除项目时直接删除项目工商数据。
|
||
- 项目工商信息与实体库相互隔离。
|
||
|
||
## 6. API 与页面
|
||
|
||
- 实体库提供详情刷新、历史补全启动和 Redis 任务状态查询。
|
||
- 项目提供对手方详情、单个刷新、历史补全启动和 Redis 任务状态查询。
|
||
- 任务状态包含总数、完成数、成功数、跳过数、失败数和最终状态，不新增任务表。
|
||
- 实体详情展示新增工商字段和完整股东；仅未同步或缓存过期时显示重新查询。
|
||
- 流水对手方名称打开本地工商详情；打开、翻页和普通刷新不得触发外呼。
|
||
- 接口日志页面为安静的只读运维表格，详情展示请求、响应和异常原文。
|
||
|
||
## 7. 实施顺序与验收
|
||
|
||
1. 执行 `sql/migration/2026-07-29-xinhua-enterprise-profile.sql`，重复执行验证幂等性。
|
||
2. 启动 FastAPI Mock、Java 后端和 Vue 前端，开发配置必须指向本地 Mock。
|
||
3. 运行 Mock、Java 模块测试和前端生产构建，确认源码不存在 `LSFXXHSResult`。
|
||
4. 构造信用代码匹配、同名信用代码不匹配、空股东和多股东场景，核对缓存、实体、项目和日志。
|
||
5. 使用应用内浏览器验收实体库、流水明细和接口日志真实页面。
|
||
6. 清理业务测试数据并关闭本轮启动的前后端及 Mock 进程。
|
||
7. 生产先对单个已知企业烟测，确认一次外呼、一条日志、原始缓存、`creditCode` 和股东一致后，再启动历史补全；任何环节失败立即停止上线。
|