chore(db): 新增 npm run db:deploy,部署时一次执行全部库结构变更

- scripts/db-deploy.js:建库(有权限时) → 基线表 sql/schema.sql → 全部未执行的 database/migrations,
  幂等可重复执行;--check 只列出待执行迁移(有 pending 时退出码 1),便于上线前/CI 卡一道
- 保留仓库内所有迁移脚本:sql/migrations 历史补丁、database/migrations、一次性数据脚本都不删不改,
  顺序与用途写进 README「部署 / 升级(库结构)」

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-10-20 21:26:30 +08:00
parent 7b11f7052d
commit 413bd9f981
3 changed files with 252 additions and 6 deletions

View File

@ -84,11 +84,17 @@ packService/backend
│ └── plugin.unittest.js # 单测环境关闭 DB 相关插件
├── scripts
│ ├── db-config.js # 脚本共用的连接信息解析
│ ├── init-db.js # 执行 sql 下的 SQL 文件(npm run db:init [file])
│ ├── db-deploy.js # **部署/升级一次执行**:建库 + 基线表 + 全部未执行迁移(npm run db:deploy [--check])
│ ├── init-db.js # 执行单个 SQL 文件(npm run db:init [file]),给历史补丁用
│ ├── backfill-snapshot.js # 一次性回填:老扫码记录补工作台快照
│ ├── dedupe-scan-records.js # 一次性去重:24 小时内同一运单只留一条
│ └── set-password.js # 创建用户/重置密码(npm run user:pass -- 账号 密码)
├── database
│ ├── config.cjs # sequelize-cli 配置(与运行时同一份连接信息)
│ └── migrations/ # Sequelize 迁移(按文件名顺序,SequelizeMeta 记账,只跑没跑过的)
├── sql
│ ├── schema.sql # 建表脚本(幂等)
│ └── migrations/ # 一次性数据迁移脚本
│ ├── schema.sql # 基线表(幂等,db:deploy 第 1 步执行)
│ └── migrations/ # 历史一次性 SQL 补丁(仅老库需要,保留不删)
├── test
│ ├── utils/fake-redis.js # 单测用的内存版 Redis
│ └── utils/internal.js # 内部接口鉴权 header(X-Internal-Token)
@ -106,9 +112,10 @@ npm install
# - redis.client.password / db = Redis 的密码(无密码写 null)与库序号(本机用 1)
# 也可以改用环境变量 MYSQL_PASSWORD / REDIS_PASSWORD / REDIS_DB
# 3. 建表(库 packservice 需已存在,账号 packservice 仅有该库权限)
npm run db:init
# 如果是旧版本库,按顺序补跑迁移:
# 3. 建表 / 升级(**部署时只需这一条**:建库(有权限时) + 基线表 + 所有未执行的迁移,可反复执行)
npm run db:deploy
# npm run db:deploy -- --check # 只检查还剩哪些迁移没执行(CI / 上线前确认,不改库)
# 老版本的库照常补跑遗留 SQL 补丁(这些脚本都保留在 sql/migrations,新库不需要):
# npm run db:init sql/migrations/20261016_rebuild_users.sql # users 表结构重建
# npm run db:init sql/migrations/20261016_add_user_password.sql # 增加 password_hash
# npm run db:init sql/migrations/20261016_devices_to_scanners.sql # 删掉旧的 devices 表(改用 scanners)
@ -141,6 +148,32 @@ curl -H 'X-Internal-Token: <INTERNAL_TOKEN>' http://127.0.0.1:7300/api/users #
> 后端只管接口:页面在 `../frontend/`(`npm run dev` 起在 7301)。
> 联调推荐**只开后端地址** `http://127.0.0.1:7300`(dev 环境自动把页面请求反代给前端);也可以直接开前端 7301(Vite 把 `/api` 反代到 7300)。
## 部署 / 升级(库结构)
**一次执行**,幂等,可反复跑:
```bash
cd backend
npm install
npm run db:deploy # ① 建库(有权限时) ② 基线表 sql/schema.sql ③ 全部未执行的 database/migrations
npm run db:deploy -- --check # 只检查(列出未执行的迁移;有 pending 时退出码 1),适合上线前/CI 卡一道
```
规则(**所有迁移脚本都保留在仓库里,不删不改**):
| 位置 | 作用 | 什么时候跑 |
|---|---|---|
| `sql/schema.sql` | 基线 6 张表(`CREATE TABLE IF NOT EXISTS`,幂等) | 每次 `db:deploy` 第 2 步自动跑 |
| `database/migrations/*.js` | 全部结构变更 / 数据回填(`SequelizeMeta` 记账) | 每次 `db:deploy` 第 3 步自动跑,**只跑没跑过的** |
| `sql/migrations/*.sql` | 历史一次性补丁(重建 users、加列、删旧 devices 表) | **仅老库升级时手动补跑**,新库已包含最终结构,重复执行会 `Duplicate column` |
| `scripts/backfill-snapshot.js`、`scripts/dedupe-scan-records.js` | 一次性数据修复(需带参数,可 `--dry-run`) | 按需手动,不是部署必跑 |
执行顺序固定为「基线表 → 迁移(按文件名升序)」,所以新库和老库走同一条命令,结果一致;
连接信息与运行时同源(环境变量 > `config/config.local.js` > 默认值)。
> 生产库如果由 DBA 预建、且应用账号没有建库权限,`db:deploy` 会打印一行「跳过建库」后继续,不影响后续迁移。
## 单元测试
```bash
@ -906,3 +939,44 @@ FROM user_agreements WHERE user_id = ? ORDER BY agreed_at DESC;
```
⚠️ 种子迁移里的协议正文是**占位示例**,正式上线前务必替换为法务确认后的文本。
## 微信小程序登录(2026-10-20)
独立的小程序登录模块:`code2Session` 换 openid → 按 openid 找绑定账号 → 未绑定则自动建账号。
### 数据表
| 表 | 用途 |
|---|---|
| `wechat_mp_accounts` | 小程序 openid 与平台账号的绑定:`(appid, openid)` 唯一,`user_id` 为空表示已解绑;另存 unionid / session_key / 最近登录 |
与公众号的 `wechat_oauth` 分开:小程序是「一个 openid 对一个平台账号」,解绑只清 `user_id`,记录保留。
### 配置
| 环境变量 | 说明 |
|---|---|
| `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。
### 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| 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,先设密码) |
登录细节:
- 未绑定过的 openid → 自动创建平台账号:用户名 `wx_<openid 尾 12 位>`(重名加随机后缀)、
随机密码(等于没有密码,需要用「找回密码」设置后才能密码登录),`firstTime: true`;
- 已绑定 → 复用原账号,校验 `users.status`(禁用 → 403);
- 与账号密码登录共用协议校验:`client='mini_program'` 未同意当前协议版本 → **428** `agreement_required`;
- 签发令牌 / 记录同意 / 带主体列表的逻辑在 `app/service/login.js`(两种登录共用)。

View File

@ -36,6 +36,7 @@
"test": "egg-bin test",
"cov": "egg-bin cov",
"db:init": "node scripts/init-db.js",
"db:deploy": "node scripts/db-deploy.js",
"db:migrate": "sequelize-cli db:migrate",
"db:migrate:undo": "sequelize-cli db:migrate:undo",
"db:migrate:status": "sequelize-cli db:migrate:status",

View File

@ -0,0 +1,171 @@
'use strict';
/**
* 部署 / 升级时**一次执行**的库结构脚本(幂等,可反复跑)
*
* npm run db:deploy # 建库(缺则建) + 基线表 + 全部未执行的迁移
* npm run db:deploy -- --check # 只检查:列出还没执行的迁移,不改库
* npm run db:deploy -- --dry-run # 同上(别名)
*
* 执行顺序(**所有迁移脚本都保留在仓库里**,这里只是按固定顺序跑一遍):
* 1. `sql/schema.sql` 基线表(CREATE TABLE IF NOT EXISTS,可重复执行)
* 2. `database/migrations/*.js` Sequelize 迁移(靠 SequelizeMeta 记账,只跑没跑过的)
*
* `sql/migrations/*.sql` 是**历史一次性补丁**(重建 users、加列、删旧 devices 表),
* 只为老库保留:新库的 schema.sql 已经包含最终结构,重复执行会报 Duplicate column。
* 需要给很老的库补跑时手动执行,见 README「快速开始」。
*
* 连接信息与运行时同源:环境变量 > config/config.local.js > 默认值(scripts/db-config.js)。
*/
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
const mysql = require('mysql2/promise');
const resolveDbConfig = require('./db-config');
const ROOT = path.join(__dirname, '..');
const SCHEMA_FILE = path.join(ROOT, 'sql', 'schema.sql');
const MIGRATIONS_DIR = path.join(ROOT, 'database', 'migrations');
const META_TABLE = 'SequelizeMeta';
const args = process.argv.slice(2);
const checkOnly = args.includes('--check') || args.includes('--dry-run');
/** 去掉 -- 行注释,再按分号切分成可逐条执行的语句(与 init-db.js 同一套规则) */
function splitStatements(sql) {
return sql
.split(/\r?\n/)
.filter((line) => !line.trim().startsWith('--'))
.join('\n')
.split(';')
.map((stmt) => stmt.trim())
.filter(Boolean);
}
/** 仓库里的全部迁移文件名(按文件名升序 = 执行顺序) */
function migrationFiles() {
if (!fs.existsSync(MIGRATIONS_DIR)) return [];
return fs.readdirSync(MIGRATIONS_DIR)
.filter((name) => name.endsWith('.js'))
.sort();
}
/** 已执行的迁移名(元数据表不存在 = 一条都没跑过) */
async function appliedMigrations(conn) {
try {
const [rows] = await conn.query(`SELECT name FROM \`${META_TABLE}\` ORDER BY name`);
return rows.map((row) => row.name);
} catch (err) {
if (err.code === 'ER_NO_SUCH_TABLE') return [];
throw err;
}
}
async function connect(config, database) {
const options = { host: config.host, port: config.port, user: config.user, password: config.password };
if (database) options.database = database;
return mysql.createConnection(options);
}
/** 库不存在就建(账号没有建库权限时只告警,交给 DBA 预先建好) */
async function ensureDatabase(config) {
const conn = await connect(config);
try {
await conn.query(
`CREATE DATABASE IF NOT EXISTS \`${config.database}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`,
);
console.log(`[db:deploy] 数据库就绪:${config.database}`);
} catch (err) {
console.warn(`[db:deploy] 跳过建库(${err.code || err.message}),请确认库 ${config.database} 已由 DBA 建好`);
} finally {
await conn.end();
}
}
/** 基线表:schema.sql 全部是 CREATE TABLE IF NOT EXISTS,重复执行安全 */
async function applyBaseSchema(conn) {
const statements = splitStatements(fs.readFileSync(SCHEMA_FILE, 'utf8'));
console.log(`[db:deploy] 应用基线表:sql/schema.sql(${statements.length} 条语句)`);
for (const stmt of statements) {
await conn.query(stmt);
}
}
/** 执行 sequelize-cli(走本地依赖,不联网) */
function runSequelizeMigrate() {
const cli = require.resolve('sequelize-cli/lib/sequelize');
const result = spawnSync(process.execPath, [ cli, 'db:migrate' ], {
cwd: ROOT,
stdio: 'inherit',
env: process.env,
});
if (result.status !== 0) {
throw new Error(`sequelize-cli db:migrate 退出码 ${result.status}`);
}
}
async function main() {
const config = resolveDbConfig();
console.log(`[db:deploy] 目标:${config.host}:${config.port}/${config.database} as ${config.user}`);
if (checkOnly) {
const conn = await connect(config, config.database);
try {
const applied = new Set(await appliedMigrations(conn));
const pending = migrationFiles().filter((name) => !applied.has(name));
console.log(`[db:deploy] 已执行 ${applied.size} 条,待执行 ${pending.length} 条`);
for (const name of pending) console.log(` pending ${name}`);
if (pending.length) process.exitCode = 1;
} finally {
await conn.end();
}
return;
}
await ensureDatabase(config);
const conn = await connect(config, config.database);
try {
await applyBaseSchema(conn);
} finally {
await conn.end();
}
const before = new Set();
const conn2 = await connect(config, config.database);
try {
for (const name of await appliedMigrations(conn2)) before.add(name);
} finally {
await conn2.end();
}
console.log(`[db:deploy] 执行 SQL 迁移:database/migrations(${migrationFiles().length} 条,已执行 ${before.size} 条)`);
runSequelizeMigrate();
const conn3 = await connect(config, config.database);
try {
const applied = await appliedMigrations(conn3);
const pending = migrationFiles().filter((name) => !applied.includes(name));
const done = migrationFiles().filter((name) => !before.has(name));
for (const name of done) console.log(` applied ${name}`);
if (pending.length) {
console.warn(`[db:deploy] ⚠️ 仍有 ${pending.length} 条未执行:${pending.join(', ')}`);
process.exitCode = 1;
return;
}
const [tables] = await conn3.query('SHOW TABLES');
const names = tables.map((row) => Object.values(row)[0]);
console.log(`[db:deploy] 完成:本次执行 ${done.length} 条迁移,库内 ${names.length} 张表`);
} finally {
await conn3.end();
}
}
main().catch((err) => {
console.error(`[db:deploy] 失败:${err.code || ''} ${err.message}`);
process.exit(1);
});