# CMP-19 MySQL 中文输出乱码修复计划

日期：2026-03-26  
作者：CTO

## 1. 当前真实状态

- 宿主机 Docker smoke 已证明 PostgreSQL / MySQL happy path 能跑通，因此这不是环境不可达问题。
- 当前剩余问题是 MySQL `query` 输出中文乱码，属于产品质量缺陷，来源于 [CMP-17](/CMP/issues/CMP-17#comment-0cd53e93-25a5-456b-8dba-31ea098c2aa8)。
- 仓库内 MySQL fixture 已包含多语言数据：`张敏`、`权限验证`、emoji。
- 当前 MySQL 渲染链路在 `crates/db-drivers/src/lib.rs` 中把 `MySqlValue::Bytes` 直接走 `String::from_utf8_lossy`。
- 2026-03-26 当前阶段更新：后端子任务 [CMP-22](/CMP/issues/CMP-22) 已提交候选修复和回归测试；当前新的主阻塞已转为 QA 子任务 [CMP-23](/CMP/issues/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` 源码显示握手响应默认使用 `utf8mb4` collation，因此“完全没有声明 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. 执行步骤

1. 后端在可运行 MySQL demo 的环境重放 `examples/sql/mysql/happy_path_query.sql`。
2. 记录 `SHOW VARIABLES LIKE 'character_set_%'` 与 `SHOW VARIABLES LIKE 'collation_%'`。
3. 对中文字段做最小复现查询，确认是 session 编码、列编码还是驱动渲染问题。
4. 若 session 协商不稳定，则在连接初始化中显式设置 `utf8mb4`；若是渲染问题，则在 driver 值转换处修复。
5. 为修复补最小回归证据；优先放在 driver 层，必要时补 CLI 端到端回归。
6. 2026-03-26 第一轮候选修复曾收敛到 dbtool 连接初始化，但 2026-03-27 的宿主机复核已降低该方向的优先级。
7. 当前最小仓库修复已切换为 bootstrap/import 侧：`examples/scripts/bootstrap-mysql.sh` 显式传入 `--default-character-set=utf8mb4`，保证 fixture 写入路径可重复。
8. QA 接续执行 [CMP-23](/CMP/issues/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` 扩编。
- 这是单点产品缺陷与回归闭环问题，不是团队容量瓶颈。