chore: Android 扫码台设置页、发布脚本健壮性与文档同步

- Android 扫码台:设置页新增「设为默认桌面 / 解除默认桌面 / 回到盒子桌面 / 打开系统设置」等现场免 adb 操作
- android_client/build.ps1:gradle 的 javac 提示走 stderr,改成 2>&1 逐行 Write-Host,避免被当成构建失败
- deploy-lib.cjs:ssh 加 ServerAliveInterval/CountMax 与 -n,避免发布脚本卡在远端命令结束前不退出
- set-password.js:重置密码时补写 password_changed_at(否则旧 JWT 不失效)
- .gitignore:忽略 video_split/(调试用的视频拆帧产物)
- 文档同步:README / backend README(微信网关、成员扫码绑定、平台管理员、顶栏下载入口、已下线的自建微信表)/
  database README / desktop README

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-10-29 17:21:41 +08:00
parent 3e2bd56416
commit 43dae198db
18 changed files with 1282 additions and 215 deletions

3
.gitignore vendored
View File

@ -90,3 +90,6 @@ desktop.ini
# ---------- 内置 ffmpeg(exe 体积大不进仓库;打包前按 desktop/native/ffmpeg/README.md 放好) ----------
desktop/native/ffmpeg/*.exe
# ---------- 调试用的视频拆帧产物(video_split/frame_*.jpg,别提交) ----------
video_split/

View File

@ -29,6 +29,12 @@
(协议见 [`docs/udp-48899-protocol.md`](docs/udp-48899-protocol.md))。
- **扫码上报**:`ScanServer` 监听 TCP 8087,桌面端连上后,主界面收到的每一条扫码结果
都会按行推送过去。桌面端下发的扫码枪串口设置指令会被读取并丢弃(本机是 USB HID)。
- **下游播报(面单摄像头)**:桌面端识别到条码后,只给型号是 `AndroidStation`(安卓扫描通道)的通道
在同一 TCP 连接上下发 `0x1E + {"cmd":"scan","id":"…","code":"…"} + "\n"` 控制帧;本机**先蜂鸣一声**(方波 2.7kHz/90ms,
和语音拼在同一段 PCM 里一次播出来)**再播报后四位 + 开始打包**,并在主界面显示这条条码,
然后**回执** `0x1E + {"cmd":"ack","id":"…"} + "\n"`(id 必须原样回显;桌面端据此确认通知成功,超时会重发)。
播报/显示都不会把条码回推给桌面端(避免回路)。
网口扫码枪没有语音能力,桌面端不给它们发;但**扫码记录与通知无关**,安卓端离线也照样落库上传。
- **兼容桌面端添加通道**:响应 JCMD `10001 / 10003 / 10005 / 10017`,报出一条
`packcenter / TCP-SERVER / 8087` 的 SOCK 条目;桌面端写 `SYS.HostName` 会更新设备名,
写 `SOCK.LocalPort` 会改本地服务端口。`20003` 只确认,不重启本机。
@ -36,8 +42,10 @@
## 主界面
- 设备名称 / MAC / IP / 型号版本 / 服务与发现状态 / 累计扫码。
- 最近 8 条扫码记录(**每 5 秒才刷新一次**,不参与扫码热路径)。
- 设备名称 / MAC / IP / 型号版本 / 服务与发现状态 / 累计扫码(面单摄像头下发的会单独计「面单 N」)。
- 最近 8 条扫码记录(**每 5 秒才刷新一次**,不参与扫码热路径);
桌面端下发的面单条码会**立刻**刷新界面,并带 `[面单]` 前缀,最近条码下面写「面单摄像头识别:时间」,
现场据此确认「摄像头认的是不是这张面单」(只显示、只播报,不回推桌面端)。
- USB 扫码枪是键盘设备:在 Activity 层统一收键,连续可打印字符攒成一条条码,
回车/Tab 立即提交;没有后缀时停手 **50ms** 自动提交。
- 底部「服务设置」「清空记录」两个按钮可用遥控器操作。
@ -51,6 +59,18 @@
按键 → 追加缓冲 → 提交 → StationService 入队 → 后台写线程 → 桌面端
```
#### 语音播报「开头被吞」的处理(踩过的坑)
实测这段临时 WAV 起播时开头会被吃掉一小段(起播延迟 + 音频输出通道切换),
表现是「后四位」里第一个/前两个数字、或者**蜂鸣声**听不到。所以:
- PCM 最前面垫静音 `LEAD_IN_MS = 300`,尾部垫 120ms(避免还没播完就被 `release`);
- **蜂鸣必须排在静音之后**(`300ms 静音 → 嘀 160ms → 40ms → 后四位`):
只垫 60ms 就让蜂鸣起播时,蜂鸣正好落在起播损耗窗口里,经常整个被吞;
- **先 `start()` 新的 MediaPlayer,再停/收掉上一句**:反过来会让音频输出通道在起播瞬间被拆,
开头更容易被吞;
- `setVolume(1f, 1f)` 兜一下某些 ROM 的淡入。
- **按键/扫码回调里不同步刷新任何 UI、不写日志**;界面由 1 秒的时钟和 5 秒一次的状态刷新兜底。
- socket 写入只在 `station-scan-write` 单线程里做,避免主线程 `NetworkOnMainThreadException`,
同时保证多条扫码按顺序发出。
@ -151,13 +171,58 @@ npm run android:publish # 构建 + 上传 + 刷新 nginx
- 这是**普通用户应用**:只需要 `INTERNET`、`RECEIVE_BOOT_COMPLETED`、
`MODIFY_AUDIO_SETTINGS` 三个普通权限,`/data` 直接安装即可。
- 不依赖 Device Owner / 设备管理员 / lock task / 系统应用 / 任何 ADB 赋权。
- 不依赖 Device Owner / 设备管理员 / lock task / 系统应用(kiosk 方式见下文,也是纯普通应用)。
- `BootReceiver` 监听 `BOOT_COMPLETED`,开机后自动拉起 `MainActivity`。
开机后还会用 `AlarmManager` 在 **6 秒 / 15 秒**各补一次「切回前台」(`FLAG_ACTIVITY_REORDER_TO_FRONT`)。
⚠️ Android 的既定行为:**新装后必须手动启动一次**,应用才脱离 stopped 状态,
之后重启才会收到开机广播。
- ⚠️ **电视盒子 ROM 会拦后台启动 Activity**:实测 G96max H616(Android 10)即使 targetSdk=28,
开机广播拉起界面也会被拒(`logcat` 里 `Background activity start … isBgStartWhitelisted: false`),
结果是服务起来了、界面被盒子自带桌面 `com.swe.dgbluancher` 顶到后台。
这种机器要**把它设成盒子桌面(kiosk)**,由系统自己启动:
```bash
# 设成桌面(开机直接进扫码界面,不会再被桌面抢前台)
adb shell cmd package set-home-activity com.gztbyc.scancenter/.MainActivity
# 校验:isDefault=true / com.gztbyc.scancenter/.MainActivity
adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME
# 想还原成盒子自带桌面
adb shell cmd package set-home-activity com.swe.dgbluancher/.MainActivity
# 设成桌面后要进系统设置:adb shell am start -a android.settings.SETTINGS
```
普通手机/平板(不设 HOME)只靠 `BOOT_COMPLETED` 就够。
- 主界面不在后台驻留额外服务;扫码服务随应用进程生命周期运行。
## 约定
## 服务设置
设备名、扫码服务端口(TCP)、发现端口(UDP)、两个启停开关,以及 **「开机 / 桌面」** 一栏:
- **设为默认桌面**:调用 `RoleManager.createRequestRoleIntent(ROLE_HOME)`,由**系统自己**弹
「要将扫码终端设为您的默认主屏幕应用吗?」的确认框(`取消` / `设为默认应用`)。
不需要 adb、不需要 root,也**不用先把默认桌面清掉**;
- **解除默认桌面**:**Android 不允许应用自己放弃 HOME 角色**(只有系统/设备管理员能 `removeRoleHolder`),
所以点它弹一个框,给三条路:
1. 打开系统「主屏幕应用」页 → 选回盒子自带桌面(个别 ROM 这页一开就闪退,见下);
2. **卸载本应用**(`ACTION_DELETE` 系统卸载确认框)→ 桌面角色自动释放,盒子回自带桌面,需要时再装;
3. 取消(改用下面的「回到盒子桌面」);
- **回到盒子桌面**:不改默认设置,直接把机器上**另一个**桌面应用拉到前台(临时用一下);
- **打开系统设置**:设成桌面后现场唯一的系统入口;
- 状态行会显示当前是「扫码终端」还是「盒子自带桌面」,按钮按状态自动置灰。
⚠️ 已知 ROM 缺陷:**G96max H616(Android 10)的系统「主屏幕应用 / 默认应用」页会闪退**
(`java.lang.NullPointerException: android.app.ActionBar.setDisplayHomeAsUpEnabled … null object reference`),
只有 `com.android.tv.settings` 的「设置」首页能开。这种机器上解除桌面只能走
**卸载本应用**,或者用 adb:
```bash
adb shell cmd package set-home-activity com.swe.dgbluancher/.MainActivity # 还原成盒子自带桌面
```
为什么要设桌面:部分电视盒子 ROM 禁止应用在后台拉起界面
(`logcat`:`Background activity start … isBgStartWhitelisted: false`),开机广播收到也切不到前台。
Android 10 以下没有 RoleManager 时,这一栏会提示去「设置 → 应用 → 默认应用 → 主屏幕应用」手动选择。
- 依赖仓库走阿里云镜像,Gradle 分发走腾讯云镜像,改动仓库配置时保持国内源优先。
- 主界面以遥控器为主:可点击控件必须方向键可达,并在 `res/drawable/bg_button.xml`

View File

@ -46,6 +46,15 @@
<category android:name="android.intent.category.LEANBACK_LAUNCHER" />
<!-- 普通桌面入口 -->
<category android:name="android.intent.category.LAUNCHER" />
<!--
也可以被选作盒子桌面(kiosk):
某些电视盒子 ROM(实测 G96max H616 / Android 10)禁止后台拉起 Activity
(日志:Background activity start … isBgStartWhitelisted: false),
开机广播收到也回不到前台。设成 HOME 后由系统自己启动,稳定常驻。
现场用 `adb shell cmd package set-home-activity com.gztbyc.scancenter/.MainActivity` 切换。
-->
<category android:name="android.intent.category.HOME" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>

View File

@ -205,18 +205,20 @@ public class MainActivity extends AppCompatActivity {
StationIdentity.MODEL, StationIdentity.version()));
infoServiceView.setText(serviceStatusText());
infoDiscoveryView.setText(discoveryStatusText());
infoTotalView.setText(getString(R.string.main_total_value, service.totalScans()));
infoTotalView.setText(service.remoteScans() > 0
? getString(R.string.main_total_value_remote, service.totalScans(), service.remoteScans())
: getString(R.string.main_total_value, service.totalScans()));
String code = service.lastCode();
if (code.isEmpty()) {
StationService.ScanEntry latest = service.latestEntry();
if (latest == null) {
lastCodeView.setText(R.string.main_waiting);
lastTimeView.setText("");
}
else {
lastCodeView.setText(code);
long atMs = service.lastScanAt();
lastTimeView.setText(getString(R.string.main_last_time,
clockFormat.format(new Date(atMs))));
lastCodeView.setText(latest.code);
lastTimeView.setText(getString(
latest.remote ? R.string.main_last_time_camera : R.string.main_last_time,
clockFormat.format(new Date(latest.atMs))));
}
List<StationService.ScanEntry> history = service.history();
@ -232,8 +234,11 @@ public class MainActivity extends AppCompatActivity {
text.append('\n');
}
text.append(clockFormat.format(new Date(entry.atMs)))
.append(" ")
.append(entry.code);
.append(" ");
if (entry.remote) {
text.append(getString(R.string.main_recent_remote_tag)).append(' ');
}
text.append(entry.code);
}
recentView.setText(text.toString());
}

View File

@ -1,6 +1,14 @@
package com.gztbyc.scancenter;
import android.app.role.RoleManager;
import android.content.ComponentName;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.content.pm.ResolveInfo;
import android.net.Uri;
import android.os.Build;
import android.os.Bundle;
import android.provider.Settings;
import android.view.View;
import android.widget.Button;
import android.widget.EditText;
@ -8,6 +16,7 @@ import android.widget.TextView;
import android.widget.Toast;
import androidx.annotation.Nullable;
import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import androidx.appcompat.widget.SwitchCompat;
@ -15,19 +24,32 @@ import com.gztbyc.scancenter.core.StationIdentity;
import com.gztbyc.scancenter.core.StationSettings;
import com.gztbyc.scancenter.core.service.StationService;
import static com.gztbyc.scancenter.util.L.e;
import static com.gztbyc.scancenter.util.L.i;
/**
* 服务设置:只配置设备名、扫码服务端口、发现端口和启停开关。
* 服务设置:设备名、扫码服务端口、发现端口、启停开关,以及「设为盒子桌面」。
*
* <p>按现场要求<b>不提供改 IP 的入口</b>:设备地址由网络分配,应用只负责应答发现和推扫码数据。
*
* <p>「设为盒子桌面」用 Android 10 的 {@link RoleManager#createRequestRoleIntent}:
* 由系统弹自己的确认框(不需要 adb、不需要 root、也不用先把默认桌面清掉)。
* 为什么要这个:部分电视盒子 ROM(实测 G96max H616)禁止应用在后台拉起界面,
* 开机广播收到了界面也切不到前台,只有设成桌面才会由系统直接进入。
*/
public class SettingsActivity extends AppCompatActivity {
private static final int REQUEST_HOME_ROLE = 1001;
private EditText nameField;
private EditText servicePortField;
private EditText discoveryPortField;
private SwitchCompat serviceSwitch;
private SwitchCompat discoverySwitch;
private TextView statusView;
private TextView homeStatusView;
private Button setHomeButton;
private Button clearHomeButton;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
@ -40,6 +62,9 @@ public class SettingsActivity extends AppCompatActivity {
serviceSwitch = findViewById(R.id.sw_service_enabled);
discoverySwitch = findViewById(R.id.sw_discovery_enabled);
statusView = findViewById(R.id.tv_settings_status);
homeStatusView = findViewById(R.id.tv_home_status);
setHomeButton = findViewById(R.id.btn_set_home);
clearHomeButton = findViewById(R.id.btn_clear_home);
nameField.setText(StationSettings.deviceName(this));
servicePortField.setText(String.valueOf(StationSettings.servicePort(this)));
@ -63,6 +88,36 @@ public class SettingsActivity extends AppCompatActivity {
}
});
setHomeButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
requestHomeRole();
}
});
clearHomeButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
showClearHomeDialog();
}
});
Button freeLauncher = findViewById(R.id.btn_free_launcher);
freeLauncher.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
openOtherLauncher();
}
});
Button systemSettings = findViewById(R.id.btn_system_settings);
systemSettings.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
openSystemSettings();
}
});
serviceSwitch.setOnCheckedChangeListener((button, checked) -> renderStatus());
discoverySwitch.setOnCheckedChangeListener((button, checked) -> renderStatus());
renderStatus();
@ -72,6 +127,180 @@ public class SettingsActivity extends AppCompatActivity {
protected void onResume() {
super.onResume();
renderStatus();
renderHomeStatus();
}
@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode != REQUEST_HOME_ROLE) {
return;
}
// 角色变更是异步落库的,等一小会儿再读
homeStatusView.postDelayed(new Runnable() {
@Override
public void run() {
renderHomeStatus();
if (isHomeRoleHeld()) {
Toast.makeText(SettingsActivity.this, R.string.settings_home_done, Toast.LENGTH_SHORT).show();
}
}
}, 400);
}
/** 当前是否已经是默认桌面 */
private boolean isHomeRoleHeld() {
if (Build.VERSION.SDK_INT < 29) {
return false;
}
RoleManager roles = getSystemService(RoleManager.class);
return roles != null && roles.isRoleAvailable(RoleManager.ROLE_HOME) && roles.isRoleHeld(RoleManager.ROLE_HOME);
}
private void renderHomeStatus() {
if (homeStatusView == null || setHomeButton == null) {
return;
}
if (Build.VERSION.SDK_INT < 29) {
homeStatusView.setText(R.string.settings_home_unsupported);
setHomeButton.setEnabled(false);
if (clearHomeButton != null) clearHomeButton.setEnabled(true);
return;
}
RoleManager roles = getSystemService(RoleManager.class);
if (roles == null || !roles.isRoleAvailable(RoleManager.ROLE_HOME)) {
homeStatusView.setText(R.string.settings_home_unsupported);
setHomeButton.setEnabled(false);
if (clearHomeButton != null) clearHomeButton.setEnabled(true);
return;
}
boolean held = roles.isRoleHeld(RoleManager.ROLE_HOME);
homeStatusView.setText(held ? R.string.settings_home_is_default : R.string.settings_home_not_default);
setHomeButton.setEnabled(!held);
// 解除:安卓不允许应用自己放弃 HOME 角色,只能走系统页面或卸载(见 showClearHomeDialog)
if (clearHomeButton != null) clearHomeButton.setEnabled(held);
}
/**
* 解除默认桌面:把三条路摆出来让人选。
*
* <p>为什么不能一键解除:Android 只给系统/设备管理员 {@code removeRoleHolder} 的能力,
* 普通应用只能「申请」角色,不能「放弃」角色。
*/
private void showClearHomeDialog() {
new AlertDialog.Builder(this)
.setTitle(R.string.settings_clear_home_title)
.setMessage(R.string.settings_clear_home_message)
.setPositiveButton(R.string.settings_clear_home_open_settings, (dialog, which) -> openHomeSettings())
.setNeutralButton(R.string.settings_clear_home_uninstall, (dialog, which) -> uninstallSelf())
.setNegativeButton(R.string.settings_clear_home_cancel, null)
.show();
}
/** 兜底:走系统卸载确认框;卸载后桌面角色自动释放,盒子回自带桌面 */
private void uninstallSelf() {
try {
startActivity(new Intent(Intent.ACTION_DELETE, Uri.parse("package:" + getPackageName())));
}
catch (Exception error) {
e("打开卸载确认框失败", error);
Toast.makeText(this, getString(R.string.settings_home_failed, String.valueOf(error.getMessage())),
Toast.LENGTH_LONG).show();
}
}
/** 不改默认设置,直接切到盒子自带的那个桌面去看一眼 */
private void openOtherLauncher() {
PackageManager pm = getPackageManager();
Intent query = new Intent(Intent.ACTION_MAIN).addCategory(Intent.CATEGORY_HOME);
for (ResolveInfo info : pm.queryIntentActivities(query, 0)) {
if (info.activityInfo == null) {
continue;
}
String pkg = info.activityInfo.packageName;
if (pkg == null || pkg.equals(getPackageName())) {
continue;
}
try {
Intent launch = new Intent(Intent.ACTION_MAIN)
.setComponent(new ComponentName(pkg, info.activityInfo.name))
.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(launch);
Toast.makeText(this, R.string.settings_back_to_launcher_done, Toast.LENGTH_SHORT).show();
i("已切到其它桌面", pkg);
return;
}
catch (Exception error) {
e("切到其它桌面失败", pkg, error);
}
}
Toast.makeText(this, R.string.settings_no_other_launcher, Toast.LENGTH_LONG).show();
}
/**
* 打开系统「主屏幕应用」选择页。
*
* <p>个别盒子 ROM 的这个页面一打开就闪退(实测 G96max H616:
* {@code NullPointerException: ActionBar … on a null object reference}),
* 所以失败时依次退到「默认应用」页和系统设置首页。
*/
private void openHomeSettings() {
String[] actions = {
Settings.ACTION_HOME_SETTINGS,
Settings.ACTION_MANAGE_DEFAULT_APPS_SETTINGS,
Settings.ACTION_SETTINGS,
};
for (String action : actions) {
try {
startActivity(new Intent(action));
Toast.makeText(this,
Settings.ACTION_HOME_SETTINGS.equals(action)
? R.string.settings_home_clear_opened
: R.string.settings_home_settings_missing,
Toast.LENGTH_LONG).show();
i("已打开系统设置页", action);
return;
}
catch (Exception error) {
e("打开系统设置页失败", action, error);
}
}
Toast.makeText(this, getString(R.string.settings_home_failed, "没有可用的系统设置页"),
Toast.LENGTH_LONG).show();
}
/** 让系统弹「将扫码终端设为默认主屏幕应用?」的确认框 */
private void requestHomeRole() {
if (Build.VERSION.SDK_INT < 29) {
openSystemSettings();
return;
}
RoleManager roles = getSystemService(RoleManager.class);
if (roles == null) {
openSystemSettings();
return;
}
try {
startActivityForResult(roles.createRequestRoleIntent(RoleManager.ROLE_HOME), REQUEST_HOME_ROLE);
Toast.makeText(this, R.string.settings_home_requested, Toast.LENGTH_SHORT).show();
i("已请求设为默认桌面(等系统确认)");
}
catch (Exception error) {
e("请求设为默认桌面失败", error);
openSystemSettings();
}
}
/** 退路:直接打开系统设置(设成桌面后现场就靠这个进来) */
private void openSystemSettings() {
try {
startActivity(new Intent(Settings.ACTION_SETTINGS));
}
catch (Exception error) {
e("打开系统设置失败", error);
Toast.makeText(this, getString(R.string.settings_home_failed, String.valueOf(error.getMessage())),
Toast.LENGTH_LONG).show();
}
}
private void saveSettings() {

View File

@ -2,6 +2,9 @@ package com.gztbyc.scancenter.core.service;
import com.gztbyc.scancenter.BuildConfig;
import org.json.JSONObject;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetSocketAddress;
@ -25,6 +28,9 @@ import static com.gztbyc.scancenter.util.L.w;
* <b>设备监听、桌面端主动连接</b>。每收到一条扫码结果,按行(CRLF 结尾)
* 写给所有已连接的客户端;客户端下发的扫码枪设置指令(二进制)只读取并丢弃
* —— 本机的扫码枪是 USB HID,不需要这些串口指令。
*
* <p>另外解析桌面端下发的 <c>0x1E</c> 控制帧(<c>{"cmd":"scan","code":"..."}</c> =
* 桌面端识别到条码、通知本机「扫码成功」):只做离线语音播报,**不回推桌面端**。
*/
public final class ScanServer {
@ -287,6 +293,12 @@ public final class ScanServer {
private final class Client implements Runnable {
/** 桌面端控制帧起始字节(RS,不会出现在条码和扫码枪设置指令里) */
private static final int CONTROL_MARK = 0x1E;
/** 单条控制帧上限(防止异常数据把内存撑大) */
private static final int MAX_CONTROL_BYTES = 2048;
final Socket socket;
final String remoteIp;
final AtomicBoolean closed = new AtomicBoolean(false);
@ -326,17 +338,44 @@ public final class ScanServer {
@Override
public void run() {
byte[] buffer = new byte[512];
boolean logged = false;
boolean loggedSettings = false;
ByteArrayOutputStream control = null;
try {
while (running && !closed.get()) {
int read = input.read(buffer);
if (read < 0) {
break;
}
if (!logged) {
logged = true;
// 桌面端连上后会下发扫码枪设置(串口指令),本机是 USB HID,忽略
i("已忽略桌面端下发的扫码枪设置指令", remoteIp, read + " 字节");
for (int index = 0; index < read; index++) {
int value = buffer[index] & 0xFF;
// 本机是 USB HID:二进制扫码枪设置指令照旧忽略;
// 0x1E 开头的控制帧是桌面端给的「播报」指令(面单摄像头识别结果)
if (control == null) {
if (value == CONTROL_MARK) {
control = new ByteArrayOutputStream(128);
}
else if (value != '\n' && value != '\r' && !loggedSettings) {
loggedSettings = true;
i("已忽略桌面端下发的扫码枪设置指令", remoteIp, read + " 字节");
}
continue;
}
if (value == '\n' || value == '\r') {
if (control.size() > 0) {
handleControl(new String(control.toByteArray(), StandardCharsets.UTF_8));
}
control = null;
}
else if (control.size() < MAX_CONTROL_BYTES) {
control.write(value);
}
else {
// 超长帧直接丢弃,避免异常客户端把内存撑大
control = null;
}
}
}
}
@ -348,6 +387,64 @@ public final class ScanServer {
}
}
/** 处理桌面端控制帧:`{cmd:"scan", id, code}` = 扫码成功 → 播报 + 回执(只播报,不回推) */
private void handleControl(String json) {
try {
JSONObject object = new JSONObject(json);
String cmd = object.optString("cmd", "");
if (!"scan".equals(cmd) && !"speak".equals(cmd)) {
return;
}
String code = object.optString("code", "").trim();
if (code.length() < 4 || code.length() > 64) {
return;
}
StationService.instance().announceRemote(code);
i("收到桌面端扫码成功通知,已播报", remoteIp, code);
// 回执:桌面端据此确认「通知成功」(等不到回执它会重发一次)
sendAck(object.optString("id", "").trim());
}
catch (Exception failure) {
w("桌面端控制帧解析失败", describe(failure));
}
}
/**
* 回执帧:0x1E + {"cmd":"ack","id":"..."} + '\n',和扫码结果走同一条上行连接。
*
* id 必须**原样回显**:桌面端是拿自己生成的 id 去比对回执的,
* 之前把非字母数字字符过滤掉(`-` 被吃掉)会让桌面端永远等不到回执。
* 用 JSONObject 拼,转义由它负责,长度只做个上限防滥用。
*/
private void sendAck(String rawId) {
String raw = rawId == null ? "" : rawId.trim();
if (raw.isEmpty()) {
return;
}
String id = raw.length() > 64 ? raw.substring(0, 64) : raw;
byte[] body;
try {
JSONObject ack = new JSONObject();
ack.put("cmd", "ack");
ack.put("id", id);
body = ack.toString().getBytes(StandardCharsets.UTF_8);
}
catch (Exception failure) {
w("播报回执拼包失败", describe(failure));
return;
}
byte[] frame = new byte[body.length + 2];
frame[0] = (byte) CONTROL_MARK;
System.arraycopy(body, 0, frame, 1, body.length);
frame[frame.length - 1] = (byte) '\n';
if (!write(frame)) {
w("播报回执发送失败", remoteIp);
}
}
void close() {
if (!closed.compareAndSet(false, true)) {
return;

View File

@ -28,9 +28,13 @@ public final class StationService {
public final String code;
public final long atMs;
ScanEntry(String code, long atMs) {
/** true = 桌面端下发的(面单摄像头识别),false = 本机 USB 扫码枪 */
public final boolean remote;
ScanEntry(String code, long atMs, boolean remote) {
this.code = code;
this.atMs = atMs;
this.remote = remote;
}
}
@ -49,6 +53,7 @@ public final class StationService {
private String lastCode = "";
private long lastScanAt;
private long totalScans;
private long remoteScans;
private StationService() {
}
@ -162,7 +167,7 @@ public final class StationService {
lastCode = code;
lastScanAt = now;
totalScans++;
history.addFirst(new ScanEntry(code, now));
history.addFirst(new ScanEntry(code, now, false));
while (history.size() > MAX_HISTORY) {
history.removeLast();
}
@ -173,12 +178,43 @@ public final class StationService {
BarcodeSpeaker.instance().announce(code);
}
/**
* 桌面端通知「扫码成功」(面单摄像头识别到的条码):播报 + **显示在界面上**,但**不回推**。
*
* 这条码的记录已经由桌面端写进待上报队列,本机只负责让现场听到语音、看到条码
* (这样打包的人能确认「摄像头认的是不是这张面单」);
* 所以绝不能调用 {@link #pushBarcode(String)} —— 那会把这条码再推回桌面端,形成回路,
* 也会让「本地扫码」和「摄像头识别」互相干扰。
*
* 历史里会带上 {@link ScanEntry#remote} 标记,界面显示成「面单」来源;
* 累计扫码数只统计本机扫码枪,面单摄像头单独计数。
*/
public void announceRemote(String code) {
if (code == null || code.isEmpty()) {
return;
}
long now = System.currentTimeMillis();
synchronized (history) {
lastCode = code;
lastScanAt = now;
remoteScans++;
history.addFirst(new ScanEntry(code, now, true));
while (history.size() > MAX_HISTORY) {
history.removeLast();
}
}
BarcodeSpeaker.instance().announce(code, true);
// 这条码是给人看的,必须立刻刷界面(界面的 1 秒兜底刷新太慢)
notifyState();
}
public void clearHistory() {
synchronized (history) {
history.clear();
lastCode = "";
lastScanAt = 0L;
totalScans = 0L;
remoteScans = 0L;
}
notifyState();
}
@ -201,6 +237,20 @@ public final class StationService {
}
}
/** 面单摄像头(桌面端下发)识别的条数 */
public long remoteScans() {
synchronized (history) {
return remoteScans;
}
}
/** 最新一条(本机扫码或面单摄像头),没有返回 null */
public ScanEntry latestEntry() {
synchronized (history) {
return history.isEmpty() ? null : history.peekFirst();
}
}
public List<ScanEntry> history() {
synchronized (history) {
return new ArrayList<ScanEntry>(history);

View File

@ -57,6 +57,24 @@ public final class BarcodeSpeaker {
/** 同一个条码在这个时间内不重复播报(连续扫描的重复帧) */
private static final long REPEAT_QUIET_MS = 2500L;
/** 模拟蜂鸣器:方波 2.7kHz / 160ms,后面再停 40ms 接语音(桌面端下发的面单条码用) */
private static final int BEEP_MS = 160;
private static final int BEEP_FREQ_HZ = 2700;
private static final int BEEP_GAP_MS = 40;
private static final double BEEP_AMPLITUDE = 0.4;
/**
* 起播/收尾要垫的静音。
*
* <p>实测:这段 WAV 起播时开头会被吃掉一小段(起播延迟 + 音频通道切换),
* 表现为「后四位」里第一个/前两个数字、或者蜂鸣声听不到。垫静音后吃掉的只是静音。
*
* <p>蜂鸣也排在静音**之后**:之前只垫 60ms 就让蜂鸣起播,结果蜂鸣经常整个被吞掉
* (语音因为在后面反而正常),所以蜂鸣必须放在起播损耗窗口之外。
*/
private static final int LEAD_IN_MS = 300;
private static final int TAIL_MS = 120;
/** 启动后延迟多久播欢迎语(等 Activity/服务都就绪) */
private static final long WELCOME_DELAY_MS = 1200L;
@ -97,6 +115,7 @@ public final class BarcodeSpeaker {
private long lastAnnouncedAt;
private boolean cacheCleaned;
private boolean welcomeScheduled;
private byte[] beepCache;
private BarcodeSpeaker() {
}
@ -185,6 +204,18 @@ public final class BarcodeSpeaker {
* <p>只做很轻的判重和入队;拼 PCM、写 WAV、起播都在 {@code station-speech} 线程。
*/
public void announce(String code) {
announce(code, false);
}
/**
* 播报一条条码,可选**先蜂鸣一声**(模拟扫码枪的蜂鸣器)。
*
* <p>蜂鸣直接拼在同一段 PCM 前面(方波 + 静音间隔),一次播放出来:
* 不用 ToneGenerator/额外音轨,rk3288 上不会有"蜂鸣和语音抢音频通道"的问题。
*
* @param beepFirst 桌面端下发的面单条码用 true:先「嘀」一下再播后四位,和手持枪手感一致
*/
public void announce(String code, boolean beepFirst) {
Context ctx = context;
if (ctx == null || code == null || code.isEmpty()) {
return;
@ -206,16 +237,84 @@ public final class BarcodeSpeaker {
worker.execute(new Runnable() {
@Override
public void run() {
byte[] pcm = buildPcm(tail);
if (pcm.length == 0) {
byte[] speech = buildPcm(tail);
if (speech.length == 0) {
w("没有可用的语音种子", tail);
return;
}
playPcm(pcm, tail);
byte[] body = beepFirst ? prependBeep(speech) : speech;
// 前后垫静音:起播(/收尾)会吃掉开头一小段,垫了静音就只吃静音,
// 不会把蜂鸣或第一位数字吞掉
byte[] pcm = padSilence(body, LEAD_IN_MS, TAIL_MS);
playPcm(pcm, beepFirst ? "beep+" + tail : tail);
}
});
}
/** 前后补静音(调用方已在 speech 线程) */
private static byte[] padSilence(byte[] pcm, int leadMs, int tailMs) {
int leadBytes = SAMPLE_RATE * Math.max(0, leadMs) / 1000 * BYTES_PER_FRAME;
int tailBytes = SAMPLE_RATE * Math.max(0, tailMs) / 1000 * BYTES_PER_FRAME;
if (leadBytes == 0 && tailBytes == 0) {
return pcm;
}
byte[] padded = new byte[leadBytes + pcm.length + tailBytes];
System.arraycopy(pcm, 0, padded, leadBytes, pcm.length);
return padded;
}
/** 把蜂鸣 PCM 拼到语音前面(调用方已在 speech 线程) */
private byte[] prependBeep(byte[] speech) {
byte[] beep = beepPcm();
if (beep.length == 0) {
return speech;
}
byte[] merged = new byte[beep.length + speech.length];
System.arraycopy(beep, 0, merged, 0, beep.length);
System.arraycopy(speech, 0, merged, beep.length, speech.length);
return merged;
}
/** 蜂鸣 PCM(方波 + 尾部静音),只生成一次 */
private byte[] beepPcm() {
synchronized (lock) {
if (beepCache != null) {
return beepCache;
}
}
int frames = SAMPLE_RATE * BEEP_MS / 1000;
int gapFrames = SAMPLE_RATE * BEEP_GAP_MS / 1000;
byte[] pcm = new byte[(frames + gapFrames) * BYTES_PER_FRAME];
int halfPeriod = Math.max(1, SAMPLE_RATE / Math.max(1, BEEP_FREQ_HZ) / 2);
int fadeFrames = Math.max(1, SAMPLE_RATE / 1000); // 1ms 淡入淡出,去掉爆音
double amplitude = Short.MAX_VALUE * BEEP_AMPLITUDE;
int offset = 0;
for (int index = 0; index < frames; index++) {
double value = ((index / halfPeriod) & 1) == 0 ? amplitude : -amplitude;
int remaining = frames - 1 - index;
if (index < fadeFrames) {
value = value * index / fadeFrames;
}
else if (remaining < fadeFrames) {
value = value * remaining / fadeFrames;
}
short sample = (short) Math.max(Short.MIN_VALUE, Math.min(Short.MAX_VALUE, Math.round(value)));
for (int channel = 0; channel < CHANNELS; channel++) {
pcm[offset++] = (byte) (sample & 0xFF);
pcm[offset++] = (byte) ((sample >> 8) & 0xFF);
}
}
// 剩余的是静音间隔(数组默认 0)
synchronized (lock) {
beepCache = pcm;
}
return pcm;
}
private void playPcm(byte[] pcm, String label) {
Context ctx = context;
if (ctx == null) {
@ -236,6 +335,9 @@ public final class BarcodeSpeaker {
.build());
created.setDataSource(file.getAbsolutePath());
created.prepare();
// 明确拉满音量:有些 ROM 会在新音频流起播时做淡入/被别的流压一点音量,
// 显式设置后至少不会被我们自己的上一个播放残留影响
created.setVolume(1f, 1f);
final int myGeneration;
MediaPlayer oldPlayer;
@ -262,8 +364,14 @@ public final class BarcodeSpeaker {
});
}
releasePlayer(oldPlayer, oldFile);
created.start();
// 先起播,再收掉上一句:反过来的话上一句一出流,音频输出通道被拆,
// 新的一句紧跟着起播就会被吃掉开头(表现为第一位数字听不到)。
try {
created.start();
}
finally {
releasePlayer(oldPlayer, oldFile);
}
long durationMs = pcm.length * 1000L / (SAMPLE_RATE * BYTES_PER_FRAME);
i("语音播报", label, durationMs + "ms");

View File

@ -1,8 +1,11 @@
package com.gztbyc.scancenter.receiver;
import android.app.AlarmManager;
import android.app.PendingIntent;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.os.Build;
import com.gztbyc.scancenter.MainActivity;
@ -23,6 +26,11 @@ import static com.gztbyc.scancenter.util.L.w;
* 所以清单里静态注册仍然有效。</li>
* </ul>
*
* <p>为什么要「补几次」:实测 G96max H616 这类电视盒子,开机时<strong>系统桌面会晚一步</strong>
* 起来,把刚拉起的主界面顶到后台(日志里能看到 `BootReceiver` 成功拉起,但前台变成
* `com.swe.dgbluancher`)。所以启动后再用 {@link AlarmManager} 定时补两次,
* 把界面抢回前台 —— 界面上只有一个状态页,重复拉起是幂等的(singleTop)。
*
* <p>⚠️ 应用<b>新装且从未启动过</b>时处于 stopped 状态,系统不会给它发开机广播,
* 必须手动启动一次之后才会生效。这是 Android 的既定行为,不是 bug。
*/
@ -32,10 +40,21 @@ public class BootReceiver extends BroadcastReceiver {
private static final String ACTION_QUICKBOOT = "android.intent.action.QUICKBOOT_POWERON";
private static final String ACTION_HTC_QUICKBOOT = "com.htc.intent.action.QUICKBOOT_POWERON";
/** 自己给自己排的「再切一次前台」闹钟 */
private static final String ACTION_RELAUNCH = "com.gztbyc.scancenter.action.RELAUNCH";
/** 开机后多久补一次前台(毫秒);0 = 立即 */
private static final long[] RELAUNCH_DELAYS_MS = { 6000L, 15000L };
@Override
public void onReceive(Context context, Intent intent) {
String action = intent == null ? "" : intent.getAction();
if (ACTION_RELAUNCH.equals(action)) {
launch(context, "补切前台");
return;
}
if (!Intent.ACTION_BOOT_COMPLETED.equals(action)
&& !ACTION_QUICKBOOT.equals(action)
&& !ACTION_HTC_QUICKBOOT.equals(action)) {
@ -43,17 +62,51 @@ public class BootReceiver extends BroadcastReceiver {
}
i("收到开机广播,准备自启动", action);
launch(context, "开机");
for (long delay : RELAUNCH_DELAYS_MS) {
schedule(context, delay);
}
}
private void launch(Context context, String reason) {
try {
Intent launch = new Intent(context, MainActivity.class);
// 从 Receiver 启动 Activity 必须带 NEW_TASK,否则直接抛异常
launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
// 从桌面/别的界面抢回前台时,用 REORDER_TO_FRONT 不会重建界面
launch.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
context.startActivity(launch);
i("开机自启动已拉起设备端主界面");
i("开机自启动已拉起设备端主界面", reason);
}
catch (Exception error) {
// 自启动失败不该让进程崩掉:用户手动点图标仍然能进
w("开机自启动失败,需要手动启动应用");
w("开机自启动失败,需要手动启动应用", reason);
e("开机自启动异常", error);
}
}
/** 用闹钟延迟再拉起一次(进程被杀也能触发,比 Handler 稳) */
private void schedule(Context context, long delayMs) {
try {
AlarmManager alarm = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE);
if (alarm == null) {
return;
}
Intent intent = new Intent(context, BootReceiver.class).setAction(ACTION_RELAUNCH);
PendingIntent pending = PendingIntent.getBroadcast(
context, (int) delayMs, intent, PendingIntent.FLAG_UPDATE_CURRENT);
long at = System.currentTimeMillis() + delayMs;
if (Build.VERSION.SDK_INT >= 23) {
alarm.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, at, pending);
}
else {
alarm.setExact(AlarmManager.RTC_WAKEUP, at, pending);
}
}
catch (Exception error) {
w("排补切前台闹钟失败", delayMs);
e("补切前台闹钟异常", error);
}
}
}

View File

@ -152,6 +152,77 @@
android:textSize="14sp" />
</LinearLayout>
<!-- 开机 / 桌面(kiosk) -->
<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:background="@drawable/bg_card"
android:orientation="vertical"
android:padding="20dp">
<TextView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/settings_section_home"
android:textColor="@color/text_primary"
android:textSize="18sp"
android:textStyle="bold" />
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="10dp"
android:text="@string/settings_home_hint"
android:textColor="@color/text_secondary"
android:textSize="14sp" />
<TextView
android:id="@+id/tv_home_status"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="10dp"
android:textColor="@color/text_primary"
android:textSize="16sp" />
<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="14dp"
android:orientation="horizontal">
<Button
android:id="@+id/btn_set_home"
style="@style/ActionButton"
android:text="@string/settings_action_set_home" />
<Button
android:id="@+id/btn_clear_home"
style="@style/ActionButton"
android:layout_marginStart="12dp"
android:text="@string/settings_action_clear_home" />
<Button
android:id="@+id/btn_free_launcher"
style="@style/ActionButton"
android:layout_marginStart="12dp"
android:text="@string/settings_action_back_to_launcher" />
<Button
android:id="@+id/btn_system_settings"
style="@style/ActionButton"
android:layout_marginStart="12dp"
android:text="@string/settings_action_system_settings" />
</LinearLayout>
<TextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="10dp"
android:text="@string/settings_home_clear_hint"
android:textColor="@color/text_secondary"
android:textSize="14sp" />
</LinearLayout>
<!-- 当前状态 -->
<LinearLayout
android:layout_width="match_parent"

View File

@ -14,14 +14,17 @@
<string name="main_label_total">累计扫码</string>
<string name="main_version_value">%1$s · %2$s</string>
<string name="main_total_value">%1$d 条</string>
<string name="main_total_value_remote">%1$d 条 · 面单 %2$d</string>
<string name="main_service_running">运行中 · TCP %1$d · 已连接 %2$d</string>
<string name="main_service_failed">启动失败:%1$s</string>
<string name="main_discovery_running">运行中 · UDP %1$d</string>
<string name="main_discovery_failed">启动失败:%1$s</string>
<string name="main_waiting">等待扫码…</string>
<string name="main_last_time">扫码时间:%1$s</string>
<string name="main_recent_title">最近扫码</string>
<string name="main_last_time_camera">面单摄像头识别:%1$s</string>
<string name="main_recent_title">最近扫码(面单 = 面单摄像头识别)</string>
<string name="main_recent_empty">暂无扫码记录</string>
<string name="main_recent_remote_tag">[面单]</string>
<string name="main_hint">请使用 USB 扫码枪扫描条码</string>
<string name="main_action_settings">服务设置</string>
<string name="main_action_clear">清空记录</string>
@ -46,6 +49,28 @@
<string name="settings_discovery_enabled">允许被桌面端发现</string>
<string name="settings_note">桌面端会在局域网内自动发现本机,并连接上面的扫码服务端口读取 USB 扫码枪结果。\n默认:TCP 8087 / UDP 48899。修改后请与桌面端约定保持一致。</string>
<string name="settings_section_status">当前状态</string>
<string name="settings_section_home">开机 / 桌面</string>
<string name="settings_home_hint">部分电视盒子禁止应用在后台拉起界面(开机广播收到了也切不到前台)。把本应用设为盒子桌面后,开机会由系统直接进入扫码界面。</string>
<string name="settings_home_is_default">扫码终端(开机会直接进入本界面)</string>
<string name="settings_home_not_default">盒子自带桌面(开机后需要手动点开本应用;点下面按钮可设为默认桌面)</string>
<string name="settings_home_unsupported">当前系统版本不支持一键设置,请到「设置 → 应用 → 默认应用 → 主屏幕应用」里选择本应用</string>
<string name="settings_action_set_home">设为默认桌面</string>
<string name="settings_action_clear_home">解除默认桌面</string>
<string name="settings_action_back_to_launcher">回到盒子桌面</string>
<string name="settings_action_system_settings">打开系统设置</string>
<string name="settings_home_clear_hint">解除时打开系统「主屏幕应用」选择页,选回盒子自带桌面即可(解除后本应用不再开机自动进入)。</string>
<string name="settings_home_clear_opened">已打开系统「主屏幕应用」选择页,请选回盒子自带桌面</string>
<string name="settings_home_settings_missing">这台系统没有「主屏幕应用」设置页,已改开系统设置,请到 应用 → 默认应用 → 主屏幕应用 里选</string>
<string name="settings_clear_home_title">解除默认桌面</string>
<string name="settings_clear_home_message">安卓不允许应用自己取消「默认桌面」,只能走系统页面或卸载。\n\n① 打开系统「主屏幕应用」页 → 选回盒子自带桌面(个别盒子这个页面会闪退,比如 G96max H616);\n② 卸载本应用 → 桌面角色自动释放,盒子回到自带桌面(需要扫码终端时重新安装即可);\n③ 临时用一下盒子桌面 → 点上面的「回到盒子桌面」,不改默认设置。</string>
<string name="settings_clear_home_open_settings">打开系统页面</string>
<string name="settings_clear_home_uninstall">卸载本应用</string>
<string name="settings_clear_home_cancel">取消</string>
<string name="settings_no_other_launcher">这台机器上没找到其它桌面应用</string>
<string name="settings_back_to_launcher_done">已切到盒子自带桌面(默认桌面设置未改)</string>
<string name="settings_home_requested">请在系统弹窗里点「允许」</string>
<string name="settings_home_done">已设为默认桌面</string>
<string name="settings_home_failed">打开系统设置页失败:%1$s</string>
<string name="settings_status">MAC %1$s · IP %2$s\n扫码服务:%3$s\n设备发现:%4$s</string>
<string name="settings_save">保存</string>
<string name="settings_back">返回</string>

View File

@ -40,7 +40,10 @@ packService/
| --- | --- | --- |
| 前端 SPA(用户端,toC:用户只管自己的设备/记录) | `Authorization: Bearer <user JWT>`(typ=user) | `/api/web/*`(登录/资料/设备/记录) |
| 设备(扫描枪、中控) | `Authorization: Bearer <device JWT>`(typ=scanner) | `/api/device/login`、`/api/scanner/*`、`/api/scan/*` |
| 公开 | 无 | `/api/wechat/{login,status,qrcode.svg}`、`/api/web/auth/*` |
| 公开 | 无 | `/api/wechat-gateway/notify`(网关回调,**靠签名**)、`/api/wechat-gateway/qrcode.{svg,gif}`、`/api/wechat/{status,qrcode.svg}`(设备扫码登录的登录码)、`/api/web/auth/*` |
扫码登入用到的 `WX_GATEWAY_*` 只配在**服务端**(appSecret 绝不能进前端/二维码):服务端申请二维码、验签收网关回调,
前端只负责显示二维码和长轮询结果。
前端**不用 cookie/session**:令牌存本地、放 header,所以没有跨域 cookie 与 CSRF 的问题
(JWT 用 `typ` 声明隔离:用户令牌调设备接口一律 401)。
@ -49,13 +52,34 @@ packService/
- [x] 目录拆分为 `backend/` + `frontend/`
- [x] 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通 `/api/web/auth/*`
- [x] 小程序脚手架 `miniprogram/`(uni-app + Vue3 + TS):微信一键登录(code2Session)+ 账号登录双 tab / 首页统计 / 扫码记录 / 个人中心;登录前需阅读并同意协议(版本落库);不强制登录(启动不弹窗,点功能或 401 才提示,符合小程序审核)
- [x] 小程序脚手架 `miniprogram/`(uni-app + Vue3 + TS):账号密码登录 / 首页统计 / 扫码记录 / 个人中心;登录前需阅读并同意协议(版本落库);不强制登录(启动不弹窗,点功能或 401 才提示,符合小程序审核)
- [x] 浏览器扩展 `extension/`(MV3,零构建):注入第三方 WMS 页面,在运单号**旁边**渲染「查看打包视频」按钮 → 点按钮打开溯源页
- [x] **后端去掉服务端渲染**:删除 `app/controller/page/`、`app/view/`、`app/lib/page.js`、nunjucks / session / CSRF 配置与依赖,后端只剩 JSON 接口
- [x] 页面全部迁移到前端:登录 / 注册 / 找回密码 / 扫码 / 扫码确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页(仅开发构建,生产不打包)
- [x] 后端 dev 反代前端(`app/middleware/frontend.js`);生产由 nginx 直接托管前端构建产物(Egg 只提供 API)
- [x] 运维接口加鉴权:`app/controller/admin/` → `internal/`,统一挂 `middleware.internalAuth()`
- [x] 新增用户端接口:`/api/web/{stats,devices*,records,test/*}`(范围一律限定在令牌对应的那个用户)
- [x] 工作台成员登录(2026-10-24):成员扫码登入(是主体成员记工号/姓名,否则记昵称);
「成员」弹窗看当前/历史成员、手动下线、一键全部下线;扫码上报刷新最后活跃时间,超过设置(团购 1h / 散单 30min)由定时任务自动下线;
运单查询(`/api/web/pack-query`)每条记录带上当时的打包人员 `packers`
- [x] **对接微信登录网关(2026-10-28)**:扫码登录 / 绑定微信 / 工作台扫码登入统一走
[gateway.gztbyc.com](https://gateway.gztbyc.com/#/docs)(申请临时码 → 本地画二维码 → 手机微信确认 → 网关带签名回调);
- **废弃自建登录码**:登录页的 6 位扫码串码(`GET /api/wechat/login`)与工作台的 `WSC-` 登录码都已删除,
二维码改为**按需生成、一次有效**;
- **个人中心新增「微信绑定」**:扫码绑定/解绑;绑定后可直接用微信扫码登录,也能扫码登入工作台;
- **主体成员改为「扫码绑定」**:管理员出二维码 → 成员用微信扫码 → 微信已有平台账号的直接继承(自动建的临时账号删掉),
还没有账号的由服务端自动给这名成员建号并把微信绑成它的登录方式;旧的 6 位绑定码与 `/wechat?bind=<码>` 手机确认页已删除;
绑错了可以「解除绑定」重来;
- 配置见 `WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET`(不配则扫码入口提示「未开通」),
网关管理台的「服务端通知地址」要配成 `https://<域名>/api/wechat-gateway/notify`
- [x] **移除自建的微信授权表(2026-10-29)**:微信侧接入收敛到登录网关后,删除 `wechat_oauth`(公众号网页授权)与
`wechat_mp_accounts`(小程序一键登录)两张表及其代码/接口/环境变量;小程序改为账号密码登录
(详见 [`backend/README.md`](backend/README.md) 的「已下线:小程序微信一键登录」)
- [x] **平台管理员 + 平台管理台(2026-10-29)**:新表 `admin_members`(平台管理员名单,`INTERNAL_ADMIN_IDS` 为内置/救急入口);
平台管理员登录后左侧菜单多出「平台管理」:**主体管理**(所有主体 + 直接改授权到期时间:选时间或顺延)、
**订单管理**(所有订单 + 确认订单 = 支付回调的同一套后续动作)、**管理员**(成员列表 + 按账号添加/移除)
- [x] **顶栏下载入口(2026-10-29)**:所有页面右上角都有「桌面端 / Android 扫码台」下载按钮(**不看权限**),
版本号读 `/download/version.json` 与 `/download/android_client/version.json`,没发布过安装包时按钮置灰
- [ ] 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址
后端接口细节见 [`backend/README.md`](backend/README.md),扩展用法见 [`extension/README.md`](extension/README.md),小程序用法见 [`miniprogram/README.md`](miniprogram/README.md)。
@ -68,10 +92,11 @@ packService/
- ⚠️ 外层**不要用 `align-items: center`**:卡片比视口高时顶部会被裁掉且滚不上去 —— 用 `.bare-card { margin: auto }` 让它在容器里自己居中,`overflow-y: auto` 兜底;
- **表单字段不用 `<label>`**(会把卡片撑高):字段名写进 `placeholder`,「必填 + 说明」用**悬浮气泡** `.field-plain > .tip`(`position: absolute` + `opacity/visibility`,hover 或聚焦时才显示,**不参与布局**,所以显不显示都不改变页面高度);
- **登录页版面**:登录 ⇄ 注册用表单底部的**文字链接**互换(不放按钮);**扫码**面板由右上角三角形 `.corner-toggle` 切换,且**只在登录 ↔ 扫码之间**(**注册面板不显示三角**);三角形挂在**卡片**上(`.card.bare-card` 设 `position: relative` + `overflow: hidden`,让它的直角被卡片圆角裁掉),`.panel-switch.is-login` / `.is-wechat` 给 `padding-top: 18px` + `min-height: 282px`(卡片自身 padding 20 + 18 = 38,正好让开三角)→ 登录与扫码**同高、同位置**,来回切不跳;扫码面板只有二维码 + **「使用微信扫码登录」**一行字;
- 扫码面板**只放二维码 + 返回入口**,不要写说明文字;二维码是后端本地画的 SVG(`/api/wechat/qrcode.svg?code=…`,**没有任何外链资源**);
- 扫码面板**只放二维码 + 返回入口**,不要写说明文字;二维码是后端本地画的 SVG(登录页 `/api/wechat-gateway/qrcode.svg?state=…`,设备扫码登录 `/api/wechat/qrcode.svg?code=…`,**没有任何外链资源**);
- 三角形只在自己那块折角区域可点(`clip-path` 把命中区一起裁了)→ 自动化点击要点在折角内(如 right-10 / top+10),点元素中心会落空;
- **注册字段顺序固定**:用户名 → 邮箱 → 邮箱验证码(右侧「获取验证码」按钮,同一行 `.input-row`)→ 密码 → 重复密码;单列排布、没有步骤小标题、不收昵称/手机号;
- **后台页(测试页 / 个人中心)的表单**保留 `label + placeholder` 的写法(字段多、需要一直可见),列表页与表单页共用 `.card`(卡片间距由 `.card + .card` 统一);
- **网格里的卡片要清掉 `.card + .card` 的间距**:全局 `.card + .card { margin-top: 16px }` 只适合单列堆叠;放进 `display: grid` 的容器里会把第 2 张之后的卡片整体下推 16px,看起来就是「卡片高度/位置不一致」。网格内用 `gap` 排版,并写 `.你的网格 > .card { margin-top: 0 }`(首页 `.stat-grid` / `.charts` 就是这么做的,另外 `grid-auto-rows: 1fr` 保证换行后的每一行也等高);
- **列表页**(设备管理 / 扫码记录)用 `<AppLayout fill>`:内容区不滚动、卡片吃掉剩余高度、只有 `.table-wrap` 内部滚动(表头 `position: sticky` 吸顶、分页条贴在卡片底部);表单/详情页不传 `fill`,滚动落在内容区,侧边栏底部始终可见;
- **接口调用**一律走 `api/client.ts`(自动带 `Authorization: Bearer`、401 自动清令牌)+ `api/web.ts`;**不用 cookie/session,也就不需要 CSRF**;
- **扫码头像期**:前端要自己设客户端超时(服务端挂 60s,客户端 70s),切走面板 / 离开页面(`pagehide`)时要 `abort()` 长轮询 —— 后端会立刻停止等待(见 `backend/README.md` 长轮询一节)。
@ -98,5 +123,7 @@ npm run build # typecheck + vite build(产物 dist/,发布时由 nginx
| `INTERNAL_ADMIN_IDS` | `1` | 哪些用户 id 能调运维接口(逗号分隔) |
| `SITE_URL` | 空 | 二维码 / 邮件里链接用的绝对域名(不配则用请求的 host) |
| `VITE_PORT` / `VITE_BACKEND` | `7301` / `http://127.0.0.1:7300` | 前端 dev 端口 / 代理目标 |
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | 微信登录网关地址 |
| `WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET` | 空 | 网关应用的 appKey / appSecret(**只配服务端**);不配则扫码相关接口返回 503 |
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。

View File

@ -31,17 +31,20 @@ packService/backend
│ │ ├── web/ # **用户端(前端 SPA)**:user JWT(typ=user),只能动自己的数据
│ │ │ ├── auth.js # /api/web/auth/{login,register,register/code,forgot,reset}
│ │ │ ├── profile.js # /api/web/me [/password] 我的资料 / 改密码
│ │ │ ├── stats.js # /api/web/stats 首页统计(按当前用户)
│ │ │ ├── stats.js # /api/web/stats 首页统计(今日/昨日/近 N 天)
│ │ │ ├── device.js # /api/web/devices* 我的设备(列表/详情/通道/解绑/删除)
│ │ │ ├── record.js # /api/web/records 我的扫码记录(按自己设备过滤)
│ │ │ ├── admin_member.js # /api/web/admin/members[/:id]、/me 平台管理员名单(❗需平台管理员)
│ │ │ ├── admin_subject.js # /api/web/admin/subjects[/:id] 所有主体 + 改授权到期时间
│ │ │ ├── admin_order.js # /api/web/admin/orders[/:orderNo/confirm] 所有订单 + 确认订单
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口(仅非生产环境注册)
│ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面)
│ │ │ ├── user.js # /api/users* 用户 CRUD(含缓存)
│ │ │ ├── wechat.js # /api/wechat/:appid/:openid、bind、tokens、解绑、用户的授权列表
│ │ │ ├── wechat.js # /api/internal/wechat-bindings* 网关绑定排查 / 强制解绑
│ │ │ ├── config.js # /api/configs* 系统配置读写
│ │ │ └── device.js # /api/scanners*、/api/scanner/{bind,unbind} 设备列表/详情/解绑/删除
│ │ ├── auth/ # 公开的登录接口(发码 / 查码 / 微信回调,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{login,status,qrcode.svg,callback}
│ │ ├── auth/ # 公开的登录接口(发码 / 查码,无需令牌)
│ │ │ └── wechat.js # /api/wechat/{status,qrcode.svg} 设备扫码登录的码
│ │ ├── client/ # 小程序 / Win 客户端 / SPA(user JWT,typ=user)
│ │ │ └── wechat.js # /api/wechat/confirm
│ │ └── device/ # 设备(长期 JWT,typ=scanner)
@ -51,21 +54,23 @@ packService/backend
│ ├── middleware
│ │ ├── api_auth.js # **用户端接口鉴权(只认 header 令牌,不看 cookie/session)**
│ │ ├── internal_auth.js # **运维/内部接口鉴权**(X-Internal-Token 或白名单账号的 user JWT)
│ │ ├── platform_admin.js # **平台管理员校验**(admin_members 启用 / INTERNAL_ADMIN_IDS;给 /api/web/admin/*)
│ │ ├── scanner_auth.js # 扫描器 JWT 鉴权(Authorization: Bearer <token>)
│ │ ├── frontend.js # **前端入口**:dev 反代前端 dev server / 生产托管 frontend/dist(SPA 回退)
│ │ └── error_handler.js # 异常统一成 JSON(4xx 原消息 / 5xx 只回「服务器内部错误」)
│ ├── model
│ │ ├── user.js # users
│ │ ├── wechat_oauth.js # wechat_oauth
│ │ ├── admin_member.js # admin_members(平台管理员)
│ │ ├── sys_config.js # sys_config
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ └── scan_record.js # scan_records(去重)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
│ │ ├── admin_member.js # 平台管理员:名单维护 + isAdmin(admin_members / INTERNAL_ADMIN_IDS)
│ │ ├── mail.js # 发邮件(邮箱验证码 / 重置密码链接;开发模式只写日志)
│ │ ├── verify_code.js # 邮箱验证码:生成/发送/校验/消费(Redis 存储 + 重发节流)
│ │ ├── wechat_login.js # 微信扫码登录:二维码本地生成 / 扫码状态机 / code 换 openid
│ │ ├── wechat_login.js # 设备扫码登录:二维码本地生成 / 串码状态机 / 长轮询
│ │ ├── password_reset.js # 找回密码:重置令牌生成/校验/消费(Redis 存摘要 + 旧链接失效 + 重发节流)
│ │ ├── cache.js # Redis 封装(JSON 序列化 / 过期 / cache-aside / 降级)
│ │ ├── config.js # 配置读写(带 Redis 缓存)
@ -74,7 +79,7 @@ packService/backend
│ │ ├── scan.js # 中控通道上报 / 扫码入库去重 / 扫码查询
│ │ ├── health.js # MySQL / Redis 连通性探测
│ │ ├── user.js # 用户数据访问(app.model.User)
│ │ └── wechat.js # 微信授权数据访问
│ │ └── wx_gateway.js # 微信登录网关:临时码 / 验签 / 会话长轮询 / 绑定关系
│ └── router.js
├── config
│ ├── config.default.js # 统一配置(连接 / 端口 / 安全 / 前端入口 / 内部鉴权)
@ -341,6 +346,17 @@ npm run android:publish -- --skip-nginx
下载地址:`<androidBaseUrl>/download/android_client/YuncangScan-<版本>.apk`
更新信息:`<androidBaseUrl>/download/android_client/version.json`
### 前端顶栏的下载入口(2026-10-29)
网页端**所有页面**的右上角都有两个下载按钮(`frontend/src/components/AppLayout.vue`,**与权限无关**,登录后就能看到):
- 「桌面端 vX.Y.Z」→ `version.json` 里的 `downloadUrl`(MSI)
- 「Android 扫码台 vX.Y.Z」→ `version.json` 里的 `downloadUrl`(APK)
版本信息由 `frontend/src/api/download.ts` 直接 `fetch` 两个 `version.json`(**注意:这两个路径返回的是
`version.json` 原文,不是 `{ ok, data }` 包装**,所以没走 `api/client`);还没发布过安装包时按钮置灰、点击提示,
不会跳到 404。nginx 里这两个路径是精确 `location` 反代到 Egg 的,安装包目录才是静态托管。
## 单元测试
@ -395,16 +411,16 @@ npm run cov
| `EMAIL_DAILY_LIMIT` | `10` | **每个邮箱每天最多发几封邮件**(注册验证码 + 找回密码共用,超出提示「明天再试」) |
| `EMAIL_RESET_TTL` | `1800` | 重置密码链接有效期(秒,默认 30 分钟) |
| `SITE_URL` | 空 | 邮件里重置链接的站点地址(如 `https://packs.example.com`);不配则用当前请求的 host |
| `WECHAT_APPID` | 空 | 微信开放平台网站应用 appid;**不配时登录页二维码退化为本地演示码**(不会假装能用) |
| `WECHAT_SECRET` | 空 | 同上对应的 appsecret |
| `WECHAT_REDIRECT_URI` | 空 | 扫码回调地址(需与开放平台后台配置一致);不配则按当前请求 origin 拼 `/login/wechat/callback` |
| `WECHAT_API_BASE` | `https://api.weixin.qq.com` | 微信接口域名(自建网关/联调时可改) |
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | **微信登录网关**地址(登录页扫码 / 绑定微信 / 工作台扫码登入) |
| `WX_GATEWAY_APP_KEY` | 空 | 网关应用的 appKey(`gwk_…`);**不配 = 未开通**,扫码接口 503 |
| `WX_GATEWAY_APP_SECRET` | 空 | 网关应用的 appSecret(`gws_…`),**只放服务端**(验证回调签名) |
| `WX_GATEWAY_POLL_WAIT` / `WX_GATEWAY_SCENE_TTL` / `WX_GATEWAY_NOTIFY_SKEW` | `55` / `660` / `300` | 网关扫码的长轮询上限(秒)/ 本地会话有效期(秒)/ 通知时间戳容差(秒) |
| `WECHAT_QR_CELL` / `WECHAT_QR_MARGIN` | `6` / `4` | 二维码 SVG 的单元格像素 / 静默区格数(⚠️ 库的 margin 参数单位是像素,代码里已按格×单元格换算;<4 格会影响扫码) |
| `WECHAT_STATE_TTL` | `600` | 扫码串码(二维码)有效期(秒) |
| `WECHAT_STATE_TTL` | `600` | 扫码串码(二维码)有效期(秒)——设备扫码登录用 |
| `WECHAT_CODE_LENGTH` | `6` | 扫码串码长度(数字 + 大写字母,去掉了 0/O/1/I 等易混字符) |
| `WECHAT_SPM_PATTERN` | `1.0.{code}.1` | 二维码地址里的 spm 格式(`{code}` 会被替换成串码) |
| `USER_JWT_EXPIRES` | `7d` | 扫码登录接口下发的**用户 JWT** 有效期 |
| `WECHAT_POLL_WAIT` | `60` | 扫码登录接口长轮询最多挂起多少秒(前端自己的超时建议再 +10s;反代注意 `proxy_read_timeout` 要大于它) |
| `WECHAT_POLL_WAIT` | `60` | 设备扫码登录的长轮询最多挂起多少秒(前端自己的超时建议再 +10s;反代注意 `proxy_read_timeout` 要大于它) |
Windows PowerShell 示例:
@ -434,25 +450,6 @@ $env:MYSQL_PASSWORD = 'your-pass'; $env:REDIS_PASSWORD = 'your-pass'; npm run de
| password_changed_at | datetime | 最近一次设置/重置密码的时间(可空);**签发时间早于它的 user JWT 立即失效** |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
### wechat_oauth 微信授权表
一条记录 = 某用户在某 `appid` 下的一次授权,**一个用户可绑定多个微信**。
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | bigint unsigned | 主键 |
| user_id | bigint unsigned | 关联 `users.id` |
| appid | varchar(64) | 微信 appid,与 openid 组成唯一键 |
| openid | varchar(64) | 用户在该 appid 下的 openid |
| unionid | varchar(64) | 开放平台 unionid |
| nickname / avatar | varchar | 授权时的微信资料 |
| session_key | varchar(128) | 小程序 session_key |
| access_token / refresh_token | varchar(512) | 网页授权令牌 |
| scope | varchar(64) | 授权 scope |
| token_expires_at | datetime | access_token 过期时间 |
| last_auth_at | datetime | 最近授权时间 |
| created_at / updated_at / deleted_at | datetime | 时间戳与软删除 |
### sys_config 系统配置表
`group_name` + `config_key` 唯一定位一条配置,`value_type` 决定 `config_value` 的解析方式(`string` / `number` / `boolean` / `json`)。
@ -594,10 +591,10 @@ node scripts/backfill-snapshot.js --dry-run
| 页面 | 前端路由 | 用到的接口 |
| --- | --- | --- |
| 登录 / 注册 / 扫码 | `/login` | `/api/web/auth/*`、`/api/wechat/{login,status,qrcode.svg}` |
| 登录 / 注册 / 扫码 | `/login` | `/api/web/auth/*`、`/api/web/auth/wechat-gateway/*` |
| 手机确认登录 | `/wechat?spm=…` | `/api/wechat/confirm` |
| 忘记 / 重置密码 | `/forgot`、`/reset` | `/api/web/auth/{forgot,reset}` |
| 首页统计 | `/` | `/api/web/stats` |
| 首页统计 | `/` | `/api/web/stats`(`?days=7|14|30` 近 N 天;`?period=today|yesterday` 切到今日 / 昨日,趋势变按小时) |
| 设备管理 | `/devices` | `/api/web/devices*` |
| 扫码记录 | `/records` | `/api/web/records` |
| 个人中心 | `/profile` | `/api/web/me*` |
@ -622,18 +619,18 @@ node scripts/backfill-snapshot.js --dry-run
| 调用方 | 控制器目录 | 鉴权 | 典型接口 |
| --- | --- | --- | --- |
| **用户端(前端 SPA)** | `app/controller/web/` | `middleware.apiAuth()`(**user JWT**,typ=user);登录/注册/找回免令牌 | `/api/web/{auth/*,me*,stats,devices*,records,test/*}` |
| **运维 / 内部**(运维脚本、后台系统) | `app/controller/internal/` | `middleware.internalAuth()`(`X-Internal-Token` 或白名单账号的 user JWT) | `/api/users*`、`/api/configs*`、`/api/scanners*`、`/api/scanner/{bind,unbind}`、`/api/wechat/{bind,:id/tokens}` |
| **用户端(前端 SPA)** | `app/controller/web/` | `middleware.apiAuth()`(**user JWT**,typ=user);登录/注册/找回免令牌 | `/api/web/{auth/*,me*,stats,devices*,records,test/*}`;`/api/web/admin/*` 额外要 `middleware.platformAdmin()` |
| **运维 / 内部**(运维脚本、后台系统) | `app/controller/internal/` | `middleware.internalAuth()`(`X-Internal-Token` 或白名单账号的 user JWT) | `/api/users*`、`/api/configs*`、`/api/scanners*`、`/api/scanner/{bind,unbind}`、`/api/internal/wechat-bindings*` |
| **用户态**(小程序 / Win 客户端) | `app/controller/client/` | `middleware.apiAuth()`(**user JWT**,typ=user) | `/api/wechat/confirm` |
| **设备**(扫描枪 / 中控) | `app/controller/device/` | `middleware.scannerAuth()`(**device JWT**,typ=scanner) | `/api/device/login`、`/api/scanner/{me,heartbeat}`、`/api/scan/*` |
| **公开登录接口** | `app/controller/auth/` | 无 | `/api/wechat/{login,status,qrcode.svg,callback}`(`/api/device/login` 的发码也无需凭据) |
| **公开登录接口** | `app/controller/auth/` | 无 | `/api/wechat/{status,qrcode.svg}`、`/api/wechat-gateway/notify`(设备发码 `GET /api/device/login` 也无需凭据) |
| 公共 | `home.js` / `health.js` | 无 | `/api/info`、`/health` |
- **小程序与 Win 客户端共用 `client/` 那一套**:它们身份相同(都是「某个登录用户」),业务接口不该复制两份;要区分用途用 header(如 `X-Client: miniapp|win`)或令牌里的自定义声明,别用路径分叉。
- **令牌层是硬隔离**:`verifyUser()` 只认 `typ: 'user'`(默认 7d),`verifyScanner()` 只认 `typ: 'scanner'`(默认 365d)——用户令牌调设备接口、设备令牌调用户接口都直接 401。
(⚠️ 两个 `verify*` 都必须比对 `typ`:用户令牌与设备令牌用的是同一把密钥,不比对的话用户令牌就能当设备令牌用。)
- **前端只能碰自己的数据**:`/api/web/devices*`、`/api/web/records`、`/api/web/stats` 的过滤条件一律取令牌里的 `userId`,前端传的 `userId`/`deviceId` 越权一概 404(不泄露别人有没有这台设备)。
- **服务层不按调用方分**:`app/service/` 按**领域**拆文件(`scanner` / `scan` / `user` / `config` / `wechat` / `wechat_login` / `jwt` / `cache` / `mail` / `verify_code` / `password_reset`),因为设备与内部接口会共用同一个领域服务(如 `service.scanner` 既被 `device/*` 也被 `internal/device.js` 调用);`app/model/` 按表拆。
- **服务层不按调用方分**:`app/service/` 按**领域**拆文件(`scanner` / `scan` / `user` / `config` / `wechat_login` / `wx_gateway` / `jwt` / `cache` / `mail` / `verify_code` / `password_reset`),因为设备与内部接口会共用同一个领域服务(如 `service.scanner` 既被 `device/*` 也被 `internal/device.js` 调用);`app/model/` 按表拆。
- Egg 支持多级目录:`app/controller/internal/user.js` → `controller.internal.user`(路由里就是这么引用的),`typings/` 会自动重新生成。
| 方法 | 路径 | 说明 |
@ -645,17 +642,14 @@ node scripts/backfill-snapshot.js --dry-run
| POST | `/api/users` | 新增,body: `{"username":"zhangsan","nickname":"张三","phone":"13800000000"}` |
| PUT | `/api/users/:id` | 更新(清除该用户缓存) |
| DELETE | `/api/users/:id` | 软删除(清除该用户缓存) |
| GET | `/api/users/:id/wechats` | 某用户的全部微信授权 |
| GET | `/api/wechat/:appid/:openid` | 按 appid + openid 反查授权与关联用户 |
| POST | `/api/wechat/bind` | 绑定/更新授权,body: `{"userId":1,"appid":"wx123","openid":"o_abc"}` |
| PUT | `/api/wechat/:id/tokens` | 更新 session_key / 令牌,body: `{"sessionKey":"sk","expiresIn":7200}` |
| DELETE | `/api/wechat/:id` | 解绑(软删除) |
| GET | `/api/internal/wechat-bindings?openid=&userId=` | 微信登录网关的绑定关系(含已解绑的)+ 账号状态 |
| DELETE | `/api/internal/wechat-bindings/:id` | **强制解绑**(不校验归属;微信绑在前员工账号上时用) |
| GET | `/api/configs?group=wechat` | 配置列表(管理用,含禁用项) |
| GET | `/api/configs/:group/:key` | 取单个配置值(带 Redis 缓存) |
| GET | `/api/configs/:group` | 取分组内所有启用配置 |
| PUT | `/api/configs` | 新增/更新(幂等),body: `{"groupName":"wechat","configKey":"appid","configValue":"wx123"}` |
| DELETE | `/api/configs/:group/:key` | 软删除(清缓存) |
| GET | `/api/device/login` | **设备「扫码登录 + 注册」**(参考 `/api/wechat/login`,但下发**长期** JWT):**不需要凭据、不需要预先注册**(公开接口);`?sn=`/`name`/`vendor`/`model`/`firmware` 可选(发码时带上最省事,服务端会暂存)、`?expiresIn=30d` 可选(只能比服务端上限短);不带 `code` → 发登录码(`code` / `spm` / **`qrContent`(二维码要编的完整网址)** / `qrImageUrl`(完整地址的 SVG));带 `?code=&wait=N` → 长轮询,手机用 `POST /api/wechat/confirm` 确认后**立即**返回 `{ firstTime, sn, token, expiresIn, expiresAt, refreshToken, refreshExpiresIn, scanner, user }`,**注册/绑定就发生在这一刻**(SN 已属于别人 → 403) |
| GET | `/api/device/login` | **设备「扫码登录 + 注册」**(扫码确认,下发**长期** JWT):**不需要凭据、不需要预先注册**(公开接口);`?sn=`/`name`/`vendor`/`model`/`firmware` 可选(发码时带上最省事,服务端会暂存)、`?expiresIn=30d` 可选(只能比服务端上限短);不带 `code` → 发登录码(`code` / `spm` / **`qrContent`(二维码要编的完整网址)** / `qrImageUrl`(完整地址的 SVG));带 `?code=&wait=N` → 长轮询,手机用 `POST /api/wechat/confirm` 确认后**立即**返回 `{ firstTime, sn, token, expiresIn, expiresAt, refreshToken, refreshExpiresIn, scanner, user }`,**注册/绑定就发生在这一刻**(SN 已属于别人 → 403) |
| POST | `/api/device/refresh` | 用刷新令牌换新访问令牌(**无需访问令牌**):body `{ refreshToken, sn? }` → `{ sn, token, tokenType, expiresIn, refreshToken, refreshExpiresIn, refreshExpiresAt }`;两者都会轮换,旧的立即失效 |
| POST | `/api/scanner/bind` | **管理侧**:把设备绑定到账号,body: `{ sn, username }` 或 `{ sn, userId }` |
| POST | `/api/scanner/unbind` | **管理侧**:解绑,body: `{ sn }`(设备可再扫码重新认领) |
@ -664,10 +658,12 @@ node scripts/backfill-snapshot.js --dry-run
| GET | `/api/scanners?page=&pageSize=&keyword=&userId=&status=` | 设备列表(带绑定账号;管理侧) |
| GET | `/api/scanners/:id` | 扫描器详情 |
| DELETE | `/api/scanners/:id` | 软删除扫描器 |
| POST | `/api/scan/channels` | **需扫描器 JWT**(主体过期/停用 → 403 `subject_expired` / `subject_disabled`):中控上报通道,body: `{ channels: [{ channelId, channelName }], replace?: boolean }`(单条也可)→ `{ created, updated, invalid, errors, removed, unbound }`。`replace: true` = 全量对账:本中控下不在列表里的通道软删并解绑工作台,允许 `channels: []` |
| POST | `/api/scan/channels` | **需扫描器 JWT**(主体过期/停用 → 403 `subject_expired` / `subject_disabled`):中控上报通道,body: `{ channels: [{ channelId, channelName }], replace?: boolean }`(单条也可)→ `{ created, updated, invalid, errors, removed, unbound }`。`replace: true` = 全量对账:本中控下不在列表里的通道软删并解绑工作台,允许 `channels: []`(**虚拟通道 `CAM-` 前缀豁免**,见面单摄像头) |
| GET | `/api/scan/channels?page=&pageSize=&keyword=&status=` | **需扫描器 JWT**:当前中控已登记的通道 |
| POST | `/api/scan/records` | **需扫描器 JWT**(主体过期/停用 → 403 `subject_expired` / `subject_disabled`):中控上报扫码,body: `{ records: [{ barcode, scanTime, channelId }] }` → `{ received, inserted, updated, duplicated, suppressed, invalid, unknownChannels }`(`updated` = 24 小时内同一运单被覆盖为最新扫描时间的条数;`suppressed` = 比库里已有记录更旧、被忽略的条数) |
| GET | `/api/scan/records?page=&pageSize=&channelId=&barcode=&startTime=&endTime=` | **需扫描器 JWT**:当前中控上报的扫码记录 |
| GET | `/api/scanner/label-cameras` | **需扫描器 JWT**:本机该跑的**面单摄像头识别配置** → `{ revision, items, channels, warnings, scannedAt }`。返回本主体、启用中工作台(**散单和团购都支持**)里被设为面单摄像头的绑定;`items[]` 带 `workstationId/Name`、**`wsType`(1 散单 / 2 团购)**、`channelId/Name`(**本机的扫码通道**;工作台没接扫码枪时是**虚拟通道** `CAM-<工作台id>`,见下)、`virtualChannel`(true = 虚拟通道)、`cameraId/Name`、`cameraChannelNo`、`streamType`、`nvr{host,port,username,password}`。`channels[]` 是本机所有被工作台绑定的通道 + `wsType`(含虚拟通道),设备端用它决定**扫码枪**那条路的记录规则(散单取第一次、团购取最后一次)。`revision` 是内容指纹(含密码和通道模式),变了设备端就重建识别任务。RTSP 路径**不在这里拼**(要按录像机「首个数字通道号」换算,只有设备端问得到)。读接口,不挂 `subjectActive` |
| PUT | `/api/web/workstations/:id/cameras/:cameraId/label` | 设置/取消面单摄像头(`{ isLabelCamera: true/false }`,不传按设置)。**散单、团购都可以**;一台工作台最多一路,设新的会先清旧的;取消时顺手清理虚拟通道 |
扫码上报的两个接口都**不会因为重复而报错**(幂等):完全重复的条数计入 `duplicated`,
**同一运单号 24 小时内重复扫描的只保留一条**:时间更新就覆盖(`updated`),更旧的上报忽略(`suppressed`);
@ -693,7 +689,7 @@ node scripts/backfill-snapshot.js --dry-run
```js
// ===== MySQL:Sequelize 模型(定义在 app/model/*.js)=====
// 通过 app.model.User / this.app.model.User / ctx.model.User 访问
const { User, WechatOauth, SysConfig } = this.app.model;
const { User, Scanner, SysConfig } = this.app.model;
await User.findByPk(1); // 主键查询
await User.findOne({ where: { username: 'zhangsan' } });
@ -704,8 +700,8 @@ await User.update({ status: 0 }, { where: { id: 1 } }); //
await User.destroy({ where: { id: 1 } }); // 删除(paranoid 模型 = 软删除)
await User.destroy({ where: { id: 1 }, force: true }); // 物理删除
// 关联查询:一个用户的多条微信授权
const withWechats = await User.findOne({ where: { id: 1 }, include: [{ model: WechatOauth, as: 'wechats' }] });
// 关联查询:一个用户的多台设备
const withScanners = await User.findOne({ where: { id: 1 }, include: [{ model: Scanner, as: 'scanners' }] });
// 原生 SQL / 事务
const [rows2] = await this.app.model.query('SELECT 1 AS ok');
@ -722,10 +718,9 @@ await this.ctx.service.config.set({ groupName: 'wechat', configKey: 'appid', con
const groupConfig = await this.ctx.service.config.getGroup('wechat'); // { appid: 'wx123', ... }
await this.ctx.service.config.remove('wechat', 'appid'); // 软删除 + 清缓存
// ===== 微信授权 =====
await this.ctx.service.wechat.bind({ userId: 1, appid: 'wx123', openid: 'o_abc', nickname: '微信昵称' });
const oauth = await this.ctx.service.wechat.findByOpenid('wx123', 'o_abc'); // 带关联用户
const user = await this.ctx.service.user.findByOpenid('wx123', 'o_abc'); // 直接拿用户
// ===== 微信绑定(网关绑定关系,app/service/wx_gateway.js)=====
const binding = await this.ctx.service.wxGateway.findBinding({ appKey, openid: 'o_abc' }); // 带用户
await this.ctx.service.wxGateway.forceUnbind(12); // 运维强制解绑
// ===== 扫描器长期 JWT(app/service/jwt.js)=====
const jwtToken = this.ctx.service.jwt.signScanner(scanner, { jti: 'uuid' }); // 签发
@ -781,7 +776,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
- **Sequelize 是启动强依赖**:插件在 `beforeStart` 里会 `authenticate()`,连不上数据库时应用启动会失败(重试 3 次后退出);Redis 用 `egg-redis@2`(ioredis),配置了 `client.weakDependent: true`,Redis 不可用不阻塞启动。
- 时间统一按 `timezone: '+08:00'` 处理;表名/字段名下划线映射、created_at/updated_at 命名在 `config.sequelize.define` 中配置。
- 用户/微信授权/系统配置的 `deleted_at` 为软删除:普通查询自动过滤,需物理删除时加 `force: true`。
- `wechat_oauth` 用 `(appid, openid)` 唯一键防重;`sys_config` 的唯一性在 service 层保证(原因见「数据表」一节的说明)。
- `wechat_gateway_bindings` 用 `(app_key, openid)` 唯一键防重;`sys_config` 的唯一性在 service 层保证(原因见「数据表」一节的说明)。
- 所有异常经 `app/middleware/error_handler.js` 处理:`/api/*`、`/health`(或声明了 `Accept: application/json` 的请求)统一返回 `{ ok:false, message }`(4xx 原消息、5xx 只回「服务器内部错误」);其它请求返回一行纯文本(正常情况下它们都被 `middleware/frontend.js` 接走了)。
- **没有模板 / 会话 / CSRF**:`app/view/`、`egg-view-nunjucks`、`egg-session-redis`、`config.view`、`config.session` 全部已删除;接口一律 header 令牌鉴权,`config.security.csrf.enable = false`(没有基于 cookie 的表单了,CSRF 保护已无意义)。
- **前端的页面与样式在 `../frontend/src/`**:公共样式 `styles/main.css`(卡片 / 表单 / 表格 / 分页 / 徽标),每个页面一个 `views/*.vue`;接口调用统一走 `api/client.ts`(自动带令牌、401 清令牌)+ `api/web.ts`(按接口分组)。
@ -814,96 +809,49 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
- 邮件正文由 `service.mail.sendResetLink()` 生成(与验证码同一套开发模式/SMTP 逻辑:未配 `SMTP_HOST` 时链接写日志 + 接口返回 `url`,前端直接给个可点链接,方便本地点开);
- 链接地址默认取当前请求的 host,正式部署建议配 `SITE_URL`(有反代/多域名时更可靠);
- **改密 / 重置密码后旧令牌立即失效(2026-10-17 已做)**:`users` 新增 `password_changed_at`(迁移 `sql/migrations/20261017_add_user_password_changed_at.sql`;老数据为 NULL = 不限制);`service.user.setPassword()`(注册/重置/脚本)与 `auth.changePassword()` 写这个时间;`middleware/api_auth.js` 与 `middleware/internal_auth.js` 比对 JWT 的 `iat`:**iat 秒 < 改密秒 → 401** `{ status:'password_changed', message:'密码已修改,请重新登录' }`(**留 1 秒容差**:改密当秒新签发的令牌仍然可用,避免误杀);
- **扫码登录**(`app/service/wechat_login.js`):前端登录页顶部是「登录 / 注册」两个 tab,**扫码**用右上角的三角形切换(三角形挂在**卡片**右上角,只在登录 ↔ 扫码之间切,注册面板不显示):
- **串码**:服务端生成 **6 位数字 + 字母**随机串码(`WECHAT_CODE_LENGTH`,字符集去掉了 0/O/1/I 等易混字符),写进 Redis `packs:wechat:state:<code>` = `pending`(TTL `WECHAT_STATE_TTL`);
- **二维码内容 = 本站地址**:`http://<域名>/wechat?spm=1.0.<code>.1`(spm 格式由 `WECHAT_SPM_PATTERN` 决定);二维码图片本身用零依赖的 `qrcode-generator` 现场画成 **SVG**(`GET /api/wechat/qrcode.svg?code=…`)——**不需要任何外链资源**;
- **完整时序**(都是我们自己的接口,不需要第三方 JS/iframe):
1. 电脑端调 `GET /api/wechat/login`(不带参数)拿 `code` + `qrUrl`,前端登录页把它画成 `<img src="/api/wechat/qrcode.svg?code=…">` → 串码登记为 `pending`;
2. 手机扫码打开前端路由 `/wechat?spm=1.0.<code>.1`:
- **配了微信** → 前端页重定向到公众号网页授权(`oauth2/authorize`,`scope=snsapi_base` 静默拿 openid,`state=<code>`)→ 微信回调后端 `GET /api/wechat/callback` → `code` 换 `openid`(`WECHAT_API_BASE`)→ 按 `(appid, openid)` 查 `wechat_oauth` 找账号 → 把 Redis 里串码的值改成**用户 id** → 再 302 回前端 `/wechat?ok=1`;
- **没配微信**(本机默认)→ 前端页给「确认登录」按钮:要求手机端**已登录**(本地有占位令牌),点确认调 `POST /api/wechat/confirm`(带 `Authorization: Bearer <user JWT>`)把串码的值改成用户 id;
3. 电脑端用 `GET /api/wechat/login?code=…&wait=60` 长轮询取结果 → `{ status:'confirmed', token, user }` 存本地即登录完成(前端登录页会自动跳首页);**取走即删(一次性)**。
- **JWT 怎么用**:`config.jwt.userExpiresIn`(env `USER_JWT_EXPIRES`,默认 7 天);前端把令牌存 localStorage,调接口时放 `Authorization: Bearer <token>`(`app/middleware/api_auth.js` 只认这个头,不读 cookie/session)。
- **长轮询(前端接口)**:`GET /api/wechat/login?code=<code>&wait=60` —— 服务端把请求挂起最多 `WECHAT_POLL_WAIT` 秒(默认 60):
- 有人扫码确认 → **立即**返回 `{ status:'confirmed', token, … }`(靠 Redis 发布订阅 `packs:wechat:login:<code>` 唤醒,不是忙轮询;`confirm()` / 微信回调写完状态后 `PUBLISH` 一次);
- 到时间还没动静 / 串码已失效 → 返回 `{ status:'refreshed', code:<新码>, spm, qrUrl, expiresIn, waited }` —— **前端直接换二维码继续轮询**,不用自己判断过期;
- `wait=0` 或不传 → 不挂起,只回 `{ status:'pending' }`(短轮询模式);
- **客户端断开就立即结束挂起**(2026-10-17 修):服务端会监听连接关闭(`res.on('close')`),浏览器导航离开(例如登录页点「返回账号密码登录」)、关页签或前端 `abort()` 时立刻停止等待并释放订阅连接,**不会白等满 `wait` 秒,也不会把串码换掉**(登录页的脚本在 `pagehide` 时会 `abort()` 当前请求);日志里能看到 `[wechat] 客户端已断开,停止等待串码 XXXXXX`;
- ⚠️ **前端要自己设超时**(服务端上限 60s,客户端建议 70s):`AbortController` / `AbortSignal.timeout(70000)`,超时就重发一次请求(或退化成短轮询);重启/热更也会断掉长连接,断了重试即可。**反代/网关要把读超时调到 > 60s**(nginx `proxy_read_timeout 90s`),否则会被代理提前切断;
```js
let code = null;
async function loop() {
const url = code ? `/api/wechat/login?code=${code}&wait=60` : '/api/wechat/login';
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 70000); // 前端超时 > 服务端 wait
let r;
try {
r = await (await fetch(url, { signal: ac.signal })).json();
} catch (err) { // 超时/断网 → 重试
return setTimeout(loop, 800);
} finally { clearTimeout(timer); }
const d = r.data;
if (d.status === 'confirmed') return localStorage.setItem('token', d.token);
if (d.status === 'refreshed') { code = d.code; img.src = d.qrUrl; } // 换新码
if (!code) { code = d.code; img.src = d.qrUrl; } // 首次拿码
loop();
}
```
- **联调/自测(三个终端就能跑通整个扫码登录)**:
```bash
# ① 电脑端:拿登录码
curl -s http://127.0.0.1:7300/api/wechat/login
# → {"ok":true,"data":{"code":"XBUBHP","spm":"1.0.XBUBHP.1","qrUrl":"/login/wechat/qrcode.svg?code=XBUBHP",...}}
# ② 电脑端:挂在长轮询上等(25s 内有人确认就立即返回,没人扫就换新码)
curl -s 'http://127.0.0.1:7300/api/wechat/login?code=XBUBHP&wait=60'
# ③ 已登录的客户端(或用手机打开 /wechat?spm=1.0.XBUBHP.1):用登录码触发登录
curl -s -X POST http://127.0.0.1:7300/api/wechat/confirm \
-H 'Authorization: Bearer <用户JWT>' -H 'Content-Type: application/json' \
-d '{"code":"XBUBHP"}'
# → ② 的请求会立即返回 {"data":{"status":"confirmed","token":"<JWT>",...}}
```
`POST /api/wechat/confirm` 的 **鉴权完全走 header**(`app/middleware/api_auth.js`:`Authorization: Bearer <用户JWT>`,也认 `X-Access-Token`)——**不读 session/cookie**,所以小程序 / App / SPA 直接帯令牌就行,也不写 session;它返回 401(缺令牌)/ 403(账号被禁用)/ 422(码格式不对)/ 410(码失效、已过期或已用过);`/api/*` 不过 CSRF,所以 curl 不用带 token。
- **不自动建号**:扫码只对已绑定微信的账号生效(绑定关系在 `wechat_oauth`,可用 `POST /api/wechat/bind` 写入),未绑定会提示先用账号密码登录;账号被禁用(`status != 1`)拒绝登录;
- **小程序接入**(小程序里「扫码 → 直接登录电脑端」):接口都是 JSON,**鉴权只看 header 里的 `Authorization: Bearer <用户 JWT>`,不认 cookie/session**(`app/middleware/api_auth.js`);用户 JWT 用 `USER_JWT_EXPIRES`(默认 7d)控制有效期,由登录接口/扫码登录接口下发。
```js
// 小程序侧:扫登录页上的二维码(内容 http://<域名>/wechat?spm=1.0.<码>.1)
wx.scanCode({
success (scan) {
// ① 先问一下这个码还在不在(可选,但能给出更好的提示)
wx.request({
url: `https://<域名>/api/wechat/status?spm=${encodeURIComponent(scan.result)}`,
success (r) {
// r.data.data.status: pending(待扫)/ confirmed(已被确认)/ expired(没这个码)
}
});
// ② 确认登录:把扫到的整条地址丢进来就行(接口自己抽 6 位码)
wx.request({
url: 'https://<域名>/api/wechat/confirm',
method: 'POST',
header: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + userJwt },
data: { spm: scan.result }, // 也可以传 { code: 'AB12CD' }
success (r) {
if (r.statusCode === 200 && r.data.data.status === 'confirmed') {
wx.showToast({ title: '登录成功' }); // 电脑端那台浏览器已经进系统了
} else {
wx.showToast({ title: r.data.message, icon: 'none' }); // 401/422/410 的错误原因
}
}
});
}
});
```
返回:成功 `HTTP 200 { ok:true, data:{ status:'confirmed', code, spm, user:{ id, username, nickname } } }`;
失败 `HTTP 401 status=unauthorized`(没带/过期令牌)、`422 bad_format`(码格式不对)、`410 expired`(没这个码/已过期)、`410 used`(已被用过);
- **扫码登录(微信登录网关,2026-10-28 起)**:登录页右上角三角形的扫码面板改为对接
[微信登录网关](https://gateway.gztbyc.com/#/docs)。**不再自己发 6 位串码、也不再依赖自家公众号回调**
(旧的 `GET /api/wechat/login` 已删除;`/api/wechat/{qrcode.svg,status}` 只剩**设备扫码登录**在用)。
- **配置**(`config.wxGateway`,全部走 env):`WX_GATEWAY_BASE`(默认 `https://gateway.gztbyc.com`)、
`WX_GATEWAY_APP_KEY` / `WX_GATEWAY_APP_SECRET`(网关管理台建应用时拿,**只放服务端**)、
`WX_GATEWAY_POLL_WAIT`(长轮询上限,默认 55s)、`WX_GATEWAY_SCENE_TTL`(本地会话 TTL,默认 660s)、
`WX_GATEWAY_NOTIFY_SKEW`(通知时间戳容差,默认 300s)、`WX_GATEWAY_TIMEOUT`(调网关超时,默认 8s)。
**不配 appKey/appSecret → 扫码相关接口 503(`未开通微信扫码登录`),前端据此提示**;
- **网关管理台里必须把「服务端通知地址」配成** `https://<本站域名>/api/wechat-gateway/notify`
(= `config.wxGateway.notifyPath`),这是扫码结果回到本站的唯一通道;
- **完整时序**(`service/wx_gateway.js`):
1. 前端 `POST /api/web/auth/wechat-gateway/qrcode` → 服务端向网关 `POST {网关}/api/auth/temp-code`
(header 带 `X-App-Key` / `X-App-Secret`)拿**临时码 + 授权页地址**,同时把「这次扫码要干什么」
写进本地会话(Redis `packs:wxgw:sess:<state>`;`state` 是我们自己的 32 位 hex,原样带给网关);
2. 前端把 `qrUrl`(`/api/wechat-gateway/qrcode.svg?state=…`)当图片显示 —— 二维码**仍然是本地画**
(`qrcode-generator`,零外链资源),内容就是网关给的 `pageUrl`;桌面端(WPF)用同一张图的 GIF 版
(`/api/wechat-gateway/qrcode.gif?state=…`);
3. 用户用**手机微信**扫码 → 网关页点确认 → 网关静默授权(`snsapi_base`)拿 openid →
**带签名 POST** 我们的 `notifyPath`(`event` / `appKey` / `openid` / `bindCode` / `state` / `timestamp` / `nonce` / `sign`);
4. 服务端验签(密钥是 `sha256(appSecret)` 的十六进制,签名串 `appKey.userId.bindCode.timestamp.nonce`;
时间戳偏差 > 5 分钟直接 401)→ 按 `openid` 查 `wechat_gateway_bindings` 找到平台账号 →
把结果写回会话并 `PUBLISH` 唤醒长轮询(验签失败 401;会话已过期返回 **200 + `{ignored:'session_expired'}`**,
免得网关白重试);
5. 前端 `GET /api/web/auth/wechat-gateway/login?state=&wait=55` 拿到 `{ status:'confirmed', token, user }`
—— **令牌是这一步当场签发的**,Redis 里不落令牌;
- **长轮询语义**(`awaitSession()`):`pending`(还在等,继续轮询)/ `confirmed`(成功,**取走即删**)/
`failed`(附 `message`,例如「这个微信还没绑定平台账号」)/ `expired`(会话没了 → 前端重新申请一张继续轮询);
客户端断开(切面板 / 关页签)→ 服务端立刻停止等待(`aborted`,不写响应);前端自己设 70s 超时;
- **不自动建号**:只有「已经绑定微信」的账号能扫码登录;绑定入口在个人中心(见下一条);
- **绑定微信(个人中心,2026-10-28 新增)**:`POST /api/web/me/wechat/qrcode`(需令牌)申请 `scene=bind` 的网关二维码,
手机确认后网关回调 → 写 `wechat_gateway_bindings`:
- `UNIQUE(app_key, openid)`:一个微信只能绑一个账号;同一账号也只留一个微信(换绑要先解绑);
- `GET /api/web/me/wechat/bindings` → `{ list, enabled }`(`enabled=false` = 服务端没配网关,前端整块灰掉);
- `GET /api/web/me/wechat/status?state=&wait=` 长轮询绑定结果(`binding` 里是落库后的绑定关系);
- `DELETE /api/web/me/wechat/bindings/:id` 解绑(只能删自己的,找不到 404);
- 表结构:`wechat_gateway_bindings`(迁移 `20261028120000`):网关用的公众号 appid 我们并不掌握,
只有 `app_key` + `openid`,所以单独一张表(旧的 `wechat_oauth` / `wechat_mp_accounts` 已于 `20261029100000` 删除);
- **设备专用:扫码登录 + 注册(`GET /api/device/login`,`app/controller/device.js`)**:给「设备上不好敲账号密码、甚至**出厂什么都不用配**」的场景用——
**登录即注册**:设备插上电直接要一个登录码显示在**设备屏幕上**,用已经登录的手机(小程序/网页)扫一下确认,
服务端**这才**把设备注册到那个账号名下(归属 = 确认登录的人),并把**长期 JWT** 发给设备
(默认 365 天,见 `config.jwt.deviceExpiresIn` / env `DEVICE_JWT_EXPIRES`;
设备可用 `?expiresIn=30d`(或秒数)申请**更短**的,超上限 422):
- **不需要凭据、也不需要预先注册**(与 `GET /api/wechat/login` 一样是公开接口);
- **不需要凭据、也不需要预先注册**(公开接口);
- **不带 `code`**:发一张新登录码(此时**库里还没有任何记录**),返回
`{ status:'pending', expiresIn, code, spm, origin, qrContent, qrImageUrl, qrUrl, device:{ sn, name } }`
—— **域名不用设备自己拼**:`qrContent` 就是二维码里该编的**完整**网址(`http://<域名>/wechat?spm=…`),
@ -911,7 +859,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
域名取 `SITE_URL`(`config.email.siteUrl`)——有反代/多域名、或**设备走内网而扫码的手机要走公网**时建议配上;没配就用设备请求时的 origin(设备访问服务用的那个地址);
- **设备信息(可选)**:`?sn=`(设备序列号)、`name` / `vendor` / `model` / `firmware`;**发码时带上最省事**
(服务端暂存 `packs:device:info:<code>`,确认/换码时沿用),轮询时再带(补齐/覆盖)也行;不带 SN 时服务端注册那一步生成一个 `DEV-…` 并返回给设备保存;
- **带 `?code=&wait=N`**:**长轮询**(与 `/api/wechat/login` 完全同一套实现与上限 `WECHAT_POLL_WAIT`,默认 60s):
- **带 `?code=&wait=N`**:**长轮询**(上限 `WECHAT_POLL_WAIT`,默认 60s):
- 手机确认 → **立即**返回 `{ status:'confirmed', firstTime, sn, token, tokenType, expiresIn, expiresAt, scanner, user }`;
- 到时间没人扫 / 码已失效 → `{ status:'refreshed', code:<新码>, spm, qrContent, qrImageUrl, … }`(设备换二维码后继续轮询);
- 设备断开(重启/换页)→ 服务端**立刻**停止等待(`aborted`,不写响应、也不换码);
@ -958,7 +906,6 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
showQrcode(d.qrContent); // 直接编 qrContent(已是完整网址,设备无需知道域名)
}
```
- 未配 `WECHAT_APPID`/`WECHAT_SECRET`(本机默认):二维码照旧本地生成(内容是本站 `/wechat?spm=…`),扫码面板**不显示任何说明文字**(只留二维码 + 「返回账号密码登录」),扫码后走「手机确认登录」降级路径;
- 新增/重置登录账号:`npm run user:pass -- <账号> <密码> [昵称]`。
- 设备身份**只有长期 JWT 一种**:列表/详情/`me` 接口**不会**返回 `token_jti`(`sanitize()` 兜底);`secret_hash` 是历史字段(已不再写入)。
- **软删除的行仍占着唯一键**:`scanners.sn` 是唯一键而 `deleted_at` 的软删行还在库里,所以扫码登录(`loginByScan()`)**带上已删除的一起查**,命中就把那条记录**复活**(`restore()`,与 `scan.js` 里通道的处理一致),否则 `create` 会撞唯一键;
@ -968,6 +915,8 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
确认成功那一刻(就是「注册」时刻)才按 SN 建/取记录、绑定到确认登录的用户、发长期 JWT;确认环节复用
`POST /api/wechat/confirm` 与同一套 6 位串码(`service/wechatLogin`),**不新增确认接口、不新增 Redis key 空间**;
`SN 已属于其他账号 → 403`(不会把别人的设备扫走),无主记录(老接口注册出来的)由本次确认者认领;
- **扫码登入工作台**:二维码按需生成(网关一次性临时码),手机微信确认后由网关回调落 `workstation_login_records`;
旧的工作台登录码(`WSC-`)与 `POST /api/web/workstation-login` **已废弃**(见下文「工作台成员登录」);
- **没有 CSRF**:后端已关掉 CSRF(`config.security.csrf.enable = false`),页面表单/会话都没了;扫描器用 JWT 调 JSON 接口不会遇到 403;
- 扫码去重放在**数据库唯一键 + 服务层预过滤**两层:唯一键 `(scanner_id, channel_id, barcode, scan_time)` 是最终保证,服务层先查一次再做批量插入(并发撞键时退化为逐条插入并计数),所以重复上报既不报错也不产生脏数据;另外**同一运单号 24 小时内只保留一条**,后上报的扫描时间更新时覆盖原记录(时间 + 工作台快照),旧上报不回退;
- 扫码记录是**流水表、不用软删除**(`paranoid: false`):软删除会让记录占用唯一键,导致同一条数据无法再入库;清理请按时间物理删除;
@ -977,10 +926,70 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
- 「查状态」→ `GET /api/wechat/status?code=…`(无需登录):`pending`(待扫码)/ `confirmed`(已被确认)/ `expired`(没这个码);
- 「请求登录」→ `POST /api/wechat/confirm`(`{ code }`):`data.status='confirmed'` 即授权成功,电脑端正在长轮询的请求会**立即**完成登录;已用过/不存在/格式错分别返回 `used` / `expired` / `bad_format`;
- **鉴权完全模仿小程序**:AJAX 把用户 JWT 放在 `Authorization: Bearer` 头里(`fetch` 不带 `credentials`),页面上也把这枚令牌显示出来方便贴到小程序里调试;
- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**);`/api/users*`、`/api/configs*`、`/api/scanners*` 走 `app/middleware/internal_auth.js`(`X-Internal-Token` 或白名单账号的 user JWT);`/api/scanner/*`、`/api/scan/*` 走 `app/middleware/scanner_auth.js`(设备长期 JWT);公开接口只有 `/api/info`、`/health`、`/api/wechat/{login,status,qrcode.svg,callback}`、`/api/device/login` 与 `/api/web/auth/*`;
- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**),其中 `/api/web/admin/*` 再叠一层 `app/middleware/platform_admin.js`(平台管理员);`/api/users*`、`/api/configs*`、`/api/scanners*` 走 `app/middleware/internal_auth.js`(`X-Internal-Token` 或白名单账号的 user JWT);`/api/scanner/*`、`/api/scan/*` 走 `app/middleware/scanner_auth.js`(设备长期 JWT);公开接口只有 `/api/info`、`/health`、`/api/wechat/{status,qrcode.svg}`、`/api/wechat-gateway/notify`、`/api/device/login` 与 `/api/web/auth/*`;
- 密码等敏感信息放 `config/config.local.js`(已 gitignore)或环境变量,不要写进 `config.default.js`。
- 生产环境请修改 `config/config.default.js` 中的 `config.keys`。
## 平台管理员与平台管理台(2026-10-29)
两种「管理员」互不相干,别混:
| | 谁 | 能干什么 | 存在哪 |
|---|---|---|---|
| **主体管理员** | 某个主体里的 `role=1` 成员 | 只管**自己那个主体**:成员、设备、录像机、工作台、扫码记录、续期下单 | `subject_members.role` / `subjects.admin_user_id` |
| **平台管理员** | 平台的运营/管理人员 | 看**所有**主体与订单、改授权到期时间、**确认订单**、加别的平台管理员 | `admin_members`(+ `INTERNAL_ADMIN_IDS` 内置名单) |
### 数据表
| 表 | 说明 |
|---|---|
| `admin_members` | 平台管理员:`user_id`(唯一,账号 id)+ `name`(显示名,不填取昵称/用户名)+ `role`(1 超级管理员 / 2 管理员)+ `status`(1 启用 / 0 停用)+ `remark`;软删除 |
迁移 `20261029120000-create-admin-members`:
- 建表 + `uk_admin_members_user`(`user_id` 唯一)+ `idx_admin_members_status`;
- **把内置管理员先塞进来**(`users.username='admin'`,没有就 `id=1`),保证升级后立刻能用;
- ⚠️ 软删的行仍占着 `user_id` 唯一索引,所以「查重 / 加回来」必须带 `paranoid: false`(`service/admin_member.js` 已处理:命中软删行就 `restore()`)。
### 谁是平台管理员(`middleware/platform_admin.js`)
满足其一即可,`ctx.state.platformAdmin` 记录通过方式:
1. `admin_members` 里 `status=1` 的行(**页面可自助维护**);
2. `config.internal.adminIds`(env `INTERNAL_ADMIN_IDS`,默认 `[1]`)——**内置 / 救急入口**:
就算把页面上的管理员全删了,也还能用它登录把入口加回来(前端会标「内置」且不给移除按钮)。
不通过 → **403** `{ status: 'not_platform_admin' }`。这些接口都要 **user JWT**(`apiAuth` 之后才校验)。
### 接口(`/api/web/admin/*`,全部要求平台管理员)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/admin/me` | 当前账号是不是平台管理员 → `{ admin, builtin, user }`(前端决定要不要显示「平台管理」菜单) |
| GET | `/api/web/admin/members` | 平台管理员列表(表里的 + 内置名单里表里没有的,后者 `id=null`、`builtin=true`) |
| POST | `/api/web/admin/members` | 添加 `{ account, name?, role?, remark? }`;`account` = 用户名 / 手机号 / 邮箱。账号不存在 404、已是管理员 409、账号被禁用 409 |
| DELETE | `/api/web/admin/members/:id` | 移除(软删;**不能移除自己**,也不能把最后一个启用的管理员删光) |
| GET | `/api/web/admin/subjects?page=&pageSize=&keyword=&status=&expired=` | **所有主体**(带成员数 / 管理员账号 / 是否过期);`keyword` 模糊匹配主体名或备注;`expired=1\|0` 只看已过期 / 未过期 |
| PUT | `/api/web/admin/subjects/:id` | **改授权到期时间**:`{ expireAt: '2027-01-01T00:00:00+08:00' }` 直接设(可设成过去 = 立即到期),或 `{ extendDays: 30 }` 顺延(未过期从原到期时间算、已过期从现在算);也可顺带改 `remark` / `status` |
| GET | `/api/web/admin/orders?page=&pageSize=&keyword=&status=&subjectId=` | **所有订单**(带主体名 / 下单人);`keyword` 模糊匹配订单号、套餐名、主体名;`status=0\|1\|2` |
| POST | `/api/web/admin/orders/:orderNo/confirm` | **确认订单**(线下收款 / 手工补单):与支付回调走**同一套** `service.subjectOrder.payNotify()`,所以「标记已支付 + 主体顺延 + 失效主体状态缓存 + 幂等」完全一致,只是渠道记成 `manual`、流水号 `ADMIN-<时间戳>` |
改授权到期时间后必须失效主体状态缓存(`subjectState.invalidate`),否则设备心跳 / 上报最多要等一个 TTL 才看到新期限 —— `service/subject.js#setExpireAt()` 已经做了。
### 前端(`frontend/`)
左侧菜单在**平台管理员**登录后会多出一组「平台管理」(`components/AppLayout.vue`):
| 菜单 | 路由 | 页面 | 干什么 |
|---|---|---|---|
| 主体管理 | `/admin/subjects` | `views/AdminSubjectsView.vue` | 所有主体;「改到期时间」弹窗支持**直接选时间**或**顺延 N 天**(+7 / +30 / +90 / +1 年快捷按钮) |
| 订单管理 | `/admin/orders` | `views/AdminOrdersView.vue` | 所有订单;待支付的可以「确认订单」(二次确认后立即续期) |
| 管理员 | `/admin/members` | `views/AdminMembersView.vue` | 平台管理员列表 + 添加(按账号)+ 移除 |
- 是否显示这组菜单靠 `GET /api/web/admin/me`(`composables/usePlatformAdmin.ts`;非管理员 403 静默当 false);
- 路由带 `meta.platformAdmin`,不是平台管理员会被守卫踢回首页(`?denied=1`);
- 这三个页面 `allowNoSubject: true` —— 平台管理员可能一个主体都没有,不能因为「没主体」被挡走。
## 主体(租户)体系(2026-10-18)
业务数据(设备 / NVR / 摄像头 / 工作台 / 扫码记录 / 扫码通道)全部挂在**主体**下,接口按主体隔离。
@ -991,6 +1000,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
|---|---|
| `subjects` | 主体:`name`、`admin_user_id`(**创建者**,恒为管理员)、`expire_at`(使用期限)、`status`、`remark` |
| `subject_members` | 成员:`subject_id` + `name`(姓名,必填)+ `user_id`(绑定账号,可为空)+ `role`(1 管理员 / 2 成员,**同一主体可多名管理员**)+ `wechat_openid` / `bound_at` |
| `workstation_login_records` | 工作台成员登录记录:谁在什么时候登入 / 下线了哪台工作台(见「工作台成员登录」) |
| 业务表 | `scanners` / `nvrs` / `cameras` / `workstations` / `scan_channels` / `scan_records` 都有 `subject_id` |
升级时(迁移 `20261018230000-create-subject-tables`)会给**已有数据**的账号各建一个主体(管理员=本人、期限 +365 天),
@ -1007,17 +1017,31 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
| POST | `/api/web/subjects/:id/members` | 按姓名快速添加成员 `{ name }`(**仅管理员**,此时还没绑账号) |
| DELETE | `/api/web/subjects/:id/members/:memberId` | 移除成员(**仅管理员**;不能删创建者/管理员/自己,管理员要先取消管理员) |
| PUT | `/api/web/subjects/:id/members/:memberId/role` | 设/取消管理员 `{ role: 1\|2 }`(**仅管理员**;一个主体可多名管理员,创建者恒为管理员不能降级,不能改自己) |
| POST | `/api/web/subjects/:id/members/:memberId/bind-code` | 生成成员绑定码(**仅管理员**,`{ code, bindUrl, qrUrl, expiresIn }`,10 分钟有效) |
| GET | `/api/subject/member-bind?code=` | 绑定码状态(**公开**,手机扫码页轮询) |
| POST | `/api/subject/member-bind/confirm` | 手机端确认绑定 `{ code }`(需 user JWT)→ 该账号成为成员 |
| POST | `/api/web/subjects/:id/members/:memberId/bind-qr` | 生成「扫码绑定」二维码(**仅管理员**,走微信登录网关)→ `{ memberId, memberName, state, pageUrl, qrUrl, expiresIn }`;成员已绑**真实账号**时 409 |
| GET | `/api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait=` | 长轮询绑定结果(**仅管理员**)→ `{ status, memberName?, boundName?, autoCreated?, message? }`(`pending` / `confirmed` / `failed` / `expired`) |
| POST | `/api/web/subjects/:id/members/:memberId/unbind` | 解除成员的账号绑定(**仅管理员**;绑错了/手机换人时用,自动建的临时账号会一并删除) |
角色规则(`subject_members.role`):
- **一个主体可以有多个管理员**(`role=1` 没有唯一约束);`subjects.admin_user_id` 只是**创建者**,同样恒为管理员;
- 成员管理(加成员 / 发绑定码 / 设·取消管理员 / 移除)**只有管理员能做**,普通成员只能看成员列表(只读);
- 成员管理(加成员 / 扫码绑定 / 解除绑定 / 设·取消管理员 / 移除)**只有管理员能做**,普通成员只能看成员列表(只读);
- 创建者不能降级、不能移除;不能改自己的角色、不能删自己(避免管理员把自己锁死);
- 管理员不能直接移除,需先「取消管理员」;给**未绑定账号**的成员设为管理员,绑定后即为管理员。
### 成员扫码绑定(微信登录网关,2026-10-28)
管理员点「扫码绑定」出一张网关二维码,成员用**手机微信**扫码确认后按两种情形落地(`service/subject.js#bindMemberWithWechat`):
- **这个微信已经是某个平台账号的登录方式**(`wechat_gateway_bindings` 里有它)→ 成员**直接继承**那个账号;
如果成员之前挂着一个自动建的临时账号,那个账号会被软删(连它的微信绑定一起清掉),`subject_members.temp_user_id` 置空;
- **这个微信还没有平台账号** → 服务端**自动给这名成员建一个账号**(用户名 `member<成员id>`、随机密码、昵称=成员姓名),
把微信绑成它的登录方式,并记在 `temp_user_id` 上;此后这名成员可以直接微信扫码登录;
- 例外(都会变成会话里的 `failed`,弹窗直接显示原因):微信绑定的账号被禁用、这个账号已经是本主体成员(`subject_members` 唯一键)、
成员已绑**其他真实账号**(先「解除绑定」再扫)。
旧的「6 位绑定码 + `/wechat?bind=<码>` 手机确认页」**已删除**(`/api/subject/member-bind*` 一并移除),
`/api/wechat/qrcode.svg?mode=member` 的 `mode` 参数也一起去掉。
### 续期套餐与订单(支付回调驱动)
**续期不再是「自己输入天数」**:前端先选套餐(天数 + 定价都在库里),点「生成订单」只落一笔**待支付**订单,
@ -1068,7 +1092,7 @@ curl -X POST http://127.0.0.1:7300/api/internal/subject-orders/<orderNo>/pay \
-H "X-Internal-Token: <INTERNAL_TOKEN>"
```
二维码:`GET /api/wechat/qrcode.svg?code=<码>&mode=member`(内容是 `<站点>/wechat?bind=<码>`,前端扫码页显示「确认绑定」)。
成员绑定不再用 6 位码:改用微信登录网关的二维码,见上文「成员扫码绑定」(`POST /api/web/subjects/:id/members/:memberId/bind-qr`)。
### 主体上下文(统一处理)
@ -1092,13 +1116,98 @@ curl -X POST http://127.0.0.1:7300/api/internal/subject-orders/<orderNo>/pay \
| GET | `/api/web/devices/active` | 本主体已绑定设备(开启前检查用) |
| POST | `/api/web/devices/activate` | **仅主体管理员**;`{ sn?, name? }` → `{ device, token, tokenType, expiresIn, kicked[] }` |
| POST | `/api/web/devices/:id/logout` | 关闭设备服务(轮换 jti → 该设备令牌立即 401) |
| GET | `/api/wechat/qrcode.gif?code=&mode=` | 同一张二维码的 **GIF**(桌面端 WPF 不能渲染 SVG;`online.png` 不需要) |
| GET | `/api/wechat-gateway/qrcode.gif?state=` | 桌面端(WPF)登录二维码的 **GIF**(不能渲染 SVG;`online.png` 不需要) |
**「一个主体只允许一台设备在线」**:`activate` 会把同主体下**其他**设备的 `token_jti` 全部轮换(旧 JWT 立即失效),
并在返回的 `kicked` 里列出被踢的设备;同一 SN 重复开启只是换发令牌,不会新建记录。
设备令牌用于设备侧上报:`POST /api/scan/channels`、`POST /api/scan/records`(`scannerAuth` + `subjectActive`,
不需要主体 header;所属主体过期/停用 → 403 `subject_expired` / `subject_disabled`)。
### 面单摄像头 & 虚拟通道(`CAM-<工作台id>`)
工作台的**面单摄像头**(`workstation_cameras.is_label_camera = 1`,一台工作台最多一路,散单/团购都能设)
由桌面端拉 RTSP 识别条码,识别结果按「该工作台 + 本机通道」上报。记录规则按工作台类型分流
(下发里的 `wsType`):**散单取第一次 + 立即上报,团购和扫码枪一样静默 5 秒取最后一次**。
工作台**没接扫码枪**(没绑本机通道)也能用:`GET /api/scanner/label-cameras` 会顺手给它一条
**虚拟通道**,规则如下(实现在 [app/lib/virtual-channel.js](app/lib/virtual-channel.js)):
| 项 | 规则 |
|---|---|
| 通道 id | `CAM-<工作台id>`,与设备上报的真实通道(纯数字 / `DESKTOP`)不会冲突 |
| 通道名 | `面单摄像头·<摄像头名>` |
| 创建 | 设备拉配置时幂等自愈(`label_scan.ensureVirtualChannel`),并绑到该工作台(回放定位靠 `scanner+channel → 工作台`) |
| 清理 | 取消面单摄像头、绑上真实扫码通道、删除工作台时自动清掉(`workstation.releaseVirtualChannel`) |
| 对账豁免 | `POST /api/scan/channels` 的 `replace: true` **不动** `CAM-` 前缀的通道(设备列表里永远没有它) |
| 前端 | 工作台详情里标记「虚拟」,不给解绑;人工绑定通道列表里也不出现 |
| 播报 | 虚拟通道没有对应的安卓扫码工位,所以**不会**通知安卓端播报 |
#### 变更怎么通知到设备(`labelScan.refresh`)
设备端只有「启动拉一次 + 每分钟兜底」,秒级生效靠**服务端主动推**:
| 触发点 | 位置 |
|---|---|
| 设置/取消面单摄像头 | `workstation.setLabelCamera` |
| 解绑摄像头(可能是面单那路)/ 删除摄像头 | `workstation.unbindCamera`、`camera.remove`、`camera.batchRemove` |
| 摄像头停用/改名 | `camera.update` |
| 绑定/解绑上报通道(面单结果落点变了) | `workstation.bindScanChannels`、`unbindScanChannel` |
| 工作台改名/改类型/停用/删除 | `workstation.update`、`workstation.remove` |
实现:`labelScan.notifyChanged(subjectId)` 给本主体**每台启用中的设备**入队一条
`labelScan.refresh` edge 任务(`edge_task.enqueue`)。设备收到只是被「叫醒」,真正的配置仍以
`GET /api/scanner/label-cameras` 为准;入队失败只记日志(配置已落库,不能因为通知失败回滚)。
## 工作台成员登录(2026-10-24)
成员用**手机微信**扫管理员生成的二维码登入工作台(2026-10-28 起走微信登录网关,旧的 `WSC-` 登录码已废弃)。这张表同时回答两件事:
「**现在**这台工作台上是谁」和「**某张运单打包时**是谁」。
### 数据表
| 表 / 字段 | 说明 |
|---|---|
| ~~`workstations.login_code`~~ | **已废弃**(迁移 `20261028121000` 删除):扫码登入改走微信登录网关,二维码按需生成、一次有效 |
| `workstations.last_active_at` | 最后活跃时间(扫码上报 / 有人登录时刷新) |
| `workstations.idle_timeout_sec` | 多少秒不活跃自动下线所有成员(团购默认 3600、散单默认 1800) |
| `workstation_login_records` | 一次登录一行:`subject_id` / `workstation_id` / `user_id`(+ `member_id`)/ `name` / `type`(1 扫码登录,预留扩展)/ `login_code`(历史字段,新记录为空)/ `login_at` / `logout_at` / `status`(1 在线 0 下线)/ `logout_reason` / `login_ip` |
- 索引:`(workstation_id, login_at)`(运单回放定位「当时谁在线」)、`(workstation_id, status)`、`(user_id, status)`、`(subject_id, login_at)`、`status`(定时任务扫在线)。
- `name` 记登录当时的名字:**是工作台所属主体的成员 → 成员姓名(= 工号)**;不是成员 → 用户自己设置的昵称。
- `logout_reason`:`manual` 手动下线 / `offline_all` 一键全部下线 / `reset_code`(旧版重置登录码,仅历史)/ `idle_timeout` 长时间不活跃 / `relogin` 同一个人重新登录 / `workstation_deleted` 工作台被删除。
### 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/web/workstations/:id/login-qr` | **生成扫码登入二维码**(微信登录网关,`scene=login`)→ `{ workstationId, state, pageUrl, qrUrl, expiresIn }`;二维码一次有效 |
| GET | `/api/web/workstations/:id/login-qr/status?state=&wait=25` | 长轮询扫码结果 → `{ status, workstation?, member?, name?, record? }`(`pending` / `confirmed` / `failed`+`message` / `expired`);手机确认后网关回调落登录记录,**同一账号重复登录旧记录按 `relogin` 下线** |
| GET | `/api/web/workstations/:id/members?status=1&startTime=&endTime=&page=&pageSize=` | 成员列表(`status=1` 只看在线,不传 = 含历史;`startTime/endTime` 按**登录时间**过滤)→ `{ list, total, page, pageSize, onlineCount }` |
| POST | `/api/web/workstations/:id/members/:recordId/offline` | 手动下线某条在线记录(幂等,已下线返回 `alreadyOffline: true`) |
| POST | `/api/web/workstations/:id/members/offline-all` | 把该工作台**所有在线成员下线**(`offline_all`)→ `{ id, offline }` |
| GET | `/api/web/pack-query?code=` | 每条 `records[].packers` = 该次扫码时还在线的人(`[{ id, userId, memberId, name, loginAt, logoutAt }]`) |
鉴权:`/login-qr`、`/login-qr/status`、`/members`、`/offline`、`/offline-all` 与工作台其它接口一致(`apiAuth` + `subjectAuth` + `subjectAdmin`)。
登入本身发生在**网关回调**(`/api/wechat-gateway/notify`,公开但必须验签)里:`openid` → `wechat_gateway_bindings` → 平台账号 →
`workstationLogin.loginByUser()`(主体停用 → 403、过期 → 403、工作台停用 → 403 都会变成会话里的 `failed` + 原因)。
⚠️ 旧接口 `POST /api/web/workstation-login`(`{ code }`)与 `POST /:id/login-code/reset` **已删除**。
### 自动下线
- 扫码上报(`POST /api/scan/records`)成功后刷新相关工作台的 `last_active_at`;有人登录也会刷新。
- 定时任务 `app/schedule/workstation_idle_offline.js` **每分钟**扫一次还在线的记录:
`now - (last_active_at || 该工作台最晚一条在线记录的 login_at) >= idle_timeout_sec`
→ 把该工作台所有在线记录下线(`idle_timeout`)。从没上报过条码的工作台按「最晚登录时间」算,
不会出现「刚建的工作台永远不下线」;工作台已删除则按 `workstation_deleted` 收尾。
- 默认值:团购 3600 秒、散单 1800 秒;`POST/PUT /api/web/workstations` 的 `idleTimeoutSec` 可改(60~86400 秒)。
只切类型且没传 `idleTimeoutSec` 时,自动套用新类型的默认值。
### 运单打包人员
`GET /api/web/pack-query` 的 `records[].packers` 来自 `workstation_login_records`:
`login_at <= 扫码时间 <= (logout_at ?? 现在)`(**按秒比较**,兼容设备上报的秒级扫码时间),
同一时刻多人同时在线就是多人打包(数组,可能为空)。
## 用户协议(2026-10-20)
三张表(迁移 `20261020220000-create-agreement-tables`,示例数据 `20261020221000-seed-user-agreement`):
@ -1142,43 +1251,88 @@ FROM user_agreements WHERE user_id = ? ORDER BY agreed_at DESC;
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。
## 微信小程序登录(2026-10-20)
## 已下线:小程序微信一键登录(2026-10-29 移除)
独立的小程序登录模块:`code2Session` 换 openid → 按 openid 找绑定账号 → 未绑定则自动建账号。
自建的「小程序 code2Session 一键登录」已经整体下线,微信侧的接入统一走下面的**微信登录网关**:
### 数据表
- 删除的表:`wechat_mp_accounts`(小程序 openid ↔ 平台账号)、`wechat_oauth`(自建公众号网页授权 + 运维手工维护的绑定关系);
- 删除的接口:`POST /api/web/auth/wechat/{login,bind}`、`GET /api/web/auth/wechat/bindings`、`DELETE /api/web/auth/wechat/bindings/:id`、
`GET /api/users/:id/wechats`、`GET /api/wechat/:appid/:openid`、`POST /api/wechat/bind`、`PUT /api/wechat/:id/tokens`、`DELETE /api/wechat/:id`;
- 删除的代码:`app/service/{wechat,wechat_mp}.js`、`app/controller/web/wechat_mp.js`、`app/model/{wechat_oauth,wechat_mp_account}.js`、
`service/user.js#findByOpenid`、`service/wechatLogin.js#{login,exchangeCode,oauthAuthorizeUrl}`、`GET /api/wechat/callback`;
- 删除的环境变量:`WECHAT_APPID` / `WECHAT_SECRET` / `WECHAT_REDIRECT_URI` / `WECHAT_API_BASE` / `WX_MP_APPID` / `WX_MP_SECRET` / `WX_MP_MOCK`;
- 迁移:`20261029100000-drop-legacy-wechat-tables.js`(`down` 会按原结构重建两张空表)。
| 表 | 用途 |
|---|---|
| `wechat_mp_accounts` | 小程序 openid 与平台账号的绑定:`(appid, openid)` 唯一,`user_id` 为空表示已解绑;另存 unionid / session_key / 最近登录 |
现在小程序只支持**账号密码登录**;`/api/wechat/{status,qrcode.svg}` + `POST /api/wechat/confirm` 仅剩**设备扫码登录**在用。
与公众号的 `wechat_oauth` 分开:小程序是「一个 openid 对一个平台账号」,解绑只清 `user_id`,记录保留。
## 微信登录网关(扫码登录 / 绑定微信 / 工作台扫码登入,2026-10-28)
### 配置
对接 [gateway.gztbyc.com](https://gateway.gztbyc.com/#/docs):二维码与「扫码确认」都由网关提供,
本服务只负责 **申请临时码 → 验签收通知 → 落地自己的业务**。
| 环境变量 | 说明 |
|---|---|
| `WX_MP_APPID` / `WX_MP_SECRET` | 小程序后台「开发设置」里的 AppID / AppSecret(**必须配齐才会真调微信**) |
| `WX_MP_MOCK` | 生产要允许 mock 时显式设为 `true`;本地/单测未配 AppID 时默认允许 mock |
| `WECHAT_API_BASE` | 微信接口地址(默认 `https://api.weixin.qq.com`,联调可改网关) |
### 环境变量
mock 模式:请求里 `code` 传 `mock:<openid>` 可直接指定 openid(固定账号,方便联调);
传其它 code 时按 `sha1(code)` 推导 openid。
| 变量 | 默认值 | 说明 |
|---|---|---|
| `WX_GATEWAY_BASE` | `https://gateway.gztbyc.com` | 网关地址(本地联调可指向假网关) |
| `WX_GATEWAY_APP_KEY` | 空 | 网关应用标识(`gwk_…`);**空 = 未开通**,扫码接口一律 503 |
| `WX_GATEWAY_APP_SECRET` | 空 | 网关应用密钥(`gws_…`),**只放服务端**,用来验证回调签名 |
| `WX_GATEWAY_POLL_WAIT` | `55` | 长轮询最长挂起秒数(前端再留 70s 自己的超时) |
| `WX_GATEWAY_SCENE_TTL` | `660` | 本地扫码会话有效期(秒,比网关临时码的 10 分钟略长) |
| `WX_GATEWAY_NOTIFY_SKEW` | `300` | 通知 `timestamp` 允许偏差(秒) |
| `WX_GATEWAY_TIMEOUT` | `8000` | 调网关接口的超时(毫秒) |
⚠️ **网关管理台必须把「服务端通知地址」配成** `https://<本站域名>/api/wechat-gateway/notify`。
### 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/web/auth/wechat/login` | 公开;`{ code, userInfo?, client?, agreements? }` → 令牌 + 用户 + 主体列表 + `firstTime` + `wechat` 绑定信息 |
| POST | `/api/web/auth/wechat/bind` | 需令牌;把当前微信绑到已有账号(openid 已属他人 → 409) |
| GET | `/api/web/auth/wechat/bindings` | 需令牌;当前账号的微信绑定列表 |
| DELETE | `/api/web/auth/wechat/bindings/:id` | 需令牌;解绑(若是唯一登录方式 → 422,先设密码) |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/wechat-gateway/notify` | **签名** | 网关回调(`X-Gateway-*` / body 里的 `sign`);验签失败 401,会话过期 200 + `{ignored:'session_expired'}` |
| POST | `/api/web/auth/wechat-gateway/qrcode` | 公开 | 申请登录二维码 → `{ state, pageUrl, qrUrl, expiresIn }`;没配网关 503 |
| GET | `/api/web/auth/wechat-gateway/login?state=&wait=` | 公开 | 长轮询 → `{ status, token?, user?, message? }`(`pending` / `confirmed` / `failed` / `expired`) |
| GET | `/api/wechat-gateway/qrcode.svg?state=` | 公开 | 会话里那张二维码的 **SVG**(本地画,零外链) |
| GET | `/api/wechat-gateway/qrcode.gif?state=` | 公开 | 同一张二维码的 **GIF**(桌面端 WPF 不能渲染 SVG) |
| POST | `/api/web/me/wechat/qrcode` | user JWT | 申请「绑定微信」二维码(`scene=bind`)→ 同上结构 |
| GET | `/api/web/me/wechat/status?state=&wait=` | user JWT | 长轮询绑定结果 → `{ status, binding? , message? }` |
| GET | `/api/web/me/wechat/bindings` | user JWT | `{ list, enabled }`(`enabled=false` = 没配网关) |
| DELETE | `/api/web/me/wechat/bindings/:id` | user JWT | 解绑(只能删自己的;找不到 404) |
| GET | `/api/internal/wechat-bindings?openid=&userId=` | 内部令牌 | 运维查绑定(**含已解绑的**),带账号状态(禁用/已删除) |
| DELETE | `/api/internal/wechat-bindings/:id` | 内部令牌 | **强制解绑**任意绑定(微信绑在前员工账号上时兜底) |
| POST | `/api/web/workstations/:id/login-qr` | + 主体管理员 | 二维码(`scene=login`,`purpose=workstation`)→ 见「工作台成员登录」 |
| GET | `/api/web/workstations/:id/login-qr/status?state=&wait=` | + 主体管理员 | 长轮询扫码登入结果 |
| POST | `/api/web/subjects/:id/members/:memberId/bind-qr` | + 主体管理员 | 二维码(`scene=bind`,`purpose=member`)→ 见「成员扫码绑定」 |
| GET | `/api/web/subjects/:id/members/:memberId/bind-qr/status?state=&wait=` | + 主体管理员 | 长轮询成员绑定结果 |
登录细节:
### 实现要点
- 未绑定过的 openid → 自动创建平台账号:用户名 `wx_<openid 尾 12 位>`(重名加随机后缀)、
随机密码(等于没有密码,需要用「找回密码」设置后才能密码登录),`firstTime: true`;
- 已绑定 → 复用原账号,校验 `users.status`(禁用 → 403);
- 与账号密码登录共用协议校验:`client='mini_program'` 未同意当前协议版本 → **428** `agreement_required`;
- 签发令牌 / 记录同意 / 带主体列表的逻辑在 `app/service/login.js`(两种登录共用)。
- 会话存 Redis(`packs:wxgw:sess:<state>`,`state` 是我们自己的 32 位 hex,原样传给网关):
`{ status, purpose, scene, pageUrl, tempCode, payload }`;没有 Redis 时退化为进程内 Map(**只适合本地/单测**,
多实例部署必须用 Redis,否则回调与轮询可能落在不同实例)。
- 长轮询用 Redis 发布订阅(`packs:wxgw:chan:<state>`)唤醒:先 `SUBSCRIBE` 再查状态,避免「刚查完就被确认」漏掉;
客户端断开(`res` 的 `close`)会立刻结束等待,不白占连接。
- 验签:`HMAC-SHA256(key = sha256hex(appSecret), msg = appKey.userId.bindCode.timestamp.nonce)`,
与 `crypto.timingSafeEqual` 比较;`appKey` 必须是本应用的,`timestamp` 与当前时间差 > `WX_GATEWAY_NOTIFY_SKEW` 直接拒绝。
- 落地:
- `purpose=login` → `openid` 查 `wechat_gateway_bindings` → 会话里只放 `userId`,**令牌等轮询时再签**;
- `purpose=bind` → 写/更新绑定关系(一个 openid 只能绑一个账号,一个账号只绑一个微信);
- `purpose=workstation` → `workstationLogin.loginByUser()` 落 `workstation_login_records`(失败原因写回会话);
- `purpose=member` → `subject.bindMemberWithWechat()`:微信已有平台账号就直接继承(自动建的临时账号删除),
没有就自动给这名成员建号并把微信绑成它的登录方式(见「成员扫码绑定」)。
- 未绑定微信时 `failed` 的文案是「请先用账号密码登录,在『个人中心 → 微信绑定』绑好后重新扫码」。
### 「这个微信已经绑了别的账号」怎么处理
绑定时按「原绑定账号是否还能用」分三种情况(`handleBind` / `upsertBinding`):
| 情况 | 处理 |
|---|---|
| 原账号**正常**(`users.status = 1`) | 拒绝,会话里给 `failed`:「这个微信已经绑定了其他账号(<昵称/用户名>):请用那个账号登录后在『个人中心 → 微信绑定』解绑,或联系管理员处理」。**不会**静默改绑——微信绑定就是登录凭证,不能让拿到微信的人抢走别人的账号 |
| 原账号**已禁用或已删除** | 绑定已经"用不了",直接把微信**改绑**到当前账号(复用同一条 `wechat_gateway_bindings` 记录),日志 `[wx-gateway] 微信 … 原绑定账号 … 不可用,改绑到 userId=…` |
| 本人拿不到原账号(前员工 / 手机换人) | 运维用 `GET /api/internal/wechat-bindings?openid=` 查到这条绑定,再 `DELETE /api/internal/wechat-bindings/:id` **强制解绑**;之后该微信可以重新绑给别人(解绑是软删,下次绑定会 `restore` 复用这条记录) |
> 成员扫码绑定(`purpose=member`)遇到「微信已绑账号」时**不改绑**:微信是谁的就绑到谁身上(继承那个账号);
> 只有那个账号被禁用时才 `failed` 提示联系管理员,管理员可以先「强制解绑」再让成员重扫。
- 单测不走真网关:`mock(app, 'httpclient', ...)` 假装临时码接口,再用 `service.wxGateway.signOf(body)` 造合法签名
直接打 `/api/wechat-gateway/notify`(见 `test/app/controller/wx-gateway.test.js`)。

View File

@ -133,7 +133,10 @@ Write-Host "JAVA_HOME=$javaHome"
# ---------------- 4. 构建 APK ----------------
Push-Location $projectDir
try {
& $gradlew --no-daemon assembleRelease "-PversionName=$Version" "-PversionCode=$VersionCode"
# 2>&1 | Write-Host:gradle 会把 javac 的提示写到 stderr(例如「使用了已过时的 API」),
# 直接调用时 PowerShell 会把它当错误记录,配合 $ErrorActionPreference='Stop' 会误判构建失败。
& $gradlew --no-daemon assembleRelease "-PversionName=$Version" "-PversionCode=$VersionCode" 2>&1 |
ForEach-Object { Write-Host $_ }
if ($LASTEXITCODE -ne 0) { throw "gradlew assembleRelease 失败($LASTEXITCODE)" }
}
finally {

View File

@ -51,5 +51,13 @@ npm run db:migration:generate -- create_xxx_tables # 生成迁移骨架
| `20261018210000-add-workstation-type` | `workstations.ws_type`(1 散单 / 2 团购) |
| `20261018220000-add-workstation-record-range` | `workstations.record_before_sec/record_after_sec/record_max_sec`(录制范围与最大录制时长) |
| `20261018230000-create-subject-tables` | 新表 `subjects` / `subject_members`;`scanners`/`nvrs`/`cameras`/`workstations`/`scan_channels`/`scan_records` 加 `subject_id`,并把已有数据回填到「每人一个主体」 || `20261019233000-drop-has-ptz-from-cameras` | 删除 `cameras.has_ptz`(预览统一显示云台面板,后端不再标记是否支持云台) |
| `20261024100000-add-workstation-login-fields` | `workstations.login_code`(登录码 `WSC-` 前缀,唯一)/ `last_active_at`(最后活跃时间)/ `idle_timeout_sec`(多少秒不活跃自动下线,团购 3600 / 散单 1800),并回填已有工作台(⚠️ `login_code` 已被 `20261028121000` 删除) |
| `20261024101000-create-workstation-login-records` | 新表 `workstation_login_records`(工作台成员登录记录,含 `(workstation_id, login_at)` 等索引) |
| `20261024102000-add-workstation-camera-label-flag` | `workstation_cameras.is_label_camera`(面单摄像头标记,仅散单工作台;一台工作台最多一路) |
| `20261028120000-create-wechat-gateway-bindings` | 新表 `wechat_gateway_bindings`(微信登录网关绑定:`user_id` / `app_key` / `openid`(唯一)/ `unionid` / `bind_scene` / `last_login_at`) |
| `20261028121500-add-subject-member-temp-user` | `subject_members.temp_user_id`(扫码绑定时自动建给成员的临时账号;被已有账号继承时该账号会被删除) |
| `20261028121000-drop-workstation-login-code` | 删除 `workstations.login_code`(`WSC-` 登录码已废弃,扫码登入改走微信登录网关的一次性二维码);`workstation_login_records.login_code` 保留作历史 |
| `20261029100000-drop-legacy-wechat-tables` | 删除 `wechat_oauth`(自建公众号网页授权)与 `wechat_mp_accounts`(小程序 code2Session 一键登录):微信侧接入已统一走登录网关;`down` 按原结构重建两张空表 |
| `20261029120000-create-admin-members` | 新表 `admin_members`(平台管理员:`user_id` 唯一、`name`、`role`、`status`、`remark`)+ 把内置管理员(`username='admin'`,没有就 `id=1`)先入表 |
> 历史遗留的 `sql/schema.sql` + `sql/migrations/*.sql`(用 `npm run db:init` 执行)是接入 sequelize-cli 之前的做法,
> 只用于初始化老表;**新变更一律写 `database/migrations/*.js`**。

View File

@ -162,6 +162,9 @@ function normalizeDeployConfig(config, envName) {
[ /^KbdInteractiveAuthentication=/i, 'KbdInteractiveAuthentication=no' ],
[ /^BatchMode=/i, 'BatchMode=yes' ],
[ /^ConnectTimeout=/i, 'ConnectTimeout=10' ],
// 链路静默断开时(NAT 超时 / 网络抖动)不要无限期挂着,45 秒内判定失败
[ /^ServerAliveInterval=/i, 'ServerAliveInterval=15' ],
[ /^ServerAliveCountMax=/i, 'ServerAliveCountMax=3' ],
];
for (const [ matcher, option ] of requiredSshOptions) {
if (!sshOptions.some(item => matcher.test(item))) {
@ -272,6 +275,9 @@ function buildSshBaseArgs(config) {
function runSsh(config, remoteScript, options = {}) {
const args = [
// -n:不读本机 stdin。发布命令全是非交互的;Windows 终端下 ssh 继承控制台 stdin 时
// 偶尔会在远端命令结束后迟迟不退出(发布脚本就卡在「远端目录已就绪」之前)
'-n',
...buildSshBaseArgs(config),
`${config.username}@${config.host}`,
`bash -lc ${quoteForBash(remoteScript)}`,

View File

@ -9,6 +9,9 @@
*
* 账号不存在时自动创建(username = 账号,status = 1);
* 账号存在时只重置密码。密码经 bcrypt 哈希后写入 users.password_hash。
*
* ⚠️ 重置密码时**同时写 `password_changed_at`**:与 app/service/user.js#setPassword 一致,
* 这样改密前签发的旧 JWT 会立即失效(middleware/api_auth.js 比对 `iat`)。
*/
const mysql = require('mysql2/promise');
@ -42,7 +45,10 @@ async function main() {
if (rows.length) {
const user = rows[0];
await conn.query('update users set password_hash = ?, updated_at = now() where id = ?', [ hash, user.id ]);
await conn.query(
'update users set password_hash = ?, password_changed_at = now(), updated_at = now() where id = ?',
[ hash, user.id ],
);
console.log(`[user:pass] 已重置密码: ${user.username || user.phone || user.email} (id=${user.id})`);
} else {
const [result] = await conn.query(

View File

@ -42,10 +42,10 @@ desktop/
| 场景 | 行为 |
| --- | --- |
| 首次启动 | 先起本机服务(17300 HTTP + 17301 WS)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 启动时检查更新 | **不等登录**:进入登录页的同时就开始查 `GET /download/version.json`,有新版本会把更新窗盖在登录页上(否则老版本用户永远卡在登录页收不到更新) |
| 启动时检查更新 | 进登录页的同时就开始查 `GET /download/version.json`(老版本用户卡在登录页也能收到提示)。**查到的版本不会塞进登录窗的模态循环**:登录窗还开着就先记下,等主窗口显示完再弹(`_pendingUpdate`)。以前直接盖在登录页上,会撞上「登录窗要关闭、但它挂着模态子窗」→ 父子窗一起被隐藏、两个模态循环互等,**主界面永远出不来**(日志停在 `已恢复登录` 之后,进程还在但没有任何窗口) |
| 已有令牌 | 登录窗一闪而过:`/api/web/me` 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例 |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例;**没带参数(双击快捷方式)也会转发一条 `--show`**,让已运行实例把主界面叫到前面 —— 以前这种情况什么都不发、第二个实例直接退出,表现就是「点图标没反应」 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 托盘右键「重启软件」 | 等 2 秒后拉起新进程(先退出才能释放单实例互斥体与 17300) |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
@ -625,6 +625,8 @@ reg query "HKCU\Software\Classes\yuncang\shell\open\command"
| 启动报「句柄无效」/ `句柄无效 (6)` | 老版本用 `HttpListener`(HTTP.sys)才会这样:系统的 HTTP 服务被禁用或卡在 STOP_PENDING。本次修复起本机服务改成自建 TcpListener,不再依赖 HTTP.sys;老版本临时处理可 `net start http` 或重启电脑 |
| 启动报「没有绑定端口的权限」/ `Access is denied (5)` | 端口被安全软件拦了;换端口(`YUNCANG_LOCAL_PORT`)或加白名单 |
| 报端口被占用(`AddressAlreadyInUse`) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 双击图标没反应 / 主界面打不开,托盘图标还在 | 1.0.134 起:再次启动会把已运行实例的主界面叫到前面(托盘双击也行)。更老的版本点了没反应是正常的(第二个实例直接退出),从托盘打开即可 |
| 升级后主界面仍然出不来 | 看日志最后几行:停在 `准备显示更新窗口…` 之后就是老版本的「更新窗盖在登录窗上」死锁,装新版本即可;有 `[app] 主窗口没建:server=… session=… api=…` 说明登录态没建立 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17300/api/query/`(会回 400 但带登录状态):打不开→防火墙/端口;打得开→多半是 CORS 头没回。预览类问题则看 `ws://127.0.0.1:17301/` 能不能打开(直接浏览器访问应该返回一小段 JSON) |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 `bin\Debug` 这类 framework-dependent 的 exe(拿不到 `DOTNET_ROOT`)。用自包含发布产物,并让它启动一次以校正注册表 |
@ -633,9 +635,12 @@ reg query "HKCU\Software\Classes\yuncang\shell\open\command"
## 主体切换 / 微信扫码登录 / 设备服务(2026-10-18)
### 登录窗
- **微信扫码登录**:点「微信扫码登录」→ `GET /api/wechat/login` 发码 → 显示二维码
(`GET /api/wechat/qrcode.gif?code=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
`GET /api/wechat/login?code=&wait=25`,手机确认后直接拿令牌进主界面;码过期会自动换新。
- **微信扫码登录**(2026-10-28 起走微信登录网关):点「微信扫码登录」→
`POST /api/web/auth/wechat-gateway/qrcode` 申请二维码 → 显示二维码
(`GET /api/wechat-gateway/qrcode.gif?state=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
`GET /api/web/auth/wechat-gateway/login?state=&wait=25`,手机微信确认后直接拿令牌进主界面;
二维码过期(`expired`)会自动重新申请一张,绑定状态不对(`failed`)直接把服务端给的原因显示在二维码下面。
⚠️ 只有**已经绑定过微信**的账号才能扫码登录(绑定入口在网页版「个人中心 → 微信绑定」)。
- 账号密码登录与微信登录**都会带回主体列表**(`subjects`),主界面右上角显示当前主体。
### 主界面
@ -758,14 +763,157 @@ reg query "HKCU\Software\Classes\yuncang\shell\open\command"
- 服务模式:桌面端只写通道文件,后台服务发现文件时间变了会重新加载并重连
(日志 `[agent] channels.json 已变更,重新加载通道`)。
### 面单摄像头(独立页签:配置 + 拉流识别)
「面单摄像头」是**单独的页签**(与「扫码通道/扫码记录」一起显示),每路一行:
`工作台 | 摄像头 | 上报通道 | 状态(识别中/启动中/异常/已停止) | 最近识别到的条码 | 首次识别时间 | 最近命中 | 码流 | 解码耗时 | 次数 | 备注`。
- **首次识别时间**:这条记录真正拿去上报/落库的时间,面单一直摆在拍摄区**不会刷新**(重复命中不改时间);
- **最近命中**:摄像头最近一次解码成功的时刻,每秒都在跳,只用来判断「摄像头有没有在看/对着条码」;
- **码流**:当前实际用的是主码流还是子码流、分辨率多少;
- **解码耗时**:最近一帧「OpenCV 检测 + 透视矫正 + ZXing 解码」花了多少毫秒,用来判断机器吃不吃得消;
- 行是按 `工作台|摄像头|通道` 原地更新的(不整体重画),只有值真变了才会重绘。
顶部状态行显示 `已拉取 N 路 · 时间`,底部的黄字是服务端提示(例如「摄像头找不到录像机」「录像机没有保存密码」)。
数据来源:服务模式下由**后台服务**拉配置 + 识别,界面读 `agent-status.json` 的 `LabelScan`
(后台服务每 **400ms** 写一轮、界面每 **300ms** 轮询一次,识别到就是几百毫秒内能看到);
普通模式下直接读本进程 `ScanService.LabelScan`。
#### 配置拉取(`LabelScanMonitor`)
- 服务启动拉一次 + **每 1 分钟**兜底(推送可能丢:设备正好离线、edge 任务 TTL 过期、推送失败);
以前是 5 分钟,现场在网页上改完面单摄像头要等好几分钟才生效,看起来就是「取消的那路还在跑、新增的不启动」;
- 收到 `labelScan.refresh`(**服务端**在 Web 端改了面单摄像头/工作台/上报通道后主动推的 edge 任务)立即重拉;
- 记住 `revision`:内容变了才写一条「配置变更」日志;
- 拉完就**对账**:新增的启动识别、配置变了的重建、消失的停掉;没变的不打断(轮询很密,不能断流);
- 对账单路失败(构造/启动异常)只记日志并清掉半成品,**不影响其它路**,下一轮会重试。
#### 识别(`LabelScanWorker`)
```
ffmpeg(RTSP, tcp) → 灰度 rawvideo 帧 → 读帧线程只留最新一帧(按 DecodeFps 限速)
→ OpenCV BarcodeDetector 整图检测(cv::barcode,输出条码四角点,带旋转/透视)
→ 无候选 = 画面里没面单,直接丢掉
→ 有候选:逐个透视矫正成轴对齐小图 → ZXing 解 CODE_128 → CleanBarcode 校验
→ 命中入队(扫描线程不等) → 上报线程:写记录 + 立即上报 + 通知安卓播报
```
- **为什么用 OpenCV 检测而不是自己找 ROI**:现场面单是**竖放或斜着**摆的(实测四角点
`(433,602)(450,514)(1371,685)(1354,774)`,倾斜约 5°)。1D 码要求扫描线完整穿过整条,
按「行梯度能量」找横带再轴对齐裁剪,会把条码截断 → **必然解不出**(实测 0 命中)。
OpenCV 给的是四角点,透视矫正后条码完整,实测 1920×1080 整图 **检测约 10~15ms + 解码约 1ms**,
3/3 帧命中、无面单画面 3/3 帧 0 候选(无假阳性)。
- **退避(隔帧检测)**:① 同一个码连续命中 3 次(面单没动)② 连续 3 帧没结果(画面里没面单)→ 之后隔帧检测;
一旦**画面变化**(面单拿走/换新/有人手伸进来,靠 32×18 缩略图平均灰度差 > 6 判定)立刻恢复全帧率。
实测面单摆着不动时 CPU 直接减半,新面单放上去不额外延迟。
- **选流**:先试子码流,**宽度够 1080 才用**(拉流解码开销只有主码流的 1/7,更省 CPU);
太小就退回主码流并在日志里说明。实测这台录像机子码流 800×448,条码只有 1.8px/模块,
同样设置**读不出来**;把子码流调到 1280×720 即可自动启用;
- **延迟**:`ffmpeg -threads 2`。HEVC 默认帧级多线程会把输出往后压好几帧 ——
用画面里的时间水印实测「OSD 时间 → 本机收到帧」:默认线程 **2.6s**、`-threads 1/2` **0.5s**、
加 `-fflags nobuffer -flags low_delay` 反而更慢(2.9s)。输入 20fps、我们只取 8fps,2 线程完全够;
- **不积压**:读帧线程始终把管道读空、只保留最新一帧,旧帧直接丢(`FrameLag` 恒为 0~个位数);
上报走独立线程 + 8 条缓冲队列,写记录/上报/通知安卓再慢也不会拖住识别;
- **RTSP 通道序号**:库里存的是设备通道号(数字通道从 33 起),RTSP 要 1 起序号,
所以按 `channelNo-32 → channelNo` 依次探测,成功后**记住**(日志 `码流就绪:主码流 2304x1296(序号 3201)`);
- 条码过滤:4~64 位、只含常见条码字符、**至少 6 位数字**(压掉摄像头误识别噪声);
- 同一张面单连续命中节流到 500ms 一次:足够维持「在场」状态,又不会刷上报;
- 断流自动重连(3 秒),连续失败按 3/10 次节流打日志;不影响扫码枪链路。
排障字段(`agent-status.json` 的 `LabelScan.Items[]`):
| 字段 | 含义 |
|---|---|
| `LastPath` | `OpenCV解码` / `无候选` / `候选未解出` / `稳态退避` / `失败退避` |
| `LastCvMs` | OpenCV 整图检测耗时 |
| `LastDecodeMs` | 透视矫正 + ZXing 解码耗时 |
| `RoiText` | 矫正后的条码尺寸(如 `条码 937x90`),或 `无候选` |
| `RoiRatio` | 矫正+解码耗时(毫秒) |
| `FrameLag` / `FrameDropped` | 取帧时的积压帧数 / 累计丢弃旧帧数(正常应接近 0) |
| `FramesRead` / `FrameThrottled` / `FramesDecoded` | 管道读到 / 限速丢弃 / 实际处理 的帧数 |
| `LastWaitMs` / `LastLoopMs` | 等新帧耗时 / 两次取帧的完整周期(看瓶颈在「帧不够」还是「处理慢」) |
| `RoiFailStreak` / `SteadyHits` | 连续无结果次数 / 连续命中次数(≥3 触发隔帧退避) |
日志样例:
```
[label-scan] 已拉取面单识别配置(启动):1 路,revision=sha1:df244c17781de5ba
[label-scan] 散单1号 → 测试散单面单(241 通道 64,主码流)→ 上报通道 2「测试安卓」
[label-scan] 散单1号 → 测试散单面单… 子码流只有 800x448(条码像素不够,读不出来),改用主码流
[label-scan] 散单1号 → 测试散单面单… 码流就绪:主码流 2304x1296(序号 3201)
[label-scan] 识别到条码:SF1164748936737(通道 2,首次 10-24 16:19:26,倾角 -12°,解码 38ms,新记录=True,播报=True)
```
页签里的「码流」「解码耗时」两列就是上面这些信息,现场调机位时能直接看出问题在哪一层。
⚠️ 配置快照里含录像机密码:只放内存,不落盘、不写日志、界面文案也不显示。
### 摄像头识别结果 → 记录 + 安卓播报通知
在「工作台 → 绑定管理」里把某路摄像头设为**面单摄像头**(每个工作台只保留一路,散单/团购都能设)后,识别到的条码
统一走 `ScanService.ReportCameraScanAsync(channelId, channelName, code, wsType)`。
**与扫码枪的差别(现场场景:面单放进拍摄区 → 开始打包 → 打包完才取走)**:
| | 扫码枪(团购) | 面单摄像头(散单) |
|---|---|---|
| 时间 | **最后一次**扫描(包裹离开扫码器) | **第一次**识别(面单进入拍摄区);面单没离开画面就**永不前移** |
| 上报时机 | 静默 5 秒后 | **写入即上报**(`ScanRecordItem.Immediate`) |
| 视野内重复命中 | 刷新时间 | **什么都不做**(不改时间、不重复上报、不重复播报) |
| 中途被手挡/移位/反光(面单还在画面里) | 刷新成新时间 | **仍算同一轮,时间不前移** |
| 面单真的被拿走(画面里连续 45 秒没有任何条码)后再放回 | 刷新成新时间 | 当作**新一轮打包**,用**这次**的时间(装错了重新打包、20 分钟后重新称重再包一遍都属于这种) |
**工作台类型决定规则**(后端下发的 `wsType`,见 `LabelScanMonitor.ModeOf`):
| | 散单(wsType=1) | 团购(wsType=2) |
|---|---|---|
| 面单摄像头识别 | 取**第一次** + 立即上报 | 和扫码枪一样:静默 5 秒、取**最后一次** |
| 扫码枪 | 同样取**第一次** + 立即上报(`DeviceService.ReportFirstSeen`,5 秒内重复算一次) | 静默 5 秒、取**最后一次**(不变) |
**工作台没接扫码枪也能用**(摄像头完全替代扫码枪):服务端会给这种工作台一条**虚拟通道**
`CAM-<工作台id>`(名字 `面单摄像头·<摄像头名>`),下发的 `items[].virtualChannel = true`。
设备端照常上报即可,差别只有:
- 通道名从配置里取(`LabelScanMonitor.ChannelNameOf`),因为 `CAM-` 不在本机 `channels.json` 里;
- `channels[]` 里也会带这条虚拟通道,所以记录规则照旧按 `wsType` 走;
- 虚拟通道没有对应的扫码工位,`NotifyScanSuccessAsync` 找不到安卓通道 → **不播报**(正常现象);
- 这类工作台在 Web 端「绑定管理」里看不到「没绑扫码通道」的警告,虚拟通道带「虚拟」标记、不给解绑。
- **「离开」只有一个判据**:画面里**连续 45 秒没有任何条码**(`LabelScanWorker.RepackAbsence`)。
识别线程和上报层共用这个值(`ScanService.CameraPresenceGap` = 它),避免出现
「算重新进去了、但时间没更新」的漏洞。在场状态是**按「通道|条码」**记的,
所以换一张新面单永远是新建记录、不受这个值影响。
- **为什么用「画面里有没有条码」而不是「有没有解出码」**:接入 OpenCV 后 `无候选` 是可信的
(面单在视野里就一定有候选);而「解不出」还会发生在面单明明在场的时候(反光、遮住一角)。
- **时间绝不因为识别空档前移**(这是修过的现场问题):面单一直摆着、中途被手挡一会儿,
以前会被当成「离开又回来」,加上这中间通道上又扫过别的包裹,打包时间直接被改成
「开始打包 30 秒之后」,录像定位整体偏移。**「中间扫过别的包裹」不是重新打包的信号**
—— 两张面单轮流进入视野就会命中,但那两张都没离开过。
- **真正的新一轮打包会被识别**:面单被拿走(画面里连续 45 秒没有条码)后再放回,
记录时间更新成这一次(`ScanService.ResolveCameraScanTime` 的 `afterAbsence`)。
例如 20 分钟后发现称重不对、开箱重装再包一遍 —— 只要换货期间面单离开了画面就成立。
- **时间只认记录**:上报/界面显示的时间都取本地记录里那条的 `ScannedAt`,
在场判定只决定「要不要重新上报一次 + 时间要不要更新」,服务重启、丢帧都不会把时间推后;
- **记录永远写**:与通道类型、安卓是否在线、设备服务是否开启无关。断网/离线只是留在本地队列等重试;
- **通知要回执**:只对 `AndroidStation` 通道发 `0x1E{"cmd":"scan","id":…,"code":…}\n`,
等设备回 `0x1E{"cmd":"ack","id":…}\n`(1.2 秒超时,最多重发 2 次)。
`CameraScanResult.Notified=false` 只代表「没确认到播报」,**不代表没记上**;
网口扫码枪没有语音能力,不发(避免被透传到枪的串口)。
**设备端要求 AndroidStation ≥ 1.0.3**:1.0.1 还不认识 0x1E 控制帧(表现为「安卓端没回执」),
1.0.2 起会把 ack 里的 id 过滤掉非字母数字字符导致桌面端永远比对不上,1.0.3 已改成原样回显。
### 界面
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 N 个(在线 M)` + 通道同步状态 + 待上传条数)+ `重连全部` / `静音`(选中行切换,已静音时叫「恢复蜂鸣」)/ `读取设备配置` / `重命名` / `删除通道`(后三个都要先选中一行);
通道列表有「状态」「静音」两列;
通道列表有「类型」「状态」「静音」三列(类型 = `安卓扫描通道` / `扫码枪`,来自 UDP 发现应答的设备型号,
`AndroidStation` 才标成安卓扫描通道。**只有安卓扫描通道需要「扫码成功」通知**:摄像头识别到条码时
通知它播报语音;扫码枪通道没有语音能力,不发。**记录一直在写,与通道类型/在线状态无关**);
**没有「同步通道」按钮** —— 通道增删/启停都会自动上传并回查确认;
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`)。
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`);
发现列表和「添加通道」弹窗都会标注 **安卓扫描通道**(型号 `AndroidStation`),添加时把型号一起落进 `channels.json`。
- **已经添加为通道的设备不会再出现在发现列表里**:显示集合与「发现到的全集」分开存(`_allDevices` / `_devices`),
按通道 MAC 过滤;删掉通道后那台设备会自己回到列表里,不用重新扫。每轮结果按 MAC 合并,不整表覆盖(UDP 丢包时设备不会闪没)。
- 扫码记录页(对应 AndroidScanCenter 的「通道回放」,`Views/ScanRecordsView`):