# 项目管理模块设计文档

> 日期: 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. 明确不做的事

- 通知/提醒系统
- 文件附件上传
- 评论/讨论功能
- 自动排期算法（关键路径法）
- 多项目资源冲突检测
- 移动端适配
- 成员自助端（仅管理员使用）