Elaina/ephron-ren-prd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0de9d3d8662c684b92026c522a752e642c94e44
ephron-ren-prd/api/prompt-api-specification.md

12 KiB
Raw Blame History

ephron.ren API 需求文档

版本: v1.0 更新日期: 2026-05-05 Base URL: https://{service}.ephron.ren/api/v1

一、概述

1.1 服务架构

服务 域名 说明
Home www.ephron.ren 个人主页
Auth auth.ephron.ren 认证授权
Blog blog.ephron.ren 博客系统
Canvas canvas.ephron.ren 代码画布
Prompt prompt.ephron.ren 提示词管理

1.2 权限级别

权限 标识 说明
🟢 公开 public 无需认证
🔵 用户 user 需要登录（Cookie 或 Token）
🟡 服务 service 需要 Service Token
🔴 管理 admin 需要管理员权限

1.3 认证方式

方式 Header 适用场景
Cookie ephron_auth 浏览器访问
Bearer Token Authorization: Bearer {token} 服务间调用
API Key X-API-Key: {key} 第三方集成

二、Home 服务

现状: ❌ 无API实现

2.1 需新增API

方法 路径 权限 说明 状态
GET /api/v1/profile 🟢 公开 获取个人资料 ❌ 待实现
GET /api/v1/skills 🟢 公开 获取技能列表 ❌ 待实现
GET /api/v1/projects 🟢 公开 获取项目列表 ❌ 待实现
GET /api/v1/projects/{id} 🟢 公开 获取项目详情 ❌ 待实现
GET /api/v1/timeline 🟢 公开 获取经历时间线 ❌ 待实现

三、Auth 服务

现状: 部分实现（主要是页面路由）

3.1 已实现

方法 路径 权限 说明
GET /auth/verify 🟢 公开 验证认证状态
GET /authz/service-admin 🟡 服务 验证服务管理员
POST /login 🟢 公开 用户登录
POST /register 🟢 公开 用户注册
POST /logout 🔵 用户 用户登出
GET /check-username 🟢 公开 检查用户名可用

3.2 需新增API

方法 路径 权限 说明 状态
GET /api/v1/users/{username} 🟢 公开 获取用户公开信息 ❌ 待实现
GET /api/v1/me 🔵 用户 获取当前用户信息 ❌ 待实现
PATCH /api/v1/me 🔵 用户 更新个人资料 ❌ 待实现
POST /api/v1/me/change-password 🔵 用户 修改密码 ❌ 待实现
POST /api/v1/auth/forgot-password 🟢 公开 发送重置邮件 ❌ 待实现
POST /api/v1/auth/reset-password 🟢 公开 重置密码 ❌ 待实现
POST /api/v1/me/api-keys 🔵 用户 生成 API Key ❌ 待实现
GET /api/v1/me/api-keys 🔵 用户 列出 API Keys ❌ 待实现
DELETE /api/v1/me/api-keys/{key_id} 🔵 用户 删除 API Key ❌ 待实现

四、Blog 服务

现状: 部分实现

4.1 已实现

方法 路径 权限 说明
GET /posts 🟢 公开 文章列表（页面）
GET /posts/{slug} 🟢 公开 文章详情（页面）
GET /api/service/posts 🟡 服务 文章列表（API）
GET /api/service/posts/{slug} 🟡 服务 文章详情（API）
POST /api/service/posts 🟡 服务 创建文章
PATCH /api/service/posts/{slug} 🟡 服务 更新文章
DELETE /api/service/posts/{slug} 🟡 服务 删除文章
GET /posts/{post_slug}/comments 🟢 公开 获取评论
POST /posts/{post_slug}/comments 🔵 用户 添加评论
GET /feed 🟢 公开 RSS 订阅
GET /sitemap.xml 🟢 公开 站点地图

4.2 需新增API

方法 路径 权限 说明 状态
GET /api/v1/posts 🟢 公开 文章列表API ❌ 待实现
GET /api/v1/posts/{slug} 🟢 公开 文章详情API ❌ 待实现
GET /api/v1/posts/search 🟢 公开 全文搜索 ❌ 待实现
POST /api/v1/posts/{slug}/view 🟢 公开 记录阅读 ❌ 待实现
POST /api/v1/posts/{slug}/like 🔵 用户 点赞文章 ❌ 待实现
DELETE /api/v1/posts/{slug}/like 🔵 用户 取消点赞 ❌ 待实现
POST /api/v1/posts/{slug}/favorite 🔵 用户 收藏文章 ❌ 待实现
DELETE /api/v1/posts/{slug}/favorite 🔵 用户 取消收藏 ❌ 待实现
GET /api/v1/posts/{slug}/stats 🟢 公开 获取统计 ❌ 待实现
GET /api/v1/user/favorites 🔵 用户 收藏列表 ❌ 待实现
GET /api/v1/posts/{slug}/comments 🟢 公开 评论列表API ❌ 待实现
POST /api/v1/posts/{slug}/comments 🔵 用户 添加评论API ❌ 待实现
POST /api/v1/upload/image 🔵 用户 上传图片 ❌ 待实现
GET /api/v1/posts/{slug}/versions 🔵 用户 版本历史 ❌ 待实现
POST /api/v1/posts/batch 🟡 服务 批量操作 ❌ 待实现
GET /api/v1/posts/export 🟡 服务 导出文章 ❌ 待实现

五、Canvas 服务

现状: ❌ 无API实现

5.1 需新增API

方法 路径 权限 说明 状态
GET /api/v1/canvas 🟢 公开 画布列表 ❌ 待实现
GET /api/v1/canvas/{slug} 🟢 公开 画布详情 ❌ 待实现
GET /api/v1/canvas/{slug}/raw 🟢 公开 原始内容 ❌ 待实现
POST /api/v1/canvas/{slug}/view 🟢 公开 记录浏览 ❌ 待实现
POST /api/v1/canvas 🟡 服务 创建画布 ❌ 待实现
PATCH /api/v1/canvas/{slug} 🟡 服务 更新画布 ❌ 待实现
DELETE /api/v1/canvas/{slug} 🟡 服务 删除画布 ❌ 待实现
POST /api/v1/canvas/{slug}/like 🔵 用户 点赞 ❌ 待实现
POST /api/v1/canvas/{slug}/favorite 🔵 用户 收藏 ❌ 待实现
GET /api/v1/templates 🟢 公开 模板列表 ❌ 待实现
POST /api/v1/canvas/{slug}/share 🔵 用户 生成分享链接 ❌ 待实现

六、Prompt 服务

现状: ✅ 已实现7个API

6.1 已实现

方法 路径 权限 说明
GET /api/prompts 🟢 公开 提示词列表
GET /api/prompts/{key} 🟢 公开 提示词详情
GET /api/service/prompts 🟡 服务 提示词列表
GET /api/service/prompts/{key} 🟡 服务 提示词详情
POST /api/service/prompts 🟡 服务 创建草稿
PATCH /api/service/prompts/{key} 🟡 服务 更新草稿
DELETE /api/service/prompts/{key} 🟡 服务 删除草稿

6.2 需新增API

方法 路径 权限 说明 状态
GET /api/v1/prompts/search 🟢 公开 高级搜索 ❌ 待实现
GET /api/v1/prompts/categories 🟢 公开 分类列表 ❌ 待实现
GET /api/v1/prompts/tags 🟢 公开 标签列表 ❌ 待实现
GET /api/v1/prompts/popular 🟢 公开 热门提示词 ❌ 待实现
POST /api/v1/prompts/{key}/use 🟢 公开 记录使用 ❌ 待实现
POST /api/v1/prompts/{key}/like 🔵 用户 点赞 ❌ 待实现
DELETE /api/v1/prompts/{key}/like 🔵 用户 取消点赞 ❌ 待实现
POST /api/v1/prompts/{key}/favorite 🔵 用户 收藏 ❌ 待实现
DELETE /api/v1/prompts/{key}/favorite 🔵 用户 取消收藏 ❌ 待实现
GET /api/v1/user/favorites 🔵 用户 收藏列表 ❌ 待实现
GET /api/v1/prompts/{key}/versions 🟡 服务 版本历史 ❌ 待实现
GET /api/v1/prompts/{key}/versions/{v} 🟡 服务 特定版本 ❌ 待实现
POST /api/v1/prompts/{key}/rollback/{v} 🟡 服务 回滚版本 ❌ 待实现
POST /api/v1/prompts/batch 🟡 服务 批量创建 ❌ 待实现
POST /api/v1/prompts/batch-delete 🟡 服务 批量删除 ❌ 待实现
GET /api/v1/prompts/export 🟡 服务 导出 ❌ 待实现
POST /api/v1/prompts/import 🟡 服务 导入 ❌ 待实现
GET /api/v1/marketplace 🟢 公开 模板市场 ❌ 待实现
POST /api/v1/marketplace/{key}/publish 🔵 用户 发布到市场 ❌ 待实现
POST /api/v1/marketplace/{key}/install 🔵 用户 安装模板 ❌ 待实现

七、通用接口

现状: ❌ 无实现

7.1 需新增API

方法 路径 权限 说明 状态
POST /api/v1/upload 🔵 用户 上传文件 ❌ 待实现
GET /api/v1/notifications 🔵 用户 通知列表 ❌ 待实现
POST /api/v1/notifications/{id}/read 🔵 用户 标记已读 ❌ 待实现
GET /api/v1/search 🟢 公开 全局搜索 ❌ 待实现
POST /api/v1/webhooks 🔵 用户 创建 Webhook ❌ 待实现
GET /api/v1/webhooks 🔵 用户 列出 Webhooks ❌ 待实现
DELETE /api/v1/webhooks/{id} 🔵 用户 删除 Webhook ❌ 待实现
GET /api/v1/admin/stats 🔴 管理 全站统计 ❌ 待实现

八、实现统计

服务 已实现 待实现 总计
Home 0 5 5
Auth 6 9 15
Blog 11 16 27
Canvas 0 11 11
Prompt 7 20 27
通用 0 8 8
总计 24 69 93

完成度: 24/93 = 26%

九、实现优先级

P0 - 核心功能

服务 API 说明
Home /api/v1/profile 首页展示
Auth /api/v1/me 用户系统基础
Blog /api/v1/posts 文章列表API
Blog /api/v1/posts/search 文章搜索
Canvas /api/v1/canvas 画布列表
Prompt /api/v1/prompts/search 高级搜索

P1 - 重要功能

服务 API 说明
Auth /api/v1/me/api-keys 第三方集成
Blog /api/v1/posts/{slug}/like 用户互动
Blog /api/v1/upload/image 图片上传
Canvas 服务API 自动化支持
Prompt 批量操作 管理效率

P2 - 增强功能

服务 API 说明
Auth 密码重置 用户体验
Blog 版本管理 内容管理
Canvas 模板API 用户便利
Prompt 模板市场 社区生态

P3 - 扩展功能

服务 API 说明
通用 通知服务 用户提醒
通用 Webhook 自动化
通用 全局搜索 用户体验

十、错误处理

{
  "detail": "错误信息",
  "code": "ERROR_CODE"
}
HTTP 说明
400 请求参数错误
401 未认证
403 无权限
404 资源不存在
429 请求过于频繁
500 服务器错误

十一、速率限制

API 类型 限制
公开 API (GET) 100次/分钟
公开 API (POST) 10次/分钟
用户 API 60次/分钟
服务 API 30次/分钟
文件上传 5次/分钟

十二、数据库扩展

-- 用户收藏表
CREATE TABLE user_favorites (
    id INTEGER PRIMARY KEY,
    user_id TEXT NOT NULL,
    resource_type TEXT NOT NULL,
    resource_id TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(user_id, resource_type, resource_id)
);

-- 使用统计表
CREATE TABLE usage_stats (
    id INTEGER PRIMARY KEY,
    resource_type TEXT NOT NULL,
    resource_id TEXT NOT NULL,
    user_id TEXT,
    action TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- API Keys 表
CREATE TABLE api_keys (
    id INTEGER PRIMARY KEY,
    key_id TEXT UNIQUE NOT NULL,
    user_id TEXT NOT NULL,
    key_hash TEXT NOT NULL,
    name TEXT,
    permissions TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_used_at TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE
);
Reference in New Issue View Git Blame Copy Permalink