# 狂盗项目管理系统 - 企业级综合管理平台

## 项目概述
[系统架构图](docs/architecture.png) *建议添加系统架构图*

基于Flask的企业级项目管理系统，提供以下核心能力：
- ✅ 一体化管理：人员、考勤、任务、审批全流程
- 🔒 多级权限：基于角色的精细化访问控制
- 🔗 深度集成：JIRA、企业微信、考勤设备无缝对接

## 核心功能亮点

### 管理员后台系统
![管理员界面](docs/admin-panel.png) 

![企业微信](docs/wxwork.png)

![项目管理](docs/jira.png)

![中控考勤](docs/zktime.png)

- **安全认证**：
  - 🔐 多因素认证（账号密码+企业微信扫码）
  - ⚠️ 登录失败锁定（5次失败后锁定30分钟）
  - ⏳ 密码策略（90天强制更换+复杂度检查）

- **组织管理**：
  - 部门树形结构维护
  - 细粒度权限分配（基于RBAC模型）

- **系统配置**：
  - 企业微信集成（CorpID/Secret配置）
  - 考勤设备管理（IP/端口/密钥配置）

- **审计追踪**：
  - 操作日志记录（保留180天）
  - 数据变更历史追溯

### JIRA集成模块
- **任务管理**：创建、分配、跟踪任务
- **审批流程**：自定义审批工作流
- **数据同步**：与JIRA系统双向同步

### 企业微信集成
- **组织架构同步**：自动同步部门和成员信息
- **消息通知**：任务提醒、审批通知
- **扫码登录**：支持企业微信扫码登录系统

### 考勤系统
- **设备管理**：考勤机配置与状态监控
- **记录同步**：自动同步考勤数据
- **统计分析**：考勤报表生成

### 资产管理
- **资产管理**：资产管理，添加，分配，维护
- **自动上报**：自动上报资产信息
- **资产代理**：https://gitee.com/thomasblog/kdasset_agent

### 成员门户
- **个人中心**：资料维护、密码修改
- **任务看板**：个人任务管理
- **审批流程**：发起和审批各类申请

## 技术架构

### 后端技术栈
```mermaid
graph TD
    A[Flask] --> B[业务逻辑]
    A --> C[API端点]
    B --> D[SQLAlchemy]
    D --> E[(数据库)]
    A --> F[APScheduler]
    F --> G[定时任务]
```

- **核心框架**：Flask 3.1.1（RESTful API支持）
- **数据层**：SQLAlchemy 2.0（支持MySQL/PostgreSQL/SQLite）
- **异步任务**：APScheduler 3.11（定时任务管理）
- **安全认证**：
  - Flask-Login（会话管理）
  - Flask-WTF（表单验证）
  - JWT支持（API认证）

### 前端技术
- **模板引擎**：Jinja2 3.1.6
- **样式**：CSS3
- **交互**：原生JavaScript

### 第三方集成
- **JIRA**：通过REST API集成
- **企业微信**：使用官方SDK
- **考勤设备**：中控考勤机SDK

## 部署指南

### 开发环境
#### 最低要求
- Python 3.9+ (推荐3.11)
- 数据库：
  - SQLite（开发测试）
  - MySQL 5.7+/PostgreSQL 13+（生产环境）
- 操作系统：Windows 10+/Linux/macOS

#### 推荐配置
- 内存：4GB+（生产环境8GB+）
- 存储：SSD硬盘（数据库性能优化）
- 网络：稳定连接（企业微信API依赖）

### 安装步骤
1. 克隆仓库：
```bash
git clone https://github.com/your-repo/project-management.git
cd project-management
```

2. 创建虚拟环境并安装依赖：
```bash
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
pip install -r requirements.txt
```

3. 数据库配置：
- 复制`.env.example`为`.env`
- 修改数据库连接配置：
```ini
DB_URI=sqlite:///database/data.db
```

4. 初始化数据库：
```bash
python app.py --init
```

5. 运行开发服务器：
```bash
python app.py
```

6. 访问应用：
- 管理员后台：http://localhost:5000/admin
- 成员门户：http://localhost:5000/member

## 项目结构
```
.
├── admin/            # 管理员后台模块
├── member/           # 成员管理模块
├── database/         # 数据库文件
├── templates/        # 前端模板
├── static/           # 静态资源
├── app.py            # 主应用入口
└── requirements.txt  # 依赖列表
```

## 依赖说明
主要依赖：
- Flask及相关扩展
- SQLAlchemy ORM
- 企业微信SDK
- 考勤设备SDK

完整依赖列表见requirements.txt

## 生产环境部署

### Docker部署
1. 构建Docker镜像：
```bash
docker build -t project-management .
```

2. 运行容器：
```bash
docker run -d \
  -p 5000:5000 \
  -v ./database:/app/database \
  -v ./logs:/app/logs \
  --name pm-app \
  project-management
```

3. 使用Nginx反向代理：
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 高可用部署建议
- 使用Redis缓存会话数据
- 配置数据库主从复制
- 设置负载均衡和多实例

## 模块配置说明

### JIRA模块配置
1. 在JIRA中创建API令牌
2. 修改`admin/jira/jira_route.py`中的配置：
```python
JIRA_CONFIG = {
    'server': 'https://your-jira.com',
    'api_key': 'your-api-token',
    'project_key': 'PM'
}
```

### 企业微信模块配置
1. 在企业微信管理后台获取CorpID和AgentID
2. 修改`admin/wxwork/wxwork_sync.py`中的配置：
```python
WECOM_CONFIG = {
    'corp_id': 'your-corp-id',
    'agent_id': 'your-agent-id',
    'secret': 'your-app-secret'
}
```

## 可视化内容建议
建议添加以下截图：
1. 系统架构图（可放在docs/architecture.png）
2. 管理员后台界面截图
3. 成员门户界面截图
4. 企业微信扫码登录流程截图

## 使用说明

### 管理员使用
1. 首次登录：
   - 默认管理员账号：admin
   - 默认密码：admin（首次登录后强制修改）
   - 密码要求：至少8位，包含大小写字母和数字

2. 系统配置：
   - 企业微信：配置CorpID和AgentID（需管理员权限）
   - JIRA集成：配置API密钥和项目映射
   - 考勤设备：添加设备IP和端口（支持批量导入）

3. 常见问题：
   - Q：企业微信扫码登录失败？
     A：检查CorpID和AgentID配置，确保网络可达
   - Q：考勤数据不同步？
     A：检查设备状态和网络连接，参考[设备排障指南](#)

### 成员使用
1. 登录方式：
   - 账号密码登录（支持密码找回）
   - 企业微信扫码登录（需先绑定账号）

2. 主要功能：
   - 任务管理：
     - 查看分配的任务
     - 更新任务进度
     - 提交任务成果
   - 审批流程：
     - 发起请假/报销等申请
     - 查看审批进度
   - 考勤记录：
     - 每日考勤打卡
     - 月度考勤统计
     - 异常考勤申诉

### API文档
各模块API文档可通过Swagger UI访问：
```bash
http://localhost:5000/api/docs
```

## 贡献指南
![开发流程](docs/dev-flow.png) *建议添加开发流程图*

### 代码规范
- 遵循PEP8规范（使用flake8检查）
- 类型注解：重要函数需添加类型提示
- 文档字符串：公共API必须包含docstring

### 测试要求
- 单元测试覆盖率不低于80%
- 新增功能必须包含测试用例
- 使用pytest框架编写测试

### 提交规范
1. 创建特性分支（feature/xxx）
2. 提交前运行测试：
```bash
pytest && flake8
```
3. 编写清晰的提交信息，格式：
```
类型(模块): 简短描述

详细说明（可选）
```
示例：
```
feat(auth): 添加企业微信扫码登录支持

- 实现扫码登录前端组件
- 添加后端认证逻辑
- 更新相关文档
```

### 代码审查
- 至少需要1位核心成员批准
- 审查重点：
  - 代码质量
  - 测试覆盖
  - 文档更新

## 许可证
MIT License

## 获取帮助
- 文档中心：[项目Wiki](#)
- 问题反馈：[GitHub Issues](#)
- 紧急支持：contact@example.com

## 版本历史
| 版本  | 日期         | 主要变更            |
|-----|------------|-----------------|
| 1.0 | 2025-08-15 | 初始发布            |
| 1.1 | 2025-08-20 | 添加企业微信集成        |
| 1.2 | 2025-10-20 | 支持JIRA工作流自定义    |
| 1.3 | 2025-10-27 | 考勤设备多机同步支持      |
| 1.4 | 2025-11-07 | 资产管理系统+支持自动收集上报 |