schema-optimizer

架构优化器

用途

分析架构中的质量问题并提出改进建议。识别未使用的字段、配置错误的合并操作、缺失的映射、身份解析缺口以及 PII 暴露风险。仅进行只读分析，并提供可执行的建议。

环境

需要经过身份验证的 API 访问权限。有关凭据解析，请参阅 ../references/auth.md。

输入

• 表（默认值：user）
• 可选的关注领域：unused-fields、coverage、identity、merge-ops、mappings、pii 或 all

分析流程

运行所有检查（或指定的关注领域），然后生成统一报告。

第 1 步：收集数据

并行获取三个核心数据集：

# All fields with metadata
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# All mappings
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/mapping" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# All segments (to find field references)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

第 2 步：收集字段覆盖率

# Field info with presence/absence counts
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

第 3 步：收集身份配置

# Identity resolution config and ranks
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/rank" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/idconfig" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

分析检查项

检查 1：未使用的字段

将字段与分段 FilterQL 交叉比对，找出架构中存在但任何分段都未引用的字段。

1. 解析每个分段中的 segment_ql，提取引用的字段名称
2. 与所有架构字段进行比对
3. 标记符合以下条件的字段：
   • 未被任何分段引用，且 ents_present 为零或非常低
   • 未被任何分段引用，但有数据（可能对未来的分段有用）

### Unused Fields (12 found)

Never referenced in segments AND empty:
  legacy_score        -- 0 profiles, created 2024-03-01, no mappings
  old_campaign_tag    -- 0 profiles, created 2024-06-15, 1 stale mapping

Never referenced but have data:
  browser_version     -- 45,000 profiles (31%), not in any segment
  referrer_domain     -- 89,000 profiles (61%), not in any segment
  (these may be useful -- review before removing)

检查 2：未生效的字段（无映射）

没有映射的字段永远不会从任何数据流接收数据。

1. 获取所有字段和所有映射
2. 找出没有任何映射指向该字段名称的字段
3. 排除由系统管理的字段（ManagedBy = "lytics" 或类似值）

### Inert Fields -- No Mappings (3 found)

  custom_score    -- type: number, created 2025-01-10, no mapping exists
  user_tier       -- type: string, created 2025-02-20, no mapping exists
  (these fields will never receive data until a mapping is added)

检查 3：字段覆盖率

找出覆盖率很低但被分段使用的字段——这会限制受众范围。

### Low Coverage Fields Used in Segments

  phone           -- 12% coverage, used in 2 segments
  company_name    -- 8% coverage, used in 1 segment
  (segments using these fields are limited to at most N% of profiles)

检查 4：身份解析

检查身份字段配置：

• 是否有任何字段标记为标识符？（至少需要一个才能解析用户档案）
• 排序是否合理？（优先级较高的字段应是更稳定的标识符）
• 身份字段相对于字段总数的数量是多少？

### Identity Resolution

Identity fields: 3 configured
  1. email        -- rank 1, coverage: 92%
  2. _uid         -- rank 2, coverage: 100%
  3. user_id      -- rank 3, coverage: 45%

Observations:
  3 identity fields configured -- looks reasonable
  email is rank 1 with 92% coverage -- good primary identifier
  user_id has 45% coverage -- only useful for profiles from sources that provide it

注意：IDConfig（压缩设置）是可选的，大多数账户不需要。只有在用户明确询问身份压缩时才提及。

检查 5：合并操作审查

标记可能与字段数据类型或使用模式不匹配的合并操作：

字段类型	典型的 MergeOp	配置错误时的问题
string（姓名、电子邮件）	latest	sum/count 毫无意义
int（访问次数）	sum 或 count	latest 会丢失累计值
number（分数）	latest 或 max	sum 可能导致数值无限增长
[]string（标签、类别）	merge	latest 会丢失历史记录
date（last_visit）	latest 或 max	min 会使值停留在初始值
map[string]int（操作计数）	merge 或 mapmax	latest 会丢失数据

### Merge Operation Review

Potential issues:
  visit_count (int, merge_op: latest)
    -> Recommendation: consider 'sum' or 'count' to accumulate visits

  tags ([]string, merge_op: latest)
    -> Recommendation: consider 'merge' to accumulate tag values

  engagement_score (number, merge_op: sum)
    -> Recommendation: consider 'latest' or 'max' -- summing scores causes unbounded growth

检查 6：PII 暴露

标记在分段 FilterQL 中出现的 PII 字段（通过分段定义导致潜在的数据暴露）。

### PII in Segments

  email (PII) -- referenced in 3 segments
    "Email Subscribers": EXISTS email
    (EXISTS checks are generally safe -- no value exposure)

  phone (PII) -- referenced in 1 segment
    "Phone Contacts": phone CONTAINS "+1"
    WARNING: FilterQL contains a literal value match on PII field

检查 7：容量和保留

对于集合和映射字段，检查是否设置了容量，以及容量是否与实际基数相符。

### Capacity Review

  products_purchased ([]string, capacity: 100, actual cardinality: 2,340)
    -> WARNING: Cardinality far exceeds capacity. Values are being dropped.
    -> Recommendation: increase capacity or review if all values are needed

  action_counts (map[string]int, capacity: 0)
    -> WARNING: No capacity limit. Map will grow unbounded.
    -> Recommendation: set a capacity limit

输出格式

## Schema Optimization Report (user table)

### Summary
- Total fields: 145
- Unused fields: 12 (8%)
- Inert fields (no mapping): 3
- Low-coverage fields in segments: 5
- Identity issues: 1
- Merge op concerns: 3
- PII exposure warnings: 1
- Capacity warnings: 2

### Priority Recommendations
1. HIGH: 3 fields have no mappings and will never receive data -- add mappings or remove fields
2. MEDIUM: visit_count uses 'latest' merge -- consider 'sum' to accumulate
3. MEDIUM: products_purchased capacity (100) exceeded by cardinality (2,340) -- values being dropped
4. LOW: 12 fields are unused -- review and archive if no longer needed

[Detailed findings per check follow...]

错误处理

• 架构较大：如果字段超过 500 个，则分批请求 fieldinfo。提醒用户这可能需要一些时间。
• 没有分段：如果不存在分段，则跳过使用情况分析并注明这一点。
• Fieldinfo 不可用：如果 fieldinfo 端点失败，则仅根据元数据继续分析（跳过覆盖率和容量检查）。

依赖项

• 组合使用：schema-manager skill、segment-manager skill
• 参考：../references/field-types.md、../references/auth.md、../references/api-client.md