feat: harden support, localize knowledge and add operator availability [skip ci]

Source-only publication of reviewed commit 64e96a7f423673dc29ad56485be9fc79bce8af1c. Passed in isolation: focused frontend/backend tests, race checks, TypeScript typecheck, lint, Go compilation, Flowgram build, and deterministic SDK build/tests. Not accepted as a production release: Next.js export/native assembly remains blocked by environment memory limits; browser interaction and MySQL staging acceptance remain unverified. No production server, database/schema, runtime configuration, deployment, release tag, or workflow execution was performed. Expected source tree: 0a4a7528e9.
2026-10-16 15:21:42 +00:00
parent 299ea50fb5
commit 2f7a491666
176 changed files with 11869 additions and 2716 deletions
--- a/internal/handlers/api/customer_handler.go
+++ b/internal/handlers/api/customer_handler.go
@@ -1,7 +1,13 @@
+// Modified in the independent hardening fork; see docs/hardening.
+
 package api

 import (
+	"time"
+
 	"agent-desk/internal/pkg/config"
+	"agent-desk/internal/pkg/dto/response"
+	"agent-desk/internal/pkg/enums"
 	"agent-desk/internal/pkg/httpx"
 	"agent-desk/internal/pkg/openidentity"
 	"agent-desk/internal/services"
@@ -17,10 +23,11 @@ func CustomerPostSession_exchange(ctx *gin.Context) {
 	}
 	identity := config.Current().Identity
 	externalUser, err := openidentity.GetExternalUser(ctx, openidentity.Secrets{
-		UserToken:      services.ChannelService.GetUserTokenSecret(channel),
-		IdentityHMAC:   identity.Secret,
-		IdentityMaxAge: identity.MaxAge(),
-		ChannelID:      channel.ChannelID,
+		UserToken:             services.ChannelService.GetUserTokenSecret(channel),
+		IdentityHMAC:          identity.Secret,
+		IdentityMaxAge:        identity.MaxAge(),
+		ChannelID:             channel.ChannelID,
+		RequireSignedIdentity: services.ChannelService.RequiresSignedIdentity(channel),
 	})
 	if err != nil {
 		httpx.WriteJSON(ctx, err)
@@ -33,3 +40,29 @@ func CustomerPostSession_exchange(ctx *gin.Context) {
 	}
 	httpx.WriteJSON(ctx, resp)
 }
+
+// Refresh requires possession of the still-valid customer credential; unlike
+// unsigned session exchange it never creates or changes an anonymous identity.
+func CustomerPostSession_refresh(ctx *gin.Context) {
+	channel := services.ChannelService.GetEnabledChannel(ctx)
+	if channel == nil {
+		httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0209"))
+		return
+	}
+	result, err := services.CustomerSessionService.VerifyRequest(ctx, channel)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	services.CustomerSessionService.SetRefreshHeaders(ctx, result)
+	source := "guest:"
+	if result.ExternalUser.ExternalSource == enums.ExternalSourceUser {
+		source = "user:"
+	}
+	httpx.WriteJSON(ctx, &response.CustomerSessionExchangeResponse{
+		CustomerSessionToken: result.Token,
+		ExpiresAt:            result.ExpiresAt.UTC().Format(time.RFC3339),
+		IdentityKey:          source + result.ExternalUser.ExternalID,
+		Customer:             response.CustomerSessionCustomerResponse{ID: result.CustomerID, Name: result.ExternalUser.ExternalName},
+	})
+}
--- a/internal/handlers/api/support_status_handler.go
+++ b/internal/handlers/api/support_status_handler.go
@@ -0,0 +1,22 @@
+package api
+
+import (
+	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/services"
+	"github.com/gin-gonic/gin"
+)
+
+func SupportGetStatus(ctx *gin.Context) {
+	channel := services.ChannelService.GetEnabledChannel(ctx)
+	if channel == nil {
+		httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0209"))
+		return
+	}
+	result, err := services.SupportAvailabilityService.PublicStatus(channel)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	ctx.Header("Cache-Control", "no-store")
+	httpx.WriteJSON(ctx, result)
+}
--- a/internal/handlers/dashboard/agent_handler.go
+++ b/internal/handlers/dashboard/agent_handler.go
@@ -1,3 +1,4 @@
+// Modified in AgentDeskNext: authenticated support availability and calendars.
 package dashboard

 import (
@@ -18,13 +19,18 @@ func AgentAnyList(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	list, paging := services.AgentProfileService.FindPageByCnd(params.NewPagedSqlCnd(ctx,
+	cnd := params.NewPagedSqlCnd(ctx,
 		params.QueryFilter{ParamName: "userId"},
 		params.QueryFilter{ParamName: "teamId"},
-		params.QueryFilter{ParamName: "serviceStatus"},
 		params.QueryFilter{ParamName: "agentCode", Op: params.Like},
 		params.QueryFilter{ParamName: "displayName", Op: params.Like},
-	).Desc("id"))
+	).Desc("id")
+	status, _ := params.Get(ctx, "serviceStatus")
+	if err := services.AgentProfileService.FilterEffectiveServiceStatus(cnd, status); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	list, paging := services.AgentProfileService.FindPageByCnd(cnd)
 	results := builders.BuildAgentProfileList(list)
 	httpx.WriteJSON(ctx, &web.PageResult{Results: results, Page: paging})
 }
@@ -34,12 +40,17 @@ func AgentGetList_all(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	list := services.AgentProfileService.Find(params.NewPagedSqlCnd(ctx,
+	cnd := params.NewPagedSqlCnd(ctx,
 		params.QueryFilter{ParamName: "userId"},
 		params.QueryFilter{ParamName: "teamId"},
-		params.QueryFilter{ParamName: "serviceStatus"},
 		params.QueryFilter{ParamName: "agentCode", Op: params.Like},
-	).Desc("id"))
+	).Desc("id")
+	status, _ := params.Get(ctx, "serviceStatus")
+	if err := services.AgentProfileService.FilterEffectiveServiceStatus(cnd, status); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	list := services.AgentProfileService.Find(cnd)

 	httpx.WriteJSON(ctx, builders.BuildAgentProfileList(list))
 }
--- a/internal/handlers/dashboard/knowledge_base_handler.go
+++ b/internal/handlers/dashboard/knowledge_base_handler.go
@@ -1,7 +1,9 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
 	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/pkg/i18nx"
 	"context"
 	"log/slog"

@@ -35,7 +37,7 @@ func KnowledgeBaseAnyList(ctx *gin.Context) {
 	for _, item := range list {
 		docCount := repositories.KnowledgeDocumentRepository.CountByKnowledgeBaseID(sqls.DB(), item.ID)
 		faqCount := repositories.KnowledgeFAQRepository.CountByKnowledgeBaseID(sqls.DB(), item.ID)
-		resp := builders.BuildKnowledgeBase(&item)
+		resp := builders.BuildKnowledgeBase(&item, i18nx.Locale(ctx))
 		resp.DocumentCount = docCount
 		resp.FAQCount = faqCount
 		results = append(results, resp)
@@ -54,7 +56,7 @@ func KnowledgeBaseAnyList_all(ctx *gin.Context) {
 	).Asc("sort_no").Desc("id"))
 	results := make([]response.KnowledgeBaseResponse, 0, len(list))
 	for _, item := range list {
-		resp := builders.BuildKnowledgeBase(&item)
+		resp := builders.BuildKnowledgeBase(&item, i18nx.Locale(ctx))
 		results = append(results, resp)
 	}
 	httpx.WriteJSON(ctx, results)
@@ -75,7 +77,7 @@ func KnowledgeBaseGetBy(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0283"))
 		return
 	}
-	resp := builders.BuildKnowledgeBase(item)
+	resp := builders.BuildKnowledgeBase(item, i18nx.Locale(ctx))
 	resp.DocumentCount = repositories.KnowledgeDocumentRepository.CountByKnowledgeBaseID(sqls.DB(), item.ID)
 	resp.FAQCount = repositories.KnowledgeFAQRepository.CountByKnowledgeBaseID(sqls.DB(), item.ID)
 	httpx.WriteJSON(ctx, resp)
@@ -98,7 +100,7 @@ func KnowledgeBasePostCreate(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	httpx.WriteJSON(ctx, builders.BuildKnowledgeBase(item))
+	httpx.WriteJSON(ctx, builders.BuildKnowledgeBase(item, i18nx.Locale(ctx)))
 }

 func KnowledgeBasePostUpdate(ctx *gin.Context) {
--- a/internal/handlers/dashboard/knowledge_directory_handler.go
+++ b/internal/handlers/dashboard/knowledge_directory_handler.go
@@ -1,3 +1,4 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
@@ -9,6 +10,7 @@ import (
 	"agent-desk/internal/pkg/errorsx"
 	"agent-desk/internal/pkg/httpx"
 	"agent-desk/internal/pkg/httpx/params"
+	"agent-desk/internal/pkg/i18nx"
 	"agent-desk/internal/services"

 	"github.com/gin-gonic/gin"
@@ -25,7 +27,7 @@ func KnowledgeDirectoryGetList_all(ctx *gin.Context) {
 		return
 	}
 	list := services.KnowledgeDirectoryService.FindAllByKnowledgeBaseID(knowledgeBaseID)
-	httpx.WriteJSON(ctx, buildKnowledgeDirectoryTreeResponses(list))
+	httpx.WriteJSON(ctx, buildKnowledgeDirectoryTreeResponses(list, i18nx.Locale(ctx)))
 }

 func KnowledgeDirectoryPostCreate(ctx *gin.Context) {
@@ -44,7 +46,7 @@ func KnowledgeDirectoryPostCreate(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	resp := builders.BuildKnowledgeDirectory(item)
+	resp := builders.BuildKnowledgeDirectory(item, i18nx.Locale(ctx))
 	httpx.WriteJSON(ctx, &resp)
 }

@@ -104,7 +106,7 @@ func KnowledgeDirectoryPostUpdate_sort(ctx *gin.Context) {
 	httpx.WriteJSON(ctx, nil)
 }

-func buildKnowledgeDirectoryTreeResponses(list []models.KnowledgeDirectory) []response.KnowledgeDirectoryResponse {
+func buildKnowledgeDirectoryTreeResponses(list []models.KnowledgeDirectory, locales ...string) []response.KnowledgeDirectoryResponse {
 	childrenByParent := make(map[int64][]models.KnowledgeDirectory, len(list))
 	for _, item := range list {
 		childrenByParent[item.ParentID] = append(childrenByParent[item.ParentID], item)
@@ -114,7 +116,7 @@ func buildKnowledgeDirectoryTreeResponses(list []models.KnowledgeDirectory) []re
 		items := childrenByParent[parentID]
 		ret := make([]response.KnowledgeDirectoryResponse, 0, len(items))
 		for _, item := range items {
-			resp := builders.BuildKnowledgeDirectory(&item)
+			resp := builders.BuildKnowledgeDirectory(&item, knowledgeDirectoryLocale(locales))
 			resp.Children = build(item.ID)
 			ret = append(ret, resp)
 		}
@@ -122,3 +124,10 @@ func buildKnowledgeDirectoryTreeResponses(list []models.KnowledgeDirectory) []re
 	}
 	return build(0)
 }
+
+func knowledgeDirectoryLocale(locales []string) string {
+	if len(locales) > 0 {
+		return locales[0]
+	}
+	return i18nx.DefaultLocale
+}
--- a/internal/handlers/dashboard/knowledge_document_handler.go
+++ b/internal/handlers/dashboard/knowledge_document_handler.go
@@ -1,3 +1,4 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
@@ -7,6 +8,7 @@ import (
 	"agent-desk/internal/pkg/dto/response"
 	"agent-desk/internal/pkg/enums"
 	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/pkg/i18nx"
 	"agent-desk/internal/services"

 	"agent-desk/internal/pkg/httpx/params"
@@ -47,7 +49,7 @@ func KnowledgeDocumentAnyList(ctx *gin.Context) {
 	directoryPaths := services.KnowledgeDirectoryService.PathMap(knowledgeBaseID)
 	results := make([]response.KnowledgeDocumentListResponse, 0, len(list))
 	for _, item := range list {
-		resp := builders.BuildKnowledgeDocumentList(&item)
+		resp := builders.BuildKnowledgeDocumentList(&item, i18nx.Locale(ctx))
 		fillKnowledgeDocumentDirectory(&resp, directoryPaths)
 		results = append(results, resp)
 	}
@@ -69,7 +71,7 @@ func KnowledgeDocumentGetBy(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0218"))
 		return
 	}
-	resp := builders.BuildKnowledgeDocument(item)
+	resp := builders.BuildKnowledgeDocument(item, i18nx.Locale(ctx))
 	fillKnowledgeDocumentDirectory(&resp, services.KnowledgeDirectoryService.PathMap(item.KnowledgeBaseID))
 	httpx.WriteJSON(ctx, resp)
 }
@@ -102,7 +104,7 @@ func KnowledgeDocumentPostCreate(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	httpx.WriteJSON(ctx, builders.BuildKnowledgeDocument(item))
+	httpx.WriteJSON(ctx, builders.BuildKnowledgeDocument(item, i18nx.Locale(ctx)))
 }

 func KnowledgeDocumentPostUpdate(ctx *gin.Context) {
--- a/internal/handlers/dashboard/knowledge_faq_handler.go
+++ b/internal/handlers/dashboard/knowledge_faq_handler.go
@@ -1,3 +1,4 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
@@ -23,7 +24,7 @@ func KnowledgeFAQGetImport_template(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	file, err := services.KnowledgeFAQService.BuildKnowledgeFAQImportTemplate()
+	file, err := services.KnowledgeFAQService.BuildKnowledgeFAQImportTemplate(i18nx.Locale(ctx))
 	if err != nil {
 		httpx.WriteJSON(ctx, err)
 		return
@@ -41,7 +42,7 @@ func KnowledgeFAQGetExport(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, errorsx.InvalidParamI18n("error.e0283"))
 		return
 	}
-	file, err := services.KnowledgeFAQService.ExportKnowledgeFAQs(knowledgeBaseID)
+	file, err := services.KnowledgeFAQService.ExportKnowledgeFAQs(knowledgeBaseID, i18nx.Locale(ctx))
 	if err != nil {
 		httpx.WriteJSON(ctx, err)
 		return
@@ -111,7 +112,7 @@ func KnowledgeFAQAnyList(ctx *gin.Context) {
 	directoryPaths := services.KnowledgeDirectoryService.PathMap(knowledgeBaseID)
 	results := make([]response.KnowledgeFAQResponse, 0, len(list))
 	for _, item := range list {
-		resp := builders.BuildKnowledgeFAQ(&item)
+		resp := builders.BuildKnowledgeFAQ(&item, i18nx.Locale(ctx))
 		fillKnowledgeFAQDirectory(&resp, directoryPaths)
 		results = append(results, resp)
 	}
@@ -133,7 +134,7 @@ func KnowledgeFAQGetBy(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0025"))
 		return
 	}
-	resp := builders.BuildKnowledgeFAQ(item)
+	resp := builders.BuildKnowledgeFAQ(item, i18nx.Locale(ctx))
 	fillKnowledgeFAQDirectory(&resp, services.KnowledgeDirectoryService.PathMap(item.KnowledgeBaseID))
 	httpx.WriteJSON(ctx, resp)
 }
@@ -154,7 +155,7 @@ func KnowledgeFAQPostCreate(ctx *gin.Context) {
 		httpx.WriteJSON(ctx, err)
 		return
 	}
-	httpx.WriteJSON(ctx, builders.BuildKnowledgeFAQ(item))
+	httpx.WriteJSON(ctx, builders.BuildKnowledgeFAQ(item, i18nx.Locale(ctx)))
 }

 func KnowledgeFAQPostUpdate(ctx *gin.Context) {
--- a/internal/handlers/dashboard/knowledge_retrieve_handler.go
+++ b/internal/handlers/dashboard/knowledge_retrieve_handler.go
@@ -1,15 +1,18 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
-	"agent-desk/internal/pkg/httpx"
 	"context"
+	"errors"

 	"agent-desk/internal/ai/rag"
 	"agent-desk/internal/pkg/constants"
 	"agent-desk/internal/pkg/dto/request"
-	"agent-desk/internal/services"
-
+	"agent-desk/internal/pkg/errorsx"
+	"agent-desk/internal/pkg/httpx"
 	"agent-desk/internal/pkg/httpx/params"
+	"agent-desk/internal/pkg/i18nx"
+	"agent-desk/internal/services"

 	"github.com/gin-gonic/gin"
 )
@@ -26,9 +29,9 @@ func KnowledgeRetrievePostDebugSearch(ctx *gin.Context) {
 		return
 	}

-	resp, err := rag.Answer.DebugSearch(context.Background(), req)
+	resp, err := rag.Answer.DebugSearch(knowledgeRequestContext(ctx), req)
 	if err != nil {
-		httpx.WriteJSON(ctx, err)
+		httpx.WriteJSON(ctx, safeKnowledgeOperationError(err, "error.knowledge.retrieveFailed"))
 		return
 	}
 	httpx.WriteJSON(ctx, resp)
@@ -47,9 +50,9 @@ func KnowledgeRetrievePostDebugAnswer(ctx *gin.Context) {
 		return
 	}

-	resp, err := rag.Answer.DebugAnswer(context.Background(), req, operator)
+	resp, err := rag.Answer.DebugAnswer(knowledgeRequestContext(ctx), req, operator)
 	if err != nil {
-		httpx.WriteJSON(ctx, err)
+		httpx.WriteJSON(ctx, safeKnowledgeOperationError(err, "error.knowledge.retrieveFailed"))
 		return
 	}
 	httpx.WriteJSON(ctx, resp)
@@ -70,8 +73,8 @@ func KnowledgeRetrievePostBuild(ctx *gin.Context) {
 			httpx.WriteJSON(ctx, err)
 			return
 		}
-		if err := rag.Answer.BuildDocumentIndex(context.Background(), req.DocumentID); err != nil {
-			httpx.WriteJSON(ctx, err)
+		if err := rag.Answer.BuildDocumentIndex(knowledgeRequestContext(ctx), req.DocumentID); err != nil {
+			httpx.WriteJSON(ctx, safeKnowledgeOperationError(err, "error.knowledge.indexFailed"))
 			return
 		}
 		httpx.WriteJSON(ctx, nil)
@@ -83,8 +86,8 @@ func KnowledgeRetrievePostBuild(ctx *gin.Context) {
 			httpx.WriteJSON(ctx, err)
 			return
 		}
-		if err := rag.Index.IndexFAQByID(context.Background(), req.FAQID); err != nil {
-			httpx.WriteJSON(ctx, err)
+		if err := rag.Index.IndexFAQByID(knowledgeRequestContext(ctx), req.FAQID); err != nil {
+			httpx.WriteJSON(ctx, safeKnowledgeOperationError(err, "error.knowledge.indexFailed"))
 			return
 		}
 		httpx.WriteJSON(ctx, nil)
@@ -93,3 +96,29 @@ func KnowledgeRetrievePostBuild(ctx *gin.Context) {

 	httpx.WriteJSON(ctx, httpx.JsonErrorMsg(ctx, "error.e0066"))
 }
+
+func knowledgeRequestContext(ctx *gin.Context) context.Context {
+	parent := context.Background()
+	if ctx != nil && ctx.Request != nil {
+		parent = ctx.Request.Context()
+	}
+	return i18nx.WithLocale(parent, i18nx.Locale(ctx))
+}
+
+// Only catalog-owned errors without arbitrary diagnostic arguments are safe to
+// return from index/embedding/vector providers. Unwrap the application error so
+// a surrounding SQL/provider message never reaches the response.
+func safeKnowledgeOperationError(err error, fallbackKey string) error {
+	if err == nil {
+		return nil
+	}
+	var appErr *errorsx.I18nError
+	if errors.As(err, &appErr) && appErr != nil && len(appErr.Args) == 0 && i18nx.Get(appErr.Key) != appErr.Key {
+		return appErr
+	}
+	var localizedErr *i18nx.Error
+	if errors.As(err, &localizedErr) && localizedErr != nil && len(localizedErr.Args) == 0 && i18nx.Get(localizedErr.Key) != localizedErr.Key {
+		return i18nx.Errorf(localizedErr.Key)
+	}
+	return errorsx.BusinessErrorI18n(0, fallbackKey)
+}
--- a/internal/handlers/dashboard/knowledge_retrieve_handler_test.go
+++ b/internal/handlers/dashboard/knowledge_retrieve_handler_test.go
@@ -0,0 +1,77 @@
+package dashboard
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"agent-desk/internal/pkg/errorsx"
+	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/pkg/i18nx"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mlogclub/simple/web"
+)
+
+func TestKnowledgeRequestContextPreservesLocaleAndCancellation(t *testing.T) {
+	parent, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	ctx, _ := gin.CreateTestContext(httptest.NewRecorder())
+	ctx.Request = httptest.NewRequest("POST", "/knowledge_retrieve/debug_answer", nil).WithContext(parent)
+	ctx.Request.Header.Set("X-Locale", i18nx.LocaleZhCN)
+	ctx.Request.Header.Set("Accept-Language", i18nx.LocaleZhCN)
+	i18nx.SetLocale(ctx, i18nx.LocaleRuRU)
+	derived := knowledgeRequestContext(ctx)
+	if i18nx.LocaleFromContext(derived) != i18nx.LocaleRuRU {
+		t.Fatal("request locale was lost")
+	}
+	parentDeadline, _ := parent.Deadline()
+	if deadline, ok := derived.Deadline(); !ok || !deadline.Equal(parentDeadline) {
+		t.Fatal("request deadline was lost")
+	}
+	cancel()
+	if !errors.Is(derived.Err(), context.Canceled) {
+		t.Fatal("request cancellation was lost")
+	}
+}
+
+func TestKnowledgeOperationErrorsHideProviderDiagnostics(t *testing.T) {
+	const diagnostic = "synthetic-private-diagnostic"
+	for _, key := range []string{"error.knowledge.indexFailed", "error.knowledge.retrieveFailed"} {
+		for _, cause := range []error{
+			errors.New("SQL failed: " + diagnostic),
+			fmt.Errorf("provider request failed: %w", errors.New(diagnostic)),
+			web.NewError(2000, diagnostic),
+			errorsx.BusinessErrorI18n(0, "error.e0340", diagnostic),
+			errorsx.BusinessErrorI18n(0, "unknown.translation."+diagnostic),
+		} {
+			for _, locale := range []string{i18nx.LocaleEnUS, i18nx.LocaleRuRU, i18nx.LocaleZhCN} {
+				recorder := httptest.NewRecorder()
+				ctx, _ := gin.CreateTestContext(recorder)
+				i18nx.SetLocale(ctx, locale)
+				httpx.WriteJSON(ctx, safeKnowledgeOperationError(cause, key))
+				body := recorder.Body.String()
+				if strings.Contains(body, diagnostic) || !strings.Contains(body, i18nx.Getf(locale, key)) {
+					t.Fatalf("unsafe/unlocalized %s response: %s", key, body)
+				}
+			}
+		}
+	}
+}
+
+func TestKnowledgeOperationErrorPreservesCatalogApplicationError(t *testing.T) {
+	original := errorsx.InvalidParamI18n("error.e0340")
+	wrapped := fmt.Errorf("private provider details: %w", original)
+	if got := safeKnowledgeOperationError(wrapped, "error.knowledge.retrieveFailed"); got != original {
+		t.Fatalf("application error lost: %v", got)
+	}
+	localized := i18nx.Errorf("error.embeddingModel.noneEnabled")
+	got := safeKnowledgeOperationError(fmt.Errorf("private: %w", localized), "error.knowledge.indexFailed")
+	if got.Error() != localized.Error() || strings.Contains(got.Error(), "private") {
+		t.Fatalf("localized application error changed/leaked: %v", got)
+	}
+}
--- a/internal/handlers/dashboard/knowledge_retrieve_log_handler.go
+++ b/internal/handlers/dashboard/knowledge_retrieve_log_handler.go
@@ -1,3 +1,4 @@
+// Modified in the independent AgentDesk fork: localized knowledge workflows and safe display errors.
 package dashboard

 import (
@@ -5,6 +6,7 @@ import (
 	"agent-desk/internal/pkg/constants"
 	"agent-desk/internal/pkg/dto/response"
 	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/pkg/i18nx"
 	"agent-desk/internal/services"

 	"agent-desk/internal/pkg/httpx/params"
@@ -39,7 +41,7 @@ func KnowledgeRetrieveLogAnyList(ctx *gin.Context) {
 	list, paging := services.KnowledgeRetrieveLogService.FindPageByParams(queryParams)
 	results := make([]response.KnowledgeRetrieveLogResponse, 0, len(list))
 	for _, item := range list {
-		resp := builders.BuildKnowledgeRetrieveLog(&item)
+		resp := builders.BuildKnowledgeRetrieveLog(&item, i18nx.Locale(ctx))
 		if knowledgeBase := services.KnowledgeBaseService.Get(item.KnowledgeBaseID); knowledgeBase != nil {
 			resp.KnowledgeBaseName = knowledgeBase.Name
 		}
@@ -64,7 +66,7 @@ func KnowledgeRetrieveLogGetBy(ctx *gin.Context) {
 		return
 	}

-	logResp := builders.BuildKnowledgeRetrieveLog(logItem)
+	logResp := builders.BuildKnowledgeRetrieveLog(logItem, i18nx.Locale(ctx))
 	if knowledgeBase := services.KnowledgeBaseService.Get(logItem.KnowledgeBaseID); knowledgeBase != nil {
 		logResp.KnowledgeBaseName = knowledgeBase.Name
 	}
@@ -72,7 +74,7 @@ func KnowledgeRetrieveLogGetBy(ctx *gin.Context) {
 	hits := services.KnowledgeRetrieveLogService.FindHitsByRetrieveLogID(id)
 	hitResults := make([]response.KnowledgeRetrieveHitResponse, 0, len(hits))
 	for _, item := range hits {
-		hitResults = append(hitResults, builders.BuildKnowledgeRetrieveHitResponse(&item))
+		hitResults = append(hitResults, builders.BuildKnowledgeRetrieveHitResponse(&item, i18nx.Locale(ctx)))
 	}

 	httpx.WriteJSON(ctx, response.KnowledgeRetrieveLogDetailResponse{
--- a/internal/handlers/dashboard/support_availability_handler.go
+++ b/internal/handlers/dashboard/support_availability_handler.go
@@ -0,0 +1,152 @@
+package dashboard
+
+import (
+	"agent-desk/internal/pkg/constants"
+	"agent-desk/internal/pkg/dto"
+	"agent-desk/internal/pkg/dto/request"
+	"agent-desk/internal/pkg/errorsx"
+	"agent-desk/internal/pkg/httpx"
+	"agent-desk/internal/pkg/httpx/params"
+	"agent-desk/internal/services"
+	"github.com/gin-gonic/gin"
+	"slices"
+	"strconv"
+)
+
+func SupportAvailabilityGetMe(ctx *gin.Context) {
+	ctx.Header("Cache-Control", "no-store")
+	principal := services.AuthService.GetAuthPrincipal(ctx)
+	if principal == nil {
+		httpx.WriteJSON(ctx, errorsx.UnauthorizedI18n("error.auth.expired"))
+		return
+	}
+	item, err := services.SupportAvailabilityService.ForUser(principal.UserID, true)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
+func SupportAvailabilityPostMe(ctx *gin.Context) {
+	principal := services.AuthService.GetAuthPrincipal(ctx)
+	if principal == nil {
+		httpx.WriteJSON(ctx, errorsx.UnauthorizedI18n("error.auth.expired"))
+		return
+	}
+	req := request.SupportAvailabilityRequest{}
+	if err := params.ReadJSON(ctx, &req); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	// Never accept a target from a self-service request.
+	item, err := services.SupportAvailabilityService.Update(principal.UserID, req, principal)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
+func SupportAvailabilityGetAgents(ctx *gin.Context) {
+	ctx.Header("Cache-Control", "no-store")
+	principal := services.AuthService.GetAuthPrincipal(ctx)
+	if principal == nil {
+		httpx.WriteJSON(ctx, errorsx.UnauthorizedI18n("error.auth.expired"))
+		return
+	}
+	if !slices.Contains(principal.Permissions, constants.PermissionAgentView.Code) && !slices.Contains(principal.Permissions, constants.PermissionConversationAssign.Code) && !slices.Contains(principal.Permissions, constants.PermissionConversationTransfer.Code) {
+		httpx.WriteJSON(ctx, errorsx.ForbiddenI18n("error.e0225"))
+		return
+	}
+	id, _ := strconv.ParseInt(ctx.Query("conversationId"), 10, 64)
+	if id <= 0 && !slices.Contains(principal.Permissions, constants.PermissionAgentView.Code) {
+		httpx.WriteJSON(ctx, errorsx.ForbiddenI18n("error.e0225"))
+		return
+	}
+	items, err := services.SupportAvailabilityService.List(id, principal)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, items)
+}
+func SupportAvailabilityPostAgent(ctx *gin.Context) {
+	principal, err := services.AuthService.RequirePermission(ctx, constants.PermissionAgentUpdate)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	req := request.SupportAvailabilityRequest{}
+	if err := params.ReadJSON(ctx, &req); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	item, err := services.SupportAvailabilityService.Update(req.UserID, req, principal)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
+func supportCalendarPermission(ctx *gin.Context, teamID int64, write bool) (*dto.AuthPrincipal, error) {
+	if teamID == 0 {
+		if write {
+			return services.AuthService.RequirePermission(ctx, constants.PermissionSupportConfigUpdate)
+		}
+		return services.AuthService.RequirePermission(ctx, constants.PermissionSupportConfigView)
+	}
+	if write {
+		return services.AuthService.RequirePermission(ctx, constants.PermissionAgentTeamScheduleUpdate)
+	}
+	return services.AuthService.RequirePermission(ctx, constants.PermissionAgentTeamScheduleView)
+}
+func SupportAvailabilityGetCalendar(ctx *gin.Context) {
+	teamID, err := strconv.ParseInt(ctx.DefaultQuery("teamId", "0"), 10, 64)
+	if err != nil || teamID < 0 {
+		httpx.WriteJSON(ctx, errorsx.InvalidParamI18n("error.supportAvailability.invalidCalendar"))
+		return
+	}
+	if _, err := supportCalendarPermission(ctx, teamID, false); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	item, err := services.SupportCalendarService.Get(teamID)
+	if err != nil {
+		httpx.WriteJSON(ctx, errorsx.InvalidParamI18n("error.supportAvailability.persistence"))
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
+func SupportAvailabilityPostCalendar(ctx *gin.Context) {
+	req := request.SupportCalendarRequest{}
+	if err := params.ReadJSON(ctx, &req); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	if _, err := supportCalendarPermission(ctx, req.TeamID, true); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	item, err := services.SupportCalendarService.Save(req)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
+func SupportAvailabilityPostCalendarPreview(ctx *gin.Context) {
+	req := request.SupportCalendarPreviewRequest{}
+	if err := params.ReadJSON(ctx, &req); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	if _, err := supportCalendarPermission(ctx, req.Calendar.TeamID, false); err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	item, err := services.SupportCalendarService.Preview(req)
+	if err != nil {
+		httpx.WriteJSON(ctx, err)
+		return
+	}
+	httpx.WriteJSON(ctx, item)
+}
--- a/internal/handlers/dashboard/support_availability_handler_test.go
+++ b/internal/handlers/dashboard/support_availability_handler_test.go
@@ -0,0 +1,121 @@
+package dashboard
+
+import (
+	"agent-desk/internal/models"
+	"agent-desk/internal/pkg/constants"
+	"agent-desk/internal/pkg/dto"
+	"agent-desk/internal/pkg/enums"
+	"encoding/json"
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"github.com/mlogclub/simple/sqls"
+	"gorm.io/gorm"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func availabilityHandlerDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(filepath.Join(t.TempDir(), "availability.db")), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.AutoMigrate(&models.User{}, &models.AgentProfile{}, &models.AgentTeam{}, &models.AgentTeamSchedule{}, &models.SupportCalendar{}, &models.AgentPresenceLease{}, &models.Conversation{}); err != nil {
+		t.Fatal(err)
+	}
+	previous := sqls.DB()
+	sqls.SetDB(db)
+	t.Cleanup(func() { sqls.SetDB(previous); conn, _ := db.DB(); conn.Close() })
+	for _, row := range []any{&models.User{ID: 1, Username: "one", UserType: enums.UserTypeEmployee}, &models.User{ID: 2, Username: "two", UserType: enums.UserTypeEmployee}, &models.AgentTeam{ID: 1, Name: "Support"}, &models.AgentProfile{ID: 1, UserID: 1, TeamID: 1, AgentCode: "one"}, &models.AgentProfile{ID: 2, UserID: 2, TeamID: 1, AgentCode: "two"}} {
+		if err := db.Create(row).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	return db
+}
+func callAvailabilityHandler(t *testing.T, handler gin.HandlerFunc, principal *dto.AuthPrincipal, body string) map[string]any {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		if principal != nil {
+			c.Set("authPrincipal", principal)
+		}
+		c.Next()
+	})
+	router.POST("/test", handler)
+	req := httptest.NewRequest("POST", "/test", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	var result map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	return result
+}
+func TestSupportAvailabilitySelfCannotTargetAnotherUser(t *testing.T) {
+	db := availabilityHandlerDB(t)
+	principal := &dto.AuthPrincipal{UserID: 1, Username: "one", UserType: enums.UserTypeEmployee}
+	got := callAvailabilityHandler(t, SupportAvailabilityPostMe, principal, `{"userId":2,"serviceStatus":2}`)
+	if got["success"] != true {
+		t.Fatalf("self update: %v", got)
+	}
+	var own, other models.AgentProfile
+	db.First(&own, 1)
+	db.First(&other, 2)
+	if own.ServiceStatus != enums.ServiceStatusBreak || other.ServiceStatus != enums.ServiceStatusIdle {
+		t.Fatal("self endpoint changed another profile")
+	}
+}
+func TestSupportAvailabilitySelfDoesNotProvisionMissingProfile(t *testing.T) {
+	db := availabilityHandlerDB(t)
+	principal := &dto.AuthPrincipal{UserID: 99, Username: "missing", UserType: enums.UserTypeEmployee}
+	got := callAvailabilityHandler(t, SupportAvailabilityPostMe, principal, `{"serviceStatus":0}`)
+	if got["success"] == true {
+		t.Fatal("missing operator gained profile")
+	}
+	var count int64
+	db.Model(&models.AgentProfile{}).Count(&count)
+	if count != 2 {
+		t.Fatalf("profile count %d", count)
+	}
+}
+func TestSupportAvailabilityAdminRequiresExactPermission(t *testing.T) {
+	db := availabilityHandlerDB(t)
+	principal := &dto.AuthPrincipal{UserID: 1, Username: "one", Permissions: []string{constants.PermissionAgentView.Code}}
+	got := callAvailabilityHandler(t, SupportAvailabilityPostAgent, principal, `{"userId":2,"serviceStatus":3}`)
+	if got["success"] == true {
+		t.Fatal("read permission changed another operator")
+	}
+	var other models.AgentProfile
+	db.First(&other, 2)
+	if other.ServiceStatus != enums.ServiceStatusIdle {
+		t.Fatal("unauthorized mutation")
+	}
+	principal.Permissions = []string{constants.PermissionAgentUpdate.Code}
+	got = callAvailabilityHandler(t, SupportAvailabilityPostAgent, principal, `{"userId":2,"serviceStatus":3}`)
+	if got["success"] != true {
+		t.Fatalf("authorized update: %v", got)
+	}
+}
+func TestSupportCalendarDeploymentAndTeamPermissionsDoNotOverlap(t *testing.T) {
+	db := availabilityHandlerDB(t)
+	principal := &dto.AuthPrincipal{UserID: 1, Username: "one", Permissions: []string{constants.PermissionAgentTeamScheduleUpdate.Code}}
+	got := callAvailabilityHandler(t, SupportAvailabilityPostCalendar, principal, `{"teamId":0,"mode":"recurring","timezone":"Europe/Berlin","weekly":[],"exceptions":[]}`)
+	if got["success"] == true {
+		t.Fatal("team editor changed deployment default")
+	}
+	principal.Permissions = []string{constants.PermissionSupportConfigUpdate.Code}
+	got = callAvailabilityHandler(t, SupportAvailabilityPostCalendar, principal, `{"teamId":1,"mode":"recurring","timezone":"Europe/Berlin","weekly":[],"exceptions":[]}`)
+	if got["success"] == true {
+		t.Fatal("deployment editor changed team schedule")
+	}
+	var count int64
+	db.Model(&models.SupportCalendar{}).Count(&count)
+	if count != 0 {
+		t.Fatal("denied mutations persisted")
+	}
+}