SocialDatabase 是群成员历史数据的聚合、保存和检索工具。核心程序消费外部 产生的 xlsx 或标准 JSON 批次，不调用机器人接口。配套 AstrBot 插件位于独立 仓库，可由管理员显式触发采集，但不自动定时获取群成员。
导入采用非破坏性合并：
- 新记录写入数据库。
- 新非空值更新最后已知资料。
- 空值不清除旧值。
- 新数据源缺少某个成员时不删除历史关系。
当前核心能力包括：
- 多工作表 xlsx 校验与导入。
- 标准 JSON v1 批次导入，以及与 xlsx 共用的格式无关合并核心。
- 完整保存现有来源的 19 个字段和采集来源元数据。
- SQLite 规范化模型和事务 upsert。
- 数据源哈希、重复跳过和强制重处理。
- 导入批次、来源统计和关系观察记录。
- 按字段、多用户分页搜索，数据库统计和批次查询。
- FTS5/LIKE 混合搜索、事务内索引同步、健康检查与人工重建。
- JSON、CSV 和 xlsx 搜索结果导出。
- 数据库健康检查、一致性备份和恢复操作说明。
- 受认证 HTTP 搜索、统计、批次导入和健康检查 API。
- 非 root Docker 镜像、Compose 持久卷和容器健康检查。
- 与独立 AstrBot
aiocqhttp插件兼容的 HTTP JSON v1 接收接口。 - Caddy HTTPS、来源 CIDR 限制和双令牌轮换生产部署基线。
- Python 3.10、3.12、3.14 持续集成。
已完成：
- 建立 83,580 条关系的只读搜索性能基线，且未输出成员明细。
- 确认 nickname 与 any 查询超过交互目标，决定验证 FTS5 trigram 加速。
- 完成可重建、可清理的临时 FTS5 原型；实际库全部可用场景与
LIKE命中用户集合一致，昵称和任意字段查询获得显著加速。 - 确认短于 3 个字符以及不具收益的群 ID 查询应保留
LIKE回退，正式 接入采用混合路由。 - 完成 schema 2、导入事务内全量同步、自动 LIKE 回退、内容一致性检查和
reindex恢复命令。 - 完成实际数据库 schema 1→2 迁移与完整分页复测，全部场景达到交互目标。
- 完成一致性备份、恢复候选健康检查与清理演练。
- 补齐稳定版本号、变更记录、分发包构建和发布检查清单。
- schema 3 补齐 sex、age、area、level、qq_level、title_expire_time、 unfriendly、card_changeable、is_robot、shut_up_timestamp 和 role。
- 扩展字段缺失时保持旧版 xlsx 兼容，存在时参与非破坏合并与导出。
- 建立带格式版本、生产方和采集时间的 JSON v1 契约；AstrBot 可作为外部 生产方输出该格式，核心包不依赖 AstrBot。
- 搜索和导出公开关系首次/最近观察批次及时间，但仍不从缺席推断退群。
- 数据库初始化先拒绝未来 schema，避免检查报错前产生任何建表修改。
本版本不加入采集器、HTTP 或 Docker，以便先稳定未来服务和插件共同使用的 数据边界。
- schema 4 为 JSON v1 增加可选稳定
batch_id，插件重试不依赖原始文件字节。 - HTTP API 提供搜索、统计、导入历史、JSON 导入和完整健康检查。
- Bearer 令牌保护全部成员数据接口；存活与就绪探针不返回成员或路径信息。
- 服务采用单 worker、串行写入、SQLite WAL 和可配置请求边界。
- Docker/Compose 使用非 root 用户、持久卷、只读容器文件系统和健康检查。
- AstrBot
aiocqhttp上传插件已分离到 独立仓库： 管理员按需采集、每群稳定批次、plugin_datapending/rejected 队列、HTTP 超时和持久指数退避均由插件仓库独立维护。 - 已提供 Caddy 自动 HTTPS、来源 CIDR 限制、API 内部网络和当前/旧令牌短期 双窗口轮换模板，不在仓库保存真实域名、地址或密钥。
- 已把并发读取、串行写入和导入中断回滚纳入自动测试；发布检查使用系统临时 资源完成有界运行、容器重建升级和恢复候选演练。
- 当前负载没有引入服务端任务队列的依据，继续保持同步单写入模型；AstrBot 侧队列已经覆盖网络中断和确认丢失。
- 在用户提供云主机、域名、固定来源和 AstrBot 实例后完成真实端到端部署， 观察持续运行、队列积压、请求耗时和备份外带。
- 根据真实负载决定是否增加监控指标、服务端任务队列或迁移数据库；不得用多个 API 容器直接并发写同一个 SQLite 文件。
- 数据源明确提供成员状态或完整快照范围后，再设计在群/退群事件；单纯未出现 在某次批次中仍不改变状态或删除历史关系。
自动获取数据不属于当前核心范围。远期可以：
- 自建采集器并输出标准批次。
- 继续使用外部 AstrBot 插件生成 xlsx 作为兼容来源。
- 在插件仓库扩展按需采集能力；自动采集必须显式配置、可观测且不改变核心 历史聚合语义或引入对核心 Python 包的依赖。
采集器应作为外部适配器，核心合并和数据库逻辑不依赖 AstrBot。手动 xlsx 导入始终保留为独立后备方式。