Developer Burnout Risk Management

一个面向团队管理者的开发者倦怠风险管理 Web MVP。项目从 Kaggle 开发者倦怠数据集出发，把数据分析与建模、后端评估链路、Agent 问答与解释、Web 演示界面串成一个可复现的项目。

项目问题

开发者长期高压、加班、睡眠不足和恢复不足可能带来倦怠甚至健康风险，但团队管理者往往缺少一个基于数据的早期识别和干预工具。

核心价值

• 早发现：帮助管理者提前识别开发者倦怠和健康风险。
• 可解释：用数据说明风险来自工时、睡眠、会议、屏幕时间或压力信号。
• 可干预：通过 Agent 给出重点成员、风险原因和行动建议，辅助更合理地安排团队工作。

MVP 范围

• 管理者登录
• 多管理者团队案例隔离
• 团队成员数据录入
• 模型驱动的倦怠风险评估
• 数据分析、模型和图表产物
• Agent 风险解释、连续问答、RAG 检索、会话记忆、案例总结和邮件提醒草稿/发送
• HTML Web 工作台展示

计划技术栈

• Frontend: HTML, CSS, JavaScript
• Backend: FastAPI
• Database: MVP local persistence, PostgreSQL-ready schema
• Analysis: Python
• Agent: LangGraph, LangChain tools, MiniMax, local RAG, SMTP
• Testing: TDD, Python tests, frontend tests, manual browser checks

项目文档

• AGENTS.md: 项目开发规则和完成标准
• CODEX.md: Codex 工作指令
• docs/idea.md: 项目 idea 和核心价值
• docs/spec.md: 功能需求、验收标准和边界条件
• docs/plan.md: 技术方案、角色分支和数据流
• docs/test.md: TDD 流程和测试标准
• docs/tasks.md: 分阶段任务清单

分支工作流

本项目用分支模拟团队协作：

• docs/sdd-tdd: Product Owner + Tech Lead
• docs/align-core-workflow: Product Owner
• feature/data-engineering: Data Engineer
• feature/backend-foundation: Backend Engineer
• feature/backend-model-integration: Backend Engineer
• feature/backend-agent-foundation: Backend Engineer
• feature/frontend-html-mvp: Frontend Engineer
• feature/agent-layer: Agent Engineer
• feature/frontend-agent-integration: Frontend Engineer
• test/acceptance-demo: QA Engineer

每个功能分支通过 Pull Request 合并回 main，并保留 merge commit，用于展示完整开发过程。部分前端工作从后端基础分支派生，因此合并时带入前后端主链路；后续分支继续按角色单目标推进。

当前主链路

登录 / 注册
-> 创建案例
-> 录入成员信息（含 email）
-> 保存并评估
-> 后端调用模型生成团队与成员风险结果
-> Agent 生成报告、解释、建议、问答和邮件草稿
-> 管理者确认后发送提醒邮件

Agent 架构

• LangChain: 定义标准工具结构和参数契约
• LangGraph: 组织多轮 ReAct tool loop 和会话状态
• MiniMax: 作为真实 LLM，负责理解问题、选择工具、读取工具结果并生成回答
• Local fallback: 无 API key、LLM 失败或工具失败时保证演示链路可用
• RAG: 当前基于本地知识片段检索
• SMTP: 管理者确认后，向最高风险成员邮箱发送提醒邮件

运行方式

1. 安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

在项目根目录创建 .env。这里主要放系统级能力开关和 LLM 连接参数。

BURNOUT_MINIMAX_API_KEY=
BURNOUT_MINIMAX_BASE_URL=https://api.minimaxi.com/v1
BURNOUT_MINIMAX_MODEL=MiniMax-M3

BURNOUT_EMAIL_SEND_ENABLED=false

说明：

• MiniMax 通过 OpenAI-compatible Chat Completions 协议接入
• 后端按 messages + tools + tool_choice 的 tool-calling 方式调用 MiniMax
• BURNOUT_MINIMAX_BASE_URL 默认使用 https://api.minimaxi.com/v1
• 无有效 MiniMax API key 时，Agent 自动退回本地 fallback 流程
• BURNOUT_EMAIL_SEND_ENABLED 用于控制系统是否允许真实发送邮件

3. 页面内邮件设置

SMTP 发送参数不要求预先写死在 .env。当前产品流程支持管理者在报告页邮件区域填写和保存发送配置。

管理者可在页面中填写：

• SMTP host
• SMTP port
• SMTP username
• SMTP password / 授权码
• from address

说明：

• 页面内 SMTP 设置用于当前管理者的真实发信配置
• 未完成 SMTP 设置时，系统仍可生成邮件草稿，但不能真实发送
• 邮件仍然默认发给当前案例中的最高风险成员邮箱
• 发信动作必须由管理者确认，不会在评估后自动发送

4. 启动后端 API

前端脚本默认请求 http://127.0.0.1:8010，因此本地演示时后端建议固定使用 8010 端口。

.venv/bin/python -m uvicorn backend.main:app --reload --port 8010

后端启动后可以先检查：

• 健康检查：http://127.0.0.1:8010/health
• Swagger 调试页：http://127.0.0.1:8010/docs

5. 启动前端页面服务

当前 HTML 前端放在 web/ 目录下，由浏览器静态访问；FastAPI 后端目前不直接托管 /login、/dashboard、/evaluate 和 /report 页面。因此需要另开一个终端，在项目根目录启动静态文件服务：

python3 -m http.server 8020 --directory web

6. 打开前端页面

• 登录页：http://127.0.0.1:8020/login.html
• 工作台：http://127.0.0.1:8020/dashboard.html
• 团队评估页：http://127.0.0.1:8020/evaluate.html?caseId=<case_id>
• 报告页：http://127.0.0.1:8020/report.html?caseId=<case_id>

完整本地运行时需要同时保留两个服务：

• 后端 API：http://127.0.0.1:8010
• 前端页面：http://127.0.0.1:8020

测试命令

.venv/bin/python -m pytest -p no:cacheprovider tests/backend
.venv/bin/python -m pytest -p no:cacheprovider tests/frontend
node --check web/assets/app.js

Demo 路径

1. 注册或登录管理者账号
2. 创建案例
3. 录入成员数据并完成评估
4. 展示团队风险、成员风险、重点成员和解释
5. 在报告页追问原因、建议和沟通方式
6. 生成邮件草稿并演示确认发送