ad25343/waf-classifier

# WAF 类别分类器 一款基于人工智能的工具，用于将 JIRA 故事分类为您组织的“工作对齐框架”（WAF）类别。使用 Flask 和 Anthropic 的 Claude AI 构建。 ## 问题 Scrum 团队在将故事归类到 8 类 WAF 框架时持续出错。超过 80% 的故事缺少正确的 WAF 标签，导致投资组合级别的投资报告不可靠。此工具可解决该问题。 ## 功能 | 功能 | 描述 | |------|------| | **分类** | 在梳理期间对新故事进行实时聊天或批量分类 | | **分析** | 上传 JIRA 数据 → 映射列 → AI 检查每一行 → 标记不匹配 → 保存 → 生成摘要洞察 | | **团队** | 双面板团队分析：左侧树形导航（团队 › 史诗 › 功能）+ 右侧可排序的故事表格。跨团队史诗矩阵。每个上传可按数据源过滤。 | | **史诗谱系** | 健康度评分、不匹配标记、可折叠功能章节的故事树详情及排序控制 | | **全局搜索** | 基于 FTS5 的全文搜索，支持上下文丰富的结果（面包屑、徽章、上传来源） | | **WAF 参考** | 浏览全部 8 个 WAF 类别，包括定义、决策规则、颜色代码和示例 | | **设置** | 管理 WAF 定义、真实基线（查看/编辑/添加/删除）以及批量大小配置 | | **深色/浅色模式** | 导航栏中切换；偏好设置保存在 localStorage 中 | | **故事/功能/史诗 ID** | 可选的 ID 字段可从 CSV/Excel 导入，并在团队和谱系视图中显示 | | **真实基线闭环** | 批准正确的误分类以持续提升 AI 准确性 | ## WAF 类别 | 类型 | 颜色 | 类别 | |------|------|------| | 运行 | 灰色 | KTLO（保持基础运行） | | 运行 | 黑色 | 业务维护 | | 运行 | 黑色 | 技术维护 | | 运行 | 红色 | 监管（运营） | | 变更 | 红色 | 监管强制变更 | | 变更 | 橙色 | 企业战略优先级 | | 变更 | 黄色 | 部门级优先级 | | 变更 | 绿色 | 其他阻塞优先级 | ## 快速开始 ``` # 克隆仓库 git clone https://github.com/ad25343/waf-classifier.git cd waf-classifier # 安装依赖 pip install -r requirements.txt # 设置 API 密钥 echo "ANTHROPIC_API_KEY=your-key-here" > .env # 运行服务器 python app.py # 在浏览器中打开 open http://localhost:8080 ``` 应用启动时会自动加载 `test-data/` 中的 WAF 定义和真实基线 —— 无需手动上传。 **测试数据集** 位于 `test-data/` 中，可用于探索所有功能： | 文件 | 故事数 | 最佳测试场景 | |------|--------|--------------| | `compliance-focus-60.csv` | 60 | 监管类别，高误分类率 | | `platform-engineering-80.csv` | 80 | 基础设施类别、跨团队史诗 | | `multi-team-product-120.csv` | 120 | 多团队视图、按史诗标签、空描述边界情况 | | `synthetic-100-stories.csv` | 100 | 通用混合数据集 | | `synthetic-5000-stories.csv` | 5000 | 性能和大数据集测试 | ## 页面 | 路由 | 页面 | 用途 | |------|------|------| | `/` | 首页 | 包含导航卡片和系统状态的着陆页 | | `/classify` | 分类器 | 带史诗标签功能的基于聊天的 AI 分类 | | `/history` | 分析 | 上传 → 映射列 → AI 验证 → 审查 → 摘要 → 谱系 → 历史 | | `/teams` | 团队 | 双面板团队分析及跨团队史诗矩阵 | | `/lineage` | 史诗谱系 | 史诗健康评分、WAF 分类统计、可折叠故事树 | | `/dashboard` | 仪表板 | 实时 KPI 卡片和分布图表 | | `/waf-reference` | WAF 参考 | 浏览带定义和决策规则的 8 个 WAF 类别 | | `/settings` | 设置 | WAF 定义、真实基线、基线快照和处理配置 | ## 分析工作流 1. **上传数据** — 选择包含 JIRA 故事的 CSV 或 Excel 文件 2. **映射列** — 确认或调整自动检测的列映射。标题和描述为必填。可选：团队、史诗、父功能、故事 ID、功能 ID、史诗 ID 3. **AI 审查** — Claude 针对 WAF 框架对每一行进行分类。所有文件异步处理，带实时进度条 4. **审查并保存** — 可排序的表格显示文件标签与 AI 推荐。不匹配行会预选。点击任意行查看完整故事详情。保存选中行到历史记录 5. **摘要** — 投资组合级别图表：类别分布、颜色占比、运行 vs 变更、置信度水平、误分类率。点击任意 KPI 卡片可深入分析 6. **史诗谱系** — 每个史诗的 WAF 分类分布、健康评分、不匹配标记及可折叠故事树 7. **历史** — 查看、重新加载或删除以往上传记录 每次上传都会生成一个唯一 ID。使用“数据源”选择器可按特定上传过滤分析结果，或查看所有上传的合并数据。 ## 团队工作流 1. 导航至 `/teams` 2. 选择一个**数据源**（上传）或保留“所有上传” 3. **团队标签页**：左侧面板展示团队 › 史诗 › 功能树。点击任意节点以在右侧面板加载故事。按任意列排序。点击 **显示洞察** 查看 KPI 卡片和图表 4. **按史诗标签页**：展示对每个史诗做出贡献的所有团队，并显示各团队的故事表格 ## 批准行为 `approved` 标志**仅设置为误分类行**——即文件的 WAF 标签与 AI 推荐不一致的故事。匹配行保存时不带 approved 标志。这确保了“已批准”计数仅代表经过主动审查和修正的故事，而非所有通过检查的条目。 ## 史诗健康评分 每个史诗的健康评分范围为 0 到 100，基于以下因素： - **颜色聚焦（40%）** — 具备主导 WAF 颜色的故事百分比 - **类别聚焦（30%）** — 属于主导类别故事的比例 - **颜色多样性惩罚（20%）** — 颜色越少越健康 - **误分类惩罚（10%）** — 误分类越少越健康 如果史诗包含 3 种及以上 WAF 颜色，或主导颜色低于 60%，则标记为“混合”。 ## 安全 - **生产环境禁用调试模式** - **XSS 防护** — 所有用户可控数据在渲染前均进行 HTML 转义 - **安全错误响应** — 向客户端返回通用消息；详细信息仅记录在服务器端 - **分页上限** — 每页最多 500 条结果 - **速率限制** — 批量上传限制为每 IP 每分钟 5 次请求（超出返回 HTTP 429） - **安全文件名** — 上传文件使用 `werkzeug.utils.secure_filename` 处理 - **无认证机制** — 仅设计用于可信内网；切勿暴露至公网 ## 技术栈 - **后端：** Python Flask，采用基于 Blueprint 的模块化架构 - **AI：** Anthropic Claude API（`claude-sonnet-4-6`）或 AWS Bedrock 备用 - **前端：** HTML/CSS/JS + Chart.js 4.4.1 + chartjs-plugin-datalabels - **数据库：** SQLite 搭配 FTS5 全文搜索 - **数据处理：** pandas、openpyxl 用于 CSV/Excel 处理 ## 项目结构 ``` waf-classifier/ ├── app.py # Flask init, blueprint registration, startup ├── config.py # Constants, AI backend detection, paths ├── database.py # SQLite schema, queries, FTS5 index, settings cache ├── state.py # Shared in-memory stores ├── waf_core.py # WAF categories, normalization, AI client, prompts ├── routes/ │ ├── pages.py # Page-serving routes │ ├── classify.py # Classification API endpoints │ ├── settings_api.py # Settings, ground truth, baselines API │ ├── analytics.py # Dashboard, history, export, search API │ ├── verify.py # Bulk verify API + worker threads │ ├── lineage.py # Epic lineage API │ └── teams.py # Team report API ├── .env # API key (not committed) ├── requirements.txt # Python dependencies ├── waf_history.db # SQLite DB (auto-created) ├── baselines/ # Saved baseline snapshots (auto-created) ├── static/ │ ├── home.html # Home landing page │ ├── index.html # Classifier chat UI │ ├── history.html # Analytics (Upload, Summary, Lineage, History tabs) │ ├── teams.html # Team report with two-panel layout and cross-team matrix │ ├── lineage.html # Epic Lineage with story tree and sort controls │ ├── dashboard.html # Real-time dashboard │ ├── settings.html # Admin settings (WAF defs, ground truth, baselines, config) │ └── waf-reference.html # WAF framework reference guide ├── sample-data/ │ ├── waf-definitions.csv # WAF framework (8 categories) │ ├── sample-ground-truth.csv # 18 calibration examples │ ├── synthetic-100-stories.csv # 100-record test set (quick testing) │ ├── synthetic-100-answer-key.csv # 100-record answer key │ ├── synthetic-5000-stories.csv # 5000-record full test set │ └── synthetic-5000-answer-key.csv # 5000-record answer key └── docs/ ├── API_Reference.md # API endpoint reference ├── Release_Notes.md # Version changelog └── Quick_Start.md # Getting started guide ``` ## 示例数据 | 文件 | 记录数 | 用途 | |------|--------|------| | `synthetic-100-stories.csv` | 100 | 快速测试 —— 28 个史诗、8 个类别、6 种颜色、15 个团队，约 15% 误分类 | | `synthetic-5000-stories.csv` | 5,000 | 完整测试 —— 在更大规模下保持相同分布 | `.csv-answer-key` 变体包含正确的 WAF 类别、颜色、运行/变更标识以及是否为误分类列。 ## 文档 - **[API 参考](docs/API_Reference.md)** — 所有端点及请求/响应规范 - **[发布说明](docs/Release_Notes.md)** — 版本历史和变更日志 - **[快速入门](docs/Quick_Start.md)** — 5 分钟设置指南

标签：AI分类, Anthropic Claude, Apex, CSV导入, Excel导入, Flask, FTS5, JIRA, SEO检索词, WAF, WAF类别参考, 不匹配标记, 代码示例, 健康评分, 全文本搜索, 决策规则, 功能关键词, 可编辑基线, 史诗谱系, 后端开发, 团队分析, 地面真相循环, 实时聊天分类, 工作对齐框架, 工作流程分配框架, 快照保存与恢复, 批处理分类, 投资组合报告, 持续改进AI, 故事分类, 敏捷梳理, 数据上传, 数据分析, 本地存储偏好, 机器学习, 浅色模式, 深色模式, 跨团队史诗矩阵, 逆向工具, 颜色编码