# project_quadrant_tracker

**Repository Path**: alexjunqi/project_quadrant_tracker

## Basic Information

- **Project Name**: project_quadrant_tracker
- **Description**: 基于erpnext的任务扩展
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: 16.01.01
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 18
- **Created**: 2025-11-20
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目进度跟踪（Project Quadrant Tracker）

基于 Frappe v16 / ERPNext 的研发任务管理应用：以**艾森豪威尔矩阵（重要/紧急四象限）**为核心，覆盖个人工作台、人员看板、部门/事业处多级仪表板、Sprint 与看板，并内置一套**组织分级权限体系**。

同时承担 Drive / Gameplan / Wiki 三个第三方应用的中文汉化维护。

---

## 核心功能

### 个人工作台（四象限）
- Q1–Q4 四象限视图，跨象限拖拽即改优先级；列表、看板视图无缝切换
- 看得见的任务人人可操作（拖拽、改状态、点完成、评论）；按任务相关人实时推送协同刷新（无全站广播）
- 任务认领池（行锁防并发重复认领）、快捷新建（2x2 图形化象限选择器）、任务评论（富文本）

### 多人协作
- shared 模式多人任务：全部协作人完成才闭环；第一人为主负责人
- 卡片头部头像重叠栈（最多 3 人 +N，已完成绿勾）、展开区协作人员栏、Task 表单多人协作标签栏
- 人员界面任务明细只显示进行中/逾期/本周完成；本周完成清单按 ToDo 口径显示"张三 等N人"

### 人员看板（管理指挥中心）
- KPI 数字卡（与账号组织权限范围严格联动，员工只见本课室）、按部门树逐层钻取（研发中心 → 事业处 → 部门 → 课室）、成员负荷排序预警
- 人员卡片默认前 5 名、点击展开全部；部门卡片按名称排序
- 一键导出研发周报（PDF/Excel/CSV），与看板同一统计口径

### 多级仪表板
- 部门仪表板 / 事业处仪表板（视觉统一 Bento 风格）/ 项目大厅（卡片流 + 搜索过滤）/ 项目详情页（Hero 横幅 + 环形进度，概览/任务/知识/会议）
- Sprint 管理（燃尽图、速率、Backlog）与甘特图（圆角状态配色 + 毛玻璃详情抽屉）

### 组织分级权限体系
- **五级可见范围**：员工看本科室；课室主管看本部门；部门主管看事业处；事业处主管看研发中心；研发中心主管全部
- **三档操作**：查看（可见范围）/ 管理（本辖区）/ 协作指派（可见范围内任何人，自动写审计日志）
- **逐人跨部门授权**：权限管理页（`/app/scope_manager`）可对任意人员授予指定部门的查看/管理权限，实时预览生效范围
- **一站式新建成员**：权限管理页单弹窗一次完成 User 账号 + HR 员工档案 + 层级角色/管辖覆盖/额外授权（同一请求事务）
- 行级过滤注册在 Task/Project 上（`permission_query_conditions` + `has_permission` 成对、fail-closed），Desk 与 API 同口径

### 协作与集成
- Gameplan 讨论、Wiki 知识页、Drive 文件夹与任务互相关联（外链新标签页打开）；知识地图沉淀到 Wiki
- 缺陷（Issue）跟踪与任务互链；任务日历同步
- 自动化：每日逾期检查/提醒（24 小时频控防重复）、每小时依赖检查（scheduler_events）
- 审计日志（PQT Audit Log）：权限变更、协作指派、新建成员等敏感操作全量可追溯
- 「项目进度跟踪」侧边栏锁定：从看板打开 Task/Project 表单不再跳转 ERPNext 原生侧边栏

## 目录结构

```
project_quadrant_tracker/
├── api/                    # 服务端 API（tasks/org/sprint/kanban/workflow/dashboard_report/
│                           #  scope_manager/performance_permission/defect/integration 等）
├── automation/             # 定时任务（每日逾期、每小时依赖检查）
├── events/                 # Task/Project 文档事件（象限重算、实时推送）
├── overrides/              # 第三方 app 端点覆盖（wiki 翻译回退）
├── utils/                  # 权限 scope（permissions.py）、统计口径、通知、同步工具
├── permissions.py          # Task/Project 等行级过滤与文档级钩子
├── queries.py              # Link 字段自定义查询
├── setup.py                # 安装/迁移钩子：角色、自定义字段、索引、工作区同步
├── fixtures/               # Custom Field / Client Script（按模块圈定导出）
├── quadrant_tracker/
│   ├── doctype/            # Sprint、Task Comment、Task Dependency、Task Time Log、
│   │                       # Task Quadrant Position、User Org Grant、PQT Audit Log、
│   │                       # Task Collaborating Department、Project Meeting、Knowledge Map 等
│   ├── page/               # Desk 页面：个人工作台、人员看板、权限管理、部门/事业处仪表板、
│   │                       # 项目详情、甘特图、认领/新建任务等 11 个
│   └── workspace/          # 工作区定义
├── frontend/               # Vue 3 SPA 源码（vite 构建 → public/js/quadrant_tracker_vue.bundle.js）
├── scripts/                # 工程脚本（run_pqt_tests.py 测试入口）
├── package.json            # 一键脚本：build:vue / build:desk / build:all / test:all
├── AGENTS.md               # 构建管线与关键口径约定
└── tests/                  # 行为级测试（安全/组织权限/看板/权限管理/多人协作等，62 例）
```

## 安装与升级

```bash
cd ~/frappe-bench
bench get-app https://gitee.com/alexjunqi/project_quadrant_tracker.git
bench --site [站点名称] install-app project_quadrant_tracker
bench build --app project_quadrant_tracker
bench restart
```

可选依赖（V2.0 集成功能需要，未安装时对应功能自动不可用）：

```bash
bench get-app https://gitee.com/alexjunqi/gameplan.git
bench get-app https://gitee.com/alexjunqi/wiki.git
bench get-app https://gitee.com/alexjunqi/drive.git
bench --site [站点名称] install-app gameplan wiki drive
```

升级：

```bash
bench update --pull --apps project_quadrant_tracker
bench --site [站点名称] migrate
bench restart
```

> 注意：gunicorn 预加载模式下，更新代码后必须重启 web/worker 进程
>（supervisor 部署：`supervisorctl restart 'frappe-bench-web:*' 'frappe-bench-workers:*'`）。

## 权限模型速查

| 角色 | 可见范围 | 管理范围 | 导出周报 |
|---|---|---|---|
| RD Center Manager（研发中心主管） | 全部 | 全部 | ✅ |
| Division Manager（事业处主管） | 研发中心 | 本事业处子树 | ✅ |
| Department Manager（部门主管） | 本事业处 | 本部门子树 | ✅ |
| Section Manager（课室主管） | 本部门 | 本科室 | ✅ |
| 员工 | 本科室 | 本人任务 | ❌ |

- 层级由 `Employee.department` 在组织树中的位置自动决定，角色只标记"是否主管"；人员调动只改部门即可
- `Employee.pq_scope_override` 可对组织归属做显式纠偏
- 逐人额外授权通过 `/app/scope_manager` 页面或 User Org Grant 记录管理（白名单模型）

## 第三方应用汉化

通过 `translations/zh.csv` 与覆盖端点统一维护 Drive / Gameplan / Wiki 的中文翻译：侧边栏导航、页面标题、按钮、筛选项、空状态、表单占位符等。

## 开发与测试

本 app 有两条独立的前端构建链（详见 [AGENTS.md](./AGENTS.md)）：

```bash
cd apps/project_quadrant_tracker

yarn build:vue    # Vue 看板（frontend/src → vite）
yarn build:desk   # Desk 页面与 bundle CSS（bench build，在 bench 根目录执行）
yarn build:all    # 全部构建
yarn test:all     # 运行测试（scripts/run_pqt_tests.py）
```

> 注意：`bench build` 不会重建 Vue bundle；`bench run-tests --app` 在本地化部署
> （根部门非 "All Departments"）下会因 ERPNext 测试记录预加载失败而无法启动，
> 请统一使用 `yarn test:all`。

## 版本历史

见 [CHANGELOG.md](./CHANGELOG.md)。

## 许可证

MIT License