293 lines
12 KiB
Markdown
293 lines
12 KiB
Markdown
# 项目管理模块设计文档
|
||
|
||
> 日期: 2026-04-12
|
||
> 位置: 系统管理 → 项目管理
|
||
> 使用者: 管理员/项目经理
|
||
|
||
## 1. 概述
|
||
|
||
在系统管理菜单下新增「项目管理」模块，用于管理整个产品的研发与非研发任务进度。支持甘特图、日历、表格列表、Kanban 看板四种视图，覆盖项目 → 阶段 → 任务 → 子任务的四层结构。
|
||
|
||
核心场景：电商自动化运营 Agent 平台的全生命周期管理，包含研发任务（前端、后端、AI）和运营任务（官网、隐私条款、市场推广等）。
|
||
|
||
## 2. 技术选型
|
||
|
||
| 组件 | 方案 | 理由 |
|
||
|------|------|------|
|
||
| 甘特图 | dhtmlx-gantt ^8.x (GPL) | 最成熟的甘特图库，原生支持依赖箭头、拖拽、树形层级 |
|
||
| 日历 | @fullcalendar/vue3 ^6.x | 日历视图事实标准，月/周视图开箱即用 |
|
||
| 看板拖拽 | vuedraggable ^4.x | Vue 3 拖拽排序，轻量成熟 |
|
||
| 表格 | cl-crud (已有) | 复用现有 Cool Admin CRUD 组件 |
|
||
|
||
安装位置：均安装到 `@neta/frontend`。
|
||
|
||
## 3. 数据模型
|
||
|
||
### 3.1 project_info（项目表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int, PK, auto | 主键 |
|
||
| name | varchar(100) | 项目名称 |
|
||
| description | text, nullable | 项目描述 |
|
||
| status | tinyint | 状态：0未开始 1进行中 2已完成 3已归档 |
|
||
| startDate | date, nullable | 计划开始日期 |
|
||
| endDate | date, nullable | 计划结束日期 |
|
||
| progress | int, default 0 | 进度百分比 0-100 |
|
||
| ownerId | int, nullable | 项目经理（base_sys_user.id） |
|
||
| ownerName | varchar(50), nullable | 项目经理姓名（冗余） |
|
||
| color | varchar(20), nullable | 主题色（如 #409EFF） |
|
||
| createTime | datetime | 创建时间（BaseEntity） |
|
||
| updateTime | datetime | 更新时间（BaseEntity） |
|
||
| tenantId | int | 租户ID（BaseEntity） |
|
||
|
||
### 3.2 project_phase（阶段表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int, PK, auto | 主键 |
|
||
| projectId | int | 所属项目 ID |
|
||
| name | varchar(100) | 阶段名称 |
|
||
| type | varchar(50), nullable | 分类（来自系统参数 project_task_category） |
|
||
| status | tinyint, default 0 | 状态：0未开始 1进行中 2已完成 |
|
||
| startDate | date, nullable | 开始日期 |
|
||
| endDate | date, nullable | 结束日期 |
|
||
| progress | int, default 0 | 进度 0-100 |
|
||
| sortOrder | int, default 0 | 排序序号 |
|
||
| createTime | datetime | BaseEntity |
|
||
| updateTime | datetime | BaseEntity |
|
||
| tenantId | int | BaseEntity |
|
||
|
||
### 3.3 project_task（任务表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int, PK, auto | 主键 |
|
||
| projectId | int | 所属项目 ID |
|
||
| phaseId | int, nullable | 所属阶段 ID |
|
||
| parentId | int, nullable | 父任务 ID（null 为顶级任务） |
|
||
| name | varchar(200) | 任务名称 |
|
||
| description | text, nullable | 任务描述 |
|
||
| status | tinyint, default 0 | 0待办 1进行中 2已完成 3已关闭 |
|
||
| priority | tinyint, default 2 | P0(0)紧急 P1(1)高 P2(2)中 P3(3)低 |
|
||
| category | varchar(50), nullable | 分类（来自系统参数） |
|
||
| assigneeId | int, nullable | 负责人 ID |
|
||
| assigneeName | varchar(50), nullable | 负责人姓名（冗余） |
|
||
| startDate | date, nullable | 计划开始日期 |
|
||
| endDate | date, nullable | 计划结束日期 |
|
||
| estimatedHours | decimal(8,1), default 0 | 预估工时（小时） |
|
||
| actualHours | decimal(8,1), default 0 | 实际工时（由 time_log 汇总） |
|
||
| progress | int, default 0 | 进度 0-100 |
|
||
| sortOrder | int, default 0 | 排序序号 |
|
||
| color | varchar(20), nullable | 自定义颜色（覆盖项目色） |
|
||
| createTime | datetime | BaseEntity |
|
||
| updateTime | datetime | BaseEntity |
|
||
| tenantId | int | BaseEntity |
|
||
|
||
### 3.4 project_task_dependency（任务依赖表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int, PK, auto | 主键 |
|
||
| taskId | int | 当前任务 ID |
|
||
| dependsOnTaskId | int | 前置任务 ID |
|
||
| type | tinyint, default 0 | 0:FS(完成后开始) 1:SS 2:FF 3:SF |
|
||
| createTime | datetime | BaseEntity |
|
||
| updateTime | datetime | BaseEntity |
|
||
| tenantId | int | BaseEntity |
|
||
|
||
### 3.5 project_time_log（工时记录表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int, PK, auto | 主键 |
|
||
| taskId | int | 所属任务 ID |
|
||
| userId | int | 记录人 ID |
|
||
| userName | varchar(50) | 记录人姓名（冗余） |
|
||
| logDate | date | 工作日期 |
|
||
| hours | decimal(5,1) | 工时（小时） |
|
||
| description | varchar(500), nullable | 工作内容描述 |
|
||
| createTime | datetime | BaseEntity |
|
||
| updateTime | datetime | BaseEntity |
|
||
| tenantId | int | BaseEntity |
|
||
|
||
## 4. 后端模块结构
|
||
|
||
```
|
||
packages/backend/src/modules/project/
|
||
├── config.ts
|
||
├── entity/
|
||
│ ├── info.ts -- ProjectInfoEntity
|
||
│ ├── phase.ts -- ProjectPhaseEntity
|
||
│ ├── task.ts -- ProjectTaskEntity
|
||
│ ├── task_dependency.ts -- ProjectTaskDependencyEntity
|
||
│ └── time_log.ts -- ProjectTimeLogEntity
|
||
├── controller/admin/
|
||
│ ├── info.ts -- 项目 CRUD
|
||
│ ├── phase.ts -- 阶段 CRUD
|
||
│ ├── task.ts -- 任务 CRUD + 树形查询
|
||
│ ├── task_dependency.ts -- 依赖关系管理
|
||
│ └── time_log.ts -- 工时记录 CRUD
|
||
└── service/
|
||
├── info.ts -- 项目统计、进度汇总
|
||
├── task.ts -- 任务树构建、状态流转、进度计算
|
||
└── gantt.ts -- 甘特图聚合接口
|
||
```
|
||
|
||
### 4.1 核心 API
|
||
|
||
| 路径 | 方法 | 用途 |
|
||
|------|------|------|
|
||
| `/admin/project/info/page` | GET | 项目列表分页 |
|
||
| `/admin/project/info/add` | POST | 创建项目 |
|
||
| `/admin/project/info/update` | POST | 更新项目 |
|
||
| `/admin/project/info/delete` | POST | 删除项目 |
|
||
| `/admin/project/phase/list` | GET | 某项目的阶段列表 |
|
||
| `/admin/project/phase/add` | POST | 创建阶段 |
|
||
| `/admin/project/phase/update` | POST | 更新阶段 |
|
||
| `/admin/project/phase/delete` | POST | 删除阶段 |
|
||
| `/admin/project/task/tree` | GET | 任务树（含子任务层级） |
|
||
| `/admin/project/task/page` | GET | 任务分页列表（表格视图） |
|
||
| `/admin/project/task/add` | POST | 创建任务 |
|
||
| `/admin/project/task/update` | POST | 更新任务 |
|
||
| `/admin/project/task/delete` | POST | 删除任务 |
|
||
| `/admin/project/task/ganttData` | GET | 甘特图数据（任务+阶段+依赖） |
|
||
| `/admin/project/task/ganttUpdate` | POST | 甘特图拖拽批量更新 |
|
||
| `/admin/project/task/kanban` | GET | 看板数据（按状态分组） |
|
||
| `/admin/project/task/kanbanSort` | POST | 看板拖拽排序/状态变更 |
|
||
| `/admin/project/timeLog/page` | GET | 工时记录分页 |
|
||
| `/admin/project/timeLog/add` | POST | 添加工时 |
|
||
| `/admin/project/timeLog/delete` | POST | 删除工时 |
|
||
| `/admin/project/taskDependency/add` | POST | 添加依赖 |
|
||
| `/admin/project/taskDependency/delete` | POST | 删除依赖 |
|
||
|
||
### 4.2 甘特图聚合接口 ganttData
|
||
|
||
请求：`GET /admin/project/task/ganttData?projectId=1`
|
||
|
||
响应格式（适配 DHTMLX Gantt）：
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{ "id": "p_1", "text": "阶段一", "start_date": "2026-04-01", "end_date": "2026-05-01", "progress": 0.5, "type": "project", "open": true },
|
||
{ "id": "t_1", "text": "官网设计", "start_date": "2026-04-01", "end_date": "2026-04-15", "progress": 0.3, "parent": "p_1", "priority": 1, "assignee": "张三" },
|
||
{ "id": "t_2", "text": "设计首页", "start_date": "2026-04-01", "end_date": "2026-04-07", "progress": 0, "parent": "t_1" }
|
||
],
|
||
"links": [
|
||
{ "id": 1, "source": "t_1", "target": "t_3", "type": "0" }
|
||
]
|
||
}
|
||
```
|
||
|
||
## 5. 前端模块结构
|
||
|
||
```
|
||
packages/frontend/src/modules/project/
|
||
├── views/
|
||
│ ├── list.vue -- 项目列表页（入口）
|
||
│ ├── detail.vue -- 项目详情页（四视图容器）
|
||
│ └── components/
|
||
│ ├── gantt.vue -- 甘特图视图
|
||
│ ├── calendar.vue -- 日历视图
|
||
│ ├── table.vue -- 表格列表视图
|
||
│ ├── kanban.vue -- 看板视图
|
||
│ ├── task-drawer.vue -- 任务详情抽屉
|
||
│ ├── time-log-dialog.vue -- 工时记录弹窗
|
||
│ └── phase-manager.vue -- 阶段管理弹窗
|
||
└── config.ts -- 模块菜单配置
|
||
```
|
||
|
||
### 5.1 页面流程
|
||
|
||
```
|
||
系统管理 → 项目管理（list.vue）
|
||
├── 项目卡片列表：名称、进度条、状态、负责人、日期范围
|
||
├── 新建项目按钮
|
||
└── 点击项目 → detail.vue
|
||
├── 顶部：项目信息栏（名称、进度条、日期范围、负责人、阶段管理按钮）
|
||
└── Tab 切换：甘特图 | 日历 | 列表 | 看板
|
||
```
|
||
|
||
### 5.2 四种视图
|
||
|
||
**甘特图（gantt.vue）：**
|
||
- DHTMLX Gantt 渲染
|
||
- 左侧：树形任务列表（阶段 → 任务 → 子任务）
|
||
- 右侧：时间轴条形图
|
||
- 任务间依赖箭头连线
|
||
- 拖拽调整开始/结束日期，拖拽完自动调用 ganttUpdate
|
||
- 双击任务 → 打开 task-drawer
|
||
|
||
**日历（calendar.vue）：**
|
||
- FullCalendar 月/周切换
|
||
- 任务按日期范围显示为色块
|
||
- 点击日期 → 快速创建任务
|
||
- 点击任务 → 打开 task-drawer
|
||
|
||
**表格列表（table.vue）：**
|
||
- cl-crud 标准表格
|
||
- 筛选：状态、优先级、分类、负责人、阶段
|
||
- 排序：优先级、日期、进度
|
||
- 支持批量操作（删除、修改状态）
|
||
|
||
**看板（kanban.vue）：**
|
||
- 四列：待办 | 进行中 | 已完成 | 已关闭
|
||
- 任务卡片：名称、优先级标签、负责人、截止日期
|
||
- vuedraggable 拖拽跨列 → 自动更新状态
|
||
- 卡片点击 → 打开 task-drawer
|
||
|
||
### 5.3 任务详情抽屉（task-drawer.vue）
|
||
|
||
右侧滑出抽屉，包含：
|
||
- 基本信息：名称、描述（纯文本 textarea）、状态、优先级、分类
|
||
- 时间：开始/结束日期选择器、预估工时输入
|
||
- 负责人：下拉选择系统用户
|
||
- 子任务列表：展示+快速添加
|
||
- 依赖关系：前置任务选择器（下拉搜索）
|
||
- 工时记录 Tab：工时列表 + 添加工时按钮
|
||
|
||
### 5.4 数据同步策略
|
||
|
||
- 项目详情页用 Pinia store 统一管理当前项目的任务/阶段/依赖数据
|
||
- 进入详情页时一次性加载（ganttData 接口）
|
||
- 切换 Tab 不重新请求，共享同一份 store 数据
|
||
- 任何视图中的修改（拖拽、状态变更、新增/删除）同时更新 store + 调用 API
|
||
|
||
## 6. 进度自动计算规则
|
||
|
||
- **子任务** → 手动更新进度，或按工时比例（actualHours / estimatedHours * 100）
|
||
- **任务进度** = 子任务进度加权平均（权重为 estimatedHours，无预估则等权）
|
||
- **阶段进度** = 下属任务进度加权平均
|
||
- **项目进度** = 各阶段进度加权平均
|
||
- 进度计算在后端 service 层实现，每次任务更新时触发向上汇总
|
||
|
||
## 7. 权限控制
|
||
|
||
- 复用现有 RBAC 体系
|
||
- 在菜单管理中添加「项目管理」菜单节点（目录 + 两个菜单页）
|
||
- 权限点：
|
||
- `project:info:add/update/delete` — 项目增删改
|
||
- `project:task:add/update/delete` — 任务增删改
|
||
- `project:timeLog:add/delete` — 工时记录增删
|
||
- 仅管理员/项目经理角色可见
|
||
|
||
## 8. 系统参数配置
|
||
|
||
需在「系统管理 → 参数配置」中预置：
|
||
|
||
| 参数键 | 说明 | 默认值示例 |
|
||
|--------|------|-----------|
|
||
| `project_task_category` | 任务分类选项 | 前端,后端,AI,设计,运营,法务,市场 |
|
||
| `project_task_priority` | 优先级选项（可选，也可硬编码） | P0紧急,P1高,P2中,P3低 |
|
||
|
||
## 9. 明确不做的事
|
||
|
||
- 通知/提醒系统
|
||
- 文件附件上传
|
||
- 评论/讨论功能
|
||
- 自动排期算法（关键路径法）
|
||
- 多项目资源冲突检测
|
||
- 移动端适配
|
||
- 成员自助端（仅管理员使用）
|