Skip to main content

Plane Module 分组

Asset
ADP-PLN-FEAT-DOC-0024
Feature
plane-module-groups
领域
plane-core
作用域
application-level
文档状态
draft
产品生命周期
active
文档 Owner
DOC
事实源
canonical-docs
工程 Owner
PLN
Development Ready
not-ready
更新
2026/10/14

FEATURE DEVELOPMENT PACKAGE

工程就绪状态

工程 Owner：PLN · 仓库：PLN

BLOCKED
development · not ready
  • 原子需求与验收
  • 设计与工程合同
  • 代码与仓库定位
  • 里程碑与工作包
  • 验证计划
  • 无阻断决策
verification · not ready
  • Development Ready 已通过
  • 验收标准已覆盖
  • 正式测试已登记
  • Fixture 与环境已定义
  • 测试规格已物化到正式测试
release · not ready
  • Verification Ready 已通过
  • 实现修订可定位
  • 发布证据已登记
  • 兼容与迁移已定义
  • Runbook 与回滚已定义
查看阻断项（5）
  • Development Ready 缺少：原子需求与验收
  • Development Ready 缺少：设计与工程合同
  • Development Ready 缺少：代码与仓库定位
  • Development Ready 缺少：里程碑与工作包
  • Development Ready 缺少：验证计划
查看完整 readiness查看关联资产

当前状态​

当前状态：已发布并通过 producer 功能验收；本文继续作为行为契约维护。Front matter 中的 status 表示规划文档审核状态，implementation_status 表示产品实现状态。

功能目标​

在一个 Plane Project 内为 Module 实体提供稳定、可排序的分组，让 Producer 能在 Module 列表和看板中使用同一套组织结构浏览和调整模块，同时不改变 Module 内工作项、Module 生命周期或 ADP 执行语义。

术语与范围​

Plane Module Group 是 Project 级 Module 实体分组：

  • 一个分组属于一个 Project，并包含该 Project 下的零个或多个 Module。
  • 一个 Module 同一时间最多属于一个自定义分组；没有自定义分组归属时进入固定的“未分组”。
  • 分组只组织 Module 实体。它不是某个 Module 内部对 issue、work item、sub-issue 或其它工作项的分组。
  • 移动 Module 只改变 Module 的分组归属，不改变 Module 与工作项的关联、Module 状态或工作项顺序。

本文中的 Plane Module Group 也不等于规划包 manifest.yaml 中的 modules[]、module_key、 cycle 或 Docusaurus sidebar category。规划文档中的这些结构用于策划索引和投影；它们不会自动 创建、重命名或调整 Plane Project 中的 Module Group。

核心体验​

  • Module 列表和 Module 看板读取同一份 Project 级分组数据、分组顺序和 Module 归属。
  • 在任一视图创建、重命名、删除、排序分组或移动 Module 后，另一个视图刷新或同步后展示相同结果。
  • 分组折叠状态是用户偏好，按 Project、用户和分组保存；一个用户的折叠操作不影响其他用户。
  • 同一用户在列表和看板看到一致的折叠状态。折叠只改变展示，不改变共享分组顺序或 Module 归属。
  • “未分组”始终可见，在列表和看板中保持相同固定位置，不参与自定义分组排序，也不能被重命名或删除。

分组操作​

创建​

  • 有 Module 管理权限的用户可以在当前 Project 创建自定义分组。
  • 新分组获得稳定 ID 和 Project 内顺序，并立即出现在列表和看板的同一位置。
  • 创建分组不自动移动现有 Module。

重命名​

  • 有 Module 管理权限的用户可以重命名自定义分组。
  • 新名称在列表、看板和后续 API 读取中保持一致。
  • “未分组”名称由产品本地化资源提供，不能作为普通自定义分组重命名。

删除​

  • 删除确认必须说明受影响的 Module 数量和回退行为。
  • 删除自定义分组时，该组中的 Module 只回退到“未分组”。
  • 删除分组不得删除 Module，不得删除、移动或解除 Module 内任何工作项，也不得改变 Module 状态。
  • 回退和分组删除必须作为一个完整操作对外生效；失败时不得留下部分 Module 仍指向已删除分组。

排序​

  • 有 Module 管理权限的用户可以调整自定义分组顺序。
  • 排序结果属于 Project 共享数据，列表和看板使用同一顺序。
  • “未分组”保持固定位置，不接受排序写入。

移动 Module​

  • 有对应 Module 更新权限的用户可以把 Module 移入自定义分组、在分组间移动，或移回“未分组”。
  • 目标分组必须属于同一 Project；跨 Project 移动不属于本功能。
  • 移动完成后，列表和看板必须展示相同归属，且 Module 内工作项和历史关联保持不变。

权限​

  • 能读取当前 Project Module 的用户可以读取分组、顺序、归属和“未分组”。
  • 创建、重命名、删除和排序分组必须复用 Project 现有的 Module 管理权限，并由服务端校验，不能只依赖 UI 隐藏操作入口。
  • 移动 Module 必须通过该 Module 的更新权限校验；没有权限时返回明确的禁止结果，且不能产生部分写入。
  • 用户可以写入自己的折叠偏好，但不能读取或修改其他用户的私有折叠偏好。
  • 列表和看板必须使用相同权限结果，不能出现一个视图允许修改而另一个视图拒绝的权限漂移。

数据与 API 契约​

  • 分组是 Project-scoped 实体，至少包含稳定 ID、Project ID、名称和排序位置。
  • Module 分组归属使用可空或等价的 group reference 表达；没有自定义分组时统一解析为“未分组”。
  • API 必须覆盖分组列表、创建、重命名、删除、排序，以及 Module 分组归属更新。
  • 分组列表响应必须提供确定性顺序；列表和看板不得各自维护独立的分组副本或顺序。
  • “未分组”应以稳定的系统语义暴露，客户端不得把本地化显示文案当作持久 ID。
  • 非法 Project、跨 Project 分组、无权限、已删除分组和无效排序输入必须返回可区分的错误， 不得静默回退到其它自定义分组。
  • 更新接口重复提交相同目标状态时应保持幂等，不得产生重复分组或改变无关 Module。

历史数据与兼容​

  • 功能启用前已存在且没有分组归属的 Module 自动显示在“未分组”，不要求 Producer 手工补数据。
  • 历史 Module 的标题、状态、负责人、日期、工作项关联和相对展示信息必须保持不变。
  • 旧客户端或旧调用方未提交 group reference 时，仍按“未分组”语义工作。
  • 删除分组后的历史 Module 继续可读，并通过“未分组”访问；分组删除不能形成悬空引用。
  • 历史 Project 在没有任何自定义分组时，列表和看板仍能正常展示固定“未分组”和全部 Module。

双语与无障碍​

  • 中文和英文界面都必须覆盖分组标题、创建、重命名、删除、排序、移动、未分组、空状态、确认文案和 错误提示；“未分组”与 Ungrouped 必须表达同一系统语义。
  • 分组标题是可识别的结构标题；折叠控件提供可访问名称并正确更新 aria-expanded。
  • 创建按钮、更多操作菜单、重命名和删除对话框、排序手柄与 Module 移动入口都有稳定可访问名称。
  • 仅靠拖拽完成的排序或移动必须提供键盘可操作的等价入口，并在完成或失败后向辅助技术通知结果。
  • 焦点在创建、重命名、删除、排序、移动或关闭对话框后回到合理触发位置，不能丢失到页面起点。
  • 列表和看板在中文、英文以及辅助技术读取下都使用同一分组层级、顺序和 Module 归属。

边界与非目标​

  • 不提供 Module 内 issue/work item 分组。
  • 不提供分组嵌套、子分组或跨 Project 分组。
  • 不因为创建或删除分组而创建、删除、归档或改变 Module 生命周期。
  • 不改变 Module 内工作项顺序、依赖、状态、负责人或 Symphony 调度或人类验收。
  • 不把 Docusaurus category、planning cycle、module_key 或 manifest 顺序自动同步成 Plane Module Group。
  • 不在本功能中定义新的 Project 角色、权限模型或审批门；只复用现有 Module 权限。

依赖关系​

依赖 Plane Project 和 Module 实体、Project 成员权限、Module 列表与看板的数据读取能力，以及用户偏好 存储。它不依赖 ADP Runtime，且不改变工作进入或执行任务投影。

异常与阻塞场景​

  • 分组或 Module 不属于当前 Project。
  • 当前用户缺少分组管理或 Module 更新权限。
  • 分组已被其他请求删除，或排序输入包含缺失、重复、跨 Project 的分组 ID。
  • 删除分组时无法完整回退其中 Module。
  • 用户偏好存储失败；共享分组数据仍应可读，且不能把个人折叠状态写成 Project 共享状态。

验收标准​

  • 列表和看板展示相同的自定义分组、“未分组”、分组顺序和 Module 归属。
  • 创建、重命名、删除、排序和移动操作在两个视图间保持一致。
  • 删除分组只把其中 Module 回退到固定“未分组”，不删除 Module 或任何工作项。
  • “未分组”在列表和看板中保持相同固定位置，不能重命名、删除或参与排序。
  • 折叠状态按用户隔离，同一用户在列表和看板保持一致，且不改变共享数据。
  • 有权限和无权限场景同时通过 UI 与 API 校验；拒绝操作不会留下部分写入。
  • 历史 Project、历史 Module 和未携带 group reference 的兼容调用都能按“未分组”继续工作。
  • 中文和英文文案完整；关键控件有可访问名称、折叠控件有正确 aria-expanded，排序和移动有键盘等价入口。

验证方式​

  • Project-scoped 分组 API 的 CRUD、排序、Module 移动、幂等、跨 Project 和权限测试。
  • 分组删除回退与历史数据兼容 fixture，核对 Module、工作项和关联数量不变。
  • Module 列表与看板的共享数据、共享顺序、固定“未分组”和按用户折叠状态测试。
  • 中英文界面检查，以及键盘、焦点、accessible name、aria-expanded 和辅助技术通知检查。

待解问题​

当前无阻塞性待解问题。若后续需要分组嵌套、跨 Project 分组或 Module 内工作项分组，应作为独立功能 重新规划，不扩展本功能的 Project 级单层分组语义。

Last updated on by source2728