我的知识库

Appearance

思路 ​

接口适配的临时性已确认，目标是产出一份给后端 Cursor 用的开发文档。覆盖前端 mock 用到、但 API接口文档.md 里没有的接口，按优先级分批，方便后端按节奏开发。

文档归属与命名 ​

新建：docs/后端待开发接口文档.md

  • 跟 API接口文档.md 风格一致（章节/表格/示例 JSON）
  • 文件级别独立，你直接复制粘贴到后端项目仓库即可
  • 在文档头部写一句"开发完成后，对应章节同步合并到 API接口文档.md，并删除本文档对应小节"

文档结构 ​

P0 必须（前端 mock 在用，缺了就坏主流程） ​

来自 pages/post/detail.vue、pages/publish/publish.vue、pages/profile/my-posts.vue、pages/profile/profile.vue、pages/discover/discover.vue、pages/index/index.vue 的实际调用 + Mock 数据结构。

8. Post 动态模块（基础路径 /api/v1/posts） ​

数据结构参考 docs/Mock数据规范与API定义.md §2 已经定义清楚的 Post，直接复用：

typescript
interface Post {
  id, content, images[], video,
  author: User, topics: Topic[], location: Location|null,
  likeCount, commentCount, viewCount, shareCount, favoriteCount,
  isLiked, isFavorited,
  privacy: 'public'|'friends'|'private',
  status: 'published'|'draft'|'deleted',
  createdAt, updatedAt, category
}

接口（每个都要写完整规约）：

  • POST /api/v1/posts — 发布动态
  • GET /api/v1/posts/{postId} — 详情
  • DELETE /api/v1/posts/{postId} — 删除
  • PUT /api/v1/posts/{postId} — 编辑
  • GET /api/v1/posts/recommend — 推荐流（首页用）
  • GET /api/v1/posts/my — 我的动态
  • GET /api/v1/posts/user/{userId} — 用户动态（个人主页用）
  • POST /api/v1/posts/{postId}/like / DELETE same — 点赞/取消
  • POST /api/v1/posts/{postId}/favorite / DELETE same — 收藏
  • POST /api/v1/posts/{postId}/view — 浏览埋点（自增 viewCount）
  • POST /api/v1/posts/{postId}/share — 分享计数

9. Comment 评论模块（基础路径 /api/v1/posts/{postId}/comments） ​

参考 utils/mock-comments.js，支持 1 级回复（不嵌套多层）：

typescript
interface Comment {
  id, postId, content, author: User,
  likeCount, isLiked, createdAt,
  replies: Reply[]
}
interface Reply {
  id, content, author: User, replyTo:{id,nickname}, createdAt
}

接口：

  • GET /api/v1/posts/{postId}/comments — 评论列表（分页）
  • POST /api/v1/posts/{postId}/comments — 发评论
  • POST /api/v1/posts/{postId}/comments/{commentId}/replies — 回复
  • DELETE /api/v1/posts/{postId}/comments/{commentId} — 删评论
  • POST /api/v1/posts/{postId}/comments/{commentId}/like / DELETE same — 评论点赞

10. Topic 话题模块（基础路径 /api/v1/topics） ​

参考 utils/mock-topics.js：

typescript
interface Topic {
  id, name, category, postCount, heat,
  isHot, description, cover?
}

接口：

  • GET /api/v1/topics/hot — 热门话题
  • GET /api/v1/topics/recommend — 推荐话题
  • GET /api/v1/topics/search?keyword — 搜索（发布动态时选话题用）
  • GET /api/v1/topics/{topicId} — 详情
  • GET /api/v1/topics/{topicId}/posts — 话题下的动态

11. 文件上传模块（基础路径 /api/v1/upload） ​

参考 api/modules/common.js，目前发布动态、活动封面、聊天图片都需要：

  • POST /api/v1/upload/image — 单图（multipart/form-data）
  • POST /api/v1/upload/images — 多图
  • POST /api/v1/upload/video — 视频
  • 返回统一格式 { url, size, mimeType, width?, height?, duration? }

12. 认证补充 ​

P1 应该有（业务完整性，前端有占位但当前页面没强依赖） ​

13. 活动补充（/api/activity/* 增量） ​

  • POST /api/activity/{activityId}/favorite / DELETE same — 收藏（mockDiscoverApi 提示有这个数据形态）
  • GET /api/activity/my/joined — 我参加的活动（个人中心用）
  • GET /api/activity/my/favorites — 我收藏的活动
  • GET /api/activity/user/{userId} — 用户创建的活动（看别人主页用）
  • POST /api/activity/{activityId}/share — 分享计数
  • POST /api/activity/{activityId}/report — 举报
  • PUT /api/activity/update — 更新（创建者）
  • DELETE /api/activity/{activityId} — 删除（创建者）
  • 评价子模块 /api/activity/{activityId}/reviews/*：列表/发表/删除/点赞

14. 用户补充（/api/v1/users/* 增量） ​

  • POST /api/v1/users/{userId}/block / DELETE same — 拉黑
  • POST /api/v1/users/{userId}/report — 举报
  • GET /api/v1/users/recommend — 推荐用户（utils/mock-discover.js mockRecommendUsers）
  • PUT /api/v1/users/{userId}/location — 更新位置
  • GET /api/v1/users/{userId}/stats — 用户统计 {postsCount,activitiesCount,followersCount,followingCount}
  • GET/PUT /api/v1/users/preferences — 用户偏好
  • GET/PUT /api/v1/users/privacy — 隐私设置
  • POST /api/v1/users/bind-email — 绑定邮箱
  • POST /api/v1/users/reset-password — 重置密码
  • DELETE /api/v1/users/account — 注销账户

15. 通用模块（/api/v1/common/*） ​

  • GET /api/v1/common/banners?position — 轮播图（utils/mock-discover.js mockBanners）
  • GET /api/v1/common/cities/hot、/cities、/provinces — 地区数据
  • POST /api/v1/common/geocode、/reverse-geocode、/location/search、/location/nearby — 地理服务
  • POST /api/v1/common/feedback — 用户反馈

P2 可延后（依赖 web admin 或低频） ​

16. web admin 配置类（等管理后台项目） ​

  • GET /api/admin/activity/categories — 活动分类管理
  • GET /api/admin/activity/tags — 活动标签管理
  • GET /api/admin/post/tags/{hot,recommend} — 帖子标签
  • GET /api/admin/notices — 系统公告
  • GET /api/admin/help、/faq — 帮助中心、FAQ

17. 统计与运营 ​

  • GET /api/v1/posts/{postId}/stats、/api/activity/{id}/stats — 单条统计
  • POST /api/v1/common/statistics — 用户行为埋点
  • POST /api/v1/common/error-report — 前端错误上报
  • POST /api/v1/common/heartbeat — 心跳

DDD 架构建议（附录 A） ​

针对后端的 DDD 架构，给出聚合根 / 领域事件 / 仓储建议：

具体建议：

  1. 聚合边界：

    • Post 聚合根 ≠ Comment 聚合根（Comment 通过 postId 引用，独立 CRUD）
    • Like/Favorite/View 设计为独立的 Interaction 聚合（高频写，避免锁 Post 主表），通过领域事件回写 Post 的统计字段
    • Topic 独立限界上下文，与 Post 通过 PostTopicRelation 弱关联

  2. 领域事件（Domain Event）：

    • PostPublishedEvent → 触发推荐流刷新、推送给关注者
    • CommentCreatedEvent → 触发通知给动态作者
    • PostLikedEvent → 触发通知 + 用户活跃度统计
    • ActivityCompletedEvent（已存在 Saga）

  3. 仓储（Repository）拆分：

    • PostRepository / CommentRepository / TopicRepository / InteractionRepository 各自独立
    • 推荐用 CQRS：写走聚合根，读走 ReadModel（避免聚合根字段被读场景扭曲）

  4. API 层放置：

    • 所有 P0/P1 接口都放在 interfaces/web/v1/ 下
    • 现有 /api/auth/* 和 /api/activity/* 这种"裸路径"建议后续逐步迁移到 /api/v1/* 命名空间（不在本期，本文档新增的全部统一用 /api/v1/*）

引用 IM 模块（附录 B） ​

docs/IM后端接口需求.md 已经写得很完整，本文档不重复。后端开发时直接读那份。简要列出依赖：

  • POST /api/im/auth/token — 取 WuKongIM token
  • /api/im/friends/* — 好友管理
  • /api/im/conversations/* — 会话管理
  • WuKongIM Server 部署（参考 docs/WuKongIM集成完整方案.md）

每个接口规约的统一模板 ​

每个接口都按这个格式写（跟 API接口文档.md 风格一致）：

### X.Y 接口名称
- URL: METHOD /path
- 认证: 是/否/可选
- 说明: 一句话业务说明
Request Body / Query Parameters: ...（带字段表格 + 校验规则）
Postman 示例: ...
Response: ```json {...}```
注意事项: 业务规则、并发要求、依赖事件

不做的事 ​

后续动作建议（plan 之外） ​

写完文档后，工作流是：

  1. 你直接打开第二个 Cursor 窗口（后端项目），把 docs/后端待开发接口文档.md 复制过去
  2. 后端按 P0 → P1 → P2 顺序开发
  3. 每完成一批接口，前端把 config/env.js 对应的 USE_REAL_POST=true 等开关打开，测真接口
  4. 后端把对应章节同步到他们的 API接口文档.md（或合并回前端这份）

Powered by VitePress

© 2026 skeeter