aitsc/docs/prompt_quality_module_plan.md

# 提示词质量对比与评价模块 — 开发计划

| 项 | 说明 |
|----|------|
| 目标 | 多份优化后提示词 → 模型结构化评价；评价历史检索与简单可视化对比 |
| 存储 | 与现有 Flask-SQLAlchemy 一致；开发默认 SQLite（`DATABASE_URL` 未设时）；生产可用 MySQL，表结构通用 |

## 1. 接口定义

### POST `/api/prompt-quality/analyze`

**输入** `application/json`：

```json
{
  "prompts": ["提示词文本1", "提示词文本2"],
  "task_context": "可选：任务背景/领域，便于模型对齐预期输出"
}
```

**输出** `application/json`：

```json
{
  "success": true,
  "data": {
    "batch_id": "uuid",
    "results": [
      {
        "optimized_prompt": "与输入对应的完整文本",
        "evaluation": {
          "score": 82,
          "strengths": ["..."],
          "weaknesses": ["..."],
          "suggestions": ["..."],
          "applicability": ["..."],
          "mandatory_fixes": ["必须修正项"],
          "optimization_suggestions": ["可优化建议"]
        },
        "history_id": "记录主键字符串",
        "timestamp": "2026-04-03T12:00:00+00:00"
      }
    ],
    "batch_comparison": "批量横向对比摘要（可选）",
    "incremental_learning_hints": ["从本批提炼的可迁移经验"]
  }
}
```

### GET `/api/prompt-quality/history`

**Query**：`page`, `per_page`, `date_from`, `date_to`（ISO 日期）, `q`（关键词，匹配提示词片段或评价 JSON 文本）, `batch_id`（可选）

**输出**：分页列表，每条含 `batch_id`、`created_at`、`preview`、`item_count`、`results` 摘要或详情开关。

### GET `/api/prompt-quality/history/<int:record_id>`

单条记录详情（权限：同 `user_id`）。

## 2. 评价逻辑（算法描述）

1. **预处理**：去空、单条最大长度截断（如 8000 字符）、条数上限（如 ≤8）。
2. **模型调用**：系统角色 = 提示词评估专家；用户内容 = 编号列表 + 可选 `task_context`；要求 **仅输出合法 JSON**（与约定 schema 一致）。
3. **维度约束**（写入 system 说明）：清晰度、指令完整性、可操作性、预期输出匹配度；区分 **mandatory_fixes**（必须修正）与 **optimization_suggestions**（建议优化）。
4. **校验**：`json.loads`；缺字段时用安全默认值补全；`score` 钳制 0–100。
5. **持久化**：每条输入写一行 `prompt_quality_record`；同批次共用 `batch_id`；批次级 `batch_comparison` / `incremental_learning_hints` 挂在 `prompt_index=0` 行或独立字段。

## 3. 表结构要点

**`prompt_quality_record`**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | PK | `history_id` 来源 |
| user_id | int, index | 与 Session 对齐 |
| batch_id | string(36), index | 同次分析 UUID |
| prompt_index | int | 批次内序号 |
| optimized_prompt | text | 被评文本 |
| evaluation_json | JSON | 结构化评价（含两类优先级字段） |
| batch_summary | text, nullable | 批次对比摘要（仅首条或冗余存储） |
| incremental_hints_json | JSON, nullable | 增量学习建议列表 |
| created_at | datetime | ISO 时间来源 |

SQLite：`JSON` 由 SQLAlchemy 映射为 TEXT；MySQL 可用原生 JSON。

## 4. 查询 API 示例

```http
GET /api/prompt-quality/history?page=1&per_page=10&date_from=2026-04-01&date_to=2026-04-03&q=openlaw
```

## 5. 前端（Vue）

- 路由：`/prompt-quality`
- 多行文本输入，约定 **空行分隔** 多条提示词；按钮「模型分析评价」
- 展示：卡片列表（score、优劣、两类建议、适用场景）；批次对比与增量建议
- 历史区：表格 + 筛选 + 查看详情抽屉

---

**实施顺序**：模型与建表 SQL → service + 蓝图 → 注册应用 → Vue API + 页面 + 路由 + 导航。

---

## 实施记录（已完成）

| 组件 | 路径 |
|------|------|
| 计划文档 | `docs/prompt_quality_module_plan.md` |
| ORM | `src/flask_prompt_master/models/prompt_quality_models.py` |
| LLM 服务 | `src/flask_prompt_master/services/prompt_quality_service.py` |
| API 蓝图 | `src/flask_prompt_master/routes/prompt_quality_routes.py`，前缀 `/api/prompt-quality` |
| 应用注册 | `src/flask_prompt_master/__init__.py` 注册蓝图并加载模型 |
| 手工建表 SQL（SQLite 友好） | `scripts/prompt_quality_schema.sql` |
| 建表 | 首次可执行 `db.create_all()`（已在当前环境对 MySQL 验证） |
| Vue 页面 | `vue-app/src/views/PromptQualityView.vue`，路由 `/prompt-quality`，顶栏「质量评价」 |
| Vue API | `vue-app/src/api/modules/promptQuality.ts`、`api/types/promptQuality.ts` |