# 活动留言板（Activity MessageBoard）后端接口文档
> 本文档基于前端组件 `frontend/pages/support-activity/components/MessageBoard.vue` 反推后端接口契约，作为留言板模块的接口设计依据与开发指南。
---
## 1. 背景与现状
### 1.1 前端组件
`MessageBoard.vue` 是一个**纯展示组件**（presentational component），通过 `props.messages` 接收留言列表，每条留言渲染为一条气泡，组件本身不直接发请求。
调用关系：
```
support-activity/index.vue
├── // 仅展示
└── handleSendMessage(text) // 仅本地 messageList.push(...) + toast
```
当前 `messageList` 在 `index.vue` 中是**写死的 mock 数据**，并未对接任何后端接口：
```js
// 留言板 mock 数据（index.vue 中）
const messageList = ref([
{ id: 1, user: "小星星", avatar: "", content: "生日快乐！永远支持你~", time: "刚刚", isSelf: false },
// ...
]);
```
### 1.2 前端期望的字段（来自组件 props 形态）
| 字段 | 类型 | 说明 | 备注 |
| --------- | -------- | ----------------------------- | --------------------------------------------- |
| `id` | number | 留言唯一 ID | 当前 mock 用 `Date.now()` |
| `user` | string | 留言人昵称 | 当前用户昵称（来自 `fan_profiles.nickname`） |
| `avatar` | string | 留言人头像 URL | 当前 mock 为空字符串 |
| `content` | string | 留言正文 | 必填 |
| `time` | string | 留言时间 | 当前 mock 是"刚刚"/"5分钟前"等相对时间字符串 |
| `isSelf` | boolean | 是否当前登录用户所发 | 当前 mock 由前端标记 |
> ⚠️ 后端**不应直接复用 mock 字段语义**：`time` 应返回毫秒时间戳或 ISO 字符串，由前端格式化；`isSelf` 应由前端根据当前用户 ID 自行判断（避免后端泄露会话状态）。
### 1.3 后端现状
经排查（grep 全量 `message|留言`），当前 **backend 中没有留言相关接口**：
- `services/activityService/` 没有 `Message` 类方法
- 数据库迁移脚本中没有 `activity_messages` 或 `messages` 表（`migrate_add_comments_v1.sql` 是给 laser_card 加的 `comments` 列，不是新表）
- `pkg/errors` 中也没有 `ErrMessageNotFound` 等业务错误
本次为**全新模块**设计。
---
## 2. 设计目标
1. 支持粉丝在应援活动页面对活动发表祝福留言（每用户每活动有频率/上限限制）。
2. 支持活动详情页气泡墙展示历史留言（最新在上）。
3. 与现有活动模块同源（路由 `activities/{id}/...`），共享 `auth + activity 校验`。
4. 兼容现有前端组件的 props 契约，前端只需把 mock 替换为接口数据源。
5. 预留轮询扩展（`since_timestamp` / `since_id`）以便后续做实时弹幕。
---
## 3. 数据库设计
新增表 `activity_messages`，**主键 bigserial**，自增序列起始 10000（按 `CLAUDE.md` 序列规范）。
```sql
-- ============================================================
-- 活动留言表
-- ============================================================
CREATE TABLE IF NOT EXISTS public.activity_messages (
id BIGSERIAL PRIMARY KEY,
activity_id BIGINT NOT NULL,
user_id BIGINT NOT NULL,
star_id BIGINT NOT NULL,
content VARCHAR(500) NOT NULL,
status SMALLINT NOT NULL DEFAULT 0, -- 0=正常 1=隐藏 2=已删除
created_at BIGINT NOT NULL,
updated_at BIGINT NOT NULL,
deleted_at BIGINT,
CONSTRAINT fk_activity_messages_activity
FOREIGN KEY (activity_id) REFERENCES public.activities(id) ON DELETE CASCADE,
CONSTRAINT fk_activity_messages_user
FOREIGN KEY (user_id) REFERENCES public.users(id),
CONSTRAINT fk_activity_messages_star
FOREIGN KEY (star_id) REFERENCES public.stars(star_id)
);
COMMENT ON TABLE public.activity_messages IS '活动留言表。粉丝在应援活动页面的祝福留言，用于气泡墙展示';
COMMENT ON COLUMN public.activity_messages.id IS '主键，自增';
COMMENT ON COLUMN public.activity_messages.activity_id IS 'FK -> activities.id，所属活动';
COMMENT ON COLUMN public.activity_messages.user_id IS '留言用户 ID';
COMMENT ON COLUMN public.activity_messages.star_id IS '所属明星/星球 ID，活动冗余字段便于按星球维度查询';
COMMENT ON COLUMN public.activity_messages.content IS '留言正文，长度 1-500';
COMMENT ON COLUMN public.activity_messages.status IS '状态：0=正常 | 1=隐藏（违规被审核屏蔽）| 2=已删除（用户/管理删除）';
COMMENT ON COLUMN public.activity_messages.created_at IS '留言时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_messages.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_messages.deleted_at IS '软删除时间，NULL 表示未删除';
-- 序列起始值留给测试数据硬编码 ID 用
CREATE SEQUENCE IF NOT EXISTS activity_messages_id_seq START WITH 10000;
-- 索引：活动维度按时间倒序拉取是热路径
CREATE INDEX IF NOT EXISTS idx_activity_messages_activity_created
ON public.activity_messages (activity_id, created_at DESC, id DESC)
WHERE deleted_at IS NULL;
-- 索引：用户维度查询某用户的所有留言
CREATE INDEX IF NOT EXISTS idx_activity_messages_user_created
ON public.activity_messages (user_id, created_at DESC)
WHERE deleted_at IS NULL;
-- 索引：用于实时增量拉取（since_timestamp + since_id 翻页）
CREATE INDEX IF NOT EXISTS idx_activity_messages_activity_incr
ON public.activity_messages (activity_id, id DESC)
WHERE deleted_at IS NULL;
```
> **为什么 `WHERE deleted_at IS NULL`？** 留言是只追加、软删除的写入场景，使用部分索引（partial index）能让正常状态的数据索引更紧凑，热路径扫描更快。
### 3.1 与已有表的关系
- `activity_id` → `activities.id`：活动被删除时级联清理留言（`ON DELETE CASCADE`）。
- `user_id` → `users.id`：硬依赖，用户被硬删时由应用层兜底（软删用户场景下留言仍可保留，展示时昵称取自 join 后的 fan_profiles/users）。
- `star_id` → `stars.star_id`：冗余字段，便于按星球做运营统计（如"某星球 24h 留言量"）。
---
## 4. Proto 定义
新增文件 `backend/proto/activity/activity_messages.proto`（追加到现有 `backend/proto/activity/` 下，复用 `ActivityService` 服务）：
```protobuf
syntax = "proto3";
package com.topfans.activity;
option go_package = "github.com/topfans/backend/pkg/proto/activity";
option java_package = "com.topfans.activity.proto";
// ============== 留言相关 RPC ==============
service ActivityService {
// ... 现有 RPC ...
// 列出活动留言（历史/首次加载）
rpc ListActivityMessages(ListActivityMessagesRequest) returns (ListActivityMessagesResponse);
// 发送一条留言
rpc CreateActivityMessage(CreateActivityMessageRequest) returns (CreateActivityMessageResponse);
// 增量获取最新留言（轮询用，与 GetLatestContributions 同样模式）
rpc GetLatestActivityMessages(GetLatestActivityMessagesRequest) returns (GetLatestActivityMessagesResponse);
}
// 单条留言
message ActivityMessage {
int64 id = 1;
int64 activity_id = 2;
int64 user_id = 3;
int64 star_id = 4;
string nickname = 5; // 冗余带出，减少 join
string avatar_url = 6; // 冗余带出
string content = 7;
int64 created_at = 8;
}
// 列出活动留言
message ListActivityMessagesRequest {
int64 activity_id = 1;
int32 page = 2; // 默认 1
int32 page_size = 3; // 默认 20，最大 50
}
message ListActivityMessagesResponse {
BaseResponse base = 1;
repeated ActivityMessage messages = 2;
int32 page = 3;
int32 page_size = 4;
int32 total = 5;
}
// 发送留言
message CreateActivityMessageRequest {
int64 activity_id = 1;
int64 user_id = 2; // 从 JWT 解析，gateway 注入
int64 star_id = 3;
string content = 4;
}
message CreateActivityMessageResponse {
BaseResponse base = 1;
ActivityMessage message = 2;
}
// 增量获取最新留言
message GetLatestActivityMessagesRequest {
int64 activity_id = 1;
int64 since_timestamp = 2; // 自该时间戳之后的新记录（毫秒）
int64 since_id = 3; // 配合 since_timestamp 在同毫秒内二次排序
int32 limit = 4; // 默认 20，最大 50
}
message GetLatestActivityMessagesResponse {
BaseResponse base = 1;
repeated ActivityMessage messages = 2;
}
```
> **生成命令**：项目根目录执行 `make proto` 或参考 `backend/Proto编译完成总结.md`。生成后会产生 `activity_messages.pb.go`，注册到 `ActivityServiceHandler` 接口。
---
## 5. HTTP 接口设计
### 5.1 通用约定
- **Base URL**：`https://{host}/api/v1`
- **认证**：所有接口必须带 `Authorization: Bearer `（JWT），由 `middleware.AuthMiddleware()` 注入 `user_id` / `star_id`。
- **统一响应结构**（沿用 `gateway/pkg/response.Response`）：
```json
{
"code": 0,
"message": "ok",
"data": { ... }
}
```
- **错误码**：使用 `pkg/errors` 中的 gRPC code 映射（`codes.OK=0`、`InvalidArgument=3`、`NotFound=5`、`PermissionDenied=7`、`ResourceExhausted=8`、`Internal=13`、`Unauthenticated=16`）。
- **时间字段**：统一返回**毫秒时间戳**（`created_at`），前端负责格式化。
- **驼峰/下划线**：HTTP 响应使用 **snake_case**（与现有 `GetLatestContributions` 保持一致），由 `convert*Response` 函数在 controller 层做转换。
### 5.2 接口清单
| # | 方法 | 路径 | 说明 | 鉴权 |
| --- | ---- | ----------------------------------------------- | ------------ | ---- |
| 1 | GET | `/api/v1/activities/{activity_id}/messages` | 列出活动留言 | 需要 |
| 2 | POST | `/api/v1/activities/{activity_id}/messages` | 发送一条留言 | 需要 |
| 3 | GET | `/api/v1/activities/{activity_id}/messages/latest` | 增量拉取最新留言 | 需要 |
> 三个接口都登记到 `gateway/controller/activity_controller.go` 的 Swagger 注解上，`router.go` 的 `activities` 组内注册。
---
### 5.3 接口 1：列出活动留言
**适用场景**：用户进入活动详情页首次加载 / 下拉刷新（替代当前 `messageList` mock）。
```
GET /api/v1/activities/{activity_id}/messages?page=1&page_size=20
```
**Path 参数**
| 名称 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | -------- |
| `activity_id` | int64 | 是 | 活动 ID |
**Query 参数**
| 名称 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---- | ---- | ---- | -------------------------- |
| `page` | int | 否 | 1 | 页码，从 1 开始 |
| `page_size` | int | 否 | 20 | 每页条数，最大 50 |
**响应示例**
```json
{
"code": 0,
"message": "ok",
"data": {
"messages": [
{
"id": 10086,
"activity_id": 42,
"user_id": 1001,
"star_id": 87,
"nickname": "小星星",
"avatar_url": "https://oss.example.com/avatars/1001.png",
"content": "生日快乐！永远支持你~",
"created_at": 1750492800000
},
{
"id": 10085,
"activity_id": 42,
"user_id": 1002,
"star_id": 87,
"nickname": "月光宝盒",
"avatar_url": "",
"content": "星光不问赶路人~",
"created_at": 1750492700000
}
],
"page": 1,
"page_size": 20,
"total": 2
}
}
```
**错误码**
| code | HTTP | message | 说明 |
| ---- | ---- | ------------------------ | ----------------------------- |
| 5 | 404 | `活动不存在` | activity_id 无效 |
| 5 | 404 | `活动不存在` | 活动已结束超过 30 天 |
| 16 | 401 | `未授权，请先登录` | token 缺失 / 失效 |
---
### 5.4 接口 2：发送一条留言
**适用场景**：用户在 `MessageInput` 输入文本后点击发送箭头（当前 `index.vue` 的 `handleSendMessage` 调用点）。
```
POST /api/v1/activities/{activity_id}/messages
```
**请求头**：`Content-Type: application/json`
**Path 参数**
| 名称 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | -------- |
| `activity_id` | int64 | 是 | 活动 ID |
**Body**
```json
{
"content": "永远支持你！生日快乐 🎂"
}
```
| 字段 | 类型 | 必填 | 限制 |
| --------- | ------ | ---- | --------------------------------- |
| `content` | string | 是 | 长度 1-500；去前后空格后非空 |
**响应示例（成功）**
```json
{
"code": 0,
"message": "ok",
"data": {
"message": {
"id": 10087,
"activity_id": 42,
"user_id": 2001,
"star_id": 87,
"nickname": "爱战战",
"avatar_url": "https://oss.example.com/avatars/2001.png",
"content": "永远支持你！生日快乐 🎂",
"created_at": 1750492900000
}
}
}
```
**业务规则校验**
| 校验项 | 失败 code | message |
| ----------------------- | --------- | -------------------------------- |
| 活动状态非 active | 7 | `活动未开始` / `活动已结束` |
| `content` 长度不合法 | 3 | `留言内容长度需在 1-500 字之间` |
| `content` 含敏感词 | 7 | `留言包含不当内容，请修改` |
| 单用户单活动 1 分钟内 > 5 条 | 8 | `留言太频繁，请稍后再试` |
| 单用户单活动累计 > 100 条 | 8 | `当前活动留言已达上限` |
> 上限和频控值通过配置项注入（参考 `notificationService/configs/config.yaml` 的模式），避免硬编码。
**错误码**
| code | HTTP | message | 说明 |
| ---- | ---- | ------------------ | -------------------------- |
| 3 | 400 | `请求参数错误` | JSON 解析失败 / 字段缺失 |
| 5 | 404 | `活动不存在` | activity_id 无效 |
| 7 | 403 | `活动已结束` | 状态非 active |
| 8 | 429 | `留言太频繁` | 频控触发 |
| 16 | 401 | `未授权` | token 失效 |
---
### 5.5 接口 3：增量获取最新留言（轮询用）
**适用场景**：前端使用 `setInterval` 轮询新留言，实现"气泡墙实时滚动"效果。对标 `GetLatestContributions` 接口模式。
```
GET /api/v1/activities/{activity_id}/messages/latest?since_timestamp=1750492800000&since_id=10086&limit=20
```
**Path 参数**
| 名称 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | -------- |
| `activity_id` | int64 | 是 | 活动 ID |
**Query 参数**
| 名称 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | ------ | ---- | ---- | ------------------------------------- |
| `since_timestamp` | int64 | 否 | 0 | 毫秒时间戳，返回严格大于该值的新留言 |
| `since_id` | int64 | 否 | 0 | 同毫秒内按 id 二次排序 |
| `limit` | int | 否 | 20 | 最多返回多少条，最大 50 |
> 前端轮询时可复用 `frontend/pages/support-activity/composables/useContributionPolling.js` 的 `latestTimestamp` / `latestId` 游标模式。
**响应示例**
```json
{
"code": 0,
"message": "ok",
"data": {
"messages": [
{
"id": 10087,
"activity_id": 42,
"user_id": 2001,
"star_id": 87,
"nickname": "爱战战",
"avatar_url": "https://oss.example.com/avatars/2001.png",
"content": "永远支持你！生日快乐 🎂",
"created_at": 1750492900000
}
]
}
}
```
无新数据时 `data.messages` 为空数组（不返回 404，避免轮询噪声）。
---
## 6. 错误码扩展
新增到 `backend/pkg/errors/errors.go`：
```go
// 活动留言相关错误
var (
ErrActivityMessageNotFound = errors.New("活动留言不存在")
ErrActivityMessageTooFrequent = errors.New("留言太频繁，请稍后再试")
ErrActivityMessageLimitReached = errors.New("当前活动留言已达上限")
ErrActivityMessageContentEmpty = errors.New("留言内容不能为空")
ErrActivityMessageContentTooLong = errors.New("留言内容过长，最多500字")
ErrActivityMessageContentInvalid = errors.New("留言内容包含不当内容")
ErrActivityMessageActivityInactive = errors.New("活动不在进行中")
)
```
并在 `ToGRPCCode` 函数中追加映射：
| error | gRPC code |
| ---------------------------------- | -------------------- |
| `ErrActivityMessageNotFound` | `NotFound (5)` |
| `ErrActivityMessageTooFrequent` | `ResourceExhausted (8)` |
| `ErrActivityMessageLimitReached` | `ResourceExhausted (8)` |
| `ErrActivityMessageContentEmpty` | `InvalidArgument (3)` |
| `ErrActivityMessageContentTooLong` | `InvalidArgument (3)` |
| `ErrActivityMessageContentInvalid` | `PermissionDenied (7)` |
| `ErrActivityMessageActivityInactive` | `PermissionDenied (7)` |
并把中文错误提示加到 `gateway/pkg/response/response.go` 的 `errorMap`：
```go
"活动留言不存在": "活动留言不存在",
"留言太频繁": "留言太频繁，请稍后再试",
"留言内容不能为空": "留言内容不能为空",
"留言内容过长": "留言内容过长，最多500字",
"留言内容包含不当内容": "留言内容包含不当内容，请修改",
"活动不在进行中": "活动未开始或已结束",
```
---
## 7. 分层实现（按 CLAUDE.md 接口开发规范）
```
HTTP 请求 (Gin)
│
▼
gateway/controller/activity_controller.go ← 新增 3 个 handler + Swagger 注解
│ - ListActivityMessages
│ - CreateActivityMessage
│ - GetLatestActivityMessages
│ - convertActivityMessage* 响应转换函数
│
│ Dubbo / gRPC (Triple)
▼
services/activityService/provider/activity_provider.go ← 3 个 RPC 入口
│
▼
services/activityService/service/activity_service.go ← 业务编排（鉴权/频控/事务）
│
▼
services/activityService/repository/activity_repository.go ← SQL 拼装（不写业务逻辑）
│
▼
PostgreSQL (activity_messages 表)
```
### 7.1 待新增 / 修改文件清单
| 类型 | 文件 | 说明 |
| ---- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 新增 | `backend/scripts/migrations/migrate_create_activity_messages_table.sql` | 建表 + 索引 + 注释 |
| 新增 | `backend/proto/activity/activity_messages.proto` | proto 定义（追加 RPC + message） |
| 新增 | `backend/services/activityService/repository/activity_messages_repository.go` | 仓储层，封装 SQL 操作 |
| 修改 | `backend/services/activityService/repository/activity_repository.go` | 注册新的仓储接口（可选合并到同一文件） |
| 修改 | `backend/services/activityService/service/activity_service.go` | 新增 3 个业务方法 + 接口签名 |
| 修改 | `backend/services/activityService/provider/activity_provider.go` | 新增 3 个 RPC 入口 + 日志 |
| 修改 | `backend/gateway/controller/activity_controller.go` | 新增 3 个 HTTP handler + 转换函数 + Swagger 注解 |
| 修改 | `backend/gateway/router/router.go` | 注册 3 条路由到 `activities` 组 |
| 修改 | `backend/pkg/errors/errors.go` | 新增 7 个错误变量 + ToGRPCCode 映射 |
| 修改 | `backend/gateway/pkg/response/response.go` | 新增 6 条中文错误映射 |
| 修改 | `backend/services/activityService/configs/config.yaml` | 新增 `message_rate_limit_per_min: 5` 等频控配置 |
| 修改 | `frontend/utils/api.js` | 新增 `listActivityMessagesApi`、`createActivityMessageApi`、`getLatestActivityMessagesApi` 三个 API 函数 |
| 修改 | `frontend/pages/support-activity/index.vue` | 把 `messageList` mock 替换成接口数据源，`handleSendMessage` 改为调用 `createActivityMessageApi` |
| 修改 | `frontend/pages/support-activity/components/MessageBoard.vue` | 字段映射：`time` → 用 `created_at` 格式化；`isSelf` 由 `user_id === currentUser.id` 计算 |
### 7.2 Service 层业务逻辑要点
```go
// CreateActivityMessage 节选伪代码
func (s *activityService) CreateActivityMessage(ctx context.Context, req *pb.CreateActivityMessageRequest) (*pb.CreateActivityMessageResponse, error) {
// 1. 入参校验
if strings.TrimSpace(req.Content) == "" { return nil, appErrors.ErrActivityMessageContentEmpty }
if utf8.RuneCountInString(req.Content) > 500 { return nil, appErrors.ErrActivityMessageContentTooLong }
// 2. 活动存在性 + 状态
activity, err := s.activityRepo.GetActivityByID(req.ActivityId)
if err != nil { return nil, err }
if activity == nil { return nil, appErrors.ErrActivityNotFound }
if activity.Status != "active" { return nil, appErrors.ErrActivityMessageActivityInactive }
// 3. 频控（Redis INCR + EXPIRE）
rateKey := fmt.Sprintf("msg:rate:%d:%d", req.ActivityId, req.UserId)
count, _ := s.redisClient.Incr(ctx, rateKey).Result()
if count == 1 { s.redisClient.Expire(ctx, rateKey, 60*time.Second) }
if count > cfg.MessageRateLimitPerMin { return nil, appErrors.ErrActivityMessageTooFrequent }
// 4. 累计上限
total, _ := s.activityMessagesRepo.CountByUserActivity(ctx, req.ActivityId, req.UserId)
if total >= cfg.MessageLimitPerActivity { return nil, appErrors.ErrActivityMessageLimitReached }
// 5. 敏感词校验（可后续接入内容审核服务）
if containsBannedWord(req.Content) { return nil, appErrors.ErrActivityMessageContentInvalid }
// 6. 写入 + 回查用户昵称 / 头像
now := time.Now().UnixMilli()
msgID, err := s.activityMessagesRepo.Insert(ctx, repository.ActivityMessage{
ActivityId: req.ActivityId,
UserId: req.UserId,
StarId: req.StarId,
Content: req.Content,
Status: 0,
CreatedAt: now,
UpdatedAt: now,
})
if err != nil { return nil, err }
// 7. 返回带 nickname / avatar_url 的展示模型
profile, _ := s.userRPCClient.GetFanProfile(ctx, req.UserId, req.StarId)
return &pb.CreateActivityMessageResponse{
Base: &pbCommon.BaseResponse{Code: uint32(codes.OK), Message: "ok"},
Message: convertToPBMessage(msgID, req, profile, now),
}, nil
}
```
---
## 8. 前端集成要点
### 8.1 字段映射表
| 后端字段 | 前端 MessageBoard props 字段 | 转换说明 |
| ---------------- | ---------------------------- | ----------------------------------------- |
| `id` | `id` | 直接使用 |
| `nickname` | `user` | 直接使用 |
| `avatar_url` | `avatar` | 直接使用 |
| `content` | `content` | 直接使用 |
| `created_at`(ms) | `time` | 前端用 `formatRelativeTime()` 工具格式化 |
| — | `isSelf` | 前端自己判断 `user_id === currentUser.id` |
### 8.2 API 工具函数模板（追加到 `frontend/utils/api.js`）
```js
// 列出活动留言
export function listActivityMessagesApi(activityId, page = 1, pageSize = 20) {
return request({
url: `/api/v1/activities/${activityId}/messages?page=${page}&page_size=${pageSize}`,
method: 'GET',
})
}
// 发送活动留言
export function createActivityMessageApi(activityId, content) {
return request({
url: `/api/v1/activities/${activityId}/messages`,
method: 'POST',
data: { content },
})
}
// 增量获取最新留言（轮询用）
export function getLatestActivityMessagesApi(activityId, sinceTimestamp = 0, sinceId = 0, limit = 20) {
return request({
url: `/api/v1/activities/${activityId}/messages/latest?since_timestamp=${sinceTimestamp}&since_id=${sinceId}&limit=${limit}`,
method: 'GET',
})
}
```
### 8.3 `index.vue` 集成建议
```js
// 替换 mock data
const messageList = ref([])
const currentUserId = ref(null) // 从 store/modules/user.js 取
async function loadMessages() {
const res = await listActivityMessagesApi(activityId.value)
if (res.code === 0) {
messageList.value = res.data.messages.map(m => ({
id: m.id,
user: m.nickname,
avatar: m.avatar_url,
content: m.content,
time: m.created_at,
isSelf: m.user_id === currentUserId.value,
}))
}
}
async function handleSendMessage(text) {
if (!text || !text.trim()) return
const res = await createActivityMessageApi(activityId.value, text.trim())
if (res.code === 0) {
const m = res.data.message
messageList.value.push({
id: m.id,
user: m.nickname,
avatar: m.avatar_url,
content: m.content,
time: m.created_at,
isSelf: true,
})
uni.showToast({ title: '留言成功', icon: 'success' })
} else {
uni.showToast({ title: res.message || '留言失败', icon: 'none' })
}
}
onMounted(loadMessages)
```
---
## 9. 缓存与性能
- **频控计数器**：Redis Key `msg:rate:{activity_id}:{user_id}`，TTL 60s。
- **读取缓存**：首版不上缓存，直接走 DB（留言写入是追加为主，索引已覆盖热路径）；QPS 上量后再考虑 30s 缓存。
- **响应体大小**：每条留言 ≤ 500 字符 + JSON 字段约 200B，每页 20 条 ≤ 4KB，无需特殊压缩。
---
## 10. 测试用例
### 10.1 Service 层（必须覆盖）
- [ ] 首次进入活动，能正确按 `created_at DESC, id DESC` 拉取留言
- [ ] 发送空 content → `ErrActivityMessageContentEmpty`
- [ ] 发送超 500 字 content → `ErrActivityMessageContentTooLong`
- [ ] 活动状态 pending → `ErrActivityMessageActivityInactive`
- [ ] 同一用户 1 分钟内 > 5 条 → `ErrActivityMessageTooFrequent`
- [ ] 单用户单活动累计 > 100 条 → `ErrActivityMessageLimitReached`
- [ ] 增量拉取：`since_timestamp` / `since_id` 正确过滤历史
### 10.2 Handler 层
- [ ] Happy path：发送留言成功后响应体 `data.message.id` 正确
- [ ] Error path：JWT 缺失 → 401
- [ ] Error path：活动 ID 不存在 → 5 + 友好提示
---
## 11. 开放问题 / 后续迭代
| 主题 | 讨论 |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| 敏感词审核 | 首版仅本地词表；后续接 `dify` 内容审核工作流（同 laser-card 模式） |
| 留言置顶 | 是否需要 `is_pinned` 字段？若需要，新增字段 + 列表查询加 ORDER BY is_pinned DESC, created_at DESC |
| 删除能力 | 用户是否能删除自己的留言？若是，新增 `DELETE /api/v1/activities/{id}/messages/{message_id}` |
| 跨活动聚合 | "我的留言"页面：`GET /api/v1/me/activity-messages?page=&page_size=` |
| WebSocket 推送 | 高 QPS 场景下用 WS 推送替代 HTTP 轮询；接口 3 保留作为降级方案 |
---
## 12. 变更影响面（按 CLAUDE.md 自审规范）
修复 / 新增本模块时必须回归：
- [x] 现有 `activities` 表上的其他接口不受影响（新表 + 新路由）
- [x] `activity_service.go` 现有方法签名不变
- [x] 新增的 3 条路由不与现有 `activities` 组冲突
- [x] `pkg/errors` 新增错误变量不影响现有 `ToGRPCCode` 行为
- [x] `gateway/pkg/response` 的 errorMap 是追加，不覆盖现有映射
- [x] `frontend/pages/support-activity/index.vue` 已有 `ContributionList`、`ActionBar` 等组件，与 `MessageBoard` 数据流独立
- [x] PostgreSQL 序列 `activity_messages_id_seq` 起始 10000，符合 CLAUDE.md 测试数据预留规范
---
## 附录 A：Swagger 注解示例（直接复制到 controller）
```go
// ListActivityMessages 列出活动留言
// @Summary 列出活动留言
// @Description 分页获取活动留言列表（最新在上）
// @Tags activities
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param activity_id path int64 true "活动ID"
// @Param page query int false "页码，默认1"
// @Param page_size query int false "每页数量，默认20，最大50"
// @Success 200 {object} response.Response
// @Router /api/v1/activities/{activity_id}/messages [get]
func (ctrl *ActivityController) ListActivityMessages(c *gin.Context) { /* ... */ }
// CreateActivityMessage 发送活动留言
// @Summary 发送活动留言
// @Description 用户在应援活动页面发送一条祝福留言
// @Tags activities
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param activity_id path int64 true "活动ID"
// @Param request body object{content=string} true "留言内容"
// @Success 200 {object} response.Response
// @Router /api/v1/activities/{activity_id}/messages [post]
func (ctrl *ActivityController) CreateActivityMessage(c *gin.Context) { /* ... */ }
// GetLatestActivityMessages 增量获取最新留言
// @Summary 增量获取最新留言
// @Description 用于前端轮询获取活动最新留言（since_timestamp + since_id 游标）
// @Tags activities
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param activity_id path int64 true "活动ID"
// @Param since_timestamp query int64 false "毫秒时间戳，返回严格大于此值的新记录"
// @Param since_id query int64 false "ID筛选，配合since_timestamp使用"
// @Param limit query int false "返回数量，默认20，最大50"
// @Success 200 {object} response.Response
// @Router /api/v1/activities/{activity_id}/messages/latest [get]
func (ctrl *ActivityController) GetLatestActivityMessages(c *gin.Context) { /* ... */ }
```
## 附录 B：迁移脚本完整版
```sql
-- ============================================================
-- Activity Messages Table
-- ============================================================
BEGIN;
CREATE TABLE IF NOT EXISTS public.activity_messages (
id BIGSERIAL PRIMARY KEY,
activity_id BIGINT NOT NULL,
user_id BIGINT NOT NULL,
star_id BIGINT NOT NULL,
content VARCHAR(500) NOT NULL,
status SMALLINT NOT NULL DEFAULT 0,
created_at BIGINT NOT NULL,
updated_at BIGINT NOT NULL,
deleted_at BIGINT,
CONSTRAINT fk_activity_messages_activity
FOREIGN KEY (activity_id) REFERENCES public.activities(id) ON DELETE CASCADE,
CONSTRAINT fk_activity_messages_user
FOREIGN KEY (user_id) REFERENCES public.users(id),
CONSTRAINT fk_activity_messages_star
FOREIGN KEY (star_id) REFERENCES public.stars(star_id)
);
CREATE SEQUENCE IF NOT EXISTS activity_messages_id_seq START WITH 10000;
CREATE INDEX IF NOT EXISTS idx_activity_messages_activity_created
ON public.activity_messages (activity_id, created_at DESC, id DESC)
WHERE deleted_at IS NULL;
CREATE INDEX IF NOT EXISTS idx_activity_messages_user_created
ON public.activity_messages (user_id, created_at DESC)
WHERE deleted_at IS NULL;
CREATE INDEX IF NOT EXISTS idx_activity_messages_activity_incr
ON public.activity_messages (activity_id, id DESC)
WHERE deleted_at IS NULL;
COMMENT ON TABLE public.activity_messages IS '活动留言表';
COMMENT ON COLUMN public.activity_messages.id IS '主键，自增';
COMMENT ON COLUMN public.activity_messages.activity_id IS 'FK -> activities.id';
COMMENT ON COLUMN public.activity_messages.user_id IS '留言用户 ID';
COMMENT ON COLUMN public.activity_messages.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.activity_messages.content IS '留言正文，1-500 字';
COMMENT ON COLUMN public.activity_messages.status IS '0=正常|1=隐藏|2=已删除';
COMMENT ON COLUMN public.activity_messages.created_at IS '留言时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_messages.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_messages.deleted_at IS '软删除时间';
-- 健康检查（部署后跑一次）
SELECT
sequencename,
last_value,
(SELECT COALESCE(MAX(id), 0) FROM public.activity_messages) AS table_max_id,
last_value >= (SELECT COALESCE(MAX(id), 0) FROM public.activity_messages) AS is_healthy
FROM pg_sequences
WHERE sequencename = 'activity_messages_id_seq';
COMMIT;
```