家谱现有接口调试50%

2026-07-09 17:29:25 +08:00
commit 6050508144
262 changed files with 63354 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 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` 滑动验证接入登录、注册、忘记密码三个认证页面，并按 `APP.openapi.json` 的验证中心接口换取 `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
+
+- 严格依据 `APP.openapi.json` 的 `/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**.