# Efficiency

**Repository Path**: king_nd/efficiency

## Basic Information

- **Project Name**: Efficiency
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YJHH GitLab 研发效能大屏与 AI 代码审查系统

本系统是一套为企业（YJHH）量身定制的 GitLab 研发效能分析与代码质量管控工具。系统深度集成了 **实时 AI 代码审查 (Code Review)** 功能、**全员研发效能日历大屏** 以及 **自动化钉钉周报推送**，支持根据文件类型智能分发专属审查规则。

---

## 🏗️ 核心架构与工作模式

本系统采用 **“双轨制”** 运行模式：
1. **实时全量采集 (基于 System Hook)**：通过 GitLab 全局 System Hook 实时拦截所有项目的 `Push` 事件，毫秒级将代码产出存入本地数据库，供“研发效能日历矩阵”展示。
2. **按需 AI 审查 (降本增效)**：拦截到提交后，系统会自动判断该项目是否在白名单（`config/groups_config.json`）中。只有核心项目才会触发大模型（如 Qwen-coder-plus）进行深度的代码审查，并在界面上生成打分和优化建议。

---

## 📂 项目目录结构与模块说明

```text
d:\AI\gitlab代码统计\
├── config/                     # 核心配置目录
│   ├── config.json             # 全局系统配置 (大模型密钥、GitLab Token、钉钉 Webhook 等)
│   ├── developers.json         # 真实研发人员花名册 (用于日历大屏的左侧人员名单固定展示)
│   ├── groups_config.json      # 核心监控群组配置 (配置在这里的项目才会被触发 AI 审查)
│   ├── author_alias_map.json   # 开发者 GitLab 账号到真实姓名的映射字典
│   ├── prompt_templates.yml    # AI 审查规则中心 (定义各语言的专项 Prompt 及防内卷指令)
│   └── weekly_report_prompt.yml# 每周智能研发效能周报的生成分析规则
├── templates/                  # 大屏 Web 模板 (前端界面)
│   ├── portal.html             # 门户首页导航 (入口)
│   ├── index.html              # 项目视角效能看板 (图表、排行榜、实时审查日志)
│   ├── user.html               # 个人视角效能看板
│   ├── calendar.html           # 研发效能日历大屏矩阵 (全员每日产出与打分热力图)
│   └── report.html             # 历史效能周报归档查阅页面
├── reports/                    # (自动生成) 存放每天生成的 Markdown 格式历史日报
├── scripts/                    # 各种自动化脚本和工具目录
│   ├── sync_task.py            # 【核心兜底脚本】全量/增量同步脚本（仅在服务器宕机或更换服务器时使用，自带自愈纠错功能）
│   ├── weekly_report.py        # 钉钉周报生成与推送脚本 (每周一自动汇总数据并推送到群)
│   ├── db_init.py              # 数据库表结构初始化工具
│   ├── cleanup_db.py           # 数据库瘦身清理脚本 (清理超过3个月的超长审查文本)
│   ├── update_and_restart.sh   # 一键拉取代码、更新依赖并重启后台服务的运维脚本
│   └── fix_zombie_reviews.py   # 僵尸审查记录清理脚本 (修复因重启导致一直卡在“审查中”的数据)
├── manage.sh                   # 一键管理服务的控制台脚本 (支持 start/stop/restart/status)
├── app.py                      # Flask Web 服务主入口 (提供 API 接口、路由渲染、前端数据支撑)
├── reviewer.py                 # AI 实时代码审查核心引擎 (接收 Webhook，排队处理大模型请求)
├── API_DOCS.md                 # 接口文档说明
├── PRD_Architecture.md         # 产品需求与架构设计文档
└── gitlab_stats.db             # 本地 SQLite 数据库文件
```

---

## 🚀 生产环境部署指南 (Linux/CentOS)

### 1. 环境准备
确保服务器已安装 Python 3.8+ 环境，并安装必要的依赖：
```bash
pip install flask python-gitlab requests pyyaml jinja2
```

### 2. 基础配置
1. 复制或创建 `config/config.json`，配置你的 `private_token`、`api_key` 和相关地址。
2. 编辑 `config/groups_config.json`，填入你需要**开启 AI 代码审查**的核心 GitLab 群组 ID。
3. 编辑 `config/developers.json`，维护你们真实的研发人员名单（这决定了日历大屏上显示哪些人）。

### 3. 初始化数据库（全新部署）
如果是第一次在一台新机器上运行系统，需要初始化 SQLite 数据库：
```bash
python scripts/db_init.py
```
*(注：如果你是从本地 Windows 迁移过来的，直接将本地的 `gitlab_stats.db` 连同代码一起打包传到服务器即可，跳过此步骤。)*

### 4. 启动后端 Web 服务 (守护进程模式)
在生产环境中，推荐使用 `nohup` 或 `systemd` (Supervisor) 来后台运行 Flask 服务，这里以 nohup 为例：
```bash
# 启动 app.py (前端界面与 API 提供)
nohup python app.py > web_app.log 2>&1 &

# 启动 reviewer.py (Webhook 监听与 AI 审查工作队列)
nohup python reviewer.py > reviewer.log 2>&1 &
```
*启动后，通过 `http://服务器IP:5000` 即可访问门户首页。*

### 5. 在 GitLab 配置 System Hook (核心步骤)
为了实现全公司的代码产出实时统计：
1. 登录 GitLab 管理员账号。
2. 进入 `Admin Area` (管理中心) -> `System Hooks` (系统钩子)。
3. 在 URL 处填写：`http://你的服务器IP:5000/webhook/gitlab`。
4. 勾选 `Push events` 和 `Merge request events`。
5. 取消勾选 `Enable SSL verification`（如果是内网 HTTP 环境）。
6. 点击 `Add system hook` 保存。

### 6. 配置自动化定时任务 (Crontab)
使用 `crontab -e` 编辑服务器的定时任务，添加以下自动化脚本：

```bash
# 1. 每周一上午 09:30，自动发送上周的研发效能周报到钉钉群
30 9 * * 1 cd /path/to/gitlab代码统计 && /usr/bin/python3 scripts/weekly_report.py >> logs/weekly_report.log 2>&1

# 2. (可选/兜底方案) 每天凌晨 02:00，运行极速同步脚本，兜底昨天未被 Webhook 成功捕获的提交事件
0 2 * * * cd /path/to/gitlab代码统计 && /usr/bin/python3 scripts/sync_daily_events.py >> logs/sync.log 2>&1

# 3. (可选/维护方案) 每天凌晨 03:00，清理因服务重启导致的“僵尸”审查状态
0 3 * * * cd /path/to/gitlab代码统计 && /usr/bin/python3 scripts/fix_zombie_reviews.py >> logs/zombie.log 2>&1

# 4. 每个月 1 号凌晨 04:00 自动清理过期(超过 3 个月)的 AI 审查数据，释放数据库空间
0 4 1 * * cd /path/to/gitlab代码统计 && /usr/bin/python3 scripts/cleanup_db.py >> logs/cleanup.log 2>&1
```

### 7. 后期代码更新与维护 (升级脚本)
为方便生产环境一键升级与重启，系统提供了一个维护脚本：
```bash
# 给予执行权限
chmod +x scripts/update_and_restart.sh

# 每次修改了代码或者拉取了新代码，直接运行该脚本即可完成重启
./scripts/update_and_restart.sh
```

---

## 🛠️ 日常运维与故障排查

### 1. 怎么补齐历史数据？
如果你是第一次部署，想要大屏上显示过去几个月的数据：
*   修改 `scripts/sync_daily_events.py` 中的 `after_date`（如改为 `2026-01-01`）。
*   手动运行一次：`python scripts/sync_daily_events.py`。几分钟后，历史代码量就会全部入库。

### 2. 界面上的人名对不上怎么办？
如果在 GitLab 上有人用拼音提交，导致大屏上出现了英文名，可以编辑 `config/author_alias_map.json` 字典文件，添加映射关系（如 `"liuyuanfang": "刘元芳"`）。修改后，无需重启 `app.py` 即可立即生效。

### 3. AI 审查一直卡在“审查中”？
这通常是因为在 AI 正在调用大模型时，你重启了 `reviewer.py` 服务。
**解决办法**：直接运行 `python scripts/fix_zombie_reviews.py`，它会把超时 1 小时的任务强制标记为“失败”，然后你可以在网页上点击“重试”按钮重新审查。

### 4. 数据库并发写入报错 (database is locked)
系统已在 `reviewer.py` 中实现了基于 SQLite WAL 模式的退让重试机制，可完美抗住日常的并发 Push。如果仍有极小概率报错，系统会自动跳过，凌晨的 `sync_daily_events.py` 定时任务会自动把漏掉的代码量补齐。