本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/docs/改造执行计划 (2).md。

SoSite 1.0（SplitDB 引擎迁移）— 改造执行计划

文档状态：定稿（2026-08-13，经用户确认）

基线版本：SoSite 5.0（MySQL）→ SoSite 1.0（SplitDB 纯 SQLite 分片引擎）

依据：《SplitDB v2.3 白皮书》（根目录 Splitdb V2.3 白皮书.txt）

兼容基线：PHP 8.0.2（phpstudy D:\phpstudy_pro\Extensions\php\php8.0.2nts，内置 SQLite 3.33.0）

编码规范：全部生成文件 UTF-8 without BOM + LF

一、角色与目标

• 角色：资深 PHP 架构师与重构专家
• 目标：将现有 SoSite 5.0（MySQL）核心代码重构为 SoSite 1.0（SplitDB 纯 SQLite 分片引擎）
• 原则：彻底剥离 MySQL，不使用任何 MySQL 兼容层 / 双引擎切换 / 回退功能，只存在 SplitDB 一种驱动

二、核心开发红线（严禁违反）

1. 彻底移除 MySQL 依赖：所有数据读写必须通过 SQLite 文件进行。严禁保留 PDO_MySQL 连接逻辑、mysql_* 函数、MySQL 语法兼容判断
2. 不兼容 MySQL：不提供双引擎切换或 MySQL 回退，只存在 SplitDB 一种驱动
3. 功能精简：保留除插件之外的核心功能（用户注册/登录、发帖、回帖、版块、个人中心等）；插件系统代码与目录全部保留，不删除——P0~P6 阶段仅「暂停迁移插件」，保持插件未激活/忽略状态，先让 SoSite 核心骨架跑通 SplitDB

补充要求（用户 2026-08-13 追加，与红线同等强制）

1. 【精确的"暂不删除"机制】（P3/P5）：遇到 Plugin::hook() 调用时，严禁直接删除该行代码。必须采用 // [SplitDB] 临时注释： 前缀将其注释掉，注释内保留原始调用原文，方便日后回顾与恢复（恢复时去掉注释前缀即可）。
2. 【数据无损迁移】（P7 重点）：编写 cli/migrate.php 时，必须确保正文（MEDIUMTEXT）成功剥离为 extern/ 目录下的 .txt 文件。若 extern 文件生成失败，迁移脚本必须报错并整体回滚——严禁出现「索引导入成功但正文丢失」的情况。
3. 【ViewCounter 安全降级】（P4）：实现浏览计数时，若系统检测到未安装 APCu 扩展，严禁让全站报错。必须静默降级为简单的 UPDATE 实时计数（降低性能但不崩站），确保程序在任何 PHP 环境下都能运行。

三、执行规范与工作流（必须严格遵守）

1. 计划先行，禁止直接修改：行动前先输出书面《改造执行计划表》，经用户确认后才动工
2. 绝对安全的更新模式：改动的核心文件可在原位置直接覆盖，同时在 update/ 目录下同步改动过的文件；update/ 根目录维护 CHANGELOG.md，详细记录修改了哪些文件、进行了什么逻辑变更
3. 串行执行与单步反馈：不批量修改，严格"改好一个核心模块，立即测试，通过后再进行下一个"
4. 编码安全：全部文件 UTF-8 without BOM、LF 行尾，禁止乱码

四、架构与实现要求（参照白皮书 v2.3）

五、适配 SoSite 5.0 现有骨架

1. Model 层：保留 app/Models/ 目录结构（User.php、Thread.php、Post.php 等），查询逻辑重写为调用 SplitDB 连接池与路由，而非直接执行 MySQL SQL
2. Config：修改 config.php，去掉 MySQL 配置项，加入 DATA_PATH（数据目录）、BUCKET_SIZE（桶数量）等 SplitDB 配置
3. 新增核心 Helper：在 app/Helpers/（实际落点 app/SplitDB/）为 SplitDB 功能（外置文件读写、队列任务分发等）增加辅助类

六、交付标准

1. 结构完整性：update/ 目录代码必须是"可以运行"的骨架
2. 不可逆性：提供可执行的旧 MySQL → SplitDB 数据迁移脚本（可选）
3. 测试流程：交付后提供本地手动测试说明（如何发帖并验证分片文件生成）

七、勘察结论（现状盘点）

八、目标架构总览（SplitDB v2.3 落地形态）

数据流：
  写入 = global_id 取号 → 季度分区 + ID%32 哈希 → 写 Bucket + 正文 extern → 随机入队 → 返回
  读取 = 列表/分页走 main_index → 详情走 bucket_path + extern → 搜索走 search_index（异步）

分层：
  data/meta/                → main_index.sqlite(帖子主索引) · business.sqlite(用户/版块/设置/
                              博客/私信/附件/标签/投票等非分片业务数据)
                              search_index.sqlite(自研倒排) · global_id.sqlite · sessions.sqlite
  data/meta/task_queue/     → queue_0~2.sqlite（三队列打散锁竞争）
  data/bucket/active/{季度}/{0..31}.sqlite  → topic / reply 真相源
  data/bucket/archive/      → 18 个月以上冷数据
  data/extern/{年}/{季度}/{桶}/{id}.txt     → 正文外置
  cli/                      → worker.php(队列) · rebuild_search.php · archive.php · migrate.php

已确认的设计决策（用户拍板）：

1. 搜索方案：保留自研倒排索引（Search.php + bigram 分词，表平移至 SQLite），不采用 FTS5
2. 非分片数据：独立 business.sqlite（与 main_index 分离，避免索引写锁互相影响）

九、目录结构变动表

十、改造执行计划表（严格串行，每步验证通过才进下一步）

十一、update/ 同步与交付规范

1. 同步规则：每改动一个文件，立即拷贝至 update/ 对应相对路径（含 config.php 模板、cli/、app/ 全量），保证 update/ 是可运行骨架
2. CHANGELOG.md：每次模块改动后追加一条，格式 [P1] DBFactory.php — 新增 LRU 连接池（MAX_HANDLES=8）…，含文件清单与逻辑变更说明
3. 编码安全：全部文件 UTF-8 without BOM、LF 行尾（逐文件校验确认）

十二、测试流程说明（交付后本地验收）

1. phpstudy 起 Nginx + PHP 8.0.2（无需 MySQL）→ 访问 /install.php 初始化 → 确认 data/ 目录树生成
2. 注册账号 → 发帖「测试标题」→ 验证：

• data/bucket/active/{当前季度}/{id%32}.sqlite 出现 topic 行
• data/extern/{年}/{季}/{桶}/{id}.txt 生成正文
• main_index.sqlite 有索引行

1. 首页/版块列表可见新帖（读 main_index）；点开详情正文正常（读 extern）；回复后 reply 落桶 + 回复计数异步更新
2. 搜索关键词命中（search_index）；php cli/worker.php 消费队列后索引一致

十三、进度状态

• ✅ P1 核心引擎已完成（2026-08-13）：DBFactory / IDGenerator / ShardRouter / ExternStorage + 4 个冒烟脚本，50/50 通过
• 关键适配：PHP 8.0.2 的 SQLite 3.33.0 不支持 UPDATE…RETURNING（需 ≥3.35），IDGenerator 改用 BEGIN IMMEDIATE 写锁事务（等价原子性，兼容 7.4+）
• PDO-SQLite 对 exec('BEGIN IMMEDIATE') 不置内部事务标志，事务控制全程用原始 SQL（exec('COMMIT')/exec('ROLLBACK')），避免 "There is no active transaction" 与残留事务问题
• 全部文件 UTF-8 无 BOM + LF；update/ 已同步 8 个文件 + CHANGELOG.md
• ⏳ 下一阶段：P2 任务队列（Queue + QueueConsumer + cli/worker.php），等待用户指令后开始