lth/1818web-hoduan

Fork 0

Files

Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00

11 KiB

Raw Blame History

广场审核与排序优化完成总结

✅ 已完成功能

一、智能排序算法优化

1. 时间衰减热度算法（已实现）

核心公式：

热度分 = (10 × 点赞数 + 1 × 浏览数) / (发布小时数 + 2)^1.5

支持的排序方式：

latest - 最新排序（按发布时间倒序）
hot - 热门排序（时间衰减热度算法）
quality - 高质量排序（按点赞率）

实现位置：

PlazaWorkMapper.java - findPublicWorksList() 方法

SQL实现：

SELECT pw.*, u.nickname, u.avatar_url,
  CASE
    WHEN sortBy = 'hot' THEN
      (10 * pw.like_count + 1 * pw.view_count) / 
      POW(TIMESTAMPDIFF(HOUR, pw.create_time, NOW()) + 2, 1.5)
    WHEN sortBy = 'quality' THEN
      CASE WHEN pw.view_count > 0 THEN (pw.like_count * 100.0 / pw.view_count) ELSE 0 END
    ELSE
      UNIX_TIMESTAMP(pw.create_time)
  END as score
FROM plaza_work pw
LEFT JOIN user u ON pw.user_id = u.id
WHERE pw.status = 'published' AND pw.audit_status = 'approved'
ORDER BY score DESC

优势：

✅ 新作品有机会获得曝光（时间加权）
✅ 优质内容能长期保持高位（点赞加权）
✅ 避免老作品独霸榜单
✅ 符合用户"看新鲜热辣内容"的心理

二、完整审核系统

1. 基础审核功能（6个API）

接口	方法	路径	功能
查询待审核列表	GET	`/admin/plaza/audit/pending`	分页查询待审核作品
查询待审核详情	GET	`/admin/plaza/audit/pending/{workNo}`	查看单个作品详情
审核作品	POST	`/admin/plaza/audit/audit`	通过或拒绝作品
批量审核	POST	`/admin/plaza/audit/batch-audit`	批量处理多个作品
审核统计	GET	`/admin/plaza/audit/stats`	获取审核数据统计
审核历史	GET	`/admin/plaza/audit/history`	查询历史记录

2. 增强审核功能（4个新API）

接口	方法	路径	功能
撤销审核	POST	`/admin/plaza/audit/revoke`	将已审核作品重新设为待审核
快捷审核	POST	`/admin/plaza/audit/quick-approve`	一键通过最早的N个待审核作品
详细审核信息	GET	`/admin/plaza/audit/detail/{workNo}`	含历史记录、作者统计的完整信息
审核员统计	GET	`/admin/plaza/audit/admin-stats`	统计审核员工作量和效率

三、审核流程设计

用户发布作品
    ↓
设置 audit_status = 'pending'
    ↓
管理员查看待审核列表
    ↓
审核决策
    ├─ 通过 → audit_status = 'approved' → 在广场显示
    ├─ 拒绝 → audit_status = 'rejected' → 不显示，记录原因
    └─ 撤销 → audit_status = 'pending' → 重新审核

审核日志记录：

每次审核操作都会记录到 plaza_work_audit_log 表
包含：审核人、审核时间、审核结果、审核备注
支持查询完整的审核历史轨迹

四、数据库变更

1. plaza_work 表新增字段

字段	类型	默认值	说明
`audit_status`	VARCHAR(20)	`pending`	审核状态
`audit_admin_id`	BIGINT	NULL	审核管理员ID
`audit_time`	DATETIME	NULL	审核时间
`audit_remark`	TEXT	NULL	审核备注

2. plaza_work_audit_log 表（新建）

审核记录表，记录所有审核操作历史：

CREATE TABLE plaza_work_audit_log (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    work_no VARCHAR(64) NOT NULL,
    work_id BIGINT NOT NULL,
    audit_status VARCHAR(20) NOT NULL,
    audit_admin_id BIGINT NOT NULL,
    audit_admin_name VARCHAR(100),
    audit_remark TEXT,
    audit_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_work_no (work_no),
    INDEX idx_admin_id (audit_admin_id)
);

五、核心业务逻辑

1. 发布作品逻辑

// PlazaServiceImpl.publishWork()
work.setStatus("published");
work.setAuditStatus("pending");  // 默认待审核
plazaWorkMapper.insert(work);

2. 查询广场作品逻辑

-- 只显示审核通过的作品
WHERE pw.status = 'published' 
  AND pw.audit_status = 'approved'  -- 关键过滤
  AND pw.is_public = 1 
  AND pw.is_deleted = 0

3. 审核作品逻辑

// AdminPlazaAuditServiceImpl.auditWork()
1. 更新作品审核状态
2. 记录审核管理员信息
3. 保存审核时间和备注
4. 插入审核日志到 audit_log 表

4. 撤销审核逻辑（新增）

// AdminPlazaAuditServiceImpl.revokeAudit()
1. 检查作品是否已审核
2. 重置 audit_status = 'pending'
3. 清空 audit_admin_id 和 audit_time
4. 记录撤销原因和操作人
5. 插入 'revoked' 类型的审核日志

5. 快捷审核逻辑（新增）

// AdminPlazaAuditServiceImpl.quickApprove()
1. 查询最早的N个待审核作品
2. 批量更新为 approved 状态
3. 为每个作品记录审核日志
4. 返回成功数量

六、新增统计功能

1. 审核基础统计

{
  "pendingCount": 50,           // 待审核数量
  "todayApprovedCount": 120,   // 今日通过数
  "todayRejectedCount": 8,     // 今日拒绝数
  "totalAuditedCount": 5000    // 累计审核数
}

2. 审核员工作量统计（新增）

{
  "adminId": 1,
  "adminName": "管理员张三",
  "totalAudited": 500,          // 总审核数
  "approvedCount": 450,         // 通过数
  "rejectedCount": 50,          // 拒绝数
  "approvalRate": 90.0,         // 通过率 90%
  "avgAuditTimeMinutes": 15.5,  // 平均审核时长（分钟）
  "busiestDate": "2025-10-28",  // 最忙碌日期
  "busiestDateCount": 120       // 最忙日审核数
}

3. 作者统计（新增）

{
  "authorApprovalRate": 85.5,   // 作者历史通过率
  "authorTotalWorks": 20        // 作者累计作品数
}

七、API调用示例

1. 快捷审核（批量通过前10个）

curl -X POST "http://localhost:8081/admin/plaza/audit/quick-approve?count=10" \
  -H "Authorization: Bearer ADMIN_TOKEN"

2. 撤销审核

curl -X POST "http://localhost:8081/admin/plaza/audit/revoke" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d "workNo=WORK-xxx&reason=误操作，需要重新审核"

3. 查询作品详细审核信息

curl "http://localhost:8081/admin/plaza/audit/detail/WORK-xxx" \
  -H "Authorization: Bearer ADMIN_TOKEN"

响应示例：

{
  "code": 200,
  "data": {
    "workInfo": {
      "workNo": "WORK-xxx",
      "title": "美丽的风景",
      "author": {
        "userId": 123,
        "username": "user123"
      }
    },
    "auditStatus": "approved",
    "auditTime": "2025-10-28T10:30:00",
    "auditAdminName": "管理员张三",
    "auditHistory": [
      {
        "auditStatus": "approved",
        "auditTime": "2025-10-28T10:30:00",
        "auditAdminName": "管理员张三",
        "auditRemark": "内容优质"
      }
    ],
    "authorApprovalRate": 85.5,
    "authorTotalWorks": 20
  }
}

4. 查询审核员工作量

curl "http://localhost:8081/admin/plaza/audit/admin-stats?startTime=2025-10-01&endTime=2025-10-31" \
  -H "Authorization: Bearer ADMIN_TOKEN"

5. 使用不同排序查询广场

# 最新排序
GET /user/plaza/works?sortBy=latest

# 热门排序（时间衰减算法）
GET /user/plaza/works?sortBy=hot

# 高质量排序（按点赞率）
GET /user/plaza/works?sortBy=quality

八、技术实现亮点

1. 时间衰减算法

使用 POW() 函数实现指数衰减
平衡新鲜度和质量的权重
避免"马太效应"

2. 审核日志追溯

完整记录所有审核操作
支持审核撤销和重审
便于问题排查和数据分析

3. 管理员效率统计

自动计算平均审核时长
识别最忙碌的审核时间
便于管理员绩效考核

4. 作者信用评分

统计作者历史通过率
辅助审核决策（高信用作者可快审）
为未来信用体系打基础

九、文件清单

数据库脚本

✅ V11__add_plaza_audit_feature.sql - 审核功能数据库变更

实体类

✅ PlazaWork.java - 新增审核字段
✅ PlazaWorkAuditLog.java - 审核记录实体

DTO

✅ AdminPlazaAuditDto.java - 新增2个DTO：
- WorkAuditDetailResponse - 详细审核信息
- AdminWorkloadStatsResponse - 审核员统计

Mapper

✅ PlazaWorkMapper.java - 优化排序算法，新增作者统计
✅ PlazaWorkAuditLogMapper.java - 新增统计查询方法

Service

✅ AdminPlazaAuditService.java - 新增4个方法
✅ AdminPlazaAuditServiceImpl.java - 实现新增方法

Controller

✅ AdminPlazaAuditController.java - 新增4个API端点

Util

✅ SecurityUtil.java - 新增 getUsername() 方法

文档

✅ 广场作品排序推荐算法说明.md - 排序算法详解
✅ 广场审核功能说明.md - 审核功能完整说明

十、部署检查清单

1. 数据库更新

# 执行审核功能SQL脚本
mysql -u root -p 1818ai < src/main/resources/db/migration/V11__add_plaza_audit_feature.sql

2. 验证字段

-- 检查 plaza_work 表
DESC plaza_work;  -- 应包含 audit_status, audit_admin_id, audit_time, audit_remark

-- 检查 plaza_work_audit_log 表
DESC plaza_work_audit_log;  -- 应存在此表

3. 测试API

✅ 发布作品后，默认为 pending 状态
✅ 广场列表只显示 approved 的作品
✅ 管理员可以查看待审核列表
✅ 审核操作记录到日志表
✅ 排序算法正确计算热度分

十一、性能优化建议

1. 索引优化

-- 审核状态索引（已在脚本中）
CREATE INDEX idx_audit_status ON plaza_work(audit_status);

-- 复合索引优化查询
CREATE INDEX idx_status_audit ON plaza_work(status, audit_status, is_public);

2. 缓存策略

广场作品列表可以缓存10分钟
热度分计算可以异步更新
审核统计数据可以缓存5分钟

3. 分页优化

使用游标分页代替offset（大数据量时）
限制最大页数，避免深分页

十二、后续优化方向

短期（1-2周）

🔄 AI辅助审核（敏感词检测）
🔄 审核规则配置化
🔄 审核任务分配系统

中期（1个月）

⏳ 个性化推荐算法
⏳ 用户举报功能
⏳ 审核优先级队列

长期（2-3个月）

⏳ 机器学习推荐模型
⏳ 内容质量评分体系
⏳ A/B测试不同排序算法

🎉 总结

✅ 排序优化：实现时间衰减热度算法 + 质量排序
✅ 审核系统：10个完整的审核API（基础6个 + 增强4个）
✅ 统计分析：审核员工作量统计 + 作者信用评分
✅ 日志追溯：完整的审核历史记录
✅ 代码质量：清晰的注释 + 完善的异常处理

所有功能已100%实现，可立即上线使用！ 🚀

11 KiB Raw Blame History Unescape Escape