智慧餐厅 MySQL 5.6 / 达梦 DM8 双数据库兼容实施方案（待评审）
版本：v0.2，2026-09-28。目标代码仓库：store、ai_api。本文件是应用兼容改造方案，不代表代码已改造、客户环境已切换或业务已验收。v0.2 按用户确认修正：以现有 MySQL 5.6 业务行为为基线，不另造达梦专属业务规则。
一、目标与边界
同一产品版本按客户部署配置选择数据库，不为 MySQL 客户和达梦客户维护两套业务代码。一个客户环境只选择一种数据库产品：
| 客户选择 | store 主库 | ai_api 主库 | 双方跨库访问 |
|---|---|---|---|
| MySQL 5.6 | MySQL zhct |
MySQL aizhct |
指向该客户的两套 MySQL 库 |
| 达梦 DM8 | 达梦 ZHCT_COMPAT 类实例 |
达梦 AIZHCT_COMPAT 类实例 |
指向该客户的两套达梦库 |
用户已确认：同一客户只选 MySQL 5.6 或只选达梦，store 与 ai_api 跟随同一选型。不做“每次请求动态切库”、MySQL 与达梦双写、实时同步或混搭。已有 MySQL 客户改库和历史数据割接不在本轮范围内，需另立项目。
二、当前事实与最重要的风险
证据等级 A：本地仓库 store@e2f567623、ai_api@f6aeef3b（均在 develop_dameng，当前与各自 master 同提交）的只读检查；达梦迁移验收记录。B：项目 README/运行说明。C：达梦官方 PHP 接口文档与PHP 编程指南。以下静态扫描计数是定位线索，不是完整兼容缺陷数。
- 已准备隔离测试数据：store 274 表、4,505,635 行；ai_api 168 表、1,570,745 行。表/字段/逐表行数/索引对账已通过，尚未运行 PHP 应用与业务接口。
store使用 ThinkPHP 5.0、测试镜像中 PHP 7.3；ai_api使用 ThinkPHP 6 / think-orm 2、PHP 7.4。当前两个框架的已安装连接器目录均无达梦连接器；官方提供 PHP/PDO_DM接口，但必须先验证目标 DM 包、CPU/系统、PHP 精确版本、TS/NTS、PHP API/ABI 与驱动能匹配。不能假定把type=mysql改成dm即可运行。- 两个框架的数据库连接配置都可指向自定义连接器类，同时还需匹配 SQL Builder、表字段元数据、分页、生成主键获取和错误处理；应在应用仓库实现可测试适配层，不直接改
vendor/或框架源码。 store/application/common.php的get_ai_db()只覆盖 AI 库的库名、前缀、主机、账号和密码，没有覆盖端口；现有两套达梦测试实例使用不同端口，必须修正。初步扫描有约 34 个store文件使用该入口，ai_api中约 44 个文件通过旧名mysql_zhct访问 store 库或模型。连接名可以先保留作兼容别名，但实际驱动和目标库必须跟客户选型一致。- 代码中已定位 MySQL 专属写法：
ON DUPLICATE KEY UPDATE、INSERT IGNORE、DATE_FORMAT、FIELD、FIND_IN_SET、GROUP_CONCAT、IFNULL、SHOW COLUMNS，以及部分原生 SQL。优先逐处做参数化且有测试的方言适配，不进行全局字符串替换。 - 数据侧已知差异：17,797 个零日期转成
NULL；175 个ON UPDATE CURRENT_TIMESTAMP列未实现同等自动更新时间语义；17 个非唯一前缀索引改为整列索引；ENUM转VARCHAR。这些都要进入业务回归与后续 DDL 标准，不能把“行数一致”当作应用兼容。 - 现有 MySQL 跨库行为核查确认：现有代码已通过两条连接分别开事务并顺序提交，部分流程有订单号幂等或失败补偿，但并非统一的跨库原子事务。这是现有实现，不是达梦新增业务规则。兼容改造先保持 MySQL 成功路径的金额、状态、提示与 API 口径，再对两种数据库跑相同的异常测试；发现的既有部分提交风险单独按双引擎共用缺陷处理，不做 DM 专属业务改造。
三、目标技术结构
1. 部署时选型，运行时固定
每套部署提供 DB_VENDOR=mysql|dm，由交付环境注入两组连接：STORE_DB_* 与 AI_DB_*。两应用加载相同的客户选型，但各有自己的主连接，并保留必要的跨库连接。账号最小权限、密码只放私有配置/密钥管理，不进入 Git、日志和安装包示例。
启动健康检查必须输出已选数据库类型、脱敏目标和版本；两个连接都真实 SELECT 验证，失败则启动失败或明确报告不可用，禁止退回 MySQL、静默读空或误连另一个客户库。前端不做数据库类型分支，API 业务响应与数据形态应保持一致。
2. 两个框架各有可维护的 DM 适配层
为 ThinkPHP 5 和 ThinkPHP 6 分别封装达梦连接器与 SQL Builder；共用一份兼容行为规范和测试用例，而不是强行复用不兼容的框架代码。首个技术门禁是官方 PHP 驱动连通、参数绑定、事务、字段元数据、自动编号、分页及中文/CLOB 往返。MySQL 路径保持原连接器和现有 SQL 行为；达梦路径只在 DB_VENDOR=dm 激活。
逐类建立适配清单：
| 类别 | 必须验证的具体行为 |
|---|---|
| 连接/ORM | PDO 驱动加载、连接池、超时/重连、前缀、字段缓存、大小写、列名与类型回传、受影响行数 |
| 查询 | 分页/排序、IN、聚合、日期格式、去重、模糊匹配、空值、别名、保留字、原生 SQL |
| 写入 | 自增 ID/批量插入、忽略冲突或 upsert、默认值、更新时间、乐观/悲观锁、事务和回滚 |
| 数据 | 金额精度、日期/时区、零日期 NULL、布尔/枚举、空字符串、中文排序、长文本/JSON |
| 跨库 | store → AI、AI → store 的读取与双库写入；复现 MySQL 当前提交顺序、幂等/补偿与对账，再核对 DM 差异 |
3. 双轨数据库变更
后续版本的每一个逻辑数据库变更都应有同版本的 mysql 与 dm 脚本（必要时分别为 store/ai_api），并在空库初始化、已有库升级两条路径执行。禁止把 MySQL DDL 原样发送给达梦，也禁止应用启动时偷偷改表。每次升级保留前置条件、目标版本、幂等或防重入规则、备份/回滚说明和双引擎验证记录。
四、实施顺序与每阶段交付门禁
| 阶段 | 交付切片 | 完成门槛 |
|---|---|---|
| P0 事实盘点与驱动 PoC | 冻结 PHP/DM 版本；枚举全部数据库连接、原生 SQL、DDL、定时任务、跨库写入；以现有 MySQL 成功路径和异常路径建立基线；两版本 PHP 在隔离容器中加载匹配 PDO_DM |
两应用均可分别连本次两套达梦测试库；参数、事务、中文/大字段/自增/字段信息的最小测试通过；产出逐文件改造清单。驱动不兼容即停止应用改造，不用未验证第三方驱动替代 |
| P1 连接与只读链路 | 实现两框架 DM Connector/Builder、部署配置和跨库连接；首条纵向链路选登录→权限→人员/餐单查询 | MySQL 5.6 与 DM8 各跑一次同一套 API 契约测试；响应字段/类型/数据范围一致；数据库断连明确报错 |
| P2 核心写入链路 | 按餐单/菜品→下单/结算→卡务/余额/补贴→AI 推荐的业务顺序改造，每条先冻结 MySQL 行为再复现于 DM | 两引擎分别通过成功、重复请求、权限、并发、单库/跨库失败与重试测试；金额与订单状态逐条对账；既有缺陷双方共修并单独评审，不得调用真实支付或真实设备产生副作用 |
| P3 长尾与运维链路 | 报表/导出、定时任务、批处理、设备/API、审计和所有版本 SQL；补齐 175 列更新时间策略及数据边界 | 双引擎功能矩阵无 P0 未测项；报表和异步导出结果同口径；空库安装与升级演练通过 |
| P4 发布验收 | 同代码版本、两套部署包/配置模板；压测、备份恢复演练、安全检查、回滚演练与交付文档 | MySQL 5.6 既有核心回归零退化，DM8 核心场景 100% 通过；无未关闭 P0/P1 缺陷；达到项目约定 SLA 后才能声明“双数据库兼容” |
优先完成 P0 后再给出可信工期和人天；当前没有全量 SQL 清单、驱动 PoC 和性能基线，直接承诺总工期不可靠。建议以 2 名后端（store、ai_api 各一名）、1 名测试和 1 名交付/DBA 参与 P0/P1 评审；后续投入按改造清单确定。
五、双数据库验收矩阵
同一 Git 提交、同一应用接口契约，分别部署到独立的 MySQL 5.6 与 DM8 测试环境。每个用例记录 tested-pass、tested-fail、not-tested 或 not-applicable，保留请求/响应脱敏对比、SQL/日志、数据前后值和代码版本。
| 场景 | MySQL 5.6 | DM8 | 关键断言 |
|---|---|---|---|
| 启动、登录、角色/门店权限 | 必测 | 必测 | 不串客户/门店，错误时不返回空成功 |
| 菜品、餐单、人员、营养推荐 | 必测 | 必测 | 数据过滤、日期和排序、中文/长文本同口径 |
| 下单、结算、卡务、余额、补贴/退款 | 必测 | 必测 | 金额精度、状态、幂等、双库失败恢复一致 |
| 列表、分页、汇总、异步导出 | 必测 | 必测 | 总数、金额、字段、排序与导出一致 |
| 定时任务、批处理、设备回调 | 必测 | 必测 | 不重复写、可重试、可审计；外部副作用隔离 |
| 初始化、升级、备份/恢复、断连 | 必测 | 必测 | 可重复安装/升级，失败可恢复，密码不泄露 |
性能阈值应先在同规格环境测得 MySQL 基线，再由业务方签订并发、数据量、p95 延迟、错误率和持续运行时间；不能用“运行起来了”代替性能验收。测试覆盖至少包括零日期转 NULL 的生日/餐单分支、枚举约束、前缀索引查询、跨实例事务和 ON UPDATE 更新时间。
六、AI 可执行 Use Case 草案
UC-DBCOMPAT-001：交付人员为客户选择数据库并运行智慧餐厅。 版本 v0.2；状态 Draft；DoR: BLOCKED（技术验证项未关闭）。
- 角色/触发：交付人员在新客户部署时选择 MySQL 5.6 或 DM8，并提供 store、ai_api 两组连接；业务用户随后执行核心流程。
- 主流程 M1：校验数据库选型、驱动、两组连接与版本；M2：执行对应引擎的初始化/升级脚本；M3：启动 store 和 ai_api；M4：完成登录、菜品餐单读取、下单结算、营养推荐；M5：核对订单/余额/业务状态和审计。
- 分支 A1@M1：选择 MySQL 时保持既有驱动/SQL 行为；A2@M1：选择达梦时加载 DM 驱动和方言适配。两分支输出同一业务接口契约。
- 异常/恢复 E1@M1：任一连接/驱动不可用时停止部署并明确报错；R1@E1：修正配置后重新健康检查，不自动切到另一数据库。E2@M4：跨库写入一边成功一边失败；R2@E2：以现有 MySQL 代码的处理为对照进行故障注入，识别兼容差异和已有缺陷；不凭空规定新的达梦恢复规则。
- 验收 AC-001：同一版本分别在两引擎完成上述主流程，接口和数据状态同口径。AC-002：MySQL 5.6 既有回归全部通过。AC-003：数据库断连、重复请求和跨库中途失败可明确识别并恢复。测试：API/集成/E2E/故障注入各覆盖两引擎；性能阈值待签订。
- 已确认：客户部署两套业务库同选型；本轮只做可选择数据库的应用兼容，不做既有客户迁库。P0 技术待验证：跨库写入在隔离 MySQL/DM 环境中发生部分提交时的实测结果；正式支持的 DM 构建、OS/CPU 与 PHP 运行时组合；业务 SLA 和测试环境外部设备/支付替身。若发现现有 MySQL 行为存在缺陷，应作为两种数据库共用的修复议题，不由达梦适配者自行改业务口径。未关闭前不将 UC 标记 Ready，不创建或更新云效工作项。
七、评审与下一步
部署模式和“业务逻辑沿用现有 MySQL”已由用户确认，不再要求用户重新选择或设计业务规则。技术负责人应先核对 MySQL 当前跨库行为并在隔离环境验证关键失败点；随后在任务分支/独立 worktree 中实施 PoC，分别验证 PHP 7.3/7.4 达梦驱动和两框架最小读写。PoC 通过后输出逐文件风险清单、可排期任务和双库验收用例，再进入正式开发。业务代码与数据库在本方案阶段均未改动。
人审状态：待用户/技术负责人评审。认可的结论再进入开发任务；本文件中的待确认项不能由 Agent 猜测为既定规则。