PayrollManagementSystem/scripts/windows/README.md

# Windows T+ supervisor 托管

本包说明旧 Windows 任务计划与新 supervisor 服务的迁移边界。新部署使用 `scripts/windows/PayrollTPlusSupervisor.xml.example` 由管理员选择并核验 WinSW 版本后注册 supervisor；旧的后端、worker 和每分钟维护任务不得与新 supervisor 并行运行。自动周采集与业务自动接入分别由应用配置启用。采集本身只写来源快照；启用业务自动接入后，成功采集会排队建档或追加单据，但不会自动核算或生成工资。业务自动接入默认关闭。

## 配置及账号准备

使用目标服务器已有受限服务账号，配置“作为批处理作业登录”、MySQL／Redis 连接和项目外的 T+ 只读连接文件。生产不能使用 SYSTEM。管理员须预先准备运行目录及文件权限：

- 部署目录、Python 环境和全部程序文件，只允许管理员及指定服务账号维护，不允许普通 Users、Everyone、Authenticated Users 写入。
- 只读连接文件和 `backend/.env`，仅限管理员、SYSTEM 与服务账号读取；连接文件不放进仓库。
- 运行目录供服务账号写入日志、安装清单和停止标记，拒绝其他普通用户写入。上层目录也不能给普通用户删除／替换这些目录的权限。
- 脚本安装前和 Start 前检查关键入口、文件所有者和上层目录 ACL；不会自动改变 ACL。管理员仍需确保部署树全部内容和 Python 依赖都受相同保护。
- 安装清单保存服务账号 SID 和登录方式，Check／Start／Stop 均核验实际任务账号及 Limited 权限，发现漂移则拒绝操作。

应用需先完成经授权的迁移；部署时以本次交付代码的 `alembic heads` 和目标库的 `alembic current` 核对版本，不能沿用历史 head。客户现场外部 T+ 连接、证书和 Linux 部署方式见 [客户现场部署与 T+ 连接说明](../../docs/客户现场部署与T+连接说明.md)。

`backend/.env` 中的非敏感开关：

```dotenv
T_PLUS_AUTOMATION_ENABLED=false
T_PLUS_SCHEDULE_WEEKDAY=0
T_PLUS_SCHEDULE_TIME=02:00
```

`T_PLUS_AUTOMATION_ENABLED` 只是未保存页面设置时的初始值。T+ 同步页保存开关后写入 `tplus_automation_configs`，维护程序以该源级设置为准；关闭页面开关会阻止后续自动排队，不影响当前任务和手动同步。

weekday 的 0～6 分别为周一至周日，时间固定按 `Asia/Shanghai` 解释。上线前保持自动化开关为 false。修改后重启托管进程，使后端与检查命令使用同一配置。

## 新部署：WinSW supervisor

新安装不注册旧的三个任务。管理员应选择并核验适用于目标 Windows Server 的 WinSW 版本，将包装器与同名 XML 放到受保护目录，按现场路径修改 [PayrollTPlusSupervisor.xml.example](PayrollTPlusSupervisor.xml.example) 中的程序、工作目录和日志目录，再注册 `PayrollTPlusSupervisor` 服务。服务账号、ACL、证书和未登录状态下的配置读取必须在目标机验证；supervisor 只在 API、MySQL、Redis 和 T+ 只读连接健康时领取任务。

```powershell
# 仅示意：WinSW 版本、路径和服务账号由目标环境管理员核验
winsw.exe install PayrollTPlusSupervisor.xml
winsw.exe start PayrollTPlusSupervisor
winsw.exe status PayrollTPlusSupervisor
```

停止时先在页面停止读取服务，等待当前安全步骤结束，再由管理员停止 Windows Service。不要同时启用旧 `PayrollDev-worker`、旧维护任务和新 supervisor；旧任务只做识别、停用和回退记录。

## 旧任务计划迁移检查（不用于新安装）

以下脚本仅用于识别和迁移既有任务计划，不是新部署入口。在 Windows PowerShell 5 中执行，使用实际部署路径。以下为示例路径，不含真实凭据。

```powershell
$project = 'D:\Payroll App'
$python = 'D:\Payroll App\backend\.venv\Scripts\python.exe'
$runtime = 'D:\Payroll Runtime'
$reader = 'D:\Payroll Secrets\reader.local.json'

# 只读预演：输出路径、动作、触发和恢复策略，不注册任务
& "$project\scripts\windows\Install-PayrollTasks.ps1" `
  -ProjectRoot $project -PythonPath $python -RuntimeDirectory $runtime -ConnectionFile $reader

# 检查脚本语法、任务策略、引号、ACL规则及账号核验；不注册任务
& "$project\scripts\windows\Test-PayrollTaskPlan.ps1" `
  -ProjectRoot $project -PythonPath $python -RuntimeDirectory $runtime -ConnectionFile $reader
```

客户环境安装需另行确认。确认后管理员才执行 `Install-PayrollTasks.ps1` 的同组参数，并增加 `-ServiceAccount '域或主机\已有服务账号' -Apply`。凭据通过交互框输入，不写入命令行、清单或日志。目录须提前准备且 ACL 合格，否则拒绝注册；已有同名任务／安装清单不会覆盖。安装过程部分失败时，已创建的任务仍保持禁用，按提示核对专用任务目录后处理。

测试模式只允许 `\PayrollManagementSystem-Test-xxxxxxxx\`（8 位十六进制）的独立目录及当前用户 Interactive／Limited 身份，同样要求显式 `-Apply` 和合格 ACL。不要用测试模式替代客户服务账号验收。

## 检查、启动、停用

```powershell
# 检查状态、最近退出码、下次执行及任务身份／动作／恢复策略
& "$project\scripts\windows\Manage-PayrollTasks.ps1" -Action Check -RuntimeDirectory $runtime

# 预演启动或停用；增加 -Apply 才改变任务状态
& "$project\scripts\windows\Manage-PayrollTasks.ps1" -Action Start -RuntimeDirectory $runtime
& "$project\scripts\windows\Manage-PayrollTasks.ps1" -Action Stop -RuntimeDirectory $runtime
```

以下 `Start`／`Stop` 和 `tplus-maintain` 说明仅适用于旧任务计划迁移检查，不是新 supervisor 的启动入口。新部署请按上方 WinSW supervisor 说明操作，不要执行这些旧任务的 `-Apply` 启动流程。

旧任务迁移时，`Start` 的 `-Apply` 只允许在回退窗口按原安装清单恢复；`Stop` 的 `-Apply` 先写停止标记并禁用旧任务。默认等待 30 秒，长查询未结束则返回 2，稍后 Check。仅在核实中断影响后，才使用 `-Force -Apply` 强制停止明确的旧项目任务；重启后遗留 RUNNING 批次标记中断，原数据及失败批次保留，由制作人核对后重试。旧任务不得与 `PayrollTPlusSupervisor` 并行。

旧任务使用 IgnoreNew，异常退出间隔 1 分钟重启，最多 3 次；启动器保留子进程退出码。后端、旧 worker 和旧维护命令的触发方式仅供迁移核对，不代表新部署架构。启动器子进程隐藏运行，后端绑定 `127.0.0.1`，对外访问应沿用现有网关。

## 调度和异常处理

旧版 `tplus-maintain --once` 只用于迁移期间核对最近到期的一周，同周期幂等；新 supervisor 内部负责周期排队和 worker 执行。停机后补一次，不逐周补积压。手动任务／正式导入工作区正在运行时延后排队。人工重试结果接入该周期，不会在人工恢复成功后再次重读原失败批次。

仅定时采集且错误均为明确断连或超时，才在终止后 5 分钟、15 分钟重试，最多两次。中途断连保留已暂存页并标记失败，重新全量读取由哈希去重。行级错误／部分失败、配置错误、字段错误、进程中断和正式导入不自动重试。原批次、重试关系与错误记录一直保留。

T+ 同步页显示自动化开关、心跳、最近成功和下次重试，以及失败／部分失败、排队超过 15 分钟、超过 8 天无成功、心跳中断提示。独立心跳每 30 秒写入，2 分钟无更新提示离线。日志固定保留当前与上一次两份（`runtime\logs\<角色>.out.log`、`<角色>.err.log` 及对应 `.prev.log`），不输出驱动连接文本。外部邮件及企业消息未启用。

## 验证范围

已验证 Windows PowerShell 5 的计划参数、单实例／重启设置、含空格路径、隐藏子进程、停止标记和退出码传递；测试未注册计划任务或连接业务数据库。应用侧已完成隔离库周期竞争、人工／自动重试竞争、上限及独立长查询心跳验证。

客户服务器实际注册、服务账号权限、开机触发、每分钟三次恢复和停止后不再启动，仍需在专用目标环境演练并留存 Check 输出。SQL Server 2008 R2 实机、备份全量／增量恢复链及生产启用分别验收，不由本机测试替代。