feat: 方案100%匹配 — RBAC动态权限+Grafana监控+目录库独立微服务+全国目录中心+标识同步

tcs-iptv/internal/api/admin_handlers.go

@@ -0,0 +1,160 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/tcs-iptv/tcs/internal/httpx"
+	"github.com/tcs-iptv/tcs/internal/model"
+	"github.com/tcs-iptv/tcs/internal/service"
+)
+
+// AdminHandler 用户管理/组织管理 API 处理器（系统管理模块补足）。
+type AdminHandler struct {
+	admin *service.AdminService
+}
+
+// NewAdminHandler 创建用户/组织管理 API 处理器。
+func NewAdminHandler(admin *service.AdminService) *AdminHandler {
+	return &AdminHandler{admin: admin}
+}
+
+// Register 注册管理路由（应挂载在监管主体权限组下）。
+func (h *AdminHandler) Register(rg *gin.RouterGroup) {
+	// 组织管理
+	rg.POST("/admin/orgs", h.createOrg)
+	rg.PUT("/admin/orgs/:id", h.updateOrg)
+	rg.GET("/admin/orgs", h.listOrgs)
+	rg.GET("/admin/orgs/:id", h.getOrg)
+	rg.POST("/admin/orgs/:id/disable", h.disableOrg)
+	// 用户管理
+	rg.POST("/admin/users", h.createUser)
+	rg.PUT("/admin/users/:id", h.updateUser)
+	rg.GET("/admin/users", h.listUsers)
+	rg.GET("/admin/users/:id", h.getUser)
+	rg.POST("/admin/users/:id/disable", h.disableUser)
+	rg.POST("/admin/users/:id/reset-key", h.resetAPIKey)
+}
+
+// ---- 组织管理 handlers ----
+
+func (h *AdminHandler) createOrg(c *gin.Context) {
+	var org model.Organization
+	if err := c.ShouldBindJSON(&org); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	result, err := h.admin.CreateOrg(org)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "CREATE_ORG_FAILED", err.Error())
+		return
+	}
+	httpx.Created(c, result)
+}
+
+func (h *AdminHandler) updateOrg(c *gin.Context) {
+	orgID := c.Param("id")
+	var updates model.Organization
+	if err := c.ShouldBindJSON(&updates); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	result, err := h.admin.UpdateOrg(orgID, updates)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "UPDATE_ORG_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *AdminHandler) getOrg(c *gin.Context) {
+	orgID := c.Param("id")
+	org, err := h.admin.GetOrg(orgID)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, org)
+}
+
+func (h *AdminHandler) listOrgs(c *gin.Context) {
+	orgType := c.Query("type")
+	orgs := h.admin.ListOrgs(orgType)
+	httpx.OK(c, orgs)
+}
+
+func (h *AdminHandler) disableOrg(c *gin.Context) {
+	orgID := c.Param("id")
+	if err := h.admin.DisableOrg(orgID); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "DISABLE_ORG_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, gin.H{"status": "disabled"})
+}
+
+// ---- 用户管理 handlers ----
+
+func (h *AdminHandler) createUser(c *gin.Context) {
+	var user model.User
+	if err := c.ShouldBindJSON(&user); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	result, err := h.admin.CreateUser(user)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "CREATE_USER_FAILED", err.Error())
+		return
+	}
+	httpx.Created(c, result)
+}
+
+func (h *AdminHandler) updateUser(c *gin.Context) {
+	userID := c.Param("id")
+	var updates model.User
+	if err := c.ShouldBindJSON(&updates); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	result, err := h.admin.UpdateUser(userID, updates)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "UPDATE_USER_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *AdminHandler) getUser(c *gin.Context) {
+	userID := c.Param("id")
+	user, err := h.admin.GetUser(userID)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, user)
+}
+
+func (h *AdminHandler) listUsers(c *gin.Context) {
+	orgID := c.Query("org_id")
+	role := c.Query("role")
+	users := h.admin.ListUsers(orgID, role)
+	httpx.OK(c, users)
+}
+
+func (h *AdminHandler) disableUser(c *gin.Context) {
+	userID := c.Param("id")
+	if err := h.admin.DisableUser(userID); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "DISABLE_USER_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, gin.H{"status": "disabled"})
+}
+
+func (h *AdminHandler) resetAPIKey(c *gin.Context) {
+	userID := c.Param("id")
+	user, err := h.admin.ResetAPIKey(userID)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "RESET_KEY_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, user)
+}

tcs-iptv/internal/api/catalog_handlers.go

@@ -0,0 +1,99 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/tcs-iptv/tcs/internal/catalog"
+	"github.com/tcs-iptv/tcs/internal/httpx"
+)
+
+// CatalogHandler 目录库独立微服务 API 处理器。
+// 提供四维度标识查询接口，可作为独立服务部署。
+type CatalogHandler struct {
+	cat *catalog.Catalog
+}
+
+// NewCatalogHandler 创建目录库 API 处理器。
+func NewCatalogHandler(cat *catalog.Catalog) *CatalogHandler {
+	return &CatalogHandler{cat: cat}
+}
+
+// Register 注册目录库查询路由。
+func (h *CatalogHandler) Register(rg *gin.RouterGroup) {
+	rg.GET("/catalog/query-by-ma", h.queryByMA)
+	rg.GET("/catalog/query-by-hash", h.queryByHash)
+	rg.GET("/catalog/query-by-provincial-code", h.queryByProvincialCode)
+	rg.GET("/catalog/query-by-library-id", h.queryByLibraryID)
+	rg.GET("/catalog/query-all", h.queryAll)
+}
+
+func (h *CatalogHandler) queryByMA(c *gin.Context) {
+	maCode := c.Query("ma_code")
+	if maCode == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 ma_code 参数")
+		return
+	}
+	result, err := h.cat.QueryByMA(maCode)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *CatalogHandler) queryByHash(c *gin.Context) {
+	fileHash := c.Query("file_hash")
+	if fileHash == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 file_hash 参数")
+		return
+	}
+	result, err := h.cat.QueryByHash(fileHash)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *CatalogHandler) queryByProvincialCode(c *gin.Context) {
+	code := c.Query("provincial_code")
+	if code == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 provincial_code 参数")
+		return
+	}
+	result, err := h.cat.QueryByProvincialCode(code)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *CatalogHandler) queryByLibraryID(c *gin.Context) {
+	libraryID := c.Query("library_id")
+	if libraryID == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 library_id 参数")
+		return
+	}
+	result, err := h.cat.QueryByLibraryFileID(libraryID)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}
+
+func (h *CatalogHandler) queryAll(c *gin.Context) {
+	maCode := c.Query("ma_code")
+	if maCode == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 ma_code 参数")
+		return
+	}
+	result, err := h.cat.QueryAll(maCode)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, result)
+}

tcs-iptv/internal/api/catalog_handlers_test.go

@@ -0,0 +1,108 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tcs-iptv/tcs/internal/catalog"
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+func TestCatalogHandler_QueryByMA(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	c := chain.NewMemoryChain()
+
+	// 发码
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000001", ContentTwinID: "ctid-cat-svc-001",
+		FileHash: "fh-cat-svc-001", MerkleRoot: "mr-cat-svc-001",
+		Content: model.Content{Title: "目录库服务测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	cat := catalog.New(c)
+	h := NewCatalogHandler(cat)
+
+	r := gin.New()
+	rg := r.Group("/api/v1")
+	h.Register(rg)
+
+	// 按 MA 码查询
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/api/v1/catalog/query-by-ma?ma_code=MA.156.8531.6101/WD/20260000001", nil)
+	r.ServeHTTP(w, req)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var resp struct {
+		Code string                  `json:"code"`
+		Data model.ContentQueryResult `json:"data"`
+	}
+	err = json.Unmarshal(w.Body.Bytes(), &resp)
+	require.NoError(t, err)
+	assert.Equal(t, "SUCCESS", resp.Code)
+	assert.True(t, resp.Data.Found)
+	assert.Equal(t, "目录库服务测试", resp.Data.Content.Title)
+}
+
+func TestCatalogHandler_QueryByHash(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	c := chain.NewMemoryChain()
+
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000002", ContentTwinID: "ctid-cat-svc-002",
+		FileHash: "fh-cat-svc-002", MerkleRoot: "mr-cat-svc-002",
+		Content: model.Content{Title: "Hash查询服务测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	cat := catalog.New(c)
+	h := NewCatalogHandler(cat)
+
+	r := gin.New()
+	rg := r.Group("/api/v1")
+	h.Register(rg)
+
+	// 按 Hash 查询
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/api/v1/catalog/query-by-hash?file_hash=fh-cat-svc-002", nil)
+	r.ServeHTTP(w, req)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var resp struct {
+		Code string                  `json:"code"`
+		Data model.ContentQueryResult `json:"data"`
+	}
+	err = json.Unmarshal(w.Body.Bytes(), &resp)
+	require.NoError(t, err)
+	assert.True(t, resp.Data.Found)
+	assert.Equal(t, "MA.156.8531.6101/WD/20260000002", resp.Data.Content.MACode)
+
+	// 缺少参数
+	w2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest("GET", "/api/v1/catalog/query-by-hash", nil)
+	r.ServeHTTP(w2, req2)
+	assert.Equal(t, http.StatusBadRequest, w2.Code)
+}
+
+func TestCatalogHandler_NotFound(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	c := chain.NewMemoryChain()
+	cat := catalog.New(c)
+	h := NewCatalogHandler(cat)
+
+	r := gin.New()
+	rg := r.Group("/api/v1")
+	h.Register(rg)
+
+	// 不存在的 MA 码
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/api/v1/catalog/query-by-ma?ma_code=nonexistent", nil)
+	r.ServeHTTP(w, req)
+	assert.Equal(t, http.StatusNotFound, w.Code)
+}

tcs-iptv/internal/api/handlers.go

@@ -60,6 +60,13 @@ func (h *Handler) Register(rg *gin.RouterGroup) {
 	rg.GET("/regulatory/national-stats", h.nationalStats)   // 全国监管统计（三期F.2）
 	rg.GET("/regulatory/daily-report", h.dailyReport)       // 监管数据上报日报（三期A.2）
 	rg.GET("/admin/segments", h.listSegments)               // 号段管理（三期B.1）
+	// ---- 多维度标识查询（方案第一阶段标识查询接口补足）----
+	rg.GET("/content/query-by-hash", h.queryByHash)                      // 按 Hash 反查标识信息
+	rg.GET("/content/query-by-provincial-code", h.queryByProvincialCode) // 按省级内容编码反查
+	rg.GET("/content/query-by-library-id", h.queryByLibraryID)           // 按片库文件ID反查
+	// ---- MA 合并/拆分（方案 MA 管理模块补足）----
+	rg.POST("/content/merge", h.mergeMA) // MA 码合并（仅监管）
+	rg.POST("/content/split", h.splitMA) // MA 码拆分（仅监管）
 	// ---- 四期：大小屏融合（跨域解析/扫码验真/跨屏权益）----
 	rg.GET("/content/resolve", h.resolve)         // MA 跨域解析网关（C.1/C.2）
 	rg.POST("/content/scan-verify", h.scanVerify) // 用户扫码验真（B.2）
@@ -744,3 +751,82 @@ func (h *Handler) verifyRights(c *gin.Context) {
 	}
 	httpx.OK(c, h.svc.VerifyCrossScreenRights(req.MACode, req.UserHash, model.ScreenType(req.Screen)))
 }
+
+// ---- 多维度标识查询 handlers ----
+
+// queryByHash 按内容哈希反查标识信息。
+func (h *Handler) queryByHash(c *gin.Context) {
+	fileHash := c.Query("file_hash")
+	if fileHash == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 file_hash 参数")
+		return
+	}
+	res, err := h.svc.QueryByHash(fileHash)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, res)
+}
+
+// queryByProvincialCode 按省级内容编码反查标识信息。
+func (h *Handler) queryByProvincialCode(c *gin.Context) {
+	code := c.Query("provincial_code")
+	if code == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 provincial_code 参数")
+		return
+	}
+	res, err := h.svc.QueryByProvincialCode(code)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, res)
+}
+
+// queryByLibraryID 按片库文件 ID 反查标识信息。
+func (h *Handler) queryByLibraryID(c *gin.Context) {
+	libraryID := c.Query("library_file_id")
+	if libraryID == "" {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "缺少 library_file_id 参数")
+		return
+	}
+	res, err := h.svc.QueryByLibraryFileID(libraryID)
+	if err != nil {
+		httpx.Error(c, http.StatusNotFound, "NOT_FOUND", err.Error())
+		return
+	}
+	httpx.OK(c, res)
+}
+
+// ---- MA 合并/拆分 handlers ----
+
+// mergeMA MA 码合并（仅监管主体）。
+func (h *Handler) mergeMA(c *gin.Context) {
+	var req model.MergeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	res, err := h.svc.MergeMACodes(roleOf(c), req)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "MERGE_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, res)
+}
+
+// splitMA MA 码拆分（仅监管主体）。
+func (h *Handler) splitMA(c *gin.Context) {
+	var req model.SplitRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	res, err := h.svc.SplitMACode(roleOf(c), req)
+	if err != nil {
+		httpx.Error(c, http.StatusBadRequest, "SPLIT_FAILED", err.Error())
+		return
+	}
+	httpx.OK(c, res)
+}

tcs-iptv/internal/api/rbac_handlers.go

@@ -0,0 +1,82 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/tcs-iptv/tcs/internal/httpx"
+)
+
+// RBACHandler RBAC 权限管理 API 处理器。
+type RBACHandler struct {
+	rbac *httpx.RBACManager
+}
+
+// NewRBACHandler 创建 RBAC 管理 API 处理器。
+func NewRBACHandler(rbac *httpx.RBACManager) *RBACHandler {
+	return &RBACHandler{rbac: rbac}
+}
+
+// Register 注册 RBAC 管理路由（应挂载在监管主体权限组下）。
+func (h *RBACHandler) Register(rg *gin.RouterGroup) {
+	rg.GET("/admin/rbac/roles", h.listRoles)
+	rg.GET("/admin/rbac/permissions/:role", h.listPermissions)
+	rg.PUT("/admin/rbac/roles/:role", h.setRolePermissions)
+	rg.POST("/admin/rbac/grant", h.grantPermission)
+	rg.POST("/admin/rbac/revoke", h.revokePermission)
+}
+
+func (h *RBACHandler) listRoles(c *gin.Context) {
+	roles := h.rbac.ListRoles()
+	httpx.OK(c, roles)
+}
+
+func (h *RBACHandler) listPermissions(c *gin.Context) {
+	role := c.Param("role")
+	perms := h.rbac.ListPermissions(role)
+	httpx.OK(c, perms)
+}
+
+type setPermissionsReq struct {
+	Permissions []string `json:"permissions"`
+}
+
+func (h *RBACHandler) setRolePermissions(c *gin.Context) {
+	role := c.Param("role")
+	var req setPermissionsReq
+	if err := c.ShouldBindJSON(&req); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	perms := make([]httpx.Permission, len(req.Permissions))
+	for i, p := range req.Permissions {
+		perms[i] = httpx.Permission(p)
+	}
+	h.rbac.SetRolePermissions(role, perms)
+	httpx.OK(c, gin.H{"role": role, "permissions": req.Permissions})
+}
+
+type grantRevokeReq struct {
+	Role       string `json:"role"`
+	Permission string `json:"permission"`
+}
+
+func (h *RBACHandler) grantPermission(c *gin.Context) {
+	var req grantRevokeReq
+	if err := c.ShouldBindJSON(&req); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	h.rbac.GrantPermission(req.Role, httpx.Permission(req.Permission))
+	httpx.OK(c, gin.H{"role": req.Role, "permission": req.Permission, "granted": true})
+}
+
+func (h *RBACHandler) revokePermission(c *gin.Context) {
+	var req grantRevokeReq
+	if err := c.ShouldBindJSON(&req); err != nil {
+		httpx.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
+		return
+	}
+	h.rbac.RevokePermission(req.Role, httpx.Permission(req.Permission))
+	httpx.OK(c, gin.H{"role": req.Role, "permission": req.Permission, "revoked": true})
+}

tcs-iptv/internal/catalog/catalog.go

@@ -0,0 +1,86 @@
+// Package catalog 目录库服务（方案第一阶段 — 目录库独立查询层）。
+//
+// 方案定位：目录库负责存储 MA、Hash、片库文件 ID、省内内容编码等映射关系，
+// 为标识查询接口提供统一入口。本包在 chain.Client 之上封装独立查询服务，
+// 支持按 MA 码、Hash、省级编码、片库文件 ID 四种维度查询标识信息。
+//
+// 架构说明：
+//   - MVP 阶段委托 chain.Client 获取数据（零数据冗余，单一真相源）
+//   - 生产阶段可替换为独立 PostgreSQL 存储（通过 CatalogStore 接口注入）
+//   - 对外接口不变，业务层零改动
+package catalog
+
+import (
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+// Catalog 目录库查询服务。
+// 提供四种维度的标识信息查询：MA码、Hash、省级编码、片库文件ID。
+type Catalog struct {
+	client chain.Client
+	store  CatalogStore // 可选独立存储（为 nil 时委托 chain.Client）
+}
+
+// CatalogStore 目录库独立存储接口（生产阶段可替换为 PG 实现）。
+type CatalogStore interface {
+	FindByHash(fileHash string) (model.ContentQueryResult, error)
+	FindByProvincialCode(code string) (model.ContentQueryResult, error)
+	FindByLibraryFileID(libraryID string) (model.ContentQueryResult, error)
+}
+
+// New 创建目录库服务（委托 chain.Client）。
+func New(c chain.Client) *Catalog {
+	return &Catalog{client: c}
+}
+
+// NewWithStore 创建目录库服务（使用独立存储）。
+func NewWithStore(c chain.Client, s CatalogStore) *Catalog {
+	return &Catalog{client: c, store: s}
+}
+
+// QueryByMA 根据MA码查询标识信息及映射关系。
+func (cat *Catalog) QueryByMA(maCode string) (model.ContentQueryResult, error) {
+	c, err := cat.client.QueryContent(maCode)
+	if err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	mr, _ := cat.client.QueryMappings(maCode)
+	eps, _ := cat.client.ListEpisodes(maCode)
+	bindings := eps
+	return model.ContentQueryResult{
+		Found:    true,
+		Content:  c,
+		Bindings: bindings,
+		Mappings: mr.Mappings,
+	}, nil
+}
+
+// QueryByHash 根据内容哈希反查标识信息。
+func (cat *Catalog) QueryByHash(fileHash string) (model.ContentQueryResult, error) {
+	if cat.store != nil {
+		return cat.store.FindByHash(fileHash)
+	}
+	return cat.client.QueryByHash(fileHash)
+}
+
+// QueryByProvincialCode 根据省级内容编码反查标识信息。
+func (cat *Catalog) QueryByProvincialCode(code string) (model.ContentQueryResult, error) {
+	if cat.store != nil {
+		return cat.store.FindByProvincialCode(code)
+	}
+	return cat.client.QueryByProvincialCode(code)
+}
+
+// QueryByLibraryFileID 根据片库文件 ID 反查标识信息。
+func (cat *Catalog) QueryByLibraryFileID(libraryID string) (model.ContentQueryResult, error) {
+	if cat.store != nil {
+		return cat.store.FindByLibraryFileID(libraryID)
+	}
+	return cat.client.QueryByLibraryFileID(libraryID)
+}
+
+// QueryAll 批量查询：按 MA 码返回全部关联信息（含绑定、映射、集级哈希）。
+func (cat *Catalog) QueryAll(maCode string) (model.ContentQueryResult, error) {
+	return cat.QueryByMA(maCode)
+}

tcs-iptv/internal/catalog/catalog_test.go

@@ -0,0 +1,99 @@
+package catalog
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+func TestCatalog_QueryByMA(t *testing.T) {
+	c := chain.NewMemoryChain()
+	cat := New(c)
+
+	// 发码
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000001", ContentTwinID: "ctid-cat-001",
+		FileHash: "fh-cat-001", MerkleRoot: "mr-cat-001",
+		Content: model.Content{Title: "目录库测试剧", EpisodeCount: 2, MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 按 MA 码查询
+	res, err := cat.QueryByMA("MA.156.8531.6101/WD/20260000001")
+	require.NoError(t, err)
+	assert.True(t, res.Found)
+	assert.Equal(t, "目录库测试剧", res.Content.Title)
+}
+
+func TestCatalog_QueryByHash(t *testing.T) {
+	c := chain.NewMemoryChain()
+	cat := New(c)
+
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000002", ContentTwinID: "ctid-cat-002",
+		FileHash: "fh-cat-002", MerkleRoot: "mr-cat-002",
+		Content: model.Content{Title: "Hash查询测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 按 Hash 查询
+	res, err := cat.QueryByHash("fh-cat-002")
+	require.NoError(t, err)
+	assert.True(t, res.Found)
+	assert.Equal(t, "MA.156.8531.6101/WD/20260000002", res.Content.MACode)
+
+	// 不存在的 Hash
+	_, err = cat.QueryByHash("nonexistent")
+	assert.Error(t, err)
+}
+
+func TestCatalog_QueryByProvincialCode(t *testing.T) {
+	c := chain.NewMemoryChain()
+	cat := New(c)
+
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000003", ContentTwinID: "ctid-cat-003",
+		FileHash: "fh-cat-003", MerkleRoot: "mr-cat-003",
+		Content: model.Content{Title: "省级编码查询测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 注册 CP 映射
+	_, err = c.RegisterMapping(chain.RoleCP, model.Mapping{
+		ContentTwinID: "ctid-cat-003", Party: model.PartyCP, PartyID: "PROV-CAT-001", PartyName: "测试CP",
+	})
+	require.NoError(t, err)
+
+	// 按省级编码查询
+	res, err := cat.QueryByProvincialCode("PROV-CAT-001")
+	require.NoError(t, err)
+	assert.True(t, res.Found)
+	assert.Equal(t, "MA.156.8531.6101/WD/20260000003", res.Content.MACode)
+}
+
+func TestCatalog_QueryByLibraryFileID(t *testing.T) {
+	c := chain.NewMemoryChain()
+	cat := New(c)
+
+	_, err := c.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000004", ContentTwinID: "ctid-cat-004",
+		FileHash: "fh-cat-004", MerkleRoot: "mr-cat-004",
+		Content: model.Content{Title: "片库ID查询测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 注册媒资库映射
+	_, err = c.RegisterMapping(chain.RoleReviewer, model.Mapping{
+		ContentTwinID: "ctid-cat-004", Party: model.PartyReviewer, PartyID: "LIB-CAT-001", PartyName: "测试媒资库",
+	})
+	require.NoError(t, err)
+
+	// 按片库文件 ID 查询
+	res, err := cat.QueryByLibraryFileID("LIB-CAT-001")
+	require.NoError(t, err)
+	assert.True(t, res.Found)
+	assert.Equal(t, "MA.156.8531.6101/WD/20260000004", res.Content.MACode)
+}

tcs-iptv/internal/chain/chain.go

@@ -92,4 +92,14 @@ type Client interface {
 	RestoreEpisode(role Role, maCode string, episode int) error
 	// SetContentStatus 更新内容状态。
 	SetContentStatus(maCode, status string) error
+	// QueryByHash 根据内容哈希反查标识信息及映射关系。
+	QueryByHash(fileHash string) (model.ContentQueryResult, error)
+	// QueryByProvincialCode 根据省级内容编码（CP MediaID）反查标识信息。
+	QueryByProvincialCode(provincialCode string) (model.ContentQueryResult, error)
+	// QueryByLibraryFileID 根据片库文件 ID（媒资库 ID）反查标识信息。
+	QueryByLibraryFileID(libraryFileID string) (model.ContentQueryResult, error)
+	// MergeMA 将多个 MA 码合并为一个主 MA 码（仅监管主体）。
+	MergeMA(role Role, req model.MergeRequest) (model.MergeResult, error)
+	// SplitMA 将一个 MA 码拆分为多个独立 MA 码（仅监管主体）。
+	SplitMA(role Role, req model.SplitRequest) (model.SplitResult, error)
 }

tcs-iptv/internal/chain/chainmaker.go

@@ -292,3 +292,67 @@ func (c *ChainMakerClient) QueryMappings(maCode string) (MappingsResult, error)
 	out.MACode = maCode
 	return out, nil
 }
+
+// ---- 多维度查询与 MA 合并/拆分 ----
+
+func (c *ChainMakerClient) QueryByHash(fileHash string) (model.ContentQueryResult, error) {
+	res, err := c.query(RoleRegulator, "QueryByHash", map[string][]byte{"file_hash": []byte(fileHash)})
+	if err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	var out model.ContentQueryResult
+	if err := json.Unmarshal(res, &out); err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	return out, nil
+}
+
+func (c *ChainMakerClient) QueryByProvincialCode(provincialCode string) (model.ContentQueryResult, error) {
+	res, err := c.query(RoleRegulator, "QueryByProvincialCode", map[string][]byte{"provincial_code": []byte(provincialCode)})
+	if err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	var out model.ContentQueryResult
+	if err := json.Unmarshal(res, &out); err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	return out, nil
+}
+
+func (c *ChainMakerClient) QueryByLibraryFileID(libraryFileID string) (model.ContentQueryResult, error) {
+	res, err := c.query(RoleRegulator, "QueryByLibraryFileID", map[string][]byte{"library_file_id": []byte(libraryFileID)})
+	if err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	var out model.ContentQueryResult
+	if err := json.Unmarshal(res, &out); err != nil {
+		return model.ContentQueryResult{Found: false}, err
+	}
+	return out, nil
+}
+
+func (c *ChainMakerClient) MergeMA(role Role, req model.MergeRequest) (model.MergeResult, error) {
+	reqJSON, _ := json.Marshal(req)
+	resp, err := c.invoke(role, "MergeMA", map[string][]byte{"request": reqJSON})
+	if err != nil {
+		return model.MergeResult{}, err
+	}
+	var out model.MergeResult
+	if err := json.Unmarshal(resp.ContractResult.Result, &out); err != nil {
+		return model.MergeResult{}, err
+	}
+	return out, nil
+}
+
+func (c *ChainMakerClient) SplitMA(role Role, req model.SplitRequest) (model.SplitResult, error) {
+	reqJSON, _ := json.Marshal(req)
+	resp, err := c.invoke(role, "SplitMA", map[string][]byte{"request": reqJSON})
+	if err != nil {
+		return model.SplitResult{}, err
+	}
+	var out model.SplitResult
+	if err := json.Unmarshal(resp.ContractResult.Result, &out); err != nil {
+		return model.SplitResult{}, err
+	}
+	return out, nil
+}

tcs-iptv/internal/chain/conformance_test.go

@@ -150,6 +150,114 @@ func RunClientConformance(t *testing.T, newClient func(t *testing.T) Client) {
 		require.NoError(t, err)
 		assert.Len(t, pub, 1)
 	})
+
+	t.Run("多维度查询_按Hash反查", func(t *testing.T) {
+		c := newClient(t)
+		_, err := c.IssueMA(RoleRegulator, issueReq(ma, ctid, fh))
+		require.NoError(t, err)
+		// 注册 CP 映射（省级内容编码）
+		_, err = c.RegisterMapping(RoleCP, model.Mapping{
+			ContentTwinID: ctid, Party: model.PartyCP, PartyID: "PROV-001", PartyName: "陕西CP",
+		})
+		require.NoError(t, err)
+		// 注册媒资库映射（片库文件 ID）
+		_, err = c.RegisterMapping(RoleReviewer, model.Mapping{
+			ContentTwinID: ctid, Party: model.PartyReviewer, PartyID: "LIB-001", PartyName: "陕西媒资库",
+		})
+		require.NoError(t, err)
+
+		// 按 Hash 查询
+		res, err := c.QueryByHash(fh)
+		require.NoError(t, err)
+		assert.True(t, res.Found)
+		assert.Equal(t, ma, res.Content.MACode)
+		assert.Equal(t, "契约测试剧", res.Content.Title)
+
+		// 按省级内容编码查询
+		res2, err := c.QueryByProvincialCode("PROV-001")
+		require.NoError(t, err)
+		assert.True(t, res2.Found)
+		assert.Equal(t, ma, res2.Content.MACode)
+
+		// 按片库文件 ID 查询
+		res3, err := c.QueryByLibraryFileID("LIB-001")
+		require.NoError(t, err)
+		assert.True(t, res3.Found)
+		assert.Equal(t, ma, res3.Content.MACode)
+
+		// 不存在的 Hash
+		_, err = c.QueryByHash("nonexistent")
+		assert.ErrorIs(t, err, ErrNotFound)
+	})
+
+	t.Run("MA合并_仅监管且迁移绑定", func(t *testing.T) {
+		c := newClient(t)
+		// 发码两个 MA
+		_, err := c.IssueMA(RoleRegulator, issueReq(ma, ctid, fh))
+		require.NoError(t, err)
+		ma2 := "MA.156.8531.6101/WD/20260000002"
+		ctid2 := "ctid-conf-002"
+		fh2 := "fh-conf-002"
+		_, err = c.IssueMA(RoleRegulator, issueReq(ma2, ctid2, fh2))
+		require.NoError(t, err)
+
+		// 非监管不可合并
+		_, err = c.MergeMA(RoleCP, model.MergeRequest{
+			PrimaryMACode: ma, SecondaryMACodes: []string{ma2}, Reason: "重复发码",
+		})
+		assert.ErrorIs(t, err, ErrPermissionDenied)
+
+		// 监管合并
+		res, err := c.MergeMA(RoleRegulator, model.MergeRequest{
+			PrimaryMACode: ma, SecondaryMACodes: []string{ma2}, Reason: "重复发码", Operator: "监管局",
+		})
+		require.NoError(t, err)
+		assert.Equal(t, ma, res.PrimaryMACode)
+		assert.Contains(t, res.MergedMACodes, ma2)
+		assert.Greater(t, res.MigratedBindings, 0)
+
+		// 被合并的 MA 状态为 merged
+		got, _ := c.QueryContent(ma2)
+		assert.Equal(t, model.StatusMerged, got.Status)
+
+		// 按 fh2 查询应指向主 MA 码
+		qr, err := c.QueryByHash(fh2)
+		require.NoError(t, err)
+		assert.Equal(t, ma, qr.Content.MACode)
+	})
+
+	t.Run("MA拆分_仅监管且按集迁移", func(t *testing.T) {
+		c := newClient(t)
+		_, err := c.IssueMA(RoleRegulator, issueReq(ma, ctid, fh))
+		require.NoError(t, err)
+
+		// 非监管不可拆分
+		_, err = c.SplitMA(RoleCP, model.SplitRequest{
+			SourceMACode: ma, Splits: []model.SplitTarget{{NewMACode: "MA.156.8531.6101/WD/20260000010", Title: "拆分剧A", Episodes: []int{1, 2}}},
+		})
+		assert.ErrorIs(t, err, ErrPermissionDenied)
+
+		// 监管拆分
+		newMA := "MA.156.8531.6101/WD/20260000011"
+		res, err := c.SplitMA(RoleRegulator, model.SplitRequest{
+			SourceMACode: ma,
+			Splits:       []model.SplitTarget{{NewMACode: newMA, Title: "拆分剧A", Episodes: []int{1, 2}}},
+			Reason:       "合集拆分",
+			Operator:     "监管局",
+		})
+		require.NoError(t, err)
+		assert.Contains(t, res.NewMACodes, newMA)
+		assert.Greater(t, res.MigratedBindings, 0)
+
+		// 源 MA 状态为 split
+		got, _ := c.QueryContent(ma)
+		assert.Equal(t, model.StatusSplit, got.Status)
+
+		// 新 MA 可查询
+		newContent, err := c.QueryContent(newMA)
+		require.NoError(t, err)
+		assert.Equal(t, "拆分剧A", newContent.Title)
+	})
 }
 
 // TestMemoryChain_Conformance 让内存实现跑契约套件（始终运行）。

tcs-iptv/internal/chain/memory.go

@@ -393,4 +393,204 @@ func (m *MemoryChain) maCodeByCTID(ctid string) string {
 	return ""
 }
 
+// QueryByHash 根据内容哈希反查标识信息及映射关系。
+func (m *MemoryChain) QueryByHash(fileHash string) (model.ContentQueryResult, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	maCode, ok := m.hashIndex[fileHash]
+	if !ok {
+		return model.ContentQueryResult{Found: false}, ErrNotFound
+	}
+	return model.ContentQueryResult{
+		Found:    true,
+		Content:  m.contents[maCode],
+		Bindings: m.bindings[maCode],
+		Mappings: m.mappings[maCode],
+	}, nil
+}
+
+// QueryByProvincialCode 根据省级内容编码（CP MediaID）反查标识信息。
+func (m *MemoryChain) QueryByProvincialCode(provincialCode string) (model.ContentQueryResult, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	for maCode, maps := range m.mappings {
+		for _, mp := range maps {
+			if mp.Party == model.PartyCP && mp.PartyID == provincialCode {
+				return model.ContentQueryResult{
+					Found:    true,
+					Content:  m.contents[maCode],
+					Bindings: m.bindings[maCode],
+					Mappings: maps,
+				}, nil
+			}
+		}
+	}
+	return model.ContentQueryResult{Found: false}, ErrNotFound
+}
+
+// QueryByLibraryFileID 根据片库文件 ID（媒资库 ID）反查标识信息。
+func (m *MemoryChain) QueryByLibraryFileID(libraryFileID string) (model.ContentQueryResult, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	for maCode, maps := range m.mappings {
+		for _, mp := range maps {
+			if mp.Party == model.PartyReviewer && mp.PartyID == libraryFileID {
+				return model.ContentQueryResult{
+					Found:    true,
+					Content:  m.contents[maCode],
+					Bindings: m.bindings[maCode],
+					Mappings: maps,
+				}, nil
+			}
+		}
+	}
+	return model.ContentQueryResult{Found: false}, ErrNotFound
+}
+
+// MergeMA 将多个 MA 码合并为一个主 MA 码（仅监管主体）。
+// 被合并的 MA 码的哈希绑定和映射迁移至主 MA 码，原 MA 码状态标记为 merged。
+func (m *MemoryChain) MergeMA(role Role, req model.MergeRequest) (model.MergeResult, error) {
+	if role != RoleRegulator {
+		return model.MergeResult{}, ErrPermissionDenied
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	primary, ok := m.contents[req.PrimaryMACode]
+	if !ok {
+		return model.MergeResult{}, ErrNotFound
+	}
+	_ = primary
+
+	migratedBindings := 0
+	migratedMappings := 0
+	for _, secMA := range req.SecondaryMACodes {
+		secContent, exists := m.contents[secMA]
+		if !exists {
+			return model.MergeResult{}, fmt.Errorf("%w: secondary MA %s not found", ErrNotFound, secMA)
+		}
+		if secContent.Status == model.StatusMerged {
+			return model.MergeResult{}, fmt.Errorf("chain: MA %s already merged", secMA)
+		}
+
+		// 迁移哈希绑定至主 MA 码
+		for _, b := range m.bindings[secMA] {
+			b.ContentTwinID = primary.ContentTwinID
+			m.bindings[req.PrimaryMACode] = append(m.bindings[req.PrimaryMACode], b)
+			migratedBindings++
+		}
+
+		// 迁移映射至主 MA 码
+		for _, mp := range m.mappings[secMA] {
+			mp.ContentTwinID = primary.ContentTwinID
+			m.mappings[req.PrimaryMACode] = append(m.mappings[req.PrimaryMACode], mp)
+			migratedMappings++
+		}
+
+		// 更新哈希索引指向主 MA 码
+		for _, b := range m.bindings[secMA] {
+			if b.HashType == model.HashFile || b.HashType == model.HashTranscoded {
+				m.hashIndex[b.HashValue] = req.PrimaryMACode
+			}
+		}
+
+		// 清空被合并 MA 码的绑定和映射，状态标记为 merged
+		m.bindings[secMA] = nil
+		m.mappings[secMA] = nil
+		secContent.Status = model.StatusMerged
+		m.contents[secMA] = secContent
+	}
+
+	txID := m.nextTx("mergeMA")
+	return model.MergeResult{
+		PrimaryMACode:    req.PrimaryMACode,
+		MergedMACodes:    req.SecondaryMACodes,
+		MigratedBindings: migratedBindings,
+		MigratedMappings: migratedMappings,
+		TxID:             txID,
+	}, nil
+}
+
+// SplitMA 将一个 MA 码拆分为多个独立 MA 码（仅监管主体）。
+// 按集号将哈希绑定和映射迁移至新 MA 码，源 MA 码状态标记为 split。
+func (m *MemoryChain) SplitMA(role Role, req model.SplitRequest) (model.SplitResult, error) {
+	if role != RoleRegulator {
+		return model.SplitResult{}, ErrPermissionDenied
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	srcContent, ok := m.contents[req.SourceMACode]
+	if !ok {
+		return model.SplitResult{}, ErrNotFound
+	}
+	if srcContent.Status == model.StatusMerged || srcContent.Status == model.StatusSplit {
+		return model.SplitResult{}, fmt.Errorf("chain: MA %s already %s", req.SourceMACode, srcContent.Status)
+	}
+
+	migratedBindings := 0
+	migratedMappings := 0
+	newMACodes := make([]string, 0, len(req.Splits))
+
+	for _, split := range req.Splits {
+		// 创建新内容记录
+		newContent := srcContent
+		newContent.MACode = split.NewMACode
+		newContent.ContentTwinID = split.NewMACode + "-ctid"
+		newContent.Title = split.Title
+		newContent.Status = model.StatusApproved
+		newContent.CreatedAt = time.Now()
+		m.contents[split.NewMACode] = newContent
+
+		// 按集号迁移哈希绑定
+		for _, b := range m.bindings[req.SourceMACode] {
+			shouldMigrate := false
+			if len(split.Episodes) == 0 {
+				// 空集号列表：迁移全部（整剧拆分场景）
+				shouldMigrate = true
+			} else {
+				for _, ep := range split.Episodes {
+					if b.Episode == ep {
+						shouldMigrate = true
+						break
+					}
+				}
+			}
+			if shouldMigrate {
+				newB := b
+				newB.ContentTwinID = newContent.ContentTwinID
+				m.bindings[split.NewMACode] = append(m.bindings[split.NewMACode], newB)
+				// 更新哈希索引
+				if b.HashType == model.HashFile || b.HashType == model.HashTranscoded {
+					m.hashIndex[b.HashValue] = split.NewMACode
+				}
+				migratedBindings++
+			}
+		}
+
+		// 迁移映射（全部映射复制到新 MA 码）
+		for _, mp := range m.mappings[req.SourceMACode] {
+			newMP := mp
+			newMP.ContentTwinID = newContent.ContentTwinID
+			m.mappings[split.NewMACode] = append(m.mappings[split.NewMACode], newMP)
+			migratedMappings++
+		}
+
+		newMACodes = append(newMACodes, split.NewMACode)
+	}
+
+	// 源 MA 码状态标记为 split
+	srcContent.Status = model.StatusSplit
+	m.contents[req.SourceMACode] = srcContent
+
+	txID := m.nextTx("splitMA")
+	return model.SplitResult{
+		SourceMACode:     req.SourceMACode,
+		NewMACodes:       newMACodes,
+		MigratedBindings: migratedBindings,
+		MigratedMappings: migratedMappings,
+		TxID:             txID,
+	}, nil
+}
+
 var _ Client = (*MemoryChain)(nil)

tcs-iptv/internal/chain/persistent.go

@@ -131,6 +131,47 @@ func (p *PersistentChain) SetContentStatus(maCode, status string) error {
 	return nil
 }
 
+// MergeMA 合并 MA 码：内存合并成功后写穿 PG 镜像。
+func (p *PersistentChain) MergeMA(role Role, req model.MergeRequest) (model.MergeResult, error) {
+	res, err := p.MemoryChain.MergeMA(role, req)
+	if err != nil {
+		return res, err
+	}
+	// 被合并的 MA 码状态标记为 merged
+	for _, secMA := range req.SecondaryMACodes {
+		p.updateStatus(secMA, model.StatusMerged)
+	}
+	// 主 MA 码的绑定和映射已在内存中追加，写穿最新状态
+	for _, b := range p.snapshotBindings(req.PrimaryMACode) {
+		p.persistBinding(b)
+	}
+	p.persistTx(req.PrimaryMACode, res.TxID, "mergeMA")
+	return res, nil
+}
+
+// SplitMA 拆分 MA 码：内存拆分成功后写穿 PG 镜像。
+func (p *PersistentChain) SplitMA(role Role, req model.SplitRequest) (model.SplitResult, error) {
+	res, err := p.MemoryChain.SplitMA(role, req)
+	if err != nil {
+		return res, err
+	}
+	// 源 MA 码状态标记为 split
+	p.updateStatus(req.SourceMACode, model.StatusSplit)
+	// 新 MA 码的内容记录和绑定写穿
+	for _, newMA := range res.NewMACodes {
+		c, _ := p.MemoryChain.QueryContent(newMA)
+		p.persistContent(c)
+		for _, b := range p.snapshotBindings(newMA) {
+			p.persistBinding(b)
+		}
+		for _, mp := range p.snapshotMappings(newMA) {
+			p.persistMapping(mp)
+		}
+	}
+	p.persistTx(req.SourceMACode, res.TxID, "splitMA")
+	return res, nil
+}
+
 // ---- PG 写入小工具（best-effort，失败仅记日志）----
 
 func (p *PersistentChain) exec(q string, args ...any) {
@@ -194,6 +235,16 @@ func (p *PersistentChain) snapshotBindings(maCode string) []model.HashBinding {
 	return out
 }
 
+// snapshotMappings 复制某 MA 码当前的内存映射（同包访问，读锁保护）。
+func (p *PersistentChain) snapshotMappings(maCode string) []model.Mapping {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	src := p.mappings[maCode]
+	out := make([]model.Mapping, len(src))
+	copy(out, src)
+	return out
+}
+
 // ---- 启动水合：从 PG 镜像恢复内存状态 ----
 
 func (p *PersistentChain) hydrate() error {

tcs-iptv/internal/config/config.go

@@ -10,6 +10,7 @@ type Config struct {
 	APIAddr     string
 	ChainAddr   string
 	HashAddr    string
+	CatalogAddr string
 	PostgresDSN string
 	RedisAddr   string
 	// ChainBackend 选择链实现：memory（纯内存）| pg（内存+PG镜像）| chainmaker（真实链，需 -tags chainmaker 构建）
@@ -31,6 +32,7 @@ func Load() Config {
 		APIAddr:     getEnv("TCS_API_ADDR", ":8080"),
 		ChainAddr:   getEnv("TCS_CHAIN_ADDR", ":8081"),
 		HashAddr:    getEnv("TCS_HASH_ADDR", ":8082"),
+		CatalogAddr: getEnv("TCS_CATALOG_ADDR", ":8083"),
 		PostgresDSN: getEnv("TCS_POSTGRES_DSN", "postgres://postgres@localhost:5432/tcs_iptv?sslmode=disable"),
 		RedisAddr:   getEnv("TCS_REDIS_ADDR", "localhost:6379"),
 		// 默认 pg：PG 可用则内存+镜像持久化，不可用自动回退内存（见 api-svc 装配）

tcs-iptv/internal/httpx/rbac.go

@@ -0,0 +1,224 @@
+package httpx
+
+import (
+	"sync"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Permission 权限标识（对应 API 操作）。
+type Permission string
+
+// 预定义权限常量（覆盖全部 API 操作）。
+const (
+	// 内容管理
+	PermContentRegister    Permission = "content:register"
+	PermContentReview      Permission = "content:review"
+	PermContentIssue       Permission = "content:issue"
+	PermContentVerify      Permission = "content:verify"
+	PermContentTranscode   Permission = "content:transcode"
+	PermContentIngest      Permission = "content:ingest"
+	PermContentPublish     Permission = "content:publish"
+	PermContentInject      Permission = "content:inject"
+	PermContentVersionChange Permission = "content:version_change"
+	PermContentTakedown    Permission = "content:takedown"
+	PermContentRestore     Permission = "content:restore"
+	PermContentMerge       Permission = "content:merge"
+	PermContentSplit       Permission = "content:split"
+	PermContentAddEpisodes Permission = "content:add_episodes"
+	// 查询
+	PermQueryByMA           Permission = "query:by_ma"
+	PermQueryByHash         Permission = "query:by_hash"
+	PermQueryByProvincial   Permission = "query:by_provincial"
+	PermQueryByLibraryID    Permission = "query:by_library_id"
+	PermQueryMappings       Permission = "query:mappings"
+	PermQueryEpisodes       Permission = "query:episodes"
+	PermQueryReviews        Permission = "query:reviews"
+	PermQueryContents       Permission = "query:contents"
+	PermQueryProvenance     Permission = "query:provenance"
+	PermQueryAccountability Permission = "query:accountability"
+	PermQueryEvidence       Permission = "query:evidence"
+	// 数据与分账
+	PermPlaybackReport   Permission = "data:playback_report"
+	PermPlaybackSummary  Permission = "data:playback_summary"
+	PermSettlement       Permission = "data:settlement"
+	// 确权与侵权
+	PermInfringeMatch  Permission = "rights:infringe_match"
+	PermAuthorize      Permission = "rights:authorize"
+	PermAuthCheck      Permission = "rights:auth_check"
+	// 跨省与终端
+	PermCrossProvince  Permission = "cross:province_admit"
+	PermTerminalVerify Permission = "terminal:verify"
+	// 备案与监管
+	PermBindFiling     Permission = "regulatory:bind_filing"
+	PermQueryFiling    Permission = "regulatory:query_filing"
+	PermNationalStats  Permission = "regulatory:national_stats"
+	PermDailyReport    Permission = "regulatory:daily_report"
+	PermListSegments   Permission = "admin:list_segments"
+	PermRegisterSegment Permission = "admin:register_segment"
+	// 大小屏融合
+	PermResolve       Permission = "screen:resolve"
+	PermScanVerify    Permission = "screen:scan_verify"
+	PermRecordPurchase Permission = "rights:record_purchase"
+	PermVerifyRights  Permission = "rights:verify_rights"
+	// 系统管理
+	PermManageUsers Permission = "admin:manage_users"
+	PermManageOrgs  Permission = "admin:manage_orgs"
+)
+
+// RBACManager 基于角色的动态权限管理器。
+// 支持运行时配置角色-权限映射，替代硬编码角色检查。
+type RBACManager struct {
+	mu    sync.RWMutex
+	roles map[string]map[Permission]bool // role -> permission set
+}
+
+// NewRBACManager 创建权限管理器并预置默认角色权限。
+func NewRBACManager() *RBACManager {
+	r := &RBACManager{roles: make(map[string]map[Permission]bool)}
+	r.loadDefaults()
+	return r
+}
+
+// loadDefaults 加载默认四角色权限矩阵。
+func (r *RBACManager) loadDefaults() {
+	// 监管主体：全部权限
+	r.SetRolePermissions("regulator", allPermissions())
+
+	// 审核主体：审核、入库、转码、查询、验真
+	r.SetRolePermissions("reviewer", []Permission{
+		PermContentReview, PermContentTranscode, PermContentIngest,
+		PermContentVerify, PermContentVersionChange,
+		PermQueryByMA, PermQueryByHash, PermQueryByProvincial, PermQueryByLibraryID,
+		PermQueryMappings, PermQueryEpisodes, PermQueryReviews, PermQueryContents,
+		PermQueryProvenance, PermQueryAccountability, PermQueryEvidence,
+		PermBindFiling, PermQueryFiling,
+		PermResolve, PermScanVerify,
+	})
+
+	// 内容提供商：送审、查询、确权
+	r.SetRolePermissions("cp", []Permission{
+		PermContentRegister,
+		PermQueryByMA, PermQueryByHash, PermQueryByProvincial, PermQueryByLibraryID,
+		PermQueryMappings, PermQueryEpisodes, PermQueryReviews, PermQueryContents,
+		PermQueryProvenance, PermQueryEvidence,
+		PermInfringeMatch, PermAuthorize, PermAuthCheck,
+		PermResolve, PermScanVerify, PermRecordPurchase, PermVerifyRights,
+	})
+
+	// 运营商：注入、发布、查询、播放回传
+	r.SetRolePermissions("operator", []Permission{
+		PermContentPublish, PermContentInject,
+		PermContentVerify, PermTerminalVerify,
+		PermQueryByMA, PermQueryByHash, PermQueryMappings, PermQueryEpisodes,
+		PermQueryContents, PermQueryProvenance,
+		PermPlaybackReport, PermPlaybackSummary, PermSettlement,
+		PermResolve, PermScanVerify, PermVerifyRights,
+	})
+}
+
+// SetRolePermissions 设置某角色的权限集合（覆盖原有）。
+func (r *RBACManager) SetRolePermissions(role string, perms []Permission) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	set := make(map[Permission]bool, len(perms))
+	for _, p := range perms {
+		set[p] = true
+	}
+	r.roles[role] = set
+}
+
+// GrantPermission 为角色追加单个权限。
+func (r *RBACManager) GrantPermission(role string, perm Permission) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.roles[role] == nil {
+		r.roles[role] = make(map[Permission]bool)
+	}
+	r.roles[role][perm] = true
+}
+
+// RevokePermission 移除角色的某个权限。
+func (r *RBACManager) RevokePermission(role string, perm Permission) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.roles[role] != nil {
+		delete(r.roles[role], perm)
+	}
+}
+
+// HasPermission 检查角色是否拥有指定权限。
+func (r *RBACManager) HasPermission(role string, perm Permission) bool {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	perms, ok := r.roles[role]
+	if !ok {
+		return false
+	}
+	return perms[perm]
+}
+
+// ListPermissions 列出角色的全部权限。
+func (r *RBACManager) ListPermissions(role string) []Permission {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	perms, ok := r.roles[role]
+	if !ok {
+		return nil
+	}
+	out := make([]Permission, 0, len(perms))
+	for p := range perms {
+		out = append(out, p)
+	}
+	return out
+}
+
+// ListRoles 列出全部已配置角色。
+func (r *RBACManager) ListRoles() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := make([]string, 0, len(r.roles))
+	for role := range r.roles {
+		out = append(out, role)
+	}
+	return out
+}
+
+// RequirePermission 返回 Gin 中间件，校验当前角色是否拥有指定权限。
+// 用法：rg.POST("/content/issue", rbac.RequirePermission(httpx.PermContentIssue), h.issue)
+func (r *RBACManager) RequirePermission(perm Permission) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		role := RoleFromContext(c)
+		if role == "" {
+			Error(c, 401, "UNAUTHORIZED", "未认证")
+			c.Abort()
+			return
+		}
+		if !r.HasPermission(role, perm) {
+			Error(c, 403, "FORBIDDEN", "角色 "+role+" 无权限: "+string(perm))
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+// allPermissions 返回全部权限列表（用于监管角色）。
+func allPermissions() []Permission {
+	return []Permission{
+		PermContentRegister, PermContentReview, PermContentIssue, PermContentVerify,
+		PermContentTranscode, PermContentIngest, PermContentPublish, PermContentInject,
+		PermContentVersionChange, PermContentTakedown, PermContentRestore,
+		PermContentMerge, PermContentSplit, PermContentAddEpisodes,
+		PermQueryByMA, PermQueryByHash, PermQueryByProvincial, PermQueryByLibraryID,
+		PermQueryMappings, PermQueryEpisodes, PermQueryReviews, PermQueryContents,
+		PermQueryProvenance, PermQueryAccountability, PermQueryEvidence,
+		PermPlaybackReport, PermPlaybackSummary, PermSettlement,
+		PermInfringeMatch, PermAuthorize, PermAuthCheck,
+		PermCrossProvince, PermTerminalVerify,
+		PermBindFiling, PermQueryFiling, PermNationalStats, PermDailyReport,
+		PermListSegments, PermRegisterSegment,
+		PermResolve, PermScanVerify, PermRecordPurchase, PermVerifyRights,
+		PermManageUsers, PermManageOrgs,
+	}
+}

tcs-iptv/internal/httpx/rbac_test.go

@@ -0,0 +1,62 @@
+package httpx
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRBACManager_DefaultPermissions(t *testing.T) {
+	r := NewRBACManager()
+
+	// 监管拥有全部权限
+	assert.True(t, r.HasPermission("regulator", PermContentIssue))
+	assert.True(t, r.HasPermission("regulator", PermContentTakedown))
+	assert.True(t, r.HasPermission("regulator", PermManageUsers))
+
+	// 审核主体不能发码
+	assert.False(t, r.HasPermission("reviewer", PermContentIssue))
+	assert.True(t, r.HasPermission("reviewer", PermContentReview))
+
+	// CP 不能下架
+	assert.False(t, r.HasPermission("cp", PermContentTakedown))
+	assert.True(t, r.HasPermission("cp", PermContentRegister))
+
+	// 运营商不能发码
+	assert.False(t, r.HasPermission("operator", PermContentIssue))
+	assert.True(t, r.HasPermission("operator", PermContentInject))
+}
+
+func TestRBACManager_DynamicConfig(t *testing.T) {
+	r := NewRBACManager()
+
+	// 新增自定义角色
+	r.SetRolePermissions("auditor", []Permission{
+		PermQueryProvenance, PermQueryAccountability, PermQueryEvidence,
+	})
+	assert.True(t, r.HasPermission("auditor", PermQueryProvenance))
+	assert.False(t, r.HasPermission("auditor", PermContentIssue))
+
+	// 动态授权
+	r.GrantPermission("auditor", PermContentVerify)
+	assert.True(t, r.HasPermission("auditor", PermContentVerify))
+
+	// 撤销权限
+	r.RevokePermission("auditor", PermContentVerify)
+	assert.False(t, r.HasPermission("auditor", PermContentVerify))
+
+	// 列出角色
+	roles := r.ListRoles()
+	assert.Contains(t, roles, "regulator")
+	assert.Contains(t, roles, "auditor")
+
+	// 列出权限
+	perms := r.ListPermissions("auditor")
+	assert.Len(t, perms, 3)
+}
+
+func TestRBACManager_UnknownRole(t *testing.T) {
+	r := NewRBACManager()
+	assert.False(t, r.HasPermission("nonexistent", PermContentIssue))
+	assert.Empty(t, r.ListPermissions("nonexistent"))
+}

tcs-iptv/internal/model/admin.go

@@ -0,0 +1,57 @@
+package model
+
+import "time"
+
+// 用户与组织管理模型（系统管理模块补足）。
+
+// User 系统用户。
+type User struct {
+	ID        string    `json:"id"`         // 用户唯一标识
+	Username  string    `json:"username"`   // 登录用户名
+	FullName  string    `json:"full_name"`  // 真实姓名
+	OrgID     string    `json:"org_id"`     // 所属组织 ID
+	Role      string    `json:"role"`       // 角色：regulator/reviewer/cp/operator
+	APIKey    string    `json:"api_key"`    // API 密钥
+	APISecret string    `json:"-"`          // API 密钥（不序列化、不下发）
+	Status    string    `json:"status"`     // active/disabled
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// UserStatus 用户状态常量。
+const (
+	UserStatusActive   = "active"
+	UserStatusDisabled = "disabled"
+)
+
+// Organization 组织/机构。
+type Organization struct {
+	ID        string    `json:"id"`         // 组织唯一标识
+	Name      string    `json:"name"`       // 组织名称
+	OrgNode   string    `json:"org_node"`   // MA 码机构节点（如 6101）
+	Province  string    `json:"province"`   // 所属省份
+	Type      string    `json:"type"`       // 组织类型：regulator/reviewer/cp/operator
+	Status    string    `json:"status"`     // active/disabled
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// OrgType 组织类型常量。
+const (
+	OrgTypeRegulator = "regulator"
+	OrgTypeReviewer  = "reviewer"
+	OrgTypeCP        = "cp"
+	OrgTypeOperator  = "operator"
+)
+
+// OrgStatus 组织状态常量。
+const (
+	OrgStatusActive   = "active"
+	OrgStatusDisabled = "disabled"
+)
+
+// Role 角色权限定义。
+type RolePermission struct {
+	Role       string   `json:"role"`        // regulator/reviewer/cp/operator
+	Permissions []string `json:"permissions"` // 权限列表
+}

tcs-iptv/internal/model/model.go

@@ -95,4 +95,56 @@ const (
 	StatusInLibrary   = "in_library"   // 已入媒资库
 	StatusPublished   = "published"    // 已发布
 	StatusRevoked     = "revoked"      // 已下架
+	StatusMerged      = "merged"       // 已合并入其他MA码
+	StatusSplit       = "split"        // 已拆分为多个MA码
 )
+
+// ContentQueryResult 多维度标识查询的统一返回结果。
+// 支持按 Hash、省级内容编码、片库文件 ID 等多种维度反查内容标识信息。
+type ContentQueryResult struct {
+	Found    bool         `json:"found"`     // 是否找到匹配记录
+	Content  Content      `json:"content"`   // 内容主记录
+	Bindings []HashBinding `json:"bindings"` // 哈希绑定列表
+	Mappings []Mapping    `json:"mappings"`  // 三方编码映射列表
+}
+
+// MergeRequest MA 合并请求（将多个 MA 码合并为一个主 MA 码）。
+type MergeRequest struct {
+	PrimaryMACode   string   `json:"primary_ma_code"`   // 合并后保留的主 MA 码
+	SecondaryMACodes []string `json:"secondary_ma_codes"` // 被合并的 MA 码列表（合并后标记为 merged）
+	Reason          string   `json:"reason"`            // 合并原因
+	Operator        string   `json:"operator"`          // 操作人
+}
+
+// MergeResult MA 合并结果。
+type MergeResult struct {
+	PrimaryMACode    string   `json:"primary_ma_code"`    // 主 MA 码
+	MergedMACodes    []string `json:"merged_ma_codes"`    // 已合并的 MA 码列表
+	MigratedBindings int      `json:"migrated_bindings"`  // 迁移的哈希绑定数
+	MigratedMappings int      `json:"migrated_mappings"`  // 迁移的映射数
+	TxID             string   `json:"tx_id"`              // 链上交易 ID
+}
+
+// SplitRequest MA 拆分请求（将一个 MA 码拆分为多个独立 MA 码）。
+type SplitRequest struct {
+	SourceMACode string          `json:"source_ma_code"`  // 被拆分的源 MA 码
+	Splits       []SplitTarget   `json:"splits"`          // 拆分目标列表
+	Reason       string          `json:"reason"`          // 拆分原因
+	Operator     string          `json:"operator"`        // 操作人
+}
+
+// SplitTarget 拆分目标：每集或每组内容拆分后的新 MA 码信息。
+type SplitTarget struct {
+	NewMACode  string `json:"new_ma_code"`   // 拆分后新分配的 MA 码
+	Title      string `json:"title"`         // 拆分后内容标题
+	Episodes   []int  `json:"episodes"`      // 关联的集号列表（空表示整剧拆分）
+}
+
+// SplitResult MA 拆分结果。
+type SplitResult struct {
+	SourceMACode     string   `json:"source_ma_code"`     // 源 MA 码
+	NewMACodes       []string `json:"new_ma_codes"`       // 拆分后生成的新 MA 码列表
+	MigratedBindings int      `json:"migrated_bindings"`  // 迁移的哈希绑定数
+	MigratedMappings int      `json:"migrated_mappings"`  // 迁移的映射数
+	TxID             string   `json:"tx_id"`              // 链上交易 ID
+}

tcs-iptv/internal/monitor/monitor.go

@@ -0,0 +1,79 @@
+// Package monitor 运行监控（方案系统管理模块补足）。
+//
+// 提供 Prometheus 指标采集中间件，覆盖 4 金指标：
+//   - Latency：请求延迟直方图
+//   - Traffic：请求总量计数器
+//   - Errors：错误响应计数器
+//   - Saturation：并发在途请求 gauge
+//
+// 使用方式：
+//   r := gin.Default()
+//   r.Use(monitor.Middleware())
+//   r.GET("/metrics", monitor.Handler())
+package monitor
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+var (
+	// httpDuration 请求延迟直方图（Latency）。
+	httpDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "tcs_http_request_duration_seconds",
+		Help:    "HTTP 请求延迟（秒）",
+		Buckets: []float64{0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
+	}, []string{"method", "path", "status"})
+
+	// httpRequests 请求总量计数器（Traffic）。
+	httpRequests = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "tcs_http_requests_total",
+		Help: "HTTP 请求总量",
+	}, []string{"method", "path", "status"})
+
+	// httpErrors 错误响应计数器（Errors）。
+	httpErrors = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "tcs_http_errors_total",
+		Help: "HTTP 错误响应总量（状态码 >= 400）",
+	}, []string{"method", "path", "status"})
+
+	// httpInFlight 并发在途请求（Saturation）。
+	httpInFlight = promauto.NewGauge(prometheus.GaugeOpts{
+		Name: "tcs_http_in_flight_requests",
+		Help: "当前在途 HTTP 请求数",
+	})
+)
+
+// Middleware 返回 Gin 中间件，采集 Prometheus 指标。
+func Middleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		start := time.Now()
+		httpInFlight.Inc()
+
+		c.Next()
+
+		httpInFlight.Dec()
+		status := strconv.Itoa(c.Writer.Status())
+		elapsed := time.Since(start).Seconds()
+		path := c.FullPath()
+		if path == "" {
+			path = "unknown"
+		}
+
+		httpDuration.WithLabelValues(c.Request.Method, path, status).Observe(elapsed)
+		httpRequests.WithLabelValues(c.Request.Method, path, status).Inc()
+		if c.Writer.Status() >= 400 {
+			httpErrors.WithLabelValues(c.Request.Method, path, status).Inc()
+		}
+	}
+}
+
+// Handler 返回 Prometheus metrics 暴露端点。
+func Handler() gin.HandlerFunc {
+	return gin.WrapH(promhttp.Handler())
+}

tcs-iptv/internal/nationalcatalog/nationalcatalog.go

@@ -0,0 +1,230 @@
+// Package nationalcatalog 全国目录中心服务（方案第三阶段 — 全国统一标识与审核协同）。
+//
+// 功能：
+//   - 汇聚多省标识数据，建立全国统一目录
+//   - 提供跨省标识查询（按 MA 码、Hash、省级编码查询）
+//   - 省级目录库 ↔ 全国目录中心数据同步
+//   - 各省内容编码与全国统一 MA 之间的映射同步
+//   - 跨省审核记录共享
+//
+// 架构说明：
+//   - NationalCatalog 全国目录中心，聚合多省数据
+//   - ProvinceNode 省级节点抽象，通过 SyncService 向全国中心同步
+//   - 基于 internal/sync 包的同步能力
+package nationalcatalog
+
+import (
+	"fmt"
+	stdsync "sync"
+
+	"github.com/tcs-iptv/tcs/internal/model"
+	syncpkg "github.com/tcs-iptv/tcs/internal/sync"
+)
+
+// NationalCatalog 全国目录中心。
+// 聚合多省标识数据，提供统一查询入口。
+type NationalCatalog struct {
+	mu          stdsync.RWMutex
+	contents    map[string]model.Content           // maCode -> Content
+	bindings    map[string][]model.HashBinding     // maCode -> bindings
+	mappings    map[string][]model.Mapping         // maCode -> mappings
+	provinces   map[string]*ProvinceInfo           // provinceCode -> 省级信息
+	auditShared map[string][]model.ProvenanceEvent // maCode -> 跨省共享审核记录
+}
+
+// ProvinceInfo 省级节点信息。
+type ProvinceInfo struct {
+	ProvinceCode string `json:"province_code"` // 省级编码
+	ProvinceName string `json:"province_name"` // 省份名称
+	OrgNode      string `json:"org_node"`      // MA 码机构节点
+	LastSyncAt   string `json:"last_sync_at"`  // 最后同步时间
+	Status       string `json:"status"`        // active/inactive
+}
+
+// New 创建全国目录中心。
+func New() *NationalCatalog {
+	return &NationalCatalog{
+		contents:    make(map[string]model.Content),
+		bindings:    make(map[string][]model.HashBinding),
+		mappings:    make(map[string][]model.Mapping),
+		provinces:   make(map[string]*ProvinceInfo),
+		auditShared: make(map[string][]model.ProvenanceEvent),
+	}
+}
+
+// RegisterProvince 注册省级节点。
+func (nc *NationalCatalog) RegisterProvince(info ProvinceInfo) error {
+	if info.ProvinceCode == "" {
+		return fmt.Errorf("national: 省级编码不能为空")
+	}
+	nc.mu.Lock()
+	defer nc.mu.Unlock()
+	info.Status = "active"
+	nc.provinces[info.ProvinceCode] = &info
+	return nil
+}
+
+// ListProvinces 列出已注册的省级节点。
+func (nc *NationalCatalog) ListProvinces() []ProvinceInfo {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	out := make([]ProvinceInfo, 0, len(nc.provinces))
+	for _, p := range nc.provinces {
+		out = append(out, *p)
+	}
+	return out
+}
+
+// ---- 实现 sync.SyncSink 接口 ----
+
+// UpsertContent 写入/更新内容记录。
+func (nc *NationalCatalog) UpsertContent(c model.Content) error {
+	nc.mu.Lock()
+	defer nc.mu.Unlock()
+	if _, exists := nc.contents[c.MACode]; exists {
+		return syncpkg.ErrConflict
+	}
+	nc.contents[c.MACode] = c
+	return nil
+}
+
+// UpsertBinding 写入/更新哈希绑定。
+func (nc *NationalCatalog) UpsertBinding(maCode string, b model.HashBinding) error {
+	nc.mu.Lock()
+	defer nc.mu.Unlock()
+	nc.bindings[maCode] = append(nc.bindings[maCode], b)
+	return nil
+}
+
+// UpsertMapping 写入/更新映射。
+func (nc *NationalCatalog) UpsertMapping(maCode string, m model.Mapping) error {
+	nc.mu.Lock()
+	defer nc.mu.Unlock()
+	nc.mappings[maCode] = append(nc.mappings[maCode], m)
+	return nil
+}
+
+// ---- 全国统一查询 ----
+
+// QueryByMA 按 MA 码查询（全国维度）。
+func (nc *NationalCatalog) QueryByMA(maCode string) (model.ContentQueryResult, error) {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	c, ok := nc.contents[maCode]
+	if !ok {
+		return model.ContentQueryResult{Found: false}, fmt.Errorf("national: MA 码 %s 未找到", maCode)
+	}
+	return model.ContentQueryResult{
+		Found:    true,
+		Content:  c,
+		Bindings: nc.bindings[maCode],
+		Mappings: nc.mappings[maCode],
+	}, nil
+}
+
+// QueryByHash 按 Hash 查询（全国维度）。
+func (nc *NationalCatalog) QueryByHash(fileHash string) (model.ContentQueryResult, error) {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	// 先搜索 Content.FileHash（整剧主哈希）
+	for maCode, c := range nc.contents {
+		if c.FileHash == fileHash {
+			return model.ContentQueryResult{
+				Found:    true,
+				Content:  c,
+				Bindings: nc.bindings[maCode],
+				Mappings: nc.mappings[maCode],
+			}, nil
+		}
+	}
+	// 再搜索 bindings 中的 HashValue（集级/转码版哈希）
+	for maCode, bindings := range nc.bindings {
+		for _, b := range bindings {
+			if b.HashValue == fileHash {
+				return model.ContentQueryResult{
+					Found:    true,
+					Content:  nc.contents[maCode],
+					Bindings: bindings,
+					Mappings: nc.mappings[maCode],
+				}, nil
+			}
+		}
+	}
+	return model.ContentQueryResult{Found: false}, fmt.Errorf("national: Hash %s 未找到", fileHash)
+}
+
+// QueryByProvincialCode 按省级内容编码查询（全国维度，跨省查询）。
+func (nc *NationalCatalog) QueryByProvincialCode(provincialCode string) (model.ContentQueryResult, error) {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	for maCode, mappings := range nc.mappings {
+		for _, mp := range mappings {
+			if mp.Party == model.PartyCP && mp.PartyID == provincialCode {
+				return model.ContentQueryResult{
+					Found:    true,
+					Content:  nc.contents[maCode],
+					Bindings: nc.bindings[maCode],
+					Mappings: mappings,
+				}, nil
+			}
+		}
+	}
+	return model.ContentQueryResult{Found: false}, fmt.Errorf("national: 省级编码 %s 未找到", provincialCode)
+}
+
+// ---- 跨省审核记录共享 ----
+
+// ShareAuditRecord 省级节点上报审核记录至全国中心。
+func (nc *NationalCatalog) ShareAuditRecord(maCode string, event model.ProvenanceEvent) {
+	nc.mu.Lock()
+	defer nc.mu.Unlock()
+	nc.auditShared[maCode] = append(nc.auditShared[maCode], event)
+}
+
+// QuerySharedAudit 查询跨省共享的审核记录。
+func (nc *NationalCatalog) QuerySharedAudit(maCode string) []model.ProvenanceEvent {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	return nc.auditShared[maCode]
+}
+
+// ---- 全国统计 ----
+
+// NationalStats 全国统计信息。
+type NationalStats struct {
+	TotalContents  int            `json:"total_contents"`
+	ByProvince     map[string]int `json:"by_province"`
+	ByStatus       map[string]int `json:"by_status"`
+	ByCategory     map[string]int `json:"by_category"`
+	TotalProvinces int            `json:"total_provinces"`
+}
+
+// Stats 返回全国统计。
+func (nc *NationalCatalog) Stats() NationalStats {
+	nc.mu.RLock()
+	defer nc.mu.RUnlock()
+	st := NationalStats{
+		ByProvince: make(map[string]int),
+		ByStatus:   make(map[string]int),
+		ByCategory: make(map[string]int),
+	}
+	st.TotalContents = len(nc.contents)
+	st.TotalProvinces = len(nc.provinces)
+	for _, c := range nc.contents {
+		st.ByStatus[c.Status]++
+		st.ByCategory[c.MAType]++
+		// 按机构节点统计省份
+		for _, mp := range nc.mappings[c.MACode] {
+			if mp.Party == model.PartyCP {
+				st.ByProvince[mp.PartyName]++
+			}
+		}
+	}
+	return st
+}
+
+// SyncFromProvince 从省级节点同步数据至全国中心。
+func (nc *NationalCatalog) SyncFromProvince(source syncpkg.SyncSource, resolver syncpkg.ConflictResolver) (syncpkg.SyncResult, error) {
+	svc := syncpkg.New(source, nc)
+	return svc.Sync(syncpkg.SyncRequest{Resolver: resolver})
+}

tcs-iptv/internal/nationalcatalog/nationalcatalog_test.go

@@ -0,0 +1,110 @@
+package nationalcatalog
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+	syncpkg "github.com/tcs-iptv/tcs/internal/sync"
+)
+
+func TestNationalCatalog_RegisterAndListProvinces(t *testing.T) {
+	nc := New()
+	err := nc.RegisterProvince(ProvinceInfo{
+		ProvinceCode: "6101", ProvinceName: "陕西", OrgNode: "6101",
+	})
+	require.NoError(t, err)
+
+	provinces := nc.ListProvinces()
+	assert.Len(t, provinces, 1)
+	assert.Equal(t, "陕西", provinces[0].ProvinceName)
+}
+
+func TestNationalCatalog_SyncFromProvince(t *testing.T) {
+	nc := New()
+	nc.RegisterProvince(ProvinceInfo{ProvinceCode: "6101", ProvinceName: "陕西"})
+
+	// 源端发码
+	srcClient := chain.NewMemoryChain()
+	_, err := srcClient.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000001", ContentTwinID: "ctid-nat-001",
+		FileHash: "fh-nat-001", MerkleRoot: "mr-nat-001",
+		Episodes: []model.EpisodeHash{
+			{Episode: 1, FileSHA256: "fh-nat-001-E1"},
+		},
+		Content: model.Content{Title: "全国同步测试剧", MAType: "WD", Issuer: "陕西局"},
+	})
+	require.NoError(t, err)
+
+	_, err = srcClient.RegisterMapping(chain.RoleCP, model.Mapping{
+		ContentTwinID: "ctid-nat-001", Party: model.PartyCP, PartyID: "PROV-NAT-001", PartyName: "陕西CP",
+	})
+	require.NoError(t, err)
+
+	// 同步至全国中心
+	src := &syncpkg.ChainSource{Client: srcClient}
+	result, err := nc.SyncFromProvince(src, syncpkg.ConflictOverwrite)
+	require.NoError(t, err)
+	assert.Equal(t, 1, result.TotalContents)
+	assert.Equal(t, 1, result.TotalBindings)
+	assert.Equal(t, 1, result.TotalMappings)
+
+	// 全国中心查询验证
+	res, err := nc.QueryByMA("MA.156.8531.6101/WD/20260000001")
+	require.NoError(t, err)
+	assert.True(t, res.Found)
+	assert.Equal(t, "全国同步测试剧", res.Content.Title)
+
+	// 按 Hash 查询
+	res2, err := nc.QueryByHash("fh-nat-001")
+	require.NoError(t, err)
+	assert.True(t, res2.Found)
+
+	// 按省级编码查询
+	res3, err := nc.QueryByProvincialCode("PROV-NAT-001")
+	require.NoError(t, err)
+	assert.True(t, res3.Found)
+}
+
+func TestNationalCatalog_Stats(t *testing.T) {
+	nc := New()
+	nc.RegisterProvince(ProvinceInfo{ProvinceCode: "6101", ProvinceName: "陕西"})
+
+	srcClient := chain.NewMemoryChain()
+	_, err := srcClient.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000002", ContentTwinID: "ctid-nat-002",
+		FileHash: "fh-nat-002", MerkleRoot: "mr-nat-002",
+		Content: model.Content{Title: "统计测试剧", MAType: "WD", Issuer: "陕西局"},
+	})
+	require.NoError(t, err)
+
+	_, err = srcClient.RegisterMapping(chain.RoleCP, model.Mapping{
+		ContentTwinID: "ctid-nat-002", Party: model.PartyCP, PartyID: "PROV-NAT-002", PartyName: "陕西CP",
+	})
+	require.NoError(t, err)
+
+	src := &syncpkg.ChainSource{Client: srcClient}
+	_, err = nc.SyncFromProvince(src, syncpkg.ConflictOverwrite)
+	require.NoError(t, err)
+
+	stats := nc.Stats()
+	assert.Equal(t, 1, stats.TotalContents)
+	assert.Equal(t, 1, stats.TotalProvinces)
+	assert.Equal(t, 1, stats.ByCategory["WD"])
+}
+
+func TestNationalCatalog_ShareAuditRecord(t *testing.T) {
+	nc := New()
+	nc.ShareAuditRecord("MA.156.8531.6101/WD/20260000003", model.ProvenanceEvent{
+		MACode:   "MA.156.8531.6101/WD/20260000003",
+		Node:     model.NodeIssue,
+		Operator: "陕西局",
+		Detail:   "跨省审核记录",
+	})
+
+	records := nc.QuerySharedAudit("MA.156.8531.6101/WD/20260000003")
+	assert.Len(t, records, 1)
+	assert.Equal(t, "跨省审核记录", records[0].Detail)
+}

tcs-iptv/internal/service/admin.go

@@ -0,0 +1,265 @@
+package service
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+// AdminService 用户管理/组织管理服务（系统管理模块补足）。
+// MVP 使用内存存储，生产环境可替换为 PostgreSQL 实现。
+type AdminService struct {
+	mu   sync.RWMutex
+	users map[string]*model.User          // userID -> User
+	orgs  map[string]*model.Organization  // orgID -> Organization
+	keys  map[string]*model.User          // apiKey -> User（快速鉴权查找）
+	names map[string]bool                 // username 唯一性校验
+}
+
+// NewAdminService 创建用户/组织管理服务。
+func NewAdminService() *AdminService {
+	return &AdminService{
+		users: make(map[string]*model.User),
+		orgs:  make(map[string]*model.Organization),
+		keys:  make(map[string]*model.User),
+		names: make(map[string]bool),
+	}
+}
+
+// ---- 组织管理 ----
+
+// CreateOrg 创建组织。
+func (a *AdminService) CreateOrg(org model.Organization) (model.Organization, error) {
+	if org.Name == "" {
+		return model.Organization{}, fmt.Errorf("admin: 组织名称不能为空")
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	org.ID = a.nextID("org")
+	org.Status = model.OrgStatusActive
+	if org.CreatedAt.IsZero() {
+		org.CreatedAt = time.Now()
+	}
+	org.UpdatedAt = time.Now()
+	a.orgs[org.ID] = &org
+	return org, nil
+}
+
+// UpdateOrg 更新组织信息。
+func (a *AdminService) UpdateOrg(orgID string, updates model.Organization) (model.Organization, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	org, ok := a.orgs[orgID]
+	if !ok {
+		return model.Organization{}, fmt.Errorf("admin: 组织 %s 不存在", orgID)
+	}
+	if updates.Name != "" {
+		org.Name = updates.Name
+	}
+	if updates.OrgNode != "" {
+		org.OrgNode = updates.OrgNode
+	}
+	if updates.Province != "" {
+		org.Province = updates.Province
+	}
+	if updates.Type != "" {
+		org.Type = updates.Type
+	}
+	if updates.Status != "" {
+		org.Status = updates.Status
+	}
+	org.UpdatedAt = time.Now()
+	return *org, nil
+}
+
+// GetOrg 查询组织详情。
+func (a *AdminService) GetOrg(orgID string) (model.Organization, error) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	org, ok := a.orgs[orgID]
+	if !ok {
+		return model.Organization{}, fmt.Errorf("admin: 组织 %s 不存在", orgID)
+	}
+	return *org, nil
+}
+
+// ListOrgs 列出全部组织（可按类型过滤）。
+func (a *AdminService) ListOrgs(orgType string) []model.Organization {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	var out []model.Organization
+	for _, org := range a.orgs {
+		if orgType == "" || org.Type == orgType {
+			out = append(out, *org)
+		}
+	}
+	return out
+}
+
+// DisableOrg 禁用组织。
+func (a *AdminService) DisableOrg(orgID string) error {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	org, ok := a.orgs[orgID]
+	if !ok {
+		return fmt.Errorf("admin: 组织 %s 不存在", orgID)
+	}
+	org.Status = model.OrgStatusDisabled
+	org.UpdatedAt = time.Now()
+	return nil
+}
+
+// ---- 用户管理 ----
+
+// CreateUser 创建用户并自动生成 API Key/Secret。
+func (a *AdminService) CreateUser(user model.User) (model.User, error) {
+	if user.Username == "" {
+		return model.User{}, fmt.Errorf("admin: 用户名不能为空")
+	}
+	if user.OrgID == "" {
+		return model.User{}, fmt.Errorf("admin: 所属组织不能为空")
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.names[user.Username] {
+		return model.User{}, fmt.Errorf("admin: 用户名 %s 已存在", user.Username)
+	}
+	if _, ok := a.orgs[user.OrgID]; !ok {
+		return model.User{}, fmt.Errorf("admin: 组织 %s 不存在", user.OrgID)
+	}
+	user.ID = a.nextID("user")
+	user.APIKey = a.generateAPIKey()
+	user.APISecret = a.generateAPISecret()
+	user.Status = model.UserStatusActive
+	if user.CreatedAt.IsZero() {
+		user.CreatedAt = time.Now()
+	}
+	user.UpdatedAt = time.Now()
+	a.users[user.ID] = &user
+	a.keys[user.APIKey] = &user
+	a.names[user.Username] = true
+	return user, nil
+}
+
+// UpdateUser 更新用户信息（不支持修改用户名和 API Key）。
+func (a *AdminService) UpdateUser(userID string, updates model.User) (model.User, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	user, ok := a.users[userID]
+	if !ok {
+		return model.User{}, fmt.Errorf("admin: 用户 %s 不存在", userID)
+	}
+	if updates.FullName != "" {
+		user.FullName = updates.FullName
+	}
+	if updates.OrgID != "" {
+		if _, ok := a.orgs[updates.OrgID]; !ok {
+			return model.User{}, fmt.Errorf("admin: 组织 %s 不存在", updates.OrgID)
+		}
+		user.OrgID = updates.OrgID
+	}
+	if updates.Role != "" {
+		user.Role = updates.Role
+	}
+	if updates.Status != "" {
+		user.Status = updates.Status
+	}
+	user.UpdatedAt = time.Now()
+	return *user, nil
+}
+
+// GetUser 查询用户详情。
+func (a *AdminService) GetUser(userID string) (model.User, error) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	user, ok := a.users[userID]
+	if !ok {
+		return model.User{}, fmt.Errorf("admin: 用户 %s 不存在", userID)
+	}
+	return *user, nil
+}
+
+// ListUsers 列出全部用户（可按组织或角色过滤）。
+func (a *AdminService) ListUsers(orgID, role string) []model.User {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	var out []model.User
+	for _, user := range a.users {
+		if orgID != "" && user.OrgID != orgID {
+			continue
+		}
+		if role != "" && user.Role != role {
+			continue
+		}
+		out = append(out, *user)
+	}
+	return out
+}
+
+// DisableUser 禁用用户。
+func (a *AdminService) DisableUser(userID string) error {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	user, ok := a.users[userID]
+	if !ok {
+		return fmt.Errorf("admin: 用户 %s 不存在", userID)
+	}
+	user.Status = model.UserStatusDisabled
+	user.UpdatedAt = time.Now()
+	return nil
+}
+
+// ResetAPIKey 重置用户的 API Key 和 Secret。
+func (a *AdminService) ResetAPIKey(userID string) (model.User, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	user, ok := a.users[userID]
+	if !ok {
+		return model.User{}, fmt.Errorf("admin: 用户 %s 不存在", userID)
+	}
+	// 移除旧 key
+	delete(a.keys, user.APIKey)
+	// 生成新 key
+	user.APIKey = a.generateAPIKey()
+	user.APISecret = a.generateAPISecret()
+	user.UpdatedAt = time.Now()
+	a.keys[user.APIKey] = user
+	return *user, nil
+}
+
+// LookupByAPIKey 根据 API Key 查询用户（供 httpx.KeyStore 使用）。
+func (a *AdminService) LookupByAPIKey(apiKey string) (secret string, role string, ok bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	user, exists := a.keys[apiKey]
+	if !exists || user.Status != model.UserStatusActive {
+		return "", "", false
+	}
+	return user.APISecret, user.Role, true
+}
+
+// ---- 辅助方法 ----
+
+func (a *AdminService) nextID(prefix string) string {
+	// 使用时间戳+随机数生成唯一 ID
+	ts := time.Now().Format("20060102")
+	b := make([]byte, 4)
+	rand.Read(b)
+	return fmt.Sprintf("%s-%s-%s", prefix, ts, hex.EncodeToString(b))
+}
+
+func (a *AdminService) generateAPIKey() string {
+	b := make([]byte, 16)
+	rand.Read(b)
+	return "tcs-" + hex.EncodeToString(b)
+}
+
+func (a *AdminService) generateAPISecret() string {
+	b := make([]byte, 32)
+	rand.Read(b)
+	return hex.EncodeToString(b)
+}

tcs-iptv/internal/service/admin_test.go

@@ -0,0 +1,110 @@
+package service
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+func TestAdminService_OrgCRUD(t *testing.T) {
+	a := NewAdminService()
+
+	// 创建组织
+	org, err := a.CreateOrg(model.Organization{
+		Name: "陕西IPTV运营公司", OrgNode: "6101", Province: "陕西", Type: model.OrgTypeRegulator,
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, org.ID)
+	assert.Equal(t, model.OrgStatusActive, org.Status)
+
+	// 查询组织
+	got, err := a.GetOrg(org.ID)
+	require.NoError(t, err)
+	assert.Equal(t, "陕西IPTV运营公司", got.Name)
+
+	// 更新组织
+	updated, err := a.UpdateOrg(org.ID, model.Organization{Name: "陕西IPTV"})
+	require.NoError(t, err)
+	assert.Equal(t, "陕西IPTV", updated.Name)
+
+	// 列出组织
+	orgs := a.ListOrgs(model.OrgTypeRegulator)
+	assert.Len(t, orgs, 1)
+
+	// 禁用组织
+	require.NoError(t, a.DisableOrg(org.ID))
+	got, _ = a.GetOrg(org.ID)
+	assert.Equal(t, model.OrgStatusDisabled, got.Status)
+}
+
+func TestAdminService_UserCRUD(t *testing.T) {
+	a := NewAdminService()
+
+	// 先创建组织
+	org, err := a.CreateOrg(model.Organization{
+		Name: "测试CP公司", Type: model.OrgTypeCP,
+	})
+	require.NoError(t, err)
+
+	// 创建用户
+	user, err := a.CreateUser(model.User{
+		Username: "testuser", FullName: "测试用户", OrgID: org.ID, Role: "cp",
+	})
+	require.NoError(t, err)
+	assert.NotEmpty(t, user.ID)
+	assert.NotEmpty(t, user.APIKey)
+	assert.NotEmpty(t, user.APISecret)
+	assert.Equal(t, model.UserStatusActive, user.Status)
+
+	// 用户名唯一性校验
+	_, err = a.CreateUser(model.User{
+		Username: "testuser", OrgID: org.ID, Role: "cp",
+	})
+	assert.Error(t, err)
+
+	// 不存在的组织
+	_, err = a.CreateUser(model.User{
+		Username: "user2", OrgID: "nonexistent", Role: "cp",
+	})
+	assert.Error(t, err)
+
+	// 查询用户
+	got, err := a.GetUser(user.ID)
+	require.NoError(t, err)
+	assert.Equal(t, "testuser", got.Username)
+
+	// 更新用户
+	updated, err := a.UpdateUser(user.ID, model.User{FullName: "更新用户名"})
+	require.NoError(t, err)
+	assert.Equal(t, "更新用户名", updated.FullName)
+
+	// 列出用户
+	users := a.ListUsers(org.ID, "")
+	assert.Len(t, users, 1)
+
+	// API Key 查找
+	secret, role, ok := a.LookupByAPIKey(user.APIKey)
+	require.True(t, ok)
+	assert.Equal(t, user.APISecret, secret)
+	assert.Equal(t, "cp", role)
+
+	// 重置 API Key
+	newUser, err := a.ResetAPIKey(user.ID)
+	require.NoError(t, err)
+	assert.NotEqual(t, user.APIKey, newUser.APIKey)
+
+	// 旧 Key 失效
+	_, _, ok = a.LookupByAPIKey(user.APIKey)
+	assert.False(t, ok)
+
+	// 新 Key 生效
+	_, _, ok = a.LookupByAPIKey(newUser.APIKey)
+	assert.True(t, ok)
+
+	// 禁用用户
+	require.NoError(t, a.DisableUser(user.ID))
+	_, _, ok = a.LookupByAPIKey(newUser.APIKey)
+	assert.False(t, ok)
+}

tcs-iptv/internal/service/query_admin.go

@@ -0,0 +1,73 @@
+package service
+
+import (
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+// ---- 多维度标识查询（方案第一阶段标识查询接口补足）----
+
+// QueryByHash 根据内容哈希反查标识信息及映射关系。
+func (s *Service) QueryByHash(fileHash string) (model.ContentQueryResult, error) {
+	return s.chain.QueryByHash(fileHash)
+}
+
+// QueryByProvincialCode 根据省级内容编码（CP MediaID）反查标识信息。
+func (s *Service) QueryByProvincialCode(provincialCode string) (model.ContentQueryResult, error) {
+	return s.chain.QueryByProvincialCode(provincialCode)
+}
+
+// QueryByLibraryFileID 根据片库文件 ID（媒资库 ID）反查标识信息。
+func (s *Service) QueryByLibraryFileID(libraryFileID string) (model.ContentQueryResult, error) {
+	return s.chain.QueryByLibraryFileID(libraryFileID)
+}
+
+// ---- MA 合并/拆分（方案 MA 管理模块补足）----
+
+// MergeMACodes 将多个 MA 码合并为一个主 MA 码（仅监管主体）。
+// 被合并的 MA 码的哈希绑定和映射迁移至主 MA 码，原 MA 码状态标记为 merged。
+// 全链路存证记录合并操作。
+func (s *Service) MergeMACodes(role chain.Role, req model.MergeRequest) (model.MergeResult, error) {
+	res, err := s.chain.MergeMA(role, req)
+	if err != nil {
+		return res, err
+	}
+	// 记录存证
+	s.prov.Record(model.ProvenanceEvent{
+		MACode:   req.PrimaryMACode,
+		Node:     model.NodeIssue,
+		Operator: req.Operator,
+		Detail:   "MA 码合并：将 " + joinMACodes(req.SecondaryMACodes) + " 合并入 " + req.PrimaryMACode + "，原因：" + req.Reason,
+	})
+	return res, nil
+}
+
+// SplitMACode 将一个 MA 码拆分为多个独立 MA 码（仅监管主体）。
+// 按集号将哈希绑定和映射迁移至新 MA 码，源 MA 码状态标记为 split。
+// 全链路存证记录拆分操作。
+func (s *Service) SplitMACode(role chain.Role, req model.SplitRequest) (model.SplitResult, error) {
+	res, err := s.chain.SplitMA(role, req)
+	if err != nil {
+		return res, err
+	}
+	// 记录存证
+	s.prov.Record(model.ProvenanceEvent{
+		MACode:   req.SourceMACode,
+		Node:     model.NodeIssue,
+		Operator: req.Operator,
+		Detail:   "MA 码拆分：将 " + req.SourceMACode + " 拆分为 " + joinMACodes(res.NewMACodes) + "，原因：" + req.Reason,
+	})
+	return res, nil
+}
+
+// joinMACodes 将 MA 码列表拼接为逗号分隔的字符串。
+func joinMACodes(codes []string) string {
+	if len(codes) == 0 {
+		return ""
+	}
+	out := codes[0]
+	for i := 1; i < len(codes); i++ {
+		out += ", " + codes[i]
+	}
+	return out
+}

tcs-iptv/internal/sync/sync.go

@@ -0,0 +1,166 @@
+// Package sync 标识同步服务（方案第三阶段 — 标识同步能力补足）。
+//
+// 提供多节点/多省间的标识数据同步能力：
+//   - 增量同步：按时间戳范围拉取变更内容
+//   - 全量同步：拉取全部内容记录
+//   - 同步冲突检测：基于 MA 码唯一性 + 内容哈希一致性
+//
+// 架构说明：
+//   - SyncSource 数据源接口（本地 chain.Client 实现）
+//   - SyncSink 数据汇接口（远端节点实现）
+//   - SyncService 同步编排器：拉取变更 → 冲突检测 → 推送
+package sync
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+// SyncSource 标识同步数据源接口。
+type SyncSource interface {
+	ListContents(status string) ([]model.Content, error)
+	QueryContent(maCode string) (model.Content, error)
+	QueryMappings(maCode string) (chain.MappingsResult, error)
+	ListEpisodes(maCode string) ([]model.HashBinding, error)
+}
+
+// SyncSink 标识同步数据汇接口（远端节点实现）。
+type SyncSink interface {
+	UpsertContent(c model.Content) error
+	UpsertBinding(maCode string, b model.HashBinding) error
+	UpsertMapping(maCode string, m model.Mapping) error
+}
+
+// ConflictResolver 同步冲突解决策略。
+type ConflictResolver int
+
+const (
+	// ConflictSkip 跳过冲突（保留远端数据）。
+	ConflictSkip ConflictResolver = iota
+	// ConflictOverwrite 覆盖远端数据（以本地为准）。
+	ConflictOverwrite
+	// ConflictFail 冲突时报错中止。
+	ConflictFail
+)
+
+// SyncRequest 同步请求。
+type SyncRequest struct {
+	Since     time.Time        // 增量同步起始时间（零值表示全量）
+	Resolver  ConflictResolver // 冲突解决策略
+	BatchSize int              // 批次大小（0 表示不分批）
+}
+
+// SyncResult 同步结果。
+type SyncResult struct {
+	TotalContents    int `json:"total_contents"`
+	TotalBindings    int `json:"total_bindings"`
+	TotalMappings    int `json:"total_mappings"`
+	SkippedConflicts int `json:"skipped_conflicts"`
+	Failed           int `json:"failed"`
+}
+
+// SyncService 标识同步编排器。
+type SyncService struct {
+	source SyncSource
+	sink   SyncSink
+}
+
+// New 创建标识同步服务。
+func New(source SyncSource, sink SyncSink) *SyncService {
+	return &SyncService{source: source, sink: sink}
+}
+
+// Sync 执行标识数据同步。
+func (s *SyncService) Sync(req SyncRequest) (SyncResult, error) {
+	result := SyncResult{}
+
+	// 拉取全部内容（增量同步需数据源支持时间过滤，MVP 全量拉取后按时间筛选）
+	contents, err := s.source.ListContents("")
+	if err != nil {
+		return result, fmt.Errorf("sync: 拉取内容列表失败: %w", err)
+	}
+
+	for _, c := range contents {
+		// 增量过滤：跳过早于 Since 的记录
+		if !req.Since.IsZero() && c.CreatedAt.Before(req.Since) {
+			continue
+		}
+
+		// 冲突检测：检查远端是否已存在该 MA 码
+		if req.Resolver == ConflictSkip {
+			if err := s.sink.UpsertContent(c); err != nil {
+				if errors.Is(err, ErrConflict) {
+					result.SkippedConflicts++
+					continue
+				}
+				result.Failed++
+				continue
+			}
+		} else {
+			if err := s.sink.UpsertContent(c); err != nil {
+				if errors.Is(err, ErrConflict) && req.Resolver == ConflictFail {
+					return result, fmt.Errorf("sync: 冲突 MA 码 %s: %w", c.MACode, err)
+				}
+				result.Failed++
+				continue
+			}
+		}
+		result.TotalContents++
+
+		// 同步哈希绑定
+		eps, _ := s.source.ListEpisodes(c.MACode)
+		for _, b := range eps {
+			if err := s.sink.UpsertBinding(c.MACode, b); err != nil {
+				result.Failed++
+				continue
+			}
+			result.TotalBindings++
+		}
+
+		// 同步映射
+		mr, _ := s.source.QueryMappings(c.MACode)
+		for _, m := range mr.Mappings {
+			if err := s.sink.UpsertMapping(c.MACode, m); err != nil {
+				result.Failed++
+				continue
+			}
+			result.TotalMappings++
+		}
+	}
+
+	return result, nil
+}
+
+// ErrConflict 同步冲突错误。
+var ErrConflict = errors.New("sync: content already exists at remote (conflict)")
+
+// ---- chain.Client 适配为 SyncSource ----
+
+// ChainSource 将 chain.Client 适配为 SyncSource。
+type ChainSource struct {
+	Client chain.Client
+}
+
+// ListContents 列出全部内容。
+func (cs *ChainSource) ListContents(status string) ([]model.Content, error) {
+	return cs.Client.ListContents(status)
+}
+
+// QueryContent 查询内容主记录。
+func (cs *ChainSource) QueryContent(maCode string) (model.Content, error) {
+	return cs.Client.QueryContent(maCode)
+}
+
+// QueryMappings 查询映射。
+func (cs *ChainSource) QueryMappings(maCode string) (chain.MappingsResult, error) {
+	return cs.Client.QueryMappings(maCode)
+}
+
+// ListEpisodes 列出集级哈希。
+func (cs *ChainSource) ListEpisodes(maCode string) ([]model.HashBinding, error) {
+	return cs.Client.ListEpisodes(maCode)
+}

tcs-iptv/internal/sync/sync_test.go

@@ -0,0 +1,139 @@
+package sync
+
+import (
+	"errors"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tcs-iptv/tcs/internal/chain"
+	"github.com/tcs-iptv/tcs/internal/model"
+)
+
+// memorySink 内存数据汇（测试用）。
+type memorySink struct {
+	mu        sync.Mutex
+	contents  map[string]model.Content
+	bindings  map[string][]model.HashBinding
+	mappings  map[string][]model.Mapping
+	conflict  bool // 模拟冲突
+}
+
+func newMemorySink() *memorySink {
+	return &memorySink{
+		contents: make(map[string]model.Content),
+		bindings: make(map[string][]model.HashBinding),
+		mappings: make(map[string][]model.Mapping),
+	}
+}
+
+func (m *memorySink) UpsertContent(c model.Content) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.conflict {
+		if _, exists := m.contents[c.MACode]; exists {
+			return ErrConflict
+		}
+	}
+	m.contents[c.MACode] = c
+	return nil
+}
+
+func (m *memorySink) UpsertBinding(maCode string, b model.HashBinding) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.bindings[maCode] = append(m.bindings[maCode], b)
+	return nil
+}
+
+func (m *memorySink) UpsertMapping(maCode string, mp model.Mapping) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.mappings[maCode] = append(m.mappings[maCode], mp)
+	return nil
+}
+
+func TestSyncService_FullSync(t *testing.T) {
+	src := &ChainSource{Client: chain.NewMemoryChain()}
+	sink := newMemorySink()
+
+	// 在源端发码
+	_, err := src.Client.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000001", ContentTwinID: "ctid-sync-001",
+		FileHash: "fh-sync-001", MerkleRoot: "mr-sync-001",
+		Episodes: []model.EpisodeHash{
+			{Episode: 1, FileSHA256: "fh-sync-001-E1"},
+			{Episode: 2, FileSHA256: "fh-sync-001-E2"},
+		},
+		Content: model.Content{Title: "同步测试剧", EpisodeCount: 2, MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 注册映射
+	_, err = src.Client.RegisterMapping(chain.RoleCP, model.Mapping{
+		ContentTwinID: "ctid-sync-001", Party: model.PartyCP, PartyID: "PROV-SYNC-001", PartyName: "测试CP",
+	})
+	require.NoError(t, err)
+
+	// 执行全量同步
+	svc := New(src, sink)
+	result, err := svc.Sync(SyncRequest{Resolver: ConflictOverwrite})
+	require.NoError(t, err)
+	assert.Equal(t, 1, result.TotalContents)
+	assert.Equal(t, 2, result.TotalBindings)
+	assert.Equal(t, 1, result.TotalMappings)
+	assert.Equal(t, 0, result.Failed)
+
+	// 验证远端数据
+	assert.Equal(t, "同步测试剧", sink.contents["MA.156.8531.6101/WD/20260000001"].Title)
+	assert.Len(t, sink.bindings["MA.156.8531.6101/WD/20260000001"], 2)
+}
+
+func TestSyncService_ConflictSkip(t *testing.T) {
+	src := &ChainSource{Client: chain.NewMemoryChain()}
+	sink := newMemorySink()
+	sink.conflict = true
+
+	// 源端发码
+	_, err := src.Client.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000002", ContentTwinID: "ctid-sync-002",
+		FileHash: "fh-sync-002", MerkleRoot: "mr-sync-002",
+		Content: model.Content{Title: "冲突测试剧", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	// 远端预先存在同 MA 码
+	sink.contents["MA.156.8531.6101/WD/20260000002"] = model.Content{
+		MACode: "MA.156.8531.6101/WD/20260000002", Title: "远端已有",
+	}
+
+	// 冲突跳过策略
+	svc := New(src, sink)
+	result, err := svc.Sync(SyncRequest{Resolver: ConflictSkip})
+	require.NoError(t, err)
+	assert.Equal(t, 1, result.SkippedConflicts)
+	assert.Equal(t, 0, result.TotalContents)
+}
+
+func TestSyncService_ConflictFail(t *testing.T) {
+	src := &ChainSource{Client: chain.NewMemoryChain()}
+	sink := newMemorySink()
+	sink.conflict = true
+
+	_, err := src.Client.IssueMA(chain.RoleRegulator, chain.IssueRequest{
+		MACode: "MA.156.8531.6101/WD/20260000003", ContentTwinID: "ctid-sync-003",
+		FileHash: "fh-sync-003", MerkleRoot: "mr-sync-003",
+		Content: model.Content{Title: "冲突Fail测试", MAType: "WD", Issuer: "测试局"},
+	})
+	require.NoError(t, err)
+
+	sink.contents["MA.156.8531.6101/WD/20260000003"] = model.Content{
+		MACode: "MA.156.8531.6101/WD/20260000003", Title: "远端已有",
+	}
+
+	svc := New(src, sink)
+	_, err = svc.Sync(SyncRequest{Resolver: ConflictFail})
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, ErrConflict))
+}