jiapu/docs/superpowers/plans/2026-07-10-tac-modal-cleanup.md

TAC 验证弹窗遮罩清理 Implementation Plan

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

Goal: 在 TAC 验证被取消、初始化异常或接口失败时，主动关闭认证页遮罩并清空残留的验证码 DOM。

Architecture: public/js/captcha-pages.js 作为验证码弹窗生命周期的唯一拥有者，新增打开和关闭挂载容器的函数。由于原 public.css 不是 UTF-8，无法使用补丁安全编辑，public/css/captcha-modal.css 作为新增公共样式文件只根据 is-active 类决定遮罩显示；三张认证页继续复用同一个页面级挂载点。

Tech Stack: 原生 JavaScript、Node assert 测试、layui 提示、TAC public/tac/js/tac.min.js。

Global Constraints

• 计划创建时间：2026-07-10 09:10:03 +08:00。
• 仅修改 TAC 遮罩生命周期，不修改 public/tac/js/tac.min.js，不改变后端验证码类型选择。
• 新增或修改的 JS、CSS 注释使用中文；样式只写入 CSS 文件。
• 失败提示继续使用 MessageUtil/layui，禁止回退到浏览器原生 alert。
• 503/CORS 是服务端或跨域环境可用性问题；本任务只保证前端失败后不遗留遮罩。

---

Task 1: 用例锁定与生命周期工具

Files:

• Modify: tests/captcha-pages.test.js
• Modify: public/js/captcha-pages.js

Interfaces:

• Produces: openCaptchaBox(box)，清空旧内容、激活容器、设置 aria-hidden="false"。

• Produces: closeCaptchaBox(box)，清空内容、取消激活、设置 aria-hidden="true"。

• Step 1: 写失败测试

CaptchaPages.openCaptchaBox(box);
assert.strictEqual(box.classList.contains('is-active'), true);
assert.strictEqual(box.attributes['aria-hidden'], 'false');

CaptchaPages.closeCaptchaBox(box);
assert.strictEqual(box.classList.contains('is-active'), false);
assert.strictEqual(box.attributes['aria-hidden'], 'true');
assert.strictEqual(box.innerHTML, '');

• Step 2: 运行失败测试

Run: node tests\\captcha-pages.test.js Expected: FAIL，提示 openCaptchaBox is not a function。

• Step 3: 实现最小生命周期函数

function openCaptchaBox(box) {
  if (!box) return;
  box.innerHTML = '';
  box.classList.add('is-active');
  box.setAttribute('aria-hidden', 'false');
}

function closeCaptchaBox(box) {
  if (!box) return;
  box.innerHTML = '';
  box.classList.remove('is-active');
  box.setAttribute('aria-hidden', 'true');
}

• Step 4: 将关闭函数接入 TAC 成功、取消、初始化异常和 Promise 捕获路径

if (captchaInstance && captchaInstance.destroyWindow) captchaInstance.destroyWindow();
closeCaptchaBox(box);

• Step 5: 运行单元测试与语法检查

Run: node tests\\captcha-pages.test.js; node --check public\\js\\captcha-pages.js Expected: 两条命令均通过。

Task 2: CSS 显示状态收口

Files:

• Create: public/css/captcha-modal.css
• Modify: login.html
• Modify: register.html
• Modify: forgot-password.html
• Test: tests/auth-page-structure.test.js

Interfaces:

• Consumes: .auth-captcha-modal.is-active。

• Produces: 默认隐藏、激活后显示的页面级遮罩。

• Step 1: 写失败结构测试

assert.ok(publicCss.includes('.auth-captcha-modal.is-active'));
assert.ok(publicCss.includes('display: none;'));

• Step 2: 运行失败测试

Run: node tests\\auth-page-structure.test.js Expected: FAIL，缺少 .auth-captcha-modal.is-active 规则。

• Step 3: 实现 CSS 状态规则

.auth-captcha-modal {
  display: none;
}

.auth-captcha-modal.is-active {
  display: grid;
}

• Step 4: 运行结构测试

Run: node tests\\auth-page-structure.test.js Expected: PASS。

Task 3: 全量验证与记录

Files:

• Modify: docs/pc-api-page-integration-tracker-2026-07-09.md

• Modify: docs/superpowers/plans/2026-07-10-tac-modal-cleanup.md

• Step 1: 运行验证码相关和全量 Node 测试

Run: Get-ChildItem -Path tests -Filter *.test.js | Sort-Object Name | ForEach-Object { node $_.FullName } Expected: 所有测试通过。

• Step 2: 记录完成时间、修改文件和验证结果

- [x] 完成时间：YYYY-MM-DD HH:mm:ss +08:00
- [x] 验证：相关测试、语法检查、全量 Node 测试均通过。

自检

• 需求覆盖：取消后遮罩清理、失败后遮罩清理、成功后遮罩清理、CSS 显示状态和回归测试均有对应任务。
• 占位扫描：无 TODO、TBD 或未定义接口。
• 接口一致性：JS 导出名、测试调用名和 CSS 类名统一为 openCaptchaBox、closeCaptchaBox、is-active。

完成记录

• 完成时间：2026-07-10 09:15:55 +08:00。
• 修改文件：public/js/captcha-pages.js、public/css/captcha-modal.css、login.html、register.html、forgot-password.html、tests/captcha-pages.test.js、tests/auth-page-structure.test.js。
• 验证：node tests\\captcha-pages.test.js、node tests\\auth-page-structure.test.js、node --check public\\js\\captcha-pages.js 和全量 tests/*.test.js 均通过。
• 已知边界：测试域名的 503、CORS 或 TLS 可用性问题仍需后端或网关处理；该前端修复保证取消或异常后不残留页面遮罩。