# openokr

**Repository Path**: goti/openokr

## Basic Information

- **Project Name**: openokr
- **Description**: OpenOKR是一个基于Python Flask构建的企业级OKR（Objectives and Key Results）管理系统，集成了AI智能查询功能，帮助企业实现目标对齐、进度跟踪和智能分析。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-30
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenOKR - 企业级目标与关键成果管理系统

## 系统概述

OpenOKR是一个基于Python Flask构建的企业级OKR（Objectives and Key Results）管理系统，集成了AI智能查询功能，帮助企业实现目标对齐、进度跟踪和智能分析。

## 核心功能

### 1. 目标管理
- ✅ 多层级目标体系（公司级、部门级、个人级）
- ✅ 目标类型分类（经营、战略、研发）
- ✅ 目标自动同步到下属
- ✅ 关键成果(KR)跟踪与进度计算

### 2. 项目管理
- ✅ 项目创建与进度跟踪
- ✅ 项目与目标关联映射
- ✅ 项目资源分配可视化

### 3. 人员状态管理
- ✅ 工作状态实时更新（在岗/远程/请假/外出）
- ✅ 位置信息记录
- ✅ 当前任务跟踪

### 4. 智能查询系统
- ✅ 基于DeepSeek-V3的自然语言查询
- ✅ 项目情况智能分析
- ✅ 团队状态智能总结
- ✅ 目标进度AI评估

### 5. 角色权限管理
- **管理员**: 全系统管理、用户管理、数据库操作
- **主管**: 查看团队进度、分配目标、AI查询
- **员工**: 管理个人OKR、更新状态、创建项目

## 技术架构

### 后端技术栈
- **框架**: Flask 3.0
- **数据库**: SQLAlchemy + SQLite
- **认证**: Flask-Login
- **AI服务**: DeepSeek-V3 API

### 前端技术栈
- **基础**: HTML5 + CSS3 + JavaScript
- **设计**: 响应式布局（支持移动端）
- **交互**: 原生JavaScript（无框架依赖）

### 项目结构
```
OpenOKR/
├── app/
│   ├── __init__.py           # 应用初始化
│   ├── models/               # 数据模型
│   │   ├── user.py          # 用户模型
│   │   ├── objective.py     # 目标模型
│   │   ├── project.py       # 项目模型
│   │   └── status.py        # 状态模型
│   ├── routes/              # 路由处理
│   │   ├── auth.py          # 认证路由
│   │   ├── objectives.py    # 目标API
│   │   ├── projects.py      # 项目API
│   │   ├── status.py        # 状态API
│   │   ├── query.py         # AI查询API
│   │   └── admin.py         # 管理员API
│   ├── services/            # 业务服务
│   │   └── ai_service.py    # AI服务
│   ├── utils/               # 工具函数
│   │   └── decorators.py    # 权限装饰器
│   ├── templates/           # HTML模板
│   │   ├── login.html
│   │   ├── employee_dashboard.html
│   │   ├── manager_dashboard.html
│   │   └── admin_dashboard.html
│   └── static/              # 静态资源
│       ├── css/
│       │   └── style.css
│       └── js/
│           └── common.js
├── database/
│   └── schema.sql           # 数据库schema
├── config.py                # 配置文件
├── run.py                   # 启动文件
├── requirements.txt         # 依赖清单
└── README.md               # 项目文档
```

## 快速开始

### 1. 环境要求
- Python 3.8+
- DeepSeek API密钥 (用于AI功能)

### 2. 安装依赖
```bash
pip install -r requirements.txt
```

### 3. 配置环境变量
复制 `.env.example` 为 `.env` 并修改配置:
```bash
cp .env.example .env
```

编辑 `.env` 文件:
```
FLASK_APP=run.py
FLASK_ENV=development
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///okr.db
DEEPSEEK_API_URL=你的服务URL
DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_MODEL=你的大模型
```

**重要提示**:
- `DEEPSEEK_API_KEY` 已配置为可用的API密钥
- 如需使用自己的API密钥,请修改此值
- AI功能依赖此配置,请确保密钥有效

### 4. 运行应用
```bash
python run.py
```

应用将在 `http://localhost:5000` 启动

### 5. 初始化数据
首次使用需要创建管理员账户:

**方法一: 通过注册API**
```bash
curl -X POST http://localhost:5000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password123",
    "email": "admin@company.com",
    "full_name": "系统管理员",
    "role": "admin"
  }'
```

**方法二: 使用Python交互式创建**
```python
from app import create_app, db
from app.models.user import User

app = create_app()
with app.app_context():
    admin = User(
        username='admin',
        email='admin@company.com',
        full_name='系统管理员',
        role='admin'
    )
    admin.set_password('password123')
    db.session.add(admin)
    db.session.commit()
    print("管理员账户创建成功!")
```

### 6. 登录系统
访问 `http://localhost:5000/auth/login` 使用以下凭据登录:
- 用户名: `admin`
- 密码: `password123`

## API文档

### 认证接口
- `POST /auth/login` - 用户登录
- `POST /auth/logout` - 用户登出
- `POST /auth/register` - 用户注册
- `GET /auth/me` - 获取当前用户信息

### 目标管理接口
- `GET /api/objectives` - 获取目标列表
- `POST /api/objectives` - 创建目标
- `GET /api/objectives/<id>` - 获取目标详情
- `PUT /api/objectives/<id>` - 更新目标
- `DELETE /api/objectives/<id>` - 删除目标
- `POST /api/objectives/sync` - 同步目标到下属
- `POST /api/objectives/<id>/key_results` - 添加关键成果
- `PUT /api/objectives/key_results/<id>` - 更新关键成果

### 项目管理接口
- `GET /api/projects` - 获取项目列表
- `POST /api/projects` - 创建项目
- `GET /api/projects/<id>` - 获取项目详情
- `PUT /api/projects/<id>` - 更新项目
- `DELETE /api/projects/<id>` - 删除项目
- `POST /api/projects/link` - 关联项目到目标

### 状态管理接口
- `POST /api/status` - 更新工作状态
- `GET /api/status/me` - 获取我的状态历史
- `GET /api/status/me/latest` - 获取最新状态
- `GET /api/status/team` - 获取团队状态(主管权限)

### AI查询接口
- `POST /api/query` - 自然语言查询
- `POST /api/query/analyze-progress` - 分析目标进度
- `GET /api/query/team-summary` - 团队状态总结

### 管理员接口
- `GET /api/admin/users` - 获取所有用户
- `GET /api/admin/users/<id>` - 获取用户详情
- `PUT /api/admin/users/<id>` - 更新用户
- `DELETE /api/admin/users/<id>` - 删除用户
- `GET /api/admin/stats` - 获取系统统计
- `POST /api/admin/init-db` - 初始化示例数据

## 使用说明

### 员工操作流程
1. 登录系统
2. 更新工作状态(在岗/远程/请假/外出)
3. 创建个人目标和关键成果
4. 创建项目并关联到目标
5. 定期更新关键成果进度

### 主管操作流程
1. 登录系统
2. 查看团队成员实时状态
3. 创建部门级目标
4. 将目标同步到下属
5. 使用AI查询分析团队进度
6. 查看下属详细信息和工作状态

### 管理员操作流程
1. 登录系统
2. 管理用户账户(创建/编辑/删除)
3. 查看系统统计数据
4. 初始化示例数据
5. 配置系统参数

## AI功能使用说明

### 智能查询示例
- "团队目标完成情况如何?"
- "谁今天在远程工作?"
- "本季度的研发目标进度怎么样?"
- "哪些项目进度滞后?"

### 进度分析
在主管仪表板中使用"分析进度"功能,AI将:
1. 评估整体进度
2. 识别滞后的目标
3. 提供改进建议
4. 给出风险提示

### 团队总结
AI可以自动总结:
1. 团队整体状态
2. 在岗人员统计
3. 主要任务分布
4. 需要关注的事项

## 开发与扩展

### 添加新的API端点
在 `app/routes/` 目录下创建新的蓝图:
```python
from flask import Blueprint, request, jsonify
from flask_login import login_required

bp = Blueprint('custom', __name__, url_prefix='/api/custom')

@bp.route('/endpoint', methods=['GET'])
@login_required
def custom_endpoint():
    return jsonify({'message': 'Custom endpoint'}), 200
```

在 `app/__init__.py` 中注册蓝图:
```python
from app.routes import custom
app.register_blueprint(custom.bp)
```

### 自定义数据模型
在 `app/models/` 目录下创建新的模型文件。

### 前端定制
- 修改 `app/static/css/style.css` 自定义样式
- 编辑 `app/templates/` 下的HTML文件调整布局
- 扩展 `app/static/js/common.js` 添加新的JavaScript功能

## 故障排查

### 问题: 无法启动应用
**解决方案**:
1. 检查Python版本: `python --version`
2. 确认依赖安装: `pip install -r requirements.txt`
3. 检查端口占用: `netstat -ano | findstr :5000`

### 问题: AI查询不工作
**解决方案**:
1. 检查API密钥配置: 确认 `.env` 文件中 `DEEPSEEK_API_KEY` 已正确设置
2. 验证API地址: 确认 `DEEPSEEK_API_URL` 可访问
3. 测试API连接: 可以使用curl测试:
   ```bash
   curl -X POST $你的服务器URL/v1/chat/completions \
     -H "Authorization: Bearer $你的密钥" \
     -H "Content-Type: application/json" \
     -d '{"model":"$你的大模型","messages":[{"role":"user","content":"你好"}]}'
   ```
4. 查看应用日志获取详细错误信息

### 问题: 数据库错误
**解决方案**:
1. 删除现有数据库: `del okr.db` (Windows) 或 `rm okr.db` (Linux/Mac)
2. 重新启动应用,数据库将自动创建

## 安全建议

1. **生产环境配置**:
   - 修改 `SECRET_KEY` 为强随机字符串
   - 使用 PostgreSQL 或 MySQL 替代 SQLite
   - 启用HTTPS

2. **密码策略**:
   - 实施强密码要求
   - 定期更换密码
   - 启用双因素认证(需要扩展)

3. **访问控制**:
   - 定期审查用户权限
   - 限制管理员账户数量
   - 记录关键操作日志

## 许可证

MIT License

## 技术支持

如有问题或建议,请联系系统管理员或提交Issue。

---

**版本**: 1.0.0
**最后更新**: 2025-09-30