packServer/desktop/Services/DeviceService.cs
liufumingren f8aa4c4899 feat(工作台): 成员扫码登入、面单摄像头与虚拟通道
- 工作台成员扫码登入:workstation_login_records 记录谁在什么时候登入/下线了哪台工作台,
  超时(团购 1h / 散单 30min)由 schedule/workstation_idle_offline 自动下线;
  运单查询的 packers 取当时的登入成员
- 面单摄像头识别:workstation_cameras.is_label_camera + service/label_scan 下发本机该跑的识别配置,
  设备端(桌面端 LabelScan 工作线程)按配置做面单识别并上报
- 虚拟通道 CAM-<工作台id>:工作台没接扫码枪时,面单摄像头那一路顶替扫码枪上报,records 规则按 ws_type 区分
- 桌面端:新增 LabelScanMonitor/LabelScanWorker/ScanDeviceKind 与面单预览页,扫描通道支持改名,静默窗口 5s

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-29 17:19:24 +08:00

615 lines
25 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using YuncangTrace.LocalService.Services.Scan;
namespace YuncangTrace.LocalService.Services;
/// <summary>
/// 桌面端「设备服务」:把本机当成一台扫码中控(scanner),向服务器上报扫码记录。
///
/// - **默认关闭**:只有主体管理员在菜单「服务 → 开启设备服务」里手动开启;
/// - 开启时调 `POST /api/web/devices/activate`,服务端保证「一个主体只有一台设备在线」,
/// 同主体其他设备会被踢下线(旧令牌立即 401);
/// - 开启后拿到**长期设备 JWT**,上报走 `POST /api/scan/{channels,records}`;
/// - 关闭时调 `POST /api/web/devices/:id/logout` 让令牌立即作废。
/// </summary>
public sealed class DeviceService
{
/// <summary>本机上报用的通道 id / 名称(一台电脑就是一个通道)</summary>
public const string LocalChannelId = "DESKTOP";
public const string LocalChannelName = "本机中控";
private readonly ApiClient _api;
private readonly AppSettings _settings;
private readonly Session _session;
// 扫码记录上报队列:条码先进本地库,后台循环批量推送,**服务器确认后才标记已上传**
private readonly SemaphoreSlim _uploadSignal = new(0, 1);
private CancellationTokenSource? _uploadCts;
private Task? _uploadTask;
private int _uploadRetryMs = 1000;
// 主体不可用(过期 / 停用)或设备令牌失效时暂停上报:
// 暂停期间只发心跳探测(心跳不受期限拦截),续费后自动恢复并补传积压。
private const int PauseNone = 0;
private const int PauseSubject = 1;
private const int PauseUnauthorized = 2;
private static readonly TimeSpan PauseProbeInterval = TimeSpan.FromSeconds(60);
// 静默窗口只有 5 秒,所以有积压时上报循环每秒醒一次(本地列表扫描,开销可忽略);
// 没积压时 30 秒保活一次,别空转。
private static readonly TimeSpan UploadBusyInterval = TimeSpan.FromSeconds(1);
private static readonly TimeSpan UploadIdleInterval = TimeSpan.FromSeconds(30);
private readonly object _pauseGate = new();
private int _pauseState = PauseNone;
private string _pauseMessage = string.Empty;
private int _probeFailures;
private DateTime _lastProbeAt = DateTime.MinValue;
/// <summary>暂停上报期间探测「是否已续期」时触发(ScanService 用来补一次通道对账)</summary>
public event Action? SubjectResumed;
// 面单一直放在扫码器上时会持续「更新最近扫描时间」(每 1~2 秒一次)——
// 这种事件不能每条都写日志,否则一天几万行;同一个 通道+条码 5 分钟记一次。
private static readonly ConcurrentDictionary<string, DateTime> TouchedLogAt = new();
/// <summary>散单通道「同一张面单还在扫」的判定窗口:这之内再扫到同一个码只算一次</summary>
private static readonly TimeSpan FirstSeenGap = TimeSpan.FromSeconds(5);
// 散单通道的在场记录:key = 通道|条码 → (首次扫到, 最近扫到)
private readonly Dictionary<string, (DateTime FirstSeenAt, DateTime LastHitAt)> _firstSeen =
new(StringComparer.OrdinalIgnoreCase);
private readonly object _firstSeenGate = new();
private static bool ShouldLogTouched(string channel, string code)
{
var key = $"{channel}|{code}";
var now = DateTime.Now;
if (TouchedLogAt.TryGetValue(key, out var last) && now - last < TimeSpan.FromMinutes(5)) return false;
TouchedLogAt[key] = now;
return true;
}
public DeviceService(ApiClient api, AppSettings settings, Session session)
{
_api = api;
_settings = settings;
_session = session;
}
/// <summary>上报状态(给界面看的一句话;空串 = 一切正常)</summary>
public string UploadStatus { get; private set; } = string.Empty;
/// <summary>是否已暂停上报(主体过期/停用,或设备令牌失效)</summary>
public bool UploadPaused
{
get { lock (_pauseGate) return _pauseState != PauseNone; }
}
/// <summary>
/// 心跳/上报拿到的视图:同步主体状态。
/// - 过期 / 停用 → 暂停上报(不消费队列、不标记已上传);
/// - 恢复可用 → 立刻补传积压(服务端幂等,整批重发安全)。
/// </summary>
public void ApplySubjectState(DeviceSubjectState? subject)
{
if (subject is null) return;
if (subject.Disabled)
{
Pause(PauseSubject, $"主体「{subject.Name}」已停用");
return;
}
if (subject.Expired)
{
var deadline = subject.ExpireAt is null ? string.Empty : $"({subject.ExpireAt:yyyy-MM-dd HH:mm})";
Pause(PauseSubject, $"主体「{subject.Name}」使用期限已到{deadline}");
return;
}
Resume("主体已续期/恢复,开始补传积压的扫码记录");
}
/// <summary>是否已开启(本地标记 + 有令牌)</summary>
public bool Enabled => _settings.DeviceServiceEnabled && !string.IsNullOrWhiteSpace(_settings.DeviceToken);
/// <summary>本机 SN(默认机器名,最多 64 字符)</summary>
public string Sn
{
get
{
if (!string.IsNullOrWhiteSpace(_settings.DeviceSn)) return _settings.DeviceSn;
var name = Environment.MachineName;
return string.IsNullOrWhiteSpace(name) ? "PC-DESKTOP" : name.ToUpperInvariant();
}
set
{
var text = (value ?? string.Empty).Trim();
_settings.DeviceSn = text.Length > 64 ? text[..64] : text;
}
}
/// <summary>当前主体 id(没有主体时 0)</summary>
public int SubjectId => _settings.SubjectId;
/// <summary>当前主体下**除本机以外**的已绑定设备(开启前提示"会被踢掉")</summary>
public async Task<IReadOnlyList<ApiDevice>> OtherDevicesAsync(CancellationToken ct = default)
{
if (SubjectId <= 0) return Array.Empty<ApiDevice>();
var devices = await _api.DevicesAsync(_session.Token, SubjectId, ct).ConfigureAwait(false);
return devices.Where(item => !string.Equals(item.Sn, Sn, StringComparison.OrdinalIgnoreCase)).ToList();
}
/// <summary>
/// 开启设备服务:注册本机 → 保存令牌 → 上报通道。
/// (踢掉其他设备的确认由界面负责,这里只管干活)
/// </summary>
/// <exception cref="ApiException">不是管理员 / 网络失败 / 主体到期等,message 可直接显示</exception>
public async Task<DeviceActivation> EnableAsync(CancellationToken ct = default)
{
if (SubjectId <= 0) throw new ApiException("还没有选择主体,请先在「服务 → 切换主体」里选一个");
var result = await _api.ActivateDeviceAsync(_session.Token, SubjectId, Sn, $"{Environment.MachineName}(本机)", ct)
.ConfigureAwait(false);
_settings.DeviceServiceEnabled = true;
_settings.DeviceId = result.Id;
_settings.DeviceSn = result.Sn;
_settings.DeviceToken = result.Token;
_settings.DeviceRefreshToken = result.RefreshToken;
_settings.DeviceTokenExpiresAt = result.ExpiresIn ?? string.Empty;
_settings.Save();
AppLog.Write($"[device] 设备服务已开启:{result.Sn}(id={result.Id},踢下线 {result.Kicked.Count} 台)");
// 重新开启 = 重新鉴权:清掉暂停状态并马上补传积压
Resume("设备服务已重新开启,恢复上报");
// 拉起扫码记录上报循环(断网期间的积压会一次性补上去)
EnsureUploadLoop();
TriggerUpload();
// 通道不在这里上报:真实通道由 `ScanService` 同步(加了几个扫码通道就报几个)。
// 以前这里会补一个 `DESKTOP`「本机中控」占位通道,结果工作台绑定页能看到一个
// 永远没数据的假通道;查询也不是扫码,不需要这个通道来"记账"。
AppLog.Write("[device] 通道由扫码服务同步(不再上报本机占位通道)");
return result;
}
/// <summary>上报一批通道(扫码服务的每条通道都同步给服务器,供工作台绑定)</summary>
public async Task ReportChannelsAsync(IEnumerable<(string ChannelId, string ChannelName)> channels,
bool replace = false, CancellationToken ct = default)
{
if (!Enabled) return;
var list = channels
.Where(item => !string.IsNullOrWhiteSpace(item.ChannelId))
.Select(item => (item.ChannelId, string.IsNullOrWhiteSpace(item.ChannelName) ? item.ChannelId : item.ChannelName))
.ToList();
// 全量对账时允许空列表(表示通道已全部删除)
if (list.Count == 0 && !replace) return;
await _api.ReportChannelsAsync(_settings.DeviceToken, list, replace, ct).ConfigureAwait(false);
}
/// <summary>关闭设备服务:让令牌立即作废并清掉本地状态</summary>
public async Task DisableAsync(CancellationToken ct = default)
{
StopUploadLoop();
var deviceId = _settings.DeviceId;
var token = _settings.DeviceToken;
_settings.DeviceServiceEnabled = false;
_settings.DeviceToken = string.Empty;
_settings.DeviceRefreshToken = string.Empty;
_settings.DeviceTokenExpiresAt = string.Empty;
_settings.Save();
if (deviceId > 0 && token.Length > 0 && SubjectId > 0)
{
try
{
await _api.DeactivateDeviceAsync(_session.Token, SubjectId, deviceId, ct).ConfigureAwait(false);
AppLog.Write($"[device] 设备服务已关闭(id={deviceId},令牌已作废)");
}
catch (Exception ex)
{
// 关服务不该因为网络问题卡住用户
AppLog.Write($"[device] 通知服务器关闭失败(本地已关闭):{ex.Message}");
}
}
else
{
AppLog.Write("[device] 设备服务已关闭(本地)");
}
}
/// <summary>换了主体/退出登录:本地状态清掉(不动服务器上的旧设备)</summary>
public void ResetLocalState()
{
StopUploadLoop();
_settings.DeviceServiceEnabled = false;
_settings.DeviceId = 0;
_settings.DeviceToken = string.Empty;
_settings.DeviceRefreshToken = string.Empty;
_settings.DeviceTokenExpiresAt = string.Empty;
_settings.Save();
}
/// <summary>
/// 通道 → 工作台类型(1 散单 / 2 团购 / 0 未知),由 <see cref="Scan.ScanService"/> 注入。
///
/// 散单的扫码枪也按「时间取**第一次** + 立即上报」记(和散单面单摄像头一致);
/// 团购(或未知)仍按「静默 5 秒、时间取最后一次」。
/// </summary>
public Func<string, int>? ChannelModeOf { get; set; }
/// <summary>
/// 上报一条扫码记录(fire-and-forget 的**入队**版本)。
///
/// ⚠️ 只在真的"扫了一次码"时调用;**运单查询不要调** ——
/// 查询只是看看,记一条 `DESKTOP` 记录会污染扫码记录表(历史要求)。
/// 先落本地库,由后台上报循环推给服务器;失败会一直重试,不会丢。
/// </summary>
public void ReportScan(string code) => ReportOnChannel(LocalChannelId, LocalChannelName, code);
/// <summary>
/// 用指定通道记一条扫码记录。
///
/// 与 AndroidScanCenter 的 ScanStore + BarcodeReporter 一致:
/// ① 先落本地(连续扫描只刷新「最近一次扫描时间」)→ ② 唤醒后台上报循环 →
/// ③ 服务器 2xx 确认后才把记录标成已上传,否则按退避重试。
///
/// **延迟上报**:扫到后 5 秒没再扫到同一个码才真正上报(见
/// <see cref="ScanRecordStore.SettleDelay"/>),上报的是最后一次扫描时间。
///
/// **散单通道例外**(<see cref="ChannelModeOf"/> 返回 1):时间取**第一次**、**立即上报**,
/// 和散单面单摄像头的规则一致;5 秒内重复扫同一个码只算一次(连续扫描帧)。
/// </summary>
/// <returns>true = 一次新的扫码事件(连续扫描的重复帧返回 false,界面不用重查)</returns>
public bool ReportOnChannel(string channelId, string channelName, string code)
{
var barcode = (code ?? string.Empty).Trim();
if (barcode.Length == 0) return false;
var channel = string.IsNullOrWhiteSpace(channelId) ? LocalChannelId : channelId;
var name = string.IsNullOrWhiteSpace(channelName) ? channel : channelName;
if ((ChannelModeOf?.Invoke(channel) ?? 0) == 1) return ReportFirstSeen(channel, name, barcode);
// 没开设备服务也照样记本地:开起来之后会把积压的自动补上去(断网/未开启期间不丢码)
var result = ScanRecordStore.Add(channel, name, barcode, DateTime.Now);
if (result.Item is null || result.Kind == ScanAddKind.Repeated) return false;
if (result.Kind == ScanAddKind.Touched)
{
if (ShouldLogTouched(channel, barcode))
{
AppLog.Write($"[scan] 通道 {channel} 扫码:{barcode}(更新最近扫描时间;5 秒内不再重复记录)");
}
}
else
{
AppLog.Write($"[scan] 通道 {channel} 扫码:{barcode}(5 秒未再扫到后上报)");
}
if (!Enabled) return true;
EnsureUploadLoop();
SignalUpload();
return true;
}
/// <summary>
/// **散单通道**的扫码枪记录:时间取第一次、立即上报(和散单面单摄像头一致)。
///
/// 扫码枪连续模式下同一个码每 ~80ms 报一次,所以这里做「在场」去重:
/// <see cref="FirstSeenGap"/> 内又扫到同一个码只算一次,不会把记录反复挂回队列。
/// </summary>
private bool ReportFirstSeen(string channel, string name, string barcode)
{
var now = DateTime.Now;
var key = $"{channel}|{barcode}";
var repeated = false;
lock (_firstSeenGate)
{
PruneFirstSeen(now);
if (_firstSeen.TryGetValue(key, out var seen) && now - seen.LastHitAt <= FirstSeenGap)
{
_firstSeen[key] = (seen.FirstSeenAt, now);
repeated = true;
}
else
{
_firstSeen[key] = (now, now);
}
}
if (repeated) return false;
var result = ScanRecordStore.AddCamera(channel, name, barcode, now);
if (result.Item is null || !result.IsScanEvent) return false;
AppLog.Write($"[scan] 通道 {channel} 扫码:{barcode}(散单:取第一次识别时间,立即上报)");
if (!Enabled) return true;
EnsureUploadLoop();
SignalUpload();
return true;
}
/// <summary>清掉 24 小时没再命中的在场记录(防字典无限增长)</summary>
private void PruneFirstSeen(DateTime now)
{
if (_firstSeen.Count == 0) return;
var stale = _firstSeen
.Where(pair => now - pair.Value.LastHitAt > TimeSpan.FromHours(24))
.Select(pair => pair.Key)
.ToList();
foreach (var key in stale) _firstSeen.Remove(key);
}
/// <summary>查服务器上当前中控已登记的通道(用于确认同步)</summary>
public Task<HashSet<string>> ChannelsAsync(CancellationToken ct = default)
=> _api.ChannelsAsync(_settings.DeviceToken, ct);
/// <summary>拉取本机的面单摄像头识别配置(`GET /api/scanner/label-cameras`)</summary>
public Task<System.Text.Json.JsonElement> FetchLabelCamerasAsync(CancellationToken ct = default)
=> _api.GetLabelCamerasAsync(_settings.DeviceToken, ct);
/// <summary>立即触发一次上报(界面的「立即上传」)</summary>
public void TriggerUpload()
{
if (!Enabled) return;
EnsureUploadLoop();
SignalUpload();
}
/// <summary>开设备服务时把上报循环拉起来(重复调用无影响)</summary>
public void EnsureUploadLoop()
{
if (_uploadTask is { IsCompleted: false }) return;
_uploadCts = new CancellationTokenSource();
_uploadTask = Task.Run(() => UploadLoopAsync(_uploadCts.Token));
}
/// <summary>停上报循环(关服务 / 退出登录)</summary>
public void StopUploadLoop()
{
try
{
_uploadCts?.Cancel();
}
catch
{
// 忽略
}
_uploadCts = null;
_uploadTask = null;
lock (_pauseGate)
{
_pauseState = PauseNone;
_pauseMessage = string.Empty;
}
UploadStatus = string.Empty;
ScanRecordStore.Flush();
}
private void SignalUpload()
{
try
{
if (_uploadSignal.CurrentCount == 0) _uploadSignal.Release();
}
catch
{
// 忽略
}
}
/// <summary>
/// 后台上报循环:有信号、有积压时每秒检查一次(空闲时 30 秒),
/// 把**静默满 5 秒**的待上传记录攒批推送。
///
/// 失败时**不标记**那批记录,等退避(1s→2s→5s→10s→30s 封顶)后重发;
/// 服务端按 设备+通道+条码+秒 去重、同一运单 24 小时内覆盖成最新时间,
/// 所以整批重发不会造成重复落库,也不会把时间改回过去。
///
/// **主体过期/停用或令牌失效时不推送**:队列原样保留,每 60 秒只发一次心跳探测,
/// 续期(或重新开启设备服务)后自动恢复并把积压补传上去。
/// </summary>
private async Task UploadLoopAsync(CancellationToken ct)
{
while (!ct.IsCancellationRequested)
{
try
{
// 静默期只有 5 秒:有待上传记录时每秒回来看一次,
// 否则「最后一次扫描 + 5 秒」会被拖到下一次 30 秒保活才上报。
var wait = ScanRecordStore.PendingCount() > 0 ? UploadBusyInterval : UploadIdleInterval;
await _uploadSignal.WaitAsync(wait, ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
break;
}
while (!ct.IsCancellationRequested && Enabled)
{
if (UploadPaused)
{
await WaitAndProbeAsync(ct).ConfigureAwait(false);
continue;
}
var batch = ScanRecordStore.Pending(50);
if (batch.Count == 0)
{
UploadStatus = string.Empty;
break;
}
try
{
var rows = batch.Select(item => (item.ChannelId, item.Code, item.ScannedAt)).ToList();
await _api.ReportRecordsAsync(_settings.DeviceToken, rows, ct).ConfigureAwait(false);
// 服务器已确认:只有这里才把记录标成已上传
// (传入上报时的扫描时间:上报期间又扫到的话保持待上传,下一轮带最新时间重发)
ScanRecordStore.MarkUploaded(batch.Select(item => (item.Id, item.ScannedAt)));
_uploadRetryMs = 1000;
UploadStatus = string.Empty;
AppLog.Write($"[scan] 已上报扫码 {batch.Count} 条");
}
catch (OperationCanceledException)
{
break;
}
catch (ApiException ex) when (ex.IsSubjectUnavailable)
{
// 主体不可用:不重试、不丢队列,改为等心跳探测到续期
Pause(PauseSubject, ex.Message);
}
catch (ApiException ex) when (ex.StatusCode == 401)
{
// 令牌失效(被踢下线/重新扫码过):重新开启设备服务之前无法恢复
Pause(PauseUnauthorized, "设备令牌已失效(可能已在其他设备开启),请重新开启设备服务");
}
catch (Exception ex)
{
UploadStatus = $"上报失败(待上传 {ScanRecordStore.PendingCount()} 条),{_uploadRetryMs / 1000} 秒后重试";
AppLog.Write($"[scan] 上报扫码失败({batch.Count} 条,{_uploadRetryMs}ms 后重试):{ex.Message}");
try
{
await Task.Delay(_uploadRetryMs, ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
break;
}
_uploadRetryMs = Math.Min(_uploadRetryMs * 2, 30000);
}
}
}
}
/// <summary>暂停期间:等一会儿 → 只发心跳探测主体是否已恢复;令牌失效时不再探测</summary>
private async Task WaitAndProbeAsync(CancellationToken ct)
{
bool unauthorized;
lock (_pauseGate) unauthorized = _pauseState == PauseUnauthorized;
// 有积压就 60 秒探一次(续费后 1 分钟内自动补传);没积压就 5 分钟探一次,别浪费请求。
// 用 _uploadSignal 等待:重新开启设备服务 / 手动「立即上传」会立刻唤醒,不用干等。
var interval = ScanRecordStore.PendingCount() > 0 ? PauseProbeInterval : TimeSpan.FromMinutes(5);
try
{
await _uploadSignal.WaitAsync(interval, ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
throw;
}
RefreshPausedStatus();
// 已被 Resume(重新鉴权/续期事件)唤醒:直接回到上报循环,不重复探测
if (!UploadPaused) return;
if (!Enabled || unauthorized) return;
// 同一分钟内不重复探测(扫码会频繁唤醒,不需要每次都发心跳)
if (DateTime.UtcNow - _lastProbeAt < PauseProbeInterval) return;
_lastProbeAt = DateTime.UtcNow;
try
{
var beat = await _api.HeartbeatAsync(_settings.DeviceToken, ct).ConfigureAwait(false);
_probeFailures = 0;
ApplySubjectState(beat?.Subject);
}
catch (OperationCanceledException)
{
throw;
}
catch (ApiException ex) when (ex.StatusCode == 401)
{
Pause(PauseUnauthorized, "设备令牌已失效(可能已在其他设备开启),请重新开启设备服务");
}
catch (Exception ex)
{
// 网络问题:保持暂停,下个周期再探测;只偶尔记一行,别刷屏
if (++_probeFailures % 10 == 1)
{
AppLog.Write($"[scan] 暂停期间心跳探测失败(继续等待,本地记录不受影响):{ex.Message}");
}
}
}
private void Pause(int state, string message)
{
var pending = ScanRecordStore.PendingCount();
var changed = false;
lock (_pauseGate)
{
changed = _pauseState != state || _pauseMessage != message;
_pauseState = state;
_pauseMessage = message;
UploadStatus = $"{message}(待上传 {pending} 条,恢复后自动补传)";
}
if (changed)
{
_lastProbeAt = DateTime.MinValue;
AppLog.Write($"[scan] {message},已暂停上报(本地记录保留,待上传 {pending} 条)");
}
}
private void Resume(string message)
{
var changed = false;
lock (_pauseGate)
{
changed = _pauseState != PauseNone;
_pauseState = PauseNone;
_pauseMessage = string.Empty;
UploadStatus = string.Empty;
}
if (!changed) return;
_uploadRetryMs = 1000;
_probeFailures = 0;
_lastProbeAt = DateTime.MinValue;
AppLog.Write($"[scan] {message}");
SubjectResumed?.Invoke();
SignalUpload();
}
/// <summary>刷新暂停提示里的「待上传 N 条」(暂停期间会继续扫码/积压)</summary>
private void RefreshPausedStatus()
{
var pending = ScanRecordStore.PendingCount();
lock (_pauseGate)
{
if (_pauseState == PauseNone) return;
UploadStatus = $"{_pauseMessage}(待上传 {pending} 条,恢复后自动补传)";
}
}
}