jiapu/docs/superpowers/plans/2026-07-10-tac-layer-real-mount-fix.md

TAC Layui 实际挂载点修复实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

目标： 修复 Layui 遮罩已显示、验证码接口已返回 200，但 TAC 验证窗口仍不显示的问题。

架构： CaptchaPages.createCaptchaLayer 使用 Layui layer.open 的字符串 content 创建弹层内部真实挂载节点；弹层创建完成后再从 document 查询该实际节点，并把它交给 CaptchaConfig.bindEl。这样 Layui 负责弹层，TAC 挂到已经进入页面的真实 DOM。

技术栈： Layui 2.11.5、TAC 原生 CSS/JS、原生 JavaScript、Node assert 测试。

全局约束

• 计划创建时间：2026-07-10 10:59:52 +08:00。
• 不修改 public/tac/css/tac.css、public/tac/js/tac.min.js 或 Layui 第三方文件。
• 不新增验证码自定义 CSS，不注入样式，不传 TAC 视觉配置。
• 保留 auth-pages.js -> CaptchaPages.ensureToken -> TAC 调用链，只修正弹层挂载点。

---

任务 1：复现“遮罩有但实际挂载点不可见”

文件：

• 修改：tests/captcha-pages.test.js

• 步骤 1：写失败测试

断言 layer.open 的 content 是包含唯一 data-captcha-layer-box 的字符串；createCaptchaLayer 必须在弹层打开后从 document.querySelector 取到实际挂载节点并返回。

• 步骤 2：运行失败测试

运行：node tests\captcha-pages.test.js

预期：失败，当前实现仍返回打开前创建的原生 DOM。

任务 2：修正实际挂载点

文件：

• 修改：public/js/captcha-pages.js

• 步骤 1：最小实现

增加内部自增 ID，用字符串内容创建 <div data-captcha-layer-box="..."></div>；layer.open 后查询该节点并作为 box 返回。

• 步骤 2：运行聚焦测试

运行：node tests\captcha-pages.test.js; node --check public\js\captcha-pages.js

预期：全部通过。

任务 3：记录和回归

文件：

• 修改：docs/pc-api-page-integration-tracker-2026-07-09.md

• 修改：docs/superpowers/plans/2026-07-10-tac-layer-real-mount-fix.md

• 步骤 1：补充 PC-019 记录

记录用户浏览器复现现象、根因、修正方式、验证命令。

• 步骤 2：最终验证

运行：node tests\auth-page-structure.test.js; node tests\captcha-pages.test.js; node --check public\js\captcha-pages.js; git diff --check

预期：全部通过；git diff --check 仅允许 Git 行尾提示，不允许空白错误。

完成记录

• 完成时间：2026-07-10 11:04:18 +08:00。
• 根因：PC-018 只让 layer.open 不再因 .parents() 报错，但仍把打开前创建的临时 DOM 返回给 TAC；真实浏览器里 Layui 遮罩已出现，/captcha/challenge 也返回 200，但 TAC 没有挂到可见弹层内容区。
• 修复：layer.open 使用字符串 content 创建弹层内部真实节点，随后通过 document.querySelector('[data-captcha-layer-box="..."]') 获取实际挂载点并交给 CaptchaConfig.bindEl。
• 约束：未修改 public/tac，未新增验证码 CSS，未传 TAC 视觉配置。
• 验证：失败测试已先复现；修复后 node tests\captcha-pages.test.js 和 node --check public\js\captcha-pages.js 通过。最终回归记录见 docs/pc-api-page-integration-tracker-2026-07-09.md 的 PC-019。