Files
quality_analyse/README.md
T

10 KiB
Raw Blame History

质量中心:质量数据分析平台

用于质量数据查询、分析、规则管理与数据治理的本地优先应用。

架构

  • 前端:React、TypeScript、Vite。
  • 后端:Java、Spring Boot、MySQL。
  • 公网入口:https://quality.lyunlab.me。服务器提供前端静态页面和 HTTPS;API 经 SSH 加密回连到本机后端。
  • MySQL、模型凭据、业务来源文件和运行数据保存在本机,不包含在本仓库中。本机需保持开机联网且项目服务运行,其他电脑才能使用完整功能。

开发入口

  • 项目规则:本项目的业务约束、代码入口和验证选择,配合全局使用习惯执行。
  • 当前进度:最近核实的代码、验证、部署状态及待办;跨会话继续时先核对实际状态。
  • 智能分析接入:当前 DSH、模型原文、报告、图表与平台边界。
  • 开发交付说明.md 及带日期的实施、验收文档保留为历史证据;其中早期数据范围、运行方式和功能状态不能直接视作当前状态。本地交付说明及被 Git 排除的验收资料不随源码同步。

本机运行

Linux 容器部署、自动重启、空间回收、备份保留及容量告警见 Docker 部署说明。这些配置随源码进入 Gitea;构建镜像使用手动入口,不要求配置 Gitea 自动构建。Mac 测试服务的开机启动与守护见 本机服务说明。

本机启动脚本面向 macOS 15 及以上的 Apple Silicon。先准备 Python 3.11 及以上、Node.js/pnpm 和 uv。首次运行需要安装项目运行依赖并构建:

python3 scripts/setup_runtime.py
pnpm --dir web install --frozen-lockfile
python3 scripts/project.py build

上述安装、构建及下列启动命令用于独立开发环境。当前共享测试服务已由守护程序运行;日常检查使用 python3 deploy/macos/service.py status。维护共享服务前先阅读本机服务说明,不在端口已被占用时重复启动,旧停止命令也不能替代守护管理。

独立开发环境随后运行:

python3 scripts/project.py start

打开 http://127.0.0.1:5280/。停止服务:

python3 scripts/project.py stop

登录信息由本机启动流程生成并保存在 runtimedata/;凭据文件和运行配置被 Git 忽略。

数据与本地配置

本仓库只包含应用源码和必要的构建文件。业务工作簿、数据库、模型 API 密钥、登录凭据、验收报告和运行时文件均不上传。首次克隆后没有预置业务数据,需要在本机导入授权的数据来源。原工作簿迁移验收基线也保留在本机;缺少该私有基线时,对应的原始来源对账功能会明确报告未配置。

在系统设置中配置本机模型。设置保存在私有的 .runtime/nao-model-config.json;旧版根目录 apikey.txt 只作为未配置时的兼容入口,严禁提交任一凭据文件。

项目保留固定的 Python 3.11.15 和旧 nao 依赖安装入口;requirements-nao.lock 中的 nao-core 0.3.26 属于兼容源码环境,不代表当前正式分析引擎。总安装器仍会准备这些依赖及 DSH;--without-ai 仅准备 Java/数据库环境,--without-dsh 不是可用的正式智能分析部署方式。已有环境不得为更新说明而覆盖或中断运行中的会话。

质量智能分析固定使用 DeepSeek Harness(DSH)。API 配置管理模型、端点和思考设置,不提供 NAO/DSH 切换。Java 管理身份、授权、正式指标及历史,DSH 执行工具循环;模型正文原样保存,普通问题直接回答,只有明确要求时生成报告。图表失败时静默省略,后台保留诊断。

DSH CLI 固定为 0.2.2-rc.1,依赖与官方 Python SDK 校验记录在 runtime/dsh/,要求 Node 24.9+。可运行 python3 scripts/setup_dsh_runtime.py --node /path/to/node24 安装项目内运行环境,--check 检查真实启动且不调用模型。scripts/build_dsh_application.py 构建独立应用,正式运行包使用其中的 scripts/quality_analysis_runtime.py;根目录同名源码仍有双引擎兼容逻辑,不能据此推断线上支持切换。当前系统隔离与正式服务在 macOS 验证;Linux/Windows 等效隔离未验收时明确拒绝 DSH 启动。详见正式接入说明。

不良率趋势钻取

总体、产业部、产品、黑片和亮片查询默认进入年度。切换年份保留当前产品层级;明确指定期间的链接继续使用该期间。

在不良率趋势图中点击有细项的分类曲线,可查看该分类下各细项的废率趋势;分类总废率以虚线保留。点击“全部分类”返回。切换年份或产品保留分类,切换黑片/亮片退出分类。不良率图不再通过点击曲线或横轴筛选月份,合格率与产量图保留原交互。

底部表格同步展开当前分类的细项,重量/废率切换与 Excel 导出跟随当前显示;产品和期间行维度保持不变。细项使用正式阶段同期总重量作分母,月、季、年均先汇总分量再计算;没有来源或分母时显示缺失,真实零显示零。细项与正式分类总量不一致时提示覆盖不足,不补造分类。

筛选索引与查询加载

来源字段支持等于、包含、排除和空值筛选;“包含”输入关键词后按回车生效,多个关键词任一命中,区分大小写,%、_ 按普通文字匹配,每个关键词最多256字符、最多50个。各类筛选共用按构建冻结的值字典及记录索引;汇总、趋势、来源明细和导出沿用当前授权与正式指标计算。源字段值保留空值、大小写及前导零语义,旧配置筛选的字符串 null 约定不变。下拉框使用只读候选模式,只取一页及是否还有;需要精确总数的原接口继续保留。

启动时在单线程后台补建当前完整正式版本的索引,导入及归类在事务提交后进入同一去重队列。完整构建标记提交后才启用;未完成、失败或未补建的历史构建沿用原始查询,不阻止启动和正式数据发布。索引增加持久存储及后台构建成本,规模取决于非空字段数和不同值数量;高基数宽表应先测容量。保留清理随无引用构建回收索引;升级后原维护兼容保护继续生效。

年度全产品查询先显示正式指标和同范围趋势,再读取产品表格;月/季及产品搜索并行读取摘要和产品页,单产品及总体/产业部等范围复用完整结果。不同范围的趋势独立加载,底部柏拉图接近视口且主查询就绪后读取。刷新和筛选变化会使旧结果失去当前资格;表格失败时,已就绪的指标与趋势仍可使用。

普通查询在数据版本已解析后开始,来源字段条件仍等待对应版本的字段目录;产品文本搜索等待必要产品选项,不因无关元数据失败而禁用。产品汇总、黑片和亮片的宽产品表由数据库分页,默认每页15行,可选择10/15/20/50/100行;换年、筛选和修改每页数量时回到第一页。指标与趋势继续统计完整范围,细分废率随当前页读取。Excel 重新读取完整授权范围并全量导出,产品钻取后的期间表保持原有展示。

旧版本时间迁移

连接与 MySQL 会话现在统一使用 UTC,界面仍按本地时区显示。V25 只校正旧代码按 UTC 墙上时间写入的截止/有效期、报告调度及报告租约列(前者由 Java 写入,租约使用 SQL UTC_TIMESTAMP),不改 SQL CURRENT_TIMESTAMP 自动生成的创建时间,也不修改业务日期或指标。若旧库存在此类值,迁移要求先备份并核实旧会话相对 UTC 的偏移,然后设置 MYSQL_LEGACY_TIMESTAMP_OFFSET_SECONDS(旧会话 UTC 为 0,旧会话中国标准时间为 28800)。本机启动可在私有 local-config 中记录 legacyTimestampOffsetSeconds;不能仅凭电脑当前时区猜测。全新空库不需要该参数;迁移标记和历史值修改在同一事务提交,防止提交确认丢失后重复平移。还原旧备份时应重新核实其原运行时区。

测试与原始工作簿验收

默认构建运行不依赖私有工作簿的测试。原始规则对账另外使用本机的独立基线、对应关系和哈希匹配来源文件;这些私有资产不随 Git 克隆分发,也不应为了构建而上传。

准备好授权的 verification/baseline.json、verification/observed_mappings.json 和基线中列出的原工作簿后,执行完整原表回归:

python3 scripts/project.py build --private-acceptance

如资产保存在独立目录,可用 QUALITY_REGRESSION_ROOT 指定该目录;其下保留 verification/ 及基线中的相对来源路径。显式选择原表验收时,资产缺失会使验收失败,不会静默跳过。正常界面中的原表回归在未配置资产时返回“未配置”,不能据此启用规则。默认测试与私有原表验收的结果应分别记录。

AI 与图表的合成数据测试源码位于 verification/test_*.py,使用 PYTHONPATH=scripts python3 -m unittest discover -s verification -p 'test_*.py' 执行。该目录的私有基线、捕获结果和工作簿仍不提交。界面状态测试使用 node --test web/verification/*.test.mjs verification/*.test.mjs。

备份与异目录恢复

python3 scripts/backup.py create-and-verify 将数据库、来源归档、应用源码及私有配置保存在本机私有备份目录,并在新建的隔离数据库内核验恢复、来源路径和必要构建输入。分项结果保存在清单中;文件校验通过不等于应用启动已验证。

需要迁移副本时,使用 python3 scripts/backup.py restore --help 查看空目标目录及新隔离库参数。恢复只允许新的 quality_restore_* 库,不能覆盖在线库;来源归档的绝对引用会在新库中重新绑定。备份不内嵌 JDK、MySQL、Node/pnpm 或 AI 二进制环境,应先按本机运行步骤准备依赖。备份包含模型和数据库私有配置,不应上传、公开分享或提交到 Git。