4.2 KiB
4.2 KiB
CMP-19 MySQL 中文输出乱码修复计划
日期：2026-03-26
作者：CTO
1. 当前真实状态
- 宿主机 Docker smoke 已证明 PostgreSQL / MySQL happy path 能跑通，因此这不是环境不可达问题。
- 当前剩余问题是 MySQL
query输出中文乱码，属于产品质量缺陷，来源于 CMP-17。 - 仓库内 MySQL fixture 已包含多语言数据：
张敏、权限验证、emoji。 - 当前 MySQL 渲染链路在
crates/db-drivers/src/lib.rs中把MySqlValue::Bytes直接走String::from_utf8_lossy。 - 2026-03-26 当前阶段更新：后端子任务 CMP-22 已提交候选修复和回归测试；当前新的主阻塞已转为 QA 子任务 CMP-23 的宿主机验证与证据回填。
- 2026-03-27 新宿主机证据表明：在干净重建并显式 UTF-8 导入后，MySQL 官方 CLI、
dbtool query与dbtool export都能正确显示中文；问题边界已从“dbtool 解码缺陷”收敛为“MySQL bootstrap/import 字符集未显式声明”。 - 后端已据此将最小修复收敛到
examples/scripts/bootstrap-mysql.sh，为导入命令显式添加--default-character-set=utf8mb4。
2. 当前技术判断
- 仅凭 CTO 当前 runner 不能直接复现该问题，因为此环境没有可用 MySQL runtime。
- 本地 vendored
mysql 28.0.0源码显示握手响应默认使用utf8mb4collation，因此“完全没有声明 UTF-8”不是充分结论。 - 更可能的方向是：需要在真实复现场景中确认 MySQL session charset / collation、返回字节序列，以及当前 driver 是否还需要显式
SET NAMES utf8mb4或等价初始化。 - 在没有复现证据前，不应由 CTO 盲改产品代码。
- 截至 2026-03-27，根因判断已被宿主机证据更新：当前不再优先怀疑
dbtool query/export的结果解码，而是优先怀疑 demo 数据在 MySQL bootstrap/import 路径中因客户端字符集未显式指定而被错误写入。
3. 第一轮职责
- 后端：复现问题，定位 session charset 与返回值解码链路，提交最小修复和回归。
- QA：在修复分支上复跑宿主机 smoke，确认中文结果恢复正常，并回填共享文档。
- 前端：继续 gated；本轮不进入 CLI 编码缺陷修复路径。
- CTO：维护优先级、评审根因证据、决定该缺陷是否仍阻塞发布。
4. 执行步骤
- 后端在可运行 MySQL demo 的环境重放
examples/sql/mysql/happy_path_query.sql。 - 记录
SHOW VARIABLES LIKE 'character_set_%'与SHOW VARIABLES LIKE 'collation_%'。 - 对中文字段做最小复现查询，确认是 session 编码、列编码还是驱动渲染问题。
- 若 session 协商不稳定，则在连接初始化中显式设置
utf8mb4；若是渲染问题，则在 driver 值转换处修复。 - 为修复补最小回归证据；优先放在 driver 层，必要时补 CLI 端到端回归。
- 2026-03-26 第一轮候选修复曾收敛到 dbtool 连接初始化，但 2026-03-27 的宿主机复核已降低该方向的优先级。
- 当前最小仓库修复已切换为 bootstrap/import 侧：
examples/scripts/bootstrap-mysql.sh显式传入--default-character-set=utf8mb4，保证 fixture 写入路径可重复。 - QA 接续执行 CMP-23：在 Docker-capable host 上用修复后的 bootstrap 脚本重跑 seed + query + export 路径，并把最终证据回填共享文档。
5. 验收标准
- 能稳定复现原问题，且有明确根因说明。
- 修复后 MySQL 查询结果中的
张敏、权限验证、emoji 均正常显示。 - 回归结果被回填到 QA 文档与相关 issue。
- 未引入 PostgreSQL / SQLite 输出回归。
- 在 QA 宿主机复核完成前，
CMP-19仍保持 blocked，不应因“代码已提交”而提前宣布关闭。 - 若 QA 复核继续正常，则
CMP-19的关闭结论应明确写成“问题已被重新归因到 bootstrap/import 字符集处理，并由最小 seed 修复关闭”，而不是“dbtool 解码层 bug 已修复”。
6. 组织判断
- 当前不建议因
CMP-19扩编。 - 这是单点产品缺陷与回归闭环问题，不是团队容量瓶颈。