Files

92 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 质量中心:质量数据分析平台
用于质量数据查询、分析、规则管理与数据治理的本地优先应用。
## 架构
- 前端:React、TypeScript、Vite。
- 后端:Java、Spring Boot、MySQL。
- 公网入口:[https://quality.lyunlab.me](https://quality.lyunlab.me)。服务器提供前端静态页面和 HTTPS;API 经 SSH 加密回连到本机后端。
- MySQL、模型凭据、业务来源文件和运行数据保存在本机,不包含在本仓库中。本机需保持开机联网且项目服务运行,其他电脑才能使用完整功能。
## 开发入口
- [项目规则](AGENTS.md):本项目的业务约束、代码入口和验证选择,配合全局使用习惯执行。
- [当前进度](docs/当前进度.md):最近核实的代码、验证、部署状态及待办;跨会话继续时先核对实际状态。
- [智能分析接入](docs/DeepSeekHarness正式接入.md):当前 DSH、模型原文、报告、图表与平台边界。
- `开发交付说明.md` 及带日期的实施、验收文档保留为历史证据;其中早期数据范围、运行方式和功能状态不能直接视作当前状态。本地交付说明及被 Git 排除的验收资料不随源码同步。
## 本机运行
Linux 容器部署、自动重启、空间回收、备份保留及容量告警见 [Docker 部署说明](deploy/docker/README.md)。这些配置随源码进入 Gitea;构建镜像使用手动入口,不要求配置 Gitea 自动构建。Mac 测试服务的开机启动与守护见 [本机服务说明](deploy/macos/README.md)。
本机启动脚本面向 macOS 15 及以上的 Apple Silicon。先准备 Python 3.11 及以上、Node.js/pnpm 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。首次运行需要安装项目运行依赖并构建:
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 启动。详见[正式接入说明](docs/DeepSeekHarness正式接入.md)。
## 不良率趋势钻取
总体、产业部、产品、黑片和亮片查询默认进入年度。切换年份保留当前产品层级;明确指定期间的链接继续使用该期间。
在不良率趋势图中点击有细项的分类曲线,可查看该分类下各细项的废率趋势;分类总废率以虚线保留。点击“全部分类”返回。切换年份或产品保留分类,切换黑片/亮片退出分类。不良率图不再通过点击曲线或横轴筛选月份,合格率与产量图保留原交互。
底部表格同步展开当前分类的细项,重量/废率切换与 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。