sdd-flow-kit 1.3.18 → 1.3.22

package/dist/cli.js

@@ -27,15 +27,42 @@ const runGuard_1 = require("./steps/runGuard");
 const bootstrap_1 = require("./core/bootstrap");
 const projectRoots_1 = require("./core/projectRoots");
 const versionIntent_1 = require("./core/versionIntent");
+const inferProject_1 = require("./core/inferProject");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
-function getArgValue(flag) {
+/** 读取 flag 后的参数；allowMultiWord 时合并至下一个以 - 开头的 token（支持未加引号的 AD Tools）。 */
+function getArgValue(flag, options) {
     const idx = process_1.default.argv.indexOf(flag);
     if (idx === -1)
         return null;
-    const v = process_1.default.argv[idx + 1];
-    if (!v)
+    const first = process_1.default.argv[idx + 1];
+    if (!first || first.startsWith("-"))
         return null;
-    return v;
+    if (!(options === null || options === void 0 ? void 0 : options.allowMultiWord))
+        return first;
+    const parts = [first];
+    for (let i = idx + 2; i < process_1.default.argv.length; i += 1) {
+        const token = process_1.default.argv[i];
+        if (token.startsWith("-"))
+            break;
+        parts.push(token);
+    }
+    return parts.join(" ");
+}
+/** 统计 flag 在 argv 中占用的 token 数（含多词值），供 getFreeTextArgs 跳过。 */
+function countFlagArgTokens(flag) {
+    const idx = process_1.default.argv.indexOf(flag);
+    if (idx === -1)
+        return 0;
+    if (flag === "--project") {
+        const raw = getArgValue("--project", { allowMultiWord: true });
+        if (!raw)
+            return 1;
+        return 1 + raw.split(" ").length;
+    }
+    const next = process_1.default.argv[idx + 1];
+    if (!next || next.startsWith("-"))
+        return 1;
+    return 2;
 }
 function getFreeTextArgs(startIndex) {
     const flagsWithValue = new Set([
@@ -64,7 +91,8 @@ function getFreeTextArgs(startIndex) {
             continue;
         }
         if (flagsWithValue.has(token)) {
-            i += 1;
+            const consumed = countFlagArgTokens(token);
+            i += Math.max(consumed - 1, 0);
             continue;
         }
         if (token.startsWith("--"))
@@ -142,7 +170,7 @@ function printHelp() {
         "   环境变量 SDD_FLOW_KIT_LEGACY_MONOREPO=1 恢复「仓库根无 package.json 时落到 frontend/」",
         "   --agent <name>         cursor | claude-code | codex | openclaw | custom（默认 claude-code）",
         "   --branch <name>        开发分支；不存在会自动创建",
-        "   --project <name>       OMS | ADI | 欢盟 | AD Tools | BreakX（默认 OMS，用于生成 docs/*-doc-skill）",
+        "   --project <name>       OMS | ADI | 欢盟 | AD Tools | BreakX（默认 OMS；支持 \"AD Tools\" / AD Tools / adtools）",
         "   -y                     非交互模式（使用默认值）",
         "   --dry-run              预演模式：仅检测并输出计划，不执行写入/安装/切分支",
         "   --plan-json            输出机器可读 JSON 计划结果",
@@ -152,7 +180,7 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
@@ -216,7 +244,9 @@ async function main() {
         ? ((_h = getArgValue("--text")) !== null && _h !== void 0 ? _h : getFreeTextArgs(3)).trim()
         : "";
     const guardIntent = rawGuardText ? (0, versionIntent_1.parseVersionIntent)(rawGuardText) : null;
-    const projectKind = ((_k = (_j = getArgValue("--project")) !== null && _j !== void 0 ? _j : guardIntent === null || guardIntent === void 0 ? void 0 : guardIntent.product) !== null && _k !== void 0 ? _k : "OMS");
+    const rawProjectArg = getArgValue("--project", { allowMultiWord: true });
+    const resolvedProject = rawProjectArg ? (0, inferProject_1.resolveProjectKindInput)(rawProjectArg) : null;
+    const projectKind = (_j = resolvedProject !== null && resolvedProject !== void 0 ? resolvedProject : ((guardIntent === null || guardIntent === void 0 ? void 0 : guardIntent.product) ? (0, inferProject_1.resolveProjectKindInput)(guardIntent.product) : null)) !== null && _j !== void 0 ? _j : "OMS";
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -225,10 +255,9 @@ async function main() {
         return;
     }
     const agent = agentValue;
-    const allowedProjects = ["OMS", "ADI", "欢盟", "AD Tools", "BreakX"];
-    if (!allowedProjects.includes(projectKind)) {
+    if (rawProjectArg && !resolvedProject) {
         // eslint-disable-next-line no-console
-        console.error(`不支持的 --project: ${projectKind}（可选：${allowedProjects.join(" / ")}）`);
+        console.error(`不支持的 --project: ${rawProjectArg}（可选：${inferProject_1.ALLOWED_PROJECTS.join(" / ")}；别名示例：adtools）`);
         process_1.default.exitCode = 1;
         return;
     }
@@ -467,7 +496,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const from = ((_l = getArgValue("--from")) !== null && _l !== void 0 ? _l : "docs-done");
+        const from = ((_k = getArgValue("--from")) !== null && _k !== void 0 ? _k : "docs-done");
         if (!CHAIN_FROM.includes(from)) {
             // eslint-disable-next-line no-console
             console.error(`chain 需要 --from ${CHAIN_FROM.join("|")}`);
@@ -496,7 +525,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const modeArg = (_m = getArgValue("--execution-mode")) !== null && _m !== void 0 ? _m : getArgValue("--executionMode");
+        const modeArg = (_l = getArgValue("--execution-mode")) !== null && _l !== void 0 ? _l : getArgValue("--executionMode");
         const textArg = getArgValue("--text");
         const strictCommands = process_1.default.argv.includes("--strict-commands");
         const result = await (0, runSessionMode_1.runSessionMode)({

package/dist/core/acAssertionBinding.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCriterionLiterals = extractCriterionLiterals;
+exports.testBlockBindsCriterionLiterals = testBlockBindsCriterionLiterals;
+exports.testBlockIsFuzzyOnly = testBlockIsFuzzyOnly;
+exports.checkAcAssertionBinding = checkAcAssertionBinding;
+/**
+ * AC 断言绑定门禁：P0 AC 的验收标准字面量须出现在对应 test/it 块的 expect 中。
+ */
+const path_1 = __importDefault(require("path"));
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const MIN_LITERAL_LEN = 4;
+/** 模糊断言：仅匹配过短的成功/失败类文案 */
+const FUZZY_ONLY_ASSERT_RE = /expect\s*\([^)]*\)\s*\.toContain(?:Text)?\s*\(\s*['"](?:成功|失败|错误|保存|完成)['"]\s*\)/;
+/**
+ * 从 05「验收标准」列提取可机械比对的字面量（引号、placeholder、toast 等）。
+ */
+function extractCriterionLiterals(criterion) {
+    var _a;
+    const out = new Set();
+    const text = criterion !== null && criterion !== void 0 ? criterion : "";
+    const quotedPatterns = [
+        /「([^」]{3,})」/g,
+        /"([^"]{3,})"/g,
+        /'([^']{3,})'/g,
+        /`([^`]{3,})`/g,
+    ];
+    for (const re of quotedPatterns) {
+        let m;
+        const r = new RegExp(re.source, re.flags);
+        while ((m = r.exec(text)) !== null) {
+            const v = (_a = m[1]) === null || _a === void 0 ? void 0 : _a.trim();
+            if (v && v.length >= MIN_LITERAL_LEN)
+                out.add(v);
+        }
+    }
+    const placeholder = text.match(/请输入[^\s，,。；;]+/);
+    if ((placeholder === null || placeholder === void 0 ? void 0 : placeholder[0]) && placeholder[0].length >= MIN_LITERAL_LEN) {
+        out.add(placeholder[0]);
+    }
+    const tooltip = text.match(/tooltip[^，,。]*[「"]([^」"]{3,})[」"]/i);
+    if (tooltip === null || tooltip === void 0 ? void 0 : tooltip[1])
+        out.add(tooltip[1].trim());
+    return [...out];
+}
+/**
+ * test 块内 expect 是否包含验收标准中的至少一条字面量。
+ */
+function testBlockBindsCriterionLiterals(blockBody, literals) {
+    if (literals.length === 0)
+        return true;
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    if (!/\bexpect\s*\(/.test(body))
+        return false;
+    const hasLiteral = literals.some((lit) => body.includes(lit));
+    if (hasLiteral)
+        return true;
+    // 允许较长文案的部分匹配（≥8 字取前 8 字）
+    return literals.some((lit) => lit.length >= 8 && body.includes(lit.slice(0, 8)));
+}
+/**
+ * 是否为仅模糊断言、未绑定 PRD 原文的 test 块。
+ */
+function testBlockIsFuzzyOnly(blockBody, literals) {
+    if (literals.length === 0)
+        return false;
+    const body = (0, testAssertionAnalysis_1.stripComments)(blockBody);
+    if (!FUZZY_ONLY_ASSERT_RE.test(body))
+        return false;
+    return !testBlockBindsCriterionLiterals(blockBody, literals);
+}
+/**
+ * P0 / e2e 类 AC 须在有效 test 块内绑定验收标准字面量；P0 禁止纯 manual。
+ */
+function checkAcAssertionBinding(items, testFiles) {
+    var _a, _b;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_AC_ASSERTION_BINDING === "1" ||
+        process.env.OPSX_SKIP_AC_ASSERTION_BINDING === "1";
+    if (skip) {
+        checks.push({
+            name: "ac-assertion-binding",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_AC_ASSERTION_BINDING=1",
+        });
+        return 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 isP0 = /^P0$/i.test(ac.priority.trim());
+        const testType = ((_a = ac.testType) !== null && _a !== void 0 ? _a : "").trim();
+        const criterion = (_b = ac.criterion) !== null && _b !== void 0 ? _b : "";
+        const literals = extractCriterionLiterals(criterion);
+        if (isP0 && /^manual$/i.test(testType)) {
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id} 为 P0 但测试类型为纯 manual，须补充 unit/e2e 自动化`,
+            });
+            continue;
+        }
+        const e2eRequired = /e2e/i.test(testType);
+        let bound = false;
+        let fuzzyOnly = false;
+        let e2eBound = false;
+        const hitFiles = [];
+        for (const tf of testFiles) {
+            const blocks = (0, testAssertionAnalysis_1.parseTestBlocks)(tf.content);
+            for (const block of blocks) {
+                if (!(0, testAssertionAnalysis_1.testBlockReferencesAc)(block, ac.id))
+                    continue;
+                if (!(0, testAssertionAnalysis_1.testBlockHasExpect)(block))
+                    continue;
+                const literalOk = testBlockBindsCriterionLiterals(block.body, literals);
+                const fuzzy = testBlockIsFuzzyOnly(block.body, literals);
+                if (literalOk && !fuzzy) {
+                    bound = true;
+                    hitFiles.push(path_1.default.basename(tf.rel));
+                    if (E2E_DIR_RE.test(tf.rel))
+                        e2eBound = true;
+                }
+                else if (fuzzy) {
+                    fuzzyOnly = true;
+                }
+                else if (literals.length === 0) {
+                    bound = true;
+                    hitFiles.push(path_1.default.basename(tf.rel));
+                    if (E2E_DIR_RE.test(tf.rel))
+                        e2eBound = true;
+                }
+            }
+        }
+        if (!bound) {
+            const hint = literals.length > 0
+                ? `须在含 [${ac.id}] 的 test 块 expect 中出现验收标准字面量之一: ${literals.slice(0, 3).join("、")}`
+                : `须在含 [${ac.id}] 的 test 块内有 expect`;
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id}(${ac.priority}) 未绑定验收断言${fuzzyOnly ? "（仅有模糊 toContain 成功/失败）" : ""}；${hint}`,
+            });
+            continue;
+        }
+        if (e2eRequired && !e2eBound) {
+            checks.push({
+                name: `ac-assertion-${ac.id}`,
+                ok: false,
+                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 下无绑定验收字面量的 test 块`,
+            });
+            continue;
+        }
+        checks.push({
+            name: `ac-assertion-${ac.id}`,
+            ok: true,
+            detail: `${ac.id} 已绑定验收字面量: ${[...new Set(hitFiles)].join(", ")}`,
+        });
+    }
+    if (mustCover.length === 0) {
+        checks.push({
+            name: "ac-assertion-binding",
+            ok: true,
+            detail: "无 P0/e2e AC，跳过断言绑定检查",
+        });
+    }
+    else {
+        const allOk = checks.every((c) => c.ok);
+        checks.unshift({
+            name: "ac-assertion-binding",
+            ok: allOk,
+            detail: allOk
+                ? `P0/e2e AC 断言绑定通过（${mustCover.length} 条）`
+                : `部分 AC 未绑定验收字面量`,
+        });
+    }
+    return checks;
+}

package/dist/core/apiFieldContract.js

@@ -36,7 +36,7 @@ async function checkApiFieldContract(pkgRoot, changeName) {
     const modRe = /config\/api\/modules\/([\w/-]+)/g;
     let m;
     while ((m = modRe.exec(blob)) !== null) {
-        moduleRefs.add(m[1].replace(/\/index$/, ""));
+        moduleRefs.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
     }
     if (moduleRefs.size === 0) {
         checks.push({

package/dist/core/apiFieldCoverage.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFieldMappingTable = parseFieldMappingTable;
+exports.checkApiFieldCoverage = checkApiFieldCoverage;
+/**
+ * API 字段级覆盖门禁（v1.3.20）：fixture 样例 + 04 字段映射表 + 源码消费点三角校验。
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const snakeCamel_1 = require("./snakeCamel");
+const FIELD_TABLE_HEADER_RE = /\|\s*后端字段\s*\|\s*前端字段\s*\|/m;
+const NORMALIZE_TEST_RE = /caseTransform|snakeToCamel|normalize\w*Api/i;
+const FIXTURE_LOAD_RE = /fixtures\/|readFileSync|import\s+\w+\s+from\s+['"].*\.json['"]/;
+/**
+ * 从 04 / design 解析 §4.3 响应字段映射表。
+ */
+function parseFieldMappingTable(content) {
+    var _a, _b, _c, _d;
+    const rows = [];
+    if (!FIELD_TABLE_HEADER_RE.test(content))
+        return rows;
+    const section = (_d = (_b = (_a = content.match(/###\s*4\.3[\s\S]*?(?=###\s*4\.4|##\s*5\.)/m)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : (_c = content.match(/##\s*API\s*字段契约[\s\S]*/im)) === null || _c === void 0 ? void 0 : _c[0]) !== null && _d !== void 0 ? _d : content;
+    const lines = section.split("\n");
+    let inTable = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("|") && FIELD_TABLE_HEADER_RE.test(trimmed)) {
+            inTable = true;
+            continue;
+        }
+        if (!inTable || !trimmed.startsWith("|"))
+            continue;
+        if (/^\|\s*[-:]+/.test(trimmed))
+            continue;
+        const cells = trimmed
+            .split("|")
+            .map((c) => c.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (cells.length < 2)
+            continue;
+        if (/后端字段|backend/i.test(cells[0]))
+            continue;
+        const backendField = cells[0].replace(/`/g, "").trim();
+        const frontendField = cells[1].replace(/`/g, "").trim();
+        if (!backendField || !frontendField)
+            continue;
+        rows.push({
+            backendField,
+            frontendField,
+            displayLocation: cells[2],
+        });
+    }
+    return rows;
+}
+async function collectApiModulesFromChange(pkgRoot, changeName) {
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    const mods = new Set();
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+        const c = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, f));
+        if (!c)
+            continue;
+        const re = /config\/api\/modules\/([\w/-]+)/g;
+        let m;
+        while ((m = re.exec(c)) !== null) {
+            mods.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
+        }
+    }
+    return mods;
+}
+async function listFixtureFiles(pkgRoot, moduleName) {
+    const dirs = [
+        path_1.default.join(pkgRoot, "tests/fixtures", moduleName),
+        path_1.default.join(pkgRoot, "frontend/tests/fixtures", moduleName),
+        path_1.default.join(pkgRoot, "tests/fixtures"),
+        path_1.default.join(pkgRoot, "frontend/tests/fixtures"),
+    ];
+    const files = [];
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            if (ent.isFile() && ent.name.endsWith(".json")) {
+                files.push(path_1.default.join(dir, ent.name));
+            }
+        }
+    }
+    return [...new Set(files)];
+}
+async function collectChangeSourceCorpus(pkgRoot, changeName) {
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    let blob = "";
+    const fileRefs = new Set();
+    for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+        const c = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, f));
+        if (c)
+            blob += `${c}\n`;
+    }
+    const patterns = [
+        /(?:src|frontend\/src)\/[\w/.-]+\.(vue|tsx?|ts)/g,
+        /views\/[\w/.-]+\.(vue|tsx?)/g,
+        /config\/api\/modules\/[\w/.-]+/g,
+    ];
+    for (const re of patterns) {
+        let m;
+        const r = new RegExp(re.source, "g");
+        while ((m = r.exec(blob)) !== null) {
+            fileRefs.add(m[0].replace(/^frontend\//, ""));
+        }
+    }
+    for (const ref of fileRefs) {
+        const candidates = [
+            path_1.default.join(pkgRoot, ref),
+            path_1.default.join(pkgRoot, "frontend", ref),
+            path_1.default.join(pkgRoot, "src", ref.replace(/^src\//, "")),
+        ];
+        for (const fp of candidates) {
+            const content = await (0, fs_1.readFileIfExists)(fp);
+            if (content) {
+                blob += `\n${content}`;
+                break;
+            }
+        }
+    }
+    const viewRoots = [
+        path_1.default.join(pkgRoot, "src/views"),
+        path_1.default.join(pkgRoot, "frontend/src/views"),
+    ];
+    // 兜底：合并 views 下源码
+    for (const vr of viewRoots) {
+        blob = await walkSourceDir(vr, blob);
+    }
+    return blob;
+}
+async function walkSourceDir(dir, acc) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return acc;
+    }
+    let out = acc;
+    for (const ent of entries) {
+        if (ent.name === "node_modules")
+            continue;
+        const full = path_1.default.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            out = await walkSourceDir(full, out);
+        }
+        else if (/\.(vue|tsx?|ts)$/.test(ent.name)) {
+            const c = await (0, fs_1.readFileIfExists)(full);
+            if (c)
+                out += `\n${c}`;
+        }
+    }
+    return out;
+}
+async function findNormalizeTests(pkgRoot, moduleName) {
+    const roots = [
+        path_1.default.join(pkgRoot, "tests"),
+        path_1.default.join(pkgRoot, "frontend/tests"),
+    ];
+    const hits = [];
+    for (const root of roots) {
+        await walkTests(root, moduleName, hits);
+    }
+    return hits;
+}
+async function walkTests(dir, moduleName, hits) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        const full = path_1.default.join(dir, ent.name);
+        if (ent.isDirectory()) {
+            await walkTests(full, moduleName, hits);
+        }
+        else if (/\.(spec|test)\.(t|j)sx?$/.test(ent.name)) {
+            const content = await (0, fs_1.readFileIfExists)(full);
+            if (!content)
+                continue;
+            if (!NORMALIZE_TEST_RE.test(content))
+                continue;
+            if (content.includes(moduleName) ||
+                content.includes("caseTransform") ||
+                content.includes("snakeToCamel")) {
+                hits.push(full);
+            }
+        }
+    }
+}
+function corpusContainsField(corpus, field) {
+    if (!field || field.length < 2)
+        return true;
+    const camel = field;
+    const snake = field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+    return (corpus.includes(camel) ||
+        corpus.includes(`'${camel}'`) ||
+        corpus.includes(`"${camel}"`) ||
+        corpus.includes(snake));
+}
+/**
+ * 字段级 API 覆盖：fixture（snake 样例）+ normalize 单测 + 04 映射表字段在源码可找到。
+ */
+async function checkApiFieldCoverage(pkgRoot, changeName, outputRoot) {
+    var _a;
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_API_FIELD_COVERAGE === "1" ||
+        process.env.OPSX_SKIP_API_FIELD_COVERAGE === "1";
+    if (skip) {
+        checks.push({
+            name: "api-field-coverage",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_API_FIELD_COVERAGE=1",
+        });
+        return checks;
+    }
+    const modules = await collectApiModulesFromChange(pkgRoot, changeName);
+    if (modules.size === 0) {
+        checks.push({
+            name: "api-field-coverage",
+            ok: true,
+            detail: "change 未引用 API 模块，跳过字段级覆盖",
+        });
+        return checks;
+    }
+    let fieldDoc = "";
+    if (outputRoot) {
+        const tech04 = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "04-技术文档草稿.md"));
+        if (tech04)
+            fieldDoc += tech04;
+    }
+    const design = await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, "openspec/changes", changeName, "design.md"));
+    if (design)
+        fieldDoc += `\n${design}`;
+    const mappingRows = parseFieldMappingTable(fieldDoc);
+    const corpus = await collectChangeSourceCorpus(pkgRoot, changeName);
+    const failures = [];
+    const passed = [];
+    for (const mod of modules) {
+        const fixtures = await listFixtureFiles(pkgRoot, mod);
+        const validFixtures = [];
+        for (const fp of fixtures) {
+            const raw = await (0, fs_1.readFileIfExists)(fp);
+            if (!raw)
+                continue;
+            try {
+                const payload = JSON.parse(raw);
+                if ((0, snakeCamel_1.hasSnakeCaseKeys)(payload)) {
+                    validFixtures.push({ path: fp, payload });
+                }
+            }
+            catch {
+                // ignore invalid json
+            }
+        }
+        if (validFixtures.length === 0) {
+            failures.push(`${mod}: 缺少 tests/fixtures/${mod}/*.json 后端样例（须含 snake_case 字段，来自联调抓包）`);
+            continue;
+        }
+        const normalizeTests = await findNormalizeTests(pkgRoot, mod);
+        let strongTest = false;
+        for (const tp of normalizeTests) {
+            const t = (_a = (await (0, fs_1.readFileIfExists)(tp))) !== null && _a !== void 0 ? _a : "";
+            if (/expect\s*\(/.test(t) &&
+                /snakeToCamel|normalize/.test(t) &&
+                (FIXTURE_LOAD_RE.test(t) || /subject_id|_[a-z]/.test(t))) {
+                strongTest = true;
+                break;
+            }
+        }
+        if (!strongTest) {
+            failures.push(`${mod}: 缺少 caseTransform/normalize 单测（须 expect 断言 camelCase 字段，建议加载 fixtures/${mod}/*.json）`);
+        }
+        const fixtureKeys = new Set();
+        for (const f of validFixtures) {
+            const row = (0, snakeCamel_1.extractFirstListRow)(f.payload);
+            const normalized = (0, snakeCamel_1.snakeToCamelDeep)(f.payload);
+            if (row) {
+                for (const k of Object.keys(row))
+                    fixtureKeys.add(k);
+            }
+            for (const k of (0, snakeCamel_1.collectLeafCamelKeys)(normalized))
+                fixtureKeys.add(k);
+        }
+        const keysToCheck = mappingRows.length > 0
+            ? mappingRows.map((r) => r.frontendField)
+            : [...fixtureKeys].filter((k) => k.length >= 3).slice(0, 12);
+        const missingInCorpus = keysToCheck.filter((k) => !corpusContainsField(corpus, k));
+        if (keysToCheck.length > 0 && missingInCorpus.length === keysToCheck.length) {
+            failures.push(`${mod}: normalize 后字段 [${keysToCheck.slice(0, 5).join(", ")}] 在 change 源码中均无消费点`);
+        }
+        else if (missingInCorpus.length > 0 && mappingRows.length > 0) {
+            failures.push(`${mod}: 04 映射表前端字段未在源码出现: ${missingInCorpus.slice(0, 6).join(", ")}`);
+        }
+        else {
+            passed.push(`${mod}(fixtures=${validFixtures.length}, fields=${keysToCheck.length - missingInCorpus.length}/${keysToCheck.length})`);
+        }
+    }
+    if (mappingRows.length === 0 && modules.size > 0) {
+        checks.push({
+            name: "api-field-mapping-doc",
+            ok: false,
+            detail: "04/design 缺少 §4.3 字段映射表（| 后端字段 | 前端字段 |）；请在 04-技术文档草稿.md 补充",
+        });
+    }
+    else {
+        checks.push({
+            name: "api-field-mapping-doc",
+            ok: true,
+            detail: `已登记 ${mappingRows.length} 条字段映射`,
+        });
+    }
+    checks.push({
+        name: "api-field-coverage",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `API 字段级覆盖通过: ${passed.join("; ") || "(无模块)"}`
+            : failures.join(" | "),
+    });
+    return checks;
+}