# lingshu-pm **Repository Path**: magic2060/lingshu-pm ## Basic Information - **Project Name**: lingshu-pm - **Description**: 沿用`lingshu-` 前缀，`pm` 是 Project Management 的通用缩写，以后加需求、测试、工时这些模块都不用改名。 备选：`lingshu-zen` （直接借"禅"的意象）、`lingshu-team` （更偏协作方向） - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-08 - **Last Updated**: 2026-11-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 灵枢项目管理（lingshu-pm） 一个类禅道（ZenTao）的开源项目管理工具：产品 / 项目 / 迭代 / 需求 / 任务 / Bug 全流程，外加可解释的 AI 进度风险、任务难度与人员画像分析。 后端 Spring Boot 3 + MyBatis-Plus，前端 Vue 3 + Element Plus，默认使用 SQLite 单文件数据库，**下载即用，不需要安装数据库**；也可以切换 MySQL 作为团队服务器。 > 当前进度：**第三阶段（AI 分析）已完成规则引擎自测**，项目进入收尾。 > 产品 / 项目 / 迭代 / 需求 / 任务 / Bug、任务指派与状态流转、逾期标记、看板拖拽、列表筛选、仪表盘燃尽图均已可用；AI 进度风险 / 任务难度 / 人员画像支持无 key 规则引擎、可解释指标与快照对比。大模型分支与第四阶段见文末路线图。 --- ## 1. 技术栈 | 层次 | 选型 | 说明 | | --- | --- | --- | | 后端框架 | Spring Boot 3.2.5（JDK 17+） | 内嵌 Tomcat，单体 jar 即可运行 | | ORM | MyBatis-Plus 3.5.5 | 分页插件、逻辑删除、字段自动填充 | | 鉴权 | JWT（jjwt 0.11.5）+ 自定义拦截器 | 不引入完整 Spring Security 过滤链，只使用 BCrypt | | 数据库 | SQLite（默认）/ MySQL | 一套代码，通过 profile 切换 | | 前端 | Vue 3.4 + Vite 5 + Element Plus 2.7 | 若依风格后台布局，动态菜单与按钮权限 | | 状态 / 路由 | Pinia + Vue Router 4 | 后端菜单树 → 动态路由 | | 打包 | spring-boot-maven-plugin + jlink | 单体 jar 内嵌前端 + 精简 JRE，双击脚本启动 | ## 2. 架构图 ``` ┌──────────────────────────────────────────────────────────────┐ │ 浏览器 │ │ Vue3 + Element Plus SPA（登录 / 工作台 / 项目管理 / 系统管理 / 监控） │ └───────────────┬──────────────────────────────────────────────┘ │ HTTP /api/**（Authorization: Bearer ） ┌───────────────▼──────────────────────────────────────────────┐ │ Spring Boot 单体应用 │ │ │ │ controller 接收请求、参数校验、统一返回 AjaxResult │ │ │ │ │ framework AuthInterceptor（JWT + @RequiresPerm） │ │ LogAspect（@Log 操作日志，异步入库） │ │ │ │ │ service 业务规则（账号权限、产品项目、任务流转、燃尽统计） │ │ │ │ │ mapper MyBatis-Plus BaseMapper + 少量原生 SQL │ │ │ │ │ domain 实体（sys_* 系统表 + pm_* 业务表） │ │ │ │ common 统一返回、分页、异常、常量、工具 │ │ config 数据源、MyBatis-Plus、WebMvc、数据库初始化 │ └───────────────┬──────────────────────────────────────────────┘ │ ┌───────▼────────┐ ┌──────────────────────┐ │ SQLite 文件库 │ 或 │ MySQL（服务器部署） │ │ data/*.db │ │ lingshu_pm │ └────────────────┘ └──────────────────────┘ ``` 分层刻意对照若依（RuoYi）：`controller / service / mapper / domain / common`，容易上手，也方便后续把若依的代码习惯搬过来。 ## 3. 目录结构 ``` lingshu-pm/ ├─ backend/ # Spring Boot 后端 │ ├─ pom.xml │ └─ src/main/ │ ├─ java/com/lingshu/pm/ │ │ ├─ LingshuPmApplication.java │ │ ├─ common/ # AjaxResult、TableDataInfo、PageQuery、异常、JWT、SecurityUtils │ │ ├─ config/ # 数据源、MyBatis-Plus、WebMvc、数据库初始化、BCrypt │ │ ├─ controller/ # Auth / 用户 / 角色 / 菜单 / 日志 / 产品 / 项目 / 迭代 / 需求 / 任务 / Bug / 仪表盘 │ │ ├─ domain/ # SysUser、SysRole、SysMenu、SysOperLog；PmProduct、PmProject、PmSprint、PmDemand、PmTask、PmBug │ │ ├─ framework/ # AuthInterceptor、LogAspect、@Log、@RequiresPerm │ │ ├─ mapper/ # MyBatis-Plus Mapper │ │ └─ service/ # 接口 + impl │ └─ resources/ │ ├─ application.yml # 公共配置（JWT、AI、MyBatis-Plus） │ ├─ application-sqlite.yml # SQLite 单机模式 │ └─ application-mysql.yml # MySQL 服务器模式 ├─ frontend/ # Vue3 前端 │ ├─ vite.config.js # /api 代理到 127.0.0.1:8080 │ └─ src/ │ ├─ api/ # 与后端接口一一对应 │ ├─ layout/ # 顶栏 + 侧边菜单 + 内容区 │ ├─ router/ # 固定路由（登录 / 工作台 / 404） │ ├─ permission.js # 登录态守卫 + 后端菜单转动态路由 │ ├─ store/ # Pinia：token、用户、权限 │ ├─ views/ # system/*、monitor/operlog、pm/*（仪表盘、产品、项目、迭代、需求、任务、看板、Bug） │ └─ utils/ # axios 封装、token 存取 ├─ script/ │ ├─ sql/sqlite/01-schema.sql # SQLite 建表 │ ├─ sql/sqlite/02-data.sql # 初始化数据（超管、角色、菜单） │ ├─ sql/mysql/01-schema.sql # MySQL 建表 │ ├─ sql/mysql/02-data.sql # MySQL 初始化数据 │ ├─ maven-settings.xml # 阿里云 Maven 镜像 │ ├─ build.ps1 # 一键打包（前端 + jar + jlink JRE） │ └─ start.bat # 单机启动脚本（打包时复制到 release/） ├─ docs/ # 面向零基础的详细文档 ├─ README.md └─ .gitignore ``` ## 4. 环境要求 | 工具 | 版本 | 检查命令 | | --- | --- | --- | | JDK | **17 及以上** | `java -version` | | Maven | 3.6+ | `mvn -v` | | Node.js | 18+（推荐 20/22） | `node -v` | | npm | 9+ | `npm -v` | > **Windows 常见坑**：机器上可能同时装了 JDK 8，`java -version` 显示 1.8 时，Maven 会编译失败。 > 先设置当前终端的 JAVA_HOME（路径换成你自己的 JDK 17）： > > ```powershell > $env:JAVA_HOME='C:\Program Files\Java\jdk-17' > $env:PATH="$env:JAVA_HOME\bin;$env:PATH" > java -version # 必须显示 17.x > ``` ## 5. 快速开始（开发模式） ### 5.1 启动后端（SQLite，零配置） ```powershell # 在项目根目录执行；首次会下载依赖，走阿里云镜像 mvn -s script/maven-settings.xml -f backend/pom.xml spring-boot:run ``` 启动成功后：。 - 数据库文件自动创建在 `backend/data/lingshu-pm.db`（`spring-boot:run` 的工作目录是 backend）。 - 首次启动会自动建表并写入超管账号，无需手工导入 SQL。 - 想固定数据库位置，可设置环境变量：`$env:LS_DB_PATH='D:\data\lingshu-pm.db'`。 ### 5.2 启动前端（热更新） ```powershell cd frontend npm install --registry=https://registry.npmmirror.com npm run dev ``` 浏览器打开 。Vite 已把 `/api` 代理到 8080，前后端联调不需要配置跨域。 ### 5.3 默认账号 | 账号 | 密码 | 角色 | 用途 | | --- | --- | --- | --- | | `admin` | `admin123` | 超级管理员 | 全部权限 | | `lisi` | `123456` | 项目经理 | 全部业务菜单：产品 / 项目 / 迭代 / 需求 / 任务 / Bug / 仪表盘 | | `zhangsan` | `123456` | 研发人员 | 仪表盘、任务看板、任务状态流转、Bug 查看与修改 | > 生产环境请第一时间修改 admin 密码，并设置 `LS_JWT_SECRET` 环境变量。 ### 5.4 第二阶段功能与示例数据 启动后侧边栏「项目管理」下会看到：**仪表盘、产品管理、项目管理、迭代管理、需求管理、任务列表、任务看板、Bug 管理**。 - 首次启动会写入一套演示数据（2 个产品、2 个项目、2 个迭代、4 条需求、12 个任务、3 个 Bug），包含 2 个逾期任务与 1 个进行中的迭代，方便直接查看看板与燃尽图。 - 演示数据可以在页面上删除；删除后不会在下次启动重新出现。 - 任务列表支持项目 / 迭代 / 指派人 / 状态 / 优先级 / 关键字 / 只看逾期筛选，按优先级、预计工时、实际工时、截止日期排序并分页。 - 任务支持新增修改、指派、状态流转（待办 → 进行中 → 已完成 → 已关闭），进入已完成会自动记录完成时间，退回会清空完成时间。 - 看板按状态分四列，拖拽卡片会调用 `PUT /api/pm/task/{id}/status`，刷新后状态保持。 - 仪表盘展示我的待办、全团队逾期任务、迭代完成数 / 总数、按工时燃尽曲线。燃尽口径为**按任务完成时间回溯推算每日剩余工时**（不是每日快照），页面已明确标注。 ### 5.5 第三阶段：AI 分析 侧边栏「项目管理 → AI 分析」下有三个页签： | 页签 | 规则引擎结论 | 关键指标 | | --- | --- | --- | | 项目进度风险 | 低 / 中 / 高风险（0-100 分） | 剩余工时、剩余天数、历史日均产出、所需日均、产能缺口、逾期率、时间进度偏差 | | 任务难度评估 | 简单 / 中等 / 困难 / 极难 + 建议工时 | 描述字数、复杂关键词命中数、同模块历史样本、中位耗时、工时偏差、置信度 | | 人员能力画像 | 负载偏高 / 正常 / 偏低 + 能力标签 | 近 90 天完成数、按时率、平均工时偏差、周均吞吐、Bug/完成比、主力模块、负荷指数 | - **无 key 也能用**：未配置 `LS_AI_API_KEY` 时全部结论由本地规则引擎计算，页面顶部显示「规则引擎」，不会空白或报错。 - **可解释**：每类分析都展示指标数值、单位、口径来源、命中的规则条件与加分过程，以及原始证据（逾期任务 / 历史同类任务 / 最近完成任务）。 - **可对比**：每次分析自动保存快照，历史快照可勾选两条对比，变化项高亮显示。 - **大模型只做补充**：配置 key 后，模型基于规则指标补充“原因 / 建议 / 口头汇报”，不会修改等级、工时和标签；调用失败自动回退并标注。 - 示例数据实测：项目「灵枢 V1.2 发布」为高风险（剩余 10 天 51 小时、所需日均 5.1 高于历史 2.9）；任务「权限按钮走查」中等（34.9 分）；张三按时率 100%、主力模块权限 80%。 - 详细公式、prompt 位置与换模型方法见 [docs/04-ai-analysis.md](docs/04-ai-analysis.md)。 ## 6. 单机版：打包成"双击即用" 目标产物：`release/` 目录，里面是 `lingshu-pm.jar` + 精简 JRE + 启动脚本，拷到任何 Windows 机器双击 `start.bat` 即可（目标机不需要装 Java）。 ```powershell # 在项目根目录，用 JDK17 执行 powershell -ExecutionPolicy Bypass -File script\build.ps1 ``` 脚本会依次：`npm install`（缺依赖时）→ `npm run build` → `mvn package`（把 dist 打进 jar 的 `static/`）→ `jlink` 生成 `release\jre` → 复制启动脚本。 产物结构： ``` release/ ├─ lingshu-pm.jar # 后端 + 前端静态资源 ├─ jre/ # 精简 JRE（约 40 MB） ├─ start.bat # 双击启动，自动打开浏览器 └─ data/ # 首次运行自动生成 SQLite 数据库 ``` 命令行启动（可选）： ```powershell .\jre\bin\java.exe -jar lingshu-pm.jar --server.port=8080 ``` 数据默认保存在 `release\data\lingshu-pm.db`，备份时复制这个文件即可。 ## 7. 服务器部署（团队使用） 1. 准备 MySQL 8 数据库：`CREATE DATABASE lingshu_pm DEFAULT CHARSET utf8mb4;` 2. 用 `script/sql/mysql/01-schema.sql`、`02-data.sql` 初始化（或让程序首次启动自动执行）。 3. 启动： ```bash java -jar lingshu-pm.jar \ --spring.profiles.active=mysql \ --spring.datasource.url="jdbc:mysql://127.0.0.1:3306/lingshu_pm?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai" \ --spring.datasource.username=lingshu \ --spring.datasource.password=你的密码 ``` 也可以全部用环境变量（推荐，避免密码进命令行历史）： | 环境变量 | 说明 | | --- | --- | | `LS_DB_HOST` / `LS_DB_PORT` / `LS_DB_NAME` | MySQL 地址、端口、库名 | | `LS_DB_USERNAME` / `LS_DB_PASSWORD` | MySQL 账号密码 | | `LS_JWT_SECRET` | JWT 签名密钥（**务必修改**） | | `LS_AI_BASE_URL` / `LS_AI_API_KEY` / `LS_AI_MODEL` | 大模型配置（不填 key 自动使用规则引擎） | 前端已打进 jar，直接用 Nginx 反代 8080 即可，不需要单独部署前端。 ## 8. 数据库切换 | 场景 | 配置 | | --- | --- | | 默认 SQLite | `spring.profiles.active: sqlite`（已默认） | | MySQL | 启动参数 `--spring.profiles.active=mysql` | | 自定义 SQLite 路径 | `LS_DB_PATH=/opt/lingshu/data/lingshu-pm.db` | 初始化脚本位置由 `lingshu.db.init-script-location` 决定（`classpath:db/sqlite` 或 `classpath:db/mysql`），两种方言的脚本都在 `script/sql/` 下维护，打包时会复制进 jar。 ## 9. AI 配置（第三阶段，已实现） ```yaml lingshu: ai: enabled: true base-url: ${LS_AI_BASE_URL:https://api.openai.com/v1} api-key: ${LS_AI_API_KEY:} model: ${LS_AI_MODEL:gpt-4o-mini} timeout-seconds: 60 ``` PowerShell 临时切换成自己的模型（以 DeepSeek 为例）： ```powershell $env:LS_AI_BASE_URL='https://api.deepseek.com/v1' $env:LS_AI_API_KEY='sk-xxx' $env:LS_AI_MODEL='deepseek-chat' java -jar backend\target\lingshu-pm.jar ``` - **没有 api-key 也能正常用**：所有分析由本地规则引擎计算，页面显示「规则引擎」，指标、原因、建议完整可读。 - 接口需兼容 OpenAI `POST {base-url}/chat/completions`；DeepSeek、通义千问、Kimi、vLLM、Ollama（开启兼容层）均可。 - 定量结论（等级、工时、标签）永远由规则引擎计算，大模型只补充定性说明，失败自动回退。 - prompt 位置：`backend/src/main/resources/prompts/*.txt`。 - 详细指标口径、公式、prompt 与自测记录见 [docs/04-ai-analysis.md](docs/04-ai-analysis.md)。 ## 10. Gitee 发版步骤 ```powershell git add . git commit -m "feat: 第二阶段 项目与任务主线" git tag -a v0.2.0 -m "第二阶段：产品/项目/迭代/需求/任务/Bug、看板、仪表盘燃尽" git push origin master --tags # 需要推送时手动执行，本项目开发期间不自动 push ``` 然后在 Gitee 仓库 →「发行版」→ 新建发行版：选择 `v0.2.0` 标签，上传 `release` 目录的 zip（**不要把 data/、*.db 一起打包**），填写更新说明即可。 ## 11. 路线图 | 阶段 | 内容 | 状态 | | --- | --- | --- | | 第一阶段 | 登录 / JWT / RBAC / 用户角色菜单 / 操作日志 | ✅ 已完成 | | 第二阶段 | 产品、项目、迭代、需求、任务、Bug；看板拖拽、列表筛选、仪表盘与燃尽 | ✅ 已完成 | | 第三阶段 | AI 进度风险 / 任务难度 / 人员画像；规则引擎 + 大模型；可解释指标与快照 | ✅ 规则引擎已完成并自测；大模型分支未实测（无 key） | | 第四阶段 | 站内信、附件、富文本、批量操作、CSV 导入导出、快捷键 | 待开始 | ## 12. 文档索引 - [技术栈与架构分层（对照若依）](docs/01-architecture.md) - [权限模型 RBAC 详解](docs/02-rbac.md) - [数据库表设计与 ER 说明](docs/03-database.md) - [AI 分析设计（指标口径 / 规则引擎 / 大模型）](docs/04-ai-analysis.md) - [进度与收尾说明（已完成 / 未完成 / 已知问题）](docs/PROGRESS.md) - [打包与精简 JRE](docs/05-package-jre.md) - [常见问题排查](docs/06-faq.md) ## 13. 许可 内部项目，暂未指定开源许可证；如需开源请补充 LICENSE。