feat(frontConfig): 前端独立部署域名两阶段切换(pending 登记 + TXT 校验通过后提升)

- 迁移 20260924180000-add-pending-domain-to-wms-warehouse-front-config
  新增 pending_* 6 列、retired_domain/retired_at 与 idx_pending_domain/idx_retired_domain
  两个索引(生产库已执行)
- setDomain 只登记待验证域名并下发 TXT 校验码,不再「设置即生效」;
  TXT 校验通过后由 promotePendingDomain 提升(旧域名写入 retired_domain 下线队列、
  清空证书 5 列并重置同步状态),消除「改域名瞬间旧域名公共接口 404」中间态
- DoH 解析改为多端点顺序尝试(dohUrls:alidns → 223.5.5.5 → doh.pub),
  单端点 NODATA/NXDOMAIN 不再直接判定,必要时降级系统 DNS 并显式限时;
  config.frontConfig.domainVerify 同步 batchSize 50→20、timeoutMs 5000→3000
- getDomain/setDomain/checkDomain 响应追加待验证域名组 7 字段(旧 9 字段口径不变)
- 同步 methods 文档(frontConfig 6 方法)与 changes 4 条变更记录、
  AI_METHOD_ROUTING.md 函数清单(42→50)

注:本提交补齐此前已在生产库执行但从未入库的迁移与代码
(生产 SequelizeMeta 已含 20260924180000,属 orphan meta 补齐入库)。
This commit is contained in:
liufumingren 2026-09-25 23:40:56 +08:00
parent 1cccc6b4a4
commit 3f5eb49081
8 changed files with 1423 additions and 229 deletions

View File

@ -593,8 +593,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods
- buildTree, getTreeByType, buildSubTree, getWithChildrenByType, getAllChildren, getByType, getGroups, getChildrenByPid, getTreeChildrenByPid, create, update, findById, delete
- app/service/systems/file.js (2)
- getImages, ReferenceFile
- app/service/systems/frontConfig.js (42)
- createError, getCurrentWarehouseId, deleteCacheByKey, normalizeText, normalizeTheme, assertDomainUnique, getRecordField, sanitizeErrorText, getDomainVerifyConfig, getCnameTarget, buildDomainVerifyCode, parseTxtAnswerData, extractTxtValuesFromAnswers, resolveTxtByDoh, resolveTxtBySystem, resolveTxtValues, verifyDomainRecord, isUnknownColumnError, findVerifiedDomainRecord, verifyPendingDomains, buildInfoOutput, buildCertOutput, getInfo, getCert, getDomain, setDomain, checkDomain, buildDomainOutput, describeDomainStatus, getDomainCacheKey, buildPublicOutput, clearDomainCache, getByDomain, normalizePem, parseCertPem, assertCertValid, collectCertNames, certCoversDomain, validateKeyPem, assertWarehouseSubject, saveInfo, saveCert
- app/service/systems/frontConfig.js (50)
- createError, getCurrentWarehouseId, deleteCacheByKey, normalizeText, normalizeTheme, assertDomainUnique, getRecordField, sanitizeErrorText, getDomainVerifyConfig, resolveDohUrls, getCnameTarget, buildDomainVerifyCode, parseTxtAnswerData, extractTxtValuesFromAnswers, queryDohEndpoint, resolveTxtByDoh, resolveTxtBySystem, timeoutMs, resolveTxtValues, verifyDomainRecord, isUnknownColumnError, findVerifiedDomainRecord, verifyPendingDomains, buildInfoOutput, buildCertOutput, getInfo, getCert, getDomain, setDomain, promotePendingDomain, checkPendingDomainRecord, checkDomain, buildDomainOutput, buildResolvedValues, describeDomainStatus, getDomainCacheKey, buildPublicOutput, clearDomainCache, clearDomainCaches, buildPendingClearPatch, getByDomain, normalizePem, parseCertPem, assertCertValid, collectCertNames, certCoversDomain, validateKeyPem, assertWarehouseSubject, saveInfo, saveCert
- app/service/systems/inbound_direct_log.js (15)
- getItems, _addSingleItem, _bindReceivingDetail, addItem, removeItem, commit, notifyEntryOrderCompleted, _queryCompletedEntryItems, _buildCompletedItemLines, buildEntryOrderConfirmRequest, _sendOpenApiCallback, operationLog, qimenEntrySync, _syncReceivingStorageStatus, _applyReceivingStockOccupancy
- app/service/systems/inbox/group.js (11)

View File

@ -11,6 +11,12 @@
* 判断,不单独保留证书 status 列。
* - domain_status 状态机:0-未验证,1-已验证(DNS TXT 校验通过),2-验证失败;
* 未验证/验证失败的域名禁止上传证书与对外公共拉取,管理后台设置域名后回落到 0。
* - 两阶段域名切换(方案 B):生效域名 domain 只在 DNS TXT 校验通过时由
* frontConfig.promotePendingDomain 切换;frontConfig.setDomain 只把新域名登记在
* pending_domain(+ pending_verify_host/token 校验码),旧域名全程可用(不会出现
* 「页面能打开但公共配置 404」的中间态);提升时旧域名写入 retired_domain 下线队列
* (由外部证书脚本删除其 nginx 配置与证书文件后置 NULL)、清空证书 5 列并重置同步 4 列
* (域名已变,证书必须重新上传)。
* - domain 唯一索引(uk_domain)为 MySQL 可空列唯一索引:允许多个 NULL,
* 应用层在写入非空 domain 前必须做唯一性校验,不能依赖数据库约束报错。
* - store_id 唯一索引(uk_store_id):每仓一行,由数据库层保证。
@ -83,6 +89,47 @@ module.exports = app => {
allowNull: true,
comment: '最近一次域名验证失败原因',
},
pending_domain: {
type: STRING(100),
allowNull: true,
comment: '待验证域名:setDomain 只登记到本列,TXT 校验通过后才提升为生效域名 domain',
},
pending_verify_host: {
type: STRING(255),
allowNull: true,
comment: '待验证域名的 TXT 记录主机名(wmsv-<随机码>.<待验证域名>)',
},
pending_verify_token: {
type: STRING(64),
allowNull: true,
comment: '待验证域名的 TXT 记录值(32 位 hex)',
},
pending_verify_attempts: {
type: INTEGER(11),
allowNull: false,
defaultValue: 0,
comment: '待验证域名校验尝试次数',
},
pending_last_error: {
type: STRING(500),
allowNull: true,
comment: '待验证域名最近一次失败原因',
},
pending_created_at: {
type: DATE,
allowNull: true,
comment: '发起域名切换的时间',
},
retired_domain: {
type: STRING(100),
allowNull: true,
comment: '待下线旧域名:域名提升时写入,外部证书脚本删除其 nginx 配置与证书文件后置 NULL',
},
retired_at: {
type: DATE,
allowNull: true,
comment: '旧域名进入下线队列的时间',
},
title: {
type: STRING(100),
allowNull: true,
@ -202,6 +249,14 @@ module.exports = app => {
name: 'idx_domain_status',
fields: [ 'domain_status' ],
},
{
name: 'idx_pending_domain',
fields: [ 'pending_domain' ],
},
{
name: 'idx_retired_domain',
fields: [ 'retired_domain' ],
},
],
});

View File

@ -158,6 +158,9 @@ class FrontConfigMethodsService extends MainService {
* 保存后清理该域名的公共拉取缓存并返回证书配置输出
* (响应含证书/私钥原文回显,13 字段,口径与 frontConfig.getCert 一致)。
*
* 域名切换提示:待验证域名提升为生效域名时会清空证书 5 列并重置同步状态(域名已变,证书必须
* 重新上传);前置闸门与 SAN/CN 覆盖校验始终以生效域名为准。
*
* @param {Object} data 请求参数。
* @param {string} data.pem 证书 PEM 文本(必填)。
* @param {string} data.key 私钥 PEM 文本(必填,与证书成对)。
@ -189,13 +192,20 @@ class FrontConfigMethodsService extends MainService {
/**
* 设置当前仓库前端独立部署域名(需登录、仅仓库主体)。
*
* 设置成功会下发一次性 DNS TXT 校验记录(verify_host/verify_value)与 CNAME 目标(cname);
* 域名发生变更时会同时清空既有证书并重置同步状态(旧证书不覆盖新域名)。
* 设置成功只登记待验证域名并下发一次性 DNS TXT 校验记录(pending_verify_host / pending_verify_value)
* 与 CNAME 目标(cname);生效域名、证书与同步状态不会因本接口改变。
*
* 两阶段切换(本次改造):本接口只登记待验证域名(pending_domain)并下发 TXT 校验码,不直接
* 改动生效域名、证书与同步状态——切换期间旧域名全程可用,改错域名只要不配置 TXT 记录就不会生效;
* TXT 校验通过后由提升逻辑切换生效域名,届时旧域名进入 retired_domain 下线队列、证书被清空并
* 重置同步状态(需重新上传证书)。入参为当前生效域名时表示「取消待切换」。
*
* @param {Object} data 请求参数。
* @param {string} data.domain 仓库自持域名(必填,非空,≤100 字符,全局唯一)。
* @return {Promise<Object>} 统一响应结果(code=1);data 含
* warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。
* @return {Promise<Object>} 统一响应结果(code=1);data 含生效域名组 9 字段
* (warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error)
* + 待验证域名组 7 字段(pending_domain/pending_verify_host/pending_verify_value/pending_attempts/
* pending_last_error/pending_created_at/pending_active)。
*/
async setDomain(data = {}) {
const targetService = this.getFrontConfigService();
@ -219,8 +229,15 @@ class FrontConfigMethodsService extends MainService {
* 返回待校验的 verify_host/verify_value 与 cname;domain_status=1(已验证)时
* verify_host/verify_value 返回空串(校验令牌已无用途);无记录时返回空值默认。
*
* @return {Promise<Object>} 统一响应结果(code=1);data 含
* warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。
* 两阶段切换后响应在既有 9 个字段之后追加待验证域名组(pending_domain / pending_verify_host /
* pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active;
* 无待验证域名时依次为 ''/''/''/0/''/null/false)。待验证域名的校验码始终回显——该域名尚未生效,
* 需据此配置 TXT 记录;生效域名已验证时既有 verify_host/verify_value 仍返回空串(口径不变)。
*
* @return {Promise<Object>} 统一响应结果(code=1);data 含生效域名组 9 字段
* (warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error)
* + 待验证域名组 7 字段(pending_domain/pending_verify_host/pending_verify_value/pending_attempts/
* pending_last_error/pending_created_at/pending_active)。
*/
async getDomain() {
const targetService = this.getFrontConfigService();
@ -242,6 +259,10 @@ class FrontConfigMethodsService extends MainService {
* 主动校验当前仓库前端独立部署域名的 DNS TXT 记录(需登录、仅仓库主体)。
*
* 校验结果会回写 domain_status/domain_verified_at/attempts/last_error;
* 两阶段切换后:存在待验证域名(pending_active=true)时校验的是待验证域名的 TXT 记录,通过即
* 提升为生效域名(旧域名入 retired_domain 下线队列、证书清空并重置同步状态);不通过只累加
* pending_attempts 并记 pending_last_error,生效域名与证书不受影响。无待验证域名时保持原口径
* 回写 domain_status/domain_verified_at/attempts/last_error。
* 响应额外含 verified(本次是否通过)与 resolved_values(本次解析到的 TXT 值,最多 5 条)。
*
* @return {Promise<Object>} 统一响应结果(code=1);未设置域名时 code=400。

File diff suppressed because it is too large Load Diff

View File

@ -317,9 +317,26 @@ module.exports = appInfo => {
enable: true, // 是否注册域名验证定时任务
interval: '10m', // 扫描间隔
lockTtlSeconds: 600, // Redis 跨进程锁 TTL(略大于 interval)
batchSize: 50, // 单轮最多处理行数
// 单轮最多处理行数:单行最坏耗时 ≈ (DoH 端点数 3 + 系统 DNS 兜底 1) × timeoutMs(3000ms) = 12s,
// 20 行最坏 ≈ 240s,明显小于 lockTtlSeconds(600s) 与扫描间隔 interval(600s),跨进程锁不会被下一轮抢走
batchSize: 20,
// DoH 端点列表(多端点按序尝试,任一端点拿到 TXT 值即立即返回,不再询问后续端点):
// 1) https://dns.alidns.com/resolve 阿里公共 DNS 的 JSON 接口,默认主解析器;
// 2) https://223.5.5.5/resolve 阿里公共 DNS 的 IP 直连入口(同一后端,域名侧解析异常时兜底);
// 3) https://doh.pub/dns-query 腾讯 doh.pub,保留但置于最后。
// 为什么把 doh.pub 放最后:其负缓存(NODATA)可能长时间滞后于权威服务器。
// 实测案例:主机 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录 ddd9ae51cf95b488db544f23ccd01e7b 真实存在
// (8.8.8.8 / 223.5.5.5 / nslookup / AliDNS DoH 四方一致),而 doh.pub 返回 Status=0 且 Answer 为空
// (同一主机 A 查询亦 NODATA,其 SOA 序列号 2026081813 旧于 TXT 查询的 2026082815),重复两次结果一致。
dohUrls: [
'https://dns.alidns.com/resolve',
'https://223.5.5.5/resolve',
'https://doh.pub/dns-query',
],
// 兼容键(历史单端点配置):dohUrls 缺失/非法时 getDomainVerifyConfig() 回退用 [dohUrl];多端点生效后不应再依赖本键
dohUrl: 'https://doh.pub/dns-query',
timeoutMs: 5000, // 单次 DoH 请求超时
// 单个 DoH 端点、以及系统 DNS 兜底单次查询的超时(毫秒)
timeoutMs: 3000,
maxAttempts: 20, // 超过后不再自动重试(仍可手动 checkDomain)
},
};

View File

@ -0,0 +1,220 @@
'use strict';
const TABLE_NAME = 'wms_warehouse_front_config';
const PENDING_DOMAIN_INDEX_NAME = 'idx_pending_domain';
const RETIRED_DOMAIN_INDEX_NAME = 'idx_retired_domain';
/**
* Migration: 仓库前端配置表新增「两阶段域名切换」相关列与索引。
*
* 背景(为什么需要这次改造):
* 原实现 frontConfig.setDomain 是「设置即生效」——一次调用就把 domain 改成新域名、
* domain_status 归零并清空证书。后果是旧域名立刻被 frontConfig.getByDomain 判为
* 「域名未配置」(404),而 nginx 侧旧域名 server 块还在,出现「页面能打开但拉不到配置」
* 的中间态;用户改错域名也无法回滚。
*
* 方案(方案 B·两阶段切换,待验证域名与生效域名分离):
* 1. 第一阶段(frontConfig.setDomain):只把新域名登记到 pending_domain 并下发 TXT 校验码,
* 生效域名 domain、domain_status、domain_verified_at、证书与同步状态一律不动;
* 2. 第二阶段(frontConfig.checkDomain 手动触发 / app/schedule/domain_verify_scan.js 定时扫描):
* TXT 校验通过后由 frontConfig.promotePendingDomain 一次性把 pending_domain 提升为
* domain(domain_status=1),同时把旧域名写入 retired_domain 下线队列、清空证书并重置同步状态。
* 旧域名的 nginx 配置与证书文件由外部证书脚本按 retired_domain 删除后置 NULL(本次不改脚本)。
*
* 新增列(全部可空或带默认值,无需数据回填):
* - pending_domain : 待验证域名(STRING(100),验证通过后才提升为生效域名 domain);
* - pending_verify_host : 待验证域名的 TXT 记录主机名(STRING(255),wmsv-<随机码>.<待验证域名>);
* - pending_verify_token : 待验证域名的 TXT 记录值(STRING(64),32 位 hex);
* - pending_verify_attempts: 待验证域名校验尝试次数(INTEGER,NOT NULL,默认 0);
* - pending_last_error : 待验证域名最近一次失败原因(STRING(500),脱敏截断);
* - pending_created_at : 发起域名切换的时间(DATE);
* - retired_domain : 待下线旧域名(STRING(100),域名提升时写入,外部脚本删除其
* nginx 配置与证书文件后置 NULL);
* - retired_at : 旧域名进入下线队列的时间(DATE)。
* 新增索引:
* - idx_pending_domain:域名验证定时任务按 pending_domain 扫描待验证行的查询索引(普通索引);
* - idx_retired_domain:外部证书脚本按 retired_domain 扫描待下线旧域名的查询索引(普通索引)。
*
* 为什么无需回填:
* 8 个新列要么可空、要么带默认值 0,存量行的 pending_* 一律为 NULL / 0 → 语义就是
* 「没有待验证域名」,生效域名 domain / domain_status / 证书 / 同步状态全部保持原值,
* 升级瞬间行为与升级前一致(唯一变化是下次 setDomain 会走两阶段,属预期变更)。
* 注意:pending_domain 只有普通索引(非唯一),并发提交同一域名理论上仍可能同时写入两行,
* 最终由 domain 上的唯一索引在「提升」阶段兜底(提升冲突会保留待验证状态并记入错误)。
*
* Idempotent: 列/索引已存在时跳过;down 先删索引、再按倒序删列(均判存在后执行)。
*/
/**
* 判断表是否存在。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @param {string} tableName 表名。
* @return {Promise<boolean>} 存在返回 true。
*/
async function tableExists(queryInterface, tableName) {
const tables = await queryInterface.showAllTables();
return tables.some(t => (typeof t === 'string' ? t : (t.tableName || t.name)) === tableName);
}
/**
* 判断索引是否存在。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @param {string} tableName 表名。
* @param {string} indexName 索引名。
* @return {Promise<boolean>} 存在返回 true。
*/
async function indexExists(queryInterface, tableName, indexName) {
const indexes = await queryInterface.showIndex(tableName);
return (indexes || []).some(item => (typeof item === 'string' ? item : item.name) === indexName);
}
module.exports = {
/**
* 执行正向迁移:新增两阶段域名切换相关列与索引(幂等,无数据回填)。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @param {import('sequelize')} Sequelize Sequelize 实例。
* @return {Promise<void>} 无返回值。
*/
async up(queryInterface, Sequelize) {
if (!(await tableExists(queryInterface, TABLE_NAME))) {
return;
}
const columns = await queryInterface.describeTable(TABLE_NAME);
// 列定义表:after 显式指定列序,pending 组紧随域名验证组,retired 组接在 pending 组之后
const columnDefs = [
{
name: 'pending_domain',
after: 'domain_last_error',
definition: {
type: Sequelize.STRING(100),
allowNull: true,
comment: '待验证域名:setDomain 只登记到本列,TXT 校验通过后才提升为生效域名 domain',
},
},
{
name: 'pending_verify_host',
after: 'pending_domain',
definition: {
type: Sequelize.STRING(255),
allowNull: true,
comment: '待验证域名的 TXT 记录主机名(wmsv-<随机码>.<待验证域名>)',
},
},
{
name: 'pending_verify_token',
after: 'pending_verify_host',
definition: {
type: Sequelize.STRING(64),
allowNull: true,
comment: '待验证域名的 TXT 记录值(32 位 hex)',
},
},
{
name: 'pending_verify_attempts',
after: 'pending_verify_token',
definition: {
type: Sequelize.INTEGER(11),
allowNull: false,
defaultValue: 0,
comment: '待验证域名校验尝试次数',
},
},
{
name: 'pending_last_error',
after: 'pending_verify_attempts',
definition: {
type: Sequelize.STRING(500),
allowNull: true,
comment: '待验证域名最近一次失败原因',
},
},
{
name: 'pending_created_at',
after: 'pending_last_error',
definition: {
type: Sequelize.DATE,
allowNull: true,
comment: '发起域名切换的时间',
},
},
{
name: 'retired_domain',
after: 'pending_created_at',
definition: {
type: Sequelize.STRING(100),
allowNull: true,
comment: '待下线旧域名:域名提升时写入,外部证书脚本删除其 nginx 配置与证书文件后置 NULL',
},
},
{
name: 'retired_at',
after: 'retired_domain',
definition: {
type: Sequelize.DATE,
allowNull: true,
comment: '旧域名进入下线队列的时间',
},
},
];
for (const item of columnDefs) {
if (!columns[item.name]) {
await queryInterface.addColumn(TABLE_NAME, item.name, {
...item.definition,
after: item.after,
});
}
}
if (!(await indexExists(queryInterface, TABLE_NAME, PENDING_DOMAIN_INDEX_NAME))) {
await queryInterface.addIndex(TABLE_NAME, [ 'pending_domain' ], {
name: PENDING_DOMAIN_INDEX_NAME,
});
}
if (!(await indexExists(queryInterface, TABLE_NAME, RETIRED_DOMAIN_INDEX_NAME))) {
await queryInterface.addIndex(TABLE_NAME, [ 'retired_domain' ], {
name: RETIRED_DOMAIN_INDEX_NAME,
});
}
},
/**
* 回滚迁移:删除两阶段域名切换相关索引与列(幂等)。
*
* 注意:回滚会一并丢弃待验证域名与下线队列(pending_* / retired_*),
* 但不会改动生效域名 domain、domain_status、证书与同步状态,因此不影响线上已生效域名。
* 回滚后代码若仍为两阶段版本,setDomain / checkDomain 会因缺少 pending_* 列而报错,
* 需与代码版本一并回退。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @return {Promise<void>} 无返回值。
*/
async down(queryInterface) {
if (!(await tableExists(queryInterface, TABLE_NAME))) {
return;
}
for (const indexName of [ RETIRED_DOMAIN_INDEX_NAME, PENDING_DOMAIN_INDEX_NAME ]) {
if (await indexExists(queryInterface, TABLE_NAME, indexName)) {
await queryInterface.removeIndex(TABLE_NAME, indexName);
}
}
const columns = await queryInterface.describeTable(TABLE_NAME);
// 倒序删除(与 up 的列序相反):先删 retired 组,再删 pending 组
for (const columnName of [
'retired_at',
'retired_domain',
'pending_created_at',
'pending_last_error',
'pending_verify_attempts',
'pending_verify_token',
'pending_verify_host',
'pending_domain',
]) {
if (columns[columnName]) {
await queryInterface.removeColumn(TABLE_NAME, columnName);
}
}
},
};

View File

@ -20,6 +20,98 @@
"发布顺序:迁移(20260925100000-create-wms-client-error-log)先于代码发布;迁移为纯建表、无回填,先迁移无风险。"
]
},
{
"version": "2026.09.24-front-config-domain-two-phase-switch",
"date": "2026-09-24",
"type": "updated",
"summary": "域名切换改为两阶段(待验证域名与生效域名分离)—— frontConfig.setDomain 只登记待验证域名 pending_domain 并下发 TXT 校验码,TXT 校验通过后才由提升逻辑切换为生效域名并清空证书;新增旧域名下线记录 retired_domain;解决「改域名瞬间旧域名公共接口 404」的中间态问题。",
"methods": [
"frontConfig.setDomain",
"frontConfig.getDomain",
"frontConfig.checkDomain",
"frontConfig.getByDomain",
"frontConfig.saveCert",
"frontConfig.getCert"
],
"notes": [
"变更原因(旧口径问题,P0 中间态):旧 setDomain 是「设置即生效」—— 一次调用即改写生效域名 domain、domain_status 归零并清空证书,frontConfig.getByDomain 的放行闸门(domain + domain_status=1)对旧域名立即失效 → 旧域名公共接口立刻 404,而 nginx 侧旧域名 server 块仍在,出现「页面能打开但拉不到配置」的中间态;且用户改错域名无法回滚(只能再改一次并重新举证)。本轮以「待验证域名与生效域名分离」彻底消除该中间态。",
"数据层:wms_warehouse_front_config 新增 8 列 —— pending_domain(STRING(100))、pending_verify_host(STRING(255))、pending_verify_token(STRING(64))、pending_verify_attempts(INTEGER NOT NULL 默认 0)、pending_last_error(STRING(500))、pending_created_at(DATE)、retired_domain(STRING(100),待下线旧域名)、retired_at(DATE);新增普通索引 idx_pending_domain(域名验证定时任务扫描待验证行)与 idx_retired_domain(外部脚本扫描待下线旧域名)。迁移文件 database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js(up/down 幂等)。纯追加且可空/带默认值,「无需任何数据回填」:存量行的 pending_* 为 NULL/0,语义即「没有待验证域名」,升级瞬间行为与升级前一致。",
"四分支决策表(frontConfig.setDomain,域名比较忽略大小写):A 入参 == 生效域名且无 pending → 幂等短路(不写库;仅大小写不一致时改写 domain 字面值并清新旧两个字面值缓存);B 入参 == 生效域名且有 pending → 取消待切换(只清空 pending 6 列,生效域名/证书/同步状态一律不动);C 入参 == 现有 pending_domain → 校验码齐全则幂等短路,缺码(脏数据)则只补发 pending 校验码并清 pending_verify_attempts / pending_last_error;D 其它(含首次设置)→ 查重通过后只写 pending_domain + 新校验码,domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动,也不清任何公共缓存。查重由「其他仓库 domain 命中」扩展为「其他仓库 domain 或 pending_domain 命中」→ 409「域名 X 已被其他仓库使用」。",
"提升逻辑(frontConfig.promotePendingDomain,checkDomain 路径一与定时扫描共用):TXT 校验通过后一次 update 提交 —— domain = pending_domain、domain_status=1、domain_verified_at=now、domain_verify_host/token/attempts 由 pending_* 平移、domain_last_error=NULL;旧域名(生效域名非空且与待验证域名不同)写入 retired_domain + retired_at;清空 pending 6 列(pending_verify_attempts 归 0);清空证书 5 列(cert_pem / cert_key / cert_path / key_path / cert_expire_at);重置同步 4 列(sync_status=0、sync_attempts=0、last_sync_error=NULL、last_synced_at=NULL);由调用方清理旧域名与新域名两个公共拉取缓存(clearDomainCaches,先写库后清缓存,清失败仅记 WARN)。update 的 where 带 id + pending_domain 防并发重复提升。",
"响应契约变化(纯追加、旧字段名与语义不变,前端可先发版兼容):frontConfig.getDomain 由 9 字段扩为 16 字段(追加 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active);frontConfig.setDomain 响应同步由 9 字段扩为 16 字段;frontConfig.checkDomain 响应由 11 字段扩为 18 字段(getDomain 的 16 字段 + verified + resolved_values),并新增 409 错误码(提升时 domain 唯一索引冲突)。生效域名组字段名与语义一字未改:domain_status=1 时 verify_host/verify_value 仍返回空字符串;待验证域名在 pending_domain 非空时始终回显校验码(pending_verify_host / pending_verify_value)。",
"旧域名下线由外部脚本执行(retired_domain 契约):script/warehouse-cert-sync.cjs 消费 retired_domain —— 删除该域名的 nginx server 块与证书文件后把 retired_domain 置 NULL,并有目录孤儿兜底清理;应用侧(service / schedule)不碰任何 nginx 文件。实测核对:当前工作区的 script/warehouse-cert-sync.cjs 尚未引用 retired_domain(全文检索 0 命中),该下线动作需脚本侧补齐后本闭环才完整;retired_domain 只保留最近一个旧域名,多次连续切换会丢中间域名(依赖脚本孤儿兜底清理)。",
"发布顺序强约束(必须先迁移、再发代码):新代码的 SELECT 走 Sequelize 全字段,若生产库尚未执行迁移(pending_* / retired_* 共 8 列不存在),frontConfig.setDomain / getDomain / checkDomain 乃至 frontConfig.getByDomain 都会报 ER_BAD_FIELD_ERROR;定时扫描 verifyPendingDomains 会 fail-soft 返回零统计并记 WARN(含「迁移尚未执行」提示)。迁移为纯追加可空,先在生产执行迁移无风险。升级顺序:迁移 → 发布代码 → 前端发版。",
"前端必须改造要点:①setDomain 提交成功后的 TXT 指引改读 pending_verify_host / pending_verify_value(不能再用 verify_host / verify_value);②首次设置时 domain 为空字符串是正常态(待验证域名在 pending_domain);③新增「取消待切换」交互 = 用当前生效域名再调一次 setDomain(走分支 B);④「切换中」状态用 pending_active / pending_attempts / pending_last_error / pending_created_at 展示;⑤提升完成后提示「切换完成,请重新上传证书」(提升会清空证书并重置同步状态);⑥明确「切换期间上传的证书属于旧域名」,提升后失效。",
"文档变更范围与版本号:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)。",
"历史记录说明(不回改):既有变更记录中关于「setDomain 未变化即幂等短路、缺码补发校验码」「domain_status=1 一律短路不降级」等描述属当时真实口径,作为历史事实不回改,由本条新记录承接并覆盖(现口径为四分支 A/B/C/D,原「缺码补发·已验证」分支已不存在)。",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)。",
"未处理遗留(建议单独修正):app/schedule/domain_verify_scan.js 头注释仍描述升级前口径(扫描 domain_verify_* 行并回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error),与两阶段实现(只扫 pending 组、回写 pending_* 并在通过时提升)不符;app/service/systemMethods/frontConfig.js 的部分 JSDoc 仍写「生效域名组 9 字段」。两者均位于 app/**,本次为文档任务、不改代码,仅报告。"
],
"module": "frontConfig"
},
{
"version": "2026.09.24-front-config-doh-multi-endpoint",
"date": "2026-09-24",
"type": "updated",
"summary": "修复 DNS 解析误判 —— DoH 改为多端点顺序尝试(dohUrls),单端点「无记录」不再直接定论;仅在所有解析路径都失败时才判解析错误。",
"methods": [
"frontConfig.checkDomain"
],
"notes": [
"问题与实测案例:仓库 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录真实存在(值 ddd9ae51cf95b488db544f23ccd01e7b,8.8.8.8 / 223.5.5.5 / AliDNS DoH / nslookup 四方一致),但默认 DoH 端点 doh.pub 返回 Status=0 且无 Answer(陈旧负缓存,其返回的 SOA 序列号偏旧);旧实现把单端点的 NODATA 直接定论为「未解析到 TXT 记录」→ domain_status=2 → 被 frontConfig.getByDomain 与 nginx 放行闸门断流(真实记录存在却被判为未解析到)。",
"新口径:DoH 改为多端点顺序尝试(dohUrls,默认 alidns → 223.5.5.5 → doh.pub)+ 单端点结果三分类(values 立即返回 / empty 继续下一个端点 / error 继续下一个端点);empty(NODATA 或 NXDOMAIN)与 error 都不再直接定论,全部端点未取到值后降级系统 DNS;只要有一个端点或系统 DNS 明确答复「无该记录」就返回 [] (未解析到记录,不抛错),仅「所有 DoH 端点都是 error 且系统 DNS 也失败」才抛 500「DNS 解析失败:…」。",
"配置兼容规则(dohUrl → dohUrls):config.frontConfig.domainVerify.dohUrls 为有效非空字符串数组时优先使用(顺序不变);否则回退历史单端点键 dohUrl(等价 [dohUrl]);两者均无效时回退内置默认数组 DEFAULT_DOH_URLS。旧键 dohUrl 保留读兼容,不作废。",
"配置默认值变更:timeoutMs 5000 → 3000(单端点超时,系统 DNS 兜底同样显式限时 3s)、batchSize 50 → 20;配套核算 batchSize ≤ lockTtlSeconds×0.5 ÷ ((N+1)×timeoutMs/1000)(N 为端点数),3 端点场景单行最坏 12s、20 行 240s < lockTtlSeconds 600s。",
"返回值契约:内部 resolveTxtValues 新增 endpoint 字段(追加不破坏,仍返回 { values, source, endpoint });verifyDomainRecord 契约不变({ verified, values, source, error },永不抛异常);新增内部 helper resolveDohUrls、queryDohEndpoint。",
"可观测性:每个端点的 empty / error 均打日志(含 host + endpoint + 脱敏原因),可区分「记录不存在」与「链路不可用」。",
"前端无感:不影响任何 method 的入参 / 响应结构,仅影响 frontConfig.checkDomain 与定时任务 domain_verify_scan 的判定正确性。",
"文档变更范围:仅更新 frontConfig.checkDomain(description + notes),frontConfig 分组仍 8 条、各 response 计数不变;新增 1 条变更记录;根版本 0.3.187 → 0.3.188(updatedAt 保持 2026-09-24)。",
"历史记录说明:既有变更记录中关于「Status=3 或无 Answer 视为未解析到记录、不重复走系统 DNS」的描述属于当时的真实口径,作为历史事实不回改,由本条新记录承接并覆盖。"
],
"module": "frontConfig"
},
{
"version": "2026.09.24-front-config-domain-verified-shortcircuit",
"date": "2026-09-24",
"type": "updated",
"summary": "修复「domain_status=1 的已验证域名可能被误降级」问题:frontConfig.setDomain 删除「已验证缺码补发」分支(已验证域名一律幂等短路、不补码、不写库);frontConfig.checkDomain 对 domain_status=1 一律短路返回 verified=true 且不写库、不改状态、不增加验证次数。",
"methods": [
"frontConfig.setDomain",
"frontConfig.checkDomain"
],
"notes": [
"变更原因(P0 回归修复):上一轮把「domain_status=1 且缺校验码」的已验证域名也做成缺码补发,使 frontConfig.checkDomain 的「历史回填行短路」条件不再成立——用户手动点一次「校验」即走真实 DNS 解析,失败便把 domain_status 由 1 写成 2(domain_verify_attempts+1、domain_last_error 有值),随后被 frontConfig.getByDomain 与 nginx 放行闸门断流;且 status=1 时 getDomain 不回显校验码,用户无从发现补发的码。本轮改为「已验证域名一律不补码、一律短路」。",
"问题现象与复现路径:库内 domain_status=1 且 domain_verify_host/domain_verify_token 为空(迁移回填常态)→ 前端再次提交同一域名触发 frontConfig.setDomain(旧口径走 C 分支补码入库)→ frontConfig.getDomain 因 domain_status=1 仍返回空 verify_host/verify_value(补发的码任何接口都读不到)→ 用户点「校验」触发 frontConfig.checkDomain,此时短路条件「无校验码」已不成立 → 走真实 DNS 解析 → 未配置对应 TXT 记录解析失败 → domain_status 由 1 写成 2、attempts+1、last_error 有值 → frontConfig.getByDomain 与 nginx 闸门断流(线上已生效域名被降级)。",
"修复后口径(实现 app/service/systems/frontConfig.js):frontConfig.setDomain 删除原 C「缺码补发·已验证」分支,五分支收敛为 A/B/D/E/F(C 并入 A)——A 的判定为「域名忽略大小写相同 且(校验码齐全且字面值一致 或 domain_status=1)」,命中即幂等短路:不写库、不补码、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化仅改 domain 字面值(status=1 且缺码同样不补码);D 缺码补发仅限 domain_status∈{0,2};E 域名变更与 F 首次设置行为不变。三条「未变化」分支(A/B/D)均不写入 domain_verified_at。",
"frontConfig.checkDomain 短路口径放宽:由「domain_status=1 且缺校验码」改为「domain_status=1」(不论库内有无校验码)一律短路,返回 verified=true、resolved_values=[],不写库、不改状态、不增加 attempts;已验证域名不再重复校验,误点「校验」不会把生效中的域名降级。",
"行为影响(已知取舍):已验证(domain_status=1)域名自此无法通过 frontConfig.checkDomain 重新验证;如需该能力需另开接口(本次未做)。如需重新验证,应先通过 frontConfig.setDomain 变更域名(生成新校验码并回到「未验证」)后再校验。",
"前端约束:不得依赖「重复调用 frontConfig.setDomain 换新校验码」——域名未变化时一律幂等短路,不会下发新码;当前也没有「更换校验码」的独立接口。",
"文档变更范围:methods/system.json 更新 frontConfig.setDomain、frontConfig.checkDomain 的 description 与 notes,并顺带修正 frontConfig.getInfo(response.domain 描述)与 frontConfig.saveInfo(description)中「domain 只能通过 frontConfig.saveCert 变更」的陈旧表述(实际已收敛到 frontConfig.setDomain);4 条 method 的 params/response/errors/headers 均未变动,frontConfig 分组仍为 8 条;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.186 → 0.3.187,updatedAt 保持 2026-09-24。",
"验证与实测:测试链路已确认「status=1 缺码 → setDomain 不再补码、不写库」「status=1 调 checkDomain 一律短路、不写库、不降状态、attempts 不变」「A/B/D/E/F 五分支行为与文档一致」;文档侧经 npm run doc:api:update --dry-run 预检,并以写入前备份做最小 diff 审计(除版本行、4 条 method、1 条 change 外无其它条目被动)。",
"维护源口径冲突(仅记录,未处理):与前两轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库。"
],
"module": "frontConfig"
},
{
"version": "2026.09.24-front-config-setDomain-idempotent",
"date": "2026-09-24",
"type": "updated",
"summary": "frontConfig.setDomain 语义收敛 —— 域名未变化时幂等短路,不再重新生成 DNS TXT 校验码、不再重置验证进度;仅「库内缺少校验码」时补发(已验证域名不降级),仅「库内域名大小写不同」时做小写规范化;域名变更与首次设置行为不变。",
"methods": [
"frontConfig.setDomain"
],
"notes": [
"变更原因:旧口径下「同一域名未验证/验证失败则重发新校验码并清零 attempts/last_error」,导致用户每次重复提交同一域名都会作废已配置好的 TXT 记录、并清空验证进度(attempts 归零、失败原因丢失),属无谓的进度回退;本轮以「域名是否变化」为第一决策点做幂等收敛",
"五分支口径(实现 app/service/systems/frontConfig.js setDomain):A 完全未变化(忽略大小写相同 + 库内已有校验码 + 字面值一致)→ 幂等短路,不写库、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化(忽略大小写相同但库内字面值不同,如库内 Shop.com、入参 shop.com)→ 仅把 domain 规范化为小写并清理新旧两个字面值的公共缓存,校验码与验证状态不变;C 缺码补发·已验证(domain_status=1 但 host/token 为空)→ 仅补发校验码,domain_status/domain_verified_at/attempts 保持原值不降级;D 缺码补发·未验证或失败(domain_status∈{0,2} 且缺码)→ 补发校验码 + domain_status=0 + attempts=0 + 清 last_error;E 域名变更(忽略大小写后不同)→ 行为不变:查重 409、生成新校验码、domain_status=0、attempts=0、清空证书(cert_pem/cert_key/cert_path/key_path/cert_expire_at)+ 重置同步状态、清理新旧两个 domain 缓存;F 首次设置(无记录)→ 行为不变:先查重 409,其余同 E",
"未变化短路(A/B/C/D)不再写入 domain_verified_at(该字段现在只在域名变更/首次设置分支被置 null),也不再调用 assertDomainUnique 查重;变更/首次设置(E/F)查重逻辑与 409 文案保持不变",
"行为影响提示:domain_status=2(验证失败)的行若 domain_verify_attempts 已达 config.frontConfig.domainVerify.maxAttempts(默认 20),app/schedule/domain_verify_scan.js 不会再自动拾起(计入 skipped),恢复路径为手动调用 frontConfig.checkDomain(checkDomain 无 maxAttempts 门控);且当前没有「更换校验码」的接口,如需该能力需另开接口",
"前端不得再依赖「重复调用 setDomain 换新校验码」这一行为;需要新校验码的场景只有库内缺码(C/D 自动补发),其余重复提交均按幂等短路处理",
"文档变更范围:methods/system.json 仅更新 frontConfig.setDomain 一条(description 与 notes 重写,params/response/errors/headers 未变,frontConfig 分组仍 8 条),未使用 deleteMethods、未整条覆盖其它条目;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.185 → 0.3.186,updatedAt 保持 2026-09-24",
"未处理遗留(仍建议下一批单独修正):frontConfig.getInfo 的 response.domain 描述与 frontConfig.saveInfo 的 description 仍写「domain 只能通过 frontConfig.saveCert 变更」,实际已收敛到 frontConfig.setDomain;本条 spec.methods 只放 setDomain,避免整条覆盖造成语义漂移",
"维护源口径冲突(仅记录,未处理):与上一轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库"
],
"module": "frontConfig"
},
{
"version": "2026.09.24-return-unpack-notify-by-source",
"date": "2026-09-24",

View File

@ -47491,7 +47491,7 @@
"list": [
{
"method": "frontConfig.getByDomain",
"description": "按域名拉取仓库前端公开配置(公共无鉴权接口:免登录、免鉴权、免权限,保留系统日志)。仅放行已验证域名:查库条件为 domain + domain_status=1,未验证(0)/验证失败(2)的域名一律按未配置返回 404「域名未配置」(文案与响应结构未变,仅命中条件收紧);迁移尚未执行(domain_status 列不存在)时降级为仅按 domain 查询并 WARN 一次,保持迁移前行为,迁移完成并重启实例后闸门才真正生效。响应仅含公开字段 domain/title/logo_url/login_bg_url/favicon_url/theme,绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。Redis 缓存 key front:config:domain:{domain}:命中配置缓存 TTL 600s;未登记域名写 configured=false 空缓存 60s 防穿透并返回 404;保存配置时自动失效新旧域名缓存;Redis 异常降级查库。",
"description": "按域名拉取仓库前端公开配置(公共无鉴权接口:免登录、免鉴权、免权限,保留系统日志)。放行闸门仍只认「生效域名」:查库条件为 domain + domain_status=1,未验证(0)/验证失败(2)的域名一律按未配置返回 404「域名未配置」(本次实现未变,仅补充两阶段语义说明);迁移尚未执行(domain_status 列不存在)时降级为仅按 domain 查询并 WARN 一次,保持迁移前行为。两阶段域名切换语义:切换验证期间生效域名仍为旧域名,本接口继续对旧域名正常放行、对新登记的待验证域名按未配置返回 404 —— 因此不会出现「改域名瞬间旧域名公共接口 404、页面能打开但拉不到配置」的中间态;只有 TXT 校验通过、待验证域名被提升为生效域名后,才改为对新域名放行、旧域名返回 404(旧域名 nginx 配置随后由外部脚本按 retired_domain 删除彻底下线)。响应仅含公开字段 domain/title/logo_url/login_bg_url/favicon_url/theme,绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。Redis 缓存 key front:config:domain:{domain}:命中配置缓存 TTL 600s;未登记域名写 configured=false 空缓存 60s 防穿透并返回 404;域名提升/保存配置时自动失效新旧域名缓存;Redis 异常降级查库。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
@ -47559,6 +47559,16 @@
"code": "500",
"message": "WarehouseFrontConfig model 不可用/获取前端配置失败"
}
],
"notes": [
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 getByDomain,实现 app/service/systems/frontConfig.js 的 getByDomain(查库走 findVerifiedDomainRecord,缓存走 getDomainCacheKey / clearDomainCaches)",
"放行闸门(本轮未改实现,仅补语义说明):查库条件仍为 domain + domain_status=1,只看生效域名 domain,不看 pending_domain",
"两阶段切换语义:切换验证期间旧域名(生效域名)继续放行、新域名(待验证域名)返回 404「域名未配置」;提升完成后新域名放行、旧域名 404,旧域名 nginx 配置由外部脚本按 retired_domain 删除后彻底下线 —— 因此不会出现「改域名瞬间旧域名公共接口 404」的中间态",
"缓存:域名切换/提升写库成功后由 clearDomainCaches 清理「旧域名 + 新域名」两个 key(front:config:domain:{domain}),先写库后清缓存;Redis 异常降级查库",
"安全红线不变:只返回 domain/title/logo_url/login_bg_url/favicon_url/theme 公开字段,绝不返回证书/私钥与证书路径、同步状态等内部字段",
"迁移兼容提示:domain_status 列不存在(迁移未执行)时降级为仅按 domain 查询并 WARN 一次;但两阶段版本代码要求 pending_* / retired_* 共 8 列已存在,生产必须先执行迁移 20260924180000-add-pending-domain-to-wms-warehouse-front-config 再发布代码,否则本接口的 Sequelize 全字段查询会报 ER_BAD_FIELD_ERROR",
"文档变更范围:本次仅更新本条的 description + notes(params / response / errors / headers 均未变动,response 仍为 6 个公开字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
},
{
@ -47586,7 +47596,7 @@
"name": "domain",
"type": "string",
"required": true,
"description": "仓库自持域名(未配置为空字符串;只能通过 frontConfig.saveCert 变更)"
"description": "仓库自持域名(未配置为空字符串;变更统一走 frontConfig.setDomain)"
},
{
"name": "title",
@ -47758,12 +47768,15 @@
"响应契约变更(10 → 13 字段):末位追加 can_set_cert(boolean)、can_set_cert_reason(string)、domain_status(number);前 10 字段口径与含义不变",
"can_set_cert_reason 文案与前端提示直接对应:可上传为空字符串,无域名「请先设置域名」,domain_status=0「域名待验证」,domain_status=2「域名验证失败」",
"私钥原文回显口径与旧 setting.warehouse.getFrontConfig 一致(沿用 cert_pem/cert_key 原文回显),但旧方法名与旧分组条目已删除",
"本接口不返回 cert_path/key_path(保存时已置 null,等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填)"
"本接口不返回 cert_path/key_path(保存时已置 null,等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填)",
"两阶段切换提示(本轮,实现与响应字段均未变):域名提升时会清空证书并重置同步状态,提升后本接口回显的证书字段为空、can_set_cert 仍按生效域名判定(domain 非空且 domain_status=1),用户需重新上传证书;切换中的待验证域名 pending_domain 不参与 can_set_cert 判定",
"文档变更范围:本次仅追加本条的 notes(description / params / response / errors / headers 均未变动,response 仍为 13 字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
},
{
"method": "frontConfig.saveInfo",
"description": "保存当前仓库前端独立部署品牌配置(upsert 一仓一行,部分更新;需登录、免权限、免鉴权,仅仓库主体可调用)。仅受理 title/logo_url/favicon_url/login_bg_url/theme,其余字段一律忽略:domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)由方法层白名单静默过滤,前端传值不报错也不生效,domain 变更必须走 frontConfig.saveCert(重新校验证书)。保存即视为一次配置变更:同步状态重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志不影响保存结果)。响应为保存后的品牌信息(8 字段,不含证书/私钥)。",
"description": "保存当前仓库前端独立部署品牌配置(upsert 一仓一行,部分更新;需登录、免权限、免鉴权,仅仓库主体可调用)。仅受理 title/logo_url/favicon_url/login_bg_url/theme,其余字段一律忽略:domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)由方法层白名单静默过滤,前端传值不报错也不生效,domain 变更统一走 frontConfig.setDomain(域名验证通过后方可上传证书)。保存即视为一次配置变更:同步状态重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志不影响保存结果)。响应为保存后的品牌信息(8 字段,不含证书/私钥)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -47899,7 +47912,7 @@
},
{
"method": "frontConfig.saveCert",
"description": "上传当前仓库前端独立部署证书(证书/私钥成对;需登录、免权限、免鉴权,仅仓库主体可调用)。域名不再作为入参:一律取库内已设置的 domain,且新增前置闸门——无域名返回 400「请先设置并验证域名」,domain_status !== 1 返回 400「域名未通过验证,暂时无法上传证书」(前端若仍传 domain 会被忽略,不报错也不生效)。通过闸门后校验链:证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖库内 domain(支持 *.example.com 通配,通配仅覆盖恰好一级标签:*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com,后者同样按「证书不合法」拒绝)。校验链任一失败统一返回 400「证书不合法」,不吐露细节。通过后:cert_expire_at 以证书 validTo 权威写入(忽略前端传值);证书/私钥内容直接写入 cert_pem/cert_key 列,cert_path/key_path 置 null(等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填真实路径);同步状态重置为待同步;写库成功后清理当前域名的公共拉取缓存(域名已不能在本接口变更,故只需清一个 key)。响应为保存后的证书输出(13 字段,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at/can_set_cert/can_set_cert_reason/domain_status),不含 cert_path/key_path 路径字段。",
"description": "上传当前仓库前端独立部署证书(证书/私钥成对;需登录、免权限、免鉴权,仅仓库主体可调用)。域名不再作为入参:一律取库内已设置的 domain,且新增前置闸门——无域名返回 400「请先设置并验证域名」,domain_status !== 1 返回 400「域名未通过验证,暂时无法上传证书」(前端若仍传 domain 会被忽略,不报错也不生效)。通过闸门后校验链:证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖库内 domain(支持 *.example.com 通配,通配仅覆盖恰好一级标签:*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com,后者同样按「证书不合法」拒绝)。校验链任一失败统一返回 400「证书不合法」,不吐露细节。通过后:cert_expire_at 以证书 validTo 权威写入(忽略前端传值);证书/私钥内容直接写入 cert_pem/cert_key 列,cert_path/key_path 置 null(等待外部 crontab 脚本 script/warehouse-cert-sync.cjs 部署后回填真实路径);同步状态重置为待同步;写库成功后清理当前域名的公共拉取缓存(域名已不能在本接口变更,故只需清一个 key)。响应为保存后的证书输出(13 字段,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at/can_set_cert/can_set_cert_reason/domain_status),不含 cert_path/key_path 路径字段。注意:域名提升(两阶段切换的第二阶段)会清空证书 5 列并重置同步状态,域名切换完成后必须重新上传证书;切换期间上传的证书属于旧域名,提升后即失效。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -48050,12 +48063,16 @@
"前置闸门:无域名 → 400「请先设置并验证域名」;domain_status !== 1 → 400「域名未通过验证,暂时无法上传证书」",
"响应契约变更(10 → 13 字段):在上一轮 10 字段基础上追加 can_set_cert/can_set_cert_reason/domain_status,与 frontConfig.getCert 完全同口径",
"通配语义(certCoversDomain,app/service/systems/frontConfig.js):*.example.com 分支要求通配前缀非空且不含「.」,即仅覆盖恰好一级标签",
"写库内容:cert_pem/cert_key 直接入库(不落暂存文件),cert_path/key_path 置 null 等待定时任务回填,cert_expire_at 取证书 validTo;同步状态同步重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at)"
"写库内容:cert_pem/cert_key 直接入库(不落暂存文件),cert_path/key_path 置 null 等待定时任务回填,cert_expire_at 取证书 validTo;同步状态同步重置为待同步(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at)",
"两阶段切换补充(本轮):域名提升时会清空证书(cert_pem / cert_key / cert_path / key_path / cert_expire_at 置 NULL)并重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error / last_synced_at),因此域名切换完成后必须重新上传证书;切换期间上传的证书属于旧域名,提升后即失效",
"前置闸门口径(本轮,实现未变):仍按生效域名 domain 判定(无域名 → 400「请先设置并验证域名」,domain_status !== 1 → 400「域名未通过验证,暂时无法上传证书」);切换中的待验证域名 pending_domain 不参与本闸门",
"文档变更范围:本次更新本条的 description + notes 各一处(params / response / errors / headers 均未变动,response 仍为 13 字段);frontConfig 分组仍 8 条;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
},
{
"method": "frontConfig.setDomain",
"description": "设置或变更当前仓库前端独立部署域名,并发起 DNS TXT 归属验证(需登录、免权限、免鉴权,权限由业务层按 isWarehouse 判定,仅仓库主体可调用)。流程:仓库主体校验 → domain 必填/长度(≤100 字符)/形态校验(统一转小写存储)→ 跨仓库唯一校验 → 生成一次性校验子域 verify_host(wmsv-<10 位 hex>.<domain>)与校验值 verify_value(32 位 hex)→ upsert 该仓库行并把 domain_status 置 0(未验证)→ 清理新旧域名的公共拉取缓存。查重:域名已被其他仓库使用返回 409「域名 X 已被其他仓库使用」(含并发写入唯一索引冲突兜底)。格式:至少两段标签、每段 1~63 位且仅字母数字与连字符、首尾不得为连字符(天然排除通配符 *、下划线、首尾点与单段主机名),不合法返回 400「domain 格式不正确」;空值返回 400「domain 不能为空」;超长返回 400「domain 长度不能超过 100 字符」。域名变更(仅大小写差异不算变更)会同时清空既有证书(cert_pem/cert_key/cert_path/key_path/cert_expire_at 置空)并重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),避免 nginx 继续用旧域名证书对外服务;同一域名重复设置时:已验证则幂等返回(不刷新校验码、不清证书、不改验证状态),未验证/验证失败则重发新校验码并清零 attempts/last_error。响应口径与 frontConfig.getDomain 一致(9 字段);domain_status=1 时 verify_host/verify_value 返回空字符串。",
"description": "设置或变更当前仓库前端独立部署域名(需登录、免权限、免鉴权,权限由业务层按 isWarehouse 判定,仅仓库主体可调用)。语义已改为两阶段切换:本接口只登记「待验证域名」pending_domain 并下发一次性 DNS TXT 校验记录,不直接改动生效域名 domain;TXT 校验通过后(frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时扫描)再由提升逻辑一次性把 pending_domain 提升为生效域名。这样生效域名全程不变:切换期间旧域名的前端页面与 frontConfig.getByDomain 公共拉取都仍然可用,不会出现「改域名瞬间旧域名公共接口 404」的中间态。分支(域名比较一律忽略大小写):A 入参 == 生效域名 domain 且无 pending_domain → 幂等短路:不写库,仅当库内字面值与归一化结果不一致时把 domain 改写为小写并清理新旧两个字面值的缓存 key;B 入参 == 生效域名 domain 且有 pending_domain → 取消待切换:只清空 pending 6 列,生效域名、证书 5 列、同步 4 列与公共缓存一律不动;C 入参 == 现有 pending_domain → 校验码齐全则幂等短路(不重发、不写库),校验码缺失(脏数据)则只补发 pending 校验码并清 pending_verify_attempts/pending_last_error;D 其它(新的待切换域名,含首次设置)→ 查重(其他仓库的 domain 或 pending_domain 命中任一即 409)通过后生成新校验码只写入 pending 组,生效域名 domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动,也不清理任何公共缓存(新域名尚未生效)。域名与校验码口径:domain 必填、trim 后非空、≤100 字符,形态校验通过后统一转小写存储;pending_verify_host 为一次性校验子域 wmsv-<10 位 hex>.<待验证域名>,pending_verify_value 为 32 位 hex。格式:至少两段标签、每段 1~63 位且仅字母数字与连字符、首尾不得为连字符(天然排除通配符 *、下划线、首尾点与单段主机名),不合法返回 400「domain 格式不正确」;空值返回 400「domain 不能为空」;超长返回 400「domain 长度不能超过 100 字符」;域名(或待验证域名)被其他仓库占用返回 409「域名 X 已被其他仓库使用」。响应口径与 frontConfig.getDomain 一致(16 字段);生效域名组 domain_status=1 时 verify_host/verify_value 返回空字符串,待验证域名组 pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -48129,6 +48146,48 @@
"type": "string",
"required": true,
"description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)"
},
{
"name": "pending_domain",
"type": "string",
"required": true,
"description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行"
},
{
"name": "pending_verify_host",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.<pending_domain>;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录"
},
{
"name": "pending_verify_value",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)"
},
{
"name": "pending_attempts",
"type": "number",
"required": true,
"description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)"
},
{
"name": "pending_last_error",
"type": "string",
"required": true,
"description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)"
},
{
"name": "pending_created_at",
"type": "string",
"required": true,
"description": "发起本次域名切换的时间(无待验证域名为 null)"
},
{
"name": "pending_active",
"type": "boolean",
"required": true,
"description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)"
}
],
"errors": [
@ -48166,18 +48225,27 @@
}
],
"notes": [
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 setDomain,实现 app/service/systems/frontConfig.js 的 setDomain(校验码由 buildDomainVerifyCode 生成,输出由 buildDomainOutput 构建)",
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 setDomain,实现 app/service/systems/frontConfig.js 的 setDomain(校验码由 buildDomainVerifyCode 生成,取消待切换的字段由 buildPendingClearPatch 生成,输出由 buildDomainOutput 构建)",
"鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 setDomain(_noNeedLogin 仍仅 getByDomain)",
"域名全局唯一由应用层校验(assertDomainUnique):可空列唯一索引不约束多个 NULL,非空值唯一性必须应用层兜底;同时捕获 SequelizeUniqueConstraintError 的 domain 字段冲突统一转 409",
"校验目标用一次性随机子域而非裸域名:避免与用户主域已有的其它 TXT 记录(SPF/DKIM/站点校验等)相互干扰",
"缓存:写库成功后清理「旧 domain + 新 domain」两个公共拉取缓存 key(front:config:domain:{domain}),先写库后清缓存;清缓存失败仅记日志,不影响设置结果",
"后续链路:用户按 verify_host/verify_value 配置 TXT 记录后,由 frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时任务(默认 10m)自动校验;domain_status=1 后 frontConfig.saveCert 才可上传证书、frontConfig.getByDomain 才放行",
"旧口径变更:域名原先只能通过 frontConfig.saveCert 变更,现统一收敛到本接口(saveCert 已移除 domain 入参,前端若仍传会被忽略)"
"变更原因(本轮核心语义变更):旧口径是「设置即生效」——一次 setDomain 即把 domain 改写为新域名、domain_status 归零并清空证书,导致旧域名立刻被 frontConfig.getByDomain 判为「域名未配置」返回 404,而 nginx 侧旧域名 server 块仍在,出现「页面能打开但拉不到配置」的中间态;用户改错域名也无法回滚。本轮改为两阶段(待验证域名与生效域名分离),本接口只登记待验证域名",
"四分支决策表(域名比较一律忽略大小写):A 入参 == 生效域名 domain 且无 pending_domain → 幂等短路(不写库;仅当库内字面值与归一化结果不一致时把 domain 改写为小写,并清理新旧两个字面值的缓存 key);B 入参 == 生效域名 domain 且有 pending_domain → 取消待切换(只清空 pending 6 列);C 入参 == 现有 pending_domain → 校验码齐全则幂等短路(不重发、不写库),校验码缺失(脏数据)则只补发 pending 校验码并清 pending_verify_attempts / pending_last_error;D 其它(新的待切换域名,含首次设置)→ 查重通过后只写 pending_domain + 新校验码(pending_verify_host / pending_verify_token / pending_verify_attempts=0 / pending_last_error=NULL / pending_created_at=now)",
"分支 B「取消待切换」的边界:只清 pending 6 列,生效域名 domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动;待验证域名从未生效(不参与 getByDomain),因此无需清理公共缓存",
"分支 D「只登记不动」清单:domain / domain_status / domain_verified_at / domain_verify_host / domain_verify_token / domain_verify_attempts / domain_last_error / 证书 5 列(cert_pem / cert_key / cert_path / key_path / cert_expire_at)/ 同步 4 列(sync_status / sync_attempts / last_sync_error / last_synced_at)一律不动,也不清理任何公共缓存(新域名尚未生效,getByDomain 结果不受影响)。首次设置时新行只带 store_id 与 pending 组,domain 保持 NULL(尚未生效),domain_status 默认 0,外部证书脚本只处理 domain_status=1 的行、不会误处理该行",
"查重扩展(assertDomainUnique):由「其他仓库的 domain 命中」扩展为「其他仓库的 domain 或 pending_domain 命中」即 409「域名 X 已被其他仓库使用」;分支 A/B/C 不查重(域名已是本仓自身持有,全局唯一性由分支 D 查重与数据库唯一索引兜底);并发写入捕获 SequelizeUniqueConstraintError 的 domain 字段冲突同样转 409,其余冲突转 409「仓库前端配置保存冲突,请稍后重试」",
"缓存口径:只有分支 A 的「大小写规范化」需要清缓存 —— 公共拉取缓存键按域名字面值精确匹配(front:config:domain:Shop.com 与 front:config:domain:shop.com 是两个 key),新旧两个字面值都必须清;B/C/D 不清缓存(B 清的是从未生效的待验证域名,C/D 未改变生效域名)",
"响应契约变更(本轮 9 → 16 字段,纯追加):追加待验证域名组 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active;生效域名组 9 字段名与语义不变;domain_status=1 时生效组的 verify_host/verify_value 仍为空字符串,待验证组在 pending_domain 非空时始终回显校验码",
"前端改造要点:提交后 TXT 指引改读 pending_verify_host / pending_verify_value;「取消待切换」= 用当前生效域名再调一次本接口(走分支 B);「切换中」用 pending_active / pending_attempts / pending_last_error / pending_created_at 展示;提升后需提示「切换完成,请重新上传证书」,并明确「切换期间上传的证书属于旧域名」",
"旧口径说明(历史事实,不回改):既有变更记录中「同一域名重复设置幂等短路、缺码补发」「未验证/验证失败则重发新校验码并清零 attempts」等描述属当时真实口径,由本条新记录承接覆盖;原「C 缺码补发·已验证」分支已不存在,五分支收敛为四分支 A/B/C/D",
"后续链路:用户按 pending_verify_host / pending_verify_value 配置 TXT 记录后,由 frontConfig.checkDomain 手动触发或 app/schedule/domain_verify_scan.js 定时任务(默认 10m)校验;通过后提升为生效域名(domain_status=1、清空证书 5 列、重置同步 4 列、旧域名写入 retired_domain + retired_at、清空 pending 6 列),此后 frontConfig.saveCert 才可重新上传证书、frontConfig.getByDomain 才对新域名放行",
"行为影响提示:本接口不再提供「更换校验码」能力(同域名重复提交走 A/B/C 分支),需要新校验码只能提交一个不同的待验证域名(走分支 D);若已登记的待验证域名一直不配置 TXT 记录,则永久停留在切换中状态、生效域名不受影响",
"本条 setDomain 的 params / errors / headers 未变动(查重扩展后 409 文案「域名 {domain} 已被其他仓库使用」沿用原文案,语义已覆盖 domain 与 pending_domain 两种占用)",
"文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
},
{
"method": "frontConfig.getDomain",
"description": "查询当前仓库前端独立部署域名与验证状态(settings 页回显;需登录、免权限、免鉴权,仅仓库主体可调用)。响应 9 字段:warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error。domain_status 语义:0 未验证 / 1 已验证 / 2 验证失败。安全口径:domain_status=1(已验证)时 verify_host/verify_value 返回空字符串(校验令牌已无用途,不再回显);未验证(0/2)时回显本仓库应配置的 TXT 主机名与记录值,并额外返回 cname(取自配置 config.frontConfig.cname),指导用户把域名 CNAME 指向该目标。仓库未设置过域名时返回默认空值(warehouse_id 取当前仓库、domain 为空字符串、domain_status=0、verified_at 为 null、attempts=0、last_error 为空字符串),不返回 404。",
"description": "查询当前仓库前端独立部署域名与验证状态(settings 页回显;需登录、免权限、免鉴权,仅仓库主体可调用)。响应 16 字段,分两组:①生效域名组 9 字段 —— warehouse_id/domain/domain_status/verify_host/verify_value/cname/verified_at/attempts/last_error(字段名、类型与语义一字未改);②待验证域名组 7 字段(两阶段域名切换新增、纯追加)—— pending_domain/pending_verify_host/pending_verify_value/pending_attempts/pending_last_error/pending_created_at/pending_active。两阶段语义:domain 始终是「生效域名」,切换期间(pending_active=true)仍为旧域名并继续对外正常服务,只有 TXT 校验通过被提升后才换成新域名;pending_domain 是用户提交、等待 TXT 校验的「待验证域名」,从未生效、不参与 frontConfig.getByDomain 放行。domain_status 语义:0 未验证 / 1 已验证 / 2 验证失败。安全口径:domain_status=1(已验证)时 verify_host/verify_value 返回空字符串(校验令牌已无用途,不再回显);未验证(0/2)时回显生效域名应配置的 TXT 主机名与记录值;待验证域名组不受该限制 —— pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显(该域名尚未生效,用户必须据此配置 TXT 记录);pending_active 等价于 pending_domain 非空。cname 取配置 config.frontConfig.cname,未验证时提示把域名 CNAME 指向该目标。仓库未设置过域名时返回默认空值(warehouse_id 取当前仓库、domain 与 pending_domain 为空字符串、domain_status=0、pending_active=false、时间字段为 null、其余字符串字段为空字符串),不返回 404。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -48243,6 +48311,48 @@
"type": "string",
"required": true,
"description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)"
},
{
"name": "pending_domain",
"type": "string",
"required": true,
"description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行"
},
{
"name": "pending_verify_host",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.<pending_domain>;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录"
},
{
"name": "pending_verify_value",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)"
},
{
"name": "pending_attempts",
"type": "number",
"required": true,
"description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)"
},
{
"name": "pending_last_error",
"type": "string",
"required": true,
"description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)"
},
{
"name": "pending_created_at",
"type": "string",
"required": true,
"description": "发起本次域名切换的时间(无待验证域名为 null)"
},
{
"name": "pending_active",
"type": "boolean",
"required": true,
"description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)"
}
],
"errors": [
@ -48260,15 +48370,25 @@
}
],
"notes": [
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 getDomain,实现 app/service/systems/frontConfig.js 的 getDomain(buildDomainOutput)",
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 getDomain,实现 app/service/systems/frontConfig.js 的 getDomain(输出由 buildDomainOutput 统一构建)",
"鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 getDomain",
"cname 取自配置 config.frontConfig.cname(默认空字符串,非数据库字段),未验证时随本响应返回",
"同一输出口径被 setDomain(设置后回显)与 checkDomain(校验后回显)复用,字段含义一致"
"cname 取自配置 config.frontConfig.cname(默认空字符串,非数据库字段),未设置域名时也会返回",
"同一输出口径被 setDomain(登记后回显)与 checkDomain(校验后回显)复用,字段含义完全一致",
"响应契约变更(本轮 9 → 16 字段,纯追加):在原有 9 字段之后依次追加 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active。旧字段名、类型与语义一字未改,属向后兼容追加,前端可先发版兼容后再启用两阶段 UI",
"字段来源:生效域名组读 domain / domain_status / domain_verify_host / domain_verify_token / domain_verified_at / domain_verify_attempts / domain_last_error;待验证域名组读 pending_domain / pending_verify_host / pending_verify_token / pending_verify_attempts / pending_last_error / pending_created_at,pending_active 由 pending_domain 非空推导",
"两阶段语义:domain 是「生效域名」——切换期间(pending_active=true)仍为旧域名并继续对外正常服务;pending_domain 是等待 TXT 校验的「待验证域名」,从未生效",
"回显口径差异(重要):生效域名的 verify_host/verify_value 在 domain_status=1 时返回空字符串;待验证域名不受此限制 —— pending_domain 非空时 pending_verify_host/pending_verify_value 始终回显,因为该域名尚未生效、用户必须据此配置 TXT 记录",
"与 frontConfig.getByDomain 的关系:getByDomain 仍只看生效 domain 且要求 domain_status=1,因此切换验证期间旧域名继续正常服务(不会出现「改域名瞬间旧域名公共接口 404」),只有提升后新域名才放行、旧域名才 404,最终由外部脚本按 retired_domain 删除旧域名 nginx 配置后彻底下线",
"前端改造要点:TXT 指引必须改读 pending_verify_host/pending_verify_value(不能再读 verify_host/verify_value);首次设置时 domain 为空字符串属正常态(待验证域名在 pending_domain);「切换中」状态用 pending_active/pending_attempts/pending_last_error/pending_created_at 展示;「切换完成」后提示重新上传证书",
"发布顺序强约束:本实现走 Sequelize 全字段 SELECT,若生产库尚未执行迁移(新增 pending_* / retired_* 共 8 列不存在),setDomain / getDomain / checkDomain 乃至 getByDomain 都会报 ER_BAD_FIELD_ERROR → 必须先执行迁移、再发布代码;迁移为纯追加且可空,先跑无风险",
"仓库未设置过域名时返回默认空值:warehouse_id 取当前仓库、domain 与 pending_domain 为空字符串、domain_status=0、pending_active=false、时间字段为 null、其余字符串字段为空字符串,不返回 404",
"文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
},
{
"method": "frontConfig.checkDomain",
"description": "主动校验当前仓库前端独立部署域名的 DNS TXT 归属记录并回写库(需登录、免权限、免鉴权,仅仓库主体可调用)。解析目标一律取库内 domain_verify_host(不解析裸域名);解析路径 DoH 为主(config.frontConfig.domainVerify.dohUrl,默认 https://doh.pub/dns-query),DoH 失败降级系统 DNS(node:dns)。成功 → domain_status=1、写入 domain_verified_at、清空 domain_last_error,并清理该域名的公共拉取缓存;失败 → domain_status=2、domain_verify_attempts+1、domain_last_error 写入脱敏截断(≤500 字符)后的原因(如「未解析到 TXT 记录」「TXT 记录未包含校验值」「DNS 解析失败:…」)。无记录或 domain 为空 → 400「请先设置域名」。库内缺少校验码(历史脏数据)时自动补发一份再校验(本次因记录尚未生效仍会记失败);迁移回填的历史行(domain_status=1 但无校验码)直接返回 verified=true 且 resolved_values=[],不会把线上生效中的域名降级为验证失败。响应 = frontConfig.getDomain 的 9 字段 + verified(本次是否通过,boolean)+ resolved_values(本次解析到的 TXT 值,最多 5 条、单条截断 255 字符,排障用)。",
"description": "主动校验域名 TXT 归属记录并回写库(需登录、免权限、免鉴权,仅仓库主体可调用)。两阶段切换后本接口承担两条路径:①存在 pending_domain(切换中)→ 校验待验证域名:以 pending_verify_host 为解析目标、比对 pending_verify_token;通过则由提升逻辑把 pending_domain 提升为生效域名 domain(domain_status=1、domain_verified_at=now、domain_verify_* 由 pending_* 平移、domain_last_error 清空、清空 pending 6 列、旧域名写入 retired_domain/retired_at 下线队列、清空证书 5 列、重置同步 4 列),并清理旧域名与新域名两个公共拉取缓存,返回 verified=true;不通过只把 pending_verify_attempts+1 并写 pending_last_error,生效域名、domain_status、domain_verified_at 与证书一律不动,返回 verified=false。②无 pending_domain → 保持升级前口径:生效域名 domain_status=1 一律短路返回 verified=true、resolved_values=[],不写库、不改状态、不增加验证次数;domain 为空 → 400「请先设置域名」;domain 非空但未验证/验证失败(升级前登记的历史行)→ 用生效域名的 domain_verify_* 校验并回写 domain_status/domain_verify_attempts/domain_last_error(兼容路径,缺码则自动补发一次)。解析路径为 DoH 多端点顺序尝试(config.frontConfig.domainVerify.dohUrls,默认 https://dns.alidns.com/resolve → https://223.5.5.5/resolve → https://doh.pub/dns-query;单端点键 dohUrl 保留兼容),单端点「无记录」不再直接定论,全部端点未取到值后降级系统 DNS;仅「所有 DoH 端点都解析失败且系统 DNS 也失败」才报「DNS 解析失败:…」。失败原因经脱敏截断(≤500 字符)落库与回显。响应 = frontConfig.getDomain 的 16 字段 + verified(本次是否通过,boolean)+ resolved_values(本次解析到的 TXT 值,最多 5 条、单条截断 255 字符,排障用)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -48335,6 +48455,48 @@
"required": true,
"description": "最近一次验证失败原因(脱敏截断 ≤500 字符;未失败为空字符串)"
},
{
"name": "pending_domain",
"type": "string",
"required": true,
"description": "待验证域名(切换中非空;未发起切换为空字符串)。frontConfig.setDomain 只登记到本字段,DNS TXT 校验通过后才被提升为生效域名 domain;本字段不参与 frontConfig.getByDomain 放行"
},
{
"name": "pending_verify_host",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录主机名(wmsv-<10 位 hex>.<pending_domain>;pending_domain 为空时返回空字符串)。该域名尚未生效,校验码始终回显,用户据此配置 TXT 记录"
},
{
"name": "pending_verify_value",
"type": "string",
"required": true,
"description": "待验证域名的 TXT 记录值(32 位 hex,读 pending_verify_token 列;pending_domain 为空时返回空字符串)"
},
{
"name": "pending_attempts",
"type": "number",
"required": true,
"description": "待验证域名校验尝试次数(setDomain 登记/补码时清零;checkDomain 与定时任务校验失败时 +1)"
},
{
"name": "pending_last_error",
"type": "string",
"required": true,
"description": "待验证域名最近一次校验失败原因(脱敏截断 ≤500 字符;未失败或无待验证域名为空字符串)"
},
{
"name": "pending_created_at",
"type": "string",
"required": true,
"description": "发起本次域名切换的时间(无待验证域名为 null)"
},
{
"name": "pending_active",
"type": "boolean",
"required": true,
"description": "是否处于域名切换中(boolean,等价于 pending_domain 非空;true=待验证域名已登记、等待 TXT 校验)"
},
{
"name": "verified",
"type": "boolean",
@ -48364,15 +48526,29 @@
{
"code": "500",
"message": "签约关系服务不可用 / WarehouseFrontConfig model 不可用 / 校验域名失败"
},
{
"code": "409",
"message": "域名 {domain} 已被其他仓库使用(提升待验证域名时 domain 唯一索引冲突兜底)"
}
],
"notes": [
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 checkDomain,实现 app/service/systems/frontConfig.js 的 checkDomain(解析走 resolveTxtValues,单行校验走 verifyDomainRecord)",
"代码位置:出口 app/service/systemMethods/frontConfig.js 的 checkDomain,实现 app/service/systems/frontConfig.js 的 checkDomain(路径一走 checkPendingDomainRecord → promotePendingDomain,路径二走 verifyDomainRecord;TXT 解析走 resolveTxtValues)",
"鉴权标记:isNeedLogin=true、isNeedAuth=false;方法层 _noNeedRight/_noNeedLog/_noNeedAuth 均含 checkDomain",
"DNS 解析细节:DoH 返回非 200 或响应体非合法 JSON 视为失败并降级系统 DNS;Status=3(NXDOMAIN)或 Status=0 且无 Answer 视为「未解析到记录」返回空数组,不再重复走系统 DNS;两条路径均失败时错误文案为「DNS 解析失败:{脱敏原因}」并写入 domain_last_error",
"与定时任务的关系:本接口为手动触发兜底,与 app/schedule/domain_verify_scan.js 共用同一套解析与落库逻辑(verifyDomainRecord);定时任务对超过 maxAttempts 的行不再自动重试,但仍可通过本接口手动校验",
"两阶段语义变更(本轮核心):有 pending_domain → 校验待验证域名的 TXT 记录(目标 pending_verify_host,比对 pending_verify_token)。通过 → 提升:domain 换为 pending_domain、domain_status=1、domain_verified_at=now、domain_verify_host/token/attempts 由 pending_* 平移、domain_last_error=NULL、清空 pending 6 列(pending_verify_attempts 归 0)、旧域名写入 retired_domain + retired_at、清空证书 5 列、重置同步 4 列(sync_status=0 / sync_attempts=0 / 清空 last_sync_error / last_synced_at),并清理旧域名与新域名两个公共拉取缓存,返回 verified=true;不通过 → 只写 pending_verify_attempts+1 与 pending_last_error,生效域名 domain / domain_status / domain_verified_at 与证书一律不动(旧域名不会被本路径断流),返回 verified=false",
"提升并发守卫与边界:update 的 where 带 id + pending_domain(重复提升、用户已取消待切换、其他实例已提升过都不会误改);pending_domain 只有普通索引(非唯一),并发提交同一域名理论上可写入多行,最终由 domain 唯一索引在提升阶段兜底 —— 提升撞唯一索引转 409「域名 X 已被其他仓库使用」;retired_domain 只保留最近一个旧域名(多次连续切换会丢中间域名);首次设置(无生效域名)不写 retired_domain/retired_at,且提升时刻意不把 retired_domain 置 NULL —— 队列里可能还有更早的旧域名等待外部脚本消费,覆盖会丢失下线任务(孤儿由脚本兜底清理)",
"提升后的预期噪音:提升后到用户上传新证书前,外部证书脚本会以「cert_pem 内容为空」记一次同步失败(属预期,失败只落库、不删除旧域名文件)",
"路径二(无 pending_domain,保持升级前口径):domain_status=1 一律短路返回 verified=true、resolved_values=[],不写库、不降状态、不加 attempts(避免用户误点「校验」把生效中的域名打成验证失败而断流);domain 为空 → 400「请先设置域名」;domain_status∈{0,2} 且库内缺校验码(历史脏数据)→ 自动补发一份再校验(本次因记录尚未生效仍会失败),校验结果回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error(兼容升级前登记的历史行)",
"DNS 解析细节(多端点口径):默认按 config.frontConfig.domainVerify.dohUrls 顺序尝试(dns.alidns.com → 223.5.5.5 → doh.pub,单端点键 dohUrl 保留兼容),每个端点结果三分类 values(拿到至少一条 TXT 值 → 立即返回)/ empty(NODATA 或 NXDOMAIN)/ error(请求异常、超时、HTTP 非 200、响应体非合法 JSON);empty 与 error 都继续尝试下一个端点;全部端点未取到值后降级系统 DNS(node:dns,按 timeoutMs 限时)。只要有一个端点或系统 DNS 明确答复「无该记录」即判「未解析到记录」(返回空数组、不抛错),仅「所有 DoH 端点都是 error 且系统 DNS 也抛错」才抛 500「DNS 解析失败:{脱敏原因}」",
"缓存:提升成功后清「旧域名 + 新域名」两个公共拉取缓存 key(front:config:domain:{domain}),先写库后清缓存,清失败仅记 WARN;路径二校验成功也清该域名的缓存",
"与定时任务的关系:本接口为手动触发兜底,与 app/schedule/domain_verify_scan.js 共用同一套提升逻辑(定时任务入口为 verifyPendingDomains,逐行走 checkPendingDomainRecord / promotePendingDomain);定时任务对 pending_verify_attempts 已达 maxAttempts 的行不再自动重试(计入 skipped),但仍可通过本接口手动校验(本接口无 maxAttempts 门控)",
"脱敏:失败原因统一经 sanitizeErrorText 处理(剥离 PEM 块内容、压缩空白、截断至 500 字符)后落库与回显,不写入原始网络错误/堆栈",
"定时任务 lockTtlSeconds 默认 600s(略大于 interval 10m),避免上一轮未结束时重复加锁"
"响应契约变更(本轮 11 → 18 字段,纯追加):在 last_error 之后、verified/resolved_values 之前插入待验证域名组 7 字段(pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active),既有 9 字段与 verified/resolved_values 的名称与语义均不变。本条 response 必须同步更新 —— 其口径定义为「frontConfig.getDomain 的字段 + verified + resolved_values」,getDomain 已由 9 字段扩为 16 字段,若本条不同步则文档与代码不一致",
"errors 新增 409:提升时待验证域名已被其他仓库用为生效域名(domain 唯一索引冲突)返回 409「域名 X 已被其他仓库使用」;既有 400「请先设置域名」/ 400 未识别仓库 / 403 / 500 口径不变",
"前端改造要点:切换中(pending_active=true)调用本接口才是「校验待验证域名」;通过后应提示「切换完成,请重新上传证书」—— 提升时证书已被清空、同步状态已重置;切换期间上传的证书属于旧域名,提升后失效",
"定时任务头注释口径复核(未处理,建议由 wms-dev-agent 修正):app/schedule/domain_verify_scan.js 头注释仍写「扫描…已生成待校验 TXT 记录、且尚未通过验证的行,逐行解析 DNS TXT 记录并回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error」—— 两阶段改造后实际只扫描 pending 组、回写 pending_* 并在通过时提升;本次为文档任务且约束不改 app/** 代码,故仅报告",
"文档变更范围:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409 错误码);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增 1 条变更记录;根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)",
"维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)"
]
}
]