fadd

2026-06-19 11:27:53 +08:00
parent b16db987a7
commit 39079b9022
22 changed files with 1673 additions and 7 deletions
--- a/app/main/api/desc/admin/admin_query_whitelist.api
+++ b/app/main/api/desc/admin/admin_query_whitelist.api
@@ -0,0 +1,91 @@
+syntax = "v1"
+
+info (
+	title:   "后台查询白名单管理服务"
+	desc:    "对接天远 API 查询白名单配置接口"
+	version: "v1"
+)
+
+@server (
+	prefix: /api/v1/admin/query-whitelist
+	group:  admin_query_whitelist
+	middleware: AdminAuthInterceptor
+)
+service main {
+	// 创建查询白名单规则
+	@handler AdminCreateQueryWhitelist
+	post /create (AdminCreateQueryWhitelistReq) returns (AdminCreateQueryWhitelistResp)
+
+	// 追加产品编码到已有规则
+	@handler AdminAppendQueryWhitelist
+	// 获取操作记录列表
+	@handler AdminGetQueryWhitelistOpLogList
+	get /op-log/list (AdminGetQueryWhitelistOpLogListReq) returns (AdminGetQueryWhitelistOpLogListResp)
+}
+
+type (
+	AdminQueryWhitelistEntry {
+		Id           string   `json:"id"`
+		Name         string   `json:"name"`
+		IdCardMasked string   `json:"id_card_masked"`
+		ApiCodes     []string `json:"api_codes"`
+		Status       string   `json:"status"`
+		Remark       string   `json:"remark"`
+		CreatedAt    string   `json:"created_at"`
+		UpdatedAt    string   `json:"updated_at"`
+	}
+	AdminCreateQueryWhitelistReq {
+		Name     string   `json:"name,optional"`
+		IdCard   string   `json:"id_card"`
+		ApiCodes []string `json:"api_codes"`
+		Remark   string   `json:"remark,optional"`
+	}
+	AdminCreateQueryWhitelistResp {
+		Code          int                      `json:"code"`
+		Message       string                   `json:"message"`
+		TransactionId string                   `json:"transaction_id"`
+		Entry         *AdminQueryWhitelistEntry `json:"entry,optional"`
+	}
+	AdminAppendQueryWhitelistReq {
+		Name     string   `json:"name,optional"`
+		IdCard   string   `json:"id_card"`
+		ApiCodes []string `json:"api_codes"`
+		Remark   string   `json:"remark,optional"`
+	}
+	AdminAppendQueryWhitelistResp {
+		Code          int                      `json:"code"`
+		Message       string                   `json:"message"`
+		TransactionId string                   `json:"transaction_id"`
+		Entry         *AdminQueryWhitelistEntry `json:"entry,optional"`
+	}
+	AdminGetQueryWhitelistOpLogListReq {
+		Page         int64   `form:"page"`
+		PageSize     int64   `form:"pageSize"`
+		IdCard       *string `form:"id_card,optional"`
+		Action       *string `form:"action,optional"`
+		TianyuanCode *int64  `form:"tianyuan_code,optional"`
+	}
+	AdminQueryWhitelistOpLogItem {
+		Id              string   `json:"id"`
+		AdminUserId     string   `json:"admin_user_id"`
+		AdminUsername   string   `json:"admin_username"`
+		Action          string   `json:"action"`
+		ActionText      string   `json:"action_text"`
+		Name            string   `json:"name"`
+		IdCard          string   `json:"id_card"`
+		IdCardMasked    string   `json:"id_card_masked"`
+		ApiCodes        []string `json:"api_codes"`
+		Remark          string   `json:"remark"`
+		TianyuanCode    int64    `json:"tianyuan_code"`
+		TianyuanMessage string   `json:"tianyuan_message"`
+		TransactionId   string   `json:"transaction_id"`
+		EntryId         string   `json:"entry_id"`
+		EntryStatus     string   `json:"entry_status"`
+		EntryApiCodes   []string `json:"entry_api_codes"`
+		CreateTime      string   `json:"create_time"`
+	}
+	AdminGetQueryWhitelistOpLogListResp {
+		Total int64                          `json:"total"`
+		Items []AdminQueryWhitelistOpLogItem `json:"items"`
+	}
+)
--- a/app/main/api/desc/main.api
+++ b/app/main/api/desc/main.api
@@ -25,6 +25,7 @@ import "./admin/notification.api"
 import "./admin/admin_product.api"
 import "./admin/admin_feature.api"
 import "./admin/admin_whitelist.api"
+import "./admin/admin_query_whitelist.api"
 import "./admin/admin_query.api"
 import "./admin/admin_agent.api"
 import "./admin/admin_api.api"
--- a/app/main/api/etc/main.dev.yaml
+++ b/app/main/api/etc/main.dev.yaml
@@ -94,6 +94,7 @@ Tianyuanapi:
    Key: "04c6b4c559be6d5ba5351c04c8713a64"
    BaseURL: "https://api.tianyuanapi.com"
    Timeout: 60
+    WhitelistMgmtKey: "2R12TmEc1e8P3p69RdIoN5Ykjk%H@4orPy7DZv7MXpGByoEL" # 查询白名单管理密钥，向平台商务/技术支持申请
 Authorization:
    FileBaseURL: "https://www.onecha.cn/api/v1/auth-docs" # 授权书文件访问基础URL
 Promotion:
--- a/app/main/api/etc/main.yaml
+++ b/app/main/api/etc/main.yaml
@@ -84,6 +84,7 @@ Tianyuanapi:
    Key: "04c6b4c559be6d5ba5351c04c8713a64"
    BaseURL: "https://api.tianyuanapi.com"
    Timeout: 60
+    WhitelistMgmtKey: "2R12TmEc1e8P3p69RdIoN5Ykjk%H@4orPy7DZv7MXpGByoEL" # 查询白名单管理密钥，向平台商务/技术支持申请
 Authorization:
    FileBaseURL: "https://www.onecha.cn/api/v1/auth-docs" # 授权书文件访问基础URL
 Promotion:
--- a/app/main/api/internal/config/config.go
+++ b/app/main/api/internal/config/config.go
@@ -102,10 +102,11 @@ type TaxConfig struct {
 	TaxExemptionAmount float64
 }
 type TianyuanapiConfig struct {
-	AccessID string
-	Key      string
-	BaseURL  string
-	Timeout  int64
+	AccessID          string
+	Key               string
+	BaseURL           string
+	Timeout           int64
+	WhitelistMgmtKey  string // 查询白名单管理密钥 Whitelist-Mgmt-Key
 }

 type AuthorizationConfig struct {
--- a/app/main/api/internal/handler/admin_query_whitelist/adminappendquerywhitelisthandler.go
+++ b/app/main/api/internal/handler/admin_query_whitelist/adminappendquerywhitelisthandler.go
@@ -0,0 +1,29 @@
+package admin_query_whitelist
+
+import (
+	"net/http"
+
+	"github.com/zeromicro/go-zero/rest/httpx"
+	"ycc-server/app/main/api/internal/logic/admin_query_whitelist"
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	"ycc-server/common/result"
+	"ycc-server/pkg/lzkit/validator"
+)
+
+func AdminAppendQueryWhitelistHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.AdminAppendQueryWhitelistReq
+		if err := httpx.Parse(r, &req); err != nil {
+			result.ParamErrorResult(r, w, err)
+			return
+		}
+		if err := validator.Validate(req); err != nil {
+			result.ParamValidateErrorResult(r, w, err)
+			return
+		}
+		l := admin_query_whitelist.NewAdminAppendQueryWhitelistLogic(r.Context(), svcCtx)
+		resp, err := l.AdminAppendQueryWhitelist(&req)
+		result.HttpResult(r, w, resp, err)
+	}
+}
--- a/app/main/api/internal/handler/admin_query_whitelist/admincreatequerywhitelisthandler.go
+++ b/app/main/api/internal/handler/admin_query_whitelist/admincreatequerywhitelisthandler.go
@@ -0,0 +1,29 @@
+package admin_query_whitelist
+
+import (
+	"net/http"
+
+	"github.com/zeromicro/go-zero/rest/httpx"
+	"ycc-server/app/main/api/internal/logic/admin_query_whitelist"
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	"ycc-server/common/result"
+	"ycc-server/pkg/lzkit/validator"
+)
+
+func AdminCreateQueryWhitelistHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.AdminCreateQueryWhitelistReq
+		if err := httpx.Parse(r, &req); err != nil {
+			result.ParamErrorResult(r, w, err)
+			return
+		}
+		if err := validator.Validate(req); err != nil {
+			result.ParamValidateErrorResult(r, w, err)
+			return
+		}
+		l := admin_query_whitelist.NewAdminCreateQueryWhitelistLogic(r.Context(), svcCtx)
+		resp, err := l.AdminCreateQueryWhitelist(&req)
+		result.HttpResult(r, w, resp, err)
+	}
+}
--- a/app/main/api/internal/handler/admin_query_whitelist/admingetquerywhitelistoploglisthandler.go
+++ b/app/main/api/internal/handler/admin_query_whitelist/admingetquerywhitelistoploglisthandler.go
@@ -0,0 +1,29 @@
+package admin_query_whitelist
+
+import (
+	"net/http"
+
+	"github.com/zeromicro/go-zero/rest/httpx"
+	"ycc-server/app/main/api/internal/logic/admin_query_whitelist"
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	"ycc-server/common/result"
+	"ycc-server/pkg/lzkit/validator"
+)
+
+func AdminGetQueryWhitelistOpLogListHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		var req types.AdminGetQueryWhitelistOpLogListReq
+		if err := httpx.Parse(r, &req); err != nil {
+			result.ParamErrorResult(r, w, err)
+			return
+		}
+		if err := validator.Validate(req); err != nil {
+			result.ParamValidateErrorResult(r, w, err)
+			return
+		}
+		l := admin_query_whitelist.NewAdminGetQueryWhitelistOpLogListLogic(r.Context(), svcCtx)
+		resp, err := l.AdminGetQueryWhitelistOpLogList(&req)
+		result.HttpResult(r, w, resp, err)
+	}
+}
--- a/app/main/api/internal/handler/routes.go
+++ b/app/main/api/internal/handler/routes.go
@@ -16,6 +16,7 @@ import (
 	admin_platform_user "ycc-server/app/main/api/internal/handler/admin_platform_user"
 	admin_product "ycc-server/app/main/api/internal/handler/admin_product"
 	admin_query "ycc-server/app/main/api/internal/handler/admin_query"
+	admin_query_whitelist "ycc-server/app/main/api/internal/handler/admin_query_whitelist"
 	admin_role "ycc-server/app/main/api/internal/handler/admin_role"
 	admin_role_api "ycc-server/app/main/api/internal/handler/admin_role_api"
 	admin_user "ycc-server/app/main/api/internal/handler/admin_user"
@@ -688,6 +689,30 @@ func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
 		rest.WithPrefix("/api/v1/admin/whitelist"),
 	)

+	server.AddRoutes(
+		rest.WithMiddlewares(
+			[]rest.Middleware{serverCtx.AdminAuthInterceptor},
+			[]rest.Route{
+				{
+					Method:  http.MethodGet,
+					Path:    "/op-log/list",
+					Handler: admin_query_whitelist.AdminGetQueryWhitelistOpLogListHandler(serverCtx),
+				},
+				{
+					Method:  http.MethodPost,
+					Path:    "/append",
+					Handler: admin_query_whitelist.AdminAppendQueryWhitelistHandler(serverCtx),
+				},
+				{
+					Method:  http.MethodPost,
+					Path:    "/create",
+					Handler: admin_query_whitelist.AdminCreateQueryWhitelistHandler(serverCtx),
+				},
+			}...,
+		),
+		rest.WithPrefix("/api/v1/admin/query-whitelist"),
+	)
+
 	server.AddRoutes(
 		[]rest.Route{
 			{
--- a/app/main/api/internal/logic/admin_query_whitelist/adminappendquerywhitelistlogic.go
+++ b/app/main/api/internal/logic/admin_query_whitelist/adminappendquerywhitelistlogic.go
@@ -0,0 +1,46 @@
+package admin_query_whitelist
+
+import (
+	"context"
+
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type AdminAppendQueryWhitelistLogic struct {
+	logx.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewAdminAppendQueryWhitelistLogic(ctx context.Context, svcCtx *svc.ServiceContext) *AdminAppendQueryWhitelistLogic {
+	return &AdminAppendQueryWhitelistLogic{
+		Logger: logx.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *AdminAppendQueryWhitelistLogic) AdminAppendQueryWhitelist(req *types.AdminAppendQueryWhitelistReq) (resp *types.AdminAppendQueryWhitelistResp, err error) {
+	if err = validateQueryWhitelistReq(req.IdCard, req.ApiCodes); err != nil {
+		return nil, err
+	}
+
+	apiResp, err := callQueryWhitelistMgmt(
+		l.svcCtx,
+		"/api/v1/query-whitelist/entries/append",
+		req.Name,
+		req.IdCard,
+		req.ApiCodes,
+		req.Remark,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	recordQueryWhitelistOpLog(l.ctx, l.svcCtx, "append", req.Name, req.IdCard, req.ApiCodes, req.Remark, apiResp)
+
+	return toAppendResp(apiResp), nil
+}
--- a/app/main/api/internal/logic/admin_query_whitelist/admincreatequerywhitelistlogic.go
+++ b/app/main/api/internal/logic/admin_query_whitelist/admincreatequerywhitelistlogic.go
@@ -0,0 +1,46 @@
+package admin_query_whitelist
+
+import (
+	"context"
+
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type AdminCreateQueryWhitelistLogic struct {
+	logx.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewAdminCreateQueryWhitelistLogic(ctx context.Context, svcCtx *svc.ServiceContext) *AdminCreateQueryWhitelistLogic {
+	return &AdminCreateQueryWhitelistLogic{
+		Logger: logx.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *AdminCreateQueryWhitelistLogic) AdminCreateQueryWhitelist(req *types.AdminCreateQueryWhitelistReq) (resp *types.AdminCreateQueryWhitelistResp, err error) {
+	if err = validateQueryWhitelistReq(req.IdCard, req.ApiCodes); err != nil {
+		return nil, err
+	}
+
+	apiResp, err := callQueryWhitelistMgmt(
+		l.svcCtx,
+		"/api/v1/query-whitelist/entries",
+		req.Name,
+		req.IdCard,
+		req.ApiCodes,
+		req.Remark,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	recordQueryWhitelistOpLog(l.ctx, l.svcCtx, "create", req.Name, req.IdCard, req.ApiCodes, req.Remark, apiResp)
+
+	return toCreateResp(apiResp), nil
+}
--- a/app/main/api/internal/logic/admin_query_whitelist/admingetquerywhitelistoploglistlogic.go
+++ b/app/main/api/internal/logic/admin_query_whitelist/admingetquerywhitelistoploglistlogic.go
@@ -0,0 +1,119 @@
+package admin_query_whitelist
+
+import (
+	"context"
+
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	"ycc-server/app/main/model"
+	"ycc-server/common/xerr"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/pkg/errors"
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type AdminGetQueryWhitelistOpLogListLogic struct {
+	logx.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewAdminGetQueryWhitelistOpLogListLogic(ctx context.Context, svcCtx *svc.ServiceContext) *AdminGetQueryWhitelistOpLogListLogic {
+	return &AdminGetQueryWhitelistOpLogListLogic{
+		Logger: logx.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *AdminGetQueryWhitelistOpLogListLogic) AdminGetQueryWhitelistOpLogList(req *types.AdminGetQueryWhitelistOpLogListReq) (resp *types.AdminGetQueryWhitelistOpLogListResp, err error) {
+	builder := l.svcCtx.QueryWhitelistOpLogModel.SelectBuilder()
+
+	if req.IdCard != nil && *req.IdCard != "" {
+		builder = builder.Where("id_card LIKE ?", "%"+*req.IdCard+"%")
+	}
+	if req.Action != nil && *req.Action != "" {
+		builder = builder.Where("action = ?", *req.Action)
+	}
+	if req.TianyuanCode != nil {
+		builder = builder.Where("tianyuan_code = ?", *req.TianyuanCode)
+	}
+
+	total, err := l.svcCtx.QueryWhitelistOpLogModel.FindCount(l.ctx, builder, "id")
+	if err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DB_ERROR), "查询操作记录总数失败, %v", err)
+	}
+
+	list, err := l.svcCtx.QueryWhitelistOpLogModel.FindPageListByPage(l.ctx, builder, req.Page, req.PageSize, "create_time DESC")
+	if err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DB_ERROR), "查询操作记录列表失败, %v", err)
+	}
+
+	adminNameMap := l.buildAdminUsernameMap(list)
+	items := make([]types.AdminQueryWhitelistOpLogItem, 0, len(list))
+	for _, row := range list {
+		items = append(items, types.AdminQueryWhitelistOpLogItem{
+			Id:              row.Id,
+			AdminUserId:     row.AdminUserId,
+			AdminUsername:   adminNameMap[row.AdminUserId],
+			Action:          row.Action,
+			ActionText:      queryWhitelistActionText(row.Action),
+			Name:            row.Name,
+			IdCard:          row.IdCard,
+			IdCardMasked:    row.IdCardMasked.String,
+			ApiCodes:        parseApiCodesJSON(row.ApiCodes),
+			Remark:          row.Remark.String,
+			TianyuanCode:    row.TianyuanCode,
+			TianyuanMessage: row.TianyuanMessage.String,
+			TransactionId:   row.TransactionId.String,
+			EntryId:         row.EntryId.String,
+			EntryStatus:     row.EntryStatus.String,
+			EntryApiCodes:   parseApiCodesJSON(row.EntryApiCodes.String),
+			CreateTime:      row.CreateTime.Format("2006-01-02 15:04:05"),
+		})
+	}
+
+	return &types.AdminGetQueryWhitelistOpLogListResp{
+		Total: total,
+		Items: items,
+	}, nil
+}
+
+func (l *AdminGetQueryWhitelistOpLogListLogic) buildAdminUsernameMap(list []*model.QueryWhitelistOpLog) map[string]string {
+	nameMap := make(map[string]string)
+	if len(list) == 0 {
+		return nameMap
+	}
+
+	adminIds := make([]string, 0, len(list))
+	seen := make(map[string]struct{}, len(list))
+	for _, row := range list {
+		if row.AdminUserId == "" {
+			continue
+		}
+		if _, ok := seen[row.AdminUserId]; ok {
+			continue
+		}
+		seen[row.AdminUserId] = struct{}{}
+		adminIds = append(adminIds, row.AdminUserId)
+	}
+	if len(adminIds) == 0 {
+		return nameMap
+	}
+
+	builder := l.svcCtx.AdminUserModel.SelectBuilder().Where(squirrel.Eq{"id": adminIds})
+	users, err := l.svcCtx.AdminUserModel.FindAll(l.ctx, builder, "")
+	if err != nil {
+		l.Errorf("批量查询管理员名称失败: %v", err)
+		return nameMap
+	}
+	for _, user := range users {
+		displayName := user.RealName
+		if displayName == "" {
+			displayName = user.Username
+		}
+		nameMap[user.Id] = displayName
+	}
+	return nameMap
+}
--- a/app/main/api/internal/logic/admin_query_whitelist/query_whitelist_helper.go
+++ b/app/main/api/internal/logic/admin_query_whitelist/query_whitelist_helper.go
@@ -0,0 +1,199 @@
+package admin_query_whitelist
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"regexp"
+	"strings"
+
+	"ycc-server/app/main/api/internal/svc"
+	"ycc-server/app/main/api/internal/types"
+	tianyuanapi "ycc-server/app/main/api/internal/service/tianyuanapi_sdk"
+	"ycc-server/app/main/model"
+	"ycc-server/common/ctxdata"
+	"ycc-server/common/xerr"
+
+	"github.com/pkg/errors"
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+var idCardPattern = regexp.MustCompile(`^\d{17}[\dXx]$`)
+
+func validateQueryWhitelistReq(idCard string, apiCodes []string) error {
+	if strings.TrimSpace(idCard) == "" {
+		return errors.Wrapf(xerr.NewErrMsg("身份证号不能为空"), "")
+	}
+	if !idCardPattern.MatchString(strings.TrimSpace(idCard)) {
+		return errors.Wrapf(xerr.NewErrMsg("身份证号格式不正确，需为18位中国大陆身份证号"), "")
+	}
+	if len(apiCodes) == 0 {
+		return errors.Wrapf(xerr.NewErrMsg("请至少选择一个产品编码"), "")
+	}
+	for _, code := range apiCodes {
+		if strings.TrimSpace(code) == "" {
+			return errors.Wrapf(xerr.NewErrMsg("产品编码不能为空"), "")
+		}
+		if code == "*" {
+			return errors.Wrapf(xerr.NewErrMsg("产品编码不支持通配符 *"), "")
+		}
+	}
+	return nil
+}
+
+func buildQueryWhitelistPayload(name, idCard string, apiCodes []string, remark string) map[string]interface{} {
+	payload := map[string]interface{}{
+		"name":      name,
+		"id_card":   strings.TrimSpace(idCard),
+		"api_codes": apiCodes,
+	}
+	if strings.TrimSpace(remark) != "" {
+		payload["remark"] = strings.TrimSpace(remark)
+	}
+	return payload
+}
+
+func callQueryWhitelistMgmt(
+	svcCtx *svc.ServiceContext,
+	apiPath string,
+	name, idCard string,
+	apiCodes []string,
+	remark string,
+) (*tianyuanapi.QueryWhitelistMgmtResponse, error) {
+	mgmtKey := svcCtx.Config.Tianyuanapi.WhitelistMgmtKey
+	if mgmtKey == "" {
+		return nil, errors.Wrapf(xerr.NewErrMsg("查询白名单管理密钥未配置，请在服务端配置 Tianyuanapi.WhitelistMgmtKey"), "")
+	}
+	if svcCtx.TianyuanapiClient == nil {
+		return nil, errors.Wrapf(xerr.NewErrMsg("天远 API 客户端未初始化"), "")
+	}
+
+	if strings.TrimSpace(name) == "" {
+		name = "*"
+	}
+
+	payload := buildQueryWhitelistPayload(name, idCard, apiCodes, remark)
+	return svcCtx.TianyuanapiClient.CallQueryWhitelistMgmt(apiPath, payload, mgmtKey)
+}
+
+func toAdminEntry(entry *tianyuanapi.QueryWhitelistEntry) *types.AdminQueryWhitelistEntry {
+	if entry == nil {
+		return nil
+	}
+	return &types.AdminQueryWhitelistEntry{
+		Id:           entry.ID,
+		Name:         entry.Name,
+		IdCardMasked: entry.IdCardMasked,
+		ApiCodes:     entry.ApiCodes,
+		Status:       entry.Status,
+		Remark:       entry.Remark,
+		CreatedAt:    entry.CreatedAt,
+		UpdatedAt:    entry.UpdatedAt,
+	}
+}
+
+func toCreateResp(resp *tianyuanapi.QueryWhitelistMgmtResponse) *types.AdminCreateQueryWhitelistResp {
+	return &types.AdminCreateQueryWhitelistResp{
+		Code:          resp.Code,
+		Message:       resp.Message,
+		TransactionId: resp.TransactionID,
+		Entry:         toAdminEntry(resp.Entry),
+	}
+}
+
+func toAppendResp(resp *tianyuanapi.QueryWhitelistMgmtResponse) *types.AdminAppendQueryWhitelistResp {
+	return &types.AdminAppendQueryWhitelistResp{
+		Code:          resp.Code,
+		Message:       resp.Message,
+		TransactionId: resp.TransactionID,
+		Entry:         toAdminEntry(resp.Entry),
+	}
+}
+
+func resolveName(name string) string {
+	if strings.TrimSpace(name) == "" {
+		return "*"
+	}
+	return strings.TrimSpace(name)
+}
+
+func parseApiCodesJSON(raw string) []string {
+	if raw == "" {
+		return nil
+	}
+	var codes []string
+	if err := json.Unmarshal([]byte(raw), &codes); err != nil {
+		return nil
+	}
+	return codes
+}
+
+func queryWhitelistActionText(action string) string {
+	switch action {
+	case "create":
+		return "创建规则"
+	case "append":
+		return "追加接口"
+	default:
+		return action
+	}
+}
+
+func recordQueryWhitelistOpLog(
+	ctx context.Context,
+	svcCtx *svc.ServiceContext,
+	action, name, idCard string,
+	apiCodes []string,
+	remark string,
+	apiResp *tianyuanapi.QueryWhitelistMgmtResponse,
+) {
+	adminUserId, err := ctxdata.GetUidFromCtx(ctx)
+	if err != nil {
+		logx.WithContext(ctx).Errorf("记录查询白名单操作日志失败: 获取管理员ID失败, %v", err)
+		adminUserId = ""
+	}
+
+	apiCodesJSON, marshalErr := json.Marshal(apiCodes)
+	if marshalErr != nil {
+		logx.WithContext(ctx).Errorf("记录查询白名单操作日志失败: 序列化 api_codes 失败, %v", marshalErr)
+		return
+	}
+
+	log := &model.QueryWhitelistOpLog{
+		AdminUserId:  adminUserId,
+		Action:       action,
+		Name:         resolveName(name),
+		IdCard:       strings.TrimSpace(idCard),
+		ApiCodes:     string(apiCodesJSON),
+		TianyuanCode: int64(apiResp.Code),
+	}
+
+	if strings.TrimSpace(remark) != "" {
+		log.Remark = sql.NullString{String: strings.TrimSpace(remark), Valid: true}
+	}
+	if apiResp.Message != "" {
+		log.TianyuanMessage = sql.NullString{String: apiResp.Message, Valid: true}
+	}
+	if apiResp.TransactionID != "" {
+		log.TransactionId = sql.NullString{String: apiResp.TransactionID, Valid: true}
+	}
+	if apiResp.Entry != nil {
+		if apiResp.Entry.IdCardMasked != "" {
+			log.IdCardMasked = sql.NullString{String: apiResp.Entry.IdCardMasked, Valid: true}
+		}
+		if apiResp.Entry.ID != "" {
+			log.EntryId = sql.NullString{String: apiResp.Entry.ID, Valid: true}
+		}
+		if apiResp.Entry.Status != "" {
+			log.EntryStatus = sql.NullString{String: apiResp.Entry.Status, Valid: true}
+		}
+		if len(apiResp.Entry.ApiCodes) > 0 {
+			entryCodesJSON, _ := json.Marshal(apiResp.Entry.ApiCodes)
+			log.EntryApiCodes = sql.NullString{String: string(entryCodesJSON), Valid: true}
+		}
+	}
+
+	if _, insertErr := svcCtx.QueryWhitelistOpLogModel.Insert(ctx, nil, log); insertErr != nil {
+		logx.WithContext(ctx).Errorf("记录查询白名单操作日志失败: %v", insertErr)
+	}
+}
--- a/app/main/api/internal/service/tianyuanapi_sdk/query_whitelist.go
+++ b/app/main/api/internal/service/tianyuanapi_sdk/query_whitelist.go
@@ -0,0 +1,105 @@
+package tianyuanapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+// QueryWhitelistEntry 查询白名单规则详情（解密后）
+type QueryWhitelistEntry struct {
+	ID           string   `json:"id"`
+	Name         string   `json:"name"`
+	IdCardMasked string   `json:"id_card_masked"`
+	ApiCodes     []string `json:"api_codes"`
+	Status       string   `json:"status"`
+	Remark       string   `json:"remark"`
+	CreatedAt    string   `json:"created_at"`
+	UpdatedAt    string   `json:"updated_at"`
+}
+
+// QueryWhitelistMgmtResponse 查询白名单管理接口响应
+type QueryWhitelistMgmtResponse struct {
+	Code          int                  `json:"code"`
+	Message       string               `json:"message"`
+	TransactionID string               `json:"transaction_id"`
+	Entry         *QueryWhitelistEntry `json:"entry,omitempty"`
+	Timeout       int64                `json:"timeout"`
+}
+
+// CallQueryWhitelistMgmt 调用查询白名单管理接口（创建/追加）
+func (c *Client) CallQueryWhitelistMgmt(apiPath string, params map[string]interface{}, mgmtKey string) (*QueryWhitelistMgmtResponse, error) {
+	startTime := time.Now()
+
+	if mgmtKey == "" {
+		return nil, fmt.Errorf("Whitelist-Mgmt-Key 不能为空")
+	}
+	if params == nil {
+		return nil, fmt.Errorf("params不能为空")
+	}
+
+	jsonData, err := json.Marshal(params)
+	if err != nil {
+		return nil, fmt.Errorf("参数序列化失败: %v", err)
+	}
+
+	encryptedData, err := c.encrypt(string(jsonData))
+	if err != nil {
+		return nil, fmt.Errorf("数据加密失败: %v", err)
+	}
+
+	requestBody := map[string]string{"data": encryptedData}
+	requestBodyBytes, err := json.Marshal(requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("请求体序列化失败: %v", err)
+	}
+
+	url := c.baseURL + apiPath
+	httpReq, err := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(requestBodyBytes))
+	if err != nil {
+		return nil, fmt.Errorf("创建HTTP请求失败: %v", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Access-Id", c.accessID)
+	httpReq.Header.Set("Whitelist-Mgmt-Key", mgmtKey)
+	httpReq.Header.Set("User-Agent", "TianyuanAPI-Go-SDK/1.0.0")
+
+	resp, err := c.client.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("请求失败: %v", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("读取响应失败: %v", err)
+	}
+
+	var apiResp ApiResponse
+	if err := json.Unmarshal(body, &apiResp); err != nil {
+		return nil, fmt.Errorf("响应解析失败: %v", err)
+	}
+
+	result := &QueryWhitelistMgmtResponse{
+		Code:          apiResp.Code,
+		Message:       apiResp.Message,
+		TransactionID: apiResp.TransactionID,
+		Timeout:       time.Since(startTime).Milliseconds(),
+	}
+
+	if apiResp.Data != "" {
+		decryptedData, decryptErr := c.decrypt(apiResp.Data)
+		if decryptErr == nil {
+			var entry QueryWhitelistEntry
+			if json.Unmarshal([]byte(decryptedData), &entry) == nil {
+				result.Entry = &entry
+			}
+		}
+	}
+
+	return result, nil
+}
--- a/app/main/api/internal/svc/servicecontext.go
+++ b/app/main/api/internal/svc/servicecontext.go
@@ -37,11 +37,13 @@ type ServiceContext struct {
 	// 天元API调用记录模型
 	TianyuanapiCallLogModel   model.TianyuanapiCallLogModel
 	TianyuanapiCallLogService *service.TianyuanapiCallLogService
+	TianyuanapiClient         *tianyuanapi.Client

 	// 白名单相关模型
-	UserFeatureWhitelistModel model.UserFeatureWhitelistModel
-	WhitelistOrderModel       model.WhitelistOrderModel
-	WhitelistOrderItemModel   model.WhitelistOrderItemModel
+	UserFeatureWhitelistModel  model.UserFeatureWhitelistModel
+	WhitelistOrderModel        model.WhitelistOrderModel
+	WhitelistOrderItemModel    model.WhitelistOrderItemModel
+	QueryWhitelistOpLogModel   model.QueryWhitelistOpLogModel

 	// 订单相关模型
 	OrderModel              model.OrderModel
@@ -140,6 +142,7 @@ func NewServiceContext(c config.Config) *ServiceContext {
 	userFeatureWhitelistModel := model.NewUserFeatureWhitelistModel(db, cacheConf)
 	whitelistOrderModel := model.NewWhitelistOrderModel(db, cacheConf)
 	whitelistOrderItemModel := model.NewWhitelistOrderItemModel(db, cacheConf)
+	queryWhitelistOpLogModel := model.NewQueryWhitelistOpLogModel(db, cacheConf)

 	// ============================== 订单相关模型 ==============================
 	orderModel := model.NewOrderModel(db, cacheConf)
@@ -254,11 +257,13 @@ func NewServiceContext(c config.Config) *ServiceContext {
 		// 天元API调用记录模型
 		TianyuanapiCallLogModel:   tianyuanapiCallLogModel,
 		TianyuanapiCallLogService: tianyuanapiCallLogService,
+		TianyuanapiClient:         tianyuanapi,

 		// 白名单相关模型
 		UserFeatureWhitelistModel: userFeatureWhitelistModel,
 		WhitelistOrderModel:       whitelistOrderModel,
 		WhitelistOrderItemModel:   whitelistOrderItemModel,
+		QueryWhitelistOpLogModel:  queryWhitelistOpLogModel,

 		// 订单相关模型
 		OrderModel:              orderModel,
--- a/app/main/api/internal/types/types.go
+++ b/app/main/api/internal/types/types.go
@@ -197,6 +197,78 @@ type AdminCreateWhitelistResp struct {
 	Id string `json:"id"`
 }

+type AdminAppendQueryWhitelistReq struct {
+	Name     string   `json:"name,optional"`
+	IdCard   string   `json:"id_card"`
+	ApiCodes []string `json:"api_codes"`
+	Remark   string   `json:"remark,optional"`
+}
+
+type AdminAppendQueryWhitelistResp struct {
+	Code          int                       `json:"code"`
+	Message       string                    `json:"message"`
+	TransactionId string                    `json:"transaction_id"`
+	Entry         *AdminQueryWhitelistEntry `json:"entry,optional"`
+}
+
+type AdminCreateQueryWhitelistReq struct {
+	Name     string   `json:"name,optional"`
+	IdCard   string   `json:"id_card"`
+	ApiCodes []string `json:"api_codes"`
+	Remark   string   `json:"remark,optional"`
+}
+
+type AdminCreateQueryWhitelistResp struct {
+	Code          int                       `json:"code"`
+	Message       string                    `json:"message"`
+	TransactionId string                    `json:"transaction_id"`
+	Entry         *AdminQueryWhitelistEntry `json:"entry,optional"`
+}
+
+type AdminQueryWhitelistEntry struct {
+	Id           string   `json:"id"`
+	Name         string   `json:"name"`
+	IdCardMasked string   `json:"id_card_masked"`
+	ApiCodes     []string `json:"api_codes"`
+	Status       string   `json:"status"`
+	Remark       string   `json:"remark"`
+	CreatedAt    string   `json:"created_at"`
+	UpdatedAt    string   `json:"updated_at"`
+}
+
+type AdminGetQueryWhitelistOpLogListReq struct {
+	Page         int64   `form:"page"`
+	PageSize     int64   `form:"pageSize"`
+	IdCard       *string `form:"id_card,optional"`
+	Action       *string `form:"action,optional"`
+	TianyuanCode *int64  `form:"tianyuan_code,optional"`
+}
+
+type AdminQueryWhitelistOpLogItem struct {
+	Id              string   `json:"id"`
+	AdminUserId     string   `json:"admin_user_id"`
+	AdminUsername   string   `json:"admin_username"`
+	Action          string   `json:"action"`
+	ActionText      string   `json:"action_text"`
+	Name            string   `json:"name"`
+	IdCard          string   `json:"id_card"`
+	IdCardMasked    string   `json:"id_card_masked"`
+	ApiCodes        []string `json:"api_codes"`
+	Remark          string   `json:"remark"`
+	TianyuanCode    int64    `json:"tianyuan_code"`
+	TianyuanMessage string   `json:"tianyuan_message"`
+	TransactionId   string   `json:"transaction_id"`
+	EntryId         string   `json:"entry_id"`
+	EntryStatus     string   `json:"entry_status"`
+	EntryApiCodes   []string `json:"entry_api_codes"`
+	CreateTime      string   `json:"create_time"`
+}
+
+type AdminGetQueryWhitelistOpLogListResp struct {
+	Total int64                          `json:"total"`
+	Items []AdminQueryWhitelistOpLogItem `json:"items"`
+}
+
 type AdminDeleteApiReq struct {
 	Id string `path:"id"`
 }
--- a/app/main/model/queryWhitelistOpLogModel.go
+++ b/app/main/model/queryWhitelistOpLogModel.go
@@ -0,0 +1,27 @@
+package model
+
+import (
+	"github.com/zeromicro/go-zero/core/stores/cache"
+	"github.com/zeromicro/go-zero/core/stores/sqlx"
+)
+
+var _ QueryWhitelistOpLogModel = (*customQueryWhitelistOpLogModel)(nil)
+
+type (
+	// QueryWhitelistOpLogModel is an interface to be customized, add more methods here,
+	// and implement the added methods in customQueryWhitelistOpLogModel.
+	QueryWhitelistOpLogModel interface {
+		queryWhitelistOpLogModel
+	}
+
+	customQueryWhitelistOpLogModel struct {
+		*defaultQueryWhitelistOpLogModel
+	}
+)
+
+// NewQueryWhitelistOpLogModel returns a model for the database table.
+func NewQueryWhitelistOpLogModel(conn sqlx.SqlConn, c cache.CacheConf) QueryWhitelistOpLogModel {
+	return &customQueryWhitelistOpLogModel{
+		defaultQueryWhitelistOpLogModel: newQueryWhitelistOpLogModel(conn, c),
+	}
+}
--- a/app/main/model/queryWhitelistOpLogModel_gen.go
+++ b/app/main/model/queryWhitelistOpLogModel_gen.go
@@ -0,0 +1,398 @@
+// Code generated by goctl. DO NOT EDIT!
+
+package model
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"strings"
+
+	"reflect"
+	"time"
+
+	"github.com/Masterminds/squirrel"
+	"github.com/google/uuid"
+	"github.com/pkg/errors"
+	"github.com/zeromicro/go-zero/core/stores/builder"
+	"github.com/zeromicro/go-zero/core/stores/cache"
+	"github.com/zeromicro/go-zero/core/stores/sqlc"
+	"github.com/zeromicro/go-zero/core/stores/sqlx"
+	"github.com/zeromicro/go-zero/core/stringx"
+	"ycc-server/common/globalkey"
+)
+
+var (
+	queryWhitelistOpLogFieldNames          = builder.RawFieldNames(&QueryWhitelistOpLog{})
+	queryWhitelistOpLogRows                = strings.Join(queryWhitelistOpLogFieldNames, ",")
+	queryWhitelistOpLogRowsExpectAutoSet   = strings.Join(stringx.Remove(queryWhitelistOpLogFieldNames, "`create_time`", "`update_time`"), ",")
+	queryWhitelistOpLogRowsWithPlaceHolder = strings.Join(stringx.Remove(queryWhitelistOpLogFieldNames, "`id`", "`create_time`", "`update_time`"), "=?,") + "=?"
+
+	cacheYccQueryWhitelistOpLogIdPrefix = "cache:ycc:queryWhitelistOpLog:id:"
+)
+
+type (
+	queryWhitelistOpLogModel interface {
+		Insert(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) (sql.Result, error)
+		FindOne(ctx context.Context, id string) (*QueryWhitelistOpLog, error)
+		Update(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) (sql.Result, error)
+		UpdateWithVersion(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) error
+		Trans(ctx context.Context, fn func(context context.Context, session sqlx.Session) error) error
+		SelectBuilder() squirrel.SelectBuilder
+		DeleteSoft(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) error
+		FindSum(ctx context.Context, sumBuilder squirrel.SelectBuilder, field string) (float64, error)
+		FindCount(ctx context.Context, countBuilder squirrel.SelectBuilder, field string) (int64, error)
+		FindAll(ctx context.Context, rowBuilder squirrel.SelectBuilder, orderBy string) ([]*QueryWhitelistOpLog, error)
+		FindPageListByPage(ctx context.Context, rowBuilder squirrel.SelectBuilder, page, pageSize int64, orderBy string) ([]*QueryWhitelistOpLog, error)
+		FindPageListByPageWithTotal(ctx context.Context, rowBuilder squirrel.SelectBuilder, page, pageSize int64, orderBy string) ([]*QueryWhitelistOpLog, int64, error)
+		FindPageListByIdDESC(ctx context.Context, rowBuilder squirrel.SelectBuilder, preMinId, pageSize int64) ([]*QueryWhitelistOpLog, error)
+		FindPageListByIdASC(ctx context.Context, rowBuilder squirrel.SelectBuilder, preMaxId, pageSize int64) ([]*QueryWhitelistOpLog, error)
+		Delete(ctx context.Context, session sqlx.Session, id string) error
+	}
+
+	defaultQueryWhitelistOpLogModel struct {
+		sqlc.CachedConn
+		table string
+	}
+
+	QueryWhitelistOpLog struct {
+		Id              string         `db:"id"`               // UUID主键
+		CreateTime      time.Time      `db:"create_time"`      // 创建时间
+		UpdateTime      time.Time      `db:"update_time"`      // 更新时间
+		DeleteTime      sql.NullTime   `db:"delete_time"`      // 删除时间
+		DelState        int64          `db:"del_state"`        // 删除状态：0=未删除，1=已删除
+		Version         int64          `db:"version"`          // 版本号（乐观锁）
+		AdminUserId     string         `db:"admin_user_id"`    // 操作管理员ID
+		Action          string         `db:"action"`           // 操作类型：create=创建规则，append=追加接口
+		Name            string         `db:"name"`             // 姓名规则
+		IdCard          string         `db:"id_card"`          // 身份证号（明文，供后台审计）
+		IdCardMasked    sql.NullString `db:"id_card_masked"`   // 天远返回的脱敏身份证号
+		ApiCodes        string         `db:"api_codes"`        // 本次提交的产品编码（JSON数组）
+		Remark          sql.NullString `db:"remark"`           // 备注
+		TianyuanCode    int64          `db:"tianyuan_code"`    // 天远 API 业务码
+		TianyuanMessage sql.NullString `db:"tianyuan_message"` // 天远 API 返回描述
+		TransactionId   sql.NullString `db:"transaction_id"`   // 天远 API 流水号
+		EntryId         sql.NullString `db:"entry_id"`         // 天远规则ID（成功时）
+		EntryStatus     sql.NullString `db:"entry_status"`     // 规则状态（成功时）
+		EntryApiCodes   sql.NullString `db:"entry_api_codes"`  // 规则当前产品编码列表（JSON数组，成功时）
+	}
+)
+
+func newQueryWhitelistOpLogModel(conn sqlx.SqlConn, c cache.CacheConf) *defaultQueryWhitelistOpLogModel {
+	return &defaultQueryWhitelistOpLogModel{
+		CachedConn: sqlc.NewConn(conn, c),
+		table:      "`query_whitelist_op_log`",
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) Insert(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) (sql.Result, error) {
+	data.DelState = globalkey.DelStateNo
+	m.insertUUID(data)
+	yccQueryWhitelistOpLogIdKey := fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, data.Id)
+	return m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (result sql.Result, err error) {
+		query := fmt.Sprintf("insert into %s (%s) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", m.table, queryWhitelistOpLogRowsExpectAutoSet)
+		if session != nil {
+			return session.ExecCtx(ctx, query, data.Id, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes)
+		}
+		return conn.ExecCtx(ctx, query, data.Id, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes)
+	}, yccQueryWhitelistOpLogIdKey)
+}
+func (m *defaultQueryWhitelistOpLogModel) insertUUID(data *QueryWhitelistOpLog) {
+	t := reflect.TypeOf(data).Elem()
+	v := reflect.ValueOf(data).Elem()
+	for i := 0; i < t.NumField(); i++ {
+		sf := t.Field(i)
+		if sf.Tag.Get("db") == "id" {
+			f := v.Field(i)
+			if f.IsValid() && f.CanSet() && f.Kind() == reflect.String {
+				if f.String() == "" {
+					f.SetString(uuid.NewString())
+				}
+			}
+			break
+		}
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindOne(ctx context.Context, id string) (*QueryWhitelistOpLog, error) {
+	yccQueryWhitelistOpLogIdKey := fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, id)
+	var resp QueryWhitelistOpLog
+	err := m.QueryRowCtx(ctx, &resp, yccQueryWhitelistOpLogIdKey, func(ctx context.Context, conn sqlx.SqlConn, v interface{}) error {
+		query := fmt.Sprintf("select %s from %s where `id` = ? and del_state = ? limit 1", queryWhitelistOpLogRows, m.table)
+		return conn.QueryRowCtx(ctx, v, query, id, globalkey.DelStateNo)
+	})
+	switch err {
+	case nil:
+		return &resp, nil
+	case sqlc.ErrNotFound:
+		return nil, ErrNotFound
+	default:
+		return nil, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) Update(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) (sql.Result, error) {
+	yccQueryWhitelistOpLogIdKey := fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, data.Id)
+	return m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (result sql.Result, err error) {
+		query := fmt.Sprintf("update %s set %s where `id` = ?", m.table, queryWhitelistOpLogRowsWithPlaceHolder)
+		if session != nil {
+			return session.ExecCtx(ctx, query, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes, data.Id)
+		}
+		return conn.ExecCtx(ctx, query, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes, data.Id)
+	}, yccQueryWhitelistOpLogIdKey)
+}
+
+func (m *defaultQueryWhitelistOpLogModel) UpdateWithVersion(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) error {
+
+	oldVersion := data.Version
+	data.Version += 1
+
+	var sqlResult sql.Result
+	var err error
+
+	yccQueryWhitelistOpLogIdKey := fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, data.Id)
+	sqlResult, err = m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (result sql.Result, err error) {
+		query := fmt.Sprintf("update %s set %s where `id` = ? and version = ? ", m.table, queryWhitelistOpLogRowsWithPlaceHolder)
+		if session != nil {
+			return session.ExecCtx(ctx, query, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes, data.Id, oldVersion)
+		}
+		return conn.ExecCtx(ctx, query, data.DeleteTime, data.DelState, data.Version, data.AdminUserId, data.Action, data.Name, data.IdCard, data.IdCardMasked, data.ApiCodes, data.Remark, data.TianyuanCode, data.TianyuanMessage, data.TransactionId, data.EntryId, data.EntryStatus, data.EntryApiCodes, data.Id, oldVersion)
+	}, yccQueryWhitelistOpLogIdKey)
+	if err != nil {
+		return err
+	}
+	updateCount, err := sqlResult.RowsAffected()
+	if err != nil {
+		return err
+	}
+	if updateCount == 0 {
+		return ErrNoRowsUpdate
+	}
+
+	return nil
+}
+
+func (m *defaultQueryWhitelistOpLogModel) DeleteSoft(ctx context.Context, session sqlx.Session, data *QueryWhitelistOpLog) error {
+	data.DelState = globalkey.DelStateYes
+	data.DeleteTime = sql.NullTime{Time: time.Now(), Valid: true}
+	if err := m.UpdateWithVersion(ctx, session, data); err != nil {
+		return errors.Wrapf(errors.New("delete soft failed "), "QueryWhitelistOpLogModel delete err : %+v", err)
+	}
+	return nil
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindSum(ctx context.Context, builder squirrel.SelectBuilder, field string) (float64, error) {
+
+	if len(field) == 0 {
+		return 0, errors.Wrapf(errors.New("FindSum Least One Field"), "FindSum Least One Field")
+	}
+
+	builder = builder.Columns("IFNULL(SUM(" + field + "),0)")
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).ToSql()
+	if err != nil {
+		return 0, err
+	}
+
+	var resp float64
+	err = m.QueryRowNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return 0, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindCount(ctx context.Context, builder squirrel.SelectBuilder, field string) (int64, error) {
+
+	if len(field) == 0 {
+		return 0, errors.Wrapf(errors.New("FindCount Least One Field"), "FindCount Least One Field")
+	}
+
+	builder = builder.Columns("COUNT(" + field + ")")
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).ToSql()
+	if err != nil {
+		return 0, err
+	}
+
+	var resp int64
+	err = m.QueryRowNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return 0, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindAll(ctx context.Context, builder squirrel.SelectBuilder, orderBy string) ([]*QueryWhitelistOpLog, error) {
+
+	builder = builder.Columns(queryWhitelistOpLogRows)
+
+	if orderBy == "" {
+		builder = builder.OrderBy("id DESC")
+	} else {
+		builder = builder.OrderBy(orderBy)
+	}
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).ToSql()
+	if err != nil {
+		return nil, err
+	}
+
+	var resp []*QueryWhitelistOpLog
+	err = m.QueryRowsNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return nil, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindPageListByPage(ctx context.Context, builder squirrel.SelectBuilder, page, pageSize int64, orderBy string) ([]*QueryWhitelistOpLog, error) {
+
+	builder = builder.Columns(queryWhitelistOpLogRows)
+
+	if orderBy == "" {
+		builder = builder.OrderBy("id DESC")
+	} else {
+		builder = builder.OrderBy(orderBy)
+	}
+
+	if page < 1 {
+		page = 1
+	}
+	offset := (page - 1) * pageSize
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).Offset(uint64(offset)).Limit(uint64(pageSize)).ToSql()
+	if err != nil {
+		return nil, err
+	}
+
+	var resp []*QueryWhitelistOpLog
+	err = m.QueryRowsNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return nil, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindPageListByPageWithTotal(ctx context.Context, builder squirrel.SelectBuilder, page, pageSize int64, orderBy string) ([]*QueryWhitelistOpLog, int64, error) {
+
+	total, err := m.FindCount(ctx, builder, "id")
+	if err != nil {
+		return nil, 0, err
+	}
+
+	builder = builder.Columns(queryWhitelistOpLogRows)
+
+	if orderBy == "" {
+		builder = builder.OrderBy("id DESC")
+	} else {
+		builder = builder.OrderBy(orderBy)
+	}
+
+	if page < 1 {
+		page = 1
+	}
+	offset := (page - 1) * pageSize
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).Offset(uint64(offset)).Limit(uint64(pageSize)).ToSql()
+	if err != nil {
+		return nil, total, err
+	}
+
+	var resp []*QueryWhitelistOpLog
+	err = m.QueryRowsNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, total, nil
+	default:
+		return nil, total, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindPageListByIdDESC(ctx context.Context, builder squirrel.SelectBuilder, preMinId, pageSize int64) ([]*QueryWhitelistOpLog, error) {
+
+	builder = builder.Columns(queryWhitelistOpLogRows)
+
+	if preMinId > 0 {
+		builder = builder.Where(" id < ? ", preMinId)
+	}
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).OrderBy("id DESC").Limit(uint64(pageSize)).ToSql()
+	if err != nil {
+		return nil, err
+	}
+
+	var resp []*QueryWhitelistOpLog
+	err = m.QueryRowsNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return nil, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) FindPageListByIdASC(ctx context.Context, builder squirrel.SelectBuilder, preMaxId, pageSize int64) ([]*QueryWhitelistOpLog, error) {
+
+	builder = builder.Columns(queryWhitelistOpLogRows)
+
+	if preMaxId > 0 {
+		builder = builder.Where(" id > ? ", preMaxId)
+	}
+
+	query, values, err := builder.Where("del_state = ?", globalkey.DelStateNo).OrderBy("id ASC").Limit(uint64(pageSize)).ToSql()
+	if err != nil {
+		return nil, err
+	}
+
+	var resp []*QueryWhitelistOpLog
+	err = m.QueryRowsNoCacheCtx(ctx, &resp, query, values...)
+	switch err {
+	case nil:
+		return resp, nil
+	default:
+		return nil, err
+	}
+}
+
+func (m *defaultQueryWhitelistOpLogModel) Trans(ctx context.Context, fn func(ctx context.Context, session sqlx.Session) error) error {
+
+	return m.TransactCtx(ctx, func(ctx context.Context, session sqlx.Session) error {
+		return fn(ctx, session)
+	})
+
+}
+
+func (m *defaultQueryWhitelistOpLogModel) SelectBuilder() squirrel.SelectBuilder {
+	return squirrel.Select().From(m.table)
+}
+func (m *defaultQueryWhitelistOpLogModel) Delete(ctx context.Context, session sqlx.Session, id string) error {
+	yccQueryWhitelistOpLogIdKey := fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, id)
+	_, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (result sql.Result, err error) {
+		query := fmt.Sprintf("delete from %s where `id` = ?", m.table)
+		if session != nil {
+			return session.ExecCtx(ctx, query, id)
+		}
+		return conn.ExecCtx(ctx, query, id)
+	}, yccQueryWhitelistOpLogIdKey)
+	return err
+}
+func (m *defaultQueryWhitelistOpLogModel) formatPrimary(primary interface{}) string {
+	return fmt.Sprintf("%s%v", cacheYccQueryWhitelistOpLogIdPrefix, primary)
+}
+func (m *defaultQueryWhitelistOpLogModel) queryPrimary(ctx context.Context, conn sqlx.SqlConn, v, primary interface{}) error {
+	query := fmt.Sprintf("select %s from %s where `id` = ? and del_state = ? limit 1", queryWhitelistOpLogRows, m.table)
+	return conn.QueryRowCtx(ctx, v, query, primary, globalkey.DelStateNo)
+}
+
+func (m *defaultQueryWhitelistOpLogModel) tableName() string {
+	return m.table
+}
--- a/deploy/sql/admin_query_whitelist_menu_migration.sql
+++ b/deploy/sql/admin_query_whitelist_menu_migration.sql
@@ -0,0 +1,75 @@
+-- ============================================
+-- 查询白名单 - 后台菜单迁移 SQL
+-- 将「模块白名单」替换为「查询白名单」
+-- 数据库：ycc
+-- 父菜单：产品管理 (48d0e129-a141-4a74-b519-7adc38d22d27)
+-- ============================================
+
+-- 1. 软删除旧「模块白名单」菜单
+UPDATE `admin_menu`
+SET `del_state` = 1, `version` = `version` + 1
+WHERE `path` = '/product-manage/whitelist/list' AND `del_state` = 0;
+
+-- 2. 插入「查询白名单」菜单（已存在则跳过）
+INSERT INTO `admin_menu` (
+  `id`, `pid`, `name`, `path`, `component`, `redirect`, `meta`,
+  `status`, `type`, `sort`, `del_state`, `version`
+)
+SELECT
+  'd02e094d-6af8-11f1-bd31-dec53e82fe75',
+  '48d0e129-a141-4a74-b519-7adc38d22d27',
+  'queryWhitelist',
+  '/product-manage/query-whitelist/list',
+  '/product-manage/query-whitelist/list',
+  NULL,
+  JSON_OBJECT('icon', 'lucide:shield-off', 'title', '查询白名单'),
+  1,
+  1,
+  0,
+  0,
+  0
+FROM DUAL
+WHERE NOT EXISTS (
+  SELECT 1 FROM `admin_menu`
+  WHERE `path` = '/product-manage/query-whitelist/list' AND `del_state` = 0
+);
+
+-- 3. 给「超级管理员」授权新菜单
+INSERT INTO `admin_role_menu` (`id`, `role_id`, `menu_id`, `del_state`, `version`)
+SELECT
+  UUID(),
+  '741b7a39-a95d-4b9d-8dc0-84ee664d5fef',
+  m.`id`,
+  0,
+  0
+FROM `admin_menu` m
+WHERE m.`path` = '/product-manage/query-whitelist/list'
+  AND m.`del_state` = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM `admin_role_menu` rm
+    WHERE rm.`role_id` = '741b7a39-a95d-4b9d-8dc0-84ee664d5fef'
+      AND rm.`menu_id` = m.`id`
+      AND rm.`del_state` = 0
+  );
+
+-- 4. 给所有曾拥有旧「模块白名单」权限的角色同步授权
+INSERT INTO `admin_role_menu` (`id`, `role_id`, `menu_id`, `del_state`, `version`)
+SELECT
+  UUID(),
+  arm.`role_id`,
+  m.`id`,
+  0,
+  0
+FROM `admin_role_menu` arm
+JOIN `admin_menu` old_m ON old_m.`path` = '/product-manage/whitelist/list'
+JOIN `admin_menu` m ON m.`path` = '/product-manage/query-whitelist/list' AND m.`del_state` = 0
+WHERE arm.`menu_id` = old_m.`id`
+  AND arm.`del_state` = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM `admin_role_menu` x
+    WHERE x.`role_id` = arm.`role_id`
+      AND x.`menu_id` = m.`id`
+      AND x.`del_state` = 0
+  );
+
+-- 执行后请重新登录管理后台
--- a/deploy/sql/admin_query_whitelist_op_log_menu_migration.sql
+++ b/deploy/sql/admin_query_whitelist_op_log_menu_migration.sql
@@ -0,0 +1,9 @@
+-- ============================================
+-- 移除独立的「查询白名单记录」菜单（记录已合并到配置页下方）
+-- ============================================
+
+UPDATE `admin_menu`
+SET `del_state` = 1, `version` = `version` + 1
+WHERE `path` = '/product-manage/query-whitelist/op-log' AND `del_state` = 0;
+
+-- 执行后请重新登录管理后台
--- a/deploy/sql/query_whitelist_op_log_migration.sql
+++ b/deploy/sql/query_whitelist_op_log_migration.sql
@@ -0,0 +1,34 @@
+-- ============================================
+-- 查询白名单操作记录表
+-- 记录后台管理员通过天远 API 创建/追加屏蔽规则的操作
+-- ============================================
+
+CREATE TABLE IF NOT EXISTS `query_whitelist_op_log` (
+  `id` CHAR(36) NOT NULL COMMENT 'UUID主键',
+  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `delete_time` datetime DEFAULT NULL COMMENT '删除时间',
+  `del_state` tinyint NOT NULL DEFAULT '0' COMMENT '删除状态：0=未删除，1=已删除',
+  `version` bigint NOT NULL DEFAULT '0' COMMENT '版本号（乐观锁）',
+
+  `admin_user_id` CHAR(36) NOT NULL COMMENT '操作管理员ID',
+  `action` varchar(20) NOT NULL COMMENT '操作类型：create=创建规则，append=追加接口',
+  `name` varchar(50) NOT NULL DEFAULT '*' COMMENT '姓名规则',
+  `id_card` varchar(50) NOT NULL COMMENT '身份证号（明文，供后台审计）',
+  `id_card_masked` varchar(50) DEFAULT NULL COMMENT '天远返回的脱敏身份证号',
+  `api_codes` varchar(2000) NOT NULL COMMENT '本次提交的产品编码（JSON数组）',
+  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
+  `tianyuan_code` int NOT NULL DEFAULT 0 COMMENT '天远 API 业务码',
+  `tianyuan_message` varchar(500) DEFAULT NULL COMMENT '天远 API 返回描述',
+  `transaction_id` varchar(64) DEFAULT NULL COMMENT '天远 API 流水号',
+  `entry_id` varchar(64) DEFAULT NULL COMMENT '天远规则ID（成功时）',
+  `entry_status` varchar(20) DEFAULT NULL COMMENT '规则状态（成功时）',
+  `entry_api_codes` varchar(2000) DEFAULT NULL COMMENT '规则当前产品编码列表（JSON数组，成功时）',
+
+  PRIMARY KEY (`id`),
+  KEY `idx_admin_user_id` (`admin_user_id`),
+  KEY `idx_id_card` (`id_card`),
+  KEY `idx_action` (`action`),
+  KEY `idx_tianyuan_code` (`tianyuan_code`),
+  KEY `idx_create_time` (`create_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='查询白名单操作记录表';
--- a/tyapi.md
+++ b/tyapi.md
@@ -0,0 +1,324 @@
+# 查询白名单接口 — 下游对接说明
+
+> 本文档供**已开通权限的 API 用户 / 合作方**对接使用。  
+> 用于配置「查询为空」屏蔽规则：命中后，指定人员在指定接口上的查询将返回 `1000 查询为空`。
+
+---
+
+## 1. 服务地址
+
+| 环境 | 基础地址 |
+|------|----------|
+| 生产 | `https://api.tianyuanapi.com` |
+
+完整路径 = 基础地址 + 下表路径，例如：
+
+`https://api.tianyuanapi.com/api/v1/query-whitelist/entries`
+
+---
+
+## 2. 接口一览
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 创建规则 | POST | `/api/v1/query-whitelist/entries` | 首次为某身份证建立屏蔽规则 |
+| 追加接口 | POST | `/api/v1/query-whitelist/entries/append` | 向已有规则追加产品编码（去重合并） |
+
+**说明：**
+
+- 规则仅对**当前 `Access-Id` 对应账号**生效。
+- 本接口为**配置类接口**，不产生业务查询、**不扣费**，也不会出现在常规 API 调用记录中。
+- 规则生效后，该账号调用对应产品接口时，若命中屏蔽条件，将返回 `1000 查询为空`。
+
+---
+
+## 3. 鉴权
+
+每次请求需同时满足以下三项。
+
+### 3.1 请求头
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `Access-Id` | string | 是 | 您的 API 账号 Access-Id |
+| `Whitelist-Mgmt-Key` | string | 是 | 平台单独下发的**白名单管理密钥**（与 Access Key 不同，请向商务/技术支持索取） |
+| `Content-Type` | string | 是 | 固定为 `application/json` |
+
+### 3.2 请求体加密
+
+与业务 API 调用方式一致，外层仅传 `data`：
+
+```json
+{
+  "data": "<AES-128-CBC Base64 密文>"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | string | 是 | 业务参数经 Access Key 加密后的 Base64 字符串 |
+
+- 使用您账号的 **Access Key**（16 进制字符串）进行 AES 加密。
+- Access Key **仅用于本地加密**，不要写入明文 JSON。
+- 服务端根据请求头 `Access-Id` 查找密钥并解密；**解密成功即完成身份校验**。
+
+### 3.3 IP 白名单
+
+调用方出口 IP 须已加入该账号在控制台配置的 IP 白名单（与业务 API 要求一致）。未在白名单内的 IP 将返回 `1004`。
+
+---
+
+## 4. 业务参数（加密前明文 JSON）
+
+创建与追加接口的明文字段相同：
+
+```json
+{
+  "name": "*",
+  "id_card": "350681198611130611",
+  "api_codes": ["FLXG0V4B", "JRZQ8A2D"],
+  "remark": "可选备注"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 姓名；填 `*` 表示只按身份证匹配，不校验姓名 |
+| `id_card` | string | 是 | 18 位中国大陆身份证号 |
+| `api_codes` | string[] | 是 | 生效的产品编码列表，见下表约束 |
+| `remark` | string | 否 | 备注，最长 500 字符；追加接口传入非空时会覆盖原备注 |
+
+### 4.1 `api_codes` 约束
+
+| 传参方式 | 是否允许 | 示例 |
+|----------|----------|------|
+| 字符串数组 | 允许 | `["FLXG0V4B", "JRZQ8A2D"]` |
+| 单个字符串 | 不允许 | `"FLXG0V4B"` |
+| 通配 `*` | 不允许 | `["*"]` |
+| 空数组 | 不允许 | `[]` |
+| 非字符串元素 | 不允许 | `[123]` |
+
+---
+
+## 5. 创建与追加的区别
+
+同一账号下，**同一身份证号 + 同一 `name`** 仅对应**一条**规则；多个生效接口配置在该规则的 `api_codes` 数组中。
+
+### 5.1 创建 `POST /entries`
+
+| 情况 | 结果 |
+|------|------|
+| 尚无该身份证+姓名的规则 | 创建成功 |
+| 规则已存在 | 失败，`1013 规则已存在`（不会自动合并） |
+
+### 5.2 追加 `POST /entries/append`
+
+| 情况 | 结果 |
+|------|------|
+| 规则已存在 | 成功；将本次 `api_codes` 与已有列表**去重合并**（保留原顺序，新编码追加在后） |
+| 本次编码均已存在 | 仍返回成功（幂等），列表不变 |
+| 规则不存在 | 失败，`1014 规则不存在，请先调用创建接口` |
+
+**示例：**
+
+```
+创建：api_codes = ["FLXG0V4B"]
+追加：api_codes = ["JRZQ8A2D"]
+→ 合并后为 ["FLXG0V4B", "JRZQ8A2D"]（同一条规则，非新建）
+
+再次追加：api_codes = ["JRZQ8A2D", "FLXG2E8F"]
+→ ["FLXG0V4B", "JRZQ8A2D", "FLXG2E8F"]（JRZQ8A2D 已存在则跳过）
+```
+
+### 5.3 推荐流程
+
+1. 首次配置 → 调用**创建接口**（可一次传齐全部 `api_codes`）
+2. 后续增补产品 → 调用**追加接口**（只传新增编码）
+3. 创建返回 `1013` → 改调**追加接口**
+
+---
+
+## 6. 加密算法
+
+与业务 API 完全一致：
+
+1. Access Key 为 16 进制字符串，解码为 16 字节 AES 密钥
+2. 采用 **AES-128-CBC**，**PKCS7** 填充
+3. 每次加密随机生成 16 字节 IV，置于密文前
+4. IV + 密文整体做 **Base64** 编码，放入 `data`
+
+**加密步骤：**
+
+```
+明文 JSON → AES-128-CBC 加密 → [IV(16字节) + 密文] → Base64 → 填入 data 字段
+```
+
+**解密响应 `data` 时：** 取 Base64 解码后前 16 字节为 IV，余下为密文，用同一 Access Key 解密。
+
+---
+
+## 7. 响应格式
+
+HTTP 状态码均为 `200`。以响应体 `code` 判断业务是否成功。
+
+### 7.1 外层结构
+
+```json
+{
+  "code": 0,
+  "message": "业务成功",
+  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
+  "data": "<AES 加密字符串>"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int | `0` 表示成功，非 `0` 见错误码表 |
+| `message` | string | 结果描述 |
+| `transaction_id` | string | 本次请求流水号 |
+| `data` | string | 成功时返回，为规则详情的 AES 密文，需用 Access Key 解密 |
+
+### 7.2 `data` 解密后结构
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "*",
+  "id_card_masked": "350681********0611",
+  "api_codes": ["FLXG0V4B", "JRZQ8A2D"],
+  "status": "enabled",
+  "remark": "",
+  "created_at": "2026-06-18T10:00:00+08:00",
+  "updated_at": "2026-06-18T10:00:00+08:00"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 规则唯一标识 |
+| `name` | string | 姓名规则 |
+| `id_card_masked` | string | 脱敏身份证号 |
+| `api_codes` | string[] | 当前生效的产品编码列表 |
+| `status` | string | `enabled` 启用 / `disabled` 禁用 |
+| `remark` | string | 备注 |
+| `created_at` | string | 创建时间（ISO 8601） |
+| `updated_at` | string | 最近更新时间（ISO 8601） |
+
+---
+
+## 8. 错误码
+
+| code | message | 说明 |
+|------|---------|------|
+| 0 | 业务成功 | 创建或追加成功 |
+| 1001 | 接口异常 | 系统内部错误 |
+| 1002 | 解密失败 | `data` 无法解密 |
+| 1003 | 请求参数结构不正确 | 参数缺失、格式错误或 `api_codes` 不合法 |
+| 1004 | 未经授权的IP | 调用 IP 不在账号白名单 |
+| 1005 | 缺少Access-Id | 未传 `Access-Id` 请求头 |
+| 1006 | 未经授权的AccessId | Access-Id 无效或账号已冻结 |
+| 1010 | 缺少管理密钥 | 未传 `Whitelist-Mgmt-Key` |
+| 1011 | 管理密钥无效 | 管理密钥错误 |
+| 1012 | 接口未开放 | 功能未对该账号/环境开放 |
+| 1013 | 规则已存在 | 创建时：该身份证+姓名规则已存在 |
+| 1014 | 规则不存在 | 追加时：须先调用创建接口 |
+
+---
+
+## 9. 调用示例（Node.js）
+
+```javascript
+const crypto = require('crypto');
+
+const BASE_URL = 'https://api.tianyuanapi.com';
+const ACCESS_ID = '您的Access-Id';
+const ACCESS_KEY = '您的AccessKey';           // 16 进制，用于加解密
+const MGMT_KEY = '平台下发的Whitelist-Mgmt-Key';
+
+function encrypt(plainText, keyHex) {
+  const key = Buffer.from(keyHex, 'hex');
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv('aes-128-cbc', key, iv);
+  cipher.setAutoPadding(true);
+  let enc = cipher.update(plainText, 'utf8');
+  enc = Buffer.concat([iv, enc, cipher.final()]);
+  return enc.toString('base64');
+}
+
+function decrypt(cipherBase64, keyHex) {
+  const key = Buffer.from(keyHex, 'hex');
+  const buf = Buffer.from(cipherBase64, 'base64');
+  const iv = buf.slice(0, 16);
+  const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
+  decipher.setAutoPadding(true);
+  let dec = decipher.update(buf.slice(16));
+  dec = Buffer.concat([dec, decipher.final()]);
+  return dec.toString('utf8');
+}
+
+async function callWhitelistApi(path, payload) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Id': ACCESS_ID,
+      'Whitelist-Mgmt-Key': MGMT_KEY,
+    },
+    body: JSON.stringify({
+      data: encrypt(JSON.stringify(payload), ACCESS_KEY),
+    }),
+  });
+  const json = await res.json();
+  if (json.code === 0 && json.data) {
+    json.decrypted = JSON.parse(decrypt(json.data, ACCESS_KEY));
+  }
+  return json;
+}
+
+// 创建
+callWhitelistApi('/api/v1/query-whitelist/entries', {
+  name: '*',
+  id_card: '350681198611130611',
+  api_codes: ['FLXG0V4B'],
+  remark: '',
+}).then(console.log);
+
+// 追加
+callWhitelistApi('/api/v1/query-whitelist/entries/append', {
+  name: '*',
+  id_card: '350681198611130611',
+  api_codes: ['JRZQ8A2D'],
+}).then(console.log);
+```
+
+---
+
+## 10. 常见问题
+
+### `name` 填 `*` 是什么意思？
+
+只按**身份证号**匹配。只要业务请求中的身份证与该规则一致，无论传入什么姓名，均会返回「查询为空」。
+
+### 与业务 API 的 Access Key 是什么关系？
+
+- **Access Key**：加密请求/响应，证明账号身份（与业务 API 相同）。
+- **Whitelist-Mgmt-Key**：平台另行下发的管理授权密钥，证明有权调用白名单配置接口。
+
+两者缺一不可。
+
+### 调用成功后，常规 API 调用记录里能看到吗？
+
+不能。本接口为配置类操作，不计入业务 API 调用次数，也不扣费。
+
+### 屏蔽何时生效？
+
+接口返回 `code = 0` 后即生效（通常数秒内）。之后该账号调用 `api_codes` 中包含的产品且入参命中身份证（及姓名规则）时，将返回 `1000 查询为空`。
+
+---
+
+## 11. 联系方式
+
+- **Access-Id / Access Key**：登录控制台 → API 密钥
+- **Whitelist-Mgmt-Key**：向平台商务或技术支持申请
+- **IP 白名单**：登录控制台 → API 设置中配置