轻量级研发项目管理系统 · 需求 / 缺陷 / 迭代 / 版本 / 报表 / AI 助手
PM System 是一套面向中小研发团队的项目管理系统,覆盖研发交付的核心链路: 需求全流程跟踪、缺陷生命周期管理、迭代规划与燃尽、版本发布、质量报表, 并内置 MCP 服务让 AI 编程助手(Claude / Cursor 等)直接读写 PM 数据—— 自动提单、查需求、流转状态都可以交给 AI 完成。
草稿 → 评审 → 排期 → 开发 → 提测 → 验收全流程;表格 / 看板双视图;历史版本快照可回滚。
严重度 / 优先级 / 影响与解决版本 / 重复单归并 / 重开计数,流转规则内置校验,回归不遗漏。
迭代规划池拖拽入迭代、简化燃尽图、成员负载;版本聚合需求与缺陷进度、生成发布说明草稿。
Bug 新增/关闭趋势、存量趋势、状态与严重度分布、需求进度、CFD 累积流、成员负载。
项目级自定义工作流(状态集 + 流转矩阵 + 二次确认规则)、自定义字段、模块树、标签、视图。
内置 stdio MCP 服务器:AI 可创建/流转需求缺陷、自动提单幂等查重、按名称解析版本迭代。
工作台:我的待办、待我验收、当前迭代、版本进度与严重度分布
组件均可独立替换:文件存储(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 鉴权代理 |
| AI | MCP(stdio)· httpx | pm-mcp 独立包,26 个工具 |
| 部署 | Docker · K3s/K8s · Traefik | 见「生产部署」;docker-compose 亦可 |
| 依赖 | 版本 | 用途 |
|---|---|---|
| Python | ≥ 3.11 | 后端与 MCP 服务 |
| Node.js | ≥ 18 | 前端构建 |
| MongoDB | ≥ 4.4(建议 6.0+) | 唯一必需的存储 |
# 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_INITIAL_PASSWORD,见部署章节)。cd pmsystemfrontend
npm install
npm run dev # http://127.0.0.1:5175(/api 自动代理到 8402)
登录页 —— 使用 admin / admin123 进入
| 变量 | 默认 | 说明 |
|---|---|---|
MONGODB_URI | mongodb://localhost:27017/pm_system | 连接串需含库名 |
SECRET_KEY | - | JWT 签名密钥,生产必改 |
ADMIN_INITIAL_PASSWORD | - | 首次种入 admin 的密码;未设置且未放宽时启动失败 |
ALLOW_DEFAULT_ADMIN_PASSWORD | false | 本地开发设 true 放宽回 admin123 |
CORS_ORIGINS | localhost:5173,5174 | 逗号分隔;走 vite 代理时无需改 |
RESOURCEPLATFORM_BASE_URL / _TOKEN | - | resourceplatform 文件服务(可选旧后端,默认不启用) |
GITLAB_BASE_URL / GITLAB_WEBHOOK_TOKEN | - | GitLab 集成(可选,token 空则 webhook 关闭) |
附件与正文内嵌图通过统一接口存取(app/services/storage/),
前端一律经 /files/ 鉴权代理访问,切换后端前端与数据结构零改动:
| 后端 | 说明 | 配置 |
|---|---|---|
local(默认) | 本地磁盘,零外部依赖;生产挂持久化卷 | STORAGE_DIR=./data/uploads |
s3 | S3 兼容云:AWS S3 / 阿里云 OSS / 腾讯云 COS / MinIO / Cloudflare R2 | pip install -e ".[s3]" + STORAGE_S3_* 系列变量 |
resourceplatform | 自建文件服务(既有部署兼容) | RESOURCEPLATFORM_BASE_URL / _TOKEN |
STORAGE_BACKEND=local|s3|resourceplatform。旧数据不迁移即可读——
既有部署配回 resourceplatform 原样工作,新部署开箱即用 local。# 后端(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
两个子项目各自提供 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 节。推荐的前端 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 构建参数。# 后端 /health 同时探测 MongoDB 连通性,直接用作探针 kubectl rollout status deploy/pmsystem-backend -n studio curl http://<backend-service>/health # {"status":"ok"}
/health;kubectl apply;以下截图来自内置的「演示项目」(一款虚拟手游的研发过程),可按此结构快速上手。
每个项目拥有独立的需求/缺陷/迭代/版本/设置与成员体系;项目 Key 创建后不可修改,
单据编号以 {KEY}-序号 展示(如 DEMO-12),可直达搜索。
项目列表 —— 每个项目独立空间,右上角新建
我的待办(负责的未关闭 Bug / 进行中需求)、待我验收、当前迭代与版本速览、最近访问
左侧模块树(两级,支持子模块聚合计数)+ 多维筛选(状态/优先级/负责人/目标版本/迭代/标签/关键词), 支持「仅看我负责的」、保存自定义视图、导出/导入 Excel。
需求列表 —— 表格视图
看板视图 —— 按状态分列,可拖拽流转
需求详情 —— Markdown 正文 / 验收标准、任务子项(2/3)、附件、历史版本快照、右侧属性面板直接编辑
内置需求工作流(可在项目设置中自定义):
已排期必须绑定目标版本或所属迭代;已拒绝可重开为草稿(保留全部历史)。
缺陷列表 —— 严重度 / 优先级 / 解决方案多维筛选
缺陷详情 —— 复现步骤 / 期望 / 实际 / 环境、影响与解决版本、关联需求、评论(支持 @ 提及与表情回应)
内置缺陷工作流:
流转规则内置校验:进「已解决」必填解决方案与解决版本(解决方案=重复 时必须指定主单并自动去重归并); 重新打开 / 拒绝 / 挂起必填原因并自动写入评论;重开后负责人自动回指最近修复人;关闭时存在未关闭关联 Bug 会阻断(可二次确认放行)。
迭代详情 —— 进度 / 按状态分布 / 成员负载 / 简化燃尽图(实线实际 · 虚线理想)
版本卡片 —— 规划中 → 开发中 → 已发布 → 已归档;聚合需求进度与未关 Bug,支持生成发布说明草稿
报表 —— 新增/关闭/净增/关闭率 KPI,每日趋势、存量趋势、状态分布、严重度分布、CFD、团队速度
成员管理 —— 项目角色:管理员(全部)/ 成员(增改单据)/ 观察者(只读)
自定义工作流 —— 状态集、流转矩阵、二次确认规则完全可配;支持跨项目复制模板
设置页还提供:模块树、标签、自定义字段(文本/单选/人员/日期,作用于需求或缺陷)、 通知偏好、API Token(供 CI / MCP 使用)与危险区(清空回收站等)。
DEMO-12)+ 标题模糊;pm-mcp 是一个独立的 MCP(Model Context Protocol)stdio 服务器,
让 Claude Code / Claude Desktop / Cursor 等 AI 助手直接操作 PM 系统——
用自然语言完成建单、流转、查询与自动提单。
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)
以 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"
}
}
}
}
| 域 | 工具 |
|---|---|
| 项目 | 项目概览统计(get_project) |
| 需求 | 列表 / 详情 / 新建 / 流转(必填原因客户端预检) |
| 缺陷 | 列表 / 详情 / 新建 / 流转 / 自动提单(幂等查重) |
| 版本 | 列表 / 详情 / 新建 / 流转 |
| 迭代 | 列表 / 新建 |
dedup_key 幂等查重——
已有未关闭同键单时追加「第 N 次复现」评论而非重复建单;历史单均已关闭时新建并自动引用旧单编号。名称解析:版本 / 迭代 / 标签 / 模块 / 成员均支持按名称传参(自动解析为 id,带 60s 缓存与歧义候选提示);
编号支持 DEMO-12、纯数字与 ObjectId 三种形式。
双层权限取并集:全局角色(平台管理页配置)∪ 项目角色(项目设置 → 成员)。
| 层 | 角色 | 权限 |
|---|---|---|
| 全局 | admin | 全部(含平台管理 / 用户管理) |
tester / developer | pm:view / pm:create / pm:edit | |
viewer | pm:view | |
| 个人微调 | 支持对单个用户增发 / 剥夺权限位 | |
| 项目 | admin | 项目管理、成员管理、解锁、删除 |
member | 查看 / 建单 / 编辑 | |
viewer | 只读 |
pm_ 前缀)等同其创建人身份,供 CI / MCP 长期使用,可随时吊销;# 后端全量(需本地 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 工具契约。
不是。副本集启用多文档事务;单机模式后端探测到后自动降级为顺序写(启动时打 warning),功能完全一致。
生产:直接更新库中 admin 用户的密码哈希,或用 ADMIN_INITIAL_PASSWORD 重建实例(仅首次种入生效)。
本地开发设 ALLOW_DEFAULT_ADMIN_PASSWORD=true 用 admin123。
前端镜像构建参数 --base=/pms/ 与 VITE_API_BASE=/pms/api/v1 必须与 Ingress 路径一致;
后端无需感知路径前缀(前端 nginx 负责改写转发)。
默认写入本地磁盘(STORAGE_DIR,零外部依赖,容器部署挂持久化卷即可),也可切换 S3 兼容云或自建文件服务(见 3.5 节)。所有下载统一经后端 /files 鉴权代理,前端无感。
不会。编号按项目原子发号,软删也占号,删除后新建的单据继续向后编号。