个人开发开源项目管理系统-v1.0.42至1.0.46版本更新说明

0 阅读9分钟

项目管理系统连更五个版本:修的都是「用起来才发现」的毛病(v1.0.42 → v1.0.46)

之前写过一篇双门户落地实践,系统的整体架构和设计取舍都在那篇里了。这篇是续集——记录最近五个版本(v1.0.42 ~ v1.0.46)修掉的一批问题。都是内测的时候用户真实用出来的反馈,不是我自己在测试环境里能想到的那种。

在这里插入图片描述先上一张总览,五个版本、六个问题,有一个还是视觉重做:

版本改了什么类型
v1.0.42综合分析纳入权限管理,可单独勾选功能补齐
v1.0.43综合分析 3D 柱状图重做(原来挤成一团)视觉修复
v1.0.44文档管理支持 zip / rar 压缩包 + 上传上限问号提示功能 + 体验
v1.0.45项目详情 → 文档,「上传人」永远显示 "-"数据修复
v1.0.46综合分析团队人数 / 未关闭风险统计为 0;仪表盘在线人数虚高统计修复 ×2

下面挨个说。每个问题我都尽量把「现象 → 为什么 → 怎么修的」讲清楚,有两处原因挺有意思,值得记下来。


一、v1.0.42:综合分析也能管权限了

这个不算 bug,算补课。之前权限体系里,首页仪表盘是可以单独勾选、单独取消的,但「综合分析」没有独立权限项——它挂在项目列表的权限下面,想给某个角色单独关掉综合分析,做不到。

修法不复杂:权限表里加一项 menu_analysis,归到「首页」分组下。麻烦的是老库——已部署的库 permissions 表不是空的,初始化种子不会重跑。所以专门写了一个幂等迁移:权限不存在就插入,同时给原来有项目列表权限的角色只补授不回收。升级之后不用手工跑任何 SQL,起服务自动补。

现在角色管理页面里,「首页」分组下是两项:访问首页仪表盘、访问综合分析,想关哪个关哪个。取消勾选后侧边栏整个「分析」组消失,直接输网址进 /analysis 也会被送到第一个有权限的页面,不会出现「菜单没了、页面还能进」的尴尬。

二、v1.0.43:3D 柱状图,从「挤成一团」到「环形均分」

综合分析页的「项目运营总览」面板有一个 3D 柱状群,按项目状态(待办 / 进行中……)显示柱子。原来的实现有个隐蔽 bug:柱子按方阵排布时,纵深坐标被错误地写进了纵向位置,导致多根柱子互相错位、叠在一起,看起来像一坨。

在这里插入图片描述

这次重做成了 Canvas 2D 自绘:柱子均匀落在一个圆环上,透明度按远近衰减,绘制顺序固定「远的先画、近的后画、顶面最后画」,遮挡关系完全可控。之所以放弃 CSS 3D,是因为 preserve-3d 下浏览器对交叉面的深度排序不可控,柱顶面会被压到侧面下面,渲染成「开口的盒子」——这种渲染问题没法靠调参数解决,只能换画法。

顺带处理了细节:数据多于 8 个自动拆内外双环;只有 1 根柱子时居中显示;系统开了「减少动态效果」就只渲染静态一帧,不再自转。

三、v1.0.44:压缩包终于能传了(这个反馈最多)

现象

文档管理里传 zip / rar,转圈半天然后报「服务器内部错误」。用户的第一反应都是「是不是不支持压缩包格式」,其实后端从头到尾就没限制过文件类型。

真正的原因

multer 把单文件大小硬编码在了 10MB。超过 10MB 的压缩包,上传到一半被 multer 掐掉,抛出的 LIMIT_FILE_SIZE 错误又被全局兜底中间件改写成了「服务器内部错误」——两层叠加,把一个「文件太大」的问题伪装成了「系统坏了」。而且 200MB 的包要传挺久,用户等半天才看到报错,体验相当差。

修了三层

  1. 限额分两档:普通文件维持 10MB(MAX_UPLOAD_SIZE),压缩包(zip / rar / 7z / tar.gz 等)放宽到 200MB(ARCHIVE_MAX_UPLOAD_SIZE,可配)。超限直接删除临时文件,返回中文提示,不再假装 500。
  2. 前端提前拦:选中文件的那一刻就校验体积,超限立即提示并清空选择,不用等到点保存才挨骂。
  3. 下载也修了:原来下载 zip 的响应头不带正确的 Content-Type,某些浏览器会自作主张改成 .bin;现在按扩展名显式声明,中文文件名也能正常显示。

集群部署那边也同步改了 Nginx 的 client_max_body_size(55m → 210m),不然 Express 这边放行了、Nginx 还是先给个 413。

顺手加的「?」提示

两档上限写死在代码里,用户怎么知道?在上传弹窗的「上传文件」标题后面加了一个 ⭕ 里带问号的小图标,鼠标悬上去浮出提示,内容从后端接口实时拉,改了配置不用改文案:

在这里插入图片描述 上传超时也从全局的 30 秒单独放宽到了 10 分钟——内网传 200MB,30 秒是无论如何不够的。

四、v1.0.45:「上传人」一栏永远是横杠

项目详情 → 文档页签里有一列「上传人」,从上线起就一直显示 "-"。

查下来前端没毛病,是接口从来没返回过上传人的名字。documents 表里只存了 uploadedId(数据隔离要用),名字要 join users 表才有,而列表、详情、上传三个接口都偷懒没做这一步。

修复时特意用了批量查询:先把当前页所有文档的上传人 id 收集起来,一次 IN 查询把用户名全捞回来,避免每行文档单独查一次数据库(N+1 问题)。上传人的账号被删除时回退显示 "-",不会报错。 在这里插入图片描述

五、v1.0.46:两个统计问题一起修

5.1 综合分析的团队人数、未关闭风险全是 0

跟 1.0.45 是同一种病:/api/projects/all 这个接口是给综合分析页供数的,早期只手工算了任务数两个字段,__teamCount(团队人数)、__riskOpen(未关闭风险)压根不在响应里,前端 KPI 卡片自然永远是 0。

这次没有继续「缺一个补一个」,而是把项目列表页那套现成的批量聚合统计(固定 9 条 GROUP BY 查询,一次算完团队、风险、文档、会议、预算)直接挪过来复用,两个页面从此用同一套口径。「未关闭风险」的定义也对齐了项目详情页:除了已解决、已关闭,其余状态(含已缓解)都算未关闭。 在这里插入图片描述

5.2 仪表盘「在线人数」严重虚高

这个问题用户描述得很直白:「就我一个人在用,显示一堆人在线。」

原逻辑是「最近 24 小时内登录过就算在线」——昨天下午登录、今天压根没开机的人,也被算成了「在线」。这种口径放在报表里尚可,放在叫「在线人数」的指标上就是误导。

改成了真实会话在线:

  • 每个已登录的浏览器每 30 秒向后端发一次心跳;
  • 后端记录「最近 90 秒内有心跳」的会话才算在线,登出立即下线;
  • 标签页切到后台就停发心跳,挂机 90 秒后自动判离线;切回前台马上补一次;
  • 单机部署走内存,配了 Redis 的集群部署走 90 秒 TTL 的 key,多副本天然共享;Redis 挂了也不影响任何业务功能,只是在线数暂时不准。

实测:一个人登录显示 1,第二个账号登录变 2,登出立刻回落到 1。 在这里插入图片描述


六、升级方式

两个交付形态,都是覆盖安装,数据库结构自动迁移,不需要手工执行 SQL。

Windows 免安装版

  1. 下载 项目管理系统_免安装版_v1.0.46.exe(或对应的 zip 备用包);
  2. 停掉正在运行的旧版(托盘图标退出,或关掉启动器窗口);
  3. 直接运行新 exe,安装向导走完即可;
  4. 将安装路径中payload文件夹路径下的runtime文件夹备份,新运行的直接覆盖,然后在复制回安装路径即可。

数据不受影响:数据库、上传的文件都在 %LOCALAPPDATA%\TWO-PMS\data 下,跟程序目录分离,换版本、甚至删掉程序重装都不会丢数据。

Linux(deb 包)

# 建议先备份(按实际路径调整)
mysqldump -u root -p two_pms > two_pms_backup_$(date +%F).sql

# 覆盖安装
sudo dpkg -i two-pms_1.0.46_amd64.deb

# 如果提示依赖问题
sudo apt-get install -f

装完服务自动重启,浏览器访问 http://<服务器IP>:3001。原来 1.0.42 之前装的库,首次启动会自动补上「访问综合分析」这条权限并授给相关角色,日志里能看到「综合分析权限:补授 N 条角色授权」字样,属正常现象。

怎么确认升级成功了

三处可以核对:启动器标题栏的版本号、安装目录下 app-version.txt、以及最直观的——文档上传弹窗里那个「?」图标(1.0.44 才有)。都在就说明新版本跑起来了。

升级注意事项

  • 从 1.0.45 及更早版本升级:所有变更都是自动的,覆盖安装即可。
  • 用了集群 / Nginx 部署的:记得同步改 client_max_body_size 到 210m(deploy/nginx/two-pms.conf 里有现成配置),否则大压缩包会被 Nginx 先拦下来。
  • 想调整 200MB 上限的:改 .env 里的 ARCHIVE_MAX_UPLOAD_SIZE(单位字节),重启生效。

写在最后

这五个版本没有大功能,修的都是「用起来才发现」的问题。回头看,1.0.45 和 1.0.46 的三个 bug 其实是同一类病:接口响应里少给了字段,前端只能一直显示空值——页面看起来「坏了」,其实数据通道压根没接上。这类问题单元测试不容易覆盖(接口本身是 200,只是内容缺斤少两),最后都是靠真实使用暴露的。

下一步计划:研发门户的交付物上传还是老的 10MB 单档限制,下一版本会把压缩包这套双档限额同步过去。有其他想吐槽的点,欢迎评论区留言。


系统基于 AGPL v3 开源,技术栈:React 18 + TypeScript + Vite / Node.js + Express + TypeORM + MySQL 8。