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

基础信息

• 基础路径: /api/admin/announcement
• 认证方式: JWT Token（必须在Header中添加：Authorization: Bearer ）
• 内容类型: 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 实现不同角色的公告隔离

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