编辑 | blame | 历史 | 原始文档

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

sbcLabSystem 是一个基于 ASP.NET MVC 4 + Entity Framework 6 + SQL Server 的实验室质控（QC）管理系统，部署目标为 IIS + .NET Framework v4.8。业务围绕**实验室质控（QC）发放 / 登记 / 答卷 / 审批 / 统计 / 邮件通知**展开，主要用户为检验实验室管理员。

没有 README，没有 docs 目录，没有已有的 CLAUDE.md —— 本文件是首份给 Claude 的项目说明。

解决方案结构

一个 sbcLabSystem.sln 包含多个工程，分层依赖如下（顶层 Web 项目 → 下层类库）：

sbcLabSystem           (ASP.NET MVC Web 项目, 入口 Global.asax.cs)
  ├─ sbcLabSystem.Framework   (Autofac DI 注册: DependencyRegistrar.cs)
  ├─ sbcLabSystem.Service     (业务服务层: Account/QC/Task/Common)
  ├─ sbcLabSystem.Data        (EF6 DbContext + Domain 实体 + Migrations)
  ├─ sbcLabSystem.Import      (WinForms 导入/迁移工具, 基于老 edmx 模型)
  └─ EmailService             (Windows Service, 邮件发送)
外部引用:
  ..\..\Common\PalGain\PalGain.Core                  (自研基础框架: IoC, 任务, 缓存, 仓储)
  ..\..\Common\WCF_BatchService\trunk\...Framework.Utility

依赖关键点：
- PalGain.Core 位于解决方案外的 ..\..\Common\PalGain\ —— 克隆仓库时需要同时拉取该路径，否则无法编译。WCF_BatchService 同理。
- sbcLabSystem.Framework.DependencyRegistrar 通过 PalGainEngine.Instance.Register() 在 Application_Start 自动注册到 Autofac 容器，业务服务通过构造器注入使用。

常用命令

本项目是 .NET Framework（**不是 .NET Core/.NET 5+**），因此使用 MSBuild，而不是 dotnet build。

还原与构建（Windows / Visual Studio 2019 环境）

# 还原 NuGet 包（.NET Framework 项目必须用 nuget.exe，不能用 dotnet restore）
nuget restore sbcLabSystem.sln

# 用 MSBuild 构建整个解决方案（Debug）
msbuild sbcLabSystem.sln /p:Configuration=Debug /p:Platform="Any CPU"

# 只构建 Web 项目
msbuild sbcLabSystem\sbcLabSystem.csproj /p:Configuration=Debug

首选在 Visual Studio 2019+ 中直接打开 sbcLabSystem.sln 进行 F5 调试 —— 项目依赖老版 packages（EF 6.1.3、Autofac 3.5.2、MVC 4.0）并且引用了位于解决方案外的相对路径工程，命令行构建对环境要求严格。

运行

  • Web 项目通过 IIS Express（VS F5）或部署到 IIS 运行；入口是 sbcLabSystem/Global.asax.cs。
  • sbcLabSystem.Import 是 WinForms 工具（Program.cs + Form1.cs），用于老系统数据迁移，**与线上 Web 运行无关**。

数据库迁移（EF6 Code First）

数据库通过 EF6 Code First Migrations 管理。启动时 ContextBuilder.InitDataBase() 注册 MigrateDatabaseToLatestVersion<FreseniusDBContext, Configuration> —— 应用启动会自动把数据库升级到最新 migration。

新增迁移（Package Manager Console，默认项目选 sbcLabSystem.Data）：

Add-Migration <MigrationName> -ProjectName sbcLabSystem.Data -StartUpProjectName sbcLabSystem
Update-Database -ProjectName sbcLabSystem.Data -StartUpProjectName sbcLabSystem

连接字符串在 sbcLabSystem/Web.config 的 <connectionStrings> 节，名称 FreseniusDBContext。**切勿把开发库密码提交到仓库以外的公开位置。**

测试

仓库中**没有单测工程**。新增变更时若需要验证，只能通过跑起 Web 项目手测 / SQL 验证，或在 sbcLabSystem.Import 里写一次性脚本。提交完成声明前务必说明「无自动化测试覆盖」，避免假阳性成功。

架构关键事实

阅读多文件才能看出的"大图"，先在这里固化：

1. 请求管线与 DI 装配

  1. MvcApplication.Application_Start（sbcLabSystem/Global.asax.cs）顺序做四件事：
  • PalGainEngine.Instance.Register() —— 扫描所有 IDependencyRegistrar 实现，用 Autofac 构建容器，并把 AutofacDependencyResolver 装到 MVC。
  • ContextBuilder.InitDataBase() —— 启用 EF 自动迁移。
  • MVC 标配三件套 AreaRegistration / FilterConfig / RouteConfig / BundleConfig。
  • TaskManager.Instance.Initialize(); Start(); —— 启动 PalGain 的后台任务调度，sbcLabSystem.Service/Task/ 下的计划任务（如 SendEmailTaskService、KeepAliveTask）在这里跑起来。
  1. sbcLabSystem.Framework/DependencyRegistrar.cs 是唯一的服务注册点：
  • IDbContext → FreseniusDBContext（InstancePerLifetimeScope，即每请求一个 DbContext）。
  • IRespository<> → EfRepository<>（泛型仓储，来自 PalGain.Core）。
  • 业务服务按需注册：AccountService、QCService、ScheduleTaskService 等。**新增 Service 时必须在此处注册**，否则 Controller 构造注入会抛 DependencyResolutionException。

2. 数据层（sbcLabSystem.Data）

  • DBContext/FreseniusDBContext.cs 是**当前系统唯一在用的 DbContext**。里面用 Fluent API 定义了 QC 相关的三组外键关系（QCDistribution ↔ QCDistributionRegisterInfo ↔ LabInfo，以及 QCDistribution ↔ StandAnswer 的 1:1 外键映射为 QCDistInfoId）。
  • Domain/ 下按业务域分子目录：Account（UserInfo/RoleInfo/ResourceInfo/UserRequestInfo）、Backstage（QC 发放/登记、审批、邮件 SMTP、标准答案、结果占比等）、Config（LocationInfo）。所有实体继承自 PalGain.Core.BaseEntity。
  • Migrations/ 下的迁移是**线上真实历史**（最早 2016-12，长期演进）。**不要 rebase/squash 已应用的 migration**；只能追加 Add-Migration。
  • sbcLabSystem.Import 工程里同时存在**另一套 edmx 模型**（sbcLabSystem.edmx、hds123001_db.edmx）和大量 POCO —— 这是给老数据导入工具用的 DB-First 产物，**与 Web 项目运行时的 Code First 模型是两条平行的独立链路**。修改 Web 业务时不要去改 sbcLabSystem.Import 下的实体。

3. 业务服务层（sbcLabSystem.Service）

  • 按域拆子目录：Account/AccountService.cs、QC/QCService.cs（1100+ 行，核心质控发放逻辑）、QC/AnswerService.cs、Task/SendEmailTaskService.cs 等。
  • ExcelUtil.cs + sbcLabSystem/Excel/*.xlsx 模板配合 —— 多处 Controller 通过模板 Excel 生成下发/回收文档，修改模板时需同步确认 ExcelUtil 的列映射。
  • 邮件发送有两条路径：**Web 进程内**通过 SendEmailTaskService（PalGain 任务）周期执行；**独立** EmailService 工程是一个可部署的 Windows Service，用途是离线批量发邮件 —— 改邮件逻辑前先确认要改的是哪一条。

4. Web 层（sbcLabSystem）

  • Controllers：AccountController（登录/权限）、BackstageController（**全系统后台主入口，1600+ 行，质控发放/登记/审批/答卷/统计/邮件/打印都塞在这一个 Controller 里**）、HomeController、PdfViewController、UserUIController。
  • BaseController 做了两件事：把默认 Json() 结果改成 JsonNetResult（即 Json.NET 序列化，替代 MS 内置的 JavaScriptSerializer，以便处理循环引用与日期格式），以及用 iTextSharp 把 HTML 渲染成 PDF（RenderToPDF 被 PdfViewController 和 BackstageController 打印相关动作复用）。**新增控制器若需要返回 JSON 或者 HTML→PDF 能力，务必继承 BaseController 而非 Controller。**
  • Models/Backstage/ 全是 ViewModel（不是实体），命名后缀为 ViewModel 或 PageViewModel。Controller 动作的入参/出参应走 ViewModel，不要直接暴露 EF 实体。
  • Reports/ 里有 .rdlc 报表文件（EmsInfo.rdlc、EnvelopeInfo.rdlc 等），通过 PrintLabInfo / PrintEnvelope 等动作渲染，参数由 DataSet1.xsd 定义。改报表列时三件套（.rdlc / .xsd / 传入的 ViewModel）必须同步。

5. 配置与打包

  • Setup1 工程是 Visual Studio 老式 Installer 项目，用于生成 Web 安装包，日常开发基本不用动。
  • UpgradeLog*.htm 是旧版 VS 升级项目留下的报告，可忽略。
  • .gitignore 已屏蔽 bin/、obj/、packages/，但仓库里依旧保留了 packages/ 目录 —— 那是老项目直接把 NuGet 包签入的历史遗留，不要当作缺失。

QCDistributionRegisterInfo 保存契约

本仓库**没有** (QCDistributionId, LabId, ProjectId) 的数据库唯一索引（产品决定不动 DDL），防重复登记完全靠业务层。约定如下：

  • 唯一的保存入口：所有保存 QCDistributionRegisterInfo 的路径都必须经过 QCService.SaveQcDistributionRegister。新写任何涉及登记表写入的代码，**不要**直接 _qcDistributionRegisters.Insert、不要绕开此方法。
  • Id==0 的语义：该方法把 Id==0 视为"新增"请求，进入前会按 (QCDistributionId, LabId, ProjectId) 做查重：
  • 查不到 → 正常 Insert。
  • 查到 → 打一条 LogHelper.Error 日志（强制告警），按 MergeRegisterInfo 规则**合并**到既有行后 UPDATE；同时把入参 qcDistributionRegister.Id 回写为 existing.Id，便于调用方后续引用。
  • MergeRegisterInfo 的合并规则（刻意不对称）：
  • string 字段：!string.IsNullOrEmpty(source) 才覆盖（保留既有内容；空串也不覆盖，因为 QCDistributionRegisterInfoViewModel.ToEntity 里的 entity.EMSNo = "" ?? ... 这类 force-set 代码会把 null 变成 "", 若按 != null 判断就会清空既有 EMSNo）。
  • DateTime? 字段：HasValue 才覆盖。
  • DateTime ModifyTime：非默认值才覆盖（调用方都用 DateTime.Now，天然非默认）。
  • bool 字段：**只能 false → true，不能 true → false**。这是为了防止一次 Id==0 的脏 Save 把既有的 IsCharged=1 意外清零。
  • QCDistributionId / LabId / ProjectId：业务唯一键，不动。
  • 要把 bool 清回 false、或清空 string/Date 字段，必须走 Id>0 路径：先用 GetQcDistributionRegister(id) 查出 tracked entity，直接改字段再 SaveQcDistributionRegister。用 Id=0 + IsCharged=false 这种方式期望"反收费"会被静默忽略。
  • 生产日志里出现 SaveQcDistributionRegister 命中已有行（Error 级别） = 某个上层调用方漏做了查重或前端提交了脏 Id，**必须排查根因**。这条日志**刻意用 LogHelper.Error** 而不是 Info —— 因为本仓库的 LogHelper 没有 Warn 方法，而 Info 级别不会触发告警系统；用 Error 保证运维能第一时间收到通知。
  • SaveLabList 路径（QCDistributionInfoViewModel.ToEntity）：作为第一道防线，保留了自己的 (QCDist, LabId, ProjectId) 查重分支 —— 与 SaveQcDistributionRegister 里的收口形成双保险。修改这两处任一处时都要同步检查另一处。注意第一道防线命中后**只同步 IsCharged 和 ModifyTime**（基于 SaveLabList 的业务语义），第二道防线命中后走 MergeRegisterInfo 全字段合并（通用兜底）；两者行为刻意不对称。
  • SaveLabList 的 byId / byLabProject 字典是循环前的快照：QCDistributionInfoViewModel.ToEntity 在循环开始前一次性 WHERE QCDistributionId=? 预加载全部登记行进内存，构建两个字典供循环查找。这意味着**同一次 SaveLabList 请求内，前端 LabList 里如果有两条完全一致的 (LabId, ProjectId) 条目**，第一道防线**看不到第一次 Insert 刚产生的那一行**（字典没更新），第二次循环会继续走 Insert 分支 —— 最终落到 SaveQcDistributionRegister 的**第二道防线兜底**，触发 LogHelper.Error 并合并到已有行。这是**刻意的分层设计**：第一道防线负责 99% 的已入库重复，第二道防线负责同批提交的 race。不要试图"为了一致性"把第一道防线改成在循环内动态刷新字典 —— 那反而会放大并发窗口。
  • byLabProject 的 GroupBy.First() 用 OrderByDescending(p.Id) 保证确定性：如果数据库里历史上有未清理的重复（不应该发生，但作防御），这个顺序保证永远命中 Id 最大（最新插入）的那一条。修改这个 LINQ 表达式时必须保留 OrderByDescending，否则行为变得不确定。
  • QCDistributionRegisterInfoViewModel.ToEntityByLabCode 的 ProjectId 过滤是**条件的**：只有 regInfoivewModel.ProjectId > 0 才加入 WHERE 子句，否则退化为只按 (QCDistributionId, LabId) 匹配。原因：前端 Views/Backstage/QCDistributionLabs.cshtml 的 openFeeWindow / openEMSWindow 把 CurrentQCDistRegisterInfo 重置为不含 ProjectId 字段的 JSON 字面量，序列化后服务端 regInfoivewModel.ProjectId == 0，无条件加过滤会让 ConfigrmFee / ConfigrmEMS / switchNextOne 全部静默失效。**未来若前端补上 ProjectId 选择控件**，服务端会自动切换到精准匹配，不需要改服务端代码。多项目共存时当前会匹配第一条（与修复前行为一致）。
  • BackstageController.ImportLabs：是唯一绕过 SaveQcDistributionRegister 的写入路径（直接操作 QCDistribution.QCDistributionRegisters 导航集合）。它自己在源读取后用 GroupBy(LabId, ProjectId).Select(g => g.First()) 去重；**修改 ImportLabs 时必须保留这段 GroupBy**，否则脏数据会跨分发传染。
  • 残余风险（已知，不修复）：两个管理员并发编辑同一分发时，两个独立 DbContext 的查重都可能返回空，仍有产生重复的理论窗口。本仓库不通过 DB 约束兜底，缓解办法是前端按钮防抖 + 监控 SaveQcDistributionRegister 命中已有行 的 Error 日志。如果日后发现并发窗口被真实触发，加唯一索引是根治方案（见"一致性"章节末尾）。

修改时的红线（针对本仓库的具体风险）

  • BackstageController 是超级 Controller：1600+ 行、几十个动作、大量 QC 业务耦合在一起。做变更时务必在动作内部就近改，**不要顺手重构或拆分文件** —— 这不是本次任务范围，且缺少测试覆盖，重构风险极高。
  • Excel 导出的 headers[] 和 cellKes[] 是手动对齐的平行数组：BackstageController 里每个导出 action（OutputUnderTakenLabs / LabExcelDate / LabExcel / Quality_Excel / ToExcel / ...）都用两个字符串数组靠**下标顺序对齐** —— headers[i] 是 Excel 第 i 列的中文标签，cellKes[i] 是对应的属性名（反射读 DataTable 列）。数组长度必须严格一致，语义顺序必须一一对应，**没有任何编译期/运行期检查**。历史上已经出过两次相同模式的 bug：(1) 15e82c0 追加"是否收费"时只加到末尾忘了检查前面已有一份，导致重复列（a3f4e4f 已修）；(2) LabExcelDate/LabExcel 长期把 Province 字段放在标签为"城市"的列下，admin 以为 Province 没保存（d5a91a2 已修）。**改这类导出的铁律**：每次修改都必须把 headers 和 cellKes 两个数组并排看一遍，逐下标核对中文标签和字段名是否语义匹配；新增列时两个数组都要加；删除列时两个数组都要删。如果下次排查的 bug 形态是"导出看不到数据"或"导出数据不对劲"，**先去检查这俩数组的对齐而不是写路径**。
  • DI 注册点单一：所有新增 Service 类都要到 sbcLabSystem.Framework/DependencyRegistrar.cs 去手动注册；没有约定式自动装配。
  • DbContext 生命周期：IDbContext 是 InstancePerLifetimeScope，即每次 HTTP 请求共享一个 FreseniusDBContext。**不要在 Service 内部 new FreseniusDBContext()**，会绕过事务 / 变更跟踪。
  • EF 迁移自动升级：启动即跑 MigrateDatabaseToLatestVersion。本地改 migration 后第一次运行 Web 就会对你连的数据库执行 DDL —— 在连生产/共享库时要特别小心，**改 migration 前先确认 Web.config 里的连接串指向的是哪个环境**。
  • 隐式契约变更：修改 ViewModel / Service 公共方法的返回结构、Map key 格式、枚举含义等，必须 grep 所有调用方与对应 .cshtml 视图（视图里常用 @Model.XXX 直接绑定），见全局 CLAUDE.md「隐式契约变更必须追踪所有调用方」。
  • Web.config 连接字符串包含明文口令：现有代码已经把数据库口令以明文方式写在 Web.config 中。修改时**不要进一步扩大暴露面**（例如写进日志、复制到示例文件、贴进评审意见或 commit message）。若用户明确要求整改加密，再独立开任务处理。

语言与沟通约定

代码注释与 UI 文案使用中文；对话回复使用中文（见全局设置）。方法名、类名、枚举值等标识符保持英文原样。