func (h *handler) Registry(ws *restful.WebService) {
	tags := []string{"资源检索"}

	ws.Route(ws.GET("/search").To(h.SearchResource).
		Doc("检索资源").                                    // OpenAPI 文档描述
		Metadata(restfulspec.KeyOpenAPITags, tags).          // 文档分组标签
		Metadata(label.Resource, h.Name()).                  // 权限点：资源=resource
		Metadata(label.Action, label.List.Value()).          // 权限点：动作=list
		Metadata(label.Auth, label.Enable).                  // 该路由需要鉴权
		Reads(resource.SearchRequest{}).                     // 文档：请求参数类型
		Writes(resource.ResourceSet{}).                      // 文档：响应类型
		Returns(200, "OK", resource.ResourceSet{}))          // 文档：返回码

	// 资源发现（给 Prometheus 用）
	ws.Route(ws.GET("/discovery/prometheus").To(h.DiscoveryPrometheus).
		Doc("监控发现(Prometheus)").
		Metadata(restfulspec.KeyOpenAPITags, tags).
		Metadata(label.Resource, "prometheus_resource").
		Metadata(label.Action, label.List.Value()).
		Reads(resource.SearchRequest{}).
		Writes(resource.ResourceSet{}).
		Returns(200, "OK", resource.ResourceSet{}))
}

var (
	h = &handler{}                    // 包级单例 handler
)

type handler struct {
	service resource.Service          // 注意：持有的是 Service 接口（gRPC 实现的本地引用）
	log     logger.Logger
}

func (h *handler) Config() error {
	h.log = zap.L().Named(resource.AppName)
	// 魔法在这里：从框架的注册表里按模块名取出 gRPC 服务实现，
	// 断言成 Go 接口后直接当本地方法调用！
	h.service = app.GetGrpcApp(resource.AppName).(resource.Service)
	return nil
}

func (h *handler) QuerySecret(r *restful.Request, w *restful.Response) {
	// 1. 参数绑定：URL Query → Go 结构体（模块根包提供的构造函数）
	req := secret.NewQuerySecretRequestFromHTTP(r.Request)
	// 2. 调 Service（进程内直接调用）
	set, err := h.service.QuerySecret(r.Request.Context(), req)
	if err != nil {
		response.Failed(w, err)      // 统一错误响应
		return
	}
	// 3. 返回前脱敏（密钥绝不能出接口）
	set.Desense()
	response.Success(w, set)
}

// apps/resource/impl/impl.go 的 service 结构（示意，字段来自源码）
type service struct {
	db  *gorm.DB    // GORM 流派：conf.C().MySQL.ORM() 拿到
	log logger.Logger
	resource.UnimplementedServiceServer
}

func (s *service) Config() error {
	// 依赖注入：按 AppName 从框架取出兄弟模块的接口实现
	s.secret = app.GetInternalApp(secret.AppName).(secret.Service)
	s.host   = app.GetGrpcApp(host.AppName).(host.ServiceServer)
	s.bill   = app.GetGrpcApp(bill.AppName).(bill.ServiceServer)
	s.rds    = app.GetGrpcApp(rds.AppName).(rds.ServiceServer)
	...
}

func (s *service) BuildQuery(ctx context.Context, req *resource.SearchRequest) (*gorm.DB, error) {
	query := s.db.WithContext(ctx).
		Table("resource_meta m").                                           // 主表取别名 m
		Joins("LEFT JOIN resource_spec spsc ON spec.resource_id=m.id").    // JOIN 规格表
		Joins("LEFT JOIN resource_cost cost ON cost.resource_id=m.id").
		Joins("LEFT JOIN resource_status status ON status.resource_id=m.id")
	// ……下面根据 req 里的非空字段逐个追加 Where（省略，5.3 节详讲）
	return query, nil
}

query := sqlbuilder.NewQuery(queryHostSQL)      // 以 SQL 常量为基座
if req.Keywords != "" {                          // 按需追加 WHERE
	query.Where("r.name LIKE ? OR r.id = ? OR r.private_ip LIKE ? OR r.public_ip LIKE ?",
		"%"+req.Keywords+"%", req.Keywords, req.Keywords+"%", req.Keywords+"%")
}
// 分页 + 排序 + 分组
querySQL, args := query.
	GroupBy("r.id").
	Order("r.sync_at").Desc().
	Limit(req.OffSet(), uint(req.Page.PageSize)).
	BuildQuery()                                  // 生成最终 SQL + 参数切片
queryStmt, err := s.db.PrepareContext(ctx, querySQL)   // 预编译防注入
defer queryStmt.Close()
rows, err := queryStmt.QueryContext(ctx, args...)       // 参数化执行

// apps/resource/impl/resource.go:10-53 —— 更新资源包含创建
func (s *service) Put(ctx context.Context, res *resource.Resource) (
	*resource.Resource, error) {
	// ① 参数校验（proto message 的 Validate 方法）
	if err := res.Validate(); err != nil {
		return nil, err
	}

	// ② 开启事务：四张子表要么全写成功，要么全回滚
	var err error
	tx := s.db.WithContext(ctx).Begin()
	defer func() {
		if err == nil {
			tx.Commit()      // 全成功 → 提交
		} else {
			tx.Rollback()   // 任何一步失败 → 回滚
		}
	}()

	// ③ proto 模型 → 分表模型（第 4 章讲过的 NewResource）
	temp := NewResource(res)

	// ④ 依次写四张表
	if err := tx.Save(temp.ResourceMeta).Error; err != nil {   // meta 表
		return nil, err
	}
	if err := tx.Save(temp.ResourceSpec).Error; err != nil {   // spec 表
		return nil, err
	}
	if res.Cost != nil {                                        // cost 表（有费用才写）
		if err := tx.Save(temp.ResourceCost).Error; err != nil {
			return nil, err
		}
	}
	if err := tx.Save(temp.ResourceStatus).Error; err != nil { // status 表
		return nil, err
	}
	// ⚠️ 注意：temp.Tags 被构建了，但这里没有 tx.Save(temp.Tags)！
	// 这是底稿 7.2 节指出的真实缺口：标签不会写入 resource_tag 表

	return res, nil
}

// apps/secret/interface.go:42-56 —— 加密：入库前调用
func (s *CreateSecretRequest) EncryptAPISecret(key string) error {
	// 幂等保护：已经是密文就不再加密（防止二次加密）
	if strings.HasPrefix(s.ApiSecret, conf.CIPHER_TEXT_PREFIX) {
		return fmt.Errorf("text has ciphered")
	}
	// CBC 对称加密（key 来自配置 app.encrypt_key）
	cipherText, err := cbc.Encrypt([]byte(s.ApiSecret), []byte(key))
	if err != nil {
		return err
	}
	// base64 编码后加上密文前缀标记
	base64Str := base64.StdEncoding.EncodeToString(cipherText)
	s.ApiSecret = fmt.Sprintf("%s%s", conf.CIPHER_TEXT_PREFIX, base64Str)
	// 最终形态：@ciphered@xBa9sD7f...（前缀+base64密文）
	return nil
}

// apps/secret/interface.go:104-113 —— api_key 掩码脱敏
func (s *CreateSecretRequest) DensenseKey() string {
	if s.ApiKey == "" {
		return ""
	}
	total := len(s.ApiKey)
	if total > 8 {
		// 只露前 4 后 4 位：LTAI5t****x9Km
		return fmt.Sprintf("%s****%s", s.ApiKey[:4], s.ApiKey[total-4:])
	}
	return s.ApiKey
}

// apps/resource/impl/dao.go 节选 —— 检索条件动态拼装
if req.Vendor != nil {
	query = query.Where("spec.vendor = ?", req.Vendor)   // ⚠️ 用了 spec 别名
}
if req.Type != nil {
	query = query.Where("spec.type = ?", req.Type)       // ⚠️ 同上
}
if req.Status != "" {
	query = query.Where("status.phase = ?", req.Status)
}
if req.Keywords != "" {
	query = query.Where("r.name LIKE ? OR r.id = ? OR r.private_ip LIKE ? OR r.public_ip LIKE ?",
		// ⚠️ 用了 r 别名
		"%"+req.Keywords+"%", req.Keywords, req.Keywords+"%", req.Keywords+"%")
}

// apps/host/impl/host.go:97-121 节选 —— 原生 SQL 查询结果手工组装
for rows.Next() {
	ins := host.NewDefaultHost()
	base := ins.Resource.Meta      // 借出三个子结构的指针
	info := ins.Resource.Spec
	desc := ins.Describe
	err := rows.Scan(              // 逐列按顺序塞进结构体字段
		&base.Id, &info.ResourceType, &info.Vendor, &info.Region, &info.Zone,
		&base.CreateAt, &info.ExpireAt,
		&info.Category, &info.Type, &info.Name, &info.Description,
		&ins.Resource.Status.Phase, &info.UpdateAt, &base.SyncAt, &info.Owner,
		&publicIPList, &privateIPList, &ins.Resource.Cost.PayMode, &base, &base,
		&base.CredentialId, &base.Domain, &base.Namespace, &base.Env, &base.UsageMode, &base.Id,
		&desc.GpuSpec, &desc.OsType, &desc.OsName,
		&desc.ImageId, &desc.InternetMaxBandwidthOut, &desc.InternetMaxBandwidthIn,
		&keyPairNameList, &securityGroupsList,
	)
	if err != nil {
		return nil, exception.NewInternalServerError("query host error, %s", err.Error())
	}
	// 字符串还原为数组："1.1.1.1,2.2.2.2" → []string
	ins.Resource.Status.LoadPrivateIPString(privateIPList)
	ins.Resource.Status.LoadPublicIPString(publicIPList)
	desc.LoadKeyPairNameString(keyPairNameList)
	desc.LoadSecurityGroupsString(securityGroupsList)
	set.Add(ins)
}