4. 数据模型与对象映射
迁移项目最容易在“看起来已经搬完”之后翻车：数据都在，但用户发现原来能提交的缺陷类型不见了、审批流跳过了合规节点、某个字段在目标实例里变成了自由文本、Confluence 页面虽然导入成功却把机密内容暴露给了全公司。这些问题的根因通常不是工具能力不足，而是源端与目标端的数据模型没有建立显式映射。本节把 Jira 与 Confluence 的映射拆成可执行的对照关系，并给出判断映射是否成立的依据。
一、先建立“模型对齐”而不是“字段对齐”
对象映射的起点是理解两端模型的结构差异。Jira 的核心模型是项目 → 问题类型 → 工作流 → 字段 → 权限方案，其中问题类型决定可用字段与工作流，工作流由状态、转换、条件、校验器、后置函数组成，权限方案通过项目角色与用户组控制“谁能看、谁能改、谁能转”。Confluence 的核心模型是空间 → 页面树 → 页面 → 权限，权限由空间权限与页面级限制叠加，页面还带有版本、附件、标签、评论等附属对象。
因此映射设计要回答三个问题：对象是否等价（问题类型对页面类型？）、行为是否等价（工作流转换对页面状态？）、可见性是否等价（权限方案对空间权限？）。只有三者都对齐，迁移后的使用体验才与源端一致。
二、Jira 侧映射：问题类型、工作流、字段、权限方案
问题类型映射不是简单改名。源端可能有 Bug、Story、Task、Sub-task、Epic、Change Request、Incident 等，目标端若采用标准方案，需要决定哪些保留、哪些合并、哪些转为标签。例如源端“Change Request”与“Incident”都走审批流，目标端若只保留“Task”，就必须把原类型写入标签（如 legacy-type:change-request），否则历史筛选器与报表会失效。判断依据是：迁移后按原类型过滤是否还能得到相同结果集。
工作流映射要处理状态名、转换路径与校验规则。源端状态可能是“待处理 → 处理中 → 待验证 → 已关闭”，目标端若简化为“To Do → In Progress → Done”，则“待验证”需要映射为 Done 并附加验证标签，或保留为自定义状态。更关键的是转换条件：源端“仅项目负责人可关闭”在目标端若丢失，合规性就被破坏。建议在迁移前导出工作流 XML，逐条比对条件、校验器、后置函数，并记录哪些被保留、哪些被替代。
字段映射需要区分系统字段与自定义字段。系统字段（摘要、描述、经办人、报告人、优先级、截止日期）通常可直接对应；自定义字段则要判断目标端是否已存在同名字段、类型是否一致（文本、单选、多选、日期、用户选择器、级联选择）。类型不一致时不能强行导入，例如源端“影响版本”是单选，目标端是版本选择器，就需要转换值域。字段上下文也要检查：某字段在源端仅对 Bug 可见，目标端若对所有类型可见，界面会变得混乱。
权限方案映射是风险最高的部分。Jira 权限方案由“权限类型 + 授予对象（组/角色/用户）”组成，目标端若采用不同角色模型，必须建立组映射表。例如源端 jira-developers 拥有“转换问题”权限，目标端对应组为 dev-team，则需在目标权限方案中为 dev-team 授予 Transition Issues。判断映射是否成功的标准是：用典型用户账号分别登录源端与目标端，执行浏览、编辑、转换、分配四类操作，结果应一致。
三、Confluence 侧映射：空间、页面、权限
空间映射通常与 Jira 项目对应。若源端一个项目对应一个空间，目标端可保持 1:1；若多个小项目共用一个空间，则需决定合并后空间 KEY 与权限边界。空间 KEY 一旦确定，页面链接、宏引用、Jira 关联都会依赖它，因此要在迁移前冻结。
页面映射要处理页面树层级、页面模板、标签、附件与评论。源端页面若使用自定义模板，目标端需先创建对应模板再导入，否则页面会退化为普通页面。页面树层级若过深（超过 5 层），建议在迁移时扁平化，否则导航体验会变差。附件要检查大小限制与存储路径，评论要保留作者与时间戳，否则审计链断裂。
权限映射是 Confluence 迁移的难点。空间权限控制“谁能进入空间”，页面限制控制“谁能看某页”。源端若大量使用页面级限制，目标端必须逐页重建，不能只靠空间权限。常见做法是：先按空间权限做粗粒度映射，再对敏感页面单独设置查看限制。判断依据是：用受限用户账号访问原受限页面，应返回无权限，而不是内容可见。
四、映射设计交付物：映射对照表
建议在迁移前产出一份可执行的映射对照表，至少包含以下字段。下表为示例结构，具体值需按实际环境填写。
| 源端对象 | 源端值/示例 | 目标端对象 | 目标端值/示例 | 转换规则 | 验证方式 |
|---|---|---|---|---|---|
| Jira 问题类型 | Change Request | 问题类型 + 标签 | Task + legacy-type:cr | 合并类型，原类型写入标签 | 按标签过滤结果集一致 |
| Jira 工作流状态 | 待验证 | 状态 + 标签 | Done + pending-verify | 保留语义，附加标签 | 状态分布报表一致 |
| Jira 自定义字段 | 影响版本（单选） | 版本选择器 | Fix Version | 值域映射，缺失值置空 | 抽样 20 条比对值 |
| Jira 权限方案 | jira-developers 可转换 | 项目角色 | dev-team 可转换 | 组映射表转换 | 典型账号操作比对 |
| Confluence 空间 | OPS 空间 | 空间 | OPS（保持 KEY） | 1:1 保留 | 空间首页可访问 |
| Confluence 页面限制 | 仅 HR 组可查看 | 页面查看限制 | hr-team 可查看 | 组名映射后重建 | 受限账号不可见 |
映射设计完成后，应组织一次“小批量试迁”：选取 1 个 Jira 项目与 1 个 Confluence 空间，按映射表执行迁移，然后用典型用户账号验证浏览、编辑、转换、搜索、权限五类行为。只有试迁结果与源端一致，才把映射规则固化到全量迁移脚本中。映射表本身也应纳入版本管理，后续每发现一个边界情况就补充一行，避免同类问题重复出现。