init: consolidate all ephron.ren PRDs and docs

2026-05-15 10:39:54 +08:00
parent 9568533314
commit ee8cddf8b8
21 changed files with 6991 additions and 2 deletions
--- a/api/api-specification.md
+++ b/api/api-specification.md
@@ -0,0 +1,156 @@
+# ephron.ren API 文档
+
+> 版本: v1.0
+> 更新日期: 2026-05-05
+> 状态: 已实现
+
+---
+
+## 概述
+
+本文档记录 ephron.ren 已实现的所有 API 接口。
+
+### 服务架构
+
+| 服务 | 域名 | 说明 |
+|------|------|------|
+| Auth | auth.ephron.ren | 认证授权 |
+| Blog | blog.ephron.ren | 博客系统 |
+| Canvas | canvas.ephron.ren | 代码画布 |
+| Prompt | prompt.ephron.ren | 提示词管理 |
+
+### 权限级别
+
+| 权限 | 标识 | 说明 |
+|------|------|------|
+| 🟢 公开 | `public` | 无需认证 |
+| 🔵 用户 | `user` | 需要登录 |
+| 🟡 服务 | `service` | 需要 Service Token |
+
+### 认证方式
+
+| 方式 | Header | 说明 |
+|------|--------|------|
+| Cookie | `ephron_auth` | 浏览器访问 |
+| Bearer Token | `Authorization: Bearer {token}` | 服务间调用 |
+
+---
+
+## Auth 服务
+
+### 用户认证
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/login` | 🟢 公开 | 用户登录 |
+| POST | `/register` | 🟢 公开 | 用户注册 |
+| POST | `/logout` | 🔵 用户 | 用户登出 |
+| GET | `/check-username` | 🟢 公开 | 检查用户名可用 |
+
+### 认证验证
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/auth/verify` | 🟢 公开 | 验证认证状态 |
+| GET | `/authz/service-admin` | 🟡 服务 | 验证服务管理员 |
+
+---
+
+## Blog 服务
+
+### 文章管理（服务API）
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/service/posts` | 🟡 服务 | 文章列表 |
+| GET | `/api/service/posts/{slug}` | 🟡 服务 | 文章详情 |
+| POST | `/api/service/posts` | 🟡 服务 | 创建文章 |
+| PATCH | `/api/service/posts/{slug}` | 🟡 服务 | 更新文章 |
+| DELETE | `/api/service/posts/{slug}` | 🟡 服务 | 删除文章 |
+
+### 点赞功能
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/posts/{post_slug}/likes` | 🟢 公开 | 获取点赞状态 |
+| POST | `/posts/{post_slug}/likes/toggle` | 🟢 公开 | 切换点赞 |
+| GET | `/posts/{post_slug}/likes/stats` | 🟢 公开 | 点赞统计 |
+
+### 评论功能
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/posts/{post_slug}/comments` | 🟢 公开 | 获取评论列表 |
+| POST | `/posts/{post_slug}/comments` | 🔵 用户 | 添加评论 |
+
+### 订阅与站点
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/feed` | 🟢 公开 | RSS 订阅 |
+| GET | `/sitemap.xml` | 🟢 公开 | 站点地图 |
+
+---
+
+## Canvas 服务
+
+### 画布管理（服务API）
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/service/canvas` | 🟡 服务 | 画布列表 |
+| GET | `/api/service/canvas/{slug}` | 🟡 服务 | 画布详情 |
+| POST | `/api/service/canvas` | 🟡 服务 | 创建画布 |
+| PATCH | `/api/service/canvas/{slug}` | 🟡 服务 | 更新画布 |
+| DELETE | `/api/service/canvas/{slug}` | 🟡 服务 | 删除画布 |
+
+---
+
+## Prompt 服务
+
+### 公开API
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/prompts` | 🟢 公开 | 提示词列表 |
+| GET | `/api/prompts/{key}` | 🟢 公开 | 提示词详情 |
+
+### 服务API
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/service/prompts` | 🟡 服务 | 提示词列表 |
+| GET | `/api/service/prompts/{key}` | 🟡 服务 | 提示词详情 |
+| POST | `/api/service/prompts` | 🟡 服务 | 创建草稿 |
+| PATCH | `/api/service/prompts/{key}` | 🟡 服务 | 更新草稿 |
+| DELETE | `/api/service/prompts/{key}` | 🟡 服务 | 删除草稿 |
+
+---
+
+## 错误响应
+
+```json
+{
+  "detail": "错误信息"
+}
+```
+
+| HTTP | 说明 |
+|------|------|
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 500 | 服务器错误 |
+
+---
+
+## 统计
+
+| 服务 | API数量 |
+|------|---------|
+| Auth | 6 |
+| Blog | 12 |
+| Canvas | 5 |
+| Prompt | 7 |
+| **总计** | **30** |
--- a/api/prompt-api-specification.md
+++ b/api/prompt-api-specification.md
@@ -0,0 +1,339 @@
+# 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 | 自动化 |
+| 通用 | 全局搜索 | 用户体验 |
+
+---
+
+## 十、错误处理
+
+```json
+{
+  "detail": "错误信息",
+  "code": "ERROR_CODE"
+}
+```
+
+| HTTP | 说明 |
+|------|------|
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 429 | 请求过于频繁 |
+| 500 | 服务器错误 |
+
+---
+
+## 十一、速率限制
+
+| API 类型 | 限制 |
+|----------|------|
+| 公开 API (GET) | 100次/分钟 |
+| 公开 API (POST) | 10次/分钟 |
+| 用户 API | 60次/分钟 |
+| 服务 API | 30次/分钟 |
+| 文件上传 | 5次/分钟 |
+
+---
+
+## 十二、数据库扩展
+
+```sql
+-- 用户收藏表
+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
+);
+```