dev-guide.md

开发指南

环境要求

建议使用：

• Windows 开发环境。
• Visual Studio 2022 或可构建 .NET Framework 4.8 项目的 Visual Studio。
• .NET Framework 4.8 Developer Pack。
• NuGet 包还原能力。
• SQL Server 或 SQL Server LocalDB。
• IIS Express。
• Node.js 与 npm，仅在需要维护前端资源构建时使用。
• VSCode 建议使用 Csharp_Webform Profile，并启用 C#、.NET Runtime 及本项目推荐扩展。

获取依赖

本项目使用经典 NuGet packages.config。推荐在 Visual Studio 中打开 src/master.sln 并启用 NuGet Restore。

VSCode / 命令行方式：

powershell -NoProfile -ExecutionPolicy Bypass -File dev\scripts\Restore-NuGetPackages.ps1

当前普通 PowerShell PATH 未发现 nuget.exe。脚本会优先使用 NuGet CLI；如果未安装但 src\packages 已存在，则跳过显式还原，以保持旧项目当前可构建状态。后续如果要重新完整还原，建议安装 NuGet CLI 或使用 Visual Studio 的 NuGet Restore。

构建

推荐方式：

1. 使用 Visual Studio 打开 src/master.sln。
2. 还原 NuGet 包。
3. 选择 Debug|Any CPU。
4. 构建解决方案。

VSCode / 命令行方式：

powershell -NoProfile -ExecutionPolicy Bypass -File dev\scripts\Build-Solution.ps1 -Configuration Debug -Platform "Any CPU"

脚本会通过 dev\scripts\Find-MsBuild.ps1 查找 Visual Studio / Build Tools 中的 MSBuild。当前已验证脚本可自动定位已安装的 MSBuild 并完成 Debug|Any CPU 构建；实际安装路径因本机 Visual Studio / Build Tools 配置而异。

VSCode 任务

.vscode/tasks.json 提供以下常用任务：

• nuget: restore packages：还原或检查 NuGet 包。
• build: solution Debug：构建 src/master.sln，并作为默认 build task。
• iisexpress: start Portal (40001)：以固定端口 40001 启动 src/Portal。
• iisexpress: stop Portal (40001)：仅停止匹配端口或站点路径的 IIS Express 进程。
• iisexpress: restart Portal (40001)：顺序执行停止和启动。
• gulp: assets:build：执行一次前端资源构建。
• gulp: startWatch / gulp: stopWatch：保留原 Gulp 监视任务的 VSCode 入口。
• portal: build assets and start：构建解决方案、构建前端资源并启动 IIS Express。
• portal: documentation baseline：输出已追踪源码的文档化 inventory JSON。
• portal: build JavaScript documentation pilot：独立生成并验证 HIA JSDoc pilot。
• portal: build .NET DotNetDoc pilot：独立生成并验证 HIA DotNetDoc pilot。
• portal: verify .NET XML documentation：构建 Debug 后检查既有 C# XML 文档输出。
• portal: verify frontend contracts：只读检查已追踪的 Web Forms 呈现、主题、模块 CSS 和 Gulp 契约。
• portal: verify public documentation：只读检查公开 Markdown 的入口、相对文件链接、隐私边界和生成目录边界。

这些任务只调用仓库内的辅助脚本和 npm scripts，不修改 .sln、.csproj、.csproj.user，因此不会覆盖 Visual Studio 的既有调试设置。

文档化基线

公开文档门禁只读取根 README、docs/ 与 JSDoc 工具 README；它不联网、不读取 WorkZone、不生成文档， 也不会访问配置或数据库：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalPublicDocumentation.ps1

门禁会验证公开入口、相对文件链接、文档索引、项目绝对路径/凭据形态和未确认生成目录的 Git 边界。它允许 $env:USERPROFILE、{ExternalCfgPath} 和 PowerShell 7 通用安装路径等可复现示例，但不会验证复杂 Markdown 锚点、 外部链接或网络可达性。

Get-PortalDocumentationBaseline.ps1 是 W-anp-P4.1 的只读基线工具。它只统计 Git 已追踪的 src/ 源码，输出 C#、Web Forms、前端与配置的文件数量、C# XML 文档 inventory，以及已知生成/未跟踪目录的边界状态；这些数值不是文档质量或覆盖率百分比。

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalDocumentationBaseline.ps1 -AsJson

如需把 baseline 写入证据目录，可使用：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalDocumentationBaseline.ps1 -OutputJson work-zone\dev\evidence\p13.3\documentation-baseline.json

脚本不会生成、发布、删除或修改文档。src/Documentation/、src/DoxyGen/、src/Portal/Documentation/、src/Portal/js/、src/Portal/css/ 和 temp/ 均不会被自动纳入输入；JSDoc 验证生成物写入被忽略的 temp/documentation/，公开发布策略见文档产物与工具链边界。

P13.3 起，文档化 readiness 和证据包可以用以下脚本执行：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalDocumentationReadiness.ps1
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalDocumentationEvidencePackage.ps1

readiness 会检查 Required、Recommended、Deferred 三档覆盖率口径、JSDoc pilot 隔离、.NET XML 延期边界、生成物未入库和 HIA 通知读取。证据包默认写入 WorkZone；它不修改源码注释、不提交生成物、不读取敏感配置，也不连接数据库。

JavaScript 文档化 Pilot

dev/documentation/jsdoc/ 是独立的 HIA JSDoc 工具项目。它锁定 @mandolin/jsdoc-plugin-hia-sys@0.1.0、@mandolin/jsdoc-theme-hia@0.1.0 和 jsdoc@4.0.5，不改动 src/Portal/package.json，因此不会干扰既有 Gulp 或 Visual Studio Task Runner。

当前 pilot 只读取两个已追踪且经审查的输入：src/Portal/gulpfile.js 与 src/Portal/Scripts/Security/PortalLoginPasswordEncryption.js。可在 VSCode 运行 portal: build JavaScript documentation pilot，或直接执行：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Build-PortalJsdocPilot.ps1

首次运行会在工具目录执行 npm ci；生成 HTML、HIA metadata 和 integration JSON 后验证双语内容、source-link 及本机路径泄漏。生成物只在 temp/documentation/jsdoc/，不得提交。

.NET XML 文档验证

Test-PortalXmlDocumentation.ps1 只检查既有 Debug|Any CPU 的四份 C# XML 文档输出：Portal、Portal.Components、Portal.Components.Data 与 Portal.Components.Data1。它不修改 .csproj、不生成 HIA artifact，也不设置 CS1591 数量门禁。

默认仅验证已有构建产物：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalXmlDocumentation.ps1

需要脚本先执行既有解决方案构建时，显式传入 -Build；VSCode 的 portal: verify .NET XML documentation 任务采用此模式：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalXmlDocumentation.ps1 -Build

验证器只检查 XML 结构、程序集名和至少一个成员条目。XML 继续属于本机构建产物；待 HIA C# producer 和 source-linkage 契约稳定后，再考虑独立接入。

.NET DotNetDoc Pilot

dev/documentation/dotnetdoc/ 是独立的 HIA DotNetDoc 工具项目。其清单声明 @hia-doc/dotnetdoc-runner@^0.1.8，受版本控制的锁文件解析为 0.1.8；并通过工具目录局部 .npmrc 使用 npm 官方 registry。这只影响 DotNetDoc pilot，不改变 Portal 前端依赖或 Gulp 工作流。

默认 pilot 读取四份 Debug XML 文档、代表性 Web Forms 标记注释、一个 Web Forms surface 和 solution/project discovery， 输出到被忽略的 temp/documentation/dotnetdoc/。执行：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Build-PortalDotNetDocPilot.ps1

已有 Debug XML 文档时可跳过构建：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Build-PortalDotNetDocPilot.ps1 -SkipXmlBuild

-ApiOnly 使用 dotnetdoc.api-only.config.json，用于排查 XML 文档管线；-SourceProbe 使用 dotnetdoc.source-probe.config.json，用于研究 C# source relation。当前 source probe 可能因逐文件 Roslyn 解析缺少完整项目上下文而产生 CS0246/CS0103 诊断，因此不作为默认门禁。

VSCode 调试

.vscode/launch.json 提供两个调试配置：

• Portal: Start IIS Express (40001), then attach：先启动 IIS Express，再通过进程选择器附加到 iisexpress.exe。
• Portal: Attach to IIS Express：用于 IIS Express 已经启动时手动附加。

使用流程：

1. 在 VSCode 中打开 Debug 面板。
2. 选择 Portal: Start IIS Express (40001), then attach。
3. 进程选择器出现后选择 iisexpress.exe。
4. 浏览器访问 http://localhost:40001/。
5. 结束调试后会执行 iisexpress: stop Portal (40001)。

当前已验证 IIS Express 可在 http://localhost:40001/ 返回 HTTP 200 OK。

Win7 VM 或其他局域网设备访问 IIS Express 时，不能使用默认 localhost 简易模式。先停止已有实例，再显式绑定主机 IP：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Stop-IISExpress.ps1 -Port 40001
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Start-IISExpress.ps1 -Port 40001 -HostName 192.168.199.21

脚本会同时保留 localhost 绑定并输出外部 URL。若 VM 仍无法访问，按脚本提示在主机管理员命令行中添加 URLACL 或防火墙规则。 默认不传 -HostName 时仍使用原有 localhost 启动方式，不影响 Visual Studio 和 VSCode 既有调试路径。

自动化测试、Smoke 与 SQL Server 兼容检查

P28 起新增正式 MSTest runner，默认只运行本机单元/契约测试，不连接数据库、不启动 IIS、不创建账号：

mise exec -- pwsh -NoLogo -NoProfile -File dev/scripts/Invoke-PortalTests.ps1

需要快速复用已构建的测试程序集时，可显式跳过还原和构建：

mise exec -- pwsh -NoLogo -NoProfile -File dev/scripts/Invoke-PortalTests.ps1 -NoRestore -NoBuild

P2.5 新增的 HTTP smoke 默认只检查已经运行的站点，不写入数据库，也不要求管理员凭据：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSmoke.ps1

需要脚本自行启动并关闭本地 IIS Express 时，显式传入：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSmoke.ps1 -StartIISExpress -StopWhenComplete

管理员页面回归需要显式提供用户名；密码会使用交互式 SecureString 输入，不应写入命令、脚本或配置文件：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSmoke.ps1 -AdminUser admin

非 LocalDB SQL Server 兼容检查必须使用独立测试库的外置连接串文件。默认只读 preflight；传入 -ApplyP2Migrations、-ApplyP3Migrations、-ApplyP5Migrations、-ApplyP6UserProfileMigration 或 -ApplyP6EmployeeOrganizationMigration 并确认后，才会执行对应的幂等增量迁移：

$testConfig = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\test\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSqlCompatibility.ps1 -ConnectionStringsConfigPath $testConfig -RequireP2Migrations -RequireP3Migrations -RequireP5Migrations -RequireP6UserProfileMigration -RequireP6EmployeeOrganizationMigration

P6 用户资料迁移会先检查旧用户名称和邮箱是否存在会破坏唯一性的历史数据；P6.3 员工组织迁移按 PortalBiz_OrganizationUnits.sql、PortalBiz_Employees.sql、PortalBiz_UserEmployeeBindings.sql 的顺序执行。两者都只应指向隔离开发库或测试库，不要指向生产配置。

SQL Server 版本矩阵预检用于 P11 之后的多版本补证。默认只做静态扫描，不连接数据库、不创建数据库、不执行 SQL：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSqlVersionMatrix.ps1

需要给某个隔离 SQL Server 测试实例补充版本、兼容级别和目标库元数据时，传入仓库外连接串文件。脚本只读取元数据，不输出服务器名、连接串或密码；SQL Server 2016/2017/2019 的通过结论仍必须由对应真实实例补证，不能用更新版本代替：

$testConfig = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\test\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSqlVersionMatrix.ps1 -ConnectionStringsConfigPath $testConfig

P11.2 起提供只读数据访问 inventory，用于扫描已追踪源码中的 SQL Server 专属依赖、需要 provider 方言处理的 SQL、可抽象入口和 provider proof 边界。它不连接数据库、不读取仓库外连接串，也不会扫描未跟踪生成目录：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalDataAccessInventory.ps1

需要保留 JSON 证据时显式指定输出路径：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalDataAccessInventory.ps1 -OutputJson work-zone\dev\evidence\p11.2\data-access-inventory.json

P11.3 起提供只读迁移 manifest 检查，用于盘点 src/Setup 脚本的执行顺序、迁移类型、幂等性、provider 标签、回滚模式和 legacy 风险：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalMigrationManifest.ps1

需要保留 JSON 证据时显式指定输出路径：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalMigrationManifest.ps1 -OutputJson work-zone\dev\evidence\p11.3\migration-manifest.json

既有测试库需要补齐 P5/P6 schema 时，必须显式使用外置 test 连接串和 Test-PortalSqlCompatibility.ps1 的 -Apply* 开关。该操作会写入目标测试库，只应指向隔离测试实例：

$testConfig = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\test\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSqlCompatibility.ps1 -ConnectionStringsConfigPath $testConfig -ApplyP5Migrations -ApplyP6UserProfileMigration -ApplyP6EmployeeOrganizationMigration -ApplyP6BusinessModuleMigration -RequireP2Migrations -RequireP3Migrations -RequireP5Migrations -RequireP6UserProfileMigration -RequireP6EmployeeOrganizationMigration -RequireP6BusinessModuleMigration

首次创建隔离的 SQL Server 2016+ 测试库时，可显式运行初始化脚本。它从外置连接串读取目标库名，要求目标库不存在，并在确认后导入历史基础数据、P2、P3 与 P5 迁移；不会输出或保存连接串：

$testConfig = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\test\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Initialize-PortalTestDatabase.ps1 -ConnectionStringsConfigPath $testConfig

可先增加 -WhatIf 检查目标库和执行意图。该脚本绝不覆盖既有数据库，任一步失败后也不会自动删库；只可用于隔离测试实例。发布前请使用 deployment-checklist.md。

数据提供程序 Proof

P3.3 提供一个不加入 src/master.sln 的 SQLite capability proof，用于验证新增 provider profile、ADO.NET factory、参数化读写、UTC、事务和唯一约束。它不切换门户主业务数据库，不需要修改外置 Portal 连接串，也不参与站点发布。

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalDataProvider.ps1 -Configuration Debug

脚本会单独还原 proof 项目的 packages.config、构建到 temp\provider-proof\bin\，并在 temp\provider-proof\data\ 下重新生成 SQLite 文件。-DatabasePath 只允许该临时数据目录内的路径；默认会删除上次 proof 文件后重建，传入 -KeepDatabase 才保留文件。

新增 provider 专用 DDL 放在 src\Setup\Providers\{ProviderId}\。当前只有 SQLite proof；未来 MySQL、PostgreSQL 等 provider 应各自增加目录、依赖/许可证审计、方言实现、迁移与回归，不应覆盖既有 SQL Server 脚本。

HIA 外围契约 Proof

P3.4 提供独立的 HIA 外围能力描述 proof。它仅验证门户拥有的 JSON envelope、版本、字段范围和隐私边界；不加载 HIA 外部程序集、不开放 HTTP/消息/文件 transport，也不影响门户正常启动与发布。

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalHiaBoundary.ps1 -Configuration Debug

Proof 项目位于 src\Portal.HiaBoundaryProof\，未加入 src\master.sln，输出仅写入被忽略的 temp\hia-boundary-proof\。当前草案允许模块、主题、设置 registry 元数据、健康状态和受限诊断引用；不会接受用户/角色/认证、设置实际值、日志详情、审计正文、路径、连接串或任何凭据。

Portal.Hia.InstanceId 是可选的部署级、非敏感稳定标识。默认留空，留空不会启用任何对外适配器。需要为未来受控协作准备时，可设置为 GUID 或小写字母、数字、.、_、- 组成的稳定标识；不得由机器名、数据库名、域名、用户名或其他个人/环境信息推导。后续若接入真实 HIA consumer 或 transport，应先更新 ADR、契约版本和独立运行回归。

P11.4 起可生成 HIA 外围集成边界 inventory。它只盘点当前契约、proof、draft fixtures、文档化通知读取机制和候选分层，不启用真实 HIA transport，也不会读取连接串、凭据或日志正文：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalHiaIntegrationInventory.ps1

需要保留 JSON 证据时显式指定输出路径：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Get-PortalHiaIntegrationInventory.ps1 -OutputJson work-zone\dev\evidence\p11.4\hia-integration-inventory.json

如 HIA-Documentation-Sys 不在默认同级目录，可通过 -DocumentationSysRoot 指定；脚本只记录通知标题、相对路径和是否提及当前项目，不复制通知正文。

P3 扩展性验收

Test-PortalExtensionSmoke.ps1 汇总 P3 的构建、前端资源、SQLite provider、HIA 契约、根站点和虚拟目录回归。默认不写数据库、不要求管理员凭据，也不会停止正在使用的 40001 站点；虚拟目录使用临时 IIS Express 端口并在结束后停止。

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalExtensionSmoke.ps1

SQL Server schema、管理员交互和缓存隔离是显式能力。连接串仅从仓库外文件读取，脚本不会输出其中的值：

$config = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\test\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalExtensionSmoke.ps1 -IncludeSqlCompatibility -ConnectionStringsConfigPath $config

主题与缓存 proof 会在指定的开发或测试库中短暂写入验证数据，并在 finally 中恢复原状态。主题 proof 验证数据库全局 ThemeProbe、Tab 覆盖优先级和非法主题回退；缓存 proof 会创建临时 ModuleProbe 定义、实例和包状态。两者必须显式开启，且不要指向生产配置：

$config = Join-Path $env:USERPROFILE 'Web\HIA-ASPNETPortal\dev\connectionStrings.config'
& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalExtensionSmoke.ps1 -IncludeThemeMutation -IncludeCacheMutation -ConnectionStringsConfigPath $config

管理员交互回归使用 SecureString 密码输入，不记录密码。它会验证已登录访问系统健康、日志、审计、主题设置和模块目录页面；主题/模块的实际业务操作仍应在隔离数据上按阶段验收清单执行：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalExtensionSmoke.ps1 -IncludeAdmin -AdminUser admin

数据库初始化

参考 src/ReadMe.txt，基础流程为：

1. 为隔离环境准备仓库外 connectionStrings.config，并确保目标数据库不存在。
2. 优先用 Initialize-PortalTestDatabase.ps1 显式执行基础初始化，再用 Test-PortalSqlCompatibility.ps1 的 -Apply* 开关补齐后续幂等迁移；历史 SQL 文件仍保留供 Visual Studio/SSMS 人工维护使用。
3. 如确需手工执行，请按 Portal_CreateDB.sql、Portal_LoadConfig.sql、Portal_LoadData.sql、PortalCfg_SystemSettings.sql、PortalCfg_UserRegistration.sql、PortalCfg_OperationAudits.sql、PortalCfg_TabThemeOverrides.sql、PortalCfg_ModulePackageStates.sql、Portal_UserCredentials.sql、PortalCfg_RolePermissions.sql、PortalBiz_UserProfiles.sql、PortalBiz_OrganizationUnits.sql、PortalBiz_Employees.sql、PortalBiz_UserEmployeeBindings.sql、PortalBiz_EmployeeProfileConfirmations.sql、PortalBiz_EmployeeProfileCorrectionRequests.sql、PortalBiz_WorkItems.sql、PortalBiz_WorkItemEvents.sql、PortalBiz_BusinessApplications.sql、PortalBiz_WorkflowEvents.sql 的顺序操作，并确认数据库上下文与连接串一致。
4. 复制 src/Portal/Config/Templates/connectionStrings.config 到外置配置目录，并修改其中的 Portal 连接串。
5. 构建并运行站点。

P19.5 业务申请样板页可以先生成可审阅 SQL，不直接修改数据库：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalP19BusinessApplicationScenarioSql.ps1

如需在已确认的开发/测试库中执行，应先补齐 P5/P12/P19 迁移，再显式传入外置连接串并使用 -Apply：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalSqlCompatibility.ps1 -ConnectionStringsConfigPath '<仓库外>\connectionStrings.config' -ApplyP5Migrations -ApplyP12WorkItemMigration -ApplyP19BusinessApplicationMigration -RequireP5Migrations -RequireP12WorkItemMigration -RequireP19BusinessApplicationMigration -Confirm:$false

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalP19BusinessApplicationScenarioSql.ps1 -ConnectionStringsConfigPath '<仓库外>\connectionStrings.config' -Apply -Confirm:$false

需要补齐 P19.5 的认证浏览器回归时，可使用受限的 fixture helper。它只接受直接父目录名为 test 的外置 connectionStrings.config，且只创建由 FixtureId 确定的一个普通参与者和一个仅具 Admins 实体角色的管理员。Create 的密码必须由短生命周期进程以 SecureString 交互输入；不得把密码写入命令行、脚本、日志或配置。完成提交和管理员审核后，必须先 Inspect 再 Remove，并确认最终计数均为零：

$testConfig = '<仓库外>\test\connectionStrings.config'
$participantPassword = Read-Host -AsSecureString 'P19 fixture participant password'
$administratorPassword = Read-Host -AsSecureString 'P19 fixture administrator password'

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalP19BrowserSmokeFixture.ps1 `
  -ConnectionStringsConfigPath $testConfig `
  -Action Create `
  -FixtureId 'p19-local-001' `
  -ParticipantPassword $participantPassword `
  -AdministratorPassword $administratorPassword `
  -Confirm:$false

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalP19BrowserSmokeFixture.ps1 `
  -ConnectionStringsConfigPath $testConfig `
  -Action Inspect `
  -FixtureId 'p19-local-001'

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\New-PortalP19BrowserSmokeFixture.ps1 `
  -ConnectionStringsConfigPath $testConfig `
  -Action Remove `
  -FixtureId 'p19-local-001' `
  -Confirm:$false

该 helper 只输出计数级事实，不输出连接串、密码、盐、哈希或申请正文。Remove 在单一事务中按依赖顺序删除该 fixture 的 P19 记录、实体角色关系和两个账号；它不能按任意用户名、角色或前缀删除数据。它只证明 test 数据库与隔离浏览器闭环，不能替代真实 IIS/HTTPS、生产或企业扫描证明。

部署或共享环境中不得使用默认账号和弱密码。 默认凭据和旧口令治理见 docs/deployment-default-credentials.md；发布前应运行 dev/scripts/Test-PortalDefaultCredentialRisk.ps1。

前端资源

Web Forms Master、主题、模块 CSS、Gulp 输入输出、Visual Studio/VSCode 边界和未跟踪资产策略见 frontend-asset-guide.md。

src/Portal/gulpfile.js 保留 Visual Studio Task Runner 原绑定：

/// <binding ProjectOpened='startWatch' />

同时新增独立的 assets:build 任务，用于 VSCode 和 AI 自动化调用，不改变 startWatch / stopWatch 原语义。

常用命令：

cd src\Portal
npm run assets:build
npm run assets:watch
npm run assets:stop-watch

当前已验证 npm run assets:build 可以成功执行。执行时出现 Browserslist 数据过期提示，属于前端依赖维护提醒，不影响本次构建结果。

需要只读复核正式前端输入而不运行 Node/Gulp 时，执行：

& 'C:\Program Files\PowerShell\7\pwsh.exe' -NoLogo -NoProfile -File dev\scripts\Test-PortalFrontendContracts.ps1

配置注意事项

• src/Portal/Config 下有 *.template.* 文件，也有实际环境文件。
• 修改真实配置前先确认是否应改模板。
• 连接串不再写入 UnityCfg*.xml，而是从外置 {ExternalCfgPath}\{env}\connectionStrings.config 读取。
• ExternalCfgPath 留空时默认使用 {当前进程用户目录}\Web\HIA-ASPNETPortal\。
• 本地 dev 默认文件路径为 {当前进程用户目录}\Web\HIA-ASPNETPortal\dev\connectionStrings.config。
• connectionStrings.config 中当前使用的逻辑名为 Portal，启动后会映射为 Unity 的 connectionString 命名实例；providerName 为必填项，当前门户主业务数据库固定为 System.Data.SqlClient。
• 环境变量 HIA_ASPNETPORTAL_CONNSTR_PORTAL 可覆盖具体连接串值；外置文件本身仍必须存在。
• 不要提交真实生产连接字符串、账号、密码、Token 或证书。
• .gitignore 已包含部分配置、数据库和构建产物忽略规则，但历史文件仍需人工核查。

文件编码

• 后续新增或修改的文本文件统一使用 UTF-8 无 BOM。
• 仓库根目录 .editorconfig 已设置 charset = utf-8。
• src/Portal/.editorconfig 因包含 root = true，也已单独设置 charset = utf-8。
• VSCode 工作区已设置 "files.encoding": "utf8"，对应 UTF-8 无签名。