# Prompt 服务架构参考

> 基于 2026-05-05 代码分析，源码位于 `/home/ubuntu/projects/ephron.ren/prompt/`

## 项目结构

```
prompt/
├── src/
│   ├── main.py              # FastAPI 入口，挂载路由和中间件
│   ├── config.py             # 环境变量配置（AUTH_SECRET_KEY, DATABASE_PATH）
│   ├── routes/
│   │   ├── pages.py          # 页面路由（Jinja2 模板渲染，HTMLResponse）
│   │   ├── api.py            # 公开 API（/api/prompts, /api/prompts/{key}）
│   │   ├── admin.py          # 管理后台路由（/admin/*，需 Cookie 认证）
│   │   └── service_api.py    # 服务端 API（/api/service/*，需 Bearer Token）
│   └── services/
│       ├── prompts.py        # 提示词 CRUD + 版本管理
│       ├── db.py             # SQLite 连接 + 建表
│       └── auth.py           # 认证辅助
├── templates/
│   ├── base.html             # 基础模板（暗色主题、Inter + JetBrains Mono）
│   ├── public/
│   │   ├── index.html        # 列表页（搜索、分类筛选、标签过滤、卡片网格）
│   │   └── detail.html       # 详情页（内容展示、复制按钮、示例区域）
│   └── admin/
│       ├── index.html        # 管理列表
│       ├── edit.html         # 编辑表单
│       ├── new.html          # 新建表单
│       └── versions.html     # 版本历史
├── static/
│   ├── css/ds/               # 设计系统 CSS（tokens, components, layout, motion）
│   └── js/ds/ui.js           # UI 交互（modal、toast、通用组件）
└── tests/
```

## 数据模型

### prompts 表
```sql
CREATE TABLE prompts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    key TEXT NOT NULL UNIQUE,              -- URL 标识，如 "deep-research-prompt"
    title TEXT NOT NULL,
    description TEXT,
    category TEXT NOT NULL DEFAULT '未分类',
    tags TEXT,                             -- 逗号分隔
    is_template INTEGER NOT NULL DEFAULT 0,
    variables TEXT,                        -- 模板变量（逗号分隔）
    example_input TEXT,
    example_output TEXT,
    recommended_model TEXT NOT NULL DEFAULT '通用',
    is_active INTEGER NOT NULL DEFAULT 1,
    draft INTEGER NOT NULL DEFAULT 0,
    created_by TEXT,
    updated_by TEXT,
    ownership_type TEXT NOT NULL DEFAULT 'human',  -- 'human' | 'service'
    handoff_to_human INTEGER NOT NULL DEFAULT 0,
    current_version_id INTEGER,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);
```

### prompt_versions 表
```sql
CREATE TABLE prompt_versions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    prompt_key TEXT NOT NULL,
    version INTEGER NOT NULL,
    content TEXT NOT NULL,
    created_by TEXT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    FOREIGN KEY (prompt_key) REFERENCES prompts(key) ON DELETE CASCADE,
    UNIQUE(prompt_key, version)
);
```

## API 端点

### 公开 API（无需认证）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/prompts` | 列表（支持 search, tag, category, limit, offset） |
| GET | `/api/prompts/{key}` | 详情（支持 version 查询参数） |

### 服务端 API（Bearer Token）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/service/prompts` | 列表 |
| GET | `/api/service/prompts/{key}` | 详情 |
| POST | `/api/service/prompts` | 创建草稿 |
| PATCH | `/api/service/prompts/{key}` | 更新草稿 |
| DELETE | `/api/service/prompts/{key}` | 删除草稿 |

### 页面路由（返回 HTML）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` 或 `/prompts` | 列表页（支持 q, category, tag 查询参数） |
| GET | `/prompts/{key}` | 详情页 |
| GET | `/admin/*` | 管理后台（需登录 + 权限） |

## 设计系统

- **主题**: 暗色（bg-primary: #09090b, accent: #3b82f6）
- **字体**: Inter（正文）+ JetBrains Mono（代码）
- **CSS 变量**: 定义在 `:root` 中，所有组件引用变量
- **卡片组件**: `.prompt-card` 使用 `bg-secondary` + border + hover 效果
- **标签**: `.tag` 类，带 `tag-bg` 背景
- **复制按钮**: `.copy-btn`，绝对定位在内容块右上角
- **CSP**: `connect-src 'self'`，`script-src 'self' 'unsafe-inline'`，`cdn.jsdelivr.net` 已白名单

## 现有功能特性

1. **版本管理**: 每次编辑创建新版本，支持版本切换
2. **模板变量**: `is_template=true` 时，`variables` 字段定义可替换变量
3. **草稿系统**: `draft` 字段 + `ownership_type` 区分人类/服务创建
4. **搜索过滤**: 支持关键词搜索、分类筛选、标签过滤
5. **复制功能**: 前端 `navigator.clipboard.writeText()` 实现

## 待实现功能（PRD 已写）

- **调用测试**: 详情页测试 Tab，填变量 → 调 LLM → 流式输出
- **集合**: `collections` + `collection_items` 表，组织相关提示词

## 开发注意事项

- 路由区分：`response_class=HTMLResponse` → 页面路由，返回 dict/Pydantic → API
- Key 自动生成：创建 prompt 时 key 可能被截取/简化，以响应返回值为准
- Key 不可变：PATCH 不能修改 key 字段
- 服务端只能编辑自己创建的草稿（`created_by == actor_id` + `ownership_type == "service"` + `draft == true`）
- 所有时间使用 SQLite `datetime('now')` 存储