223 行
9.4 KiB
JavaScript
223 行
9.4 KiB
JavaScript
import assert from 'node:assert/strict';
|
|
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
import { tmpdir } from 'node:os';
|
|
import path from 'node:path';
|
|
import test from 'node:test';
|
|
|
|
import {
|
|
parseFrontmatter,
|
|
runFrontmatterValidation,
|
|
validateFrontendState,
|
|
validateFrontendTransition,
|
|
validateV2Document,
|
|
} from '../scripts/validate-changelog-frontmatter.mjs';
|
|
|
|
|
|
const FILE = 'changelogs-v2/2026-07/24_5218_工作流治理-修改接口-管理后台.md';
|
|
|
|
function metadata(overrides = {}) {
|
|
return {
|
|
schema: 'hl-changelog/v2',
|
|
ticket: '5218',
|
|
title: '工作流治理',
|
|
consumer: 'admin',
|
|
author: 'lc(GIT)',
|
|
change_type: '修改接口',
|
|
backend_status: 'deployed',
|
|
gateway_status: 'verified',
|
|
frontend_status: 'pending',
|
|
frontend_owner: '',
|
|
frontend_ref: '',
|
|
target_release: '',
|
|
verified_at: '',
|
|
status_note: '',
|
|
updated_at: '2026-07-24',
|
|
base: 'dev-v3',
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
function document(overrides = {}) {
|
|
const fields = metadata(overrides);
|
|
const frontmatter = Object.entries(fields)
|
|
.map(([key, value]) => `${key}: "${value}"`)
|
|
.join('\n');
|
|
return `---\n${frontmatter}\n---\n\n# 工作流治理\n\n## 二、变更接口清单\n\n| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |\n|---|---|---|---|---|---|\n| 1 | 保存配置 | POST | \`/admin/workflow/config\` | 修改请求 | 保存工作流配置 |\n\n## 三、接口详情\n\n### 1. 保存配置 \`POST /admin/workflow/config\`\n\n**VO**: \`WorkflowConfigReqVO / String\`\n\n#### 使用场景\n\n- 管理员保存工作流配置。\n\n#### 入参\n\n| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |\n|---|---|---|---|---|---|\n| name | Body | String | ✅ | 非空 | 配置名称 |\n\n#### 出参 \`Result<String>\`\n\n| 字段 | 类型 | 说明 |\n|---|---|---|\n| data | String | 配置 ID |\n\n#### 请求示例\n\n\`\`\`json\n{ "name": "审批流" }\n\`\`\`\n\n#### 响应示例\n\n\`\`\`json\n{ "code": 200, "message": "成功", "data": "1", "success": true }\n\`\`\`\n\n#### 空数据 / 降级响应\n\n成功时一定返回字符串 ID。\n\n#### 错误响应\n\n\`\`\`json\n{ "code": 400, "message": "name 不能为空", "data": null, "success": false }\n\`\`\`\n\n#### 业务边界\n\n- 业务失败也必须检查响应体 code。\n\n## 四、契约约束与正确调用方式\n\n- 请求体必须使用 JSON。\n\n## 五、数据库行为\n\n- 成功请求保存一份配置，失败请求不产生业务写入。\n\n## 六、边界行为\n\n- 未登录返回 401。\n\n## 六.6、修改前后对比\n\n| 字段 | 改前 | 改后 |\n|---|---|---|\n| name | 可为空 | 必填 |\n\n## 六.7、影响评估\n\n- **是否破坏向后兼容**: 否\n- **前端是否必须同步上线**: 是\n- **前端 workaround 清理点**: 无\n\n## 七、不影响范围\n\n- 查询接口不变。\n\n## 八、测试环境已验证\n\n- POST /admin/workflow/config → 200 ✓\n\n## 十、相关文档\n\n- Issue: #5218\n\n## 关联 / 联系人\n\n- **后端负责人**: @lc\n`;
|
|
}
|
|
|
|
function incompleteApiDocument() {
|
|
const fields = metadata();
|
|
const frontmatter = Object.entries(fields)
|
|
.map(([key, value]) => `${key}: "${value}"`)
|
|
.join('\n');
|
|
return `---\n${frontmatter}\n---\n\n# 工作流治理\n\n## 变更接口\n\n- POST /admin/workflow/config。\n\n## 验证证据\n\n- 自动化测试通过。\n`;
|
|
}
|
|
|
|
test('parses quoted flat YAML frontmatter', () => {
|
|
const parsed = parseFrontmatter(document());
|
|
assert.equal(parsed.metadata.schema, 'hl-changelog/v2');
|
|
assert.equal(parsed.metadata.frontend_status, 'pending');
|
|
});
|
|
|
|
test('CHANGELOG_TEMPLATE.md contains every section enforced for API handoffs', () => {
|
|
const template = readFileSync(
|
|
new URL('../CHANGELOG_TEMPLATE.md', import.meta.url),
|
|
'utf8',
|
|
);
|
|
for (const value of [
|
|
'author: "{推送者登录名}(GIT)"',
|
|
'## 二、变更接口清单',
|
|
'## 三、接口详情',
|
|
'#### 使用场景',
|
|
'#### 入参',
|
|
'#### 出参',
|
|
'#### 请求示例',
|
|
'#### 响应示例',
|
|
'#### 空数据 / 降级响应',
|
|
'#### 错误响应',
|
|
'#### 业务边界',
|
|
'## 四、契约约束与正确调用方式',
|
|
'## 五、数据库行为',
|
|
'## 六、边界行为',
|
|
'## 六.6、修改前后对比',
|
|
'## 六.7、影响评估',
|
|
'## 七、不影响范围',
|
|
'## 八、测试环境已验证',
|
|
'## 十、相关文档',
|
|
'## 关联 / 联系人',
|
|
]) {
|
|
assert.ok(template.includes(value), `template missing ${value}`);
|
|
}
|
|
});
|
|
|
|
test('accepts a complete v2 handoff with pending frontend consumption', () => {
|
|
assert.deepEqual(validateV2Document(FILE, document(), { requireV2: true }), []);
|
|
});
|
|
|
|
test('rejects an API handoff that does not follow CHANGELOG_TEMPLATE.md', () => {
|
|
const errors = validateV2Document(FILE, incompleteApiDocument(), { requireV2: true });
|
|
assert.ok(errors.some(({ code }) => code === 'E_API_TEMPLATE'));
|
|
});
|
|
|
|
test('rejects an endpoint detail without a required self-contained contract block', () => {
|
|
const value = document().replace('#### 错误响应', '#### 异常说明');
|
|
const errors = validateV2Document(FILE, value, { requireV2: true });
|
|
assert.ok(errors.some(({ code }) => code === 'E_API_DETAIL'));
|
|
});
|
|
|
|
test('requires a use case and explicit empty/degraded behavior for every endpoint', () => {
|
|
const value = document()
|
|
.replace('#### 使用场景', '#### 调用时机')
|
|
.replace('#### 空数据 / 降级响应', '#### 无数据');
|
|
const errors = validateV2Document(FILE, value, { requireV2: true });
|
|
assert.ok(errors.some(({ code, message }) => (
|
|
code === 'E_API_DETAIL'
|
|
&& message.includes('使用场景')
|
|
&& message.includes('空数据 / 降级响应')
|
|
)));
|
|
});
|
|
|
|
test('rejects a mismatch between the API list and endpoint detail headings', () => {
|
|
const value = document().replace(
|
|
'### 1. 保存配置 `POST /admin/workflow/config`',
|
|
'### 1. 保存配置 `POST /admin/workflow/other`',
|
|
);
|
|
const errors = validateV2Document(FILE, value, { requireV2: true });
|
|
assert.ok(errors.some(({ code }) => code === 'E_API_ENDPOINTS'));
|
|
});
|
|
|
|
test('requires the template author format and write-operation database section', () => {
|
|
const invalidAuthor = validateV2Document(
|
|
FILE,
|
|
document({ author: 'lc' }),
|
|
{ requireV2: true },
|
|
);
|
|
assert.ok(invalidAuthor.some(({ code }) => code === 'E_AUTHOR'));
|
|
|
|
const withoutDatabaseBehavior = document().replace(
|
|
'## 五、数据库行为',
|
|
'## 五、持久化说明',
|
|
);
|
|
const errors = validateV2Document(FILE, withoutDatabaseBehavior, { requireV2: true });
|
|
assert.ok(errors.some(({ code }) => code === 'E_API_TEMPLATE'));
|
|
});
|
|
|
|
test('rejects backend and gateway pending at publication', () => {
|
|
const errors = validateV2Document(
|
|
FILE,
|
|
document({ backend_status: 'pending', gateway_status: 'pending' }),
|
|
{ requireV2: true },
|
|
);
|
|
assert.ok(errors.some(({ code }) => code === 'E_BACKEND_PENDING'));
|
|
assert.ok(errors.some(({ code }) => code === 'E_GATEWAY_PENDING'));
|
|
});
|
|
|
|
test('requires frontend evidence as status advances', () => {
|
|
assert.deepEqual(
|
|
validateFrontendState(metadata({ frontend_status: 'claimed' })),
|
|
['claimed 必须填写 frontend_owner'],
|
|
);
|
|
assert.deepEqual(
|
|
validateFrontendState(metadata({
|
|
frontend_status: 'implemented',
|
|
frontend_owner: 'frontend-team',
|
|
frontend_ref: 'mmg/hl-ui@abc1234',
|
|
})),
|
|
[],
|
|
);
|
|
assert.ok(
|
|
validateFrontendState(metadata({
|
|
frontend_status: 'verified',
|
|
frontend_owner: 'frontend-team',
|
|
frontend_ref: 'mmg/hl-ui@abc1234',
|
|
target_release: 'prod-2026.07.24',
|
|
verified_at: '2026-02-30',
|
|
})).includes('verified_at 必须是 ISO 日期或时间'),
|
|
);
|
|
});
|
|
|
|
test('rejects skipped transitions and requires a rollback reason', () => {
|
|
assert.ok(validateFrontendTransition('pending', 'implemented').length > 0);
|
|
assert.deepEqual(validateFrontendTransition('pending', 'claimed'), []);
|
|
assert.ok(validateFrontendTransition('released', 'implemented').length > 0);
|
|
assert.deepEqual(
|
|
validateFrontendTransition('released', 'implemented', '测试发布已回滚'),
|
|
[],
|
|
);
|
|
});
|
|
|
|
test('new changelog requires v2 while a modified legacy file remains compatible', () => {
|
|
const root = mkdtempSync(path.join(tmpdir(), 'hl-frontmatter-'));
|
|
try {
|
|
const file = path.join(root, ...FILE.split('/'));
|
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
writeFileSync(file, '# legacy\n');
|
|
const newResult = runFrontmatterValidation([{ status: 'A', targetPath: FILE }], root);
|
|
assert.ok(newResult.errors.some(({ code }) => code === 'E_FRONTMATTER'));
|
|
const modifiedResult = runFrontmatterValidation([{ status: 'M', targetPath: FILE }], root);
|
|
assert.deepEqual(modifiedResult.errors, []);
|
|
} finally {
|
|
rmSync(root, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
test('detects metadata and filename mismatches', () => {
|
|
const errors = validateV2Document(
|
|
FILE,
|
|
document({ ticket: '9999', change_type: '新增接口' }),
|
|
{ requireV2: true },
|
|
);
|
|
assert.ok(errors.some(({ code }) => code === 'E_TICKET_MISMATCH'));
|
|
assert.ok(errors.some(({ code }) => code === 'E_TYPE_MISMATCH'));
|
|
});
|
|
|
|
test('rejects unsupported consumers and impossible dates', () => {
|
|
const errors = validateV2Document(
|
|
FILE,
|
|
document({ consumer: 'browser', updated_at: '2026-02-30' }),
|
|
{ requireV2: true },
|
|
);
|
|
assert.ok(errors.some(({ code }) => code === 'E_CONSUMER'));
|
|
assert.ok(errors.some(({ code }) => code === 'E_UPDATED_AT'));
|
|
});
|