# Proposal: init-promptcr-platform

## Why

毕业设计研究需要开展"多模型 × 多提示词策略"的代码审查对照实验，目前缺少一个能覆盖**数据集构建 → 模型调用 → 结果采集 → 指标计算 → 图表产出**全流程自动化的实验支撑平台。手工执行 324+ 个实验单元不可行，且无法保证可复现性。本平台面向单研究者、Docker 一键部署、单机可运行。

## What Changes

从零搭建整个平台（仓库当前为空），包含以下新能力：

- **数据集管理（F1）**：从开源 Git 仓库筛选 commit、提取 Unidiff、按可插拔缺陷规则预埋缺陷（Python 基于 `ast`，其他语言轻量变换）、生成 Ground Truth 标注；交付 12 个样本、覆盖 ≥3 种语言且分布均衡；缺陷规则可插拔（新增规则文件即可扩展，无需改框架代码）。
- **模型接入（F2）**：适配器模式抽象基类 `ModelAdapter`，DeepSeek / Kimi / 通义千问三个适配器统一走 OpenAI 兼容格式；工厂模式创建；内置信号量并发控制与指数退避重试。
- **提示词策略（F3）**：内置 L1（检测错误）→ L2（定位类型与行号）→ L3（修复建议）三级难度递增策略；Jinja2 模板配置化、带版本号；Web 在线编辑保存即新版本，历史版本只读；对外仅暴露 `render(strategy_id, version, context)`。
- **实验调度与采集（F4）**：全因子矩阵 3 模型 × N 级 × 12 commit × 3 重复（N=3 时 324 单元），唯一 `run_id`；asyncio 异步队列五步流水线；失败重试 + 隔离 + 断点续跑；原始输出、token、耗时、状态全量落库。
- **数据分析与可视化（F5）**：五维指标（缺陷检出率、误报率、审查覆盖率、建议可操作性李克特五级量表、输出稳定性）；描述性统计 + ANOVA + 配对 t 检验；matplotlib 论文静态图（热力图/箱线图/分组柱状图，支持中文）+ 前端 JSON 数据接口。
- **后端接入层（F6）**：FastAPI RESTful API 与 Typer CLI 两种等价调用方式；API 兼作前端数据源。
- **Web 前端（F7）**：React 18 + Tailwind CSS 3 + shadcn/ui + Vite，ECharts 唯一图表库；四个页面：数据集管理、实验配置（含模板在线编辑）、实验监控（进度/原始输出/断点续跑）、结果分析（交互图表 + 李克特打分录入）。
- **部署**：后端/前端/PostgreSQL 各自容器化，`docker compose up` 一键拉起，PostgreSQL volume 持久化。

## Capabilities

### New Capabilities
- `dataset-management`: Git 仓库解析、diff 提取、可插拔缺陷预埋、Ground Truth 标注与数据集交付
- `model-adapters`: OpenAI 兼容格式的三厂商模型适配器、工厂创建、并发控制与重试
- `prompt-strategies`: 分级提示词模板、版本管理、在线编辑、统一渲染接口
- `experiment-orchestration`: 全因子实验矩阵生成、异步调度执行、结果落库、断点续跑
- `analysis-metrics`: 五维评价指标计算、统计分析、论文图表与前端数据接口
- `backend-access`: FastAPI RESTful API 与 Typer CLI 等价接入
- `web-frontend`: React SPA 四页面、ECharts 图表、与后端仅经 API 交互

### Modified Capabilities
（无——仓库为空，全部为新增能力。）

## Impact

- **新增代码**：`backend/`（Python 3.11，FastAPI + SQLAlchemy + asyncio）、`frontend/`（React 18 + Vite）、`docker-compose.yml`、各服务 Dockerfile、README（含 ER 说明）。
- **外部依赖**：PostgreSQL（唯一中间件）、三个大模型厂商 API（DeepSeek / Kimi / 通义千问，密钥走环境变量）。
- **明确排除**：无用户系统、无移动端/SSR、无 MQ/Redis/K8s、不训练模型、不做真实缺陷挖掘与自动修复、不硬编码密钥、不覆盖历史模板版本、前端不直连数据库。
- **验收基线**：功能 A1–A7、健壮性 B1–B4、可复现性 C1–C2、工程 D1–D4（含后端 pytest 覆盖率 ≥90%）。