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/requirements/feature-requirements.md
+++ b/requirements/feature-requirements.md
@@ -0,0 +1,508 @@
+# ephron.ren 功能需求文档
+
+> 版本: v1.0
+> 更新日期: 2026-05-05
+> 状态: 待评审
+
+---
+
+## 概述
+
+本文档记录 ephron.ren 建议新增的功能需求，按优先级和模块分类。
+
+---
+
+## 一、Home 服务
+
+**现状**: 无API实现，仅有页面路由
+
+### 1.1 个人资料 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/profile` | 🟢 公开 | 获取个人资料 |
+
+**响应示例**:
+```json
+{
+  "username": "ephron",
+  "display_name": "Ephron",
+  "bio": "全栈开发者",
+  "avatar_url": "https://cdn.ephron.ren/avatar.jpg",
+  "social": {
+    "github": "https://github.com/ephron",
+    "twitter": "https://twitter.com/ephron"
+  }
+}
+```
+
+**实现建议**: 从数据库或配置文件读取个人资料
+
+---
+
+### 1.2 技能列表 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/skills` | 🟢 公开 | 获取技能列表 |
+
+**响应示例**:
+```json
+{
+  "skills": [
+    {"name": "Python", "level": 90, "category": "后端"},
+    {"name": "React", "level": 85, "category": "前端"}
+  ]
+}
+```
+
+---
+
+### 1.3 项目作品 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/projects` | 🟢 公开 | 项目列表 |
+| GET | `/api/v1/projects/{id}` | 🟢 公开 | 项目详情 |
+
+---
+
+### 1.4 时间线 API
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/timeline` | 🟢 公开 | 经历时间线 |
+
+---
+
+## 二、Auth 服务
+
+**现状**: 已实现基础认证，缺少用户管理API
+
+### 2.1 用户资料 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/users/{username}` | 🟢 公开 | 获取用户公开信息 |
+| GET | `/api/v1/me` | 🔵 用户 | 获取当前用户信息 |
+| PATCH | `/api/v1/me` | 🔵 用户 | 更新个人资料 |
+
+**实现建议**: 
+- 用户公开信息：用户名、头像、简介、注册时间
+- 当前用户信息：包含邮箱、角色等私有信息
+
+---
+
+### 2.2 密码管理 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/me/change-password` | 🔵 用户 | 修改密码 |
+| POST | `/api/v1/auth/forgot-password` | 🟢 公开 | 发送重置邮件 |
+| POST | `/api/v1/auth/reset-password` | 🟢 公开 | 重置密码 |
+
+**实现建议**:
+- 需要集成邮件服务（SMTP）
+- 重置Token有效期24小时
+- 使用安全的密码哈希（bcrypt/argon2）
+
+---
+
+### 2.3 API Key 管理
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| 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 |
+
+**实现建议**:
+- API Key 格式: `sk-xxxxxxxx`
+- 存储时只保存哈希值
+- 支持设置权限范围
+
+---
+
+## 三、Blog 服务
+
+**现状**: 已实现文章CRUD和点赞，缺少搜索、收藏、版本管理
+
+### 3.1 公开文章 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/posts` | 🟢 公开 | 文章列表 |
+| GET | `/api/v1/posts/{slug}` | 🟢 公开 | 文章详情 |
+
+**实现建议**:
+- 列表支持分页、分类筛选
+- 详情包含完整内容和元数据
+
+---
+
+### 3.2 文章搜索 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/posts/search` | 🟢 公开 | 全文搜索 |
+
+**请求参数**:
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| q | string | 搜索关键词 |
+| tag | string | 标签筛选 |
+| sort | string | 排序: newest/popular |
+| page | int | 页码 |
+
+**实现建议**:
+- 使用 SQLite FTS5 全文搜索
+- 返回匹配摘要和高亮
+
+---
+
+### 3.3 文章互动 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/posts/{slug}/view` | 🟢 公开 | 记录阅读 |
+| POST | `/api/v1/posts/{slug}/favorite` | 🔵 用户 | 收藏文章 |
+| DELETE | `/api/v1/posts/{slug}/favorite` | 🔵 用户 | 取消收藏 |
+| GET | `/api/v1/user/favorites` | 🔵 用户 | 收藏列表 |
+| GET | `/api/v1/posts/{slug}/stats` | 🟢 公开 | 文章统计 |
+
+**实现建议**:
+- 阅读统计基于IP去重
+- 收藏需要用户登录
+
+---
+
+### 3.4 图片上传 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/upload/image` | 🔵 用户 | 上传图片 |
+
+**实现建议**:
+- 支持 jpg/png/gif/webp
+- 限制文件大小（5MB）
+- 生成缩略图
+- 存储到 CDN 或本地
+
+---
+
+### 3.5 版本管理 API
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/posts/{slug}/versions` | 🔵 用户 | 版本历史 |
+| POST | `/api/v1/posts/{slug}/rollback/{id}` | 🔵 用户 | 回滚版本 |
+
+---
+
+## 四、Canvas 服务
+
+**现状**: 已实现服务API CRUD，缺少公开API和互动功能
+
+### 4.1 公开画布 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/canvas` | 🟢 公开 | 画布列表 |
+| GET | `/api/v1/canvas/{slug}` | 🟢 公开 | 画布详情 |
+| GET | `/api/v1/canvas/{slug}/raw` | 🟢 公开 | 原始内容 |
+| POST | `/api/v1/canvas/{slug}/view` | 🟢 公开 | 记录浏览 |
+
+---
+
+### 4.2 画布互动 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/canvas/{slug}/like` | 🔵 用户 | 点赞 |
+| DELETE | `/api/v1/canvas/{slug}/like` | 🔵 用户 | 取消点赞 |
+| POST | `/api/v1/canvas/{slug}/favorite` | 🔵 用户 | 收藏 |
+| DELETE | `/api/v1/canvas/{slug}/favorite` | 🔵 用户 | 取消收藏 |
+
+---
+
+### 4.3 画布模板 API
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/templates` | 🟢 公开 | 模板列表 |
+| GET | `/api/v1/templates/{id}` | 🟢 公开 | 模板详情 |
+| POST | `/api/v1/canvas/from-template/{id}` | 🔵 用户 | 从模板创建 |
+
+---
+
+### 4.4 画布分享 API
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/canvas/{slug}/share` | 🔵 用户 | 生成分享链接 |
+| GET | `/api/v1/shared/{code}` | 🟢 公开 | 访问分享内容 |
+
+---
+
+## 五、Prompt 服务
+
+**现状**: 已实现基础CRUD，缺少搜索、互动、批量操作
+
+### 5.1 高级搜索 API
+
+**优先级**: P0
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/prompts/search` | 🟢 公开 | 高级搜索 |
+| GET | `/api/v1/prompts/categories` | 🟢 公开 | 分类列表 |
+| GET | `/api/v1/prompts/tags` | 🟢 公开 | 标签列表 |
+| GET | `/api/v1/prompts/popular` | 🟢 公开 | 热门提示词 |
+
+**实现建议**:
+- 搜索支持全文、分类、标签筛选
+- 返回分面统计（facets）
+
+---
+
+### 5.2 用户互动 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| 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` | 🔵 用户 | 收藏列表 |
+
+---
+
+### 5.3 批量操作 API
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/prompts/batch` | 🟡 服务 | 批量创建 |
+| POST | `/api/v1/prompts/batch-delete` | 🟡 服务 | 批量删除 |
+| GET | `/api/v1/prompts/export` | 🟡 服务 | 导出 |
+| POST | `/api/v1/prompts/import` | 🟡 服务 | 导入 |
+
+---
+
+### 5.4 版本管理 API
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/prompts/{key}/versions` | 🟡 服务 | 版本历史 |
+| GET | `/api/v1/prompts/{key}/versions/{v}` | 🟡 服务 | 特定版本 |
+| POST | `/api/v1/prompts/{key}/rollback/{v}` | 🟡 服务 | 回滚版本 |
+
+---
+
+### 5.5 模板市场 API
+
+**优先级**: P3
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/marketplace` | 🟢 公开 | 市场列表 |
+| GET | `/api/v1/marketplace/{key}` | 🟢 公开 | 模板详情 |
+| POST | `/api/v1/marketplace/{key}/publish` | 🔵 用户 | 发布到市场 |
+| POST | `/api/v1/marketplace/{key}/install` | 🔵 用户 | 安装模板 |
+
+---
+
+## 六、通用功能
+
+### 6.1 文件上传服务
+
+**优先级**: P1
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/upload` | 🔵 用户 | 上传文件 |
+
+**实现建议**:
+- 支持图片、文档
+- 生成唯一文件名
+- 返回 CDN URL
+
+---
+
+### 6.2 通知服务
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/notifications` | 🔵 用户 | 通知列表 |
+| POST | `/api/v1/notifications/{id}/read` | 🔵 用户 | 标记已读 |
+| POST | `/api/v1/notifications/read-all` | 🔵 用户 | 全部已读 |
+
+---
+
+### 6.3 全局搜索
+
+**优先级**: P2
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/search` | 🟢 公开 | 跨服务搜索 |
+
+---
+
+### 6.4 Webhook 服务
+
+**优先级**: P3
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| POST | `/api/v1/webhooks` | 🔵 用户 | 创建 Webhook |
+| GET | `/api/v1/webhooks` | 🔵 用户 | 列出 Webhooks |
+| DELETE | `/api/v1/webhooks/{id}` | 🔵 用户 | 删除 Webhook |
+
+---
+
+## 七、数据库扩展
+
+### 7.1 新增表
+
+```sql
+-- 用户收藏表
+CREATE TABLE user_favorites (
+    id INTEGER PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    resource_type TEXT NOT NULL,  -- post | prompt | canvas
+    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,  -- view | like | use
+    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
+);
+
+-- 通知表
+CREATE TABLE notifications (
+    id INTEGER PRIMARY KEY,
+    user_id TEXT NOT NULL,
+    type TEXT NOT NULL,
+    title TEXT NOT NULL,
+    message TEXT,
+    link TEXT,
+    read BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## 八、实现优先级总览
+
+### P0 - 核心功能（6个）
+
+| 服务 | 功能 | 说明 |
+|------|------|------|
+| Home | 个人资料API | 首页展示 |
+| Auth | 用户资料API | 用户系统基础 |
+| Blog | 公开文章API | 内容展示 |
+| Blog | 文章搜索API | 用户体验 |
+| Canvas | 公开画布API | 服务完整性 |
+| Prompt | 高级搜索API | 用户体验 |
+
+### P1 - 重要功能（12个）
+
+| 服务 | 功能 | 说明 |
+|------|------|------|
+| Auth | 密码管理 | 用户体验 |
+| Auth | API Key | 第三方集成 |
+| Blog | 文章互动 | 用户参与 |
+| Blog | 图片上传 | 内容创作 |
+| Canvas | 画布互动 | 用户参与 |
+| Prompt | 用户互动 | 用户参与 |
+| Prompt | 批量操作 | 管理效率 |
+| 通用 | 文件上传 | 多服务复用 |
+
+### P2 - 增强功能（8个）
+
+| 服务 | 功能 | 说明 |
+|------|------|------|
+| Home | 技能列表 | 首页展示 |
+| Home | 项目作品 | 首页展示 |
+| Blog | 版本管理 | 内容管理 |
+| Canvas | 画布模板 | 用户便利 |
+| Canvas | 画布分享 | 内容传播 |
+| Prompt | 版本管理 | 内容管理 |
+| 通用 | 通知服务 | 用户提醒 |
+| 通用 | 全局搜索 | 用户体验 |
+
+### P3 - 扩展功能（5个）
+
+| 服务 | 功能 | 说明 |
+|------|------|------|
+| Home | 时间线 | 首页展示 |
+| Prompt | 模板市场 | 社区生态 |
+| 通用 | Webhook | 自动化 |
+
+---
+
+## 九、相关文档
+
+- [API 文档](./api-specification.md)