tkmind_go/documentation/docs/guides/plaza/08-development-guide.md

sidebar_position, title, sidebar_label, description

sidebar_position	title	sidebar_label	description
9	开发规范与 Sprint 计划	开发规范	Plaza 开发顺序、编码规范、本地启动方式、Sprint 拆分和出口条件

开发规范与 Sprint 计划

开发顺序原则

每个功能点按以下顺序完成，不跳步：

1. 数据库迁移（plaza_* 表）
2. 后端 repository 层（纯 SQL，无业务逻辑）
3. 后端 service 层（权限校验、状态机、事务）
4. 后端 API 路由（DTO、OpenAPI 更新）
5. 前端 API 封装（ui/plaza/lib/api.ts）
6. 前端页面和组件
7. 自动化测试（单元 + E2E）
8. 审计日志和指标埋点
9. 手工验收

---

本地启动

前置要求

source bin/activate-hermit    # Rust 工具链（现有要求）
node --version                # >= 18
pnpm --version                # >= 8
redis-server --version        # >= 6（新增依赖）

启动顺序

# 1. 后端（现有，不变）
cd ui/h5
node server.mjs

# 2. MindSpace H5（现有，不变）
cd ui/h5
pnpm dev

# 3. Plaza Next.js（新增）
cd ui/plaza
pnpm install
pnpm dev        # 开发模式，port 3001

# 4. 运营后台（新增，可选）
cd ui/ops
pnpm install
pnpm dev        # port 3002

环境变量

ui/plaza/.env.local：

NEXT_PUBLIC_API_BASE=http://localhost:18006
NEXT_PUBLIC_PLAZA_BASE=http://localhost:3001

ui/ops/.env.local：

VITE_API_BASE=http://localhost:18006

Nginx 本地开发替代方案

开发时不需要 Nginx，三个进程各自占用端口，直接访问：

• http://localhost:8080 → MindSpace H5
• http://localhost:3001 → Plaza
• http://localhost:3002 → 运营后台
• http://localhost:18006 → 后端 API

---

编码规范

后端

- 新模块放在 ui/h5/plaza-*.mjs，与 mindspace-publications.mjs 并列，由 server.mjs 挂载 /api/plaza/v1/*
- 路由文件只做：解析请求、鉴权、调用 service、映射响应
- service 文件只做：业务逻辑、事务、权限校验
- repository 文件只做：SQL，不含业务判断
- plaza_posts 快照字段在 service 层写入，repository 层不负责查 h5_users 表
- 错误返回统一格式：{ error: { code: 'XXX', message: '...' } }
- 运营写操作写入 ops_audit_log；用户写操作写入 h5_mindspace_audit_logs（如需要）

前端（Next.js）

- 所有数据获取在 Server Component 中完成，不在 useEffect 里 fetch
- 客户端交互（点赞、评论）使用 SWR mutation，乐观更新
- 图片全部用 next/image，不用 <img>
- 所有 API 调用封装在 lib/api.ts，组件不直接调用 fetch
- 类型定义放在 types/plaza.ts，与后端 DTO 保持一致
- 不引入 Redux / Zustand，组件状态用 useState，跨组件用 React Context

通用

- 所有 SQL 迁移：更新 `ui/h5/schema.sql` + `db.mjs` 幂等 ALTER
- 不在迁移文件中写业务数据（除 plaza_categories 初始数据）
- 新功能分支命名：feature/plaza-{功能名}
- commit 消息格式：feat(plaza): 描述 / fix(plaza): 描述
- PR 必须更新对应文档

---

Sprint 计划

Sprint 1：数据基础 + 发布到广场

目标：用户能将 MindSpace 页面发布到广场，广场首页能展示。

后端任务：

• 创建 plaza_categories 表并写入初始 8 个分类
• 创建 plaza_posts 表（含索引）
• 后端 POST /api/plaza/v1/posts（发布到广场）
• 后端 GET /api/plaza/v1/feed（热门/最新列表）
• 后端 GET /api/plaza/v1/posts/:id（帖子详情）
• 后端 GET /api/plaza/v1/categories（分类列表）
• publication 下线时自动 hidden 对应 plaza_posts
• 初始化 Redis 连接，view_count 计数接入（Sprint 3 已实现，Sprint 1 出口不阻塞）
• OpenAPI 同步（S1-B10，见 10-implementation-status P2）

前端任务：

• 初始化 ui/plaza/ Next.js 项目
• 实现 /plaza 首页（SSR，卡片瀑布流）
• 实现 /plaza/cat/:slug 分类页（SSR + fetch 缓存）
• 实现 /plaza/p/:id 帖子详情页（含 iframe embed）
• 实现 PostCard 组件（含所有状态）
• MindSpace 页面详情新增「发布到广场」按钮
• generateMetadata 接入所有 SSR 页面
• MindSpace 发布对话框：封面 URL + 允许评论开关（见 08 流程图）

审核策略（Sprint 1）：

• 帖子创建后默认 pending_review，不出现在公开 Feed。
• 开发环境：PLAZA_AUTO_APPROVE=true 时，内容扫描通过后自动 published（便于本地 E2E）。
• 生产环境：Sprint 1 在现有 /admin 增加最小审核入口；Sprint 5 再上线完整 ui/ops/。

出口条件：

• 用户能完成「MindSpace 发布页面 → 发布到广场 → 审核通过 → 广场首页出现」完整流程
• 游客可以浏览广场，curl 能拿到完整 HTML（验证 SSR 正常）
• 下线 publication 后，对应广场帖子消失

---

Sprint 2：互动系统

目标：点赞、收藏、评论、关注全部可用。

后端任务：

• 创建 plaza_reactions、plaza_comments、plaza_follows 表
• POST/DELETE /api/plaza/v1/posts/:id/reactions
• GET/POST/DELETE /api/plaza/v1/posts/:id/comments
• POST/DELETE /api/plaza/v1/comments/:id/reactions
• POST/DELETE /api/plaza/v1/users/:slug/follow
• GET /api/plaza/v1/users/:slug（用户主页数据）
• Redis 点赞计数 + 定时同步任务（仍直写 MySQL，见 P3）
• users 表新增 plaza_* 计数字段

前端任务：

• PostActions 组件（点赞/收藏/分享，含登录引导浮层）
• CommentSection 组件（列表 + 输入框 + 二级回复展示）
• /u/:slug 用户主页（SSR）
• 关注按钮组件（含乐观更新）
• 数字格式化（1.2k / 1.2万）
• 分享时调用 share reaction 写入 share_count

出口条件：

• 点赞后 hot_score 在下一次计算周期后反映在热门列表
• 二级评论正常展示，不允许三级嵌套
• 关注后用户主页粉丝数 +1（乐观更新）

---

Sprint 3：热度算法 + 用户主页

目标：热度排序正常运转，用户主页作品集完整。

后端任务：

• 创建 plaza_algorithm_config 表
• 热度计算定时任务（每 10 分钟，覆盖 48 小时内帖子）
• Feed 缓存接入（Redis TTL 5 分钟）
• GET /api/plaza/v1/users/:slug/posts（分页）
• 防刷：IP 维度浏览去重（Redis SET NX）
• 广场互动数据异步回写 publications

前端任务：

• UserPostGrid 组件（用户主页帖子网格）
• FeedTabs 「热门/最新」切换
• 无限滚动加载（IntersectionObserver）
• CategoryNav 分类导航
• 移动端底部导航

出口条件：

• 广场首页热门列表按 hot_score 正确排序
• 同一 IP 对同一帖子 24 小时内只计 1 次浏览
• 移动端 2 列布局正常

---

Sprint 4：SEO 完善 + 水印入口

目标：所有页面可被搜索引擎收录，病毒增长入口上线。

后端任务：

• 动态 OG 图生成（无封面图时兜底）
• Sitemap 接口（/sitemap.xml）
• 新帖发布后主动推送百度索引
• UTM 参数追踪接口（记录广场带来的注册转化）

前端任务：

• 所有 SSR 页面接入完整 meta（JSON-LD：帖子/用户/首页/分类）
• robots.txt 正确配置
• Footer 水印「用 MindSpace 制作 →」（带 UTM 参数）
• 社交分享功能（复制链接 + 生成分享图 + share_count）
• 性能优化：图片懒加载、骨架屏（PostGridSkeleton + loading.tsx）
• 微信 JS-SDK 内分享（P3）

出口条件：

• Google Search Console 提交 Sitemap 无报错
• 微信内分享帖子能显示封面图和标题
• 广场注册转化率可追踪（UTM 数据进入运营看板）

---

Sprint 5：运营后台

目标：运营人员可以审核内容、管理精选。

后端任务：

• 创建 plaza_reports、plaza_featured、ops_audit_log 表
• 运营角色中间件（ops_role 校验）
• POST /api/ops/v1/review/posts/:id（审核）
• POST /api/plaza/v1/posts/:id/reports（帖子举报）
• POST /api/plaza/v1/comments/:id/reports（评论举报）
• POST /api/ops/v1/featured（设置精选，含 category_top）
• GET /api/ops/v1/analytics/overview
• POST /api/ops/v1/review/batch（批量审核）

前端任务：

• 初始化 ui/ops/ Vite 项目
• 审核队列页面（待审/已通过/已拒绝 Tab + 批量通过）
• 举报处理页面
• 精选管理页面
• 数据概览看板（图表，当前为列表指标）
• Plaza 帖子页举报入口

出口条件：

• 审核操作全部写入 ops_audit_log
• 精选帖子在广场首页正确展示
• Nginx /ops 路由只允许内网访问

---

每个 Sprint 的通用出口条件

• 数据库迁移可在空库和现有生产库执行（schema.sql + db.mjs ALTER）
• 后端 API 与 OpenAPI 文档同步（just check-h5-openapi-schema）
• 权限拒绝路径有测试（跨用户越权返回 404/403）
• 前端有加载、空、错误三种状态（主要页面）
• 移动端主要流程验收通过（手工）
• 无 TypeScript 编译错误（ui/plaza / ui/ops build）
• cargo clippy 无警告（Plaza 无 Rust 改动时 N/A）

详细差距见 实现进度。

---

发布到广场的用户体验流程图

MindSpace 页面详情
        │
        ▼
  [发布到广场] 按钮
        │
        ▼
  选择分类（必选）
  输入标签（可选，最多 5 个）
  确认封面图（可换）
  是否允许评论（默认开）
        │
        ▼
  POST /api/plaza/v1/posts
        │
     ┌──┴──┐
     │     │
   成功    失败
     │     │
     ▼     ▼
  帖子进入  提示错误原因
  待审状态  （publication 未上线 /
     │      已发布过 / 无权限）
     ▼
  审核通过（自动或人工）
     │
     ▼
  广场公开展示
     │
     ▼
  页面详情显示「广场链接」和互动数