aitsc/AI项目功能需求文档.md

# AI 项目功能需求文档

| 项目 | 说明 |
|------|------|
| **目标** | 定义「提示词大师」AI 项目的功能范围、模块划分与 AI 能力需求 |
| **版本号** | v1.0 |
| **责任人** | 项目组 |
| **最后更新日期** | 2026-02-23 |

---

## 变更记录

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|----------|
| v1.0 | 2026-02-23 | 系统 | 初稿：基于代码分析整理功能与 AI 需求 |

---

## 1. 项目概述

### 1.1 项目名称与定位

- **项目名称**：提示词大师（aitsc / flask_prompt_master）
- **定位**：基于大语言模型（LLM）的智能提示词生成与多场景 AI 应用平台
- **技术栈**：Python 3.12、Flask、Gunicorn、SQLAlchemy、MySQL、DeepSeek API（OpenAI 兼容）

### 1.2 目标用户

- **Web 用户**：通过浏览器使用提示词生成、饭菜规划、古诗词解析、收藏与历史
- **微信小程序用户**：通过小程序使用提示词生成、意图识别、专家提示词、饭菜规划等
- **管理员**：通过 Flask-Admin 后台进行用户/内容/系统/数据分析管理

### 1.3 访问与部署

- **服务端口**：5002
- **运行方式**：Gunicorn + run_dev:app，conda 环境 myenv
- **文档**：参见《(红头)启动和停止.txt》

---

## 2. 功能模块需求

### 2.1 提示词生成（核心 AI 功能）

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-101 | 用户输入简短描述，系统根据所选模板（或默认）调用 LLM 生成高质量提示词 | P0 |
| F-102 | 支持按分类/行业/职业选择提示词模板，模板含系统提示词（system_prompt） | P0 |
| F-103 | 生成结果持久化（Prompt 表），并写入历史（PromptHistory）供后续查看与优化 | P0 |
| F-104 | 对生成结果支持反馈（评分、评论），写入 Feedback 表 | P1 |
| F-105 | Web 端与微信端共用生成逻辑，微信端通过 /api/wx/generate 调用 | P0 |

### 2.2 意图识别与专家提示词（微信端增强）

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-201 | 根据用户输入进行意图识别，返回推荐模板类别（如新闻获取、生成图片、网站开发、文案创作等） | P1 |
| F-202 | 两阶段专家提示词：先做意图分析（返回 core_intent、domain、key_requirements 等 JSON），再按领域（技术/创意/分析/咨询）选用专家模板生成最终提示词 | P1 |
| F-203 | 提供专家提示词生成页与 API：/expert_generate、/api/wx/generate/expert | P1 |

### 2.3 模板管理

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-301 | 模板数据存储在 PromptTemplate 表（name、description、category、industry、profession、system_prompt、is_default） | P0 |
| F-302 | 提供按分类/意图/关键词的模板查询 API，供 Web 与微信端使用 | P0 |
| F-303 | 支持内置/预置行业模板（写作、故事、短视频、设计、营销、开发、医疗、法律等）的初始化与维护 | P1 |

### 2.4 智能饭菜规划（AI）

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-401 | 用户输入人数、餐型、家乡、喜好、禁忌、预算等，系统调用 LLM 生成地区化、可执行的饭菜清单（Markdown） | P0 |
| F-402 | 支持保存规划到 MealPlan 表，支持历史列表与单条查看、删除 | P0 |
| F-403 | 提供 Web 页 /meal-planning、/meal-planning/mobile、/meal-planning/history 及对应 API | P0 |

### 2.5 古诗词解析（AI）

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-501 | 用户提供诗词标题、作者、朝代、翻译风格、解读深度等，系统调用 LLM 生成原文、译文、注释、解读（Markdown） | P0 |
| F-502 | 支持收藏解析结果到 PoetryFavorite，支持列表、编辑、删除、统计、是否已收藏检查 | P0 |
| F-503 | 提供古诗词示例页、解析页、收藏页及对应 API（/poetry/、/poetry/analyze、/poetry/examples、/poetry/favorites 等） | P0 |

### 2.6 收藏与历史

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-601 | 通用收藏：Favorite 管理，支持增删改查、统计、快速添加，路由 /favorites 及 /api/favorites/* | P1 |
| F-602 | 提示词历史：PromptHistory 的查看、标签、批量操作、导出、统计、按模板筛选、保存为模板 | P0 |
| F-603 | 优化历史：OptimizationHistory 及相关标签、收藏、用户使用统计（UserUsageStats） | P1 |

### 2.7 用户与认证

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-701 | Web 用户注册、登录、登出、个人资料、修改密码，登录态通过 Session 维护 | P0 |
| F-702 | 微信小程序登录：code 换 openid/session_key，返回自定义 uid，后续接口按 uid 鉴权 | P0 |
| F-703 | 部分接口需登录（如收藏、历史、个人数据），支持 /api/check-login、/api/profile/stats 等 | P0 |

### 2.8 管理后台（Flask-Admin）

| 需求编号 | 功能描述 | 优先级 |
|----------|----------|--------|
| F-801 | 管理员独立登录（AdminUser），角色：admin、super_admin、system_admin | P0 |
| F-802 | 用户管理、提示词管理、模板管理、系统管理、批量操作、系统监控、高级报表、数据备份、API 管理 | P1 |
| F-803 | 数据分析（Analytics）：仅 super_admin、system_admin 可访问，提供统计与图表（如 Plotly） | P1 |
| F-804 | 后台登录/登出：/admin/login、/admin/logout | P0 |

---

## 3. AI / LLM 能力需求

### 3.1 使用的模型与服务

| 项目 | 说明 |
|------|------|
| **服务** | DeepSeek API（OpenAI 兼容接口，base_url: https://api.deepseek.com/v1） |
| **模型** | deepseek-chat |
| **鉴权** | 通过 API Key（建议从环境变量 LLM_API_KEY 读取，避免硬编码） |

### 3.2 AI 场景与提示词策略

| 场景 | 系统角色/提示策略 | 输出形式 |
|------|-------------------|----------|
| 提示词生成 | 使用 DB 模板的 system_prompt 或默认「提示词工程师」 | 自然语言提示词 |
| 意图识别 | 固定「意图识别专家」提示，仅返回类别 | 单一类别标签 |
| 意图分析（专家） | 「意图分析专家」要求返回 JSON（core_intent、domain、key_requirements 等） | JSON |
| 专家提示词生成 | 按 core_intent 选领域专家模板再生成 | 自然语言提示词 |
| 饭菜规划 | 「地区智能饭菜清单规划师」，用户输入人数/餐型/家乡/喜好/禁忌/预算 | Markdown 清单 |
| 古诗词解析 | 「古典文学专家/古诗词翻译家」，用户输入标题/作者/朝代/风格/深度 | 原文、译文、注释、解读（Markdown） |

### 3.3 调用参数与可靠性

| 项目 | 要求 |
|------|------|
| **temperature** | 通用生成 0.7；意图类 0.1 |
| **max_tokens** | 约 500～2000（按场景配置） |
| **超时** | 约 30～60 秒 |
| **重试** | 提示词生成支持 max_retries（如 3 次） |

### 3.4 配置与安全

- **需求**：LLM API 的 base_url、api_key 应从配置/环境变量（如 LLM_API_URL、LLM_API_KEY）读取，禁止在生产环境硬编码。
- **现状**：部分路由仍存在硬编码 Key，需在后续迭代中统一为配置项。

---

## 4. 数据与配置需求

### 4.1 主要数据模型

| 模型 | 用途 |
|------|------|
| User | Web 用户（登录名、密码、昵称、手机、邮箱等） |
| WxUser | 微信用户（openid、session_key、unionid、昵称、头像等） |
| Prompt | 单次生成的输入与输出 |
| Feedback | 对 Prompt 的评分与评论 |
| PromptTemplate | 提示词模板（分类、行业、职业、system_prompt） |
| MealPlan | 饭菜规划参数与结果内容 |
| Favorite | 通用收藏 |
| PoetryFavorite | 古诗词解析收藏 |
| PromptHistory / HistoryTag | 提示词历史与标签 |
| OptimizationHistory / OptimizationTag / OptimizationFavorite | 优化历史与标签、收藏 |
| UserStatistics / UserUsageStats | 用户与使用统计 |
| AdminUser | 后台管理员（用户名、密码、角色） |
| SystemConfig | 系统配置项 |

### 4.2 环境与配置

- **多环境**：通过 FLASK_ENV 选择 development / production / testing / local，对应 config 目录下配置类。
- **关键配置项**：SECRET_KEY、DATABASE_URL、LLM_API_URL、LLM_API_KEY、WX_APPID、WX_SECRET、CORS_ORIGINS、LOG_LEVEL、SESSION_LIFETIME_HOURS、REDIS_URL（生产）、CACHE_TYPE 等。

### 4.3 第三方依赖（核心）

- Flask、flask-cors、flask-sqlalchemy、flask-migrate、flask-admin、flask-login
- openai（兼容 DeepSeek）、requests、pymysql、python-dotenv
- redis、waitress、psutil 等

---

## 5. 非功能需求（摘要）

| 类型 | 要求 |
|------|------|
| **可用性** | 服务端口 5002 稳定监听，支持多 worker 部署 |
| **安全** | 管理员按角色控制；数据分析仅高权限角色；API Key 与密钥走配置/环境变量 |
| **可维护性** | 日志输出到 logs/（gunicorn、app），便于排查 |
| **兼容性** | Web 与微信小程序共用后端 API，需 CORS 与小程序域名配置 |

---

## 6. 关联资源

- **代码库**：/home/renjianbo/aitsc
- **启动与停止说明**：(红头)启动和停止.txt
- **主入口**：run_dev.py，应用工厂 src/flask_prompt_master/__init__.py create_app()

---

*文档结束*