迁移的内容¶
本页列出工具通过 REST API 从 Jira 读取的内容，以及每一部分如何变成 Specivo 中的记录。未列在此处或只部分迁移的内容，见 未迁移的内容，并计入导入包的清单（manifest）。
项目、工作项类型、状态和优先级¶
| Jira | Specivo |
|---|---|
| 项目键、名称、描述 | 项目，项目标识、名称和描述与 Jira 相同。公司管理项目和团队管理项目均如此。 |
| 工作项类型 | 追踪器（Tracker）。每个追踪器的默认状态，取其多数工作项的初始状态。 |
| 状态 | 状态，并带有类别：“待办”对应 backlog，“进行中”对应 active，“完成”对应 closed（可用 --status-category-map 更改）。 |
| 优先级 | 优先级。 |
工具会迁移导出的工作项（Issue）所使用的类型、状态和优先级，也包括只在变更历史中出现过的那些。团队管理项目有自己的工作项类型和状态，所以它们是独立的记录，与 Jira 中一样。加载时加上 --merge-duplicate-statuses，可把与现有记录同名的状态合并。
工作项¶
| Jira | Specivo |
|---|---|
| 概要 | 主题 |
| 描述 | 描述，转换为 Markdown（见 文本如何转换） |
| 工作项类型、状态、优先级 | 追踪器、状态、优先级 |
| 报告人 | 作者 |
| 经办人 | 负责人 |
| 创建时间、更新时间 | 创建和更新时间，原样保留 |
| 解决日期 | 关闭日期 |
| 截止日期 | 截止日期 |
| 安全级别或工作项限制 | 私有工作项。详情保留在工作项的 extra 数据中。 |
| 工作项键、解决结果名称 | 保留在工作项的 extra 数据中。导入包没有对应的属性。 |
工作项按键的顺序写入，Specivo 也按同样的顺序编号。已删除或已移走的工作项的键不会在 Specivo 中留下空号，所以空号之后的编号可能与 Jira 不同。
人员¶
出现在导出工作项中的用户都会迁移：报告人、经办人、评论和变更的作者、关注者，以及文本中提到的人。停用的用户也会迁移，作为锁定账户。应用账户（自动化规则、集成）不是人，不予迁移；它们写的内容归到 Specivo 的导入账户名下。
如果某个 Jira Cloud 账户的所有者对执行导出的账户隐藏了邮箱地址，该账户会不带邮箱写入。Specivo 会给它分配一个永不收信的占位地址，并在导入报告中列出，方便管理员补上真实地址。登录名取自邮箱地址，没有邮箱则取自显示名称。
评论¶
评论连同作者和时间一起迁移。仅限某个角色或用户组查看的评论会变成私有备注。完整列表通过专门的分页接口读取，因为 Jira 嵌在工作项里的评论列表是截断的。已编辑和已删除的评论也会得到处理。
变更历史¶
历史会变成 Specivo 的历史记录条目，保留原作者和时间。
| 变更 | 迁移方式 |
|---|---|
| 状态、经办人、优先级、概要、工作项类型 | 记录为带新旧值的变更。指向某条记录的值（如状态、经办人）会链接到 Specivo 创建的对应记录，并按名称显示。如果该记录没有迁移过来，Specivo 显示 Jira 当时显示的名称。 |
| 添加和删除附件 | 附件的 id 和文件名，无论文件是否仍然存在。 |
| 初始预估 | 预估的变更，以小时计。 |
| 修复版本、组件 | 目标版本和类别的变更，遵循下文的“单值”规则。每次变更之前的列表，由工作项当前的列表沿历史往回推算得出。没有改动所选值的变更不会写入任何内容。 |
| 父级、长篇故事链接 | 父工作项的变更。 |
| Sprint | 工作项冲刺的变更，仅当下文的“单冲刺”规则选出了另一个冲刺时才写入。 |
| 自定义字段 | 字段的变更，以字段名称记录。 |
| 已用时间、剩余预估、工作日志 id | 不写入：它们可由迁移过来的工作日志推出。跳过且不计数。 |
| 标签及其他字段 | 计入清单。 |
工作项的完整变更历史通过该工作项自己的分页接口读取。
附件和内嵌图片¶
每个工作项的附件连同作者、时间、文件名和 MIME 类型一起迁移。文件内容存入导入包的 files/ 目录，内容相同的只存一份，以 SHA-256 命名（绝不使用它在 Jira 中的文件名）。
- 同一个工作项里有多个同名文件时，后面的会加编号（
image (2).png），因为 Specivo 把文件名链接到该名称最新的附件。Jira 中的原文件名保留在附件的extra数据中。 - 超过
--max-attachment-size的文件、Jira 拒绝提供的文件（403）以及 Jira 已不再保存的文件（404），会按原因分别计入清单。 - 描述和评论中显示的图片和文件会指向工作项的附件。见 文本如何转换。
工作项链接¶
每个 Jira 链接变成一条关联（Jira 在链接两端的工作项上都列出该链接，工具只写一次）。
| Jira 链接类型 | Specivo 关联 |
|---|---|
| Blocks | blocks |
| Duplicate | duplicates |
| Cloners | copied_to（被克隆的工作项“复制到”其克隆） |
| Relates | relates |
| 其他任何类型 | relates，Jira 中该类型的名称保留在关联的 extra 数据中，并按类型计数 |
方向与 Jira 显示的一致。链接指向的工作项如果属于导出到另一个导入包的项目（或超出了 --limit），仍然会作为关联写入，并以 id 指明对方工作项；持有这两个工作项之一的每个导入包都以相同的链接 id 携带该关联，Specivo 在两个工作项都导入后只创建一次。链接指向的工作项如果在 Jira 中已不存在，则计数并保留在工作项的 extra 数据中。
父工作项¶
子任务的父级，以及长篇故事（Epic）的子项，都变成子工作项的父工作项，跨项目也是如此。在 Jira Cloud 上，无论公司管理项目还是团队管理项目，两者都是 parent 字段。在 Data Center 和较旧的 Cloud 站点上，长篇故事的子项通过 Epic Link 字段指向它，读取方式相同。
不在导入包中的父级以其 Jira id 写入，Specivo 在两个工作项都导入后再设置父子关系。Epic Link 只以键指明长篇故事，所以导入包之外的长篇故事的键需要到 Jira 中查询（使用 --no-resolve-keys 时不查询）。Jira 找不到的父级会计数并保留在工作项的 extra 数据中。
工作日志¶
工作日志变成所属工作项和项目上的工时记录（项目会随之启用工时记录），保留作者和时间，并统一归入一个活动类型 开发，因为 Jira 的工作日志没有活动类型。
- 工时发生的日期，是工作日志开始时间在其作者所在时区的日期（即 Jira 显示的那一天）；作者没有时区时，则按 Jira 给出的时差计算。
- 小时数为已用时间四舍五入到百分之一小时，这是 Specivo 保存的精度。四舍五入改变了数值时，原始秒数保留在
extra中。不足 18 秒的工作日志会被舍为零并计数。 - 工作日志的备注为纯文本。
- 仅限某个用户组或角色查看的工作日志，保留工时但不保留备注：Specivo 会把工时记录展示给所有能查看该项目工时的人。限制信息保留在
extra中，被省略的备注计入报告。 - 受限工作项上的工作日志同样保留工时但不保留备注：Specivo 把该工作项作为私有工作项导入，但其工时记录对所有能查看项目工时的人可见。
组件和版本¶
| Jira | Specivo |
|---|---|
| 组件 | 项目的类别；如果组件把工作项分派给其负责人且该负责人在导入包中，则带默认负责人 |
| 版本 | 带发布日期和描述的版本。已发布的版本变为已关闭，已归档的变为已锁定（不能再有新工作项指向它），其余为开放。开始日期以及“已发布”“已归档”标志保留在 extra 中。 |
Specivo 中每个工作项只有一个类别和一个目标版本。工作项的第一个组件成为其类别。修复版本中，最后发布的那个成为目标版本（都未发布时，取列表中最后一个）。有多个组件的工作项，以及未被选中的其他修复版本，都会计数，并全部记录在工作项的 extra 数据中。影响版本在 Specivo 中没有对应字段，同样计数并记录在 extra 中。
冲刺¶
Jira Software 的 Sprint 从每个项目的看板和工作项的 Sprint 字段读取。
| Jira | Specivo |
|---|---|
| Sprint 名称、目标 | 名称、目标 |
| 开始和结束日期 | 开始和结束日期（Jira 向执行导出的账户显示的日期，按该账户的时区） |
| 已关闭 Sprint 的完成时间 | 与冲刺的速率一起保留 |
| 状态：未来、活跃、已关闭 | 已计划、进行中、已完成 |
- 项目会获得位于其中的看板的 Sprint（包括尚无工作项的），以及其工作项所在的其他看板的每个 Sprint。
- Jira 看板可以跨项目，但 Specivo 的冲刺（Sprint）只包含本项目的工作项。多个项目共用的 Sprint 会在每个项目中各成为一个冲刺，名称和日期相同。此情况会计数。
- 每个工作项只属于一个冲刺。Jira 列出工作项曾经所在的所有 Sprint，Specivo 只保留一个。工作项归入其未结束的 Sprint（活跃或未来），没有则归入最后完成的那个。其余的记录在工作项的
extra数据中并计数。 - 每个项目只能有一个进行中的冲刺。第二个活跃 Sprint（并行 Sprint）导入为已计划状态。Specivo 会在导入报告中说明。
- 已完成冲刺的速率，在 Specivo 加载导入包时根据其工作项计算记录。
- 没有 Jira Software，或账户无权读取项目看板时，冲刺就是工作项所指明的那些。无法读取的看板会计数。
自定义字段¶
导出的工作项所使用的自定义字段，连同其值和历史一起迁移。Specivo 把它们存为工作项元数据。
| Jira 字段类型 | Specivo 自定义字段 |
|---|---|
| 文本字段、只读文本、用户组选择器和项目选择器 | 文本。用户组按名称，项目按键。 |
| 段落（文本区域） | 长文本，Markdown 格式 |
| 数字、故事点 | 数字（float） |
| 日期选择器、日期时间选择器 | date、datetime |
| 选择列表、单选按钮 | list，并列出其选项 |
| 多选列表、复选框 | list，多个值 |
| 选择列表（级联） | list，值的形式为 Parent / Child |
| 用户选择器（单选和多选） | user，以用户的 ref 引用 |
| 版本选择器（单选和多选） | version，以版本的 ref 引用 |
| URL | link |
| 标签字段 | 文本，多个值 |
需要注意：
- Specivo 在工作项页面、历史记录、筛选、REST API 和 MCP 中都以字段的 Jira 名称显示字段，无论名称使用何种文字。用户或版本类型的值，对有权查看该用户或版本的读者按名称显示。
- 存储值所用的键是字段名称的蛇形命名（snake case）形式；名称无法用 ASCII 表示时，则用字段的 id。两个字段的名称生成同一个键时，两者都会加上各自的编号。
- 值原样存储，不带链接：段落中的提及显示为
@Name，工作项键仍是纯文本。指向应用账户的值，或不属于本项目的版本，会被省略并计数。 - 字段适用的范围。在 Jira Cloud 上，由字段的上下文决定：全局上下文使其成为所有项目的字段，否则只适用于上下文指明的项目和工作项类型，再加上其工作项持有值的项目。读取上下文需要 Administer Jira（管理 Jira）权限。Jira 拒绝时（会计数），以及在 Data Center 上，字段适用于其工作项使用了它的项目。团队管理项目自己的字段只适用于该项目。
- 选项类字段的选项，取其上下文中的选项（包括已禁用的），再加上工作项和历史中出现的值。
- Jira 为自身界面保留的字段，以及导入包以其他方式携带的字段，会被省略且其值计数：Rank、Sprint 和 Epic Link（分别作为工作项的冲刺和父工作项迁移）、长篇故事的名称、颜色和状态、Team、Development、Parent Link、计算字段，以及应用自有类型的字段。
标签¶
Jira 的标签变成工作项的标签。Specivo 的标签属于项目，而 Jira 的标签属于使用它的工作项，所以一个标签会在每个有工作项使用它的项目中各成为一个标签。只有大小写不同的名称视为同一个标签，拼写以第一次出现的为准。超过 64 个字符（Specivo 的上限）的标签会计数并保留在工作项的 extra 数据中。标签类型的字段则作为自定义字段处理，其值与标签分开。
Specivo 不保留标签的历史，所以历史中的标签变更只计数，不迁移。
关注者¶
关注者按 Jira 列出的读取（只读取关注数大于零的工作项）。列出关注者需要 Jira 的 View voters and watchers（查看投票者和关注者）权限。Jira 拒绝时，该工作项的关注数会计数，导出继续；Jira 只计数而不列出的关注者，以及应用账户，同样计数。无论如何，Specivo 都会把工作项的报告人和负责人设为关注者。
预估¶
| Jira | Specivo |
|---|---|
| 初始预估 | 工作项的预计工时，以小时计，四舍五入到百分之一。为零的预估保持为零。 |
| 剩余预估 | 工作项的剩余预估，同样的舍入规则。工作项可以只有剩余预估而没有初始预估。 |
四舍五入改变了数值时，原始秒数记录在工作项的 extra 数据中（jira_original_estimate_seconds、jira_remaining_estimate_seconds）。Specivo 按给出的值存储剩余预估，不从工时记录推算，也不保留其历史，因为 Jira 每记一条工作日志就会重写它。
标识符¶
每条记录的来源引用都是 Jira 自身永不变化的 id：工作项用 id（10042）而不是键，因为工作项移动或项目改名时键会变；项目用项目 id；用户用 Cloud 账户 id 或 Data Center 用户键；历史记录条目用 comment:<id> 和 history:<id>。正因如此，之后再次导出同一站点时才能只添加新增内容。