SystemPromptController（系统提示词 CRUD）

cn.myapps.ai.controller.SystemPromptController —— 系统提示词的增删改查与默认提示词管理。系统提示词按 userId 归属，每个用户可设置一条默认提示词。

• 基址：${myapps.context-path.ai:}/api/system-prompt（缺省 context-path /ai，故完整前缀常为 /ai/api/system-prompt）
• 鉴权：否（obpm-ai 无鉴权过滤器，详见 index.md「鉴权说明」）
• 响应：直接返回 ResponseEntity<Map<String, Object>>，非 统一 Resource（见 index.md「响应结构与错误码」）

1. 创建系统提示词

为指定用户创建一条系统提示词。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：<context-path>/api/system-prompt（完整：${myapps.context-path.ai:}/api/system-prompt）
• 鉴权：否
• Tag：（无，控制器未声明 @Tag）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
userId	string	是	归属用户 ID
promptName	string	是	提示词名称
promptContent	string	是	提示词内容
isDefault	boolean	否	是否设为该用户的默认提示词，缺省 false

请求示例

POST /ai/api/system-prompt HTTP/1.1
Content-Type: application/json

{
  "userId": "user-001",
  "promptName": "代码助手",
  "promptContent": "你是一名资深前端工程师...",
  "isDefault": true
}

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

成功示例（HTTP 200）：

{
  "id": 1,
  "userId": "user-001",
  "promptName": "代码助手",
  "isDefault": true,
  "message": "系统提示词创建成功"
}

失败示例（HTTP 400，参数缺失或创建异常）：

{ "error": "userId、promptName、promptContent不能为空" }

{ "error": "创建系统提示词失败: <异常消息>" }

2. 更新系统提示词

按提示词 ID 更新名称、内容、默认标记。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：<context-path>/api/system-prompt/{id}（完整：${myapps.context-path.ai:}/api/system-prompt/{id}）
• 鉴权：否

路径变量

变量	类型	必填	说明
id	long	是	提示词 ID

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
promptName	string	是	提示词名称
promptContent	string	是	提示词内容
isDefault	boolean	否	是否设为默认，缺省 false

请求示例

PUT /ai/api/system-prompt/1 HTTP/1.1
Content-Type: application/json

{
  "promptName": "代码助手 v2",
  "promptContent": "你是一名资深全栈工程师...",
  "isDefault": true
}

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

成功示例（HTTP 200）：

{
  "id": 1,
  "promptName": "代码助手 v2",
  "isDefault": true,
  "message": "系统提示词更新成功"
}

失败示例（HTTP 400，参数缺失 / 提示词不存在 / 异常）：

{ "error": "promptName、promptContent不能为空" }

{ "error": "系统提示词不存在" }

{ "error": "更新系统提示词失败: <异常消息>" }

3. 删除系统提示词

按提示词 ID 删除。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：<context-path>/api/system-prompt/{id}（完整：${myapps.context-path.ai:}/api/system-prompt/{id}）
• 鉴权：否

路径变量

变量	类型	必填	说明
id	long	是	提示词 ID

请求示例

DELETE /ai/api/system-prompt/1 HTTP/1.1

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

成功示例（HTTP 200）：

{ "message": "系统提示词删除成功", "id": 1 }

失败示例（HTTP 400，提示词不存在 / 异常）：

{ "error": "系统提示词不存在" }

{ "error": "删除系统提示词失败: <异常消息>" }

4. 获取系统提示词详情

按提示词 ID 取详情。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：<context-path>/api/system-prompt/{id}（完整：${myapps.context-path.ai:}/api/system-prompt/{id}）
• 鉴权：否

路径变量

变量	类型	必填	说明
id	long	是	提示词 ID

请求示例

GET /ai/api/system-prompt/1 HTTP/1.1

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

data：

字段	类型	说明
id	long	提示词 ID
userId	string	归属用户 ID
promptName	string	提示词名称
promptContent	string	提示词内容
isDefault	boolean	是否默认
createdAt	string/null	创建时间（实体时间戳）
updatedAt	string/null	更新时间（实体时间戳）

成功示例（HTTP 200）：

{
  "id": 1,
  "userId": "user-001",
  "promptName": "代码助手 v2",
  "promptContent": "你是一名资深全栈工程师...",
  "isDefault": true,
  "createdAt": "2026-08-01T10:00:00",
  "updatedAt": "2026-08-04T09:30:00"
}

失败示例：

• HTTP 404（提示词不存在，无响应体）：由 ResponseEntity.notFound().build() 返回。
• HTTP 400（异常）：{ "error": "获取系统提示词失败: <异常消息>" }

5. 获取用户的所有系统提示词

按用户 ID 列出其全部系统提示词。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：<context-path>/api/system-prompt/user/{userId}（完整：${myapps.context-path.ai:}/api/system-prompt/user/{userId}）
• 鉴权：否

路径变量

变量	类型	必填	说明
userId	string	是	用户 ID

请求示例

GET /ai/api/system-prompt/user/user-001 HTTP/1.1

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

data：

字段	类型	说明
userId	string	用户 ID
prompts	array	该用户的 SystemPrompt 实体数组（字段同 4. 获取系统提示词详情，由 JPA 序列化）
count	int	提示词数量

成功示例（HTTP 200）：

{
  "userId": "user-001",
  "prompts": [
    {
      "id": 1,
      "userId": "user-001",
      "promptName": "代码助手 v2",
      "promptContent": "你是一名资深全栈工程师...",
      "isDefault": true,
      "createdAt": "2026-08-01T10:00:00",
      "updatedAt": "2026-08-04T09:30:00"
    }
  ],
  "count": 1
}

失败示例（HTTP 400，异常）：

{ "error": "获取用户系统提示词失败: <异常消息>" }

6. 获取用户的默认系统提示词

按用户 ID 取其默认系统提示词（若无则返回 hasDefault=false）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：<context-path>/api/system-prompt/user/{userId}/default（完整：${myapps.context-path.ai:}/api/system-prompt/user/{userId}/default）
• 鉴权：否

路径变量

变量	类型	必填	说明
userId	string	是	用户 ID

请求示例

GET /ai/api/system-prompt/user/user-001/default HTTP/1.1

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

data：

字段	类型	说明
userId	string	用户 ID
hasDefault	boolean	是否存在默认提示词
id	long	提示词 ID（hasDefault=true 时）
promptName	string	提示词名称（hasDefault=true 时）
promptContent	string	提示词内容（hasDefault=true 时）
createdAt	string/null	创建时间（hasDefault=true 时）
updatedAt	string/null	更新时间（hasDefault=true 时）

成功示例（HTTP 200，有默认）：

{
  "userId": "user-001",
  "hasDefault": true,
  "id": 1,
  "promptName": "代码助手 v2",
  "promptContent": "你是一名资深全栈工程师...",
  "createdAt": "2026-08-01T10:00:00",
  "updatedAt": "2026-08-04T09:30:00"
}

成功示例（HTTP 200，无默认）：

{ "userId": "user-001", "hasDefault": false }

失败示例（HTTP 400，异常）：

{ "error": "获取默认系统提示词失败: <异常消息>" }

7. 设置用户的默认系统提示词

将指定提示词设为某用户的默认提示词（同时取消该用户的其他默认）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：<context-path>/api/system-prompt/user/{userId}/default（完整：${myapps.context-path.ai:}/api/system-prompt/user/{userId}/default）
• 鉴权：否

路径变量

变量	类型	必填	说明
userId	string	是	用户 ID

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
promptId	long	是	待设为默认的提示词 ID（必须属于该用户）

请求示例

POST /ai/api/system-prompt/user/user-001/default HTTP/1.1
Content-Type: application/json

{ "promptId": 1 }

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

成功示例（HTTP 200）：

{
  "message": "默认系统提示词设置成功",
  "userId": "user-001",
  "promptId": 1
}

失败示例（HTTP 400，提示词不属于该用户或不存在 / 异常）：

{ "error": "系统提示词不存在或不属于该用户" }

{ "error": "设置默认系统提示词失败: <异常消息>" }

8. 健康检查

返回系统提示词服务健康状态与可用功能列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：<context-path>/api/system-prompt/health
• 鉴权：否

请求参数

无。

请求示例

GET /ai/api/system-prompt/health HTTP/1.1

响应

结构：ResponseEntity<Map<String, Object>>，非 统一 Resource。

成功示例（HTTP 200）：

{
  "status": "UP",
  "service": "System Prompt Service",
  "features": [
    "创建系统提示词",
    "更新系统提示词",
    "删除系统提示词",
    "获取用户提示词",
    "设置默认提示词"
  ]
}

---