工作项与协作属于项目中心，由 yudao-module-pms 后端模块的 pm.workitem 包实现，前端实现在 @/views/pms/pm/workitem 目录。

工作项是项目执行过程中可以被分配、跟踪和验收的最小业务单元。通用项目只使用「任务」，敏捷开发项目同时使用「需求」「任务」「缺陷」；工作项的状态、负责人、迭代和协作记录都以项目编号为边界。

• 工作项列表：按事项类型、状态、优先级、迭代、负责人和标签查询，并在列表和看板之间切换。
• 工作项协作：在详情抽屉中维护描述、附件、评论、动态、子工作项和工时。
• 状态与看板：为每种工作项类型维护状态语义、初始状态和看板列，拖拽时分别保存列内顺序和规划顺序。
• 导入与生命周期：支持 Excel 导入导出、归档、回收站和恢复；彻底删除只允许作用于回收站中的工作项。

本文涉及表如下图所示：

1. 工作项

工作项，由 PmsWorkItemController 提供接口（/pms/pm/work-item）。

1.1 主表表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `pms_work_item` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '工作项编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `assignee_user_id` bigint DEFAULT NULL COMMENT '负责人用户编号',
  `iteration_id` bigint DEFAULT NULL COMMENT '所属迭代编号',
  `parent_id` bigint DEFAULT NULL COMMENT '父工作项编号',
  `related_requirement_id` bigint DEFAULT NULL COMMENT '关联需求编号',
  `status_id` bigint NOT NULL COMMENT '看板状态编号',

  `type` int NOT NULL COMMENT '工作项类型',
  `serial_number` int NOT NULL COMMENT '项目内工作项序号',
  `name` varchar(100) NOT NULL COMMENT '工作项标题',
  `description` text DEFAULT NULL COMMENT '工作项描述',
  `priority` int NOT NULL COMMENT '优先级',
  `defect_type` int DEFAULT NULL COMMENT '缺陷类型',
  `file_urls` varchar(5000) DEFAULT NULL COMMENT '附件地址列表',
  `label_ids` varchar(5000) DEFAULT NULL COMMENT '标签编号列表',

  `start_time` datetime DEFAULT NULL COMMENT '开始时间',
  `end_time` datetime DEFAULT NULL COMMENT '截止时间',
  `estimated_hours` int DEFAULT NULL COMMENT '预估工时，单位：小时',
  `progress` int NOT NULL DEFAULT 0 COMMENT '完成进度，取值范围 0-100',
  `sort` int NOT NULL DEFAULT 0 COMMENT '看板内显示顺序',

  `status` int NOT NULL COMMENT '语义状态',
  `lifecycle_status` int NOT NULL DEFAULT 1 COMMENT '生命周期状态',
  `archive_time` datetime DEFAULT NULL COMMENT '归档时间',
  `recycle_time` datetime DEFAULT NULL COMMENT '回收时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项';

① project_id 关联 pms_project 表的 id 字段，assignee_user_id 关联 system_users 表的 id 字段，iteration_id 关联 pms_iteration 表的 id 字段，status_id 关联 pms_work_item_status 表的 id 字段。

② 枚举 type 工作项类型（PmsWorkItemTypeEnum）：2 需求、3 任务、4 缺陷。通用项目只允许任务，敏捷开发项目允许三种类型。项目创建时会为每种可用类型初始化状态和看板列。

③ 枚举 priority 优先级（PmsWorkItemPriorityEnum）：0 无、1 低、2 中、3 高。

枚举 defect_type 缺陷类型（PmsWorkItemDefectTypeEnum）：1 功能问题、2 界面优化、3 易用性问题、4 安全问题、5 性能问题、6 代码错误。defect_type 只允许缺陷填写。

④ serial_number 是项目内递增的业务序号，创建时取当前项目最大值加一；sort 是状态列内的显示顺序，跨列移动后由目标状态的最大顺序加一。两者都不是数据库自增主键。

⑤ status_id 指向当前项目、当前工作项类型的看板状态，status 保存该状态对应的语义状态快照（未开始、进行中、已完成）。修改状态时，两个字段和列内顺序一起更新。

⑥ iteration_id 只有敏捷项目可以填写；parent_id 自关联本表，只允许一级子工作项；related_requirement_id 只能关联同项目、处于正常状态的需求，需求本身不能再关联需求。

⑦ file_urls 和 label_ids 由 JacksonTypeHandler 映射为前端数组，分别保存附件地址和标签编号。标签名称、状态名称、负责人昵称等展示字段由 Controller 批量拼接，不在主表重复保存。

⑧ 枚举 lifecycle_status 生命周期状态（PmsWorkItemLifecycleStatusEnum）。详见 §1.2 状态流转。

---

该表包含八个子表：

• pms_work_item_status（工作项状态）：在【状态设置】弹窗中维护，保存语义状态、初始状态和看板映射，详见 §1.3 状态与看板列。
• pms_work_item_board（看板列）：在【状态设置 -> 看板配置】页签中维护，保存看板列名称和顺序，详见 §1.3 状态与看板列。
• pms_work_item_member（参与人）：随工作项保存，保存除负责人以外的协作成员，详见 §1.4 参与人与个人排序。
• pms_work_item_user_sort（个人排序）：在待规划区域拖拽时维护，保存当前用户的 Backlog 顺序，详见 §1.4 参与人与个人排序。
• pms_work_item_work_log（工时）：在详情抽屉的「工时」页签中维护，详见 §1.5 工时记录。
• pms_work_item_label（标签）：在【标签管理】弹窗中维护，可以被多个工作项引用，详见 §1.6 标签。
• pms_work_item_comment（评论）：在详情抽屉的「评论」页签中维护，支持一级回复，详见 §1.7 评论与动态。
• pms_work_item_activity（动态）：由后端自动写入的只读时间线，详见 §1.7 评论与动态。

1.2 状态流转

工作项有两套独立维度：语义状态（status）用于统计和颜色展示，生命周期状态（lifecycle_status）用于归档和回收。语义状态见 §4.1 状态语义，生命周期状态如下：

状态值	枚举	说明	可执行操作
1	NORMAL	正常（初始状态）	编辑、改状态、改迭代、协作、归档、移入回收站
2	ARCHIVED	已归档	查看、恢复、移入回收站
3	RECYCLED	回收站	查看、恢复、彻底删除

状态流转说明

创建 ──→ 正常(1) ──归档──→ 已归档(2)
           ↑ │                │
           │ └──移入回收站──→ 回收站(3) ──彻底删除（终态）
           └──────── 恢复 ──────┘

• 创建（createWorkItem）：Service 强制写入正常状态、该类型的初始看板状态、项目内序号和列内顺序，创建请求不能自行指定生命周期状态。
• 归档（archiveWorkItem）：只允许正常工作项，写入 archive_time。归档项只读，但仍可恢复或移入回收站。
• 移入回收站（recycleWorkItem）：正常或已归档工作项都可以移入回收站，保留原归档时间并写入 recycle_time。
• 恢复（restoreWorkItem）：已归档或回收站工作项恢复为正常，同时清空生命周期时间。要求项目仍处于进行中。
• 彻底删除（deleteWorkItem）：只允许回收站工作项，删除时会清理关联数据，详见 §6. 删除与关联清理。
• 项目锁定：项目归档或移入回收站后，所有工作项的编辑入口自动隐藏。

1.3 状态与看板列

pms_work_item_status 保存每种工作项类型的状态配置，pms_work_item_board 保存看板列本身。状态和看板列是两层关系：看板列通过名称承载多个状态，状态表的 board_name 保存映射。

工作项状态表 pms_work_item_status，保存每种工作项类型的状态及其看板映射：

CREATE TABLE `pms_work_item_status` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_type` int NOT NULL COMMENT '工作项类型',
  `name` varchar(50) NOT NULL COMMENT '状态名称',
  `status_type` int NOT NULL COMMENT '语义状态',
  `description` varchar(255) DEFAULT NULL COMMENT '状态描述',
  `board_name` varchar(50) DEFAULT NULL COMMENT '看板列名称',
  `system_code` varchar(20) DEFAULT NULL COMMENT '系统状态编码',
  `default_status` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否初始状态',
  `sort` int NOT NULL DEFAULT 0 COMMENT '显示顺序',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项状态';

看板列表 pms_work_item_board，保存看板列本身及其顺序：

CREATE TABLE `pms_work_item_board` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '看板列编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_type` int NOT NULL COMMENT '工作项类型',
  `name` varchar(50) NOT NULL COMMENT '看板列名称',
  `sort` int NOT NULL DEFAULT 0 COMMENT '显示顺序',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项看板列';

① work_item_type 与工作项 type 一一对应。同一项目下的需求、任务、缺陷各自拥有独立的状态集合和看板列，不能跨类型引用；同一项目、同一类型下的状态名称必须唯一。

② status_type 使用语义状态枚举。改变状态的语义类型时，Service 会同步更新引用该状态的工作项 status 字段。

③ default_status = 1 表示新建工作项的初始状态，同一项目、同一类型只能有一个初始状态；系统初始化时默认把「未开始」设为初始状态。system_code 用于识别系统状态，避免并发初始化时重复创建。

④ board_name 是状态到看板列的映射名称。为空时状态仍可用于流转，但不会在看板中展示；这些状态会出现在「未放入看板」区域。保存看板配置时，Service 先清空当前类型的旧 board_name，再按请求中的列和状态批量写入映射。

1.4 参与人与个人排序

pms_work_item_member 保存工作项参与人，pms_work_item_user_sort 保存待规划区域的个人排序。

参与人表 pms_work_item_member，保存除负责人以外的协作成员：

CREATE TABLE `pms_work_item_member` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_id` bigint NOT NULL COMMENT '工作项编号',
  `user_id` bigint NOT NULL COMMENT '后台用户编号',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项参与人';

个人排序表 pms_work_item_user_sort，保存当前用户的 Backlog 顺序：

CREATE TABLE `pms_work_item_user_sort` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_id` bigint NOT NULL COMMENT '工作项编号',
  `user_id` bigint NOT NULL COMMENT '后台用户编号',
  `sort` int NOT NULL DEFAULT 0 COMMENT '显示顺序',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项个人排序';

① work_item_id 关联 pms_work_item 表的 id 字段，user_id 关联 system_users 表的 id 字段。负责人保存在主表 assignee_user_id，参与人是可多选的协作关系。

② 保存工作项时，Service 会先删除旧参与人再按新集合重建。参与人必须是项目成员；创建时如果没有传参与人，Service 会把当前操作人加入参与人，避免工作项没有任何协作人。

③ 待规划区域的排序分两个维度：迭代内排序使用主表 pms_work_item.sort，由项目成员共享；Backlog 排序写入 pms_work_item_user_sort，只影响当前用户看到的顺序。

1.5 工时记录

CREATE TABLE `pms_work_item_work_log` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '工时记录编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_id` bigint NOT NULL COMMENT '工作项编号',
  `actual_hours` int NOT NULL COMMENT '实际投入工时，单位：小时',
  `remaining_hours` int NOT NULL DEFAULT 0 COMMENT '本次登记后的剩余工时，单位：小时',
  `description` varchar(500) DEFAULT NULL COMMENT '工时说明',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项工时';

① actual_hours 必须大于等于 1，remaining_hours 不得小于 0。登记和修改都要求工作项处于正常状态，且项目可编辑。

② 详情页的「已登记」是所有记录 actual_hours 之和，「剩余」取最新一条记录的 remaining_hours；没有登记记录时回退到工作项的预估工时。

1.6 标签

CREATE TABLE `pms_work_item_label` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '标签编号',

  `name` varchar(50) NOT NULL COMMENT '标签名称',
  `color` varchar(20) NOT NULL COMMENT '标签颜色',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项标签';

① 标签表没有 project_id，Service 按租户范围查询和校验；工作项仅在 label_ids 中保存编号。

② 新建或修改工作项时，Service 会校验 label_ids 中的编号全部存在。删除标签后，历史工作项中的编号保留，展示时自动忽略不存在的标签。

1.7 评论与动态

评论表 pms_work_item_comment，保存主评论和一级回复：

CREATE TABLE `pms_work_item_comment` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '评论编号',

  `work_item_id` bigint NOT NULL COMMENT '工作项编号',
  `user_id` bigint NOT NULL COMMENT '评论人用户编号',
  `main_id` bigint NOT NULL DEFAULT 0 COMMENT '主评论编号',
  `reply_user_id` bigint DEFAULT NULL COMMENT '回复对象用户编号',
  `content` varchar(2000) NOT NULL COMMENT '评论内容',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项评论';

动态表 pms_work_item_activity，保存由后端自动写入的只读时间线：

CREATE TABLE `pms_work_item_activity` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '动态编号',

  `project_id` bigint NOT NULL COMMENT '项目编号',
  `work_item_id` bigint NOT NULL COMMENT '工作项编号',
  `operator_user_id` bigint NOT NULL COMMENT '操作人用户编号',
  `content` varchar(500) NOT NULL COMMENT '动态内容',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB COMMENT='PMS 工作项动态';

① main_id = 0 表示主评论；回复必须填写同一工作项下的主评论编号。页面按主评论组织一级回复，不支持回复的回复。

② 评论的创建、修改和删除都要求工作项可编辑；修改和删除还要求当前用户是评论创建人。删除主评论时会同步删除其全部回复。

③ 动态表只读，不提供新增、修改和删除页面。动态由工作项 Service 在创建、编辑、改名、改状态、改迭代、归档、回收、恢复，以及评论和工时变更时自动写入。

2. 工作项列表与看板

工作项没有独立的左侧菜单。页面位于项目详情的隐藏路由 /pms/pm/project/detail/:id，activeMenu 指向「我的项目」，因此从 [PMS 项目管理 -> 项目中心 -> 我的项目] 进入项目详情后，左侧菜单仍保持高亮。

2.1 列表

项目详情的「需求」「任务」「缺陷」页签使用 WorkItemList.vue。通用项目只展示任务页签，敏捷项目按工作项类型分别展示三个页签。

页面顶部可以输入标题或编号搜索，点击【高级筛选】可以按数据范围（当前、已归档、回收站）、语义状态、优先级、迭代、排除迭代、负责人和标签筛选。列表中的状态下拉直接调用 updateWorkItemStatus，点击标题打开 WorkItemDetail.vue 抽屉，抽屉截图见 §4.2 详情抽屉。

列表右侧的【更多】菜单按权限显示【状态设置】【导入】【导出】。当前数据可以切换到「看板」模式，归档和回收站数据强制使用列表模式。项目不可编辑时仍可查看，但不显示创建、编辑和拖拽操作。

2.2 看板与拖拽排序

切换到「看板」时，getWorkItemBoard 先读取当前类型的看板列和状态，再只返回一级工作项。没有配置 board_name 的状态不会生成看板列，但仍可通过列表和详情切换。

看板列可以包含多个状态，列内会按状态拆分投放区，避免工作项拖入合并列后静默落到第一个状态。拖拽跨列时先调用 updateWorkItemStatus，再在没有筛选条件时调用 updateWorkItemSort；筛选结果只更新状态，不把不完整的列表写回排序。

待规划看板由项目详情的 PlanningBoard.vue 处理，详见 《【项目中心】项目详情与迭代》。

2.3 全部事项

敏捷项目详情的「全部事项」页签使用 WorkItemAllList.vue，支持标题搜索，以及事项类型、语义状态、优先级、迭代、排除迭代、负责人、标签和「只显示未规划事项」筛选。

表格展示编号、类型、标题、状态、优先级、负责人、所属迭代、进度和截止时间，点击标题打开同一详情抽屉。点击右上角【新建】时，敏捷项目可以选择需求、任务或缺陷，通用项目只显示任务入口；后端仍会再次校验项目类型和工作项类型。

3. 新增、编辑与导入导出

3.1 新增

点击【创建任务】【新建需求】或【新建缺陷】打开 WorkItemForm.vue。项目编号、项目类型、工作项类型和可选迭代由项目详情页传入。

表单字段包括标题、优先级、负责人、开始时间、截止时间、所属迭代、父级工作项、关联需求、缺陷类型、预估工时、进度、参与人、标签、描述和附件；创建时还可以一次填写多个子工作项，以及实际投入和剩余工时。

① 通用项目隐藏迭代、关联需求和缺陷类型；敏捷项目的任务、缺陷可以关联需求，需求不显示关联需求字段；缺陷类型只对缺陷必填。

② 子工作项沿用父项类型、迭代和状态，不能继续创建孙级工作项。

③ 生命周期状态、初始看板状态和项目内序号都由后端写入，创建请求不能自行指定；负责人不是当前操作人时，会发送工作项指派站内信。

3.2 修改与快速操作

列表点击【编辑】或详情抽屉点击【编辑】都会打开同一个 WorkItemForm.vue，调用 updateWorkItem。修改时 Service 会忽略请求中的项目编号、工作项类型和生命周期状态，并重新校验关联关系、成员和标签。

详情抽屉支持就地编辑状态、负责人、优先级、所属迭代、关联需求、完成进度、预估工时、开始时间和截止时间；标题单独调用 updateWorkItemName。所有字段更新都会写入动态，负责人变更时会通知新负责人。

工作项状态可以在列表下拉、详情属性栏或看板拖拽中修改。归档、移入回收站、恢复和彻底删除分别调用对应的生命周期方法，详见 §1.2 状态流转。

3.3 导入

项目内工作项列表的【更多 -> 导入】打开 WorkItemImportForm.vue，先下载「工作项导入模板.xlsx」，再上传一个 xls 或 xlsx 文件。importWorkItem 按行解析并复用新增校验，返回成功数量和失败原因，页面会提示成功数量及失败行号。

模板中的状态必须是当前项目、当前工作项类型的状态名称，为空时使用该类型的初始状态；标签可以用逗号、顿号或斜杠分隔多个名称。

3.4 导出

列表和全部事项页的【导出】调用 exportWorkItemExcel，把当前筛选条件下的全部工作项（后端不分页）导出为「工作项.xlsx」；全部事项页面在前端另存为「全部事项.xlsx」。

导出只包含标注了 @ExcelProperty 的字段：类型、编号、标题、描述、优先级、负责人、状态、所属迭代、开始时间、截止时间、预估工时和完成进度。关联需求、缺陷类型和创建时间等未标注字段不会导出。

4. 工作项详情与协作

4.1 状态语义

工作项状态包含「看板状态」和「语义状态」两层。看板状态可以按项目和工作项类型自定义名称，语义状态用于统计和颜色展示。枚举 status_type 语义状态（PmsWorkItemStatusTypeEnum）：

值	枚举	说明
1	PENDING	未开始
2	PROCESSING	进行中
3	COMPLETED	已完成

4.2 详情抽屉

点击工作项标题打开 WorkItemDetail.vue 抽屉，抽屉是否可编辑由项目状态和当前用户的项目成员级别决定。

详情左侧展示标题、创建时间、标签、参与人、描述和附件，下方以页签收纳评论、活动、子工作项和工时记录。右侧「基础信息」可以查看或就地修改状态、负责人、优先级、迭代、关联需求、缺陷类型、进度、预估工时、开始时间和截止时间。

4.3 评论

WorkItemComment.vue 在「评论」页签中提供发表评论、编辑、删除和回复，回复只能指向主评论。

查询评论只校验工作项可访问；创建、修改和删除评论会校验工作项可编辑（项目处于进行中、工作项处于正常状态、当前用户拥有项目写权限），修改和删除还会校验评论创建人。项目或工作项只读时，页面保留评论内容但隐藏编辑入口。创建评论后会写入一条工作项动态。

4.4 动态

WorkItemActivity.vue 只读展示工作项动态，按时间倒序展示操作人头像、昵称和动态内容。

动态内容由后端统一生成，常见事件包括创建、修改字段、改名、切换状态、切换迭代、归档、回收、恢复、发表评论、修改评论、删除评论、登记工时和修改工时。评论或工时变化后，详情组件会刷新动态页签。

4.5 子工作项

WorkItemSubtaskList.vue 通过 parent_id 查询当前工作项的一级子项。新增表单可以一次提交多个子项，详情页也可以继续新增、编辑和移入回收站；子项复用 WorkItemForm.vue 和同一套工作项接口。

子项创建时沿用父项类型、所属迭代和看板状态，参与人默认使用当前操作人。父项不能再作为其他子项的子项，因此当前实现最多两层（父项 + 子项）。彻底删除父项前，Service 会先把子项的 parent_id 置空。

4.6 工时

WorkItemWorkLogList.vue 展示预估、已登记和剩余工时，并通过 WorkItemWorkLogForm.vue 登记或编辑工时。

详情页只展示单个工作项的记录。项目级工时报表按迭代（没有迭代时归入「未规划事项」）和工作项汇总每日投入，入口见 《【项目中心】项目详情与迭代》。

5. 状态、看板与标签设置

5.1 状态设置

工作项页签点击【更多 -> 状态设置】打开 WorkItemStatusList.vue，对应 yudao-ui-admin-vue3 项目的 @/views/pms/pm/workitem/status 目录。该弹窗也被项目设置的 ProjectCollaborationConfig.vue 复用，包含「状态管理」和「看板配置」两个页签。

「状态管理」支持拖动状态顺序、编辑名称 / 语义状态 / 描述、选择初始状态、添加状态和删除状态。初始状态不能删除；删除仍被工作项引用的状态时，必须在 WorkItemStatusDeleteForm.vue 中选择同项目、同类型的目标状态迁移工作项。

5.2 看板配置

「看板配置」页签支持添加、删除和排序看板列，把状态拖入列或移回「未放入看板」。未放入看板的状态可以继续流转，但不会出现在看板列中。

5.3 标签管理

工作项表单中的【标签管理】打开 WorkItemLabelList.vue，新增和编辑使用 WorkItemLabelForm.vue。弹窗展示标签名称、颜色和操作按钮。

当前表和 Service 未声明标签名称唯一约束，同名标签可以并存。

6. 删除与关联清理

工作项删除不依赖数据库级联。彻底删除单个工作项时，Service 在同一事务中：

① 把以该工作项为父项的子工作项 parent_id 置空；如果删除的是需求，再把其他工作项的 related_requirement_id 置空。

② 删除 pms_work_item_member、pms_work_item_user_sort、pms_work_item_comment、pms_work_item_work_log 和 pms_work_item_activity 中的关联记录。

③ 删除 pms_work_item 主记录。标签不做反向删除，标签编号数组中的历史编号在读取时自动忽略。

删除范围的差异如下：

操作	清理范围
删除迭代	只把该迭代下工作项的 iteration_id 置空，不删除工作项
彻底删除工作项	解除子项和关联需求关系，再删除参与人、个人排序、评论、工时、动态和主记录
彻底删除项目	由项目 Service 先清理整个项目的动态、评论、工时、参与人、个人排序、工作项、状态和看板列，再删除项目