企业官网建设流程全解析

OpenProject 项目状态（Project Status）配置指南：状态设置、展示与项目列表联动

【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject

OpenProject 通过「项目状态」为团队提供项目是否按计划推进（on track）的直观信号，帮助管理者快速发现偏离计划的项目并及时介入。本文基于 docs/user-guide/projects/project-status/README.md 展开，完整讲解在项目设置与项目主页中设置状态的两种方式、状态说明字段（status description）的用法，以及状态在项目列表、项目主页组件中的展示逻辑，并辅以仓库源码说明状态码定义、筛选与排序的底层实现，读完即可在 OpenProject 中落地一套项目健康度标识流程。

什么是项目状态

项目状态是 OpenProject 赋予每个项目的一组预定义健康度标记，用来回答“这个项目目前进展是否正常”。它同时承载两层信息：

• 颜色与图标标识：一眼即可识别的可视化信号（例如绿色代表正常、红色代表偏离计划）；
• 状态说明（status description）：一段自由文本，用于补充记录变更原因、项目 KPI、风险点等上下文细节。

从数据模型看，状态直接挂在Project模型上。在 app/models/project.rb 中，OpenProject 用 Rails 枚举定义了 6 个合法状态码：

enum :status_code, { on_track: 0, at_risk: 1, off_track: 2, not_started: 3, finished: 4, discontinued: 5 }

这 6 个状态码与呈现外观一一对应。在 app/constants/projects/statuses.rb 中，每个状态被定义为一个包含code、color、icon的结构体：

其中ON_TRACK、AT_RISK、OFF_TRACK、NOT_STARTED、FINISHED、DISCONTINUED六个状态组成VALID合法集合（app/constants/projects/statuses.rb），AVAILABLE则在合法集合基础上额外包含“未设置”占位状态。注意：默认情况下项目没有预设状态，需要由项目成员手动设置。

在项目设置中设置项目状态

设置项目状态最直接的入口是项目设置（Project settings）。

操作步骤

1. 进入目标项目；
2. 点击左侧项目模块菜单中的Project settings（项目设置）；
3. 在设置页面中找到Information（信息）区块，其中包含状态下拉选择框；
4. 从下拉框中选择合适的项目状态；
5. 如需补充细节，在状态下方的Status description（状态说明）字段中手动记录变更原因、项目 KPI 或其他相关信息。

状态说明字段的底层实现

状态说明与状态码是相互独立的两个字段，分别持久化。从源码看，app/models/project.rb 注册了 Journal（变更日志）格式化字段：

register_journal_formatted_fields "active", formatter_key: :active_status register_journal_formatted_fields "status_explanation", "description", formatter_key: :diff register_journal_formatted_fields "status_code", formatter_key: :project_status_code

其中status_explanation就是状态说明字段的存储名，它使用diff格式器记录变更差异；status_code使用project_status_code格式器。也就是说，每次修改项目状态或状态说明，都会在项目活动日志（Journal）中留下可追溯的历史记录，团队成员可以清楚看到“什么时候把状态从 on_track 改成了 at_risk，以及当时的说明是什么”。这为项目状态提供了完整的审计能力。

在项目主页上设置项目状态

除了项目设置，还可以直接在**项目主页（project home）**上设置状态：

• 如果尚未配置过项目主页布局，项目状态组件（widget）默认就会出现在主页上；
• 直接使用组件内的下拉菜单即可完成状态设置，无需进入项目设置页面；
• 该组件支持拖拽，可自由调整在项目主页上的位置，用于自定义概览布局。

这一交互由前端项目主页的网格组件承载。后端则通过 app/components/projects/status_badge_component.rb 负责状态徽章的渲染：它根据project.status_code在Projects::Statuses::VALID中查找对应状态，并使用helpers.hl_background_class(:project_status, @status.id)计算高亮背景色，名称则通过helpers.project_status_name(@project.status_code)输出本地化文本。因此，同一状态在项目设置、项目主页、项目列表中会呈现一致的配色与文案。

状态名称的本地化与 CSS 类名由 app/helpers/project_status_helper.rb 统一处理：

• project_status_name(status_code)：按js.grid.widgets.project_status的 i18n 作用域返回本地化名称；
• project_status_css_class(status_code)：返回 BEM 修饰符风格的 CSS 类（如-on-track、-off-track），配合.project-status--name或.project-status--bulb元素类使用，未设置状态时回退为not_set。

关于项目主页状态组件的更多自定义说明，可参考 项目主页组件文档。

展示项目状态

设置完成后的项目状态会出现在多个 OpenProject 模块中，为不同视角的管理场景提供一致的信号。

项目列表

项目列表 会展示所有项目及其状态。状态以列的形式出现在列表中，同时还可以作为筛选条件使用，从而快速定位所有“偏离计划”或“有风险”的项目。

从源码看，项目状态在列表中的参与方式是完整的三段式：

• 列（Select）：app/models/queries/projects/selects/status.rb 定义了project_status列，其标题来自 i18n 属性attributes.status；
• 筛选器（Filter）：app/models/queries/projects/filters/project_status_filter.rb 定义了键为project_status_code的可选列表筛选器，其where直接针对项目表的status_code字段生成 SQL 条件，allowed_values则枚举Project.status_codes全部状态作为候选值；
• 排序（Order）：app/models/queries/projects/orders/project_status_order.rb 允许按project_status字段以status_code升序或降序排列项目列表。

此外，OpenProject 还内置了几个“一键筛选”的静态项目查询。在 app/models/project_queries/static.rb 中可以看到类似这样的预设：

static_query("project_status_code", "=", Project.status_codes[:on_track], name: :"activerecord.attributes.project.status_codes.on_track") static_query("project_status_code", "=", Project.status_codes[:off_track], name: :"activerecord.attributes.project.status_codes.off_track") static_query("project_status_code", "=", Project.status_codes[:at_risk], name: :"activerecord.attributes.project.status_codes.at_risk")

这意味着系统内置了“按计划推进”“偏离计划”“有风险”等常用预设查询，管理者可以一键调出处于特定状态的项目集合，而无需手动配置筛选器。

项目主页

项目主页 同样会展示项目状态。状态以**组件（widget）**形式呈现，可以拖拽到主页的任意位置以自定义概览布局，形成项目级别的“健康仪表盘”。

导出中的状态展示

除了在线展示，项目状态也会进入项目导出结果。在 app/models/projects/exports/formatters/status.rb 中定义了针对project_status/status属性的导出格式化器：它读取项目的status_code，并通过 i18n 键activerecord.attributes.project.status_codes.<enum_name>转换为本地化文本；若项目未设置状态则导出为空字符串。这样导出的项目清单中同样包含可读的状态文字，便于离线汇报与存档。

小结

• 项目状态是 OpenProject 项目健康度管理的核心信号，默认不设置，需要由成员在项目设置或项目主页组件中主动配置；
• 6 个状态码（on_track / at_risk / off_track / not_started / finished / discontinued）由 Project 模型 枚举定义，颜色与图标在 app/constants/projects/statuses.rb 中统一声明；
• 状态修改会通过 Journal 记录变更历史（含状态码与状态说明的差异），具备可审计性；
• 状态在项目列表中既可作为列展示、也可作为筛选与排序条件，系统还内置了 on_track / off_track / at_risk 等一键预设查询；在项目主页中以可拖拽组件呈现；导出项目清单时也会输出本地化的状态文本。

通过组合使用状态码与状态说明字段，团队可以在不引入额外看板的情况下，快速建立一个“项目组合健康度”视图，及时识别偏离计划的项目并采取行动。

【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject