Leantime 版本演进深度解析：从 CHANGELOG 看 3.1 到 3.9 的架构现代化之路-平芜编程栈

Leantime 版本演进深度解析：从 CHANGELOG 看 3.1 到 3.9 的架构现代化之路

【免费下载链接】leantimeLeantime is a goals focused project management system for non-project managers. Building with ADHD, Autism, and dyslexia in mind.项目地址: https://gitcode.com/GitHub_Trending/le/leantime

Leantime 是一款以目标为导向的开源项目管理工具，其官方 CHANGELOG.md 完整记录了从 3.1 到 3.9 的每一次版本迭代。本文以该文档为骨架，逐版本拆解 Leantime 的核心演进脉络——原生权限引擎、JSON-RPC API、Blade 模板迁移、Tiptap 富文本编辑器、跨项目 Program Board 等关键架构决策——并结合仓库源码（如 PermissionService.php、PermissionEnforcer.php、Jsonrpc.php 等）验证底层实现，帮助你快速判断各版本的能力边界、安全修复范围与升级注意事项。

CHANGELOG 全景：版本节奏与文档结构

CHANGELOG.md（2022 行，覆盖 3.1.2 → 3.9.8）采用了典型的"自上而下"编排：最新版本在最顶部，每个版本条目按Highlights（里程碑特性）→New Features→Bug Fixes→Improvements→Security→Localization→Dependency Updates→Breaking Changes的顺序组织，部分版本还附带了提交清单。

从版本节奏可以观察到两条清晰的演进主线：

技术债清理：3.4.x 起逐步向 Laravel 靠拢（Laravel 会话处理、Laravel 数据库类、Laravel 异常处理器），3.8.0 完成全量 Blade 模板迁移，3.9.0 引入原生权限引擎与 JSON-RPC API；
能力外延：3.5.x 加入 Redis 缓存/会话，3.7.0 引入实验性 PostgreSQL 支持，3.9.x 加入跨项目 Program Board、MCP 端点与移动端 API 面。

对于运维与二次开发者，CHANGELOG 也是天然的"升级风险清单"：每个版本都会标注破坏性变更（如 3.7.0 移除 TinyMCE）和需要人工介入的配置变更（如 3.8.0 修正会话过期时间单位）。

3.9.x 主线：权限引擎、JSON-RPC 与跨项目视图

Native Permission Engine：从散落角色检查到集中式鉴权层

3.9.0 最大的架构变更是原生权限引擎（Native Permission Engine）。CHANGELOG 明确指出：它取代了分散的 ad-hoc 角色检查，以"默认拒绝"（fail-closed）的集中式授权层治理整个应用的访问控制，并逐域落地到 Tickets、Comments、Users、Clients、Settings、Sprints、Wiki、Ideas、Goals、Blueprints、Canvas、Calendar、Timesheets、Files、Reports 与 Projects 服务，期间关闭了大量跨用户 IDOR（越权访问）与信息泄露漏洞（#3461、#3469、#3471、#3472、#3473）。

源码验证了这套引擎的三层结构：

声明层：通过RequiresPermission属性（attribute）在控制器方法上声明所需权限键，PermissionEnforcer统一从三类入口读取该属性——传统路由（Frontcontroller::executeAction()）、原生 Laravel 路由（CheckPermissions中间件）、JSON-RPC（Jsonrpc::executeApiRequest()），保证"一处声明、处处一致"；
决策层：PermissionService.php 的currentUserCan(string $permissionKey, ?int $projectId, ?bool $forceGlobal)是唯一运行时入口，它区分两个关注点：能力（capability）——用户的有效角色是否持有该权限（查缓存的角色→权限授权映射表），以及数据访问（data access）——对于项目级权限，用户是否真是该项目成员（admin/owner 绕过）；
落地层：PermissionSeeder.php 将代码中发现的domain.action词汇表幂等同步进zp_permissions表，并以"仅追加"方式为六个内置角色授予默认权限（DefaultRolePermissions矩阵），保证管理员的自定义授权在重新同步后不被覆盖。

一个值得注意的工程细节是audit mode（审计模式）：PermissionEnforcer.php 的注释显示，当config('permissions.enforce')为假时（默认），引擎只记录"本应拒绝"的日志而不真正拦截，使权限可以按域逐步灰度观察后再切换为阻断模式。此外，projectIdParam无法解析为具体项目且为必填参数时失败关闭（fail closed），避免误用会话项目做错误授权。

JSON-RPC API：替代遗留 REST/JSON 控制器

3.9.0 同期引入的 JSON-RPC 2.0 API 层替代了遗留 REST/JSON 控制器，迁移了 Tickets、Users、Ideas、Calendar、Notifications、Reactions、Sessions、Submenu 等端点，并提供插件门控属性（plugin gate attribute）与能力发现端点（#3457）。

在 Jsonrpc.php 中可以看到它的关键约定：

仅显式标记@api注解的服务方法可被远程调用（3.8.0 起强制执行）；
标量返回值不再被包装成单元素数组；id参数使用类型化声明；
RPC 场景下被拒绝的服务方法抛出类型化异常，并配合JsonRpcErrorResponse/JsonRpcResponse统一响应格式。

配套的认证链路也在 3.9.1–3.9.3 之间逐步完善：3.9.1 恢复 Sanctum Bearer 请求的用户上下文（修复 3.9.0 回归，#3514），3.9.3 修复了 Bearer 令牌错误（-32001）——根因是 Sanctum guard 会话里存的是原始角色整数而非权限引擎期望的角色名（#3525），并由此推动"所有认证路径（Web 登录、API Key、Bearer 令牌）统一走同一个会话工厂"（#3526），从根上避免角色与二因素状态分叉。

跨项目 Program Board 与统一 Blueprints 域

3.9.7 的里程碑特性是跨项目 Program 视图：任务视图可以跨多个项目组成 Program，冲刺（sprint）在 Program Board 上跨项目继承，从而支持更高层级的计划与跟踪（#3587）。3.9.8 继续打磨该模块（修复里程碑 0% 完成度、时间线"Show Tasks"空视图，见 #3624、#3625、#3628），并调整卡片状态下拉框位置（#3599）。

3.9.0 的Unified Blueprints Domain则是一次大规模去重重构：原本 16 个各自独立的 canvas 变体域被合并为统一的 Blueprints 域（原生 Laravel 控制器），在保留全部画布类型的同时大幅减少重复代码，遗留的 Canvas 与 Strategy 代码退化为薄薄的弃用适配器（#3483、#3486）。配合新增的 Logic Model Board（#3455）与 WorkStructure 元模型（#3454），Leantime 正在把"画布+结构化工作层级"抽象为可编排的基础设施。

移动端与 MCP：3.9.x 的外部集成面

3.8.0 引入了支撑 Leantime Mobile App 的后端 API 面，核心是服务端权威的会话解析：移动客户端通过 Bearer 令牌认证后，无需预先知道自己的 userId 即可解析"我是谁"（#3395）。具体到方法层包括Users::getUser()缺省取会话用户、Auth\AccessToken::revokeCurrentToken()安全登出、Tickets::markTicketDone/markTicketReopen快速完成流程等。

3.9.8 对 MCP 端点的修复值得一提：/mcp端点现在接受 Leantime API Key，并提供一个针对已移除 php-mcp provider 的 shim，使原地升级可以正常引导（#3601、#3602、#3607）。3.9.7 则把 MCP 工具类重组进各自对应的领域模块（#3581），并在端到端测试中发现并修复了运行时缺陷（#3586）。

3.8 与 3.7：前端统一与编辑器换代

3.8.0：Complete Blade 模板迁移

3.8.0 完成了所有遗留.tpl.php、.sub.php、.inc.php模板到 Laravel Blade 的转换：删除 272 个遗留文件、新增 200 个 Blade 文件，净减少 72 个文件，覆盖全部 16 个 canvas 域、共享子模块（Tickets、Comments、Files、Projects）以及简单/复杂域（#3362）。对插件开发者而言，这意味着模板层的扩展点全部切换到 Blade 生态。

3.7.0：TinyMCE → Tiptap 与实验性 PostgreSQL

3.7.0 最醒目的事件是富文本编辑器换代：TinyMCE 被完全移除，替换为基于 Tiptap 的现代编辑器（#3362 同期相关），支持/斜杠命令、@提及、多列布局、字体与字号、颜色与高亮、KaTeX 数学公式、带语法高亮的代码块、表格与任务列表、全移动端适配以及为 AI 辅助写作预留的 Copilot 扩展钩子。同版本还进行了 Wiki 三栏式重构（导航/内容/属性面板 + 审计驱动的活动流）与通知系统改进（按项目静音、按事件类型过滤）。

破坏性变更提示：CHANGELOG 明确警告——现有内容无需修改即可渲染，但任何自定义 TinyMCE 插件或编辑器扩展必须针对 Tiptap API 重写。

同版本还引入了实验性 PostgreSQL 支持：新的 SchemaBuilder 负责跨数据库 schema 管理，castAs()辅助方法处理跨库 CAST，wrapColumn()取代双引号 SQL 标识符（#3447 起持续修复）。Postgres 兼容问题在后来的版本中反复出现，也反向证明了这套辅助层在真实部署中的价值。

3.6：看板体验、无障碍与多协作者

3.6.0 聚焦交互层：

Kanban 看板：可折叠泳道（collapsible swimlanes）、水平泳道头（含状态分布与吸顶）、看板快速添加表单（含键盘快捷键）、按截止日期分组、乐观 UI 更新、跨泳道拖拽（#3205 系列）；
无障碍（WCAG 2.1 AA）：全局对比度与焦点指示器优化、暗色模式与灰度下的低视力支持、自定义输入组件（下拉、日期选择器）的无障碍改造、TinyMCE 屏幕阅读器修复；
多协作者：单个 ticket 可分配多个协作者（在 3.9.0 中补完，确保协作者始终收到 ticket 通知并在列表/组件视图中展示完整元数据，#1099）；
时间表过滤：支持按 ticket 与开票状态过滤（3.5.12 期间持续打磨）。

安全修复脉络：跨版本的安全演进线

把 CHANGELOG 的 Security 章节串联起来，可以看到一条完整的加固时间线：

3.4.x–3.5.x：转义邮件内容、API Key 名称转义、项目 webhook URL 转义、SVG 禁用显示、开放重定向修复、文件管理加固；
3.6.0：LDAP 类型加固、2FA QR 码生成修复；
3.9.0：七大类漏洞族综合治理——projectIdParam必须为真实正整数且无法解析时失败关闭（#3507、#3509）、Projects 上帝服务增加递归安全的 manager+ 校验（#3505）、Calendar/Files/Reports/Timesheets/Goals/Canvas 各域门控并关闭 by-id IDOR、评论授权收敛到宿主实体的真实项目、TagsgetTagsIDOR 关闭、CSRF 加固（安装路由豁免 + 表单 token 化）；
3.9.6：授权、SSRF、重置令牌、LDAP、存储型 XSS 修复（#3584）；插件管理要求正确权限且安装输入严格校验（#3583）；头像图片源中编码用户 ID 防 DOM XSS（#3582）；getUserAPI 响应剥离凭据（#3556、#3576）。

这些条目为安全审计者提供了绝佳的排查起点：例如 3.9.3 的 Bearer 认证修复可直接定位到认证会话工厂与RoleResolver的衔接逻辑。

运维配置要点：从 CHANGELOG 提炼的部署注意事项

CHANGELOG 中的多个 Bug Fix 条目实际是在纠正配置语义，对部署者有直接价值：

会话过期时间单位（3.8.0/3.4.7）：helm/values.yaml的app.session.expiration曾默认28800（秒），而应用期望的是分钟（对应LEAN_SESSION_EXPIRATION与 Laravel 的session.lifetime）；现已修正为480分钟（8 小时）并显式注释单位，同时在 config/sample.env 与 laravelConfig.php 中澄清，防止回归（#3378）。升级到 3.8.0+ 的 Helm 用户应注意该键的语义；
Redis 会话隔离（3.9.8）：会话被隔离到独立的 Redis database，避免与其他缓存数据冲突（#3604）；3.5.10 起支持redis db配置（#3103 相关）；
API 速率限制（3.9.7）：默认 API 速率限制从 10 次/分钟提升到 120 次/分钟（#3591），配合Retry-After标准响应头（3.2.0-beta 引入）与RateLimiter中间件（app/Core/Middleware/RateLimiter.php）；
MySQL 版本底线：3.2.0 起要求 MySQL 8.0+（5.7 已 EOL），并同步支持实验性 PostgreSQL；
缓存一致性：3.9.7 修复系统更新后未清理缓存引导清单的问题，3.9.2 修复陈旧路由缓存导致的 500（#3523）。

从 CHANGELOG 追溯源码：给开发者的阅读指南

CHANGELOG 的本质是"变更索引"，每个条目都可以在仓库中找到对应实现。推荐按以下映射关系深挖：

权限引擎：RequiresPermission属性声明见 RequiresPermission.php，强制器见 PermissionEnforcer.php，决策逻辑见 PermissionService.php，角色-权限矩阵见 DefaultRolePermissions.php，播种逻辑见 PermissionSeeder.php；
JSON-RPC：控制器 Jsonrpc.php 与响应类型 JsonRpcResponse.php、JsonRpcErrorResponse.php，请求样例见 tests/Httprequests/JsonRPC.http 与 MCP.http；
API 认证：Sanctum 桥接见 SanctumServiceProvider.php，Bearer 契约测试见 tests/Acceptance/API/BearerApiCest.php（3.9.1 起带 CI 门禁）；
跨数据库兼容：castAs()/wrapColumn()辅助见 DatabaseHelper.php，Postgres 连接封装见 LtPostgresConnection.php；
模板层：Blade 组件库见 app/Views/Templates/components（3.8.0 迁移成果的落点）。

结语：把 CHANGELOG 当作架构决策日志

Leantime 的 CHANGELOG 远超"变更列表"的意义——它记录了项目从传统 PHP 模板架构向 Laravel 生态、从散落权限检查向声明式鉴权、从单一 MySQL 向双数据库、从 Web-only 向 API/移动端/MCP 多入口演进的完整决策链。对评估者，它提供了各版本能力与安全状态的权威快照；对升级者，它标注了每个破坏性变更与配置语义陷阱；对开发者，每条条目都是指向源码的精确路标。结合本文给出的源码映射，你可以快速把任何一条变更还原为可读、可验证的实现细节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考