Files
jiapu/docs/pc-api-page-integration-tracker-2026-07-09.md
T
2026-07-09 17:30:10 +08:00

23 KiB
Raw Blame History

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

创建时间:2026-07-09 15:14:58 +08:00
接口依据:genealogy-pc-openapi.yaml
接口基础地址:http://test-genealogy-api.ddxcjp.cn
旧依据处理:APP.openapi.json 只作为历史误用记录,不再作为 PC 页面继续对接依据。
旧进度记录:docs/api-page-integration-tracker-2026-07-09.md

执行规则

  1. 所有 PC 接口对接必须先进入本追踪表,再改代码。
  2. 每一项开始前先标记“进行中”,记录年月日时分秒和时区。
  3. 每一项完成后记录完成时间、修改文件、接口路径、验证命令和结果。
  4. 只有完成验证后才能标记“已完成”。
  5. genealogy-pc-openapi.yaml 没有明确接口的页面,标记“暂缓”或“待确认”,不继续套用 APP 路径。
  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 仍是本地地址示例,项目实际对接基础地址继续按用户指定使用 https://test-genealogy-api.ddxcjp.cn
  3. 登录后接口使用 Authorization 作为 token header,同时所有 PC 认证和文件接口都要求 header clientid;用户最新提供的 PC clientidced7e5f0498645c6ec642dcf450b036f,客户端 Key 为 web_pc
  4. components.tagscomponents.schemas/requestBodies 中出现家谱、动态、世系、字辈等业务模型,但 paths 没有对应接口路径;实现时不能把这些 schema 当成可调用 PC 接口。
  5. 验证码 schema 示例里仍出现 APP_LOGINPC_LOGIN 等文本示例;实际页面场景以后台配置为准,当前明确可用的 PC/H5 场景为 WEB_H5_LOGINWEB_H5_REGISTERWEB_H5_FORGOT_PASSWORD
  6. ProfileUpdate 示例出现 regionCode/addressDetail,但 schema 实际字段是 provinceCode/cityCode/districtCode,页面资料提交时应以 schema 字段为准。
  7. SmsLoginBody 未声明 validToken 字段,但短信发送 SmsCodeBody 必填 validToken;短信登录流程应先通过验证码拿票据,再发短信验证码,最后用短信码登录。
  8. 文件引用 FileReferenceBody 必填 bizType/bizTable/bizId/bizFieldossId/ossIds/usageScene/usageName 可选;但文章、动态、相册等业务主体接口未提供,文件引用只能作为公共上传能力,不代表主业务已可提交。

验证码与 TAC 调用记录

  • 后台验证码配置截图中,PC/H5 当前明确可用场景是 WEB_H5_LOGINWEB_H5_REGISTERWEB_H5_FORGOT_PASSWORD,客户端 Key 为 web_pc,验证服务为“天爱行为验证码”,验证码类型为“滑块验证码”。
  • ADMIN_LOGIN 是后台管理登录,类型为旋转验证码,不归当前 PC/H5 页面使用。
  • APP_LOGINAPP_REGISTERAPP_PHONE_CHANGEAPP_FORGOT_PASSWORDAPP_SMS_CODEAPP_ACCOUNT_DEACTIVATE 的客户端 Key 为 app,不能继续作为 PC/H5 场景默认值。
  • PC/H5 登录页调用链:
    1. 页面加载 public/tac/css/tac.csspublic/tac/js/tac.min.jspublic/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.data.trackList
    8. 验证成功后从返回 data.validToken 取票据,写回表单隐藏字段 validToken,再提交 PC 登录接口。
  • PC/H5 注册使用 WEB_H5_REGISTER,找回密码和找回密码短信验证码使用 WEB_H5_FORGOT_PASSWORD;换绑手机、注销账号暂未看到明确 PC/H5 场景编码,仍待后端补充后再接。

编号计划

编号 状态 页面范围 接口范围 计划与验证
PC-000 已完成 全项目 genealogy-pc-openapi.yamlhttps://test-genealogy-api.ddxcjp.cn 2026-07-09 15:14:58 +08:00 完成。确认旧 APP 接口依据错误,停止继续按 APP 路径推进;确认 PC YAML 当前只明确认证、文件、地区接口。
PC-001 已完成 全项目配置层 config.jshttps://test-genealogy-api.ddxcjp.cn 2026-07-09 15:57:36 +08:00 修正完成。根目录 config.js 作为开发/生产环境切换的唯一入口;开发环境基础地址为 https://test-genealogy-api.ddxcjp.cnPC clientid 按用户最新截图改为 ced7e5f0498645c6ec642dcf450b036f,客户端 Key 为 web_pc。验证:node tests\config.test.js 输出 config tests passednode --check config.js 通过。
PC-002 已完成 utils 公共工具层、public/js/api-client.js PC clientid、通用请求、token、表单、存储、PC YAML paths 2026-07-09 15:51:34 +08:00 完成。新增 utils/StorageUtil.jsutils/FormUtil.jsutils/RequestUtil.js;重写 public/js/api-client.js,真实请求只保留 PC YAML 中的 /captcha/*/auth/code/genealogy/pc/auth/*/genealogy/pc/files/*/genealogy/region/*,PC YAML 未覆盖业务方法改为抛 PC_API_NOT_AVAILABLE,不再发旧 APP 请求。验证:node tests\utils.test.jsnode tests\api-client.test.js 均通过;Select-String -Path public\js\api-client.js -Pattern '/genealogy/app/' 无输出;node --check public\js\api-client.js 通过。
PC-003 已完成 login.htmlregister.htmlforgot-password.htmlprofile-security.htmlprofile-data.htmlprofile.html /genealogy/pc/auth/*/captcha/* 2026-07-09 16:00:22 +08:00 完成。login.html 使用 WEB_H5_LOGINregister.html 使用 WEB_H5_REGISTERforgot-password.html 使用 WEB_H5_FORGOT_PASSWORD;认证/资料/安全页面均已补齐 config.jsutils/*api-client.js 脚本顺序。资料提交字段按 PC YAML 使用 provinceCode/cityCode/districtCode。验证:node tests\auth-pages.test.jsnode tests\captcha-pages.test.jsnode tests\profile-pages.test.jsnode tests\security-pages.test.js 均通过;相关 JS node --check 通过;旧 PC_LOGIN/PC_REGISTER/PC_PASSWORD_RESET/APP_* 场景扫描无输出。
PC-004 已完成 文件上传相关页面 /genealogy/pc/files/* 2026-07-09 16:03:23 +08:00 完成。api-client.js 文件上传、分片上传、文件引用绑定均走 /genealogy/pc/files/*profile-album.htmlprofile-article-edit.htmlprofile-feed-edit.htmlprofile-growth-edit.htmlprofile-memo-edit.htmlprofile-gift-edit.html 已补齐 config.jsutils/*api-client.jsupload-pages.js 顺序。验证:node tests\upload-pages.test.jsnode tests\api-client.test.js 通过;Select-String -Path public\js\api-client.js,public\js\upload-pages.js -Pattern '/genealogy/app/files' 无输出。
PC-005 已完成 使用地区选择的页面 /genealogy/region/* 2026-07-09 16:05:12 +08:00 完成。create-genealogy.htmlprofile-create-family.htmlprofile-data.html 地区选择页面已补齐 config.jsutils/*api-client.jsregion-pages.js 顺序;地区请求只走 /genealogy/region/children/genealogy/region/path/{regionCode}/genealogy/region/search/genealogy/region/{regionCode}。验证:node tests\region-pages.test.jsnode tests\profile-pages.test.js 通过;node --check public\js\region-pages.js 通过;地区旧 APP 路径扫描无输出。
PC-006 已修正 全项目页面覆盖矩阵 PC YAML 现有接口覆盖范围与缺口 2026-07-09 15:34:26 +08:00 完成修正。该项只作为文档清单任务,不做业务代码。输出页面级覆盖矩阵:完整可闭环、接口存在但验证码待确认、只能保留公共能力、文件能力可切换但主业务待确认、PC YAML 未覆盖。避免把“页面里某个公共接口可用”误标为“整页已可对接”。
PC-007 已完成 详细实施规划 genealogy-pc-openapi.yamlpathsdocs/superpowers/plans/2026-07-09-pc-api-replan.md 2026-07-09 15:41:40 +08:00 完成修正。重写详细实施计划:只以 YAML paths 为真实接口来源;api-client.js 不能保留 APP 路径 fallback;PC YAML 未覆盖页面改为受控“接口待确认/PC_API_NOT_AVAILABLE”;补充资料字段 provinceCode/cityCode/districtCode、TAC 登录场景 WEB_H5_LOGIN、文件/地区局部能力边界。
PC-008 已完成 PC YAML 未覆盖业务页面 PC_API_NOT_AVAILABLE、旧 APP 网络路径清理 2026-07-09 16:06:35 +08:00 完成。api-client.js 中家谱主体、成员、字辈、世系、动态、文章、相册、祭祀、族务、VIP、通知、反馈、帮助、推广等 PC YAML 未覆盖业务方法保留方法名但统一抛 PC_API_NOT_AVAILABLE,不再发 /genealogy/app/ 请求。验证:`Get-ChildItem -Path tests -Filter *.test.js
PC-009 已完成 login.htmlregister.htmlforgot-password.html /genealogy/pc/auth/login/genealogy/pc/auth/login/sms/genealogy/pc/auth/register/genealogy/pc/auth/sms/code/genealogy/pc/auth/password/reset/captcha/* 2026-07-09 16:32:17 +08:00 开始,2026-07-09 16:40:02 +08:00 完成。专项计划见 docs/superpowers/plans/2026-07-09-pc-auth-three-pages.mdlogin.html 已补齐密码登录/短信登录两种模式,短信登录使用 WEB_H5_LOGIN 发送验证码并调用 /genealogy/pc/auth/login/sms;注册页继续使用 WEB_H5_REGISTER/genealogy/pc/auth/register;忘记密码页继续使用 WEB_H5_FORGOT_PASSWORD/genealogy/pc/auth/sms/code/genealogy/pc/auth/password/reset。修改文件:login.htmlpublic/css/login.csspublic/js/auth-pages.jstests/auth-pages.test.jstests/api-client.test.js。验证:node tests\auth-pages.test.jsnode tests\api-client.test.jsnode tests\captcha-pages.test.js 通过;全量 tests/*.test.js 通过;node --check public\js\auth-pages.jsnode --check public\js\api-client.jsnode --check public\js\captcha-pages.js 通过;内联样式和旧验证码场景扫描无输出。
PC-010 已完成 config.jspublic/js/api-client.js 开发环境接口基础地址、/captcha/require/captcha/challenge 2026-07-09 16:45:35 +08:00 开始,2026-07-09 16:48:05 +08:00 完成。根因:浏览器和 curl.exe 复现 https://test-genealogy-api.ddxcjp.cn TLS 握手失败,错误为 ERR_SSL_UNRECOGNIZED_NAME_ALERT/SEC_E_ILLEGAL_MESSAGE;同一 /captcha/require 请求改用 http://test-genealogy-api.ddxcjp.cn 返回 200 OK。处理:开发环境基础地址改为 http://test-genealogy-api.ddxcjp.cnconfig.js 对旧的 https://test-genealogy-api.ddxcjp.cn 本地覆盖值做归一,避免浏览器 localStorage 残留继续走坏地址;api-client.js fallback 默认地址同步改为 HTTP。修改文件:config.jspublic/js/api-client.jstests/config.test.jstests/api-client.test.js。验证:node tests\config.test.jsnode tests\api-client.test.jsnode --check config.jsnode --check public\js\api-client.js 通过。
PC-011 已完成 login.htmlregister.htmlforgot-password.htmlpublic/css/public.csspublic/js/captcha-pages.js public/tac 弹窗挂载、/captcha/challenge/captcha/verify 2026-07-09 16:56:22 +08:00 开始,2026-07-09 17:02:35 +08:00 完成。根因:public/tac/css/tac.css#tianai-captcha-parent 是相对定位,会在绑定元素内渲染;此前把 [data-captcha-box] 放进表单内部,导致验证码块直接占据卡片内容区域。处理:三张认证页移除表单内部挂载点,新增页面级 .auth-captcha-modal[data-captcha-box]public/css/public.css 增加固定遮罩、居中和移动端宽度约束;captcha-pages.js 优先使用页面级挂载点;未修改 public/tac/js/tac.min.js。修改文件:login.htmlregister.htmlforgot-password.htmlpublic/css/public.csspublic/js/captcha-pages.jstests/auth-page-structure.test.jstests/captcha-pages.test.js。验证:node tests\auth-page-structure.test.jsnode tests\captcha-pages.test.js 通过;全量 tests/*.test.js 通过;node --check public\js\captcha-pages.jsnode --check public\js\auth-pages.js 通过;表单内部 data-captcha-box 扫描无输出。

PC 页面覆盖矩阵草案

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

流程记录

  • 2026-07-09 15:14:58 +08:00:收到用户纠正,停止 APP 接口继续推进;读取 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;明确旧 APP 路径不能作为 PC fallback,缺失业务接口统一降级为接口待确认。
  • 2026-07-09 15:44:18 +08:00:开始执行 PC-001/PC-002,先按 TDD 创建 config.jsutils 公共工具测试,再实现最小配置与工具层。
  • 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 的 api-client.js 切换;旧 APP 路径不再作为网络请求路径,未覆盖业务统一抛 PC_API_NOT_AVAILABLE
  • 2026-07-09 15:55:28 +08:00PC-003 认证页验证码阶段完成;登录使用 WEB_H5_LOGIN,未确认 PC/H5 场景的注册和找回密码不调用验证中心。
  • 2026-07-09 15:57:36 +08:00:收到用户补充截图,确认 PC clientidced7e5f0498645c6ec642dcf450b036f、客户端 Key 为 web_pc,新增注册场景 WEB_H5_REGISTER 和找回密码场景 WEB_H5_FORGOT_PASSWORD;同步修正配置、计划和认证页场景映射。
  • 2026-07-09 16:00:22 +08:00PC-003 完成;认证页、资料页、安全页的 PC auth/captcha 接入和脚本顺序已验证。
  • 2026-07-09 16:03:23 +08:00PC-004 完成;上传公共能力切换到 PC 文件接口,相关上传页已补齐公共层脚本顺序。
  • 2026-07-09 16:05:12 +08:00PC-005 完成;地区选择只保留公共行政区划能力,创建家谱等主业务仍按 PC YAML 未覆盖处理。
  • 2026-07-09 16:06:35 +08:00PC-008 完成;PC YAML 未覆盖业务不会继续发送旧 APP 请求,全量 Node 测试通过。
  • 2026-07-09 16:07:42 +08:00:收尾验证完成;全量 tests/*.test.js 通过,public/js 非压缩业务脚本 node --check 通过,旧 /genealogy/app/、旧验证码场景、旧 PC clientId 扫描无输出;git diff --check 因当前目录不是 Git 仓库无法执行。
  • 2026-07-09 16:09:55 +08:00:开始登录、注册、找回密码三页专项核对;按 PC YAML 的 PasswordLoginBodyPasswordRegisterBodySmsCodeBodyPasswordResetBody 修正页面字段、输入类型、验证码场景声明和文案。
  • 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.jsnode tests\captcha-pages.test.jsnode 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:00TAC 弹窗挂载修复完成。三张认证页改为页面级固定遮罩容器承载 TAC,表单内部不再放验证码挂载点;新增结构测试防止回退。
  • 2026-07-09 17:04:21 +08:00:复现用户反馈的 503 Service Unavailablecurl.exe 请求 /captcha/require 和域名根路径 / 均返回 Server: SakuraFrp503 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.htmlregister.htmlforgot-password.html
  • 接口范围:不新增接口,只修正 /captcha/* 流程中的前端提示方式和弹窗展示方式。
  • 完成时间:2026-07-09 17:20:24 +08:00
  • 修改文件:login.htmlregister.htmlforgot-password.htmlutils/MessageUtil.jspublic/js/auth-pages.jspublic/js/captcha-pages.jspublic/css/public.csstests/auth-page-structure.test.jstests/auth-message.test.jsdocs/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.jstests/auth-message.test.js
    2. 已完成:三页加载 layui 样式和脚本。
    3. 已完成:auth-pages.jscaptcha-pages.js 提示统一走 MessageUtil/layui.layer.msg,不再使用浏览器原生 alert
    4. 已完成:public/css/public.css 增加认证页 layer 提示皮肤。
    5. 已完成:焦点测试、相关测试、语法检查和全量 Node 测试通过。