FoXiMao/a-share-analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(GOV-009): 支持固定开发库结构基线

Browse Source
This commit is contained in:
FoXiMao
2026-08-13 15:43:06 +08:00
parent c5a6e6a2c0
commit b3d8e29f52
6 changed files with 207 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/database/schema-baseline.mjs
+96 -19
View File
@@ -15,12 +15,15 @@ import { fileURLToPath } from 'node:url';
const DEVELOPMENT_DATABASE = 'a_share_analysis_dev';
const REQUIRED_CHARSET = 'utf8mb4';
const REQUIRED_COLLATION = 'utf8mb4_general_ci';
const BASELINE_FORMAT_VERSION = 1;
const TOOL_VERSION = '1.0.0';
const BASELINE_FORMAT_VERSION = 2;
const LEGACY_BASELINE_FORMAT_VERSION = 1;
const TOOL_VERSION = '2.0.0';
const LEGACY_TOOL_VERSION = '1.0.0';
const VERSION_PATTERN = /^v\d+\.\d+\.\d+$/;
const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '112.192.20.11']);
const OBJECT_KEYS = Object.freeze(['tables', 'views', 'triggers', 'routines', 'events']);
const CAPTURED_FILES = Object.freeze(['checksum.sha256', 'manifest.yaml', 'schema.sql']);
const CAPTURED_EMPTY_FILES = Object.freeze(['manifest.yaml']);
const NOT_APPLICABLE_FILES = Object.freeze(['manifest.yaml']);
function requireExactValue(actual, expected, message) {
@@ -34,8 +37,9 @@ function isEnabled(value) {
}
/**
* Schema 工具拥有比普通应用启动更窄的权限边界：即使连接地址看起来是本机，
* 环境名和数据库名也必须同时命中固定开发值，避免通过参数误切到生产库。
* Schema 工具拥有比普通应用启动更窄的权限边界：环境名、数据库名和主机必须
* 同时命中代码内固定值。远程开发库不能通过 env 或命令参数动态扩展白名单，
* 避免把一次临时连接授权意外变成生产数据库访问能力。
*/
export function assertSafeDevelopmentConfiguration(config) {
requireExactValue(config.APP_ENV, 'development', 'Schema 基线只允许 development 环境');
@@ -53,7 +57,7 @@ export function assertSafeDevelopmentConfiguration(config) {
if (isEnabled(config.MYSQL_ENABLED)) {
if (!DEVELOPMENT_HOSTS.has(config.MYSQL_HOST)) {
throw new Error(
`Schema 基线只允许通过开发机回环地址连接，实际 ${config.MYSQL_HOST || '(空)'}；远程开发库必须先建立本地 SSH 隧道`,
`Schema 基线只允许固定开发数据库主机白名单，实际 ${config.MYSQL_HOST || '(空)'}`,
);
}
for (const key of ['MYSQL_HOST', 'MYSQL_PORT', 'MYSQL_USERNAME', 'MYSQL_PASSWORD']) {
@@ -265,6 +269,17 @@ function sha256(content) {
return createHash('sha256').update(content, 'utf8').digest('hex');
}
function countSchemaObjects(sql) {
const definitions = String(sql);
return Object.freeze({
tables: (definitions.match(/\bCREATE\s+TABLE\b/gi) ?? []).length,
views: (definitions.match(/\b(?:CREATE\s+)?VIEW\s+`/gi) ?? []).length,
triggers: (definitions.match(/\bTRIGGER\s+`/gi) ?? []).length,
routines: (definitions.match(/\b(?:PROCEDURE|FUNCTION)\s+`/gi) ?? []).length,
events: (definitions.match(/\bEVENT\s+`/gi) ?? []).length,
});
}
function buildManifest(fields) {
// JSON 是 YAML 1.2 的严格子集；使用标准解析器生成和读取，避免手写 YAML
// 对缩进、引号和同名嵌套字段产生歧义，同时仍保留约定的 manifest.yaml 文件名。
@@ -292,6 +307,7 @@ function buildManifest(fields) {
routines: fields.captured,
events: fields.captured,
},
object_counts: fields.objectCounts,
},
null,
2,
@@ -305,13 +321,14 @@ export function buildCapturedArtifacts(metadata, sql) {
}
const normalizedSql = normalizeSchemaSql(sql);
if (!normalizedSql.trim()) {
throw new Error('真实 Schema SQL 不能为空');
return buildCapturedEmptyArtifacts(metadata);
}
const schemaSha256 = sha256(normalizedSql);
const manifest = buildManifest({
...metadata,
status: 'captured',
captured: true,
objectCounts: countSchemaObjects(normalizedSql),
schemaSha256,
});
return Object.freeze({
@@ -325,6 +342,27 @@ export function buildCapturedArtifacts(metadata, sql) {
});
}
export function buildCapturedEmptyArtifacts(metadata) {
assertMysql57Metadata(metadata);
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
}
const schemaSha256 = sha256('');
const objectCounts = Object.freeze(Object.fromEntries(OBJECT_KEYS.map((key) => [key, 0])));
const manifest = buildManifest({
...metadata,
status: 'captured_empty',
captured: false,
objectCounts,
schemaSha256,
});
return Object.freeze({
status: 'captured_empty',
schemaSha256,
files: Object.freeze({ 'manifest.yaml': manifest }),
});
}
export function buildNotApplicableArtifacts(metadata) {
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
@@ -337,6 +375,7 @@ export function buildNotApplicableArtifacts(metadata) {
status: 'not_applicable',
reason: 'mysql_disabled',
captured: false,
objectCounts: Object.fromEntries(OBJECT_KEYS.map((key) => [key, 0])),
});
return Object.freeze({
status: 'not_applicable',
@@ -424,9 +463,13 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
const status = manifest.status;
const applicationVersion = manifest.application_version;
const generatedAt = Date.parse(manifest.generated_at ?? '');
const supportedFormat =
(manifest.format_version === LEGACY_BASELINE_FORMAT_VERSION &&
manifest.generator === `schema-baseline/${LEGACY_TOOL_VERSION}`) ||
(manifest.format_version === BASELINE_FORMAT_VERSION &&
manifest.generator === `schema-baseline/${TOOL_VERSION}`);
if (
manifest.format_version !== BASELINE_FORMAT_VERSION ||
manifest.generator !== `schema-baseline/${TOOL_VERSION}` ||
!supportedFormat ||
!Number.isFinite(generatedAt) ||
!/^[0-9a-f]{40}$/.test(manifest.git_commit ?? '')
) {
@@ -473,6 +516,29 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
}
return { status, applicationVersion, reason };
}
if (status === 'captured_empty') {
if (manifest.format_version !== BASELINE_FORMAT_VERSION) {
throw new Error('空库 Schema 基线只允许 format v2');
}
assertExactFileSet(targetDirectory, CAPTURED_EMPTY_FILES);
assertMysql57Metadata({
mysqlClientVersion: manifest.mysql_client_version,
mysqldumpClientVersion: manifest.mysqldump_client_version,
serverVersion: manifest.mysql_server_version,
databaseCharset: manifest.charset,
databaseCollation: manifest.collation,
});
const expectedEmptyChecksum = sha256('');
if (
manifest.schema_sha256 !== expectedEmptyChecksum ||
Object.keys(manifest.object_counts ?? {}).sort().join(',') !==
[...OBJECT_KEYS].sort().join(',') ||
OBJECT_KEYS.some((key) => manifest.object_counts[key] !== 0)
) {
throw new Error('空库 Schema 清单必须证明所有对象计数为零');
}
return { status, applicationVersion, schemaSha256: expectedEmptyChecksum };
}
if (status !== 'captured') {
throw new Error(`Schema 基线状态无效：${status}`);
}
@@ -491,6 +557,16 @@ export function verifyBaselineDirectory(targetDirectory, expectedRelease, expect
for (const objectName of OBJECT_KEYS) {
requireExactValue(manifest.objects?.[objectName], true, `Schema 对象范围缺少 ${objectName}`);
}
if (
manifest.format_version === BASELINE_FORMAT_VERSION &&
(Object.keys(manifest.object_counts ?? {}).sort().join(',') !==
[...OBJECT_KEYS].sort().join(',') ||
OBJECT_KEYS.some(
(key) => !Number.isInteger(manifest.object_counts[key]) || manifest.object_counts[key] < 0,
))
) {
throw new Error('Schema 对象计数字段无效');
}
const sql = readFileSync(path.join(targetDirectory, 'schema.sql'), 'utf8');
if (!sql.trim()) {
throw new Error('真实 Schema SQL 不能为空');
@@ -643,14 +719,9 @@ export function getCurrentReleasedVersion(repositoryRoot) {
* 下一版本开发开始前先从开发库生成 captured 基线。
*/
export function assertNotApplicableMatchesDevelopmentConfiguration(repositoryRoot, result) {
if (result.status !== 'not_applicable') return result;
const config = assertSafeDevelopmentConfiguration(
parseEnvironmentFile(readFileSync(resolveFixedDevelopmentEnv(repositoryRoot), 'utf8')),
);
if (config.MYSQL_ENABLED) {
throw new Error('当前开发环境已启用 MySQL，不能继续使用 not_applicable Schema 基线');
}
// 已发布清单记录的是发布当时的数据库启用状态。当前开发配置只能决定下一份
// 基线如何生成，不能反向否定或改写已发布版本的历史事实。
void repositoryRoot;
return result;
}
@@ -734,8 +805,14 @@ export function assertRemoteBranchMatches(repositoryRoot, branch, gitRunner = ru
}
function resolveFixedDevelopmentEnv(repositoryRoot) {
const realDevelopmentEnv = path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env');
export function resolveFixedDevelopmentEnv(repositoryRoot) {
const realDevelopmentEnv = path.join(
repositoryRoot,
'deploy',
'env',
'development',
'api.env.local',
);
if (existsSync(realDevelopmentEnv)) return realDevelopmentEnv;
return path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.example');
}