4.5 KiB
4.5 KiB
新华社工商信息同步接入实施计划
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. 实施顺序与验收
- 执行
sql/migration/2026-07-29-xinhua-enterprise-profile.sql，重复执行验证幂等性。 - 启动 FastAPI Mock、Java 后端和 Vue 前端，开发配置必须指向本地 Mock。
- 运行 Mock、Java 模块测试和前端生产构建，确认源码不存在
LSFXXHSResult。 - 构造信用代码匹配、同名信用代码不匹配、空股东和多股东场景，核对缓存、实体、项目和日志。
- 使用应用内浏览器验收实体库、流水明细和接口日志真实页面。
- 清理业务测试数据并关闭本轮启动的前后端及 Mock 进程。
- 生产先对单个已知企业烟测，确认一次外呼、一条日志、原始缓存、
creditCode和股东一致后，再启动历史补全；任何环节失败立即停止上线。