Files
quality_analyse/docs/智能分析通用源字段查询协议_20261027.md
lyun ff7bbe3e46 同步:完善质量分析工作台并更新主题字体
同步已上线的智能分析执行协议、来源查询、图表报告与管理页面配套代码。
补齐数据库迁移、运行依赖和回归测试,保留原有指标计算口径。
统一午夜黑及其他主题的控件细节、中文和业务数字字体。
排除本地业务数据、凭据、预览、发布与验收产物。

验证:生产构建通过,320项前端回归通过;本轮仅同步Git,不再次部署。
2026-10-30 22:40:58 +08:00

66 lines
5.7 KiB
Markdown

# 智能分析:通用源字段查询协议
日期:2026-10-27。本地实施文档;不表示已经上线或整份重构计划已经验收。
## 查询责任
模型把自然语言转换成完整任务提案。后端核对当前权限、固定发布版本、源列、阶段和操作,确认不可变任务修订后执行查询。指标仍由现有 MetricsService 和发布规则计算;源表比率列不能直接求平均代替正式指标。成员清单由平台分页、去重和渲染。
## 字段目录
`GET /api/analysis/source/catalog` 返回当前发布的授权 `sourceFields`。字段具有稳定 key、可读名称、黑片/亮片物理列映射、适用阶段、类型和操作目录。字段来自当前发布成员及当前可见组织的数据;同名列共用 key,异名只按已有明确映射关联,不按相似名称猜测等价关系。原表列类型为 `source_value`;已有产品等标准维度为 `dimension`,可用于成员投影。
列目录随发布和权限读取,不以加工单位、委托单号等固定两列为边界。某一阶段没有该列时明确拒绝或澄清;不能悄悄忽略条件。字段目录不等于原始行读取授权。
## 条件结构
权威任务只保存一份 `task.filters.columnFilters`。每条条件包含:
```json
{
"field": "目录中的稳定字段 key",
"stages": ["black", "bright"],
"operator": "in",
"values": ["完整文本值"]
}
```
- 规则之间为 AND;同一条规则的多个值为 OR。不同阶段分别应用各自适用的规则。
- `in`、`not_in` 接受 1–50 个完整文本值,每值不超过 256 字符;大小写、前导零均保留。空值使用独立操作。
- `is_empty`、`not_empty` 不接受 values。`not_in` 保留空值及缺失值,除非另有明确空值条件。
- `null` 或空规则列表表达清除;确认后规范为删除该条件。替换给出完整规则列表,不能从旧聊天或本地文件恢复已清除条件。
- 黑片、亮片和两阶段均可指定;两阶段各自筛选后沿用现有业务汇总口径,不进行原始行跨表关联。跨阶段关联需要另行确认可信关联键。
- 当前源列操作限于目录明确列出的四种。范围比较、模糊业务筛选或新增计算若未接入,要说明限制,不能转成近似查询。
`POST /api/analysis/source/values` 在同期间、同范围查询授权候选值,搜索发生在去重、计数和分页之前。搜索没有候选时,可再读取同期间、同阶段、同授权范围的首批实际候选供用户选择;不会放宽业务条件或自动替换输入值。每份候选回执均核对范围,仅用于对象确认,不能作为正式分析结果证据。
## 成员清单
任务类型为 `members`,声明 `memberFields`、阶段、期间及完整 filters。`POST /api/analysis/source/members` 仅投影所选列,按投影元组去重;相同元组保留来源阶段。最多选择 5 个字段,每页最多 200 项;读取上限 20 页(4000 项)。后端从已记录的真实分页响应重建完整结构化快照,页面可按 20/50/100 项翻页,HTML 与单张长图包含全部已载入项。快照上限 8 MiB,超过读取或快照容量时明确 PARTIAL 和缺口。禁止接收 SQL、任意物理列名或跨版本数据。
每页返回精确总数、偏移、条数、hasMore 和真实执行 proof。pageComplete 表示本页成功;complete 仅表示本次从首页即可取得全量。任务完成依据是全部页连续取回、总数稳定、证据属于当前修订与执行。后端独立核对分页链,模型不能把首页称为全部。
每次打开、翻页和导出都复核原轮次当前权限及快照内容,失败即隐藏表格并阻止下载。读取、快照容量及缺口分别说明;未全部读取或不能载入全部已读项时标记 PARTIAL。空值不是有效单号,也不补成零。
## 权威状态与旧路径退出
| 旧来源 | 新协议会话中的责任 |
| --- | --- |
| 可变 session.context / 提交页面残留筛选 | 仅保留固定初始框架;正式范围来自后台已确认任务 |
| 本地 last-agent-task 文件 | 不读取、不回填 |
| 历史问题、旧答复、native chat | 不作为正式条件或事实注入当前执行 |
| frozenContext | 不单独决定重试筛选;重试使用同一后台修订 |
| 工具自行追加/删除参数 | 固定查询范围逐项核对,不一致即拒绝 |
| 原执行的进程、凭据和证据目录 | 按独立 attempt 隔离;旧执行不能清理新执行文件 |
| 迟到进度、答复及终态 | 按当前 attempt / revision / execution 原子校验,取消后不得覆盖 |
| 历史结果、图表、导出 | 展示/下载时复核当前权限和固定发布;列条件随结果保存 |
旧会话保留原读取兼容路径。新协议默认关闭,仅在明确启用的本地验证服务中新建会话生效;不把当前代码、旧会话或本地验收称为线上版本。
## 正式报废率与连续月份
按用户确认,阶段报废率使用报废总量 ÷ 正式总重;黑片分母选择现有修正总重,利用料、本部报废、过账外废的计入方式沿用当前业务逻辑。不是 1−合格率,也不以源表百分比列平均代替正式值。零分母/缺失返回缺失,真实零保留;超过 100% 不截断。未定义跨阶段综合报废率。
期间支持单年、单月、季度或连续月份 `{year, monthStart, monthEnd}`。连续月份两个边界必须同时给出,满足 1 ≤ 起始月 ≤ 结束月 ≤ 12,且不能同时指定 month/quarter。任务、正式查询、源字段候选、证据和图表都保留同一范围;不把末月代替整个区间。两个独立期间比较分别绑定两份精确查询证明。