深圳房屋编码查询 / 解析

概述

对接深圳市官方「统一编码地址应用」（深圳市社区网格管理办公室，https://spatydz.sz.gov.cn/web/index.html），
实现深圳统一房屋编码（25 位）的正查、反查、结构解析与批量转换。

核心事实：19 位 = 楼栋编码（只到整栋楼）；25 位 = 房屋编码（精确到房间/户室）。
学位申请、公租房补租、居住登记、租赁备案等业务只认 25 位。

何时使用

出现以下任一意图时使用本技能：

• 用户给一个地址/小区名，想知道对应的房屋编码；
• 用户给一个楼栋，想列出各楼层房间的 25 位编码；
• 用户手上有一个 19 位或 25 位编码，想反查它对应的标准地址、区/街道/社区、楼栋房号；
• 用户要校验某个 25 位编码是否合法、各分段代表什么；
• 用户要批量把一批地址转成房屋编码清单。

核心工作流（决策树）

用户诉求是什么？
├─ 只有「地址/小区名」 → 想拿编码
│     └─ search  →  拿到 19 位楼栋编码（多条候选时需消歧）
│           └─ building <楼栋编码>  →  列出各房间 25 位房屋编码
│                 （若 search 直接命中 exttype=ROOM，则 uid 已是 25 位，跳过 building）
│
├─ 已有「19 位或 25 位编码」 → 想拿地址
│     └─ detail <编码>
│
├─ 只有「25 位编码」 → 想懂它的结构 / 校验真伪
│     └─ parse <编码>     （纯离线，不联网）
│
└─ 有「一批地址」 → 要批量出编码
      └─ batch <文件>  → 导出 CSV（需人工复核消歧）

命令速查

脚本：scripts/sz_house_code.py（仅用 Python 标准库，无需 pip 安装）

# 1) 按地址关键词搜楼栋，得到 19 位楼栋编码
python scripts/sz_house_code.py search "长城大厦"
python scripts/sz_house_code.py search "科兴科学园" --page-size 20 --json

# 2) 查楼栋结构，列出各房间的 25 位房屋编码
python scripts/sz_house_code.py building 4403040010010700001
python scripts/sz_house_code.py building 4403040010010700001 --room 101
python scripts/sz_house_code.py building 4403040010010700001 --floor 5 --all

# 3) 编码反查地址（19 位楼栋码 / 25 位房屋码均可）
python scripts/sz_house_code.py detail 4403040010010700001000001

# 4) 离线校验 + 解析 25 位编码的 8 级结构（不联网）
python scripts/sz_house_code.py parse 4403040010010700001000001

# 5) 批量地址 → 编码，导出 CSV
python scripts/sz_house_code.py batch addresses.txt --out result.csv

所有命令均支持 --json，便于程序化处理与二次加工。

关键规则（必须遵守）

1. 先 search 后 building：地址关键词只能搜到楼栋（19 位），要拿 25 位房屋编码必须再查楼栋结构。
2. 必须消歧：深圳同名楼栋极多（"长城大厦"全市数千条）。命中多条时，必须结合返回的
   区 / 街道 / 道路门牌号 与用户描述核对后再选，不能默认取第一条。若无法确定，把候选列表列给用户确认。
3. 关键词要短：搜索时只输入小区名、楼栋名或道路门牌号。输入完整长地址往往搜不到。
4. 权威名称靠 detail：编码第 4~6 级（街道/社区/网格）是体系内顺序码，无法直接推导街道名；
   要权威的区/街道/社区名称，用 detail 反查。
5. 低频访问：批量任务间隔 ≥ 0.6s，禁止高频抓取。脚本已内置 3 次重试与 1.2~1.5s 退避。
6. 偶发 500 属正常：官方接口返回 {"code":500,"message":"服务器出错啦"} 是软失败，重试即可。
7. 不做业务判定：学位锁定、招生范围、补租资格等由对应官方系统判定，本技能只给编码与地址。

典型示例

示例 A：用户说"帮我查深圳福田百花四路8号长城大厦4栋101的房屋编码"

python scripts/sz_house_code.py search "长城大厦"
# → 命中多条，按地址筛选出「百花四路8号长城大厦4栋」= 4403040010010700001
python scripts/sz_house_code.py building 4403040010010700001 --room 101
# → 25 位房屋编码：4403040010010700001000001

示例 B：用户给一串编码"4403040010010700001000001"，问这是哪

python scripts/sz_house_code.py detail 4403040010010700001000001
# → 广东省深圳市福田区园岭街道长城社区百花四路8号长城大厦4栋一单元101

示例 C：用户想知道 25 位编码每位是什么意思

python scripts/sz_house_code.py parse 4403040010010700001000001
# → 44(广东) 03(深圳) 04(福田) 001(街道) 001(社区) 07(网格) 00001(楼栋) 000001(房间)

输出规范

• 给用户的最终结果中，必须同时给出：25 位房屋编码、对应的完整标准地址、区/街道；
• 若命中多条候选，先列候选让用户确认，不要自作主张；
• 编码统一按字符串处理并完整保留前导零（不要当数字处理，否则 000001 会变成 1）；
• 批量结果必须提示"命中最多的候选不一定正确，需人工复核消歧"。

资源

scripts/

• sz_house_code.py — 主工具，5 个子命令：search / building / detail / parse / batch。仅依赖标准库。

references/

• api.md — 官方接口文档：3 个核心接口 + 参数、返回字段、错误码、限制与注意事项。需要改接口或排查失败时读。
• code-structure.md — 25 位编码的 8 级结构、深圳各区行政区划代码、校验要点、业务场景对照。需要解释编码含义时读。
• channels.md — 官方与线下全部查询渠道、查不到时的处理办法、常见问题 FAQ、使用边界。用户问"还有别的办法查吗""为什么查不到"时读。