企业官网建设流程全解析

OpenProject 10.1.0 版本详解：项目状态报告、API v3 项目 CRUD 与 Rails 6 升级

【免费下载链接】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 10.1.0（2019-10-28 发布）官方发布说明，系统梳理该版本的两大核心新特性：项目状态报告（Project Status Reporting）与API v3 的项目 CRUD 能力，并附带说明工作包编辑字段整合、Rails 6.0.0 升级等维护性改进。通过结合当前仓库源码，读者将理解项目状态从「状态枚举定义 → 设置入口 → 红绿灯小部件渲染 → API 表示 → 列表过滤与导出」的完整技术链路，掌握如何在项目概览页配置状态小部件、如何通过 API v3 读写项目状态，并了解版本升级路径。

版本概览：OpenProject 10.1.0 的三大主题

OpenProject 10.1 的主要亮点是全新的项目概览仪表盘页面（project overview dashboard）及其内置的项目状态小部件，用于在线的项目状态上报。除此之外，该版本还包含大量缺陷修复与代码维护工作，整体技术状态得到明显改善。三大主题可归纳为：

1. 项目状态报告：在项目概览页以「红绿灯」形式呈现项目状态，方便团队与干系人随时掌握项目是否在轨（on track）、存在风险（at risk）或偏离轨道（off track）。
2. API v3 支持项目 CRUD：此前 API v3 对项目只读，本版本起可对项目执行创建、读取、更新、删除全生命周期操作。
3. 代码维护：整合工作包编辑字段实现并统一视觉风格；底层框架升级到 Rails 6.0.0。

项目状态报告：将项目概览页升级为汇报仪表盘

红绿灯状态小部件（Status Widget）

新引入的项目状态小部件可以添加到项目概览页面（project overview page），实现一目了然、公开透明的项目状态汇报。它用红绿灯语义展示项目状态，团队成员与干系人可以在同一位置快速判断：

• On track（在轨）——项目按计划推进，无重大问题或阻塞；
• At risk（存在风险）——项目面临潜在风险，需关注；
• Off track（偏离轨道）——项目已偏离计划，需要干预。

同时，小部件还支持附加关键项目信息，如项目负责人（project owner）、截止日期（due dates）、重要资源链接等，从而把项目概览页扩展成一个详细的汇报仪表盘（reporting dashboard）。

初始状态为 NOT SET（未设置）

小部件在首次激活时显示占位符NOT SET（未设置），提示项目尚未上报状态。这一点在源码中有多处印证：状态辅助模块 project_status_helper.rb 中定义了常量NOT_SET = "not_set"，当状态码为nil时返回-not-set的 CSS 类与本地化的 "Not set" 文案；对应的单测 project_status_helper_spec.rb 明确断言了nil状态码的渲染行为。

状态枚举：六种状态码

当前仓库的 Project 模型 通过 Rails enum 定义了完整的项目状态码，比发布说明中提到的三种状态更丰富：

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

这六个状态码（on_track、at_risk、off_track、not_started、finished、discontinued）的本地化名称定义在 config/locales/en.yml，依次为 "At risk"、"Discontinued"、"Finished"、"Not started"、"Off track"、"On track"。

前端小部件实现

小部件的前端实现位于 project-status.component.ts，是一个继承自AbstractTurboWidgetComponent的 Angular 组件，其 HTML 模板 project-status.component.html 通过<turbo-frame>懒加载状态内容，并支持属性帮助文本与部件菜单。

状态说明（status explanation）

除了状态码本身，发布说明强调可以「附加重要项目信息」。对应地，Project 模型还维护了status_explanation字段（状态描述），用户可以在设置状态时以富文本形式记录变更、项目 KPI 或其他相关信息。该字段在 API 表示层由 project_representer.rb 以formattable_property暴露。

设置项目状态：项目设置与项目首页两条路径

根据用户指南 docs/user-guide/projects/project-status/README.md，设置项目状态有两种方式：

1. 项目设置（Project settings）：在左侧项目模块菜单中选择「Project settings」，然后选择对应的状态值；还可以通过下方的状态描述字段补充变更记录、项目 KPI 等额外信息。
2. 项目首页（Project home）：如果尚未配置，项目状态小部件会默认出现在首页，直接通过下拉菜单即可设置状态。

详细的用户指南见 docs/user-guide/projects/project-status/，小部件在项目首页的完整行为说明见 项目首页部件文档。

项目状态的展示位置

项目状态一旦设置，会出现在 OpenProject 的多个模块中：

• 项目列表（Project lists）：项目列表页展示所有项目及其状态列，并支持按状态过滤与排序。实现上，过滤由 project_status_filter.rb 提供（查询键project_status_code，类型为:list_optional，基于status_code字段生成 SQL）；排序由 project_status_order.rb 提供（按status_code升降序）。预置的「项目状态」静态查询（如 on track / at risk / off track）定义在 static.rb。
• 项目首页（Project home）：项目状态以可拖拽的小部件形式显示，用户可自定义项目概览布局。
• 导出（Export）：项目导出时状态列由 status.rb 格式化，输出本地化的状态码名称，未设置状态时输出空字符串。

API v3 新增项目 CRUD 操作

发布说明指出：API v3 现在支持对项目执行 CRUD（增删改查）。这在仓库中有完整的路由与测试支撑：

• 路由入口 projects_api.rb 挂载了resources :projects，其中get（列表/索引）与post（创建）直接通过SqlFallbackedIndex与Create端点挂载；route_param :id下的嵌套 API 则服务于单项目操作。
• 项目的 API 表示 project_representer.rb 以resource :status暴露状态，getter在status_code存在时渲染StatusRepresenter，setter通过LinkObject将 API 的status链接写回status_code属性；status_explanation作为可写属性同步暴露。
• 项目状态资源端点 statuses_api.rb 提供GET /api/v3/project_statuses/:id，其中:id必须是Project.status_codes的合法键，否则返回 404。
• 状态表示器 status_representer.rb 输出_type: "ProjectStatus"、id与本地化的name三个字段。
• 测试佐证：请求级测试 project_status_resource_spec.rb 验证了合法状态返回 200 且_type为ProjectStatus，非法状态返回 not found；渲染级测试 status_representer_rendering_spec.rb 验证了self链接、_type、id、name属性。

基于 API 表示层，可通过如下方式通过 API v3 读取项目状态（示意）：

GET /api/v3/projects/{id} # 响应中的 status 链接形如： # "status": { "href": "/api/v3/project_statuses/on_track", # "title": "On track" } GET /api/v3/project_statuses/on_track # 响应：{ "_type": "ProjectStatus", "id": "on_track", "name": "On track" }

注意：当前仓库已演进至更高的主版本，API 路由与字段行为以当前仓库源码为准（如 projects_api.rb 中保留了面向所有 workspace 类型的兼容注释）。

代码维护：编辑字段整合与 Rails 6 升级

整合工作包编辑字段实现

OpenProject 引入了统一外观与观感的工作包编辑字段（work package edit fields）：此前分散、风格各异的编辑字段现在拥有统一的技术基础，视觉上也趋于一致。这一改动降低了前端维护成本，也修复了类型下拉框样式丑陋等问题。

升级到 Rails 6.0.0

OpenProject 10.1 将底层框架升级到Rails 6.0.0。作为参考，当前仓库的 Gemfile 已进一步演进到gem "rails", "~> 8.1.3"，说明自 10.1 之后框架又经历了多次大版本升级；10.1 的 Rails 6.0 升级是这条演进路径上的重要里程碑。

缺陷修复与变更清单（Bug fixes and changes）

10.1 版本修复了大量与项目概览、工作包、Gantt 图表、看板（boards）、文档插件、邮件通知等相关的缺陷，代表性修复包括：

• 状态小部件位于页面底部时下拉菜单错位；
• 用户缺少权限时，项目概览的显示字段未保持「只读」；
• Gantt 图表中新调度条无法正常工作；
• 看板中状态列可被重复添加多次；
• 小部件大小有时不可调整、渲染间距异常、状态图顺序错误；
• 项目状态描述在从项目设置添加宏时未显示；
• 项目概览页偶发空白、小部件闪烁、无法移动；
• 工作包评论内容过宽时无法编辑、编辑时主题跳动；
• 会议评审邮件通知时区错误、复选框在文本编辑器中的格式错误；
• 预算小数分隔符显示错误、仓库提交中指向工作包的链接样式异常；
• 版本编辑缓慢（/api/v3/versions/available projects在大项目集合下性能问题）；
• 传入邮件unknown user=accept时产生未翻译的契约错误；
• 复制项目时缺少直接错误提示、Grid 中无法用 Escape 退出编辑等。

升级到 OpenProject 10.1

• Enterprise 云版：会自动在数天内升级到最新的 10.1 版本，无需手动操作。
• 本地安装：需要执行少量变更来完成升级，请参阅 升级指南。

后续展望

发布说明预告，下一个版本将引入多项目组合视图（multi-project portfolio view），为最重要的项目提供快速概览，相关演进可进一步参考 组合管理相关代码 与当前仓库的用户指南文档。

版本信息速查

【免费下载链接】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