feat(backthink/admin): ③b — rag/delete 真实现 + D1 推送出口钩子(自建优先→个推兜底) + api-reference 补 D2/D3/D5 补丁

- B5: POST /admin/rag/delete 真做(DeleteDocument→DeleteProject 级联删章节+索引清理, owner+审计, 200/404/500, 500降级兜底); users/iot scenarios+rules 诚实501(无用户表/IoT场景规则模型, 消息写明缺什么, 不伪造), 锁住 501+not_implemented
- D1: backthink/push_outlet.go PushExporter{Export}; pushOutlet 自建HTTP(2xx=送达, token仅Authorization头+error脱敏)优先→Getui兜底(未接入, 诚实日志'getui not integrated'+(false,nil)); backthink.Deps.Exporter → pusher.withExporter, Push 在WS/IM后 exportAsync(detached+5s超时, 失败仅日志, 不破坏现有投递, 限流不上报); config PushOutletConfig(PUSH_EXPORTER_* + GETUI_*占位)
- 前端 Rag.tsx/api.ts 删除后 reload + 类型; Docs/api-client v0.31 + api-reference(#23 owner/200-404, §8.4, 端点表PATCH/DELETE messages + pinned + messages?q=)
- 测试(push_outlet/admin_rag_delete/admin_honest501/knowledge store), 后端+前端build全绿+3平台交叉编译
- 刻意: Getui SDK 未接入(无SDK不硬造), 主人自建服务填 PUSH_EXPORTER_URL/TOKEN 即可

internal/services/gateway/admin.go

@@ -496,11 +496,6 @@ type ragQueryRequest struct {
 	Query string `json:"query"`
 }
 
-// ragDeleteRequest is the POST /api/v1/admin/rag/delete body.
-type ragDeleteRequest struct {
-	ID string `json:"id"`
-}
-
 // adminListRag lists the knowledge-base documents and, when ?query= is present,
 // returns the matching hits too. Without a wired RagStore it degrades to an empty
 // list (backward compatible — never a 500).
@@ -555,33 +550,6 @@ func (s *Server) adminSearchRag(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"query": req.Query, "hits": ragHitsFrom(hits)})
 }
 
-// adminDeleteRag answers the document delete honestly: write operations
-// (upload/chunk/embed/delete) are milestone M10, so it returns a clear 501 rather
-// than a fabricated success. The route is audited as an admin write.
-func (s *Server) adminDeleteRag(w http.ResponseWriter, r *http.Request) {
-	if s.rag == nil {
-		s.auditClaims(r, "rag.delete", "error")
-		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库 RAG 服务未配置（未注入 RagStore）", HTTPCode: http.StatusNotImplemented})
-		return
-	}
-	var req ragDeleteRequest
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid request body"))
-		return
-	}
-	if strings.TrimSpace(req.ID) == "" {
-		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "id is required"))
-		return
-	}
-	if err := s.rag.DeleteDocument(r.Context(), req.ID); err != nil {
-		s.auditClaims(r, "rag.delete", "error")
-		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库写操作（上传/分块/嵌入/删除）由 M10 后端提供", HTTPCode: http.StatusNotImplemented})
-		return
-	}
-	s.auditClaims(r, "rag.delete", "ok")
-	writeJSON(w, http.StatusOK, map[string]any{"id": req.ID})
-}
-
 // ragDocsFrom maps knowledge docs to their admin wire shape.
 func ragDocsFrom(docs []knowledge.Doc) []AdminRagDoc {
 	out := make([]AdminRagDoc, 0, len(docs))

internal/services/gateway/admin_honest501_test.go

@@ -0,0 +1,36 @@
+package gateway
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+)
+
+// TestAdminMissingStoreWritesHonest501 locks the B5 red line for the endpoints
+// whose backing store does not exist yet: they must answer 501 not_implemented
+// with an explanatory message, never a fabricated success. User creation has no
+// user table/login to persist into, and IoT has no scenario/rule model or store.
+func TestAdminMissingStoreWritesHonest501(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	cases := []string{
+		"/api/v1/admin/users",
+		"/api/v1/admin/iot/scenarios",
+		"/api/v1/admin/iot/rules",
+	}
+	for _, path := range cases {
+		resp, body := doReq(t, http.MethodPost, ts.URL+path, map[string]any{"name": "x"}, tok)
+		if resp.StatusCode != http.StatusNotImplemented {
+			t.Fatalf("%s status = %d, want 501 (body=%s)", path, resp.StatusCode, body)
+		}
+		wantErrorShape(t, body)
+		if !strings.Contains(string(body), "not_implemented") {
+			t.Fatalf("%s body = %s, want not_implemented code", path, body)
+		}
+	}
+}

internal/services/gateway/admin_rag_delete_test.go

@@ -0,0 +1,96 @@
+package gateway
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/knowledge"
+)
+
+// TestAdminRagDeleteRemovesDocument proves the delete write path is real: the
+// indexed document (project entry + its chapters) is gone from the list and the
+// search, and deleting it again answers 404 rather than a fabricated success.
+func TestAdminRagDeleteRemovesDocument(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	rag := newRagStoreForGateway(t)
+	if err := rag.IndexDocument(ctx, knowledge.Doc{
+		ID:      "doc-1",
+		Name:    "Cyrene 设计",
+		Desc:    "v2 设计文档",
+		Content: "第一段：项目描述。\n\n第二段：内部实现要点。",
+	}); err != nil {
+		t.Fatalf("IndexDocument: %v", err)
+	}
+
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: rag})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	resp, body := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("delete status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	var res struct {
+		ID      string `json:"id"`
+		Deleted bool   `json:"deleted"`
+	}
+	if err := json.Unmarshal(decodeBody(t, body)["data"], &res); err != nil {
+		t.Fatalf("decode: %v (body=%s)", err, body)
+	}
+	if res.ID != "doc-1" || !res.Deleted {
+		t.Fatalf("response = %+v, want id=doc-1 deleted=true", res)
+	}
+
+	docs, err := rag.ListDocuments(ctx)
+	if err != nil {
+		t.Fatalf("ListDocuments: %v", err)
+	}
+	if len(docs) != 0 {
+		t.Fatalf("documents = %+v, want empty after delete", docs)
+	}
+	hits, err := rag.Search(ctx, "内部实现")
+	if err != nil {
+		t.Fatalf("Search: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("hits = %+v, want none after delete", hits)
+	}
+
+	resp2, body2 := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp2.StatusCode != http.StatusNotFound {
+		t.Fatalf("second delete status = %d, want 404 (body=%s)", resp2.StatusCode, body2)
+	}
+	wantErrorShape(t, body2)
+}
+
+// TestAdminRagDeleteUnwired501 asserts an unconfigured RAG service still answers
+// honestly instead of pretending the document was removed.
+func TestAdminRagDeleteUnwired501(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	resp, body := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusNotImplemented {
+		t.Fatalf("status = %d, want 501 (body=%s)", resp.StatusCode, body)
+	}
+	wantErrorShape(t, body)
+}
+
+// TestAdminRagDeleteRequiresOwner asserts the write route stays owner-gated.
+func TestAdminRagDeleteRequiresOwner(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: newRagStoreForGateway(t)})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleAdmin)
+
+	resp, _ := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403", resp.StatusCode)
+	}
+}

internal/services/gateway/admin_write_iot_automations.go

@@ -56,17 +56,29 @@ func (s *Server) adminIoTControl(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, iotDeviceSummary{ID: dev.ID, Name: dev.Name, Type: dev.Type, State: dev.State, Online: dev.Online})
 }
 
-// adminIoTScenario answers honestly: the IoT subsystem has no scenario store yet
-// (it owns device list/control/status only), so scenario write lands in M10.
+// adminIoTScenario answers honestly: the IoT subsystem owns device
+// list/control/status only (the Provider interface has no scenario model or
+// store), so there is nothing to persist a scenario into. It reports the missing
+// store rather than fabricating one.
 func (s *Server) adminIoTScenario(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "iot.scenario", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "IoT 场景存储为 M10 提供（当前 IoT 仅有设备列表/控制/状态）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "IoT 场景未实现：IoT 子系统仅有设备列表/控制/状态（Provider 接口无场景模型与存储）；场景 CRUD 需先新增模型 + 执行器",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
-// adminIoTRule answers honestly: no IoT automation-rule store exists yet.
+// adminIoTRule answers honestly: no IoT automation-rule model or store exists
+// (the generic automations service runs cron/event rules, not device-state
+// conditions with device actions), so a rule cannot be persisted or executed.
 func (s *Server) adminIoTRule(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "iot.rule", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "IoT 自动化规则存储为 M10 提供（当前 IoT 仅有设备列表/控制/状态）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "IoT 自动化规则未实现：IoT 子系统无规则模型与存储（通用 automations 服务只跑 cron/事件规则，不含设备状态条件 + 设备动作执行器）",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
 // mapIotError maps iot sentinel errors to HTTP errors.

internal/services/gateway/admin_write_memory_rag.go

@@ -2,6 +2,7 @@ package gateway
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 
@@ -125,3 +126,45 @@ func (s *Server) adminIndexRag(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "rag.index", "ok")
 	writeJSON(w, http.StatusCreated, map[string]any{"name": name})
 }
+
+// ragDeleteRequest is the POST /api/v1/admin/rag/delete body.
+type ragDeleteRequest struct {
+	ID string `json:"id"`
+}
+
+// adminDeleteRag removes a knowledge document by id: the store deletes the
+// project-index entry and cascades its chapters. A missing document is answered
+// with 404, a store that cannot delete with a clear 501, and any other failure
+// with 500 — never a fabricated success. The route is owner-gated and audited.
+func (s *Server) adminDeleteRag(w http.ResponseWriter, r *http.Request) {
+	if s.rag == nil {
+		s.auditClaims(r, "rag.delete", "error")
+		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库 RAG 服务未配置（未注入 RagStore）", HTTPCode: http.StatusNotImplemented})
+		return
+	}
+	var req ragDeleteRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid request body"))
+		return
+	}
+	id := strings.TrimSpace(req.ID)
+	if id == "" {
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "id is required"))
+		return
+	}
+	if err := s.rag.DeleteDocument(r.Context(), id); err != nil {
+		s.auditClaims(r, "rag.delete", "error")
+		switch {
+		case errors.Is(err, knowledge.ErrDocumentNotFound):
+			writeError(w, apperr.Wrap(apperr.ErrNotFound, "not_found", "知识库文档 %q 不存在", id))
+		case errors.Is(err, knowledge.ErrWriteUnsupported):
+			writeError(w, &apperr.AppError{Code: "not_implemented", Message: "该知识库存储不支持删除", HTTPCode: http.StatusNotImplemented})
+		default:
+			s.log.Error("rag delete", "id", id, "err", err)
+			writeError(w, apperr.Wrap(apperr.ErrInternal, "rag_delete_failed", "failed to delete knowledge document"))
+		}
+		return
+	}
+	s.auditClaims(r, "rag.delete", "ok")
+	writeJSON(w, http.StatusOK, map[string]any{"id": id, "deleted": true})
+}

internal/services/gateway/admin_write_personas_users.go

@@ -132,12 +132,18 @@ func (s *Server) adminUpdatePersona(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, personaSummaryOf(p, characterFromRequest(req)))
 }
 
-// adminCreateUser answers honestly: there is no persistent user table yet (the
-// deployment is a single admin account + API keys), so user creation is deferred
-// to M10 rather than fabricated.
+// adminCreateUser answers honestly: there is no persistent user table and no
+// user-authenticated login to back one (the deployment is a single admin
+// account from .env plus runtime API keys; design/11 is single-user first), so
+// user creation would be a row nobody could log in with. It reports the missing
+// store instead of fabricating a user.
 func (s *Server) adminCreateUser(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "user.create", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "新增用户/角色存储为 M10 提供（当前为单 admin + APIKey 现状）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "新增用户/角色未实现：无用户表，登录仅用 .env 单 admin（ADMIN_USERNAME/PASSWORD），角色为 owner>admin>viewer 常量；多用户存储与登录接入需先设计（design/11 单用户为主）",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
 // apiKeyIssueRequest is the POST /api/v1/admin/users/apikey body.

internal/services/gateway/extra_test.go

@@ -1526,7 +1526,9 @@ func TestAdminRagEmptyWhenUnwired(t *testing.T) {
 	}
 }
 
-func TestAdminRagDeleteNotImplemented(t *testing.T) {
+// TestAdminRagDeleteUnsupportedStore501 asserts a store that cannot delete is
+// answered with an honest 501 rather than a fabricated success.
+func TestAdminRagDeleteUnsupportedStore501(t *testing.T) {
 	t.Parallel()
 	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: &stubRag{err: knowledge.ErrWriteUnsupported}})
 	_ = srv
@@ -1537,8 +1539,8 @@ func TestAdminRagDeleteNotImplemented(t *testing.T) {
 		t.Fatalf("status = %d, want 501 (body=%s)", resp.StatusCode, body)
 	}
 	wantErrorShape(t, body)
-	if !strings.Contains(string(body), "M10") {
-		t.Fatalf("error body = %s, want M10 write message", body)
+	if !strings.Contains(string(body), "not_implemented") {
+		t.Fatalf("error body = %s, want not_implemented code", body)
 	}
 }
 

internal/services/gateway/server.go

@@ -235,9 +235,11 @@ type OwnerRegistrar interface {
 }
 
 // RagStore backs the admin knowledge-base RAG module (design/10 §3.12 module 8).
-// *runtime/knowledge.Store is the production implementation. Every method is
-// read-only for this milestone: IndexDocument/DeleteDocument return a clear
-// "write lands in M10" error rather than a fabricated success.
+// *runtime/knowledge.Store is the production implementation: it lists/searches
+// the project index, imports a document (chunk + index) and deletes one
+// (project entry + cascaded chapters). An implementation that cannot write
+// reports a clear error (knowledge.ErrWriteUnsupported) rather than a fabricated
+// success; the handlers map a missing document to 404.
 type RagStore interface {
 	// ListDocuments enumerates the knowledge-base documents (project-index
 	// entries).
@@ -245,9 +247,10 @@ type RagStore interface {
 	// Search answers a knowledge-base query (line-level hierarchy + optional
 	// semantic/vector ranking).
 	Search(ctx context.Context, query string) ([]knowledge.Hit, error)
-	// IndexDocument uploads/chunks/embeds a document. M10; returns an error.
+	// IndexDocument uploads/chunks/embeds a document into the project index.
 	IndexDocument(ctx context.Context, doc knowledge.Doc) error
-	// DeleteDocument removes a document. M10; returns an error.
+	// DeleteDocument removes a document (and its chapters) by id, returning
+	// knowledge.ErrDocumentNotFound when no such document exists.
 	DeleteDocument(ctx context.Context, id string) error
 }
 
@@ -509,7 +512,6 @@ func (s *Server) Handler() http.Handler {
 	mux.Handle("GET /api/v1/admin/backthink", adminAuth(http.HandlerFunc(s.adminListBackthink)))
 	mux.Handle("GET /api/v1/admin/rag", adminAuth(http.HandlerFunc(s.adminListRag)))
 	mux.Handle("POST /api/v1/admin/rag/query", adminAuth(http.HandlerFunc(s.adminSearchRag)))
-	mux.Handle("POST /api/v1/admin/rag/delete", adminAuth(http.HandlerFunc(s.adminDeleteRag)))
 	mux.Handle("GET /api/v1/admin/observability/metrics", adminAuth(http.HandlerFunc(s.adminObservabilityMetrics)))
 	mux.Handle("GET /api/v1/admin/observability/trace", adminAuth(http.HandlerFunc(s.adminObservabilityTrace)))
 	mux.Handle("GET /api/v1/admin/observability/audit", adminAuth(http.HandlerFunc(s.adminObservabilityAudit)))
@@ -549,6 +551,7 @@ func (s *Server) Handler() http.Handler {
 	mux.Handle("POST /api/v1/admin/memories", ownerAuth(http.HandlerFunc(s.adminAddMemory)))
 	mux.Handle("POST /api/v1/admin/memories/search", ownerAuth(http.HandlerFunc(s.adminMemorySearch)))
 	mux.Handle("POST /api/v1/admin/rag", ownerAuth(http.HandlerFunc(s.adminIndexRag)))
+	mux.Handle("POST /api/v1/admin/rag/delete", ownerAuth(http.HandlerFunc(s.adminDeleteRag)))
 	mux.Handle("GET /api/v1/admin/sessions/{id}/export", adminAuth(http.HandlerFunc(s.adminExportSession)))
 	mux.Handle("POST /api/v1/admin/system/revoke-keys", ownerAuth(http.HandlerFunc(s.adminRevokeAllKeys)))
 	mux.Handle("POST /api/v1/admin/system/rotate-jwt", ownerAuth(http.HandlerFunc(s.adminRotateJWT)))