数据采集工具升级设计:从「广东中小企业调研」到「文旅获客数据底座 v2」
版本:v2.0 设计稿 | 2026-11-13 结论:旧工具不废,新增 v2 并行;旧库
data/sme.db不动,新库data/tourism.db。 目标:只支撑「短视频钩子 → 专属小地图 → 留资/到店 → B端结算」这条链路,不做大而全。
1. 现状审计
1.1 旧工具做了什么
| 模块 | 能力 | 评价 |
|---|---|---|
config/cities.json |
广东 21 市维表 | 单省硬编码 |
config/sources.json |
9 个数据源登记 | 广东 SME 向 |
db/schema.sql |
cities / sources / enterprises / city_indicators / collection_log | 5 张表,调研型 |
collectors/gov_lists.py |
政府公示名单表格解析 → enterprises | 通用性好,可复用表格解析 |
collectors/stats_yearbook.py |
统计公报候选句扫描 + 人工入库 | 半自动,适合宏观指标 |
collectors/commercial_api.py |
企查查/天眼查骨架 | 端点未实测,需 Key |
collectors/sizing.py |
工信部 300 号划型 | 与文旅无关,但可保留 |
scripts/init_db.py / export.py |
建库 / 导 CSV | 单库单场景 |
1.2 为什么不够用
- 对象不对:旧库核心是「企业」,新业务核心是「景区/商户/达人/视频/评论/线索/到店」。
- 区域不对:旧库只认广东 21 市;新业务首发贵州 9 市州,后续全国。
- 链路不对:旧库没有「视频→评论→地图→留资→到店→结算」的归因字段。
- 治理不足:没有原始快照、没有 consent、没有脱敏、没有数据质量闸门。
- 交付形态不对:旧库导出「企业名单」;新业务要导出「POI 库 / 线索 / 转化漏斗 / 结算单」。
2. 新业务需要什么数据
一条完整链路,只需要五类数据:
① 供给:景区 / 商户 / POI / 产品权益
② 内容:达人 / 短视频 / 评论
③ 需求:线索 / 留资 / 小地图
④ 履约:到店 / 核销
⑤ 结算:B端客户 / 合同 / 结算单
对应五个问题:
| 问题 | 数据 |
|---|---|
| 这条视频给谁看? | 达人、视频、播放/互动 |
| 谁被勾进来了? | 评论、私信、线索 |
| 我们交付了什么? | 小地图、POI、路线 |
| 有没有到店? | 核销码、到店记录、金额 |
| B 端该付多少钱? | 合同、单价、结算单 |
3. 目标架构
原始层 data/raw/v2/<source>/<sha256>.html|pdf|csv
↓ raw_artifacts(URL/时间/哈希/文件路径)
标准化层 scenic_areas / pois / poi_products / creators / videos / comments
↓
实体层 leads / map_assets / visits
↓
结算层 b_customers / contracts / settlements
↓
导出层 CSV:景区库 / 商户POI / 线索 / 转化漏斗 / 结算
设计原则:
- 一条链路一张表,不把 CRM/ERP 全搬进来。
- 原始快照可追溯:每条采集都能回到 URL + 抓取时间 + 哈希。
- PII 最小化:线索必须有 consent;导出默认脱敏;评论只存用户哈希。
- 去重确定性:景区按
(name, city)、POI 按(name, city, address)、线索按contact_hash。 - 旧库不动:v1 继续可用,v2 新库并行。
4. Schema v2 表地图
| 域 | 表 | 关键字段 | 用途 |
|---|---|---|---|
| 元数据 | meta |
schema_version | 版本 |
| 区域 | regions |
code/name/level/parent/region_group | 贵州+广东,后续扩展 |
| 数据源 | data_sources |
source_key/access_type/status/compliance | 源登记 |
| 供给 | scenic_areas |
name/level/city/lng/lat/source_coord/coord_system | 景区/度假区 |
| 供给 | pois |
name/type/scenic_id/lng/lat/source_coord/coord_system/last_verified_at | 商户/POI |
| 供给 | poi_products |
poi_id/price/commission | 产品/权益 |
| 内容 | creators |
creator_id/platform/followers | 达人 |
| 内容 | videos |
video_id/scenic_id/views/likes | 短视频 |
| 内容 | comments |
comment_id/video_id/text/intent | 评论 |
| 需求 | leads |
contact_hash/consent/scenic_id/video_id | 线索 |
| 需求 | map_assets |
map_id/lead_id/html_path | 小地图 |
| 履约 | visits |
lead_id/scenic_id/poi_id/amount | 到店/核销 |
| 结算 | b_customers |
name/type/status | B端客户 |
| 结算 | contracts |
pricing_model/lead_price/visit_price | 合同 |
| 结算 | settlements |
period/leads/visits/amount | 结算单 |
| 治理 | raw_artifacts |
url/sha256/file_path | 原始快照 |
| 治理 | collection_runs |
source_key/status/records | 采集运行 |
5. 采集器矩阵
| 采集器 | 数据 | 状态 | 合规 |
|---|---|---|---|
gov_tourism.py |
A级景区/度假区/乡村重点村 | 可用(URL 待核实) | 政府公开信息,低频 |
csv_import.py scenics/pois/creators/videos/comments/leads |
人工导出 CSV | 可用 | 线索必须 consent |
amap_poi.py |
高德 POI | 可用(需 AMAP_KEY) | 官方 API,遵守配额 |
gov_lists.py(旧) |
企业公示名单 | 保留 | 政府公开信息 |
stats_yearbook.py(旧) |
宏观指标 | 保留 | 政府公开统计 |
douyin_openapi.py |
抖音视频/评论 | P2 待建 | 只用官方授权接口 |
tender.py |
政府采购/招投标 | P2 待建 | 只检索公告,不围标 |
| 商业 API(企查查/天眼查) | 企业工商 | 骨架 | 付费 API |
不做:抖音网页版爬虫、买名单、批量外呼名单、非公开个人信息。
6. CLI 变化
# 建库(贵州+广东区域、8 个数据源)
python3 scripts/init_v2.py --db data/tourism.db --reset
# 导入景区/POI/达人/视频/评论/线索
python3 -m collectors.csv_import scenics --file data/examples/scenics.csv --db data/tourism.db
python3 -m collectors.csv_import pois --file data/examples/pois.csv --db data/tourism.db
python3 -m collectors.csv_import creators --file data/examples/creators.csv --db data/tourism.db
python3 -m collectors.csv_import videos --file data/examples/videos.csv --db data/tourism.db
python3 -m collectors.csv_import comments --file data/examples/comments.csv --db data/tourism.db
python3 -m collectors.csv_import leads --file data/examples/leads.csv --db data/tourism.db
# 政府景区名单
python3 -m collectors.gov_tourism --source gz_a_scenic --url "https://<核实后的名单页>" --city 安顺市
# 高德 POI(需 AMAP_KEY)
export AMAP_KEY=xxx
python3 -m collectors.amap_poi --keywords "黄果树瀑布" --city 安顺市 --pages 2
# 导出
python3 scripts/export_v2.py scenics
python3 scripts/export_v2.py pois --city 贵阳市
python3 scripts/export_v2.py leads
python3 scripts/export_v2.py funnel
python3 scripts/export_v2.py settlements
# 质量检查
python3 scripts/check_v2.py --db data/tourism.db7. 数据治理规则
7.1 线索 consent
- 没有
consent=1的线索不入库;CSV 导入会跳过并计数。 - 记录
consent_at/consent_channel;导出默认只给contact_masked。 - 明文联系方式只在内部表
leads.contact_value,不导出、不外发。
7.2 原始快照
- 每次网页/文件采集保存到
data/raw/v2/<source>/<sha256>.<ext>。 raw_artifacts记录 URL、抓取时间、HTTP 状态、哈希、文件路径。- 任何一条数据都能追到原始证据。
7.3 去重
- 景区:
(name, city_name)唯一。 - POI:
(name, city_name, address)唯一。 - 线索:
contact_hash唯一;重复提交只更新备注/状态,不新增。 - 视频/评论:平台 ID 唯一。
7.4 质量闸门
scripts/check_v2.py 的 critical(退出码 1):
- 线索未标记同意;
- 线索缺 contact_hash;
- 到店记录未关联线索;
- 评论未关联视频。
warning(不阻断):景区缺城市/坐标、POI 未关联景区、视频未关联景区、地图未关联线索。
8. 迁移与兼容
- 旧库不动:
data/sme.db、旧 schema、旧脚本全部保留,广东 SME 调研可继续用。 - 新库并行:
data/tourism.db,由scripts/init_v2.py创建。 - 旧采集器可复用:
gov_lists.extract_tables被gov_tourism复用;stats_yearbook仍可用于文旅统计公报。 - 不自动迁移企业数据:旧
enterprises与新scenic_areas/pois不是同一实体,强行映射会污染;如需要,单独写映射脚本。
9. 迭代路线
P0(已完成)
- schema v2 + 区域/数据源种子
- CSV 导入(景区/POI/达人/视频/评论/线索)
- 导出(景区/POI/线索/漏斗/结算)
- 质量检查
- 单测 + 端到端样例
P1(下一步)
- 核实贵州文旅厅/文旅部名单页 URL,跑通
gov_tourism - 高德 POI 实际采集(Key/配额)
- 线索 → 小地图 → 到店的回传接口(或 CSV)
- B 端合同/结算的录入 CLI
P2(跑通首战后)
- 抖音开放平台(官方授权)
- 政府采购/招投标公告检索
- 简易看板(漏斗/单客成本/结算)
- 全国区域扩展
10. 验收标准
python3 -m unittest discover -s tests -v全部通过。- 样例数据端到端:6 类 CSV 导入 → 5 类导出 →
check_v2无 critical。 - 线索无 consent 必须被拒绝;导出必须脱敏。
- 每个采集 run 都有
collection_runs记录,网页采集有raw_artifacts快照。
11. 已知限制
- 贵州 A 级景区/度假区名单页 URL 仍标「待核实」,需要人工打开官网确认后填
list_urls。 - 抖音只做了 CSV 导入,官方 API 适配器未写;不要用爬虫替代。
- 高德 API 需要 Key;未配置时
amap_poi会直接报错,不会静默失败。 - 没有前端看板;当前用 CSV + SQL 查看。
contact_hash只用于去重,不是加密;生产环境应加盐/密钥管理。