🏗️ 整体架构

🧭 分层视图

┌─────────────────────────────────────────────────────────────┐
│                       使用形态层                              │
│   ┌─────────┐  ┌──────────┐  ┌────────────┐                 │
│   │  CLI    │  │  Go SDK  │  │  HTTP API  │                 │
│   └────┬────┘  └─────┬────┘  └─────┬──────┘                 │
├───────┼─────────────┼─────────────┼─────────────────────────┤
│       │      编排层 (core/icp)     │                         │
│       │  输入归一化 · 凭证池 · 限速 │                         │
│       │  重试 · 聚合 · 去重 · 缓存 │                         │
├───────┴─────────────┴─────────────┴─────────────────────────┤
│                       适配层 (source/*)                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ zhudun   │  │  ocr     │  │  miit    │  │  ...     │     │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘     │
├───────┼──────────────┼─────────────┼─────────────┼──────────┤
│       │      传输层 (httpc · retry · ratelimit)   │          │
├───────┴──────────────┴─────────────┴─────────────┴──────────┤
│                       基础层 (model · cache · log · conf)    │
└─────────────────────────────────────────────────────────────┘

📦 模块清单

层	模块	职责	文档
使用形态	cmd/go-icp	CLI 入口	🖥️ CLI 总览
使用形态	sdk	Go SDK 对外 API	🐹 SDK 总览
使用形态	server	HTTP API 服务	🌐 API 总览
编排	core/icp	查询编排核心	🧱 模块划分
适配	source/zhudun	创宇盾适配	🛡️ 创宇盾
适配	source/ocr	点选 OCR 适配	👁️ 点选 OCR
适配	source/miit	工信部页面补全	🏛️ 工信部 ICP
传输	httpc	带重试/限速的 HTTP 客户端	📦 httpc 包
基础	model	领域模型与 DTO	📦 model 包
基础	cache	结果缓存	📦 cache 包
基础	conf	配置加载	⚙️ 配置项

🔁 调用链示例：公司 → 域名

go-icp company "X科技有限公司"
  └─ sdk.Client.QueryCompany(ctx, name)
       └─ core/icp 编排
            ├─ 1. 输入归一化
            ├─ 2. 查缓存（命中则返回）
            ├─ 3. 选凭证 (zhudun)
            ├─ 4. source/zhudun.QueryCompany
            │     └─ httpc → 创宇盾 API
            ├─ 5. 若命中验证码 → source/ocr.Break
            ├─ 6. 结果不足 → source/miit 补全
            ├─ 7. 聚合 / 去重 / 交叉校验
            └─ 8. 写缓存
  ◀─ 结构化结果

完整过程见 🔁 查询生命周期。

🎯 设计原则

1. 可降级：主路径失败有补全路径，补全失败有缓存。
2. 凭证无关：业务代码只调 core/icp，不感知凭证轮换。
3. 形态同源：CLI / SDK / HTTP API 共用同一编排核心，行为一致。
4. 可观测：每次查询带 trace，限速、重试、缓存命中均有日志。

📚 延伸阅读

• 🧱 模块划分 · 🔁 查询生命周期 · ⚠️ 错误模型