H-289: add Captain Skill management API (#46)

* H-289: add Captain Skill management API * H-289: guard Captain Skill updates with CAS * H-289: version all Captain Skill updates --------- Co-authored-by: Rogee <rogee@ipao.vip>
2026-08-18 14:29:10 +08:00
parent c97097b79f
commit 0f2b8d7857
14 changed files with 1300 additions and 0 deletions
@@ -0,0 +1,193 @@
+package v1
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gochat/gochat/internal/model"
+	"github.com/gochat/gochat/internal/service"
+	"github.com/gochat/gochat/pkg/response"
+	"gorm.io/gorm"
+)
+
+type CaptainSkillHandler struct{ svc *service.CaptainSkillService }
+
+func NewCaptainSkillHandler(svc *service.CaptainSkillService) *CaptainSkillHandler {
+	return &CaptainSkillHandler{svc: svc}
+}
+
+func (h *CaptainSkillHandler) List(c *gin.Context) {
+	accountID := parseAccountIDParam(c)
+	if accountID == 0 {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrBadRequest, "invalid account_id")
+		return
+	}
+	var assistantID *uint
+	if raw := c.Query("assistant_id"); raw != "" {
+		value, err := strconv.ParseUint(raw, 10, 32)
+		if err != nil || value == 0 {
+			response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrBadRequest, "invalid assistant_id")
+			return
+		}
+		id := uint(value)
+		assistantID = &id
+	}
+	items, err := h.svc.List(c.Request.Context(), accountID, assistantID)
+	if err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	payload := make([]gin.H, len(items))
+	for i := range items {
+		payload[i] = captainSkillSummaryPayload(items[i])
+	}
+	c.JSON(http.StatusOK, gin.H{"payload": payload, "meta": gin.H{"total_count": len(payload)}})
+}
+
+func (h *CaptainSkillHandler) Create(c *gin.Context) {
+	accountID := parseAccountIDParam(c)
+	if accountID == 0 {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrBadRequest, "invalid account_id")
+		return
+	}
+	var req service.CaptainSkillRequest
+	if err := bindNestedJSONPayload(c, "skill", &req); err != nil {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrValidation, err.Error())
+		return
+	}
+	skill, err := h.svc.Create(c.Request.Context(), accountID, &req)
+	if err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, captainSkillDetailPayload(skill))
+}
+
+func (h *CaptainSkillHandler) Get(c *gin.Context) {
+	accountID, skillID, ok := captainSkillIDs(c)
+	if !ok {
+		return
+	}
+	skill, err := h.svc.Get(c.Request.Context(), accountID, skillID)
+	if err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, captainSkillDetailPayload(skill))
+}
+
+func (h *CaptainSkillHandler) Update(c *gin.Context) {
+	accountID, skillID, ok := captainSkillIDs(c)
+	if !ok {
+		return
+	}
+	var req service.CaptainSkillRequest
+	if err := bindNestedJSONPayload(c, "skill", &req); err != nil {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrValidation, err.Error())
+		return
+	}
+	skill, err := h.svc.Update(c.Request.Context(), accountID, skillID, &req)
+	if err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, captainSkillDetailPayload(skill))
+}
+
+func (h *CaptainSkillHandler) Delete(c *gin.Context) {
+	accountID, skillID, ok := captainSkillIDs(c)
+	if !ok {
+		return
+	}
+	if err := h.svc.Delete(c.Request.Context(), accountID, skillID); err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	response.NoContent(c)
+}
+
+func (h *CaptainSkillHandler) Bind(c *gin.Context) {
+	accountID, assistantID, skillID, ok := captainAssistantSkillIDs(c)
+	if !ok {
+		return
+	}
+	if err := h.svc.Bind(c.Request.Context(), accountID, assistantID, skillID); err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	response.NoContent(c)
+}
+
+func (h *CaptainSkillHandler) Unbind(c *gin.Context) {
+	accountID, assistantID, skillID, ok := captainAssistantSkillIDs(c)
+	if !ok {
+		return
+	}
+	if err := h.svc.Unbind(c.Request.Context(), accountID, assistantID, skillID); err != nil {
+		renderCaptainSkillError(c, err)
+		return
+	}
+	response.NoContent(c)
+}
+
+func captainSkillIDs(c *gin.Context) (uint, uint, bool) {
+	accountID := parseAccountIDParam(c)
+	skillID, err := parseUintAnyParam(c, "skill_id")
+	if accountID == 0 || err != nil || skillID == 0 {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrBadRequest, "invalid account_id or skill_id")
+		return 0, 0, false
+	}
+	return accountID, skillID, true
+}
+
+func captainAssistantSkillIDs(c *gin.Context) (uint, uint, uint, bool) {
+	accountID, skillID, ok := captainSkillIDs(c)
+	if !ok {
+		return 0, 0, 0, false
+	}
+	assistantID, err := parseUintAnyParam(c, "assistant_id")
+	if err != nil || assistantID == 0 {
+		response.AbortWithStatusError(c, http.StatusBadRequest, response.ErrBadRequest, "invalid assistant_id")
+		return 0, 0, 0, false
+	}
+	return accountID, assistantID, skillID, true
+}
+
+func renderCaptainSkillError(c *gin.Context, err error) {
+	switch {
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		response.AbortWithStatusError(c, http.StatusNotFound, response.ErrNotFound, "skill or assistant not found")
+	case errors.Is(err, service.ErrCaptainSkillValidation):
+		c.JSON(http.StatusUnprocessableEntity, gin.H{"error": err.Error()})
+	case errors.Is(err, service.ErrCaptainSkillConflict):
+		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+	default:
+		response.AbortWithStatusError(c, http.StatusInternalServerError, response.ErrInternal, "failed to manage captain skill")
+	}
+}
+
+func captainSkillSummaryPayload(item service.CaptainSkillListItem) gin.H {
+	skill := item.Skill
+	return gin.H{
+		"id": skill.ID, "name": skill.Name, "description": skill.Description, "status": skill.Status,
+		"version": skill.Version, "reference_count": item.ReferenceCount, "bound": item.Bound,
+		"bound_assistant_count": item.BoundAssistantCount, "updated_at": skill.UpdatedAt.Unix(),
+	}
+}
+
+func captainSkillDetailPayload(skill *model.CaptainSkill) gin.H {
+	references := make([]gin.H, len(skill.References))
+	for i := range skill.References {
+		reference := skill.References[i]
+		references[i] = gin.H{
+			"id": reference.ID, "reference_key": reference.ReferenceKey, "content_md": reference.ContentMD, "position": reference.Position,
+		}
+	}
+	return gin.H{
+		"id": skill.ID, "name": skill.Name, "description": skill.Description, "instructions_md": skill.InstructionsMD,
+		"status": skill.Status, "version": skill.Version, "references": references,
+		"created_at": skill.CreatedAt.Unix(), "updated_at": skill.UpdatedAt.Unix(),
+	}
+}
@@ -0,0 +1,147 @@
+package v1
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+
+	"github.com/gochat/gochat/internal/auth"
+	"github.com/gochat/gochat/internal/middleware"
+	"github.com/gochat/gochat/internal/model"
+	"github.com/gochat/gochat/internal/repository"
+	"github.com/gochat/gochat/internal/service"
+)
+
+func newCaptainSkillHandlerTestRouter(t *testing.T) (*gin.Engine, *gorm.DB, *model.CaptainAssistant) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	db, err := gorm.Open(sqlite.Open("file:"+t.Name()+"?mode=memory&cache=shared"), &gorm.Config{Logger: logger.Default.LogMode(logger.Silent)})
+	require.NoError(t, err)
+	require.NoError(t, db.AutoMigrate(&model.CaptainAssistant{}, &model.CaptainSkill{}, &model.CaptainSkillReference{}, &model.CaptainAssistantSkill{}))
+	assistant := &model.CaptainAssistant{AccountID: 1, Name: "Assistant", Status: model.AssistantStatusActive}
+	require.NoError(t, db.Create(assistant).Error)
+
+	handler := NewCaptainSkillHandler(service.NewCaptainSkillService(repository.NewCaptainSkillRepo(db)))
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		role := c.GetHeader("X-Test-Role")
+		if role == "" {
+			role = "administrator"
+		}
+		c.Set("policy_context", auth.NewPolicyContext(1, 1, role, 0, nil))
+		c.Next()
+	})
+	captain := router.Group("/api/v1/accounts/:account_id/captain", middleware.RoleCheckAny("administrator", "super_admin"))
+	skills := captain.Group("/skills")
+	skills.GET("", handler.List)
+	skills.POST("", handler.Create)
+	skills.GET("/:skill_id", handler.Get)
+	skills.PUT("/:skill_id", handler.Update)
+	skills.DELETE("/:skill_id", handler.Delete)
+	assistants := captain.Group("/assistants/:assistant_id/skills")
+	assistants.POST("/:skill_id", handler.Bind)
+	assistants.DELETE("/:skill_id", handler.Unbind)
+	return router, db, assistant
+}
+
+func captainSkillRequest(t *testing.T, router http.Handler, method, path, role string, body any) *httptest.ResponseRecorder {
+	t.Helper()
+	var raw []byte
+	if body != nil {
+		raw, _ = json.Marshal(body)
+	}
+	req := httptest.NewRequest(method, path, bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	if role != "" {
+		req.Header.Set("X-Test-Role", role)
+	}
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	return w
+}
+
+func captainSkillBody(status string) map[string]any {
+	return map[string]any{"skill": map[string]any{
+		"name": "refund-policy", "description": "Refund rules", "instructions_md": "Use the policy.", "status": status,
+		"references": []map[string]any{{"reference_key": "standard-policy", "content_md": "Standard terms."}},
+	}}
+}
+
+func TestCaptainSkillHandlerManagementContract(t *testing.T) {
+	router, _, assistant := newCaptainSkillHandlerTestRouter(t)
+	base := "/api/v1/accounts/1/captain"
+
+	w := captainSkillRequest(t, router, http.MethodPost, base+"/skills", "agent", captainSkillBody("active"))
+	assert.Equal(t, http.StatusForbidden, w.Code)
+
+	w = captainSkillRequest(t, router, http.MethodPost, base+"/skills", "super_admin", captainSkillBody("active"))
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+	var created map[string]any
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &created))
+	skillID := strconv.Itoa(int(created["id"].(float64)))
+	assert.Equal(t, "active", created["status"])
+	require.Len(t, created["references"], 1)
+
+	w = captainSkillRequest(t, router, http.MethodPost, base+"/assistants/"+strconv.Itoa(int(assistant.ID))+"/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusNoContent, w.Code, w.Body.String())
+	w = captainSkillRequest(t, router, http.MethodGet, base+"/skills?assistant_id="+strconv.Itoa(int(assistant.ID)), "administrator", nil)
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+	var listed map[string]any
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &listed))
+	payload := listed["payload"].([]any)
+	require.Len(t, payload, 1)
+	assert.Equal(t, true, payload[0].(map[string]any)["bound"])
+	assert.NotContains(t, payload[0].(map[string]any), "instructions_md")
+	w = captainSkillRequest(t, router, http.MethodGet, base+"/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusOK, w.Code)
+	updatedBody := captainSkillBody("active")
+	updatedBody["skill"].(map[string]any)["description"] = "Updated refund rules"
+	updatedBody["skill"].(map[string]any)["expected_version"] = 1
+	w = captainSkillRequest(t, router, http.MethodPut, base+"/skills/"+skillID, "administrator", updatedBody)
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+	var updated map[string]any
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &updated))
+	assert.Equal(t, float64(2), updated["version"])
+	updatedBody["skill"].(map[string]any)["description"] = "Stale update"
+	w = captainSkillRequest(t, router, http.MethodPut, base+"/skills/"+skillID, "administrator", updatedBody)
+	assert.Equal(t, http.StatusConflict, w.Code, w.Body.String())
+	w = captainSkillRequest(t, router, http.MethodDelete, base+"/assistants/"+strconv.Itoa(int(assistant.ID))+"/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusNoContent, w.Code)
+
+	w = captainSkillRequest(t, router, http.MethodGet, "/api/v1/accounts/2/captain/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusNotFound, w.Code)
+	w = captainSkillRequest(t, router, http.MethodPost, base+"/assistants/999/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusNotFound, w.Code)
+}
+
+func TestCaptainSkillHandlerValidationAndConflictStatuses(t *testing.T) {
+	router, _, assistant := newCaptainSkillHandlerTestRouter(t)
+	base := "/api/v1/accounts/1/captain"
+	body := captainSkillBody("active")
+	body["skill"].(map[string]any)["references"] = []map[string]any{{"reference_key": "../unsafe", "content_md": "x"}}
+	w := captainSkillRequest(t, router, http.MethodPost, base+"/skills", "administrator", body)
+	assert.Equal(t, http.StatusUnprocessableEntity, w.Code)
+	w = captainSkillRequest(t, router, http.MethodGet, base+"/skills?assistant_id=bad", "administrator", nil)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+
+	w = captainSkillRequest(t, router, http.MethodPost, base+"/skills", "administrator", captainSkillBody("draft"))
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+	var created map[string]any
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &created))
+	skillID := strconv.Itoa(int(created["id"].(float64)))
+
+	w = captainSkillRequest(t, router, http.MethodPost, base+"/assistants/"+strconv.Itoa(int(assistant.ID))+"/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusConflict, w.Code)
+	w = captainSkillRequest(t, router, http.MethodDelete, base+"/skills/"+skillID, "administrator", nil)
+	assert.Equal(t, http.StatusNoContent, w.Code)
+}