ephron-ren-prd/requirements/feature-requirements.md

ephron.ren 功能需求文档

版本: v1.0 更新日期: 2026-05-05 状态: 待评审

---

概述

本文档记录 ephron.ren 建议新增的功能需求，按优先级和模块分类。

---

一、Home 服务

现状: 无API实现，仅有页面路由

1.1 个人资料 API

优先级: P0

方法	路径	权限	说明
GET	/api/v1/profile	🟢 公开	获取个人资料

响应示例:

{
  "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	🟢 公开	获取技能列表

响应示例:

{
  "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 新增表

-- 用户收藏表
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 文档