当前版本：v20261109-1538
ob-migration 使用说明
====================

一、启动
1. 解压本包到任意目录
2. 双击 ob-migration.exe，浏览器自动打开 http://127.0.0.1:8000
3. 关闭黑色命令行窗口即停止服务
   （需要多人共用同一份配置时，见第五章「局域网共享模式」）

二、换新版本包时恢复配置（同一台电脑）
配置全部保存在 data\ob-migration.db 这一个文件里，换新包只需三步：
1. 解压新包
2. 把旧包目录里 data\ob-migration.db 拷贝到新包目录的 data\ 下
   （新包没有 data 目录就新建一个）
3. 双击新 exe，配置（数据源、链路映射、同步记录）全部保留

注意：
- 数据库密码是 Windows 本机加密（DPAPI）的，必须同一台电脑拷贝使用；
  换电脑则密码需重新输入，其余映射配置不受影响。
- 新版 exe 若改了表结构会自动升级老库，直接拷入即可。
- data\datax_jobs 是运行时缓存，无需拷贝。

批量核验与补建普通索引
----------------------
- 在「表资产台账」勾选需要核验的表，使用「检查索引」，确认实际源 Oracle 与目标 OB 数据源。
- 核验以数据库索引字典为准，不以 CREATE TABLE 导出是否附带 CREATE INDEX 为准。
- 比较映射后的索引列、顺序、方向及唯一性；同定义异名索引也视为已存在，不重复建立。
- 先检查并预览结果，只勾选确认缺失的普通索引补建。索引同名但定义不同、无效或特殊类型会明确提示，不自动删除、覆盖或重建。
- 本功能仅核对普通列索引，主键/唯一约束的支撑索引及特殊索引不在自动补建范围；“普通索引无缺失”不代表所有约束和特殊索引均完整。
- 补建会实际执行 CREATE INDEX 并回查；不删表、不重新搬数据、不修改表迁移状态或同步水位。大表请在合适窗口执行。
- 查询失败不是“没有索引”。若执行超时或回查失败，应先重新检查目标，再决定是否继续，不要盲目重复提交。
- 本功能需要运行机器同时可连接源 Oracle 和目标 OB，OB 沿用 JDBC 工具配置与相应权限。
- 新版修正了源与目标用户名相同（如 Oracle PUSH → OB PUSH）时原 Oracle 表被误标为 OB 原生的展示问题；不据此批量修改历史来源身份。

三、目录说明
- ob-migration.exe            主程序（双击运行）
- data\                       配置库所在目录（自动创建）
- tools\ddl-runner.jar        DDL 建表执行器（OB 建表通道）
- tools\oceanbase-client.jar  OB JDBC 驱动
- 页面"工具配置"里把 tools 下两个 jar 的路径配上即可使用结构迁移

四、生产环境（交易网）额外清单
- JDK（8 及以上）
- DataX（解压即用）
- ob_comparator（解压即用）

五、局域网共享模式（测试环境多人协作）
--------------------------------------
本模式下，同一内网的同事用浏览器访问同一份配置库，不用每人各拷一份 exe、
各登记一遍。生产环境请勿开启，保持单机模式。

开启步骤：
1. 双击 ob-migration.exe 启动，浏览器打开 http://127.0.0.1:8000
2. 进入「系统设置」→「局域网共享（多人协作）」，打开开关并确认
3. 关闭黑色命令行窗口，重新双击 exe 启动（该配置需要重启才生效）
4. 启动后窗口会打印「同事访问地址」，形如 http://192.168.1.20:8000，把它发给同事
5. 同事用浏览器打开该地址即可，无需安装任何软件

首次启动时若弹出 Windows 防火墙提示，必须勾选「专用网络」并点「允许访问」。
未弹窗、或当时误点了「取消」时，用管理员身份打开命令提示符执行下面这条命令：
  netsh advfirewall firewall add rule name="ob-migration" dir=in action=allow protocol=TCP localport=8000

端口与办公软件冲突时：在启动前把环境变量 OB_MIGRATION_PORT 设为其他端口（如 8080），
并同步把上面命令里的 localport 改成同一个端口。

注意事项：
- 本模式依赖运行 exe 的这台电脑：关机、休眠、或关闭命令行窗口，同事都会立刻无法访问
- 本程序没有登录鉴权，同网段任何人都能查看和修改配置，请确认所处网络环境可信
- 配置库仍是单个文件（data\ob-migration.db），当前数据目录可在「系统设置」查看
- 数据源密码用本机 Windows 加密保存，换到别的电脑需重新录入密码

关闭共享：在同一开关处关闭并重启程序，即回到单机模式（仅本机可访问）。

六、迁移登记册（同事提请求，本机自动执行）

让不装程序的同事也能发起迁移：他们在网页上提交「请帮我把某张表迁移到 OB」，
本机（跑着 exe 的这台）自动执行并把结果写回，同事在原页面看到状态。

开启方式：「系统设置」→「迁移登记册」
1. 选择「登记册放在哪个 OB 数据源」（登记册表会建在这个库里）
2. 选择「**源数据源（Oracle）**」——必填。一次请求要建表 + 搬数据，两者都要读源库：
   建表语句的字段是从源表结构实时读的，数据也从这里抽
3. 点「初始化登记册表」创建表（只需做一次；程序升级后若表缺列会自动补列，不会删表）
   这一步会同时写入表与列的中文说明，同事在 ODC 里打开这张表就能直接读懂各字段含义
   （包括状态、冲突策略等取值说明）。表已存在时重复点它会把说明重写一遍，
   所以旧版本建的表也可以用这个按钮补上中文说明。
4. 点「测试连接」确认能连上
5. 打开开关

一条请求做两件事，**建表 + 全量搬数据**，都成功才算完成：
- 先读 Oracle 表结构生成建表语句、在 OB 建表
- 再把源表数据全量搬进新表（表刚建好、里面没数据，所以必须全量；
  用增量会漏数据）
- 中途「建表已完成、数据同步失败」时，状态说明里会写清"表已经建好了"，
  别当成没迁成功而重复提交

同事在低代码页面上要填的（目前要求字段名新旧一致，需要改名请用程序里的迁移向导）：
- 源用户 / 源表名（Oracle 侧）
- 目标用户 / 目标表名（OB 侧）
- 目标表已存在时：跳过建表（默认，最安全）/ 先 DROP 再重建（会清空该表数据）
- 日后的同步方式：全量重导 / 增量更新（这条会写进台账，决定日终调度怎么抽这张表）

之后：
- 本机每隔一段时间（默认 60 秒）自动检查有没有新请求，间隔可在同一处调整，改完不用重启
  （一轮实际耗时略多于间隔：每轮至少起 1 个 Java 进程查 OB。程序已把「待办 + 在途」合并成
  一次查询、结构检查按 10 分钟节流，把每轮开销压到最低）
  ⚡ **自适应**：空闲时用你设的间隔；**一旦有请求在跑就自动切到 10 秒一轮** ——
  所以「等下一轮」只会在提交后的第一次出现，后续阶段（建表完成、搬数据完成）推进很快
- 程序会在 OB 上维护一张 **执行器状态表 `OBM_WORKER_STATE`**（单行）：记着上次/下次扫描时间、
  本轮处理条数与本轮异常。低代码页面读它就能显示「上次扫描 … · 下次 …」，
  并在执行器没跑时给出提示。代价是每轮多一次 OB 写入（这是"让人看得见"的必要成本）
- 想立刻验证，点「立即执行一轮」，下方会显示本轮统计 + **最近请求的状态与原因**
  （注意：后台每 60 秒会自动跑，手动点的时候请求常已被自动处理掉，
  那一轮统计显示 0 是正常的 —— 看下方的请求列表即可）

注意事项：
- 只有本机需要连 OB，其他同事不用装任何东西
- ⚠️ 登记册读写 OB 走的是 JDBC 通道，所以**本机必须装好 JDK，并在「工具配置」页配好
  ddl-runner.jar 与 oceanbase-client.jar 的路径**（两者在交付包的 tools 目录里）。
  若提示「ddl-runner.jar 不存在」，先去「工具配置」页核对路径。
  **共享模式下这些工具装在跑本程序的那台机器上，只装一次**，其他人不用装
- 登记册采取「不审核，校验通过即执行」。校验会拦下的主要是：源表在 Oracle 不存在、
  同一张表已有进行中的请求、标识填不全
- ⚠️ 建表是「先 DROP 再重建」，所以**目标表已存在时默认只搬数据、不建表**（不会清空数据）；
  要重建必须由发起人在表单里**显式选择**「已存在则重建」
- 台账里没有这张表时**不拒绝**：程序会自动登记一条，并**按源表列结构自动建立字段映射**
  （这样台账与快照里这张表的字段是完整的；读不到源表结构时会在状态里说明原因）
- 请求被拒绝时，拒绝原因会写回登记册，发起人能看到，不是静默失败

七、台账快照（让同事在低代码页面看到台账）

台账本来是存在本程序里的（data 目录下那个配置库）。为了让大家都能看，程序会把台账
推成 OB 上的一张**只读表**，低代码页面读它即可 —— 同事不用装本程序就能查表、看映射、
看迁移进度。

为什么用「快照」而不是把台账直接搬到 OB：台账内部关联很多张表（列表一查就 JOIN 五张表），
搬过去等于把整个数据层重写一遍；而大家真正需要的是「看得到」。所以这里只做单向推送。

开启方式：「系统设置」→「台账快照」→ 打开开关

- 程序每隔一段时间检查台账**有没有变动**，有变动才推；没变动不会重复推，不会白耗资源。
  检查节奏跟着「迁移登记册」的轮询间隔（默认 60 秒；正有任务在跑时约 10 秒一轮）
- 能识别的变动包括：表描述 / 模块归属 / 跑数三字段 / 备注等台账字段，**字段映射（含字段描述）**、
  增量策略、写入者、存储过程编译状态，以及新增、删除对象
- 想立刻看到效果：点「立即推送一次」（忽略变动检测，强制推一次）
- 第一次点会顺便把快照表建好（幂等，可重复点）
- ⚠️ 只打开「台账快照」、不开「迁移登记册」也能自动推送（v20260930 起）。
  更早的版本必须两个都开，否则改完不会自动推 —— 如果发现"改了页面上一直没变"，先点一次
  「立即推送一次」，或把登记册开关也打开

注意事项：
- **低代码页面只能读这张表**。数据是程序先清空、再整批写入的，页面写进去的数据
  下次推送就会被抹掉。同事想改台账走第八章的「变更申请」，不要直接改表
- 快照表与登记册表放在**同一个 OB 数据源**（复用登记册里选的那个）
- 推送需要连 OB，同样依赖 JDK 与两个 jar 的配置（见第六章的注意事项）
- 推送的是**两张表**：台账主表（每行一张表）+ 字段映射子表（每行一个字段映射）。
  后者对应程序里台账「详情」里的那张子表，同事点进去能看到源字段/目标字段/类型/主键等

八、台账变更申请（同事改台账的唯一通道）

台账快照是只读的，所以同事改台账不能直接改表 —— 那样下次推送就被抹掉。
他把「哪张表、哪个字段、改成什么」提交到 OB 的 OBM_LEDGER_CHANGE，本程序认领后
应用到台账，**再自动推回快照**（所以他刷新页面就能看到新值）。

开启方式：「系统设置」→「台账变更申请」→ 打开开关 → 点「初始化变更申请表」建表

- 建表时会写入**完整的字段中文说明**（含允许改哪些字段、枚举取值），
  同事在 ODC 或低代码平台上打开这张表就能读懂，不用回来翻文档
- 允许同事改的字段（11 个）：二级业务模块、表描述、备注、生成逻辑来源、迁移后逻辑来源、
  逻辑迁移状态、生成方标识、迁移后标识、增量策略、ID 策略、增量列。
  目标表名、目标用户、源表名、迁移状态仍不开放修改。
- 整单申请固定 FIELD_NAME=BATCH，十一 NEW_ 参数全部必传，不需要 OLD_ 原值。
  新三项从快照 INCREMENT_STRATEGY / ID_STRATEGY / INCREMENT_COLUMN 回显；未修改项也完整提交，
  不得默认为空或擅自补默认策略。后处理的整单覆盖先前值，不做原值冲突检查。
  文本空值清空、分类填0清空、原三个业务枚举不能为空；任一新值非法整单拒绝，异常整单回滚。
  TABLE 的增量策略必须为 TIMESTAMP / PK_COMPARE / FULL_RELOAD，ID 策略必须为
  TSEQUENCE / SEQUENCE / NONE，两个策略均非空。
  TIMESTAMP 必填增量列：普通 Oracle 列标识符，最长60字，字母（含合法中文）开头，拒绝Oracle保留字；后续仅字母、
  数字、下划线、$、#；不接受带引号列名、表名前缀或表达式。非 TIMESTAMP 可传 SQL NULL 清空列。
  非 TABLE 且无映射时，增量策略和增量列两个 NEW_ 均传 SQL NULL（仍须绑定参数），不创建表映射，
  ID 策略仍需回显并提交合法值。
  TARGET_OWNER/TARGET_NAME只读核对，按OBM_LEDGER_SNAPSHOT_ID定位；兼容OLD_列不能删除。
  FIELD_LABEL 隐藏固定“台账信息整单修改”，REASON 选填。
- 旧单字段申请仍支持 FIELD_NAME/OLD_VALUE/NEW_VALUE，并保留旧值冲突检测。
  原八项旧单字段申请保持兼容，新页面统一使用十一项整单，不要混用两套载荷。
- 升级时先暂停旧表单提交及处理，备份配置并升级程序，再点初始化变更申请表：
  原八项版本37列表本轮新增三组OLD_/NEW_共6列VARCHAR2(1000)，成为43列；所有原列保留。
  更早的旧表也需检查升级SQL保留的原17个补列项，已存在的列跳过。初始化可重复执行并刷新注释。
  随后在低代码平台刷新数据模型、升级十一项表单及绑定，并推送最新快照。
  旧八NEW表单和待办不能自动补默认值继续覆盖，须升级后重读快照、由用户确认十一项并重新提交。
- 此申请只改台账及后续迁移配置，不对真实业务表执行ALTER、建表、创建序列或修改COMMENT，
  不搬数据，也不会重置同步水位；先暂停相关同步并等待在途任务完成，再修改策略或增量列，
  核对现有水位、数据范围和任务配置后恢复同步。
  初始化申请表自身所需的DDL不属于业务表变更。
- 校验不通过走 REJECTED，失败原因原文写回 STATUS_MSG —— **页面上必须把它显示出来**，
  否则同事不知道该怎么改（打回原因都是可自助处理的：值填错、选到一级模块、旧值过期）
- 处理速度与登记册相同（同一套轮询）：提交后最多约 1 分钟内应用完

⚠️ 页面开发要点见交付包里的 docs/lowcode-ledger-change-page.md

九、生成来源与迁移后来源（迁移登记册和变更申请统一）

两侧均为七类来源加「待确认」，页面显示中文，提交及数据库保存英文编码：
生成来源编码       迁移后来源编码    统一显示名称
APP_WRITE          APP_TO_OB         CRM自身业务操作写入
ORACLE_JOB         OB_JOB            Oracle调度算出（迁移后为OB调度算出）
XXLJOB             XXLJOB_TO_OB      XXL-JOB计算
JAVA               JAVA_TO_OB        Java程序计算／写入
HIVE_TO_ORACLE     HIVE_TO_OB        Hive计算后同步
EXTERNAL_PUSH      EXTERNAL_TO_OB    外部系统推送
ONETIME_INIT       ONETIME_IMPORT    一次性初始化
UNKNOWN            UNKNOWN           待确认

- 上表仅为分类对照，不是自动转换规则；原有来源编码与历史记录保持不变。
- JAVA、JAVA_TO_OB、OB_JOB 仅记录台账信息，不代表本工具执行Java程序或OB调度；
  不自动改来源、推荐映射、调度或同步规则。
- OBM_REGISTER 的 COMPUTE_SOURCE / TARGET_COMPUTE_SOURCE 为选填，未填不改台账；
  填写时必须为合法编码，只补台账默认值，不覆盖已有人工盘点结果。
- OBM_LEDGER_CHANGE 的单字段申请及 FIELD_NAME=BATCH 整单都接受新编码；
  整单仍须完整提交全部十一项 NEW_，来源枚举不能为空，不改原有冲突与事务规则。
- 来源 UNKNOWN 显示「待确认」；逻辑迁移状态 UNKNOWN 仍显示「未盘点」，两者不要混淆。
- 升级后分别点「初始化登记册表」「初始化变更申请表」刷新既有表中文注释，
  不删表、不改历史来源；随后刷新低代码数据模型及两处来源下拉字典。
- 登记册低代码配置见 docs/lowcode-register-page.md，统一字典及变更申请载荷见
  docs/lowcode-ledger-change-page.md；建表/升级SQL见对应 obm-register-ddl.sql、
  obm-ledger-change-ddl.sql、obm-ledger-change-upgrade.sql。

十、表资产的数据库来源身份（2026-11-09）

- “原Oracle表”不再根据源/目标用户名是否相同推断；真实同用户名迁移仍显示源表。
- 台账编辑增加数据库来源身份：Oracle来源、OB原生、来源待确认；它与第九节的业务生成来源不是同一个字段。
- 旧版本未保存身份，升级后历史记录先为“来源待确认”，保留原登记值和字段映射，不冒充已确认的Oracle来源。
- 对已确认仅在OB创建的表（如CRM.TLBL_CLAS），在台账编辑中选“OB原生”并保存；Oracle迁移表确认“Oracle来源”，核对源用户和源表名。
- 只确认身份不会清理字段映射、重置迁移状态或同步水位；若实际修改源用户/表名，仍按既有改源规则清理旧字段映射并重置迁移状态。
- 未选择Oracle数据源、查询失败、查无同名候选或候选歧义均不自动证明OB原生；重新扫描不覆盖已确认身份。
- 本次SQLite配置库升级到v15；旧v14配置可升级导入，新v15配置不能交给旧v14程序打开，两端程序需同步升级。
- 低代码业务来源字典与十一项修改申请协议不变；来源身份目前由工作台编辑确认，不给OB申请表或快照表自动新增列。
