# 质量中心:质量数据分析平台 用于质量数据查询、分析、规则管理与数据治理的本地优先应用。 ## 架构 - 前端: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)。 ## 旧版本时间迁移 连接与 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。