交付出件箱

← 返回出件箱

接力档 · 渠道机构地理分布驾驶舱大屏

2026-08-14 收口 · 供新会话直接接手
当前阶段：调研完成，等待决策。长官明确指示"先别开工"。

一、新会话开局必读三条

1. 不要写业务代码。 长官原话："先别开工，我现在要的是数据报告、调研报告"。本项目目前只出文档。
2. 本项目未立项，没有 Phase 编号，没有建功能分支。要开工须先走需求变更流程。
3. 交付链接给内网那条：http://100.113.74.62:8811/reports/xxx.md。公网域名链接给不了，原因见 §六。

二、这是个什么项目

长官要一块以中国电子地图为核心的数据驾驶舱大屏，6 块能力：

1. 机构登录实时上屏，对应地区自动点亮
2. 点位下钻：机构名称、归属渠道、登录 IP、登录时段、在线状态、机构基础信息
3. 账号安全处置：强制下线、启用/禁用、重置密码 + 操作日志
4. 分级权限：总管理员 / 渠道管理员 / 区域管理员，看不同范围
5. 统计卡片：全国活跃机构数、各省活跃度、各渠道机构分布
6. 异常提醒：多地登录、频繁掉线、非工作时间登录

需求是分两次给的：第一次只有 1、2、5 三块（对应报告 v1.0），第二次补齐 3、4、6 并指定了 8 节的报告结构（对应报告 v2.0）。

三、已交付产出（三份，均已双投递）

正本在 ~/reports/，副本在 worktree 的 reports-out/（给 claude.ai 文件卡片）。

四、核心调研结论（全部 grep 实证，出处见主报告附录 A）

4.1 两个决定性有利条件

① 登录行为已完整落库，且记的是真实公网 IP。
auth_audit_logs 有 user_id / event_type / ip(INET) / user_agent / detail(JSONB) / created_at。
写入点覆盖全角色：auth_service.py:249（管理端、渠道）、seat_auth.py:362（席位）。
IP 真实性已验证：nginx 传 X-Forwarded-For（chat.tongban.love.conf:107-111）+ 生产容器
--proxy-headers --forwarded-allow-ips *（deploy/Dockerfile.api:67）两边配套。
→ 实时上屏不需要新增任何埋点。

② 渠道/机构/签约/登录四类数据同一物理库。
结算虽拆成独立服务，生产是同库 doctor_ai_brain + 受限账号 settlement_rw 隔离
（settlement/deploy/docker-compose.prod.yml:32-34、settlement/db/grants.sql:33-48）。
核心侧超管账号可直接 JOIN。
→ "机构→渠道"一条 SQL 搞定，不需要跨服务编排。

4.2 四个真实缺口（项目的全部工程量所在）

① 无任何地理数据（最高优先级）
- 全库无 province/city 字段，无行政区划字典
- organizations.latitude/longitude 是门店名片用途，席位手动选点，业务不强制
- org_signup_profiles.address 入驻表单为 Optional，审核只校验四类证照文件不校验地址
（store_signup.py:98,126-136）
- → 覆盖率必须实测（摸底 SQL 第 1 条），低于 70% 不应进前端开发

② 无在线状态概念
- 无状态 JWT，access 30 分钟、refresh 最长 1 年（jwt_local.py:26-29）
- 无心跳，登出只进 Redis 黑名单不落库
- /api/admin/sessions 管的是对外 API 的 session_tokens，不覆盖席位/管理员
- → 建议用"活跃度四级"替代二元在线，零新增埋点

③ 强制下线做不了（但席位是例外）
- 现有黑名单是 SADD token_blacklist <具体token串>（auth_service.py:357-360），
管理员踢人时服务端不持有他人 token，此机制用不上
- 例外：席位账号 middleware 每请求校验 JWT.device_id == users.current_device_id
（middleware.py:255-257,372-373）→ 改库即踢，即时生效，零成本
- 管理员/渠道账号需新建：Redis 存按账号的失效时间戳 + 比对 JWT 的 iat（jwt_local.py:63）
- ⚠️ 最易漏的坑：只废 access 没用，refresh 最长一年，30 分钟后自动续上，等于没踢

④ 权限只有菜单维度，无数据行级范围
- role_menu_permissions 是 (role, menu_key) 二元组（role_menu_permission.py:10-23），
只管"能不能进这个页面"，管不了"能看哪些机构"
- "区域"概念全库 0 命中——无区域表、无区域省份映射、无区域管理员角色，从零建
- 渠道账号进不了管理后台：CONSOLE_ROLES = ["admin","platform_staff"]
（menu_registry.py:14-15），channel 不在内
- 🔴 红线：数据过滤必须后端强制，前端隐藏不算数。渠道间是竞争关系，泄露是商业事故

4.3 现成可复用（别重造）

4.4 顺手查出的两个既有缺陷（非本项目引入，建议一并修）

1. 取不到 request.client 时 IP 传字面量 "unknown"，写 INET 列抛错被
   _write_audit 的 try/except 吞掉 → 该条登录审计静默消失（auth_service.py:487-510）
2. auth_audit_logs docstring 写"6 月留存 APScheduler 每天 02:00 清"，
   但全仓无该定时任务实现（只有 gpu_scheduler_service.py:7 用 APScheduler）
   → 历史数据大概率一条没删，对大屏有利，但属注释与实现不符
3. 根目录 Dockerfile.api:12 无 --proxy-headers（生产用的是 deploy/ 那份）。
   若误用它构建 → 所有登录 IP 退化成网关地址，地图全国只剩一个点

4.5 IP 归属地能力（已真实跑通，非推测）

pypi 包 XdbSearchIP 自带 ip2region.xdb（11MB），白名单内可得（GitHub/MaxMind 下不到）。
实测：220.181.38.148→北京市·电信，61.139.2.69→四川省成都市·电信，
223.5.5.5→浙江省杭州市·阿里云，8.8.8.8→美国，172.18.0.1→内网IP；8 次查询 1.55ms。
短板：库文件 2022-08 版，上线前需有外网条件的人补新库。
附带用途：能认"内网IP"→ 可当代理头配置的健康探针。
详见记忆 reference-ip2region-offline-lib。

五、下一步只有一件事

跑摸底 SQL。 4 条只读查询，约 1 分钟，决定排期是 6 周还是 10 周。
云机不连生产库，必须由有权限的同事执行，我方不代跑不估算。

看两个数字：
- 机构地址可定位率：≥70% 按原计划；40~70% 技术与补录并行；<40% 先补数据
- 登录 IP 私网占比：接近 0 正常；很高 = 部署配置有问题，先修配置

六、待长官拍板 9 项（主报告附录 B 有完整表）

另有一条我主动提的设计风险：大屏常驻/投屏 + 能改密码禁账号 = 无人值守时路过就能停客户账号。
建议投屏模式与操作模式分离、切操作模式重新输密码、高危操作填理由、闲置自动退回只读。待长官定。

七、工期估算（经验估算，非实测）

关键：地址补录必须与 P0 并行启动（唯一一件技术加班也快不了的事）。
P3 可后置 → 整体提前约 1.5 周，但那样 P2 处置能力只能对总管理员开放。

技术选型已定调：地图用 ECharts + 自托管 GeoJSON（不用高德百度，避免机构位置外发）；
实时刷新用 15 秒轮询（不用 SSE/WebSocket，理由见主报告 §4.5）；
部署沿用云端现有栈（本地部署不成立）。

八、环境注意事项

1. 写 ~/reports/shared/ 报 Permission denied 时，用 sg 现场取组，不用重启会话：
   bash sg devshare -c 'cp ~/reports/a.md ~/reports/b.md ~/reports/shared/'
   真因（长官 2026-08-14 确认）：账号确实在 devshare 组，但 claude 进程创建于加组之前，
   已运行进程不继承新加的组。非权限配置问题，非挂载问题。
   本次三份报告已用此法成功投递，属组 devshare 已验。
   ⚠️ 投递后别在本机 curl 验公网链接：funnel 域名不在出网白名单，一律返 000，
   设计如此非故障，不代表长官打不开。ls 在位即可给链接。
   详见记忆 project-shared-outbox-write-denied。
2. 当前分支 worktree-bridge-cse_01496791TKo63ySaHYCggqNc，工作区干净，无任何代码改动。
   本次全程只写了 ~/reports/ 和 worktree 的 reports-out/。
3. 本机不连生产库、不跑全量 e2e，所有数据类结论一律标注"未实测"。

九、已存记忆（新会话自动加载）

本次会话零代码改动，产出为纯调研文档。