5.0 KiB
5.0 KiB
新华社工商信息同步接入实施报告
1. 实施结果
已按同步接口契约完成新华社工商信息接入。开发环境通过 FastAPI Mock 联调，生产配置保留真实接口地址；代码、配置和 Mock 均未实现 LSFXXHSResult 或 LSFXXHSstockrelation。
2. 主要改动
外部接口与日志
ccdi-lsfx新增新华社同步客户端、同步响应模型和不可变CallerContext。- 重构共享 HTTP 工具，统一记录调用人、URL、方法、请求头和参数、HTTP 状态、响应头、原始响应、异常堆栈和耗时。
sys_api_log使用独立事务写入；HTTP 200 的业务失败仍按传输成功保存，业务失败信息保留在原始响应中。- 恢复只读接口日志列表、详情 API 和页面，无删除、清空、导出能力。
缓存、解析与实体库
- 新增 180 天成功缓存，缓存保存同步接口完整原始 JSON。
- 新增工商字段解析、实体完整股东表和股东整体替换。
- 实体新增、导入、关系自动补全及名称变化后，在原事务提交后异步同步。
- 单批按企业名称去重，返回
creditCode仅回写主键完全匹配的实体；同名不匹配实体保持不变。 - 手工刷新和历史补全使用 Redis 状态，不增加任务表。
项目对手方
- 新增项目对手方企业、股东、详情、刷新和历史补全能力。
- 流水上传、平台拉取及历史导入完成后按项目当前对手方集合 reconcile。
- 查询按每批 100 条执行，新华社查询共用最大并发数 3 的执行器。
- 项目删除直接清理项目工商数据，流水删除后按剩余流水同步，空集合不外呼。
前端与 Mock
- 实体详情新增注册资本、注册日期、区域、从业人数、同步时间和完整股东表。
- 流水对手方名称可打开本地工商详情，仅无数据或缓存过期时显示重新查询。
- Mock 覆盖公司、个体、空股东、多股东、HTTP 失败、超时、空响应、非法 JSON、外层失败、业务失败、结果缺失、名称不一致和信用代码缺失。
3. 数据库实施
- 新增迁移：
sql/migration/2026-07-29-xinhua-enterprise-profile.sql。 - 已通过
bin/mysql_utf8_exec.sh连续执行两次，均成功。 - 已核对 5 张新增或校准表均为
utf8mb4_general_ci。 - 已核对缓存
query_result为LONGTEXT，缓存唯一键为(query_param, query_type)，项目唯一键为(project_id, counterparty_name)。 - 已核对实体工商扩展字段、菜单权限和管理员角色权限落库。
4. 自动化验证
python3 -m pytest tests/test_enterprise_api.py -v：新华社 Mock 专项 4 项通过。mvn -pl ccdi-info-collection -am test：构建成功，覆盖新华社客户端、HTTP 日志、字段解析和信息采集模块回归。- 项目模块定向测试：53 项通过，覆盖上传、拉取、历史导入、项目删除及调用人传递。
mvn -pl ccdi-project -am -DskipTests compile：构建成功。- 前端在 Node 14.21.3 下执行
npm run build:prod：构建成功。 git diff --check：通过。
全量项目测试当前仍有 3 个失败和 1 个错误，均位于既有结果总览和银行标签基线断言：按钮文案、规则数量、modelParamService 结构断言及对应未配置 Mock。本次新增链路的定向测试均通过，未修改这些无关基线。
Mock 子项目全量 99 项测试为 75 项通过、24 项失败；失败用例均属于既有流水 Mock 链路，原因是测试尝试使用账号 znsj 从当前宿主连接 MySQL 时被拒绝。新华社工商专项 4 项不依赖该连接并全部通过。
5. 应用内浏览器验收
- 实体库真实页面成功展示接口返回的统一社会信用代码、注册资本、日期、区域、从业人数及 7 条完整股东。
- 新增同名但不同信用代码的实体后，确认该实体保持手工数据且无股东回写；缓存命中后新华社日志仍为 1 条。
- 补充验证同名未同步实体即使存在有效缓存仍可发起刷新，并明确返回“工商信用代码与实体主键不一致”；项目无本地记录时可复用有效缓存补齐，两种缓存命中均不新增接口日志。
- 流水明细真实页面确认对手方名称为本地详情入口，打开弹窗不触发新华社；无数据时显示重新查询。
- 对手方手工刷新后展示接口返回的信用代码、结构化工商字段和完整股东。
- 接口日志真实页面确认每次缓存未命中对应一条日志，详情包含调用账号、表单参数、
CCDI_GS_时间戳_UUID、HTTP 状态、响应头和原始 JSON。 - 联调业务数据已清理；接口历史日志按设计保留。
6. 上线要求
生产环境不得配置或恢复异步结果查询。上线先使用一个已知企业完成单次烟测，逐项确认单次外呼、单条日志、原始缓存、creditCode 和股东落库一致；确认后才能启动实体和项目历史补全，失败时停止上线。