rain/jiapu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db397a7917d0e8ca1b45ceb6d8c36c13a021c89f
jiapu/docs/pc-api-page-integration-tracker-2026-07-09.md
T
rain db397a7917 修改问题
2026-07-11 11:03:47 +08:00

42 KiB
Raw Blame History

PC 接口对接重新规划与状态追踪

创建时间：2026-07-09 15:14:58 +08:00
接口依据：genealogy-pc-openapi.yaml
接口基础地址：http://182.61.18.23:8080 接口依据：genealogy-pc-openapi.yaml

当前地址契约

  • 运行时唯一来源：根目录 config.js。
  • 当前开发和生产地址：http://182.61.18.23:8080。
  • 地址变更记录：2026-07-11 已由历史测试域名切换为当前 IP 和端口；文档中出现的 test-genealogy-api.ddxcjp.cn 仅用于描述历史事件，不代表当前运行时配置。

执行规则

  1. 所有 PC 接口对接必须先进入本追踪表，再改代码。
  2. 每一项开始前先标记“进行中”，记录年月日时分秒和时区。
  3. 每一项完成后记录完成时间、修改文件、接口路径、验证命令和结果。
  4. 只有完成验证后才能标记“已完成”。
  5. genealogy-pc-openapi.yaml 没有明确接口的页面，标记“暂缓”或“待确认”，不继续套用旧路径。
  6. 样式继续写入 CSS 文件，业务 JS 不注入样式。
  7. 新增或修改的 HTML、JS、CSS 注释使用中文，代码保持可读、不压缩。

PC 文档当前接口范围

  • 验证中心：/captcha/require、/captcha/challenge、/captcha/verify、/auth/code
  • PC 认证：/genealogy/pc/auth/register、/genealogy/pc/auth/login、/genealogy/pc/auth/login/sms、/genealogy/pc/auth/sms/code、/genealogy/pc/auth/profile、/genealogy/pc/auth/password、/genealogy/pc/auth/password/reset、/genealogy/pc/auth/phone、/genealogy/pc/auth/account/deactivate、/genealogy/pc/auth/logout
  • PC 文件：/genealogy/pc/files/upload、/genealogy/pc/files/resumable/init、/genealogy/pc/files/resumable/chunk、/genealogy/pc/files/resumable/complete、/genealogy/pc/files/reference
  • 行政区划：/genealogy/region/children、/genealogy/region/path/{regionCode}、/genealogy/region/search、/genealogy/region/{regionCode}

最新 PC YAML 分析记录

分析时间：2026-07-09 15:36:16 +08:00
分析文件：genealogy-pc-openapi.yaml

  1. paths 中实际存在 25 个接口操作，分为验证码、PC 认证、PC 文件、行政区划四类。
  2. servers 仍是本地地址示例；当前运行时基础地址以 config.js 为准，为 http://182.61.18.23:8080。
  3. 登录后接口使用 Authorization 作为 token header，同时所有 PC 认证和文件接口都要求 header clientid；用户最新提供的 PC clientid 为 ced7e5f0498645c6ec642dcf450b036f，客户端 Key 为 web_pc。
  4. components.tags 和 components.schemas/requestBodies 中出现家谱、动态、世系、字辈等业务模型，但 paths 没有对应接口路径；实现时不能把这些 schema 当成可调用 PC 接口。
  5. 验证码场景以后台配置为准，当前明确可用的 PC/H5 场景为 WEB_H5_LOGIN、WEB_H5_REGISTER、WEB_H5_FORGOT_PASSWORD。
  6. ProfileUpdate 示例出现 regionCode/addressDetail，但 schema 实际字段是 provinceCode/cityCode/districtCode，页面资料提交时应以 schema 字段为准。
  7. SmsLoginBody 未声明 validToken 字段，但短信发送 SmsCodeBody 必填 validToken；短信登录流程应先通过验证码拿票据，再发短信验证码，最后用短信码登录。
  8. 文件引用 FileReferenceBody 必填 bizType/bizTable/bizId/bizField，ossId/ossIds/usageScene/usageName 可选；但文章、动态、相册等业务主体接口未提供，文件引用只能作为公共上传能力，不代表主业务已可提交。

验证码与 TAC 调用记录

  • 后台验证码配置截图中，PC/H5 当前明确可用场景是 WEB_H5_LOGIN、WEB_H5_REGISTER、WEB_H5_FORGOT_PASSWORD，客户端 Key 为 web_pc，验证服务为“天爱行为验证码”，验证码类型为“滑块验证码”。
  • ADMIN_LOGIN 是后台管理登录，类型为旋转验证码，不归当前 PC/H5 页面使用。
  • PC/H5 登录页调用链：
    1. 页面加载 public/tac/css/tac.css、public/tac/js/tac.min.js、public/js/captcha-pages.js。
    2. 表单提供 input[name="validToken"] 隐藏字段和 [data-captcha-box] 容器。
    3. auth-pages.js 在登录提交前调用 CaptchaPages.ensureToken(form, { sceneCode: 'WEB_H5_LOGIN', subject: 手机号 })。
    4. captcha-pages.js 先请求 GET /captcha/require?tenantId=000000&clientId=ced7e5f0498645c6ec642dcf450b036f&sceneCode=WEB_H5_LOGIN&subject=手机号。
    5. 如果返回 required=false，业务表单可继续提交；如果需要验证，则创建 new CaptchaConfig(...) 和 new TAC(config, ...)。
    6. TAC 内部请求 POST /captcha/challenge 获取 captchaType/challengeId/payload，适配为 TAC 需要的 data.type/data.id/backgroundImage/templateImage。
    7. 用户拖动完成后，TAC 请求 POST /captcha/verify，提交 challengeId/providerCode/captchaType/payload.track，其中 left/top 由轨迹首尾点计算。
    8. 验证成功后从返回 data.validToken 取票据，写回表单隐藏字段 validToken，再提交 PC 登录接口。
  • PC/H5 注册使用 WEB_H5_REGISTER，找回密码和找回密码短信验证码使用 WEB_H5_FORGOT_PASSWORD；换绑手机、注销账号暂未看到明确 PC/H5 场景编码，仍待后端补充后再接。

编号计划

编号 状态 页面范围 接口范围 计划与验证
PC-000 复核通过 全项目 genealogy-pc-openapi.yaml 历史记录保留；当前 PC YAML paths 再次核对通过，真实接口范围仍只有验证码、PC 认证、PC 文件和地区。
PC-001 复核通过 根目录 config.js 开发/生产环境、API 基础地址 当前 config.js 已收敛为环境和基础地址唯一入口；node tests\config.test.js、node --check config.js 通过。
PC-002 复核通过 utils 公共工具层 Axios、请求封装、PC 接口客户端 当前公共层为 utils/axios.js、utils/AxiosRequestUtil.js、utils/ApiClient.js；旧 fetch 工具和旧 public API 客户端已删除。
PC-003 本地复核通过 认证、资料、安全页面 /genealogy/pc/auth/*、/captcha/* 认证、资料、安全测试和脚本顺序检查均通过；真实登录业务仍依赖后端账户数据。
PC-004 本地复核通过 文件上传页面 /genealogy/pc/files/* node tests\upload-pages.test.js、node tests\api-client.test.js 通过；文件上传仍需真实文件和后端授权进行端到端验证。
PC-005 本地复核通过 地区选择页面 /genealogy/region/* node tests\region-pages.test.js、node tests\profile-pages.test.js 通过。
PC-006 复核通过 页面覆盖矩阵 PC YAML 覆盖边界 保持“公共能力不等于整页业务已对接”的边界，未覆盖业务继续受控失败。
PC-007 复核通过 实施规划 genealogy-pc-openapi.yaml 当前计划与 YAML paths 一致，不使用旧路径 fallback。
PC-008 复核通过 PC YAML 未覆盖业务页面 PC_API_NOT_AVAILABLE utils/ApiClient.js 统一抛 PC_API_NOT_AVAILABLE，过期请求路径扫描无结果。
PC-009 本地复核通过 登录、注册、找回密码 PC auth、/captcha/* 三页场景编码、表单契约、Axios 请求客户端和相关测试均通过；真实账号流程待业务数据联调。
PC-010 已复核（当前地址已同步） config.js、tests/config.test.js、utils/ApiClient.js API 基础地址 当前开发和生产地址均为 http://182.61.18.23:8080；地址唯一运行时来源为 config.js，tests/config.test.js 已同步断言。
PC-011 本地复核通过 三张认证页 TAC 弹窗 public/tac、/captcha/* 页面级挂载、移动端约束和结构测试通过；未修改 tac.min.js。

PC 页面覆盖矩阵草案

分类 页面/模块 当前判断 处理方式
完整可闭环 login.html PC YAML 有 /genealogy/pc/auth/login，后台验证码配置明确 WEB_H5_LOGIN，TAC 可完整串联。 可作为第一批执行页面。
接口存在但部分验证码场景待确认 register.html、forgot-password.html、profile-security.html 中的换绑/注销相关动作 PC YAML 有对应认证接口；注册场景为 WEB_H5_REGISTER，找回密码场景为 WEB_H5_FORGOT_PASSWORD，换绑和注销暂未提供 PC/H5 场景。 注册和找回密码可接 TAC；换绑、注销涉及验证码的提交先记录待确认，不套用未经确认的场景。
资料接口可对接 profile.html、profile-data.html 中用户资料读取/修改 PC YAML 有 /genealogy/pc/auth/profile。 只处理用户资料读写；页面里其他非资料业务不因此视为完成。
公共地区能力可保留 create-genealogy.html、profile-create-family.html、profile-data.html 中地区选择控件 PC YAML 有 /genealogy/region/*。 只保留和验证地区选择；创建家谱等主业务接口 PC YAML 未覆盖，仍待确认。
文件能力可切换 文章、动态、相册、成长、备忘、祭祀等页面里的上传控件 PC YAML 有 /genealogy/pc/files/*。 只把上传、分片、文件引用切到 PC 文件接口；文章/动态/相册等主业务接口仍待确认。
PC YAML 未覆盖 家谱主体、成员、字辈、世系、动态、文章、相册、祭祀、族务、VIP、通知、反馈、帮助、推广、姓氏、搜索等主业务页面 当前 PC YAML 没有这些业务路径。 等待补充 PC 接口后再逐页规划。

流程记录

  • 2026-07-09 15:14:58 +08:00：收到用户纠正，停止旧接口继续推进；读取 genealogy-pc-openapi.yaml，确认 PC 路径前缀为 /genealogy/pc，基础地址改用 https://test-genealogy-api.ddxcjp.cn。
  • 2026-07-09 15:14:58 +08:00：创建本 PC 专用追踪表，PC-001 标记为“进行中”。
  • 2026-07-09 15:17:57 +08:00：收到用户补充要求，重新规划 config.js 环境切换和 utils 公共 JS 分层；停止直接执行旧 PC-001，把 PC-001 到 PC-006 重排为待执行计划。
  • 2026-07-09 15:24:02 +08:00：收到用户补充验证码要求；记录 public/tac 调用链，确认 PC/H5 登录使用 WEB_H5_LOGIN，其他未配置 PC/H5 场景的认证验证码先待确认。
  • 2026-07-09 15:31:14 +08:00：根据用户质疑修正 PC-006；不再把“公共地区/文件接口可用”写成“整页可对接”，改为页面覆盖矩阵和缺口清单。
  • 2026-07-09 15:34:26 +08:00：同步修正详细规划文件 docs/superpowers/plans/2026-07-09-pc-api-replan.md 的 Task 6，并将 PC-006 标记为“已修正”。
  • 2026-07-09 15:41:40 +08:00：按最新 YAML 分析结果重写 docs/superpowers/plans/2026-07-09-pc-api-replan.md，新增 PC-007；明确旧路径不能作为 PC fallback，缺失业务接口统一降级为接口待确认。
  • 2026-07-09 15:44:18 +08:00：开始执行 PC-001/PC-002，先按 TDD 创建 config.js 和 utils 公共工具测试，再实现最小配置与工具层。
  • 2026-07-09 15:47:17 +08:00：完成 PC-001 和 PC-002 的公共工具层部分；config.js 位于根目录，utils 只放跨页面公共 JS，页面业务仍留在 public/js。
  • 2026-07-09 15:51:34 +08:00：完成 PC-002 的请求客户端切换；旧路径不再作为网络请求路径，未覆盖业务统一抛 PC_API_NOT_AVAILABLE。
  • 2026-07-09 15:55:28 +08:00：PC-003 认证页验证码阶段完成；登录使用 WEB_H5_LOGIN，未确认 PC/H5 场景的注册和找回密码不调用验证中心。
  • 2026-07-09 15:57:36 +08:00：收到用户补充截图，确认 PC clientid 为 ced7e5f0498645c6ec642dcf450b036f、客户端 Key 为 web_pc，新增注册场景 WEB_H5_REGISTER 和找回密码场景 WEB_H5_FORGOT_PASSWORD；同步修正配置、计划和认证页场景映射。
  • 2026-07-09 16:00:22 +08:00：PC-003 完成；认证页、资料页、安全页的 PC auth/captcha 接入和脚本顺序已验证。
  • 2026-07-09 16:03:23 +08:00：PC-004 完成；上传公共能力切换到 PC 文件接口，相关上传页已补齐公共层脚本顺序。
  • 2026-07-09 16:05:12 +08:00：PC-005 完成；地区选择只保留公共行政区划能力，创建家谱等主业务仍按 PC YAML 未覆盖处理。
  • 2026-07-09 16:06:35 +08:00：PC-008 完成；PC YAML 未覆盖业务不会继续发送过期请求，全量 Node 测试通过。
  • 2026-07-09 16:07:42 +08:00：收尾验证完成；全量 tests/*.test.js 通过，public/js 非压缩业务脚本 node --check 通过，过期请求路径、旧验证码场景、旧 PC clientId 扫描无输出；git diff --check 因当前目录不是 Git 仓库无法执行。
  • 2026-07-09 16:09:55 +08:00：开始登录、注册、找回密码三页专项核对；按 PC YAML 的 PasswordLoginBody、PasswordRegisterBody、SmsCodeBody、PasswordResetBody 修正页面字段、输入类型、验证码场景声明和文案。
  • 2026-07-09 16:12:10 +08:00：登录、注册、找回密码三页专项完成；三页表单已显式声明 data-captcha-scene，手机号输入改为 type="tel"、inputmode="numeric"、maxlength="11"，找回密码文案改为只支持注册手机号；auth-pages.js 优先读取页面 data-captcha-scene。验证：node tests\auth-pages.test.js、node tests\captcha-pages.test.js、node tests\api-client.test.js 通过；三页字段/脚本顺序扫描通过；旧邮箱文案和旧验证码场景扫描无输出。
  • 2026-07-09 16:19:11 +08:00：根据用户反馈“接口文档少了很多东西”重新核对 genealogy-pc-openapi.yaml 的真实 paths；确认当前 YAML 只有验证中心、认证登录、文件上传、行政区划四类共 25 个操作，虽然声明了家谱、成员、字辈、世系、家族圈、文章、相册、祭祀、族务、VIP、消息、反馈等标签和模型，但没有对应可调用路径。结论：这些业务页面不能继续视为已对接，只能保留 PC_API_NOT_AVAILABLE，等待后端补充 PC 接口文档。
  • 2026-07-09 16:48:05 +08:00：处理注册页滑动验证请求失败。确认失败不是注册字段问题，而是测试域名 HTTPS 握手失败；开发环境接口基础地址修正为 HTTP，并兼容清理旧 HTTPS 本地覆盖值。
  • 2026-07-09 16:56:22 +08:00：处理 TAC 验证码显示位置问题。确认不是后端验证码类型问题，也不是 tac.min.js 被改；问题来自前端挂载点在表单中，导致 TAC 相对定位弹窗被卡片布局吞进去。
  • 2026-07-09 17:02:35 +08:00：TAC 弹窗挂载修复完成。三张认证页改为页面级固定遮罩容器承载 TAC，表单内部不再放验证码挂载点；新增结构测试防止回退。
  • 2026-07-09 17:04:21 +08:00：复现用户反馈的 503 Service Unavailable。curl.exe 请求 /captcha/require 和域名根路径 / 均返回 Server: SakuraFrp、503 Service Unavailable，响应页提示检查 SakuraFrp 隧道节点、隧道配置、frpc 是否运行、隧道是否在线。结论：这是测试接口域名/内网穿透服务当前不可用，不是前端字段、TAC 样式或请求参数导致。

PC-012 认证页 layui 提示与 TAC 弹窗样式修正

  • 状态：本地复核通过
  • 计划开始时间：2026-07-09 17:14:08 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-09-auth-layer-message.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：不新增接口，只修正 /captcha/* 流程中的前端提示方式和弹窗展示方式。
  • 完成时间：2026-07-09 17:20:24 +08:00
  • 修改文件：login.html、register.html、forgot-password.html、utils/MessageUtil.js、public/js/auth-pages.js、public/js/captcha-pages.js、public/css/public.css、tests/auth-page-structure.test.js、tests/auth-message.test.js、docs/superpowers/plans/2026-07-09-auth-layer-message.md
  • 验证结果：
    • node tests\auth-page-structure.test.js 通过。
    • node tests\auth-message.test.js 通过。
    • node tests\auth-pages.test.js 通过。
    • node tests\captcha-pages.test.js 通过。
    • node --check public\js\auth-pages.js 通过。
    • node --check public\js\captcha-pages.js 通过。
    • node --check utils\MessageUtil.js 通过。
    • Get-ChildItem -Path tests -Filter *.test.js | Sort-Object Name | ForEach-Object { node $_.FullName } 全部通过。
  • 剩余风险：测试域名当前仍可能返回 SakuraFrp 503 Service Unavailable，这是后端/隧道可用性问题，不是本次提示和样式改动导致。
  • 执行计划：
    1. 已完成失败测试：tests/auth-page-structure.test.js、tests/auth-message.test.js。
    2. 已完成：三页加载 layui 样式和脚本。
    3. 已完成：auth-pages.js、captcha-pages.js 提示统一走 MessageUtil/layui.layer.msg，不再使用浏览器原生 alert。
    4. 已完成：public/css/public.css 增加认证页 layer 提示皮肤。
    5. 已完成：焦点测试、相关测试、语法检查和全量 Node 测试通过。

PC-013 TAC 取消或请求失败后的遮罩清理

  • 状态：本地复核通过
  • 计划开始时间：2026-07-10 09:10:03 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-modal-cleanup.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：/captcha/require、/captcha/challenge、/captcha/verify
  • 根因记录：现有 .auth-captcha-modal 仅依赖 :empty 判断隐藏；TAC 在取消、CORS 失败或 503 失败后仍可能保留子节点，导致外层遮罩层不再为空从而不会消失。
  • 处理计划：由 captcha-pages.js 显式管理 is-active 状态、aria-hidden 和残留 DOM；成功、取消、初始化异常、Promise 失败路径全部调用统一清理函数。
  • 完成时间：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、docs/superpowers/plans/2026-07-10-tac-modal-cleanup.md。
  • 完成结果：openCaptchaBox 在每次初始化前清理旧 TAC DOM 并显示遮罩；closeCaptchaBox 在成功、取消、初始化异常、Promise 失败后清空 DOM、隐藏遮罩并更新 aria-hidden；三张认证页加载新的公共验证码弹窗 CSS。
  • 验证结果：node tests\\captcha-pages.test.js、node tests\\auth-page-structure.test.js、node --check public\\js\\captcha-pages.js 和 Get-ChildItem -Path tests -Filter *.test.js | Sort-Object Name | ForEach-Object { node $_.FullName } 均通过。
  • 剩余风险：/captcha/* 的 503、CORS 或 TLS 错误属于测试网关/服务端可用性问题；本项只保证它们触发取消或异常后，前端不会继续遗留遮罩。

PC-014 已完成记录全量复核

  • 状态：已完成
  • 开始时间：2026-07-10 09:20:38 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-pc-tracker-reverification.md
  • 复核范围：PC-000 至 PC-013 中所有标记为“已完成”或“已修正”的项目。
  • 复核规则：以当前 genealogy-pc-openapi.yaml 的 paths、当前代码、当前 Node 测试、语法检查和静态扫描为准；历史记录只作为待核对内容，不作为证明。
  • 状态规则：当前证据完整才保留“已完成”；代码或记录不一致改为“待修正”；仅受测试网关影响的项目标记“外部环境待验证”。
  • 暂停时间：2026-07-10 09:27:30 +08:00
  • 暂停原因：用户要求删除现有 fetch 请求层并整体切换为 Axios；重构前取得的复核结果不能作为重构后的最终证据。
  • 完成时间：2026-07-10 10:03:18 +08:00
  • 当前结论：上方 PC-000 至 PC-011 及下方 PC-012、PC-013 的复核状态为本次有效状态，历史文件名、历史命令和历史时间仅用于追溯。
  • 验证证据：当前 YAML 路径扫描、Axios 公共层测试、认证/验证码/资料/安全/上传/地区测试、45 页脚本顺序测试、全量 Node 测试、语法检查均通过；受限环境外 curl.exe -I http://test-genealogy-api.ddxcjp.cn/captcha/require 返回 HTTP 200 OK。

PC-015 Axios 公共请求层重构

  • 状态：已完成
  • 开始时间：2026-07-10 09:27:30 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-axios-request-layer-refactor.md
  • 目录边界：utils/axios.js 存第三方 Axios 非压缩浏览器构建；utils/AxiosRequestUtil.js 存公共请求封装；utils/ApiClient.js 存跨页面 PC 接口客户端；public/js 只存页面业务脚本。
  • 清理目标：删除 utils/RequestUtil.js 与 public/js/api-client.js，并清除 fetch、fetchImpl、root.fetch 和旧页面脚本引用；不提供兼容分支。
  • 范围修正：2026-07-10 09:27:30 +08:00 初始清单只按旧 RequestUtil 引用列出 14 页；本轮静态扫描发现总共有 45 页加载接口客户端，已修正为自动扫描全部相关 HTML 页面，剩余 31 页必须迁移后才能完成 PC-015。
  • 配置职责修正：2026-07-10 09:47:25 +08:00 参考 C:\Users\Administrator\Desktop\job\3Dyjs\config.js 后确认，根目录 config.js 只负责开发/生产环境与 API 基础地址；PC clientId、tenantId、token key 和 Authorization header 由 utils/ApiClient.js 负责。当前未提供生产地址，生产环境暂时使用用户指定的测试地址，待后端提供生产域名后单独替换。
  • 配置单一来源复核：2026-07-10 10:10:56 +08:00 已移除 utils/ApiClient.js 的 DEFAULT_BASE_URL；客户端现在只能消费根目录 config.js 的 apiBaseUrl 或调用方显式传入的 baseUrl，缺失时立即抛出明确错误。
  • 完成时间：2026-07-10 10:03:18 +08:00
  • 完成结果：下载 Axios 1.7.9 非压缩浏览器构建至 utils/axios.js；创建 utils/AxiosRequestUtil.js 与 utils/ApiClient.js；删除 utils/RequestUtil.js 与 public/js/api-client.js；45 页统一加载 config.js、StorageUtil.js、Axios、AxiosRequestUtil、ApiClient 后再加载页面业务脚本。
  • 验证结果：node tests\config.test.js、node tests\utils.test.js、node tests\api-client.test.js、node tests\api-script-order.test.js、全量 Node 测试、node --check 和旧 fetch/旧脚本扫描均通过；git diff --check 无空白错误。2026-07-10 10:10:56 +08:00 再次回归通过，并确认客户端不再导出 DEFAULT_BASE_URL。

PC-016 TAC 原生样式调用清理

  • 状态：已完成（由 PC-017 修正调用位置）
  • 开始时间：2026-07-10 10:19:46 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-native-style-cleanup.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 约束：只调用 public/tac 自带的 CSS 和 JS；移除项目自定义验证码遮罩、尺寸约束与视觉配置，不改动 TAC 第三方文件。
  • 完成时间：2026-07-10 10:32:20 +08:00
  • 修改结果：删除 public/css/captcha-modal.css；删除 public/css/public.css 中 35 行自定义验证码规则；三页仅保留 public/tac/css/tac.css，并使用无 class 的 [data-captcha-box]；captcha-pages.js 只调用 new TAC(config)。
  • 验证结果：node tests\auth-page-structure.test.js、node tests\captcha-pages.test.js、全量 Node 测试、node --check public\js\captcha-pages.js、自定义验证码视觉标识扫描和 git diff --check 均通过。
  • 外部边界：本项只恢复 TAC 原生视觉与调用边界；验证码背景尺寸校验失败仍需以后端挑战响应的原始图片尺寸为依据另行修复。
  • 复核时间：2026-07-10 10:38:10 +08:00
  • 复核结论：TAC 的 init() 只将组件追加到 CaptchaConfig.bindEl，不负责页面级定位；删除静态挂载点定位样式后，组件被追加到 body 末尾，因此渲染到页面底部。本项不能保留“已完成”。

PC-017 TAC 默认弹层调用纠正

  • 状态：已完成
  • 开始时间：2026-07-10 10:38:10 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-layer-call-correction.md
  • 调用位置：auth-pages.js 表单提交前调用 CaptchaPages.ensureToken；验证码适配层使用 Layui 默认 layer.open 创建临时容器，容器传入 CaptchaConfig.bindEl，然后调用 new TAC(config)。
  • 功能边界：不限制后端下发的 SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK、DISABLED 类型；刷新由 TAC reloadCaptcha() 处理；成功、关闭与异常路径由适配层关闭对应 Layui 层。
  • 完成时间：2026-07-10 10:44:11 +08:00
  • 修改结果：删除三页静态 [data-captcha-box]；captcha-pages.js 用 Layui 默认 layer.open 创建临时容器作为 CaptchaConfig.bindEl，并保持 new TAC(config) 原样调用；TAC 结束后关闭同一 Layui 层。
  • 验证结果：node tests\auth-page-structure.test.js、node tests\captcha-pages.test.js、全量 Node 测试、node --check public\js\captcha-pages.js 和 git diff --check 均通过；静态扫描确认三页、公共 CSS 和验证码适配层没有 data-captcha-box、auth-captcha-modal、captcha-modal.css、bgUrl 或 logoUrl。
  • 浏览器边界：尚未在真实测试网关完成有效轨迹验证；需在浏览器发起一次注册、登录或找回密码操作，确认 Layui 默认层居中和后端 validToken 流程。

PC-018 TAC Layui content 契约修复

  • 状态：已完成（由 PC-019 修正真实挂载点）
  • 开始时间：2026-07-10 10:50:06 +08:00
  • 完成时间：2026-07-10 10:54:03 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-layui-content-contract-fix.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：/captcha/require、/captcha/challenge、/captcha/verify
  • 根因记录：浏览器中 /captcha/require 已返回 200，但点击提交后提示 d.parents is not a function 且 TAC 不显示。根因是 captcha-pages.js 将原生 DOM 节点直接传入 layui.layer.open({ content })；当前 Layui 2.11.5 弹层内部会对 content 调用 .parents()，原生 DOM 没有该方法，导致弹层创建中断。
  • 修改文件：public/js/captcha-pages.js、tests/captcha-pages.test.js、docs/superpowers/plans/2026-07-10-tac-layui-content-contract-fix.md、docs/pc-api-page-integration-tracker-2026-07-09.md
  • 修改结果：createCaptchaLayer 现在使用 layui.$、$ 或 jQuery 包装临时 DOM 后传给 layer.open；返回给 TAC 的 box 仍是真实 DOM 节点，继续作为 CaptchaConfig.bindEl。未修改 public/tac，未新增验证码 CSS，未传 TAC 视觉配置。
  • 验证结果：先运行 node tests\captcha-pages.test.js 复现失败；修复后 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 仅输出既有 CRLF 行尾提示，没有空白错误。

PC-020 TAC Layui 弹层居中修复

  • 状态：已完成
  • 开始时间：2026-07-10 11:11:05 +08:00
  • 完成时间：2026-07-10 11:14:31 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-layer-center-fix.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：/captcha/require、/captcha/challenge、/captcha/verify
  • 根因记录：Layui 打开弹层时验证码挂载点仍是空节点，TAC 后续异步创建自己的 #tianai-captcha-parent，原生尺寸为 318px * 318px，导致 Layui 先按空内容定位后，最终验证码窗口偏离视觉中心。
  • 修改文件：public/js/captcha-pages.js、tests/captcha-pages.test.js、docs/superpowers/plans/2026-07-10-tac-layer-center-fix.md、docs/pc-api-page-integration-tracker-2026-07-09.md
  • 修改结果：createCaptchaLayer 使用 Layui 默认 layer.open 时增加 area: ['318px', '318px'] 与 offset: 'auto'，尺寸来自 TAC 原生 #tianai-captcha-parent；未修改 public/tac，未新增验证码自定义 CSS，未传 TAC 视觉配置。
  • 验证结果：先运行 node tests\captcha-pages.test.js 复现 layerOptions.area 缺失失败；修复后 node tests\captcha-pages.test.js、node tests\auth-page-structure.test.js、node --check public\js\captcha-pages.js 和 git diff --check 通过。git diff --check 仅输出既有 LF/CRLF 换行提示，没有空白错误。

PC-021 验证结果参数格式修正

  • 状态：已完成
  • 开始时间：2026-07-10 14:31:14 +08:00
  • 完成时间：2026-07-10 14:34:28 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-captcha-verify-track-contract.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：POST /captcha/verify
  • 根因记录：后端最新示例要求验证轨迹提交为 payload.track，但前端仍按旧契约提交 payload.id 与 payload.data，并缺少 left/top。
  • 修改文件：public/js/captcha-pages.js、tests/captcha-pages.test.js、docs/superpowers/plans/2026-07-10-captcha-verify-track-contract.md、docs/pc-api-page-integration-tracker-2026-07-09.md
  • 修改结果：buildVerifyBody 现在提交 payload.track；left/top 优先使用已有值，缺失时由轨迹首尾点差值计算；旧的 payload.id 与 payload.data 不再作为 /captcha/verify 请求体提交。
  • 验证结果：先运行 node tests\captcha-pages.test.js 复现旧请求体失败；修复后 node tests\captcha-pages.test.js、node tests\auth-page-structure.test.js、node tests\auth-pages.test.js、node --check public\js\captcha-pages.js 和 git diff --check 通过。git diff --check 仅输出 LF/CRLF 换行提示，没有空白错误。

PC-022 登录页样式优化

  • 状态：已完成
  • 开始时间：2026-07-10 14:42:32 +08:00
  • 完成时间：2026-07-10 14:50:23 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-login-auth-flow-polish.md
  • 页面范围：login.html
  • 修改文件：public/css/login.css
  • 修改结果：登录方式切换区改为圆角分段控件，选中项使用浅红底和红字；按钮与底部链接增加间距。样式全部写在登录页 CSS 中，未通过 JS 注入样式。
  • 验证结果：node tests\auth-page-structure.test.js、node tests\auth-pages.test.js、node tests\captcha-pages.test.js、node --check public\js\auth-pages.js、node --check public\js\captcha-pages.js 和 git diff --check 通过。git diff --check 仅输出 LF/CRLF 换行提示，没有空白错误。

PC-023 注册跳转与验证码取票据流程复核

  • 状态：已完成
  • 开始时间：2026-07-10 14:42:32 +08:00
  • 完成时间：2026-07-10 14:50:23 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-login-auth-flow-polish.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：登录、注册、忘记密码提交前的 /captcha/verify
  • 根因记录：register.html 仍把注册成功地址写为 create-genealogy.html，公共认证脚本也保留同样兜底地址；但创建家谱属于登录后的行为，注册完成应回到登录页。
  • 修改文件：register.html、public/js/auth-pages.js、tests/auth-page-structure.test.js
  • 修改结果：注册页 data-success-url 改为 login.html，注册提交的兜底跳转也改为 login.html；结构测试补充三张认证页验证码场景和 validToken 隐藏字段检查。公共 CaptchaPages 仍统一用 payload.track 调 /captcha/verify 换取 validToken，登录、注册、忘记密码表单提交前共用这一入口。
  • 验证结果：先运行 node tests\auth-page-structure.test.js 复现注册跳转失败；修复后 node tests\auth-page-structure.test.js、node tests\auth-pages.test.js、node tests\captcha-pages.test.js、node --check public\js\auth-pages.js、node --check public\js\captcha-pages.js 和 git diff --check 通过。git diff --check 仅输出 LF/CRLF 换行提示，没有空白错误。

PC-024 认证页表单校验和结构规范化

  • 状态：已完成
  • 开始时间：2026-07-10 14:56:08 +08:00
  • 完成时间：2026-07-10 15:11:49 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-auth-form-validation-normalization.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：登录、短信登录、注册、找回密码提交前的本地校验与验证码取票据
  • 结论记录：form 标签本身不是落后写法，认证提交页保留语义表单更合适；但 data-captcha-scene、data-success-url、data-scene-code 这类业务配置不应散在 HTML 上。
  • 修改文件：login.html、register.html、forgot-password.html、public/js/auth-pages.js、tests/auth-pages.test.js、tests/auth-page-structure.test.js
  • 修改结果：三张认证页表单改用稳定 id 作为 JS 挂载点，移除认证业务配置型 data-*；登录方式切换改用标准 aria-controls 关联表单面板；auth-pages.js 新增 FORM_CONFIG 统一管理场景码和跳转地址；新增 validateAuthValues 统一校验手机号、密码、短信验证码和确认密码。登录、注册、忘记密码提交前仍统一走 CaptchaPages.ensureToken，由 captcha-pages.js 按 payload.track 调 /captcha/verify 换取 validToken。
  • 验证结果：先运行 node tests\auth-page-structure.test.js 与 node tests\auth-pages.test.js 复现失败；修复后 node tests\auth-page-structure.test.js、node tests\auth-pages.test.js、node tests\captcha-pages.test.js、node --check public\js\auth-pages.js、node --check public\js\captcha-pages.js 和 git diff --check 通过。扫描确认三张认证页和 auth-pages.js 无 data-auth-form、data-captcha-scene、data-success-url、data-scene-code、data-login-mode 残留；git diff --check 仅输出 LF/CRLF 换行提示，没有空白错误。
  • 复核结论：该项只解决 d.parents is not a function；用户 2026-07-10 10:59 左右浏览器复测显示 Layui 遮罩出现、/captcha/challenge 返回 200，但 TAC 本体未显示，因此真实挂载点问题进入 PC-019 修正。

PC-019 TAC Layui 实际挂载点修复

  • 状态：已完成
  • 开始时间：2026-07-10 10:59:52 +08:00
  • 完成时间：2026-07-10 11:04:18 +08:00
  • 计划文件：docs/superpowers/plans/2026-07-10-tac-layer-real-mount-fix.md
  • 页面范围：login.html、register.html、forgot-password.html
  • 接口范围：/captcha/require、/captcha/challenge、/captcha/verify
  • 根因记录：用户浏览器截图显示 Layui 遮罩已经出现，/captcha/require 与 /captcha/challenge 都返回 200，但弹层内没有 TAC 验证窗口。根因是 PC-018 仍返回打开前的临时 DOM 给 CaptchaConfig.bindEl，不能保证该节点就是 Layui 弹层内容区里的真实节点。
  • 修改文件：public/js/captcha-pages.js、tests/captcha-pages.test.js、docs/superpowers/plans/2026-07-10-tac-layer-real-mount-fix.md、docs/pc-api-page-integration-tracker-2026-07-09.md
  • 修改结果：createCaptchaLayer 现在用字符串 content 让 Layui 创建 <div data-captcha-layer-box="..."></div>，弹层打开后再通过 document.querySelector 获取这个实际节点，并将它作为 TAC 的 bindEl。未修改 public/tac，未新增验证码 CSS，未传 TAC 视觉配置。
  • 验证结果：先运行 node tests\captcha-pages.test.js 复现失败；修复后 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 仅输出既有 CRLF 行尾提示，没有空白错误。

PC-025 注册、登录到个人资料闭环

  • 状态：已完成
  • 完成时间：2026-07-11 09:32:35 +08:00
  • 规划文件：docs/superpowers/specs/2026-07-11-auth-to-profile-flow-design.md
  • 页面范围：register.html、login.html、profile.html、profile-data.html
  • 接口范围：/genealogy/pc/auth/register、/genealogy/pc/auth/login、/genealogy/pc/auth/login/sms、/genealogy/pc/auth/profile、/genealogy/pc/auth/logout
  • 地址契约：运行时唯一来源为 config.js；当前开发和生产地址均为 http://182.61.18.23:8080。
  • 流程结果：注册成功清除 token 并跳转 login.html；当前登录响应从 data.access_token 取 JWT，且兼容 token、accessToken、tokenValue 后跳转 profile.html；个人资料无 token 或收到 HTTP/业务 401 时清 token 并跳转 index.html；确认退出无论接口结果都清 token 并跳转 index.html。
  • 修改文件：tests/config.test.js、tests/utils.test.js、utils/ApiClient.js、tests/api-client.test.js、public/js/profile-pages.js、public/js/profile-common.js、profile.html、tests/profile-pages.test.js、tests/profile-logout-structure.test.js。
  • 验证结果：node tests/config.test.js、node tests/utils.test.js、node tests/api-client.test.js、node tests/auth-pages.test.js、node tests/profile-pages.test.js、node tests/profile-logout-structure.test.js、node --check utils/ApiClient.js、node --check public/js/profile-pages.js、node --check public/js/profile-common.js 和全量 Node 测试均通过。

PC-026 安全页认证入口收敛

  • 状态：部分完成
  • 完成时间：2026-07-11
  • 页面范围：profile-security.html
  • 接口范围：/genealogy/pc/auth/login/sms、/genealogy/pc/auth/phone、/genealogy/pc/auth/account/deactivate、/genealogy/pc/auth/logout
  • 契约结果：login.html 是密码和短信登录的唯一入口；登录成功跳转 profile.html。已登录的账号安全页不得重复发起登录流程。退出登录和账号注销完成后均跳转 index.html。
  • 修改结果：删除安全页遗留的短信登录表单、旧接口说明、请求体构造和提交分支；安全页退出无论接口请求结果都跳转首页，账号注销成功后也跳转首页。
  • 后端阻塞：换绑手机仍无法形成完整 PC/H5 流程。POST /genealogy/pc/auth/sms/code 必填 sceneCode 和 validToken，但当前未定义换绑手机的 PC/H5 场景码；不得使用未经确认的场景替代。待后端提供场景码后，补充滑动验证、发送短信验证码和换绑提交链路。
  • 验证结果：先运行 node tests/security-pages.test.js，确认旧安全页短信登录导出仍存在而按预期失败；修复后该测试通过。全量验证待本项后续记录补充。

PC-027 PC-only 接口契约清理

  • 状态：已完成
  • 完成时间：2026-07-11
  • 契约所有者：genealogy-pc-openapi.yaml 是 PC/H5 页面接口的唯一依据；运行时请求由 utils/ApiClient.js 统一发起。
  • 修改结果：删除旧接口文档和错误对接记录；清除页面、脚本、规划和 PC YAML 中遗留的旧路径、场景码与文档引用；PC YAML 的验证码示例统一使用 WEB_H5_LOGIN，注册来源示例为 PC。
  • 登录确认：login.html 的短信登录继续经 public/js/auth-pages.js 调用 utils/ApiClient.js，请求 POST /genealogy/pc/auth/login/sms，验证码场景为 WEB_H5_LOGIN。
  • 验证结果：新增 tests/pc-api-contract.test.js。该测试确认旧接口文档与错误记录不存在，扫描当前运行代码、PC YAML 和有效规划没有遗留旧契约，并断言短信登录使用 PC 路径和 WEB_H5_LOGIN。

PC-028 当前 PC 接口页面覆盖

  • 状态：部分完成
  • 完成时间：2026-07-11
  • 接口清单：genealogy-pc-openapi.yaml 当前有 25 个操作；tests/pc-endpoint-coverage.test.js 对每项操作断言页面调用或明确后端阻塞原因。
  • 已形成页面闭环的 21 项操作：验证码查询/挑战/校验，注册、密码登录、短信登录、短信验证码，资料读取/修改，修改密码、找回密码、注销账号、退出登录，单文件上传、分片初始化/上传/完成，地区下级查询/搜索/路径/详情。
  • 文件上传结果：profile-data.html 的头像上传不再要求手填 OSS ID。文件不超过 4 MB 时调用单文件上传；超过 4 MB 时依次调用分片初始化、每片上传和完成上传，完成后回填同一 avatarOssId，由“保存资料”提交资料接口。
  • 地区结果：profile-data.html 支持按地区名称或编码搜索；选择结果会查询地区详情和路径，再回填省、市、区县选择器后提交资料接口。
  • 后端契约阻塞的 4 项操作：
    1. GET /auth/code：接口是兼容旧图形验证码，但当前 PC 登录/注册请求体没有可提交的验证码字段。
    2. PUT /genealogy/pc/auth/phone：发送短信前需要 PC/H5 换绑手机号验证码场景码，当前文档未提供。
    3. POST /genealogy/pc/files/reference：缺少可由当前 PC 页面创建的业务表名和业务 ID 契约。
    4. DELETE /genealogy/pc/files/reference：同样缺少业务表名、业务 ID 和业务字段的来源契约。
  • 浏览器验收顺序：
    1. register.html：完成注册，确认跳转 login.html 且不保留登录态。
    2. login.html 密码登录：完成滑块验证和登录，确认跳转 profile.html。
    3. login.html 短信登录：完成滑块验证、发送短信和登录，确认跳转 profile.html。
    4. profile.html：确认资料成功加载；清空本地 token 后重新进入，确认跳转首页。
    5. profile-data.html：修改昵称、性别、生日后保存；上传小于等于 4 MB 的头像并保存资料。
    6. profile-data.html：上传大于 4 MB 的头像，确认网络依次出现 resumable/init、resumable/chunk、resumable/complete，再保存资料。
    7. profile-data.html：搜索地区名称或编码，选择结果，确认省市区回填后保存。
    8. forgot-password.html：完成验证码、短信码和密码重置。
    9. profile-security.html：分别测试修改密码、账号注销和退出登录；退出与注销成功后均回首页。
  • 验证结果：node tests/pc-endpoint-coverage.test.js、node tests/upload-pages.test.js、node tests/region-pages.test.js、node tests/profile-pages.test.js、node tests/auth-pages.test.js、node tests/captcha-pages.test.js、node tests/api-client.test.js、node tests/security-pages.test.js 均通过。
Reference in New Issue View Git Blame Copy Permalink