数据质量 · LightFoundry · frontend-intro-v5

1. 页面概览

1.1 是什么

数据质量页面（QualityPage.vue）是 LightFoundry 对数据资产做「规则化质检 + 问题闭环 + 四因子评分」的统一界面。页面以三个 Tab 组织三类能力：

规则管理：面向数据管道（pipeline）或本体对象（object）声明质量规则，支持 null（空值检查）、format（格式正则）、unique（唯一性）、referential（参照完整性）四类规则，可随时启用/停用/删除；
质量问题：展示规则检查命中的问题清单（data_quality_issues），支持按状态筛选、展开违规样本、确认（acknowledge）与修复（fix）闭环；
质量画像：由子组件 QualityProfilePanel.vue 提供，围绕 completeness（完整度）/ uniqueness（唯一度）/ validity（有效性）/ freshness（新鲜度）四因子对数据集做加权评分，支持 cron 调度、立即运行、评分历史追溯与低于阈值自动产生质量问题。

这三块能力在 V5 Stage 1（B1-2 质量画像、B1-3 同步引擎 bridge）落地：质量画像的低于阈值评分会经 profileIssueBridge 写入既有的 data_quality_issues 表，复用「质量问题」Tab 的列表与 acknowledge/fix 闭环；同步引擎（sync 包）运行成功后也会经 datasetProfileBridge 自动触发画像评分，形成「同步 → 画像 → 问题」的数据健康链路。

1.2 核心价值

维度	说明
规则化质检	四类规则（null/format/unique/referential）声明式配置，检查结果带违规行数与样本
问题闭环	open → acknowledged → fixed 三段状态机，确认/修复操作有二次确认保护
四因子画像	completeness/uniqueness/validity/freshness 加权总分（0~100），阈值可配
诚实标注	validity 超 1000 行拉样标注 sampled、缺 pk/水位列标注 na，不静默吞掉
自动联动	画像低于阈值自动产生 issue；同步成功自动触发画像；cron 调度定时运行
独立 API 实例	画像模块走 `qualityProfileApi.js`（超时 120 秒），与普通接口隔离

1.3 一句话总结

在 Foundry 用「规则 + 画像」双重手段管理数据质量：规则负责把问题揪出来闭环处理，画像负责给数据集打出可解释的四因子健康分，两者共用一张问题表闭环联动。

2. 访问入口

2.1 路由与菜单

路由：/foundry/quality
路由名称：FoundryQuality
菜单位置：Foundry 左侧边栏「数据质量」（FoundryLayout.vue 菜单第 12 项，位于「数据血缘」之后、「语义检索」之前）
源码文件：action/web/src/views/QualityPage.vue（699 行）+ action/web/src/views/QualityProfilePanel.vue（708 行，质量画像子组件）

2.2 认证与权限

需要登录：是（路由 meta.requiresAuth = true）
登录方式：AIP 统一登录，localStorage.aip_token 作为 Bearer Token 自动附带
页面本身无角色限制；但画像/规则的作用对象必须是真实存在的数据集或对象，后端 checkScopeExists 会校验作用域存在性，不存在的 scope 创建会直接报错
404 排错：若访问 /foundry/quality 出现 404，先确认 Foundry 后端（端口 18081）已启动、前端路由已注册（router/index.js 第 245~249 行）

2.3 端口与 API 前缀

后端端口：18081（Foundry）
前端 API 前缀：/api/v1
- 规则/问题两个 Tab 用 client.js（超时 30 秒）
- 画像 Tab 用 qualityProfileApi.js（超时 120 秒，因 run 可能全表扫描）

3. 界面布局

页面纵向整体结构如下（三 Tab 横向切换）：

┌────────────────────────────────────────────────────────────┐
│ ① 页头：标题「数据质量」                                      │
│ ② 操作结果提示条（alert，成功绿 / 失败红，可关闭）             │
│ ③ Tab 切换：[规则管理] [质量问题] [质量画像]                  │
│ ┌────────────── Tab1 规则管理 ──────────────┐                │
│ │ 卡片：标题（规则管理）+「+ 新建规则」按钮    │                │
│ │  ├─ 创建规则表单（展开后出现，可收起）       │                │
│ │  ├─ 编辑规则表单（选中行后出现：名称/配置/   │                │
│ │  │   严重级别/启用位；类型与作用域只读）     │                │
│ │  ├─ 规则列表表格（ID/名称/范围/对象/类型/    │                │
│ │  │   检查列/严重级别/状态/操作）             │                │
│ │  ├─ 本地分页（每页 10 条）                  │                │
│ │  └─ 诚实提示：列表无服务端分页；规则可改     │                │
│ │      名称/配置/严重级别，作用域与类型不可变  │                │
│ ├────────────── Tab2 质量问题 ──────────────┤                │
│ │ 卡片：状态筛选下拉 +「刷新」按钮             │                │
│ │ 卡片：问题列表表格（含样本展开行）+ 本地分页  │                │
│ ├────────────── Tab3 质量画像 ──────────────┤                │
│ │ QualityProfilePanel：工具栏 + 新建表单 +    │                │
│ │ 画像列表（含本地分页）+ 已删除画像（本次会话）│               │
│ │ + 评分历史抽屉                              │                │
│ └────────────────────────────────────────────┘                │
└────────────────────────────────────────────────────────────┘

各板块职责：

① 页头：标题标识当前功能域。
② 提示条：页面内唯一的消息反馈区，任何成功/失败都会在这里展示，并带「关闭」按钮清除。
③ Tab 切换：三个 Tab 用 activeTab 状态切换，点击即切换视图；规则与问题两个 Tab 在 onMounted 时并行预加载数据。
Tab1 规则管理：声明质量规则并维护规则生命周期（启用/停用/删除）。
Tab2 质量问题：查看规则检查命中问题并按状态流转处理。
Tab3 质量画像：四因子评分面板，含创建、运行、历史、启停、删除全套操作。

4. 交互元素详解

4.1 Tab 切换

属性	值
控件	三个按钮组成的 Tab 条（`.tab-btn`，激活态带下划线高亮）
选项	「规则管理」「质量问题」「质量画像」，对应 `tabs` 数组 `rules/issues/profiles`
交互效果	点击切换 `activeTab`，`v-if` 控制仅渲染当前 Tab 内容

4.2 Tab1 规则管理 —— 新建规则入口

属性	值
按钮文字	「+ 新建规则」（表单展开时变为「收起表单」）
交互效果	切换 `showCreateForm`，展开/收起创建表单；默认收起
表单校验	前端 `required` 标记：规则名称、作用对象 ID、检查列；另有 `handleCreate` 内的逻辑校验（见 4.4）

4.3 创建规则表单字段

字段	控件	必填	默认值	说明
规则名称	`<input>`	是	空	如 `orders_amount_not_null`，创建时 `trim()`
作用范围 scope_type	`<select>`	是	object	`pipeline`（管道）/ `object`（本体对象）
作用对象 ID scope_id	`<input type=number>`	是	1	数字，如 1
规则类型 rule_type	`<select>`	是	null	`null`/`format`/`unique`/`referential`
严重级别 severity	`<select>`	否	warning	`warning`/`error`（error 违规会使管道 run 标 failed）
检查列 column	`<input>`	是	空	被检查属性列，如 `amount`
格式正则 format_regex	`<input>`	format 时是	空	仅 `rule_type=format` 时显示，如 `^[0-9]{11}$`
引用表 ref_table	`<input>`	referential 时是	空	仅 `rule_type=referential` 时显示，如 `customers`
引用列 ref_column	`<input>`	referential 时是	空	仅 `rule_type=referential` 时显示，如 `id`
创建后即启用	`<checkbox>`	否	勾选	对应 `enabled` 字段

动态提示：当 rule_type 为 null 或 unique 时，表单下方显示「规则类型「null」仅需指定检查列，无需额外配置。」（文案随类型变化）。

提交按钮：「创建规则」（提交中变「提交中...」并禁用）与「取消」（调 resetCreateForm 清空表单并收起）。

4.4 创建规则逻辑校验与提交

点击「创建规则」后 handleCreate 先做前端校验：

format 类型未填 format_regex（trim 后为空）→ 提示「format 类型规则需要填写格式正则 format_regex」并中止；
referential 类型 ref_table 或 ref_column 为空 → 提示「referential 类型规则需要填写引用表 ref_table 与引用列 ref_column」并中止。

校验通过后 buildRuleConfig() 按类型组装 rule_config（column 恒有；format 追加 format_regex；referential 追加 referential:{ref_table, ref_column}），再 POST /quality/rules 提交 {name, scope_type, scope_id, rule_type, rule_config, severity, enabled}。成功后提示「规则创建成功 id=...」并刷新列表；失败提示「规则创建失败：<后端 error>」。

4.5 规则列表表格

列	说明
ID	规则主键
名称	加粗展示
作用范围	`scope_type` 原文
作用对象	`#` + `scope_id`
规则类型	`rule_type` 原文
检查列	`ruleColumn(r)` 拼接：`column`，format 追加 `· 正则`，referential 追加 `· 引用表.列`
严重级别	徽章 `sev-warning`（黄）/`sev-error`（红）
状态	徽章「启用」（绿）/「停用」（灰）
操作	「编辑」+「停用/启用」+「删除」三个小按钮

启用/停用：handleToggle 调 PUT /quality/rules/:id，请求体 {enabled: !r.enabled}，成功后提示「规则"xxx"已停用/启用」并刷新。删除：先 confirm 二次确认「确定删除规则"xxx"吗？（历史问题保留）」，确认后 DELETE /quality/rules/:id，成功提示「规则已删除」，历史问题保留（只删规则定义，data_quality_issues 不受影响）。

编辑规则：行内「编辑」按钮（startEditRule）回填 editForm（名称 / 严重级别 / rule_config / 启用位），在创建表单下方展开编辑表单（类型与作用域只读展示）。保存（handleUpdateRule）调 PUT /quality/rules/:id，请求体 {name, severity, rule_config, enabled}；成功后提示「规则"xxx"已更新」并刷新列表。作用域（scope_type/scope_id）与规则类型（rule_type）不可变更（后端刻意留作不可变：变更等同重建规则并令历史问题归属失真），需更换请删除后重建——表单以只读字段标注。

本地分页：pagedRules 按每页 10 条切片，分页条仅规则数 > 10 时显示；GET /quality/rules 无分页参数（见 5.2），故为渲染层分页，仍一次全量拉取。

4.6 Tab2 质量问题 —— 状态筛选与刷新

属性	值
控件	状态筛选下拉（`select`，`min-width:160px`）+「刷新」按钮
筛选选项	全部 / `open`（待处理）/ `acknowledged`（已确认）/ `fixed`（已修复）
交互效果	下拉 `change` 立即触发 `fetchIssues`；「刷新」手动重新拉取；请求带 `?status=` 参数（空值不带参数）

4.7 问题列表表格

列	说明
ID	问题主键
规则 ID	`#` + `rule_id`
受影响表	`affected_table`
违规行数	`issueCount(it)`：取 `affected_rows.count`，缺失显示 `-`
状态	徽章 `issue-open`（红）/`issue-acknowledged`（黄）/`issue-fixed`（绿）
创建时间	`formatTime(created_at)`：`2026-08-09T10:00:00Z → 2026-08-09 10:00:00`
操作	「样本」+「确认」+「修复」

样本展开：点击「样本」切换 expandedId，展开行跨 7 列显示「违规样本 sample（N 行）」子表格，列头由 sampleColumns(it) 取样本首行对象的键生成，值 row[k] 逐格渲染；无样本显示「无样本数据」。

确认：仅 status=open 时可点（否则禁用），先 confirm「确认问题 #N（表 xxx）吗？」，再 POST /quality/issues/:id/acknowledge，成功提示「问题 #N 已确认（状态：acknowledged）」。

修复：status=fixed 时禁用，先 confirm「确定将问题 #N（表 xxx）标记为已修复吗？」，再 POST /quality/issues/:id/fix，成功提示「问题 #N 已修复（状态：fixed）」。

本地分页：pagedIssues 按每页 10 条切片，分页条仅问题数 > 10 时显示；GET /quality/issues 无分页参数（见 5.2），故为渲染层分页。切换状态筛选或点「刷新」后页码重置为第 1 页并收起样本展开行（避免展开行不在当前页导致错位）。

4.8 Tab3 质量画像 —— 工具栏与创建表单

工具栏：「+ 新建画像」（展开时变「收起表单」）+「刷新」按钮（fetchAll 并行拉画像与数据集）。

新建画像表单（QualityProfilePanel.vue）：

字段	控件	必填	默认	说明
画像名称	`<input>`	是	空	如 `orders_quality_daily`
作用范围 scope_type	`<select>`	是	dataset	`dataset`（数据集）/ `object`（本体对象，本版仅登记）
作用对象 scope_id	dataset 下拉 / object 输入框	是	空	dataset 时下拉展示 `名称（N 行）`，value 为数据集 id
阈值 threshold	`<input type=number>`	否	60	0~100，总分低于阈值产生质量问题
completeness 完整度	`<input type=number step=0.05>`	否	0.45	权重
uniqueness 唯一度	`<input type=number step=0.05>`	否	0.25	权重
validity 有效性	`<input type=number step=0.05>`	否	0.15	权重
freshness 新鲜度	`<input type=number step=0.05>`	否	0.15	权重
主键列 pk_column	`<input>`	否	空	唯一度用，缺省按 1 记并标注 na
水位列 watermark_col	`<input>`	否	空	新鲜度用，缺省按 1 记并标注 na
调度 schedule	`<input>`	否	空	5/6 段 cron 或 @ 描述符，如 `0 9 * * *`

关键提示文案：四因子权重「留空使用默认 0.45/0.25/0.15/0.15；不必凑 1，后端自动归一」；计算配置下方说明「四因子 SQL 下推计算；validity 对 date 列与下推困难的列拉 ≤1000 行样本计算并标注 sampled；低于 threshold 产生质量问题（连续低于阈值自动去重，恢复后再次跌破重新触发）。」

提交：「创建」（创建中变「创建中...」）与「取消」。handleCreate 组装 payload：{name, scope_type, scope_id} 必填，threshold 非空转数字、权重按非空逐项填入 weights、pk_column/watermark_col 非空填入 config、schedule 非空直接透传，然后 POST /quality/profiles。成功提示「画像创建成功」并刷新。

4.9 画像列表表格

列	说明
名称	加粗展示
作用范围	徽章 `scope-dataset`（蓝）/`scope-object`（紫）+ 作用对象名（`scopeName`：dataset 反查数据集名）
权重（c/u/v/f）	`weightsSummary` 解析 JSON 后四段数字，如 `0.45 / 0.25 / 0.15 / 0.15`
阈值	`threshold` 数字
调度	`code` 展示 cron，空显示「手动」
最新总分	徽章 `score-high`（≥80 绿）/`score-mid`（≥60 橙）/`score-low`（<60 红），未运行显示「未运行」
状态	徽章「启用」（`status-on` 绿）/「停用」（`status-off` 灰）
更新时间	`fmtTime(updated_at)`
操作	「运行」「历史」「停用/启用」「删除」

运行：POST /quality/profiles/:id/run，成功后提示「画像「xxx」运行完成：总分 N.N（阈值 M）」并刷新列表与最新分。
历史：GET /quality/profiles/:id/scores?limit=100 打开评分历史抽屉。
停用/启用：PUT /quality/profiles/:id 请求体 {enabled: !p.enabled}（指针语义，仅改这一项），提示「画像已停用/启用」。
删除：confirm「确认删除画像「xxx」？（评分历史保留）」后 DELETE /quality/profiles/:id，评分历史保留；被删画像记入下方「已删除画像（本次会话保留）」列表，历史抽屉若正打开该画像则保持打开（历史仍有效）。
本地分页：pagedProfiles 按每页 10 条切片，分页条仅画像数 > 10 时显示；GET /quality/profiles 无分页参数（见 5.2），故为渲染层分页。「最新总分」只为当前页画像各拉一条 scores?limit=1，避免对全部画像并发 N+1。

已删除画像（本次会话保留）：删除画像只删 fq_profiles 定义，评分历史 fq_scores 在后端保留，且 GET /quality/profiles/:id/scores 按 profile_id 直查、不校验画像是否存在（foundry/quality/profile.go:882-896 ListScores 无非存在性判断），故删除后仍可查历史。前端在删除时把画像对象（附 deleted_at）推入会话级 deletedProfiles，在画像列表下方渲染「已删除画像（本次会话保留 · N）」卡片，每行保留「历史」按钮可继续打开评分历史抽屉。后端没有枚举已删除画像的端点，因此该入口只存在于本次会话（刷新页面后消失），卡片内常驻诚实提示。

4.10 评分历史抽屉

右侧滑出抽屉（宽度 min(920px, 94vw)），含画像信息（scope 徽章 + 名称 + 阈值 + 调度任务名 quality:<id>）与「关闭」按钮。

评分记录表格：时间 / 总分（徽章）/ 完整度 / 唯一度 / 有效性 / 新鲜度 / 行数 / 备注 / 明细。备注列展示：已产生 issue（红标签，details.issue_created）、issue_skipped 说明（未接问题出口）、note 或 -；明细列「展开/收起」按钮切换因子级与列级明细。

因子明细表：因子 / 分值 / 方式（method-pushdown 下推蓝、method-sampled 抽样橙、method-na 灰色）/ 说明。列级明细表：列 / 因子 / 分值 / 方式 / 说明，列为 * 表示全表级。空明细显示「无因子明细」「无列级明细」。

5. 后端关联

5.1 API 客户端

client.js（规则/问题 Tab）：baseURL: /api/v1，超时 30 秒；请求拦截器附 Authorization: Bearer <aip_token>；响应拦截器对 401 清理 token 并跳转 /login。
qualityProfileApi.js（画像 Tab）：独立 axios 实例，baseURL: /api/v1，超时 120 秒（run 可能全表扫描）；拦截器与 client.js 同款（401 清理跳登录）。导出函数：
- listQualityProfiles(scopeType?, scopeId?) → GET /quality/profiles
- createQualityProfile(payload) → POST /quality/profiles
- getQualityProfile(id) → GET /quality/profiles/:id
- updateQualityProfile(id, payload) → PUT /quality/profiles/:id
- deleteQualityProfile(id) → DELETE /quality/profiles/:id
- runQualityProfile(id) → POST /quality/profiles/:id/run
- listQualityScores(id, limit=100) → GET /quality/profiles/:id/scores?limit=

5.2 端点表

方法	路径	请求体	说明
GET	`/quality/rules`	—（无分页参数，可选 `?scope_type=&scope_id=` 过滤）	规则列表（全量返回）
POST	`/quality/rules`	`{name, scope_type, scope_id, rule_type, rule_config, severity, enabled}`	创建规则，返回 `{id}`
PUT	`/quality/rules/:id`	`{enabled}`（仅此一字段，缺省 400 `enabled is required`）	启用/停用（不支持改配置）
DELETE	`/quality/rules/:id`	—	删除规则（历史问题保留）
GET	`/quality/issues`	—（无分页参数，可选 `?status=open\|acknowledged\|fixed`）	问题列表（全量返回）
POST	`/quality/issues/:id/acknowledge`	—	open → acknowledged
POST	`/quality/issues/:id/fix`	—	open/acknowledged → fixed
GET	`/quality/profiles`	—（无分页参数，可选 `?scope_type=&scope_id=`）	画像列表（全量返回）
POST	`/quality/profiles`	`{name, scope_type, scope_id, weights?, threshold?, schedule?, config?, enabled?}`	创建画像
GET	`/quality/profiles/:id`	—	详情（含解析后 weights/config 与 `job_name`）
PUT	`/quality/profiles/:id`	指针字段	更新（未提供保留原值）
DELETE	`/quality/profiles/:id`	—	删除画像（评分历史保留）
POST	`/quality/profiles/:id/run`	`{}`	立即运行，返回本次评分+明细
GET	`/quality/profiles/:id/scores`	—	评分历史（`?limit=`，created_at 倒序）

5.3 响应结构

统一成功包装 {code: 0, data: ...}；失败 {code, error}（HTTP 状态取自 ierr）。示例：

// GET /quality/rules
{ "code": 0, "data": [
  { "id": 1, "name": "orders_amount_not_null", "scope_type": "object",
    "scope_id": 1, "rule_type": "null",
    "rule_config": { "column": "amount" },
    "severity": "warning", "enabled": true,
    "created_at": "2026-08-29T10:00:00Z", "updated_at": "2026-08-29T10:00:00Z" }
]}

// GET /quality/issues
{ "code": 0, "data": [
  { "id": 3, "rule_id": 1, "affected_table": "ds_orders",
    "affected_rows": { "count": 12, "sample": [ { "id": 1, "amount": null } ] },
    "status": "open", "created_at": "2026-08-29T10:00:00Z", "updated_at": "2026-08-29T10:00:00Z" }
]}

// POST /quality/profiles/:id/run
{ "code": 0, "data": {
  "score": { "id": 7, "profile_id": 2, "total": 85.4, "completeness": 0.98,
    "uniqueness": 1.0, "validity": 0.95, "freshness": 0.6,
    "details": "{\"row_count\":12000,...}", "created_at": "..." },
  "details": { "row_count": 12000, "factors": [ {"factor":"completeness","value":0.98,"method":"pushdown","detail":"..."} ],
    "columns": [ {"column":"amount","factor":"validity","value":1,"method":"pushdown","detail":"..."} ] }
}}

5.4 关联模块表

后端包	职责
`foundry/pipeline`	`QualityService`：规则 CRUD、`CheckQuality` 检查执行、问题闭环（`ListIssues/AcknowledgeIssue/FixIssue/CreateIssue`）；`DataQualityRule/DataQualityIssue` 模型
`foundry/quality`	`ProfileService`：四因子画像评分、`RegisterSchedule` 调度注册、`IssueCreator` 接口（低于阈值产 issue）
`foundry/sync`	`datasetProfileBridge`：同步成功后自动触发画像运行
`foundry/server`	`pipeline_handlers.go` 挂 `/quality/rules\|issues` 路由；`quality/rest.go` 挂 `/quality/profiles` 路由；`profileIssueBridge` 适配问题写入

5.5 关键机制

问题状态机：open → acknowledged → fixed。确认仅 open 可执行；修复 open/acknowledged 均可。修复/确认后不自动产生新问题。

画像四因子 SQL 下推：

completeness：SUM(CASE WHEN col IS NULL THEN 1 ELSE 0 END) 单条聚合下推；
uniqueness：COUNT(DISTINCT pk)/COUNT(*) 下推，pk 取 config.pk_column，未配置按 1 记并标注 na；
validity：number/date 类型列匹配率；SQLite 方言 number 列走 typeof()；date 列与下推困难的列拉 ≤1000 行样本计算并标注 sampled（全量覆盖时 detail 注明无抽样）；
freshness：MAX(watermark_col) 下推 → 距今线性衰减（≤720h 记 1，≥720h 记 0）；未配置水位列按 1 记并标注 na。

诚实标注：任何降级/失败/na 均写入评分 details（note 与列级 method/detail），计算失败按 na（值 1）降级并记 Warn 日志，不阻断调度运行。

阈值 → 问题：总分低于 threshold 时经 profileIssueBridge（CreateProfileIssue）合成规则+检查结果写入 data_quality_issues；连续低于阈值自动去重（不重复造问题），恢复后再次跌破重新触发。

指针语义更新：PUT /quality/profiles/:id 的请求字段全为指针类型，未提供的字段保留原值（例如启停只传 {enabled}）。

6. 核心流程详解

6.1 主流程一：创建质量规则

进入「规则管理」Tab，点「+ 新建规则」展开表单；
填写名称、选择 scope_type、填 scope_id、选 rule_type、选 severity；
在 rule_config 区填检查列；format 类型补格式正则，referential 类型补引用表/列；
勾选「创建后即启用」（默认勾选）；
点「创建规则」→ 前端校验 → POST /quality/rules → 成功提示并刷新列表。

分支：rule_type 为 null/unique 时无额外配置项；为 referential 时前端强制校验 ref_table/ref_column 非空。

6.2 主流程二：处理质量问题

进入「质量问题」Tab（onMounted 已拉取全部问题）；
点「样本」展开违规样本，核对违规明细；
对 open 问题点「确认」→ confirm → POST /quality/issues/:id/acknowledge → 状态变 acknowledged；
点「修复」→ confirm → POST /quality/issues/:id/fix → 状态变 fixed；
可通过状态筛选只关注待处理（open）问题。

6.3 主流程三：创建并运行质量画像

进入「质量画像」Tab，点「+ 新建画像」展开表单；
填名称，选 dataset 作用域，下拉选数据集；
按需调整四因子权重（留空用默认）、阈值（默认 60）、pk_column、watermark_col、schedule cron；
点「创建」→ POST /quality/profiles → 列表出现新画像；
点「运行」→ POST /quality/profiles/:id/run → 顶部提示总分；
点「历史」→ 抽屉内「展开」查看四因子趋势与列级明细。

分支：配置了 schedule 后由统一调度器按 cron 定时运行；同步引擎（sync）运行成功也会自动触发画像（datasetProfileBridge）；画像总分低于阈值自动写入问题表，可在「质量问题」Tab 看到。

6.4 任务终态语义

本页无独立任务化机制（run 为同步等待式，超时放宽到 120 秒）；调度运行由统一调度器承载，任务名前缀 quality:<profileID>。run 返回的评分即终态，不轮询。

7. 权限与安全

认证：全部请求经 axios 拦截器附带 Authorization: Bearer <aip_token>；401 响应统一清理 aip_token/aip_username 并跳转 /login（登录页内不重复跳转）。
数据级安全：规则与画像的 scope_id 必须指向真实存在的数据集/对象，后端 checkScopeExists 校验；创建规则时对 scope_type/rule_type/severity 枚举做白名单校验（非法枚举直接拒绝）。
写操作防护：删除规则、删除画像、确认问题、修复问题均有 confirm 二次确认；提交/运行期间 busy 状态禁用按钮防重复提交。
列名白名单：画像 config.pk_column/watermark_col 需匹配 ^[a-z][a-z0-9_]*$，防 SQL 注入。

8. 常见问题与排错

8.1 创建规则提示「加载质量规则失败」或一直转圈

现象：进入页面后顶部红条提示加载失败，或规则列表停留在「加载中...」。
原因：GET /quality/rules 请求失败。常见为 Foundry 后端（18081）未启动、token 失效（401 会先跳登录）、或网络超时（client.js 30 秒）。
排查步骤：① 确认后端已启动且能 curl -H "Authorization: Bearer <aip_token>" http://localhost:18081/api/v1/quality/rules；② 打开浏览器 Network 面板查看请求状态码；③ 401 则重新登录；④ 后端返回 {error} 时按后端错误码定位（如 scope 不存在）。

8.2 创建 referential 规则提交失败

现象：填写了引用表/列后点「创建规则」，顶部提示「referential 类型规则需要填写引用表 ref_table 与引用列 ref_column」或后端报校验错误。
原因：前端 handleCreate 对 referential 类型强制校验；或后端 CreateRule 校验 rule_config.referential{ref_table, ref_column} 非空。表名/列名带空格也会 trim 后为空。
排查步骤：① 确认引用表/列确实填写且无空格；② 查看 Network 请求体 rule_config 是否含 referential 对象；③ 确认被引用表真实存在（后端不校验引用表存在性，但检查执行时会报数据源错误）。

8.3 画像「运行」后总分异常偏低

现象：运行完成后总分很低，历史抽屉里某个因子为 na 或 sampled。
原因：缺 pk_column 时 uniqueness 按 1 记（na）；缺 watermark_col 时 freshness 按 1 记（na）；数据量大时 validity 拉样计算（sampled）；权重未填时后端用默认值归一。
排查步骤：① 打开该画像「历史」→「展开」查看因子明细的 method 列（pushdown/sampled/na）；② 对 na 因子补配 pk_column/watermark_col 后重跑；③ 对 sampled 因子确认是否可接受近似值；④ 检查 details.note 是否记录了降级原因。

8.4 问题「确认」按钮置灰无法点击

现象：某条问题的「确认」按钮是禁用态。
原因：该问题状态不是 open（已是 acknowledged 或 fixed）。确认操作只在 open 状态可用（it.status !== 'open' 时 disabled）。
排查步骤：① 查看该行状态徽章颜色；② 若已是 acknowledged，想关闭请用「修复」；③ 若状态异常，检查是否有人/定时任务已处理过。

8.5 画像列表「最新总分」显示「未运行」

现象：列表最新总分列显示灰色「未运行」。
原因：该画像从未运行过，fetchProfiles 用 listQualityScores(p.id, 1) 拉最新一条，无记录则不计入 latestScores。
排查步骤：① 点击该行「运行」生成首条评分；② 运行后仍不显示则检查 Network 中 GET /quality/profiles/:id/scores?limit=1 是否报错（如数据库未建表）。

9. 已知缺陷与边界

项	说明
object scope 画像仅登记	画像 `scope_type=object` 本版仅登记不计算（运行时明确报错/不执行），后续批次接线
schedule 变更不实时增删调度条目	画像 schedule 只在服务启动时注册一次（`RegisterSchedule`），运行中修改 cron 需重启生效
规则作用域/类型不可改（设计取舍，非缺口）	`PUT /quality/rules/:id` 已支持 `name`/`rule_config`/`severity`/`enabled`（`foundry/server/pipeline_handlers.go:258-320`、`pipeline.QualityService.UpdateRule`）；`scope_type`/`scope_id`/`rule_type` 刻意不可变——变更等同重建规则并令历史问题归属失真，故前端以只读字段展示并在提示中说明需删除后重建
画像删除后历史可查（本次会话）	`DELETE /quality/profiles/:id` 保留 `fq_scores`；`GET /quality/profiles/:id/scores` 不校验画像存在（`foundry/quality/profile.go:882-896`），前端已补「已删除画像（本次会话）」入口继续查看历史。边界：后端无枚举已删除画像的端点，刷新页面后入口消失（属后端缺口）
调度器未注册时 run 不受影响	立即运行 `POST /quality/profiles/:id/run` 与调度器无关，可随时手动触发
列表无服务端分页	`GET /quality/rules`、`/quality/issues`、`/quality/profiles` 均无分页参数（`pipeline_handlers.go:226-241 / :300-308`、`quality/rest.go:48-58`），前端已补渲染层分页（每页 10 条）但仍一次全量拉取，数据量大时首屏请求体积不变；画像评分历史保持服务端 `limit`（默认 100，上限 500）。最新总分为当前页画像按 `limit=1` 拉取（避免全量 N+1）

后端文件

action/products/foundry/server/pipeline_handlers.go（/quality/rules、/quality/issues handler）
action/products/foundry/quality/rest.go（/quality/profiles handler 与路由注册）
action/products/foundry/quality/profile.go（四因子评分服务）
action/products/foundry/pipeline/quality.go、action/products/foundry/pipeline/models.go（QualityService 与模型）

项目文档

action/wiki/upgrade-v5/dev-story/stage-1.md（V5 Stage 1 数据域规格，B1-2 质量画像）
action/wiki/changelog/2026-08-29-2-v5-stage1.md（B1-2 交付说明与偏差遗留）
action/wiki/frontend-intro-v5/markdown/foundry/index.md（Foundry 页面清单）

相邻页面链接

上一页（侧边栏）数据血缘（Markdown 版 lineage.md）
下一页语义检索（Markdown 版 semantic-search.md）
相关页：数据集（画像作用范围）、数据同步（同步自动触发画像）、对象查询、SQL 工作台