PM System

轻量级研发项目管理系统 · 需求 / 缺陷 / 迭代 / 版本 / 报表 / AI 助手

FastAPI + Beanie MongoDB Vue 3 + Element Plus MCP(AI 助手可用) K3s 一键部署
🚀 五分钟跑起来 📖 查看使用指南

01简介

PM System 是一套面向中小研发团队的项目管理系统,覆盖研发交付的核心链路: 需求全流程跟踪、缺陷生命周期管理、迭代规划与燃尽、版本发布、质量报表, 并内置 MCP 服务让 AI 编程助手(Claude / Cursor 等)直接读写 PM 数据—— 自动提单、查需求、流转状态都可以交给 AI 完成。

📋需求管理

草稿 → 评审 → 排期 → 开发 → 提测 → 验收全流程;表格 / 看板双视图;历史版本快照可回滚。

🐞缺陷管理

严重度 / 优先级 / 影响与解决版本 / 重复单归并 / 重开计数,流转规则内置校验,回归不遗漏。

🏃迭代与版本

迭代规划池拖拽入迭代、简化燃尽图、成员负载;版本聚合需求与缺陷进度、生成发布说明草稿。

📊报表

Bug 新增/关闭趋势、存量趋势、状态与严重度分布、需求进度、CFD 累积流、成员负载。

⚙️深度可配置

项目级自定义工作流(状态集 + 流转矩阵 + 二次确认规则)、自定义字段、模块树、标签、视图。

🤖AI 助手(MCP)

内置 stdio MCP 服务器:AI 可创建/流转需求缺陷、自动提单幂等查重、按名称解析版本迭代。

页面速览

工作台

工作台:我的待办、待我验收、当前迭代、版本进度与严重度分布

02系统架构

浏览器 Vue 3 + Element Plus 前端容器(nginx) 静态资源 + /api 反向代理 HTTPS /pms 后端 FastAPI REST API · JWT/API Token /api/v1 MongoDB Beanie ODM AI 编程助手 Claude / Cursor 等 pm-mcp(stdio) 26 个工具 · HTTP 调后端 GitLab commit 关联 webhook webhook(可选) 文件存储 local / S3 / 自建服务 (可插拔后端)

组件均可独立替换:文件存储(local / S3 / 自建服务)与 GitLab 集成为可选,最小依赖仅需 MongoDB。

技术栈

层技术说明
前端Vue 3 · Vite · Pinia · Element Plus · ECharts路由级代码分割、Element Plus / ECharts 按需加载
后端FastAPI · Beanie · Motor · PyJWT · bcrypt服务层分层、多文档事务(单机自动降级)、原子发号
存储MongoDB ≥ 4.4副本集启用事务,单机自动降级为顺序写
文件存储本地磁盘(默认)/ S3 兼容云(boto3 可选)/ 自建文件服务统一接口可插拔(app/services/storage),下载统一走 /files 鉴权代理
AIMCP(stdio)· httpxpm-mcp 独立包,26 个工具
部署Docker · K3s/K8s · Traefik见「生产部署」;docker-compose 亦可

03快速开始(本地开发)

3.1 环境要求

依赖版本用途
Python≥ 3.11后端与 MCP 服务
Node.js≥ 18前端构建
MongoDB≥ 4.4(建议 6.0+)唯一必需的存储

3.2 启动后端(端口 8402)

# 1. 安装依赖
cd pmsystembackend
python -m venv .venv
.venv/Scripts/pip install -e .        # Windows
# .venv/bin/pip install -e .          # macOS / Linux

# 2. 准备 .env(最小配置)
MONGODB_URI=mongodb://localhost:27017/pm_system
ALLOW_DEFAULT_ADMIN_PASSWORD=true     # 本地开发放宽为 admin123

# 3. 启动
.venv/Scripts/uvicorn app.main:app --host 127.0.0.1 --port 8402 --reload
首次启动会自动建索引、种入内置角色与默认项目。admin / admin123(生产必须用 ADMIN_INITIAL_PASSWORD,见部署章节)。

3.3 启动前端(端口 5175)

cd pmsystemfrontend
npm install
npm run dev          # http://127.0.0.1:5175(/api 自动代理到 8402)

3.4 登录

登录页

登录页 —— 使用 admin / admin123 进入

3.5 后端环境变量速查

变量默认说明
MONGODB_URImongodb://localhost:27017/pm_system连接串需含库名
SECRET_KEY-JWT 签名密钥,生产必改
ADMIN_INITIAL_PASSWORD-首次种入 admin 的密码;未设置且未放宽时启动失败
ALLOW_DEFAULT_ADMIN_PASSWORDfalse本地开发设 true 放宽回 admin123
CORS_ORIGINSlocalhost:5173,5174逗号分隔;走 vite 代理时无需改
RESOURCEPLATFORM_BASE_URL / _TOKEN-resourceplatform 文件服务(可选旧后端,默认不启用)
GITLAB_BASE_URL / GITLAB_WEBHOOK_TOKEN-GitLab 集成(可选,token 空则 webhook 关闭)

3.5 附件与图片存储(可插拔后端)

附件与正文内嵌图通过统一接口存取(app/services/storage/), 前端一律经 /files/ 鉴权代理访问,切换后端前端与数据结构零改动:

后端说明配置
local(默认)本地磁盘,零外部依赖;生产挂持久化卷STORAGE_DIR=./data/uploads
s3S3 兼容云:AWS S3 / 阿里云 OSS / 腾讯云 COS / MinIO / Cloudflare R2pip install -e ".[s3]" + STORAGE_S3_* 系列变量
resourceplatform自建文件服务(既有部署兼容)RESOURCEPLATFORM_BASE_URL / _TOKEN
切换方式:STORAGE_BACKEND=local|s3|resourceplatform。旧数据不迁移即可读—— 既有部署配回 resourceplatform 原样工作,新部署开箱即用 local。

04生产部署(Docker / K3s)

4.1 构建镜像

# 后端(Python 3.13 slim)
cd pmsystembackend
docker build -t registry.example.com/your-org/pmsystem-backend:v1.0.0 .
docker push registry.example.com/your-org/pmsystem-backend:v1.0.0

# 前端(多阶段:Vite 构建 + nginx 托管,--base=/pms/)
cd pmsystemfrontend
docker build -t registry.example.com/your-org/pmsystem-frontend:v1.0.0 .
docker push registry.example.com/your-org/pmsystem-frontend:v1.0.0

4.2 Kubernetes 清单

两个子项目各自提供 deploy/deployment.yaml(Deployment + Service), 直接 kubectl apply -f deploy/deployment.yaml。 Secret 需预先创建(模板见 deploy/secret.yaml.example):

apiVersion: v1
kind: Secret
metadata:
  name: pmsystem-secret
  namespace: studio
stringData:
  MONGODB_URI: mongodb://user:pass@mongo.<namespace>:27017/pm_system
  ADMIN_INITIAL_PASSWORD: <强口令,启动 fail-fast 校验>
  SECRET_KEY: <随机 hex:openssl rand -hex 32>
  RESOURCEPLATFORM_TOKEN: <与附件服务一致,可选>
  GITLAB_WEBHOOK_TOKEN: <随机 hex,可选>
文件存储:STORAGE_BACKEND 默认 local, 落盘到 STORAGE_DIR(容器部署需为后端挂持久化卷);既有部署可设 resourceplatform,或装 s3 扩展接对象存储,详见 3.5 节。

4.3 路由与网关

推荐的前端 Ingress 写法(Traefik示例,路径 /pms): 前端容器内 nginx 承担静态资源 + SPA 回退 + 把 /api/ 反代到后端 Service, 因此外网只需暴露前端一个入口:

# pmsystemfrontend/deploy/deployment.yaml 节选
kind: Ingress
spec:
  rules:
    - host: pm.example.com
      http:
        paths:
          - path: /pms
            backend:
              service:
                name: pmsystem-frontend
                port: { number: 80 }
注意:前端镜像构建时通过 --base=/pms/ 与 VITE_API_BASE=/pms/api/v1 注入子路径;如果你的站点部署在根路径,请改 Dockerfile 构建参数。

4.4 健康检查与升级

# 后端 /health 同时探测 MongoDB 连通性,直接用作探针
kubectl rollout status deploy/pmsystem-backend -n studio
curl http://<backend-service>/health    # {"status":"ok"}

05使用指南

以下截图来自内置的「演示项目」(一款虚拟手游的研发过程),可按此结构快速上手。

5.1 多项目

每个项目拥有独立的需求/缺陷/迭代/版本/设置与成员体系;项目 Key 创建后不可修改, 单据编号以 {KEY}-序号 展示(如 DEMO-12),可直达搜索。

项目列表

项目列表 —— 每个项目独立空间,右上角新建

5.2 工作台

工作台

我的待办(负责的未关闭 Bug / 进行中需求)、待我验收、当前迭代与版本速览、最近访问

5.3 需求管理

左侧模块树(两级,支持子模块聚合计数)+ 多维筛选(状态/优先级/负责人/目标版本/迭代/标签/关键词), 支持「仅看我负责的」、保存自定义视图、导出/导入 Excel。

需求列表

需求列表 —— 表格视图

需求看板

看板视图 —— 按状态分列,可拖拽流转

需求详情

需求详情 —— Markdown 正文 / 验收标准、任务子项(2/3)、附件、历史版本快照、右侧属性面板直接编辑

内置需求工作流(可在项目设置中自定义):

草稿→ 待评审→ 已排期→ 开发中→ 已提测→ 已验收→ 已关闭

已排期必须绑定目标版本或所属迭代;已拒绝可重开为草稿(保留全部历史)。

5.4 缺陷管理

缺陷列表

缺陷列表 —— 严重度 / 优先级 / 解决方案多维筛选

缺陷详情

缺陷详情 —— 复现步骤 / 期望 / 实际 / 环境、影响与解决版本、关联需求、评论(支持 @ 提及与表情回应)

内置缺陷工作流:

新建→ 已确认→ 修复中→ 已解决→ 已关闭

流转规则内置校验:进「已解决」必填解决方案与解决版本(解决方案=重复 时必须指定主单并自动去重归并); 重新打开 / 拒绝 / 挂起必填原因并自动写入评论;重开后负责人自动回指最近修复人;关闭时存在未关闭关联 Bug 会阻断(可二次确认放行)。

5.5 迭代与燃尽

迭代详情

迭代详情 —— 进度 / 按状态分布 / 成员负载 / 简化燃尽图(实线实际 · 虚线理想)

5.6 版本管理

版本列表

版本卡片 —— 规划中 → 开发中 → 已发布 → 已归档;聚合需求进度与未关 Bug,支持生成发布说明草稿

5.7 报表

报表

报表 —— 新增/关闭/净增/关闭率 KPI,每日趋势、存量趋势、状态分布、严重度分布、CFD、团队速度

5.8 项目设置

成员管理

成员管理 —— 项目角色:管理员(全部)/ 成员(增改单据)/ 观察者(只读)

自定义工作流

自定义工作流 —— 状态集、流转矩阵、二次确认规则完全可配;支持跨项目复制模板

设置页还提供:模块树、标签、自定义字段(文本/单选/人员/日期,作用于需求或缺陷)、 通知偏好、API Token(供 CI / MCP 使用)与危险区(清空回收站等)。

5.9 通知与协作

5.10 其他能力

06AI 助手集成(pm-mcp)

pm-mcp 是一个独立的 MCP(Model Context Protocol)stdio 服务器, 让 Claude Code / Claude Desktop / Cursor 等 AI 助手直接操作 PM 系统—— 用自然语言完成建单、流转、查询与自动提单。

6.1 安装与配置

cd pm-mcp
pip install -e .

# 工作目录或家目录建 .env
PM_BASE_URL=http://127.0.0.1:8402      # 后端地址
PM_TOKEN=pm_xxxxxxxx                   # 在 PM 项目设置 → API Token 生成
PM_PROJECT_KEY=DEMO                    # 默认项目(每次调用也可显式传 project_key)

6.2 接入 AI 客户端

以 Claude Code 为例(.mcp.json):

{
  "mcpServers": {
    "pm": {
      "command": "pm-mcp",
      "env": {
        "PM_BASE_URL": "http://127.0.0.1:8402",
        "PM_TOKEN": "pm_xxxxxxxx",
        "PM_PROJECT_KEY": "DEMO"
      }
    }
  }
}

6.3 工具一览(26 个)

域工具
项目项目概览统计(get_project)
需求列表 / 详情 / 新建 / 流转(必填原因客户端预检)
缺陷列表 / 详情 / 新建 / 流转 / 自动提单(幂等查重)
版本列表 / 详情 / 新建 / 流转
迭代列表 / 新建
自动提单是面向 CI/测试流水线的利器:按 dedup_key 幂等查重—— 已有未关闭同键单时追加「第 N 次复现」评论而非重复建单;历史单均已关闭时新建并自动引用旧单编号。

名称解析:版本 / 迭代 / 标签 / 模块 / 成员均支持按名称传参(自动解析为 id,带 60s 缓存与歧义候选提示); 编号支持 DEMO-12、纯数字与 ObjectId 三种形式。

07权限模型

双层权限取并集:全局角色(平台管理页配置)∪ 项目角色(项目设置 → 成员)。

层角色权限
全局admin全部(含平台管理 / 用户管理)
tester / developerpm:view / pm:create / pm:edit
viewerpm:view
个人微调支持对单个用户增发 / 剥夺权限位
项目admin项目管理、成员管理、解锁、删除
member查看 / 建单 / 编辑
viewer只读

08测试

# 后端全量(需本地 MongoDB,自动使用独立测试库 pm_system_test)
cd pmsystembackend && pytest tests/ -q

# 发版前冒烟回归(建单→流转→规则→回收站→级联清除全链路)
pytest tests/test_smoke_regression.py -v

# MCP 服务(respx 全程 mock,无需真实后端)
cd pm-mcp && pytest tests/ -q

覆盖:单据 CRUD 与状态机规则、批量操作、自定义字段、工作流自定义、权限(成员/非成员/Token)、 通知偏好、附件、导入导出、回收站级联、MCP 工具契约。

09FAQ

Q:MongoDB 必须是副本集吗?

不是。副本集启用多文档事务;单机模式后端探测到后自动降级为顺序写(启动时打 warning),功能完全一致。

Q:忘了 admin 密码?

生产:直接更新库中 admin 用户的密码哈希,或用 ADMIN_INITIAL_PASSWORD 重建实例(仅首次种入生效)。 本地开发设 ALLOW_DEFAULT_ADMIN_PASSWORD=true 用 admin123。

Q:部署在子路径(如 /pms)需要注意什么?

前端镜像构建参数 --base=/pms/ 与 VITE_API_BASE=/pms/api/v1 必须与 Ingress 路径一致; 后端无需感知路径前缀(前端 nginx 负责改写转发)。

Q:附件存储在哪?

默认写入本地磁盘(STORAGE_DIR,零外部依赖,容器部署挂持久化卷即可),也可切换 S3 兼容云或自建文件服务(见 3.5 节)。所有下载统一经后端 /files 鉴权代理,前端无感。

Q:单据编号会复用吗?

不会。编号按项目原子发号,软删也占号,删除后新建的单据继续向后编号。