diff --git a/backend/README.md b/backend/README.md index 29f37d0..0e0b26f 100644 --- a/backend/README.md +++ b/backend/README.md @@ -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: ' 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(固定账号,方便联调); +传其它 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_`(重名加随机后缀)、 + 随机密码(等于没有密码,需要用「找回密码」设置后才能密码登录),`firstTime: true`; +- 已绑定 → 复用原账号,校验 `users.status`(禁用 → 403); +- 与账号密码登录共用协议校验:`client='mini_program'` 未同意当前协议版本 → **428** `agreement_required`; +- 签发令牌 / 记录同意 / 带主体列表的逻辑在 `app/service/login.js`(两种登录共用)。 + diff --git a/backend/package.json b/backend/package.json index 4c9e6ee..5d9ffda 100644 --- a/backend/package.json +++ b/backend/package.json @@ -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", diff --git a/backend/scripts/db-deploy.js b/backend/scripts/db-deploy.js new file mode 100644 index 0000000..1c56d9e --- /dev/null +++ b/backend/scripts/db-deploy.js @@ -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); +});