# 质量数据分析平台项目规则 沿用全局沟通与执行习惯;本文件只补充项目约束和入口。 ## 项目约束 - 正式指标由后端指标服务和当前有效规则计算。月、季、年先汇总分量再计算,不平均月率;缺失阶段、零分母、去本部报废等语义以正式服务为准,不在页面、导出或 AI 中另造算法。 - 当前智能分析固定使用 DSH,保留模型原始正文;普通提问直接回答,报告仅在明确要求时生成。图表失败静默省略并保留后台诊断。遗留 `nao_*.py` 与根目录兼容入口不表示可以恢复双引擎或增加模型审阅。 - 权限、数据范围及来源绑定由服务端执行;查询、缓存、图表、报告和下载均保留当前授权检查,历史快照不能绕过实时权限。 - 测试使用隔离数据库与合成数据,复用 `OwnedTestDatabase` 或 `scripts/managed_test_resources.py` 登记和清理自有资源。私有原表回归另选入口,不把业务主库当测试库。 - `.runtime/`、`runtimedata/`、`output/` 含私有数据、验收产物及可能正在使用的运行包,不按目录名称判断可删除。密钥、登录资料、业务原件和备份不得进入 Git 或普通交接记录。 - 主工作目录可能在旧分支上积累已由其他工作目录交付的改动。继续开发前核对分支、最新主线及本次差异;不将全部未提交内容一并提交,不切换或重置当前目录来“清理”。 ## 按需阅读与代码入口 | 任务 | 入口 | | --- | --- | | 接续当前工作 | `docs/当前进度.md`;先核实记录与实际状态 | | 启动、构建和验证 | `README.md`;共享服务维护另读 `deploy/macos/README.md` | | 查询、指标和导出 | `web/src/QueryPage.tsx`、`web/src/metricWorkbook.ts`;后端 `metrics/`、`analytics/`,均位于 `backend/src/main/java/cn/yunsheng/quality/` | | 智能分析 | `docs/DeepSeekHarness正式接入.md`;前端 `web/src/agent/`、后端 `analysis/`、`scripts/build_dsh_application.py` 及 `runtime/dsh/application/` | | 数据接入和规则 | 后端 `source/`、`ingestion/`、`workflow/`、`masterdata/`、`dictionary/`;本地授权资产存在时,原表核对另读 `verification/rules.md`,其中样本范围属于历史基线,该文件不随源码同步 | | 界面与交互 | `DESIGN.md` 及现有组件、主题;无需为纯业务改动读取全部设计说明 | | 备份、回收和迁移 | `deploy/macos/README.md`、`deploy/docker/README.md`;版本变化触发的维护保护须经兼容性核实后再解除 | ## 验证入口 - 前端按影响选择 `node --test web/verification/<相关测试>.test.mjs`;查询导出对应 `metric_workbook.test.mjs`。必要时再执行 `pnpm --dir web build`。 - 完整本机构建入口为 `python3 scripts/project.py build`,运行后端非私有原表测试并构建前端;原表全量回归显式加 `--private-acceptance`,资产缺失不能当作通过。 - Python 用项目对应环境按需运行 `PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=scripts python3 -m unittest discover -s verification -p '<相关测试文件>'`;DSH 环境检查入口为 `python3 scripts/setup_dsh_runtime.py --check`,不调用模型。 - 不因文档变更触发构建、服务重启、模型请求、数据库迁移或维护清理。开发测试通过、仓库同步和线上生效分别记录。