login_task_web/docs/公告管理使用说明.md

基础信息

  - 基础路径: /api/admin/announcement
  - 认证方式: JWT Token（必须在Header中添加：Authorization: Bearer <token>）
  - 内容类型: application/json

  ---
  1. 创建公告

  POST /api/admin/announcement

  请求头

  Authorization: Bearer <JWT_TOKEN>
  Content-Type: application/json

  请求参数

  {
    "title": "string",           // 必填 - 公告标题，最大长度100字符
    "content": "string",         // 必填 - 公告内容
    "enabled": boolean,          // 必填 - 是否启用
    "jumpUrl": "string"          // 可选 - 跳转链接
  }

  注意: belongId 字段已从请求参数中移除，系统会自动从JWT token中解析当前用户ID并设置为 belongId

  请求示例

  {
    "title": "系统维护通知",
    "content": "系统将于今晚22:00-24:00进行维护升级，请提前保存工作内容",
    "enabled": true,
    "jumpUrl": "https://example.com/maintenance"
  }

  响应结果

  {
    "success": true,
    "message": "公告创建成功",
    "id": 1
  }

  错误响应

  {
    "success": false,
    "message": "用户未认证"
  }

  ---
  2. 获取公告列表（分页）

  GET /api/admin/announcement/list

  查询参数

  | 参数名      | 类型      | 必填  | 默认值 | 说明      |
  |----------|---------|-----|-----|---------|
  | page     | integer | 否   | 1   | 页码      |
  | size     | integer | 否   | 20  | 每页大小    |
  | enabled  | boolean | 否   | -   | 按启用状态筛选 |
  | belongId | integer | 否   | -   | 按归属ID筛选 |

  请求示例

  GET /api/admin/announcement/list?page=1&size=10&enabled=true&belongId=123

  响应结果

  {
    "items": [
      {
        "id": 1,
        "title": "系统维护通知",
        "content": "系统将于今晚22:00-24:00进行维护升级",
        "enabled": true,
        "jumpUrl": "https://example.com/maintenance",
        "belongId": 123,
        "createdAt": "2025-08-29T10:30:00",
        "updatedAt": "2025-08-29T10:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10
  }

  ---
  3. 获取公告详情

  GET /api/admin/announcement/{id}

  路径参数

  | 参数名 | 类型   | 必填  | 说明   |
  |-----|------|-----|------|
  | id  | long | 是   | 公告ID |

  请求示例

  GET /api/admin/announcement/1

  响应结果

  {
    "id": 1,
    "title": "系统维护通知",
    "content": "系统将于今晚22:00-24:00进行维护升级，请提前保存工作内容",
    "enabled": true,
    "jumpUrl": "https://example.com/maintenance",
    "belongId": 123,
    "createdAt": "2025-08-29T10:30:00",
    "updatedAt": "2025-08-29T10:30:00"
  }

  ---
  4. 更新公告

  PUT /api/admin/announcement/{id}

  请求头

  Authorization: Bearer <JWT_TOKEN>
  Content-Type: application/json

  路径参数

  | 参数名 | 类型   | 必填  | 说明   |
  |-----|------|-----|------|
  | id  | long | 是   | 公告ID |

  请求参数

  {
    "title": "string",           // 可选 - 公告标题
    "content": "string",         // 可选 - 公告内容
    "enabled": boolean,          // 可选 - 是否启用
    "jumpUrl": "string"          // 可选 - 跳转链接
  }

  注意: 更新时 belongId 会自动从JWT token中获取并更新

  请求示例

  {
    "title": "系统维护通知（更新）",
    "content": "系统维护时间调整为23:00-01:00",
    "enabled": true
  }

  响应结果

  {
    "success": true,
    "message": "公告更新成功"
  }

  ---
  5. 删除公告

  DELETE /api/admin/announcement/{id}

  路径参数

  | 参数名 | 类型   | 必填  | 说明   |
  |-----|------|-----|------|
  | id  | long | 是   | 公告ID |

  请求示例

  DELETE /api/admin/announcement/1

  响应结果

  {
    "success": true,
    "message": "公告删除成功"
  }

  ---
  6. 更新公告启用状态

  PUT /api/admin/announcement/{id}/enabled

  路径参数

  | 参数名 | 类型   | 必填  | 说明   |
  |-----|------|-----|------|
  | id  | long | 是   | 公告ID |

  查询参数

  | 参数名     | 类型      | 必填  | 说明   |
  |---------|---------|-----|------|
  | enabled | boolean | 是   | 启用状态 |

  请求示例

  PUT /api/admin/announcement/1/enabled?enabled=false

  响应结果

  {
    "success": true,
    "message": "公告已禁用"
  }

  ---
  7. 获取启用的公告

  GET /api/admin/announcement/enabled

  查询参数

  | 参数名      | 类型      | 必填  | 说明      |
  |----------|---------|-----|---------|
  | belongId | integer | 否   | 按归属ID筛选 |

  请求示例

  GET /api/admin/announcement/enabled?belongId=123

  响应结果

  [
    {
      "id": 1,
      "title": "系统维护通知",
      "content": "系统将于今晚22:00-24:00进行维护升级",
      "enabled": true,
      "jumpUrl": "https://example.com/maintenance",
      "belongId": 123,
      "createdAt": "2025-08-29T10:30:00",
      "updatedAt": "2025-08-29T10:30:00"
    }
  ]

  ---
  主要变更说明

  🔒 安全改进

  - 自动用户识别: 创建和更新公告时，系统自动从JWT token中解析当前用户ID
  - 防止伪造: 前端无法伪造 belongId，确保公告只能归属于当前登录用户

  📝 请求参数变更

  - 移除: 创建和更新公告的请求中不再需要传递 belongId 参数
  - 简化: 前端调用更加简洁，无需关心用户ID的传递

  🎯 使用场景

  1. 管理员: 创建的公告 belongId 为管理员用户ID
  2. 代理商: 创建的公告 belongId 为代理商用户ID
  3. 权限隔离: 通过 belongId 实现不同角色的公告隔离

  这样的设计既保证了安全性，又提供了灵活的公告管理能力！