sdd-flow-kit 1.3.18 → 1.3.22

package/dist/core/componentSubstance.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countEffectiveLines = countEffectiveLines;
+exports.signalPresentInComponent = signalPresentInComponent;
+exports.analyzeComponentSubstance = analyzeComponentSubstance;
+exports.checkChildComponentsImported = checkChildComponentsImported;
+exports.checkComponentSubstance = checkComponentSubstance;
+/**
+ * 组件实质门禁：防止演示迁移用空壳 .vue/.tsx + 注释塞关键词过关。
+ */
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const MIN_EFFECTIVE_LINES = 40;
+const VUE_TEMPLATE_RE = /<template[^>]*>([\s\S]*?)<\/template>/i;
+const INTERACTIVE_CONTROL_RE = /<(?:n-button|a-button|el-button|NButton|AButton|ElButton|button|n-input|a-input|el-input|input|n-data-table|a-table|el-table|NDataTable|ATable|n-drawer|a-drawer)[\s/>]/i;
+const API_BEHAVIOR_RE = /from\s+['"][^'"]*(?:config\/api|api\/modules)|useMutation|useQuery|Api\s*\(|financePost|financeGet/i;
+const EMIT_HANDLER_RE = /defineEmits|emit\s*\(|@\w+\s*=\s*["']|onClick|onSubmit/i;
+/** 子组件路径启发式（Section/Modal 等须被父组件引用） */
+const CHILD_COMPONENT_RE = /(?:Section|Modal|Panel|Form)\.vue$/i;
+const PARENT_CONTAINER_RE = /(?:Drawer|index)\.vue$/i;
+/**
+ * 统计去注释后的非空行数，用于识别空壳文件。
+ */
+function countEffectiveLines(content) {
+    const stripped = (0, testAssertionAnalysis_1.stripComments)(content);
+    return stripped.split("\n").filter((l) => l.trim().length > 0).length;
+}
+/**
+ * 交互信号须出现在 template 或 script（非注释），禁止只在注释中登记。
+ */
+function signalPresentInComponent(content, signal) {
+    var _a, _b;
+    if (!signal || signal.length < 2)
+        return true;
+    const stripped = (0, testAssertionAnalysis_1.stripComments)(content);
+    const template = (_b = (_a = stripped.match(VUE_TEMPLATE_RE)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : "";
+    const script = stripped.replace(VUE_TEMPLATE_RE, "");
+    return template.includes(signal) || script.includes(signal);
+}
+/**
+ * 单文件组件实质分析（Vue SFC / TSX）。
+ */
+function analyzeComponentSubstance(relPath, content, interactionSignals) {
+    var _a, _b;
+    const issues = [];
+    const stripped = (0, testAssertionAnalysis_1.stripComments)(content);
+    const effectiveLines = countEffectiveLines(content);
+    if (effectiveLines < MIN_EFFECTIVE_LINES) {
+        issues.push(`有效代码行 ${effectiveLines} < ${MIN_EFFECTIVE_LINES}（疑似空壳）`);
+    }
+    const isVue = /\.vue$/i.test(relPath);
+    const isTsx = /\.tsx$/i.test(relPath);
+    if (isVue) {
+        const template = (_b = (_a = content.match(VUE_TEMPLATE_RE)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : "";
+        if (!template.trim()) {
+            issues.push("缺少 <template> 区块");
+        }
+        else if (!INTERACTIVE_CONTROL_RE.test(template)) {
+            issues.push("template 中未发现 button/input/table 等可交互控件");
+        }
+    }
+    else if (isTsx) {
+        if (!INTERACTIVE_CONTROL_RE.test(stripped) && !/<[A-Z]\w*/.test(stripped)) {
+            issues.push("tsx 中未发现可交互控件或业务组件");
+        }
+    }
+    const hasBehavior = API_BEHAVIOR_RE.test(stripped) || EMIT_HANDLER_RE.test(stripped);
+    if (!hasBehavior && interactionSignals.length > 0) {
+        issues.push("script 中未发现 API 调用或 emit/事件处理（疑似只读骨架）");
+    }
+    const meaningfulSignals = interactionSignals.filter((s) => s.length >= 2);
+    const missingSignals = meaningfulSignals.filter((s) => !signalPresentInComponent(content, s));
+    if (meaningfulSignals.length > 0 && missingSignals.length === meaningfulSignals.length) {
+        issues.push(`交互信号均未出现在 template/script: ${meaningfulSignals.join("、")}`);
+    }
+    else if (missingSignals.length > 0) {
+        issues.push(`缺少交互信号: ${missingSignals.join("、")}`);
+    }
+    return { ok: issues.length === 0, issues };
+}
+/**
+ * 子组件须被映射表中的容器组件（Drawer/index）或其它生产文件 import。
+ */
+async function checkChildComponentsImported(pkgRoot, mappings) {
+    const failures = [];
+    const paths = mappings.map((m) => m.productionPath.replace(/^\.\//, ""));
+    for (const m of mappings) {
+        const rel = m.productionPath.replace(/^\.\//, "");
+        if (!CHILD_COMPONENT_RE.test(rel))
+            continue;
+        if (PARENT_CONTAINER_RE.test(rel))
+            continue;
+        const base = path_1.default.basename(rel, path_1.default.extname(rel));
+        let imported = false;
+        for (const otherRel of paths) {
+            if (otherRel === rel)
+                continue;
+            const content = await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, otherRel));
+            if (!content)
+                continue;
+            if (new RegExp(`import\\s+\\w+\\s+from\\s+['"][^'"]*${base}['"]`).test(content) ||
+                content.includes(`<${base}`) ||
+                content.includes(`<${base} `)) {
+                imported = true;
+                break;
+            }
+        }
+        if (!imported) {
+            failures.push(`${m.moduleName}: ${rel} 未被父组件 import/挂载`);
+        }
+    }
+    return failures;
+}
+/**
+ * Validate/Deliver：演示映射对应的生产组件须通过实质检查。
+ */
+async function checkComponentSubstance(pkgRoot, mappings) {
+    var _a;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_COMPONENT_SUBSTANCE === "1" ||
+        process.env.OPSX_SKIP_COMPONENT_SUBSTANCE === "1";
+    if (skip) {
+        checks.push({
+            name: "component-substance",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_COMPONENT_SUBSTANCE=1",
+        });
+        return checks;
+    }
+    if (mappings.length === 0) {
+        checks.push({
+            name: "component-substance",
+            ok: true,
+            detail: "无演示映射，跳过组件实质检查",
+        });
+        return checks;
+    }
+    const failures = [];
+    for (const m of mappings) {
+        const rel = m.productionPath.replace(/^\.\//, "");
+        const abs = path_1.default.join(pkgRoot, rel);
+        const content = await (0, fs_1.readFileIfExists)(abs);
+        if (content === null) {
+            failures.push({ moduleName: m.moduleName, path: rel, reason: "文件不存在" });
+            continue;
+        }
+        const result = analyzeComponentSubstance(rel, content, m.interactionSignals);
+        if (!result.ok) {
+            failures.push({
+                moduleName: m.moduleName,
+                path: rel,
+                reason: result.issues.join("; "),
+            });
+        }
+    }
+    const importFailures = await checkChildComponentsImported(pkgRoot, mappings);
+    for (const msg of importFailures) {
+        failures.push({ moduleName: (_a = msg.split(":")[0]) !== null && _a !== void 0 ? _a : "?", path: "", reason: msg });
+    }
+    checks.push({
+        name: "component-substance",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `组件实质检查通过（${mappings.length} 个映射组件）`
+            : failures.map((f) => `${f.moduleName}(${f.path}): ${f.reason}`).join(" | "),
+    });
+    return checks;
+}

package/dist/core/demoImplementationCoverage.js

@@ -8,6 +8,7 @@ exports.checkDemoReferenceArtifacts = checkDemoReferenceArtifacts;
 exports.checkDemoImplementationCoverage = checkDemoImplementationCoverage;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const componentSubstance_1 = require("./componentSubstance");
 const fs_1 = require("./fs");
 const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
 const DEMO_SECTION_RE = /^##\s*(演示代码参照|Demo Reference)\s*$/im;
@@ -238,5 +239,6 @@ async function checkDemoImplementationCoverage(pkgRoot, changeName) {
             ? `演示模块已全部落地（${parsed.mappings.length} 项）`
             : failures.join(" | "),
     });
+    checks.push(...(await (0, componentSubstance_1.checkComponentSubstance)(pkgRoot, parsed.mappings)));
     return checks;
 }

package/dist/core/e2eAssertionDepth.js

@@ -11,6 +11,7 @@ const path_1 = __importDefault(require("path"));
 const acMatrix_1 = require("./acMatrix");
 const fs_1 = require("./fs");
 const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const e2eDemoSignalClicks_1 = require("./e2eDemoSignalClicks");
 const E2E_SPEC_RE = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
 const UI_SCENARIO_KEYWORDS = /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|导出|筛选|输入框|对话框|导航|toast|截图/i;
 async function readChangeArtifacts(changeDir) {
@@ -156,6 +157,9 @@ async function checkE2eAssertionDepth(pkgRoot, outputRoot, changeName) {
             ? `change 级 E2E 深度通过（${specPaths.join(", ")}）`
             : `E2E 断言过浅: ${depthFailures.join(" | ")}`,
     });
+    const designContent = await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, "openspec/changes", changeName, "design.md"));
+    const demoClickCheck = await (0, e2eDemoSignalClicks_1.checkE2eDemoSignalClicks)(pkgRoot, designContent, specPaths);
+    checks.push(demoClickCheck);
     const acParsed = await (0, acMatrix_1.parseAcMatrix)(outputRoot);
     if (acParsed.ok) {
         const e2eAcs = acParsed.items.filter((i) => { var _a; return /^P0$/i.test(i.priority.trim()) || /e2e/i.test((_a = i.testType) !== null && _a !== void 0 ? _a : ""); });

package/dist/core/e2eDemoSignalClicks.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.e2eExercisesSignal = e2eExercisesSignal;
+exports.checkE2eDemoSignalClicks = checkE2eDemoSignalClicks;
+/**
+ * E2E 演示信号点击门禁：design 映射表中的可点击交互信号须在 change 级 e2e 中有 click/getByRole。
+ */
+const path_1 = __importDefault(require("path"));
+const demoImplementationCoverage_1 = require("./demoImplementationCoverage");
+const fs_1 = require("./fs");
+/** 须在 E2E 中验证点击的信号特征 */
+const CLICKABLE_SIGNAL_RE = /编辑|保存|删除|新增|导入|拉取|提交|确认|取消|打开|修改|添加/i;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * 判断 E2E 源码是否对某交互信号做了点击类操作。
+ */
+function e2eExercisesSignal(e2eContent, signal) {
+    if (!signal || signal.length < 2)
+        return true;
+    const stripped = e2eContent.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    if (!stripped.includes(signal))
+        return false;
+    const esc = escapeRegExp(signal);
+    const clickPatterns = [
+        new RegExp(`\\.click\\s*\\([^)]*${esc}`),
+        new RegExp(`getByRole\\s*\\(\\s*['"]button['"][^)]*${esc}`),
+        new RegExp(`getByRole\\s*\\(\\s*['"][^'"]+['"][^)]*name:\\s*[^)]*${esc}`),
+        new RegExp(`getByText\\s*\\(\\s*['"\`]${esc}`),
+        new RegExp(`getByText\\s*\\(\\s*[^)]*${esc}`),
+        new RegExp(`locator\\s*\\([^)]*${esc}[^)]*\\)\\.click`),
+    ];
+    return clickPatterns.some((re) => re.test(stripped));
+}
+/**
+ * UI 类 change：映射表中可点击信号须在绑定的 e2e spec 中出现 click/getByRole。
+ */
+async function checkE2eDemoSignalClicks(pkgRoot, designContent, specPaths) {
+    var _a;
+    const skip = process.env.POQUAN_SKIP_E2E_DEMO_CLICKS === "1" ||
+        process.env.OPSX_SKIP_E2E_DEMO_CLICKS === "1";
+    if (skip) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_E2E_DEMO_CLICKS=1",
+        };
+    }
+    const parsed = (0, demoImplementationCoverage_1.parseDemoReferenceSection)(designContent !== null && designContent !== void 0 ? designContent : "");
+    if (parsed.exempt || parsed.mappings.length === 0) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: true,
+            detail: "无演示映射或已豁免，跳过 E2E 点击检查",
+        };
+    }
+    if (specPaths.length === 0) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: false,
+            detail: "有演示映射但未绑定 e2e spec，无法校验交互点击",
+        };
+    }
+    let e2eBlob = "";
+    for (const rel of specPaths) {
+        const content = (_a = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, rel)))) !== null && _a !== void 0 ? _a : "";
+        e2eBlob += `\n// ${rel}\n${content}`;
+    }
+    const failures = [];
+    for (const m of parsed.mappings) {
+        const clickable = m.interactionSignals.filter((s) => CLICKABLE_SIGNAL_RE.test(s));
+        if (clickable.length === 0)
+            continue;
+        const uncovered = clickable.filter((s) => !e2eExercisesSignal(e2eBlob, s));
+        if (uncovered.length === clickable.length) {
+            failures.push(`${m.moduleName}: E2E 须 click/getByRole/getByText 覆盖信号「${clickable.join("、")}」`);
+        }
+    }
+    return {
+        name: "e2e-demo-signal-clicks",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `E2E 已覆盖演示映射中的可点击信号（${specPaths.join(", ")}）`
+            : failures.join(" | "),
+    };
+}

package/dist/core/inferProject.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PRODUCT_PREFIX_BY_KIND = exports.DOC_SKILL_BY_KIND = exports.ALLOWED_PROJECTS = void 0;
 exports.productToKind = productToKind;
+exports.resolveProjectKindInput = resolveProjectKindInput;
 exports.resolveDocSkillDir = resolveDocSkillDir;
 exports.inferProjectKind = inferProjectKind;
 const promises_1 = __importDefault(require("fs/promises"));
@@ -38,6 +39,31 @@ function productToKind(product) {
         return "BreakX";
     return "OMS";
 }
+/**
+ * 将 CLI `--project` 入参解析为规范项目类型。
+ * 支持精确名、别名（adtools / ad-tools）及带空格写法；无法识别时返回 null（避免 productToKind 默认回落 OMS）。
+ */
+function resolveProjectKindInput(raw) {
+    const value = raw.trim();
+    if (!value)
+        return null;
+    if (exports.ALLOWED_PROJECTS.includes(value)) {
+        return value;
+    }
+    const upper = value.toUpperCase();
+    const compact = upper.replace(/[\s_-]+/g, "");
+    if (upper === "ADI" || upper.includes("ADINSIGHT"))
+        return "ADI";
+    if (upper === "OMS" || upper.includes("OPERATION"))
+        return "OMS";
+    if (value === "欢盟" || upper === "HUAN" || upper === "HUANMENG" || compact === "HM")
+        return "欢盟";
+    if (upper.includes("AD TOOLS") || compact === "ADTOOLS")
+        return "AD Tools";
+    if (compact === "BREAKX" || upper.includes("POQUAN") || value.includes("破圈"))
+        return "BreakX";
+    return null;
+}
 /** 从 projectRoot 向上查找 docs/*-doc-skill（适配 frontend 子目录 + 根目录 docs） */
 async function resolveDocSkillDir(projectRoot, kind) {
     const dirName = exports.DOC_SKILL_BY_KIND[kind];

package/dist/core/prdCoverage.js

@@ -15,10 +15,12 @@ const acMatrix_1 = require("./acMatrix");
 const fs_1 = require("./fs");
 const prdParse_1 = require("./prdParse");
 const prdSemanticDiff_1 = require("./prdSemanticDiff");
-const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
 const e2eAssertionDepth_1 = require("./e2eAssertionDepth");
 const apiFieldContract_1 = require("./apiFieldContract");
+const apiFieldCoverage_1 = require("./apiFieldCoverage");
+const visualRegression_1 = require("./visualRegression");
 const demoImplementationCoverage_1 = require("./demoImplementationCoverage");
+const acAssertionBinding_1 = require("./acAssertionBinding");
 const VALID_VERDICTS = ["一致", "不一致-按PRD修复", "待人工确认"];
 /** 禁止在证据/结论中出现的揣摩或兜底措辞 */
 const FORBIDDEN_SPECULATION = [
@@ -37,7 +39,6 @@ const FORBIDDEN_SPECULATION = [
     "或许",
 ];
 const TEST_FILE_RE = /\.(spec|test)\.(t|j)sx?$/i;
-const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
 async function walkFiles(dir, out) {
     let entries;
     try {
@@ -136,38 +137,12 @@ async function loadPrdAtomsFromManifest(outputRoot) {
     }
 }
 function checkAcTestMapping(items, testContents) {
-    var _a;
-    const checks = [];
-    const mustCover = items.filter((i) => { var _a; return /^P0$/i.test(i.priority.trim()) || /e2e/i.test((_a = i.testType) !== null && _a !== void 0 ? _a : ""); });
-    for (const ac of mustCover) {
-        const e2eRequired = /e2e/i.test((_a = ac.testType) !== null && _a !== void 0 ? _a : "");
-        const hits = testContents.filter((t) => (0, testAssertionAnalysis_1.hasMeaningfulAcCoverageInFile)(t.rel, t.content, ac.id).covered);
-        const e2eHits = hits.filter((h) => E2E_DIR_RE.test(h.rel));
-        if (hits.length === 0) {
-            checks.push({
-                name: `ac-test-${ac.id}`,
-                ok: false,
-                detail: `${ac.id}(${ac.priority}) 未在有效 test/it 块中找到 [${ac.id}] + expect 映射（注释登记不计入）`,
-            });
-            continue;
-        }
-        if (e2eRequired && e2eHits.length === 0) {
-            checks.push({
-                name: `ac-e2e-${ac.id}`,
-                ok: false,
-                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 或 playwright/ 下无含 expect 的对应测试`,
-            });
-            continue;
-        }
-        checks.push({
-            name: `ac-test-${ac.id}`,
-            ok: true,
-            detail: e2eRequired
-                ? `${ac.id} 已映射（含 e2e: ${e2eHits.map((h) => path_1.default.basename(h.rel)).join(", ")})`
-                : `${ac.id} 已映射: ${hits.map((h) => path_1.default.basename(h.rel)).join(", ")}`,
-        });
-    }
-    return checks;
+    const bindingChecks = (0, acAssertionBinding_1.checkAcAssertionBinding)(items, testContents.map((t) => ({ rel: t.rel, content: t.content })));
+    return bindingChecks.map((c) => ({
+        name: c.name,
+        ok: c.ok,
+        detail: c.detail,
+    }));
 }
 function checkSemanticDiffItems(semantic) {
     const checks = [];
@@ -421,10 +396,14 @@ async function checkPrdCoverage(outputRoot, pkgRoot, options) {
             });
         }));
         checks.push(...checkAcTestMapping(acParsed.items, testContents));
+        if (options === null || options === void 0 ? void 0 : options.changeName) {
+            checks.push(...(await (0, visualRegression_1.checkVisualRegression)(pkgRoot, outputRoot, options.changeName, acParsed.items)));
+        }
     }
     if (options === null || options === void 0 ? void 0 : options.changeName) {
         checks.push(...(await (0, e2eAssertionDepth_1.checkE2eAssertionDepth)(pkgRoot, outputRoot, options.changeName)));
         checks.push(...(await (0, apiFieldContract_1.checkApiFieldContract)(pkgRoot, options.changeName)));
+        checks.push(...(await (0, apiFieldCoverage_1.checkApiFieldCoverage)(pkgRoot, options.changeName, outputRoot)));
         checks.push(...(await (0, demoImplementationCoverage_1.checkDemoImplementationCoverage)(pkgRoot, options.changeName)));
     }
     const ok = checks.every((c) => c.ok);

package/dist/core/snakeCamel.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * snake_case ↔ camelCase 深转换（与前端 caseTransform 语义一致，供门禁脚本使用）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snakeKeyToCamel = snakeKeyToCamel;
+exports.snakeToCamelDeep = snakeToCamelDeep;
+exports.hasSnakeCaseKeys = hasSnakeCaseKeys;
+exports.collectLeafCamelKeys = collectLeafCamelKeys;
+exports.extractFirstListRow = extractFirstListRow;
+function snakeKeyToCamel(key) {
+    return key.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+}
+function snakeToCamelDeep(input) {
+    if (input === null || input === undefined) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map((item) => snakeToCamelDeep(item));
+    }
+    if (typeof input === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(input)) {
+            result[snakeKeyToCamel(key)] = snakeToCamelDeep(value);
+        }
+        return result;
+    }
+    return input;
+}
+/** 对象是否含 snake_case 键（判定为后端样例 fixture） */
+function hasSnakeCaseKeys(input) {
+    if (input === null || typeof input !== "object")
+        return false;
+    if (Array.isArray(input)) {
+        return input.some((item) => hasSnakeCaseKeys(item));
+    }
+    for (const key of Object.keys(input)) {
+        if (key.includes("_"))
+            return true;
+        if (hasSnakeCaseKeys(input[key]))
+            return true;
+    }
+    return false;
+}
+/** 收集对象所有叶子路径的 camelCase 键名（末级 key） */
+function collectLeafCamelKeys(input, out = new Set()) {
+    if (input === null || input === undefined)
+        return out;
+    if (Array.isArray(input)) {
+        for (const item of input)
+            collectLeafCamelKeys(item, out);
+        return out;
+    }
+    if (typeof input === "object") {
+        const obj = input;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return out;
+        const allPrimitive = keys.every((k) => obj[k] === null || ["string", "number", "boolean"].includes(typeof obj[k]));
+        if (allPrimitive) {
+            for (const k of keys)
+                out.add(k);
+            return out;
+        }
+        for (const k of keys)
+            collectLeafCamelKeys(obj[k], out);
+        return out;
+    }
+    return out;
+}
+/** 从常见分页响应结构取首条列表行 */
+function extractFirstListRow(payload) {
+    var _a, _b;
+    const normalized = snakeToCamelDeep(payload);
+    const candidates = [
+        normalized,
+        normalized.data,
+        normalized.records,
+        (_a = normalized.data) === null || _a === void 0 ? void 0 : _a.records,
+        (_b = normalized.data) === null || _b === void 0 ? void 0 : _b.items,
+        normalized.items,
+        normalized.list,
+    ];
+    for (const c of candidates) {
+        if (Array.isArray(c) && c.length > 0 && typeof c[0] === "object" && c[0] !== null) {
+            return c[0];
+        }
+    }
+    if (typeof normalized === "object" && normalized !== null && !Array.isArray(normalized)) {
+        return normalized;
+    }
+    return null;
+}

package/dist/core/techDocQuality.js

@@ -24,6 +24,7 @@ exports.REQUIRED_TECH_DOC_SECTIONS = [
 const MIN_LINES = 150;
 const MIN_H3_UNDER_SCOPE = 2;
 const API_TABLE_RE = /\|\s*接口\s*\|\s*Method\s*\|/m;
+const FIELD_MAPPING_TABLE_RE = /\|\s*后端字段\s*\|\s*前端字段\s*\|/m;
 const DEMO_TABLE_RE = /\|\s*演示模块\s*\|\s*演示文件\/组件\s*\|/m;
 const AC_REF_RE = /\[AC-\d{2,}\]/g;
 /** 典型「摘要版」反模式：仅若干条顶层 [AC-xx]  bullet，无三级标题 */
@@ -59,6 +60,9 @@ function checkTechDocStructure(content) {
     if (!API_TABLE_RE.test(content)) {
         missingSections.push("4.1 接口清单表格（| 接口 | Method |）");
     }
+    if (API_TABLE_RE.test(content) && !FIELD_MAPPING_TABLE_RE.test(content)) {
+        missingSections.push("4.3.1 响应字段映射表（| 后端字段 | 前端字段 |）");
+    }
     if (!DEMO_TABLE_RE.test(content)) {
         missingSections.push("2.4 演示模块映射表格（| 演示模块 | 演示文件/组件 |）");
     }