23 KiB
23 KiB
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
执行规则
- 所有 PC 接口对接必须先进入本追踪表,再改代码。
- 每一项开始前先标记“进行中”,记录年月日时分秒和时区。
- 每一项完成后记录完成时间、修改文件、接口路径、验证命令和结果。
- 只有完成验证后才能标记“已完成”。
genealogy-pc-openapi.yaml没有明确接口的页面,标记“暂缓”或“待确认”,不继续套用 APP 路径。- 样式继续写入 CSS 文件,业务 JS 不注入样式。
- 新增或修改的 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
paths中实际存在 25 个接口操作,分为验证码、PC 认证、PC 文件、行政区划四类。servers仍是本地地址示例,项目实际对接基础地址继续按用户指定使用https://test-genealogy-api.ddxcjp.cn。- 登录后接口使用
Authorization作为 token header,同时所有 PC 认证和文件接口都要求 headerclientid;用户最新提供的 PCclientid为ced7e5f0498645c6ec642dcf450b036f,客户端 Key 为web_pc。 components.tags和components.schemas/requestBodies中出现家谱、动态、世系、字辈等业务模型,但paths没有对应接口路径;实现时不能把这些 schema 当成可调用 PC 接口。- 验证码 schema 示例里仍出现
APP_LOGIN、PC_LOGIN等文本示例;实际页面场景以后台配置为准,当前明确可用的 PC/H5 场景为WEB_H5_LOGIN、WEB_H5_REGISTER、WEB_H5_FORGOT_PASSWORD。 ProfileUpdate示例出现regionCode/addressDetail,但 schema 实际字段是provinceCode/cityCode/districtCode,页面资料提交时应以 schema 字段为准。SmsLoginBody未声明validToken字段,但短信发送SmsCodeBody必填validToken;短信登录流程应先通过验证码拿票据,再发短信验证码,最后用短信码登录。- 文件引用
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 页面使用。APP_LOGIN、APP_REGISTER、APP_PHONE_CHANGE、APP_FORGOT_PASSWORD、APP_SMS_CODE、APP_ACCOUNT_DEACTIVATE的客户端 Key 为app,不能继续作为 PC/H5 场景默认值。- PC/H5 登录页调用链:
- 页面加载
public/tac/css/tac.css、public/tac/js/tac.min.js、public/js/captcha-pages.js。 - 表单提供
input[name="validToken"]隐藏字段和[data-captcha-box]容器。 auth-pages.js在登录提交前调用CaptchaPages.ensureToken(form, { sceneCode: 'WEB_H5_LOGIN', subject: 手机号 })。captcha-pages.js先请求GET /captcha/require?tenantId=000000&clientId=ced7e5f0498645c6ec642dcf450b036f&sceneCode=WEB_H5_LOGIN&subject=手机号。- 如果返回
required=false,业务表单可继续提交;如果需要验证,则创建new CaptchaConfig(...)和new TAC(config, ...)。 - TAC 内部请求
POST /captcha/challenge获取captchaType/challengeId/payload,适配为 TAC 需要的data.type/data.id/backgroundImage/templateImage。 - 用户拖动完成后,TAC 请求
POST /captcha/verify,提交challengeId/providerCode/captchaType/payload.data.trackList。 - 验证成功后从返回
data.validToken取票据,写回表单隐藏字段validToken,再提交 PC 登录接口。
- 页面加载
- PC/H5 注册使用
WEB_H5_REGISTER,找回密码和找回密码短信验证码使用WEB_H5_FORGOT_PASSWORD;换绑手机、注销账号暂未看到明确 PC/H5 场景编码,仍待后端补充后再接。
编号计划
| 编号 | 状态 | 页面范围 | 接口范围 | 计划与验证 |
|---|---|---|---|---|
| PC-000 | 已完成 | 全项目 | genealogy-pc-openapi.yaml、https://test-genealogy-api.ddxcjp.cn |
2026-07-09 15:14:58 +08:00 完成。确认旧 APP 接口依据错误,停止继续按 APP 路径推进;确认 PC YAML 当前只明确认证、文件、地区接口。 |
| PC-001 | 已完成 | 全项目配置层 | config.js、https://test-genealogy-api.ddxcjp.cn |
2026-07-09 15:57:36 +08:00 修正完成。根目录 config.js 作为开发/生产环境切换的唯一入口;开发环境基础地址为 https://test-genealogy-api.ddxcjp.cn;PC clientid 按用户最新截图改为 ced7e5f0498645c6ec642dcf450b036f,客户端 Key 为 web_pc。验证:node tests\config.test.js 输出 config tests passed,node --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.js、utils/FormUtil.js、utils/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.js、node 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.html、register.html、forgot-password.html、profile-security.html、profile-data.html、profile.html |
/genealogy/pc/auth/*、/captcha/* |
2026-07-09 16:00:22 +08:00 完成。login.html 使用 WEB_H5_LOGIN;register.html 使用 WEB_H5_REGISTER;forgot-password.html 使用 WEB_H5_FORGOT_PASSWORD;认证/资料/安全页面均已补齐 config.js、utils/*、api-client.js 脚本顺序。资料提交字段按 PC YAML 使用 provinceCode/cityCode/districtCode。验证:node tests\auth-pages.test.js、node tests\captcha-pages.test.js、node tests\profile-pages.test.js、node 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.html、profile-article-edit.html、profile-feed-edit.html、profile-growth-edit.html、profile-memo-edit.html、profile-gift-edit.html 已补齐 config.js、utils/*、api-client.js、upload-pages.js 顺序。验证:node tests\upload-pages.test.js、node 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.html、profile-create-family.html、profile-data.html 地区选择页面已补齐 config.js、utils/*、api-client.js、region-pages.js 顺序;地区请求只走 /genealogy/region/children、/genealogy/region/path/{regionCode}、/genealogy/region/search、/genealogy/region/{regionCode}。验证:node tests\region-pages.test.js、node 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.yaml 的 paths、docs/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.html、register.html、forgot-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.md。login.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.html、public/css/login.css、public/js/auth-pages.js、tests/auth-pages.test.js、tests/api-client.test.js。验证:node tests\auth-pages.test.js、node tests\api-client.test.js、node tests\captcha-pages.test.js 通过;全量 tests/*.test.js 通过;node --check public\js\auth-pages.js、node --check public\js\api-client.js、node --check public\js\captcha-pages.js 通过;内联样式和旧验证码场景扫描无输出。 |
| PC-010 | 已完成 | config.js、public/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.cn;config.js 对旧的 https://test-genealogy-api.ddxcjp.cn 本地覆盖值做归一,避免浏览器 localStorage 残留继续走坏地址;api-client.js fallback 默认地址同步改为 HTTP。修改文件:config.js、public/js/api-client.js、tests/config.test.js、tests/api-client.test.js。验证:node tests\config.test.js、node tests\api-client.test.js、node --check config.js、node --check public\js\api-client.js 通过。 |
| PC-011 | 已完成 | login.html、register.html、forgot-password.html、public/css/public.css、public/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.html、register.html、forgot-password.html、public/css/public.css、public/js/captcha-pages.js、tests/auth-page-structure.test.js、tests/captcha-pages.test.js。验证:node tests\auth-page-structure.test.js、node tests\captcha-pages.test.js 通过;全量 tests/*.test.js 通过;node --check public\js\captcha-pages.js、node --check public\js\auth-pages.js 通过;表单内部 data-captcha-box 扫描无输出。 |
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;换绑、注销涉及验证码的提交先记录待确认,不能套用 APP_* 场景。 |
| 资料接口可对接 | 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 没有这些业务路径。 | 不套用 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.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 的
api-client.js切换;旧 APP 路径不再作为网络请求路径,未覆盖业务统一抛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 未覆盖业务不会继续发送旧 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 的
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,这是后端/隧道可用性问题,不是本次提示和样式改动导致。 - 执行计划:
- 已完成失败测试:
tests/auth-page-structure.test.js、tests/auth-message.test.js。 - 已完成:三页加载 layui 样式和脚本。
- 已完成:
auth-pages.js、captcha-pages.js提示统一走MessageUtil/layui.layer.msg,不再使用浏览器原生alert。 - 已完成:
public/css/public.css增加认证页 layer 提示皮肤。 - 已完成:焦点测试、相关测试、语法检查和全量 Node 测试通过。
- 已完成失败测试: