jiapu/docs/superpowers/plans/2026-07-09-tac-captcha-auth.md

TAC Captcha Auth Implementation Plan

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

Goal: 将 public/tac 滑动验证接入登录、注册、忘记密码三个认证页面，并按 genealogy-pc-openapi.yaml 的验证中心接口换取 validToken 后再提交业务接口。

Architecture: 新增 public/js/captcha-pages.js 作为 TAC 与验证中心接口之间的适配层；auth-pages.js 在提交登录、注册、发送短信、重置密码前调用验证码适配层。API 基础地址、clientId、tenantId 继续由 api-client.js 统一提供。

Tech Stack: 静态 HTML、原生 JS、现有 public/tac/js/tac.min.js、现有 public/tac/css/tac.css、Node 单元测试。

Global Constraints

• 严格依据 genealogy-pc-openapi.yaml 的 /captcha/require、/captcha/challenge、/captcha/verify 字段接入。
• 业务 JS 不压缩，新增注释使用中文。
• 自有样式写入 CSS 文件，不通过自有 JS 注入样式。
• 第三方 tac.min.js 保持原样，不重写其内部样式和 DOM 生成逻辑。
• 登录、注册、忘记密码三页都必须有隐藏 validToken 字段和验证码挂载容器。

---

Task 1: API Client Captcha Helpers

Files:

• Modify: public/js/api-client.js
• Modify: tests/api-client.test.js

Interfaces:

• Produces: client.buildApiUrl(path, query)

• Produces: client.captchaRequirement({ sceneCode, subject })

• Step 1: Write failing tests for captcha requirement URL, query, and public URL building.

• Step 2: Run tests and confirm missing methods fail.

• Step 3: Implement minimal API client helpers.

• Step 4: Run tests and confirm pass.

Task 2: TAC Adapter Module

Files:

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

Interfaces:

• Produces: CaptchaPages.buildChallengeBody(options, api)

• Produces: CaptchaPages.adaptChallengeResponse(response)

• Produces: CaptchaPages.buildVerifyBody(requestData, context, api)

• Produces: CaptchaPages.extractValidToken(response)

• Produces: CaptchaPages.ensureToken(form, options)

• Step 1: Write failing tests for OpenAPI-to-TAC mapping and validToken extraction.

• Step 2: Run tests and confirm module missing fails.

• Step 3: Implement adapter with Chinese comments.

• Step 4: Run tests and confirm pass.

Task 3: Auth Flow Integration

Files:

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

Interfaces:

• Consumes: CaptchaPages.ensureToken(form, { sceneCode, subject })

• Updates: login/register/password reset/send code flows wait for captcha before API submission.

• Step 1: Write failing tests for login body validToken and scene code mapping.

• Step 2: Run tests and confirm expected failure.

• Step 3: Integrate captcha gate before submit/send code.

• Step 4: Run tests and confirm pass.

Task 4: HTML/CSS Wiring

Files:

• Modify: login.html
• Modify: register.html
• Modify: forgot-password.html
• Modify: public/css/public.css

Interfaces:

• Adds: <link rel="stylesheet" href="public/tac/css/tac.css" />

• Adds: hidden validToken

• Adds: data-captcha-box

• Adds: public/tac/js/tac.min.js and public/js/captcha-pages.js

• Step 1: Add page hooks with Chinese HTML comments where helpful.

• Step 2: Add CSS-only layout for captcha container.

• Step 3: Run static checks for scripts, hooks, no self JS style injection.

Task 5: Verification And Records

Files:

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

• Step 1: Run all Node tests.

• Step 2: Run node --check for all business JS.

• Step 3: Run static checks for HTML hooks and style-injection patterns.

• Step 4: Append dated progress record.