rain/jiapu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

家谱现有接口调试50%

Browse Source
This commit is contained in:
rain
2026-07-09 17:29:25 +08:00
commit 6050508144
262 changed files with 63354 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-page-integration-2026-07-09.md
+102
View File
@@ -0,0 +1,102 @@
# 接口对接规划与进度记录
## 基本信息
- 项目路径：`C:\Users\Administrator\Desktop\job\家谱`
- 接口文档：`APP.openapi.json`
- 记录创建时间：2026-07-09 11:51:16 +08:00
- 执行范围：先做核心闭环页面接口对接，再按页面模块继续扩展。
- 当前假设：接口文档以 `/genealogy/app` 为主，PC/H5 页面先复用这些用户侧接口。
## 约束摘要
- 先规划再实现，所有执行进度需要记录年月日时间。
- 改动要小，只触碰接口对接必需文件。
- 新接口契约由共享 API 客户端统一维护，页面脚本只调用封装方法。
- 完成后做最小可验证检查；不能验证的地方要明确说明。
- 样式尽量写入 `public.css` 或页面对应 CSS 文件，通过 class 控制，不用 JS 注入样式。
- 新增 HTML、JS、CSS 注释统一使用中文。
- CSS 结构先公共后页面：`public.css` 放全站公共组件，页面 CSS 只放本页面差异样式。
- 个人中心模块页优先复用 `profile-module.css`，只有页面独有样式再新增或修改对应页面 CSS。
- 页面专用 JS 放 `public/js`，命名跟页面或模块对应；公告详情页如需 JS 使用 `public/js/notice-detail.js`。
- 业务代码不压缩，保持展开、可读；需要解释意图、边界或接口字段映射的位置使用中文注释。
- 第三方库、压缩库、已存在乱码文件不做无关重写，避免引入额外风险。
## 核心闭环范围
1. 共享接口层
- 新增统一 API 客户端，负责 `baseUrl`、`clientid`、`tenantId`、token 存取、请求头、响应解包和错误提示。
- 默认 `clientid` 使用接口文档示例：`ced7e5f0498645c6ec642dcf450b036f`。
- 默认 `tenantId` 使用接口文档示例：`000000`。
- API 基础地址从 `window.GENEALOGY_API_BASE_URL` 或 `localStorage.genealogy_api_base_url` 读取，未配置时使用同域相对路径。
- 浏览器端公共脚本放 `public/js`；`utils` 目前只适合作为纯工具类目录，不能作为页面脚本入口。
- 页面专用 JS 按页面或模块放 `public/js`，例如认证模块用 `auth-pages.js`，公告详情页如需脚本则用 `notice-detail.js`。
2. 登录注册找回
- `login.html` -> `POST /genealogy/app/auth/login`
- `register.html` -> `POST /genealogy/app/auth/register`
- `forgot-password.html` -> `POST /genealogy/app/auth/sms/code`，`PUT /genealogy/app/auth/password/reset`
- 密码按文档要求提交 32 位 MD5，复用已有 `public/js/md5.js`。
3. 家谱核心
- `create-genealogy.html` -> `POST /genealogy/app/genealogies`
- `profile-families.html` -> `GET /genealogy/app/genealogies/mine`
- `plaza.html` -> `GET /genealogy/app/genealogies/public`
- `family-detail.html` -> `GET /genealogy/app/genealogies/{genealogyId}`
4. 个人资料与反馈
- `profile.html`、`profile-data.html` -> `GET /genealogy/app/auth/profile`
- `profile-feedback.html`、`submit-ticket.html` -> `GET/POST /genealogy/app/feedback`
5. 拦截处理
- `public/js/page-effects.js` 当前会拦截登录、注册、创建家谱、个人中心页面并显示“功能待开发”。
- 对已接入接口的页面移除该拦截，保留未接入页面的提示。
## 验证计划
1. 新增共享 API 客户端测试，先确认测试失败，再实现通过。
2. 检查核心页面均加载共享脚本和页面脚本。
3. 用静态结构检查确认接口路径、表单字段、脚本引用存在。
4. 运行语法检查或 Node 烟测，确保 JS 可加载、核心方法可调用。
5. 检查新增样式是否位于 CSS 文件，不通过 JS 注入。
## 进度日志
- 2026-07-09 11:47:20 +08:00：已读取 `AGENTS.md`、项目目录、`APP.openapi.json`，确认项目是静态 HTML + jQuery/Layui，接口文档主要为 `/genealogy/app`。
- 2026-07-09 11:51:16 +08:00：用户确认按核心闭环方案执行，创建本规划与进度记录。
- 2026-07-09 11:52:53 +08:00：新增 `tests/api-client.test.js`，先运行 `node tests\api-client.test.js`，确认失败原因为缺少 `public/js/api-client.js`，进入共享 API 客户端实现。
- 2026-07-09 11:54:00 +08:00：用户补充要求：尽量不用 JS 注入样式，样式写在公共或页面 CSS 中并通过 class 查找；新增 HTML/JS/CSS 注释使用中文。
- 2026-07-09 11:57:19 +08:00：复查项目结构，确认 HTML 当前统一引用 `public/js`，`utils/DateUtil.js` 未被页面引用且存在乱码/语法风险；撤回过宽的 `api-pages.js` 方案，改为共享 `api-client.js` + 按模块/页面拆分脚本。
- 2026-07-09 11:59:22 +08:00：用户补充 CSS 架构要求：抽出可复用公共样式，每个页面 CSS 只写差异样式；将 CSS 结构整理加入接口接入前置约束。
- 2026-07-09 12:06:46 +08:00：完成认证模块第一步：新增 `public/js/auth-pages.js` 和 `tests/auth-pages.test.js`；`login.html`、`register.html`、`forgot-password.html` 改为真实表单；认证页公共 CSS 抽到 `public.css`，页面 CSS 只保留差异；重写 `page-effects.js`，移除“功能待开发”拦截和 JS 注入样式。
- 2026-07-09 12:10:54 +08:00：完成家谱核心第一步：新增 `public/js/genealogy-pages.js` 和 `tests/genealogy-pages.test.js`；`create-genealogy.html` 接入创建家谱接口；`plaza.html` 接入公开家谱列表；`profile-families.html` 接入我的家谱列表。验证：`node tests\api-client.test.js`、`node tests\auth-pages.test.js`、`node tests\genealogy-pages.test.js` 均通过；`node --check` 检查新增业务 JS 均通过；新增业务 JS 未发现 `createElement("style")` 或 `style.textContent` 注入样式。
- 2026-07-09 12:13:36 +08:00：用户补充可读性要求：现有该注释的位置补中文注释，代码不要压缩。执行范围限定为业务代码和本次维护的 CSS，第三方压缩库不改。
- 2026-07-09 12:16:27 +08:00：已给本次新增/重写业务代码补中文注释，覆盖 `api-client.js`、`auth-pages.js`、`genealogy-pages.js`、`page-effects.js` 和 `public.css` 的关键逻辑/样式区块；代码保持展开可读。验证：三组 Node 测试通过，四个业务 JS `node --check` 通过，业务 JS 未发现样式注入写法。
- 2026-07-09 12:23:36 +08:00：开始下一阶段：个人资料读取展示与反馈提交/历史反馈列表。范围：`profile.html`、`profile-data.html`、`profile-feedback.html`、`submit-ticket.html`；先写测试，再实现模块脚本和页面接入。
- 2026-07-09 12:28:30 +08:00：完成个人资料与反馈阶段：新增 `public/js/profile-pages.js`、`public/js/feedback-pages.js`、`tests/profile-pages.test.js`、`tests/feedback-pages.test.js`；`profile.html`、`profile-data.html` 接入当前用户资料读取展示；`profile-feedback.html`、`submit-ticket.html` 接入反馈提交，`profile-feedback.html` 接入历史反馈列表。验证：五组 Node 测试通过，六个业务 JS `node --check` 通过，业务 JS 未发现样式注入写法。
- 2026-07-09 12:31:51 +08:00：按用户要求重新验证第一阶段和第二阶段。第一阶段 API 客户端、认证页、家谱核心页测试均重新通过；第二阶段个人资料、反馈模块测试重新通过。复验命令包括 `node tests\api-client.test.js`、`node tests\auth-pages.test.js`、`node tests\genealogy-pages.test.js`、`node tests\profile-pages.test.js`、`node tests\feedback-pages.test.js`，以及六个业务脚本的 `node --check`。同时重新检查页面脚本引用、`data-*` 挂载点、业务 JS 样式注入写法和 `TODO/TBD/待实现/压缩` 标记，未发现异常。
- 2026-07-09 12:38:13 +08:00：继续推进家谱详情与加入申请阶段。`family-detail.html` 接入 `GET /genealogy/app/genealogies/{genealogyId}`，通过 `data-family-*` 挂载标题、简介、统计和家谱信息，并把“申请加入”链接带上家谱 ID；`join-genealogy.html` 改为真实申请表单，接入 `POST /genealogy/app/genealogies/{genealogyId}/join-applies`。新增/更新 `api-client.js` 和 `genealogy-pages.js` 中的申请加入、详情渲染、表单提交逻辑，并在对应 CSS 中补中文注释和页面差异样式。验证：五组 Node 测试全部通过，六个业务 JS `node --check` 全部通过，页面脚本引用与 `data-*` 挂载点检查通过，业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记。
- 2026-07-09 12:40:15 +08:00：根据接口 schema 补充 `joinMode` 枚举中文展示映射：`0` 显示为“关闭加入”、`1` 显示为“审核加入”、`2` 显示为“邀请码加入”，避免详情页直接显示数字。重新验证五组 Node 测试、六个业务 JS 语法检查、详情页/加入页挂载点、业务 JS 样式注入检查和核心文件遗留标记检查，结果均正常。
- 2026-07-09 12:45:24 +08:00：继续推进消息中心阶段。`profile-messages.html` 接入 `GET /genealogy/app/notifications`、`POST /genealogy/app/notifications/{notificationId}/read`、`POST /genealogy/app/notifications/read-all`，新增 `public/js/notification-pages.js` 负责消息列表渲染、单条已读、全部已读和刷新；`api-client.js` 新增通知相关封装；`profile-module.css` 增加按钮型模块卡片和未读消息样式，保持样式写入 CSS。验证：六组 Node 测试全部通过，七个业务 JS `node --check` 全部通过，消息页脚本引用和 `data-*` 挂载点检查通过，业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记。
- 2026-07-09 12:59:39 +08:00：按用户要求接入 `public/tac` 滑动验证到 `login.html`、`register.html`、`forgot-password.html`。依据 `APP.openapi.json` 的 `/captcha/require`、`/captcha/challenge`、`/captcha/verify` 字段实现 `public/js/captcha-pages.js` 适配层，将接口返回的 `captchaType/challengeId/payload` 转为 TAC 需要的 `type/id/backgroundImage/templateImage`，验证成功后把 `data.validToken` 写入当前表单隐藏字段；`auth-pages.js` 在登录、注册、发送短信验证码、重置密码前先执行滑动验证；`register.html` 原可见 `validToken` 输入改为昵称输入，避免和滑动验证隐藏字段冲突。三张认证页均引入 `public/tac/css/tac.css`、`public/tac/js/tac.min.js`、`public/js/captcha-pages.js`，并增加 `data-captcha-box` 挂载容器；`public.css` 增加认证页验证码容器样式。验证：七组 Node 测试全部通过，八个业务 JS `node --check` 全部通过，三张认证页 TAC 资源、隐藏 `validToken`、`data-captcha-box` 检查通过，自有业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记；`git diff --check` 因当前目录不是 git 仓库无法执行。
- 2026-07-09 13:07:18 +08:00：按用户提醒重新以 `APP.openapi.json` 为依据梳理剩余 `/genealogy/app` 页面归属，优先推进接口和页面最匹配的帮助中心。`help.html` 接入 `GET /genealogy/app/help-articles` 帮助文章列表，并在展开条目时按需调用 `GET /genealogy/app/help-articles/{helpId}` 补充详情；新增 `public/js/help-pages.js`，`api-client.js` 新增 `helpArticles`、`helpArticleDetail` 封装；`help.css` 补帮助列表加载状态注释和样式。验证：八组 Node 测试全部通过，九个业务 JS `node --check` 全部通过，帮助页 `data-help-list`、`api-client.js`、`help-pages.js` 引用检查通过，自有业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记。
- 2026-07-09 13:13:33 +08:00：继续按 `APP.openapi.json` 推进加入申请阶段。`profile-join-review.html` 接入 `GET /genealogy/app/genealogies/{genealogyId}/join-applies/pending` 待审核申请和 `PUT /genealogy/app/genealogies/{genealogyId}/join-applies/{applyId}/audit` 审核接口；`profile-join-family.html` 接入 `GET /genealogy/app/genealogies/join-applies/mine` 我的加入申请，并支持 `DELETE /genealogy/app/genealogies/join-applies/{applyId}` 撤销申请。新增 `public/js/join-apply-pages.js`，`api-client.js` 新增 `myJoinApplies`、`pendingJoinApplies`、`auditJoinApply`、`cancelJoinApply` 封装；`profile-module.css` 补加入申请行样式。验证：九组 Node 测试全部通过，十个业务 JS `node --check` 全部通过，两张页面脚本引用与 `data-join-apply-list` 挂载点检查通过，自有业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记。
- 2026-07-09 13:19:07 +08:00：继续按 `APP.openapi.json` 推进字辈谱阶段。`profile-generation.html` 接入 `GET /genealogy/app/genealogies/{genealogyId}/generation-poems` 查询字辈谱、`POST /genealogy/app/genealogies/{genealogyId}/generation-poems` 新增字辈、`PUT /genealogy/app/genealogies/{genealogyId}/generation-poems/{poemId}` 修改字辈；新增 `public/js/generation-pages.js`，`api-client.js` 新增 `generationPoems`、`createGenerationPoem`、`updateGenerationPoem` 封装；`profile-module.css` 补字辈谱行样式。本轮暂不接批量预览/批量保存接口，避免没有页面入口时过度实现。验证：十组 Node 测试全部通过，十一个业务 JS `node --check` 全部通过，字辈页 `data-generation-list`、`data-generation-add`、`generation-pages.js` 引用检查通过，自有业务 JS 未发现样式注入写法，核心文件未发现 `TODO/TBD/待实现/压缩` 标记。
- 2026-07-09 13:21:31 +08:00：根据用户提醒停止无编号推进，新增 `docs/api-page-integration-tracker-2026-07-09.md` 作为后续唯一编号规划与状态追踪表。后续每个模块必须先在追踪表中标记“进行中”，完成并验证后再标记“已完成”。
- 2026-07-09 13:33:41 +08:00：完成 API-011 世系树与人物管理。`profile-tree.html` 接入世系树、人物分页搜索、人物详情、新增成员和父母/配偶/子女快捷关系添加；`profile-family-home.html` 接入世系树预览和家谱主页摘要；新增 `public/js/lineage-pages.js`，`api-client.js` 新增 `lineageTree`、`lineagePersons`、`lineagePersonsPage`、`lineagePersonOptions`、`lineagePersonDetail`、`createLineagePerson`、`updateLineagePerson`、`deleteLineagePerson`、`addLineageRelation` 封装；`profile-module.css` 补世系列表、搜索栏和树结构样式。验证：全部 Node 测试通过，十二个业务 JS `node --check` 通过，两张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/lineage-pages.js` 未发现 `style` 样式注入片段。
- 2026-07-09 13:40:47 +08:00：完成 API-012 成员与家族管理。`profile-family-admin.html` 接入家谱概览和成员列表，支持成员权限更新和移除；`profile-admin-permissions.html` 接入成员选项、角色保存和所有者转让；`profile-invite.html`、`profile-share.html` 使用家谱概览生成邀请码/分享链接展示，不伪造接口文档中不存在的邀请生成接口。新增 `public/js/member-admin-pages.js`，`api-client.js` 新增 `genealogyOverview`、`genealogyMembers`、`genealogyMemberOptions`、`updateGenealogyMember`、`removeGenealogyMember`、`leaveGenealogy`、`transferGenealogyOwner` 封装；`profile-module.css` 补成员操作行样式。验证：全部 Node 测试通过，十三个业务 JS `node --check` 通过，四张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/member-admin-pages.js` 未发现 `style` 样式注入片段。
- 2026-07-09 13:46:31 +08:00：完成 API-014 谱文与内容文章。`profile-article.html` 接入谱文列表；`profile-article-edit.html` 接入分类列表、谱文新增和修改；`article-detail.html` 接入谱文详情；`profile-content.html` 的最近内容先接谱文列表，其他内容类型按后续编号继续接。新增 `public/js/article-pages.js`，`api-client.js` 新增 `articleCategories`、`articles`、`articleDetail`、`createArticle`、`updateArticle` 封装；`profile-module.css` 补谱文行样式。验证：全部 Node 测试通过，十四个业务 JS `node --check` 通过，四张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/article-pages.js` 未发现 `style` 样式注入片段。
- 2026-07-09 13:52:03 +08:00：完成 API-013 家族圈动态。`profile-feed.html` 接入动态分页列表、点赞和评论；`profile-feed-edit.html` 接入动态发布和修改。新增 `public/js/feed-pages.js`，`api-client.js` 新增 `feeds`、`feedsPage`、`feedDetail`、`createFeed`、`updateFeed`、`likeFeed`、`unlikeFeed`、`feedComments`、`feedCommentsPage`、`createFeedComment`、`deleteFeedComment` 封装；`profile-module.css` 补动态行样式。验证：全部 Node 测试通过，十五个业务 JS `node --check` 通过，两张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/feed-pages.js` 未发现 `style` 样式注入片段。
- 2026-07-09 13:57:31 +08:00：完成 API-015 相册照片。`profile-album.html` 接入相册列表、新增/修改相册、照片列表和新增照片；`promo-album.html` 复用相册列表做宣传相册展示。新增 `public/js/album-pages.js`，`api-client.js` 新增 `albums`、`createAlbum`、`updateAlbum`、`albumPhotos`、`createAlbumPhoto` 封装；`profile-module.css` 补相册和照片行样式。验证：全部 Node 测试通过，十六个业务 JS `node --check` 通过，两张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/album-pages.js` 未发现 `style` 样式注入片段。
- 2026-07-09 14:04:52 +08:00：完成 API-019 文件上传公共能力。`api-client.js` 接入单文件上传、文件引用绑定/释放、分片初始化、分片上传、分片完成接口；新增 `public/js/upload-pages.js` 统一处理文件选择、上传、OSS ID 回填和上传状态展示；`profile-article-edit.html` 接入谱文封面上传，`profile-feed-edit.html` 接入动态图片上传，`profile-album.html` 接入相册封面和照片上传；`profile-module.css` 补上传控件样式。验证：全部 Node 测试通过，十七个业务 JS `node --check` 通过，上传控件挂载点检查通过，`public/js/api-client.js` 和 `public/js/upload-pages.js` 未发现样式注入片段。
- 2026-07-09 14:12:27 +08:00：完成 API-016 祭祀、献礼与功德记录。`profile-gift.html` 接入祭祀/贺礼列表、献礼列表和新增献礼；`profile-gift-edit.html` 接入贺礼创建/修改和封面上传；`profile-merit.html` 接入功德记录列表；`profile-merit-edit.html` 接入新增功德记录。新增 `public/js/ceremony-pages.js`，`api-client.js` 新增 `ceremonies`、`ceremonyDetail`、`createCeremony`、`updateCeremony`、`ceremonyGifts`、`createCeremonyGift`、`meritRecords`、`createMeritRecord` 封装；`profile-module.css` 补贺礼、献礼和功德记录行样式。验证：全部 Node 测试通过，十八个业务 JS `node --check` 通过，四张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/ceremony-pages.js` 未发现样式注入片段。
- 2026-07-09 14:18:15 +08:00：完成 API-017 成长记录。`profile-growth.html` 接入成长记录列表；`profile-growth-edit.html` 接入成长记录新增/修改和附件上传。新增 `public/js/growth-pages.js`，`api-client.js` 新增 `growthRecords`、`growthRecordDetail`、`createGrowthRecord`、`updateGrowthRecord` 封装；`profile-module.css` 补成长记录行样式。验证：全部 Node 测试通过，十九个业务 JS `node --check` 通过，两张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/growth-pages.js` 未发现样式注入片段。
- 2026-07-09 14:24:10 +08:00：完成 API-018 备忘录。`profile-memo.html` 接入备忘录列表；`profile-memo-edit.html` 接入备忘录新增/修改和附件上传。新增 `public/js/memo-pages.js`，`api-client.js` 新增 `memos`、`memoDetail`、`createMemo`、`updateMemo` 封装；`profile-module.css` 补备忘录行样式。验证：全部 Node 测试通过，二十个业务 JS `node --check` 通过，两张页面脚本引用与 `data-*` 挂载点检查通过，`public/js/api-client.js` 和 `public/js/memo-pages.js` 未发现样式注入片段。
- 2026-07-09 14:31:29 +08:00：完成 API-020 会员套餐与订单创建。`profile-services.html` 接入会员套餐列表、会员订单创建表单和会员订单列表；新增 `public/js/vip-pages.js`，`api-client.js` 新增 `vipPackages`、`vipOrders`、`createVipOrder` 封装，`profile-module.css` 补会员套餐卡片和订单行样式。验证：`node tests\vip-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、会员页挂载点/字段检查均通过；API-020 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 14:37:25 +08:00：完成 API-021 推广/公告类内容。`app.html` 接入应用推广列表，`download.html` 接入下载推广入口，`notice-detail.html` 从 `/genealogy/app/promotions` 列表按 `id` 选择公告详情，未伪造接口文档不存在的详情接口。新增 `public/js/promotion-pages.js`，`api-client.js` 新增 `promotions` 封装，`app.css` 补推广卡片样式。验证：`node tests\promotion-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、三张页面推广挂载点检查均通过；API-021 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 14:42:47 +08:00：完成 API-022 账号安全。`profile-security.html` 接入修改密码、换绑手机号、短信登录校验、退出登录和账号注销表单；新增 `public/js/security-pages.js`，`api-client.js` 新增 `changePassword`、`changePhone`、`smsLogin`、`logout`、`deactivateAccount` 封装，`profile-module.css` 补安全表单和危险操作样式。验证：`node tests\security-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、账号安全页挂载点检查均通过；API-022 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 14:49:54 +08:00：完成 API-023 地区选择公共能力。`create-genealogy.html` 接入省/市/区选择器并回填 `regionCode`，`profile-data.html` 接入个人资料省市区更新表单；新增 `public/js/region-pages.js`，`api-client.js` 新增 `regionChildren`、`regionPath`、`regionSearch`、`regionDetail` 封装，`genealogy-pages.js` 去掉 `regionCode=000000` 兜底并改为提交前校验真实地区编码，两个 CSS 文件补地区选择器样式。验证：`node tests\region-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、两张页面地区挂载点检查均通过；API-023 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 14:50:47 +08:00：复查 API-024/API-025。`surname.html`、`surname-detail.html`、`search-result.html`、`genealogy.html`、`culture.html`、`about.html`、`index.html` 未发现明确同名接口，公开家谱接口也不支持搜索参数，因此标记暂缓；`profile-video.html`、`promo-video.html`、`profile-data-reminders.html` 暂无视频/资料提醒独立接口，标记暂缓；`profile-create-family.html` 可复用创建家谱能力，单独规划为 API-026。
- 2026-07-09 14:53:50 +08:00：完成 API-026 个人中心创建家谱页。`profile-create-family.html` 改为真实创建家谱表单，接入 `api-client.js`、`region-pages.js`、`genealogy-pages.js`，复用 `/genealogy/app/genealogies` 和地区选择公共能力；`profile-module.css` 补个人中心创建表单样式，`tests/genealogy-pages.test.js` 补真实 `regionCode` 断言。验证：`node tests\genealogy-pages.test.js`、`node tests\region-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、页面挂载点检查均通过；API-026 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 15:03:27 +08:00：完成 API-027 个人资料编辑提交。`profile-data.html` 增加真实个人资料编辑表单，`profile-pages.js` 增加 `ProfileUpdateBody` 构造、表单填充和 `PUT /genealogy/app/auth/profile` 提交，`profile-module.css` 补本页表单状态样式，`tests/profile-pages.test.js` 和 `tests/api-client.test.js` 补转换与接口契约测试。验证：先观察 `node tests\profile-pages.test.js` 因缺少 `buildProfileUpdateBody` 失败；实现后 `node tests\profile-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、页面挂载点检查均通过，未发现样式注入片段和 TODO 类占位；`git diff --check` 因当前目录不是 Git 仓库无法执行。
- 2026-07-09 15:11:37 +08:00：完成 API-028 字辈批量预览与批量保存。`profile-generation.html` 增加批量字辈表单和预览区域，`api-client.js` 增加 `previewGenerationPoems`、`saveGenerationPoemsBatch`，`generation-pages.js` 增加 `GenerationPoemBatchBody` 构造、预览渲染和保存动作，`profile-module.css` 补批量面板样式，`tests/generation-pages.test.js` 和 `tests/api-client.test.js` 补批量接口测试。验证：先观察 `node tests\generation-pages.test.js` 因缺少 `buildGenerationBatchBody` 失败、`node tests\api-client.test.js` 因缺少 `previewGenerationPoems` 失败；实现后 `node tests\generation-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、页面挂载点检查均通过，未发现样式注入片段和 TODO 类占位；`git diff --check` 因当前目录不是 Git 仓库无法执行。
docs/api-page-integration-tracker-2026-07-09.md
+114
View File
@@ -0,0 +1,114 @@
# 接口对接编号规划与状态追踪
创建时间：2026-07-09 13:21:31 +08:00
流程修正时间：2026-07-09 13:21:31 +08:00
接口依据：`APP.openapi.json`
主进度记录：`docs/api-page-integration-2026-07-09.md`
## 执行规则
1. 后续不再无编号推进，所有接口对接必须先进入本追踪表。
2. 每一项开始前，先把状态从“待开始”改为“进行中”，并记录开始时间。
3. 每一项完成后，必须记录完成时间、修改文件、接口路径、验证命令或静态检查结果。
4. 每一项验证通过后，才能把状态改为“已完成”。
5. 若接口文档没有明确对应接口，状态标记为“待确认”或“暂缓”，不强行接入。
6. 样式继续遵守公共 `public.css` + 页面 CSS 的结构，业务 JS 不注入样式。
7. 新增或修改的 HTML、JS、CSS 注释使用中文，代码保持可读、不压缩。
## 状态说明
- 已完成：已按接口文档接入，并完成对应验证。
- 进行中：当前正在推进，未完成前不能开始下一个无关模块。
- 待开始：已规划，尚未改代码。
- 待确认：页面存在，但接口归属需要进一步确认。
- 暂缓：接口或页面入口不足，暂不实现，避免过度开发。
## 已完成回填
| 编号 | 状态 | 页面范围 | 接口范围 | 完成记录 |
| --- | --- | --- | --- | --- |
| API-000 | 已完成 | 全项目 | `APP.openapi.json`、`AGENTS.md`、项目结构 | 2026-07-09 11:47:20 +08:00 已读取约束、接口文档和目录结构。 |
| API-001 | 已完成 | 全项目公共请求 | 共享请求客户端、认证头、租户头、Token 存取 | 2026-07-09 11:52:53 +08:00 至 12:16:27 +08:00 完成 `public/js/api-client.js` 与测试。 |
| API-002 | 已完成 | `login.html`、`register.html`、`forgot-password.html` | `/genealogy/app/auth/login`、`/genealogy/app/auth/register`、`/genealogy/app/auth/sms/code`、`/genealogy/app/auth/password/reset`、`/captcha/require`、`/captcha/challenge`、`/captcha/verify` | 2026-07-09 12:06:46 +08:00 完成认证页；2026-07-09 12:59:39 +08:00 完成 TAC 滑动验证接入。 |
| API-003 | 已完成 | `create-genealogy.html`、`plaza.html`、`profile-families.html` | `/genealogy/app/genealogies`、`/genealogy/app/genealogies/public`、`/genealogy/app/genealogies/mine` | 2026-07-09 12:10:54 +08:00 完成创建家谱、公开家谱、我的家谱列表。 |
| API-004 | 已完成 | `family-detail.html`、`join-genealogy.html` | `/genealogy/app/genealogies/{genealogyId}`、`/genealogy/app/genealogies/{genealogyId}/join-applies` | 2026-07-09 12:38:13 +08:00 完成家谱详情与申请加入；2026-07-09 12:40:15 +08:00 补 `joinMode` 展示映射。 |
| API-005 | 已完成 | `profile.html`、`profile-data.html` | `/genealogy/app/auth/profile` | 2026-07-09 12:28:30 +08:00 完成个人资料读取展示。 |
| API-006 | 已完成 | `profile-feedback.html`、`submit-ticket.html` | `/genealogy/app/feedback` | 2026-07-09 12:28:30 +08:00 完成反馈提交与历史反馈。 |
| API-007 | 已完成 | `profile-messages.html` | `/genealogy/app/notifications`、`/genealogy/app/notifications/{notificationId}/read`、`/genealogy/app/notifications/read-all` | 2026-07-09 12:45:24 +08:00 完成消息中心。 |
| API-008 | 已完成 | `help.html` | `/genealogy/app/help-articles`、`/genealogy/app/help-articles/{helpId}` | 2026-07-09 13:07:18 +08:00 完成帮助中心。 |
| API-009 | 已完成 | `profile-join-review.html`、`profile-join-family.html` | `/genealogy/app/genealogies/{genealogyId}/join-applies/pending`、`/genealogy/app/genealogies/{genealogyId}/join-applies/{applyId}/audit`、`/genealogy/app/genealogies/join-applies/mine`、`/genealogy/app/genealogies/join-applies/{applyId}` | 2026-07-09 13:13:33 +08:00 完成入谱申请审核与我的申请。 |
| API-010 | 已完成 | `profile-generation.html` | `/genealogy/app/genealogies/{genealogyId}/generation-poems`、`/genealogy/app/genealogies/{genealogyId}/generation-poems/{poemId}` | 2026-07-09 13:19:07 +08:00 完成字辈谱查询、新增、修改；批量接口因页面无入口暂缓。 |
## 后续编号规划
| 编号 | 状态 | 页面范围 | 接口范围 | 计划与验证 |
| --- | --- | --- | --- | --- |
| API-011 | 已完成 | `profile-tree.html`、`profile-family-home.html` | `/genealogy/app/genealogies/{genealogyId}/lineage/tree`、`/genealogy/app/genealogies/{genealogyId}/lineage/persons`、`/genealogy/app/genealogies/{genealogyId}/lineage/persons/page`、`/genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}`、`/genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children`、`/parents`、`/siblings`、`/spouses` | 2026-07-09 13:25:03 +08:00 开始；2026-07-09 13:33:41 +08:00 完成。新增 `public/js/lineage-pages.js`、`tests/lineage-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、`profile-tree.html`、`profile-family-home.html`、`public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-011 自有 JS 未发现样式注入片段。 |
| API-012 | 已完成 | `profile-family-admin.html`、`profile-admin-permissions.html`、`profile-invite.html`、`profile-share.html` | `/genealogy/app/genealogies/{genealogyId}/members`、`/genealogy/app/genealogies/{genealogyId}/members/{memberId}`、`/genealogy/app/genealogies/{genealogyId}/members/me`、`/genealogy/app/genealogies/{genealogyId}/members/options`、`/genealogy/app/genealogies/{genealogyId}/members/owner-transfer`、`/genealogy/app/genealogies/{genealogyId}/overview` | 2026-07-09 13:34:36 +08:00 开始；2026-07-09 13:40:47 +08:00 完成。新增 `public/js/member-admin-pages.js`、`tests/member-admin-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、四张成员/邀请页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-012 自有 JS 未发现样式注入片段。 |
| API-013 | 已完成 | `profile-feed.html`、`profile-feed-edit.html` | `/genealogy/app/genealogies/{genealogyId}/feeds`、`/genealogy/app/genealogies/{genealogyId}/feeds/page`、`/genealogy/app/genealogies/{genealogyId}/feeds/{feedId}`、`/genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/likes`、评论接口 | 2026-07-09 13:47:29 +08:00 开始；2026-07-09 13:52:03 +08:00 完成。新增 `public/js/feed-pages.js`、`tests/feed-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、两张动态页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-013 自有 JS 未发现样式注入片段。 |
| API-014 | 已完成 | `profile-article.html`、`profile-article-edit.html`、`article-detail.html`、`profile-content.html` | `/genealogy/app/genealogies/{genealogyId}/article-categories`、`/genealogy/app/genealogies/{genealogyId}/articles`、`/genealogy/app/genealogies/{genealogyId}/articles/{articleId}` | 2026-07-09 13:41:44 +08:00 开始；2026-07-09 13:46:31 +08:00 完成。新增 `public/js/article-pages.js`、`tests/article-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、四张谱文/内容页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-014 自有 JS 未发现样式注入片段。 |
| API-015 | 已完成 | `profile-album.html`、`promo-album.html` | `/genealogy/app/genealogies/{genealogyId}/albums`、`/genealogy/app/genealogies/{genealogyId}/albums/{albumId}`、`/genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos` | 2026-07-09 13:52:58 +08:00 开始；2026-07-09 13:57:31 +08:00 完成。新增 `public/js/album-pages.js`、`tests/album-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、两张相册页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-015 自有 JS 未发现样式注入片段。 |
| API-016 | 已完成 | `profile-gift.html`、`profile-gift-edit.html`、`profile-merit.html`、`profile-merit-edit.html` | `/genealogy/app/genealogies/{genealogyId}/ceremonies`、`/genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}`、`/genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts`、`/genealogy/app/genealogies/{genealogyId}/merit-records` | 2026-07-09 14:05:57 +08:00 开始；2026-07-09 14:12:27 +08:00 完成。新增 `public/js/ceremony-pages.js`、`tests/ceremony-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、四张贺礼/功德页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-016 自有 JS 未发现样式注入片段。 |
| API-017 | 已完成 | `profile-growth.html`、`profile-growth-edit.html` | `/genealogy/app/genealogies/{genealogyId}/growth-records`、`/genealogy/app/genealogies/{genealogyId}/growth-records/{recordId}` | 2026-07-09 14:13:25 +08:00 开始；2026-07-09 14:18:15 +08:00 完成。新增 `public/js/growth-pages.js`、`tests/growth-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、两张成长记录页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-017 自有 JS 未发现样式注入片段。 |
| API-018 | 已完成 | `profile-memo.html`、`profile-memo-edit.html` | `/genealogy/app/genealogies/{genealogyId}/memos`、`/genealogy/app/genealogies/{genealogyId}/memos/{memoId}` | 2026-07-09 14:19:26 +08:00 开始；2026-07-09 14:24:10 +08:00 完成。新增 `public/js/memo-pages.js`、`tests/memo-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、两张备忘录页面和 `public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面挂载点检查通过，API-018 自有 JS 未发现样式注入片段。 |
| API-019 | 已完成 | 文章、动态、相册、成长记录等需要上传的页面 | `/genealogy/app/files/upload`、`/genealogy/app/files/reference`、`/genealogy/app/files/resumable/init`、`/genealogy/app/files/resumable/chunk`、`/genealogy/app/files/resumable/complete` | 2026-07-09 14:00:01 +08:00 开始；2026-07-09 14:04:52 +08:00 完成。新增 `public/js/upload-pages.js`、`tests/upload-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、`profile-article-edit.html`、`profile-feed-edit.html`、`profile-album.html`、`public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，上传控件挂载点检查通过，API-019 自有 JS 未发现样式注入片段。 |
| API-020 | 已完成 | `profile-services.html` | `/genealogy/app/vip/packages`、`/genealogy/app/vip/orders` | 2026-07-09 14:26:34 +08:00 开始；2026-07-09 14:31:29 +08:00 完成。新增 `public/js/vip-pages.js`、`tests/vip-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、`profile-services.html`、`public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，会员页挂载点和表单字段检查通过，API-020 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-021 | 已完成 | `app.html`、`download.html`、`notice-detail.html` | `/genealogy/app/promotions` | 2026-07-09 14:33:01 +08:00 开始；2026-07-09 14:37:25 +08:00 完成。新增 `public/js/promotion-pages.js`、`tests/promotion-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、`app.html`、`download.html`、`notice-detail.html`、`public/css/app.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，三张页面推广挂载点检查通过，API-021 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-022 | 已完成 | `profile-security.html` | `/genealogy/app/auth/password`、`/genealogy/app/auth/phone`、`/genealogy/app/auth/account/deactivate`、`/genealogy/app/auth/logout`、`/genealogy/app/auth/login/sms` | 2026-07-09 14:38:22 +08:00 开始；2026-07-09 14:42:47 +08:00 完成。新增 `public/js/security-pages.js`、`tests/security-pages.test.js`；更新 `public/js/api-client.js`、`tests/api-client.test.js`、`profile-security.html`、`public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，账号安全页表单挂载点检查通过，API-022 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-023 | 已完成 | `create-genealogy.html`、`profile-data.html`、涉及地区选择的编辑页 | `/genealogy/region/children`、`/genealogy/region/search`、`/genealogy/region/{regionCode}`、`/genealogy/region/path/{regionCode}` | 2026-07-09 14:44:43 +08:00 开始；2026-07-09 14:49:54 +08:00 完成。新增 `public/js/region-pages.js`、`tests/region-pages.test.js`；更新 `public/js/api-client.js`、`public/js/genealogy-pages.js`、`tests/api-client.test.js`、`tests/genealogy-pages.test.js`、`create-genealogy.html`、`profile-data.html`、`public/css/create-genealogy.css`、`public/css/profile-module.css`。验证：全部 Node 测试通过，业务 JS 语法检查通过，两张页面地区选择挂载点检查通过，API-023 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-024 | 暂缓 | `surname.html`、`surname-detail.html`、`search-result.html`、`genealogy.html`、`culture.html`、`about.html`、`index.html` | 当前接口文档未发现明确同名业务接口 | 2026-07-09 14:50:47 +08:00 复查。公开家谱接口不支持搜索参数，文章接口依赖 `genealogyId`，推广接口只有列表，不强行映射为姓氏百科或全站搜索。 |
| API-025 | 暂缓 | `profile-video.html`、`promo-video.html`、`profile-data-reminders.html` | 当前接口文档未发现明确视频、资料提醒独立接口 | 2026-07-09 14:50:47 +08:00 复查。视频和资料提醒没有独立接口，暂不伪造接口；`profile-create-family.html` 归入新增 API-026。 |
| API-026 | 已完成 | `profile-create-family.html` | `/genealogy/app/genealogies`、`/genealogy/region/children` | 2026-07-09 14:51:39 +08:00 开始；2026-07-09 14:53:50 +08:00 完成。更新 `profile-create-family.html`、`public/css/profile-module.css`、`tests/genealogy-pages.test.js`，复用 `public/js/api-client.js`、`public/js/region-pages.js`、`public/js/genealogy-pages.js`。验证：全部 Node 测试通过，业务 JS 语法检查通过，页面创建表单和地区选择挂载点检查通过，API-026 自有 JS 未发现样式注入片段；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-027 | 已完成 | `profile-data.html` | `/genealogy/app/auth/profile` | 2026-07-09 14:57:51 +08:00 开始；2026-07-09 15:03:27 +08:00 完成。更新 `profile-data.html`、`public/js/profile-pages.js`、`public/css/profile-module.css`、`tests/profile-pages.test.js`、`tests/api-client.test.js`。补齐个人资料编辑提交，字段对应 `ProfileUpdateBody`：`nickName`、`avatarOssId`、`sex`、`birthday`；地区字段继续沿用 API-023。验证：已观察 `node tests\profile-pages.test.js` 因缺少 `buildProfileUpdateBody` 失败；实现后 `node tests\profile-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、页面挂载点检查均通过；未发现样式注入片段和 TODO 类占位；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-028 | 已完成 | `profile-generation.html` | `/genealogy/app/genealogies/{genealogyId}/generation-poems/batch/preview`、`/genealogy/app/genealogies/{genealogyId}/generation-poems/batch/save` | 2026-07-09 15:05:58 +08:00 开始；2026-07-09 15:11:37 +08:00 完成。更新 `profile-generation.html`、`public/js/api-client.js`、`public/js/generation-pages.js`、`public/css/profile-module.css`、`tests/generation-pages.test.js`、`tests/api-client.test.js`。补齐字辈批量预览和批量保存，字段对应 `GenerationPoemBatchBody`：`content`、`stopMissingOldGeneration`。验证：已观察 `node tests\generation-pages.test.js` 因缺少 `buildGenerationBatchBody` 失败，`node tests\api-client.test.js` 因缺少 `previewGenerationPoems` 失败；实现后 `node tests\generation-pages.test.js`、`node tests\api-client.test.js`、全部 `tests/*.test.js`、业务 JS `node --check`、页面挂载点检查均通过；未发现样式注入片段和 TODO 类占位；`git diff --check` 因当前目录不是 Git 仓库无法执行。 |
| API-029 | 已中止 | `profile-services.html` | `/genealogy/app/genealogies/options` | 2026-07-09 15:13:03 +08:00 开始；2026-07-09 15:14:58 +08:00 中止。原因：用户确认此前依据的 `APP.openapi.json` 不是 PC 接口文档，PC/H5 应改用 `genealogy-pc-openapi.yaml`，且接口地址使用 `https://test-genealogy-api.ddxcjp.cn`。本项不再继续按 APP 接口推进。 |
## 下一步执行顺序
1. API-011：世系树与人物管理。
2. API-012：成员与家族管理。
3. API-014：谱文与内容文章。
4. API-013：家族圈动态。
5. API-015：相册照片。
6. API-019：上传公共能力。
7. API-016 至 API-023：按页面入口完整度继续推进。
8. API-024、API-025：只在确认接口归属后推进。
## 本次流程修正记录
- 2026-07-09 13:21:31 +08:00：收到用户提醒，停止继续无编号推进；补充本编号追踪表，并要求后续每项先标记状态再实现，完成后再标记已完成。
- 2026-07-09 14:26:34 +08:00：开始执行 API-020，状态从“待开始”改为“进行中”。
- 2026-07-09 14:31:29 +08:00：API-020 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:33:01 +08:00：开始执行 API-021，状态从“待开始”改为“进行中”。
- 2026-07-09 14:37:25 +08:00：API-021 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:38:22 +08:00：开始执行 API-022，状态从“待开始”改为“进行中”。
- 2026-07-09 14:42:47 +08:00：API-022 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:44:43 +08:00：开始执行 API-023，状态从“待开始”改为“进行中”。
- 2026-07-09 14:49:54 +08:00：API-023 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:50:47 +08:00：复查 API-024/API-025，缺少明确接口的页面标记为“暂缓”，将 `profile-create-family.html` 单独规划为 API-026。
- 2026-07-09 14:51:39 +08:00：开始执行 API-026，状态从“待开始”改为“进行中”。
- 2026-07-09 14:53:50 +08:00：API-026 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:57:51 +08:00：开始执行 API-027，状态标记为“进行中”；按接口文档把 `profile-data.html` 的个人资料更新归到 `/genealogy/app/auth/profile` PUT，先写测试再实现。
- 2026-07-09 15:03:27 +08:00：API-027 执行完成，状态从“进行中”改为“已完成”；完成个人资料编辑表单、提交逻辑、页面样式和测试验证。
- 2026-07-09 15:05:58 +08:00：开始执行 API-028，状态标记为“进行中”；按接口文档把 `profile-generation.html` 的批量字辈能力归到 `/generation-poems/batch/preview` 和 `/generation-poems/batch/save`。
- 2026-07-09 15:11:37 +08:00：API-028 执行完成，状态从“进行中”改为“已完成”；完成批量字辈预览、批量保存、页面入口、样式和测试验证。
- 2026-07-09 15:13:03 +08:00：开始执行 API-029，状态标记为“进行中”；把 `profile-services.html` 的家谱选择归到 `/genealogy/app/genealogies/options`。
- 2026-07-09 15:14:58 +08:00：收到用户纠正，确认旧依据 `APP.openapi.json` 不适合作为 PC 页面接口文档；中止 API-029，后续改以 `genealogy-pc-openapi.yaml` 和 `https://test-genealogy-api.ddxcjp.cn` 重新规划。
- 2026-07-09 13:25:03 +08:00：开始执行 API-011，状态从“待开始”改为“进行中”。
- 2026-07-09 13:33:41 +08:00：API-011 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 13:34:36 +08:00：开始执行 API-012，状态从“待开始”改为“进行中”。
- 2026-07-09 13:40:47 +08:00：API-012 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 13:41:44 +08:00：开始执行 API-014，状态从“待开始”改为“进行中”。
- 2026-07-09 13:46:31 +08:00：API-014 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 13:47:29 +08:00：开始执行 API-013，状态从“待开始”改为“进行中”。
- 2026-07-09 13:52:03 +08:00：API-013 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 13:52:58 +08:00：开始执行 API-015，状态从“待开始”改为“进行中”。
- 2026-07-09 13:57:31 +08:00：API-015 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:00:01 +08:00：开始执行 API-019，状态从“待开始”改为“进行中”。
- 2026-07-09 14:04:52 +08:00：API-019 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:05:57 +08:00：开始执行 API-016，状态从“待开始”改为“进行中”。
- 2026-07-09 14:12:27 +08:00：API-016 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:13:25 +08:00：开始执行 API-017，状态从“待开始”改为“进行中”。
- 2026-07-09 14:18:15 +08:00：API-017 执行完成，状态从“进行中”改为“已完成”。
- 2026-07-09 14:19:26 +08:00：开始执行 API-018，状态从“待开始”改为“进行中”。
- 2026-07-09 14:24:10 +08:00：API-018 执行完成，状态从“进行中”改为“已完成”。
docs/pc-api-page-integration-tracker-2026-07-09.md
+134
View File
@@ -0,0 +1,134 @@
# 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 `clientid` 为 `ced7e5f0498645c6ec642dcf450b036f`，客户端 Key 为 `web_pc`。
4. `components.tags` 和 `components.schemas/requestBodies` 中出现家谱、动态、世系、字辈等业务模型，但 `paths` 没有对应接口路径；实现时不能把这些 schema 当成可调用 PC 接口。
5. 验证码 schema 示例里仍出现 `APP_LOGIN`、`PC_LOGIN` 等文本示例；实际页面场景以后台配置为准，当前明确可用的 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 页面使用。
- `APP_LOGIN`、`APP_REGISTER`、`APP_PHONE_CHANGE`、`APP_FORGOT_PASSWORD`、`APP_SMS_CODE`、`APP_ACCOUNT_DEACTIVATE` 的客户端 Key 为 `app`，不能继续作为 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.data.trackList`。
8. 验证成功后从返回 `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 | Sort-Object Name | ForEach-Object { node $_.FullName }` 全部通过；`Select-String -Path public\js\api-client.js -Pattern '/genealogy/app/'` 无输出。 |
| 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`，这是后端/隧道可用性问题，不是本次提示和样式改动导致。
- 执行计划：
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 测试通过。
docs/superpowers/plans/2026-07-09-auth-layer-message.md
+128
View File
@@ -0,0 +1,128 @@
# Auth Layer Message Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 让登录、注册、忘记密码三页的提示统一使用 layui `layer.msg`，不再出现浏览器原生 alert，并补好认证页提示和 TAC 弹窗样式。
**Architecture:** 页面加载 `public/layui/css/layui.css` 和 `public/layui/layui.js`；`auth-pages.js` 与 `captcha-pages.js` 只负责调用提示，不写样式；提示皮肤与 TAC 弹窗样式写入 `public/css/public.css`。
**Tech Stack:** 原生 HTML/CSS/JavaScript、layui layer、public/tac、Node 断言测试。
## Global Constraints
- 计划开始时间：2026-07-09 17:14:08 +08:00。
- 只处理登录、注册、忘记密码三页的提示与弹窗样式问题。
- 不修改 `public/tac/js/tac.min.js`。
- 不使用 HTML 原生 `alert` 作为用户提示。
- 样式写在 CSS 文件里，JS 只切 class 或调用组件。
- 新增或修改的 HTML、CSS、JS 注释使用中文，代码保持可读。
---
### Task 1: 补充失败测试
**Files:**
- Modify: `tests/auth-page-structure.test.js`
- Create: `tests/auth-message.test.js`
**Interfaces:**
- Consumes: 当前三页 HTML 与认证脚本。
- Produces: 能捕获缺少 layui 和原生 alert 兜底的测试。
- [x] **Step 1: 添加页面结构断言**
检查 `login.html`、`register.html`、`forgot-password.html` 必须加载 `public/layui/css/layui.css` 和 `public/layui/layui.js`，且 `layui.js` 在 `auth-pages.js` 前面。
- [x] **Step 2: 添加提示脚本断言**
检查 `public/js/auth-pages.js` 与 `public/js/captcha-pages.js` 不再包含 `root.alert`，并检查 `public/css/public.css` 提供 `.auth-layer-message`。
- [x] **Step 3: 验证红灯**
运行：
```powershell
node tests\auth-page-structure.test.js
node tests\auth-message.test.js
```
预期：两个测试均失败，分别提示缺少 layui 和仍存在 `root.alert`。
### Task 2: 接入 layui 并替换原生提示
**Files:**
- Modify: `login.html`
- Modify: `register.html`
- Modify: `forgot-password.html`
- Modify: `public/js/auth-pages.js`
- Modify: `public/js/captcha-pages.js`
**Interfaces:**
- Consumes: `layui.layer.msg(message, options)`。
- Produces: `showMessage(message)` 统一使用 layer，缺少 layui 时只输出控制台警告，不再弹原生 alert。
- [x] **Step 1: 三页加载 layui 样式和脚本**
在三页 `<head>` 中加入 `public/layui/css/layui.css`，在 `auth-pages.js` 前加入 `public/layui/layui.js`。
- [x] **Step 2: 修改认证脚本提示**
把 `auth-pages.js` 的 `showMessage` 改为优先调用 `layui.layer.msg(message, { skin: 'auth-layer-message' })`，没有 layui 时使用 `console.warn`。
- [x] **Step 3: 修改验证码脚本提示**
把 `captcha-pages.js` 的 `showMessage` 同步改为同样的 layer 提示策略。
### Task 3: 补齐公共样式
**Files:**
- Modify: `public/css/public.css`
**Interfaces:**
- Consumes: layui layer 生成的 `.auth-layer-message`。
- Produces: 认证页统一提示皮肤和移动端更稳的 TAC 弹窗尺寸。
- [x] **Step 1: 添加 layui 消息皮肤**
在公共 CSS 中添加 `.auth-layer-message`，控制圆角、背景、文字和阴影。
- [x] **Step 2: 微调 TAC 弹窗移动端尺寸**
继续使用 `.auth-captcha-modal` 页面级挂载，限制 TAC 宽度不超过视口，避免盖层内容顶到边缘。
### Task 4: 验证并记录完成
**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
**Interfaces:**
- Consumes: Task 1-3 的实现结果。
- Produces: PC-012 完成记录。
- [x] **Step 1: 跑焦点测试**
运行：
```powershell
node tests\auth-page-structure.test.js
node tests\auth-message.test.js
```
预期：全部通过。
- [x] **Step 2: 跑相关测试和语法检查**
运行：
```powershell
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
```
预期：全部通过。
- [x] **Step 3: 更新追踪记录**
把 PC-012 标记为已完成，写入完成时间、修改文件、验证命令和剩余风险。
docs/superpowers/plans/2026-07-09-pc-api-replan.md
+762
View File
@@ -0,0 +1,762 @@
# PC API Replan 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:** 按最新 `genealogy-pc-openapi.yaml` 重新整理 PC/H5 页面接口对接，只接入 `paths` 中真实存在的验证码、PC 认证、PC 文件和行政区划接口，并清除旧 APP 路径作为 PC 合同的风险。
**Architecture:** 根目录 `config.js` 是接口基础地址、客户端 ID、租户、token key 的唯一配置入口；`utils` 只放跨页面公共 JS；`public/js/api-client.js` 只暴露 PC YAML `paths` 中存在的接口和受控的“PC 接口未提供”错误。页面业务 JS 继续放在 `public/js`，页面只能调用 PC 已确认方法；PC YAML 未覆盖的页面保留静态/本地展示或显示接口待确认状态。
**Tech Stack:** 静态 HTML、原生 JS、jQuery/Layui、Node 测试脚本、`public/tac` 天爱验证码静态资源。
## Global Constraints
- 接口依据只使用 `genealogy-pc-openapi.yaml` 的 `paths`。
- 开发环境接口基础地址固定为 `https://test-genealogy-api.ddxcjp.cn`。
- PC 默认 `clientid` 使用用户最新截图确认值：`ced7e5f0498645c6ec642dcf450b036f`，客户端 Key 为 `web_pc`。
- 登录后请求使用 `Authorization` header，PC 认证和文件请求同时携带 `clientid` header。
- 样式写入 CSS 文件，不用 JS 注入样式。
- 新增或修改的 HTML、JS、CSS 注释使用中文。
- `utils` 只放跨页面公共 JS；页面业务 JS 继续放 `public/js`。
- PC YAML 没有明确接口的页面不套用 APP 路径，不把 schema/requestBodies 当成可调用接口。
- 验证码只使用后台已配置的 PC/H5 场景；当前明确场景为 `WEB_H5_LOGIN`、`WEB_H5_REGISTER`、`WEB_H5_FORGOT_PASSWORD`。
- 换绑手机、注销账号的 PC/H5 验证码场景未确认，不套用 `APP_*` 场景。
---
## File Structure
- Create or Modify: `config.js`
- 唯一负责环境切换、开发接口地址、PC clientid、tenantId、token key、token header name。
- Create or Modify: `utils/StorageUtil.js`
- 负责 localStorage 安全读写。
- Create or Modify: `utils/FormUtil.js`
- 负责表单读取、空值清理、数字转换、布尔转换。
- Create or Modify: `utils/RequestUtil.js`
- 负责 URL 拼接、header 合并、FormData 判断、JSON 解包、业务错误对象。
- Modify: `public/js/api-client.js`
- 只把 PC YAML `paths` 中存在的接口作为真实请求方法；旧 APP 路径不得作为 fallback。
- Modify: `public/js/auth-pages.js`
- 登录使用 `WEB_H5_LOGIN`；注册使用 `WEB_H5_REGISTER`；找回密码使用 `WEB_H5_FORGOT_PASSWORD`。
- Modify: `public/js/captcha-pages.js`
- 按 `/captcha/require`、`/captcha/challenge`、`/captcha/verify` 组织 TAC 调用。
- Modify: `public/js/profile-pages.js`
- 用户资料提交字段以 `ProfileUpdateBody` schema 为准：`provinceCode/cityCode/districtCode`。
- Modify: `public/js/security-pages.js`
- 修改密码、换绑手机、注销账号只调用 PC 认证接口；涉及验证码的动作保留 PC/H5 场景待确认记录。
- Modify: `public/js/upload-pages.js`
- 上传、分片上传、文件引用只调用 `/genealogy/pc/files/*`。
- Modify: `public/js/region-pages.js`
- 地区选择只调用 `/genealogy/region/*`。
- Modify: related HTML files
- API 页面按顺序加载 `config.js`、`utils/*.js`、`public/js/api-client.js`、页面业务脚本。
- Modify: `tests/*.test.js`
- 测试只验证 PC YAML 已确认接口；旧 APP 路径测试改为“不可作为 PC 合同”。
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
- 每项开始/完成都回填时间、文件、接口、验证结果。
---
### Task 1: 配置入口与公共工具合同
**Files:**
- Create or Modify: `config.js`
- Create or Modify: `utils/StorageUtil.js`
- Create or Modify: `utils/FormUtil.js`
- Create or Modify: `utils/RequestUtil.js`
- Test: `tests/config.test.js`
- Test: `tests/utils.test.js`
**Interfaces:**
- Produces: `GenealogyConfig.getConfig(): { env, apiBaseUrl, clientId, tenantId, tokenKey, tokenHeaderName }`
- Produces: `GenealogyConfig.getApiBaseUrl(): string`
- Produces: `GenealogyConfig.getClientId(): string`
- Produces: `GenealogyConfig.getTenantId(): string`
- Produces: `GenealogyConfig.getTokenKey(): string`
- Produces: `StorageUtil.read(storage, key): string|null`
- Produces: `StorageUtil.write(storage, key, value): void`
- Produces: `StorageUtil.remove(storage, key): void`
- Produces: `FormUtil.trimOrUndefined(value): string|undefined`
- Produces: `FormUtil.toNumberOrUndefined(value): number|undefined`
- Produces: `FormUtil.toBoolean(value): boolean`
- Produces: `FormUtil.getFormValues(form): object`
- Produces: `RequestUtil.createRequester(options)(method, path, requestOptions): Promise<any>`
- [ ] **Step 1: Write config test**
Create or replace `tests/config.test.js` with:
```js
const assert = require('assert');
const configFactory = require('../config.js');
const store = {};
const config = configFactory({
localStorage: {
getItem: (key) => Object.prototype.hasOwnProperty.call(store, key) ? store[key] : null,
setItem: (key, value) => { store[key] = String(value); }
}
});
assert.strictEqual(config.getApiBaseUrl(), 'https://test-genealogy-api.ddxcjp.cn');
assert.strictEqual(config.getClientId(), 'ced7e5f0498645c6ec642dcf450b036f');
assert.strictEqual(config.getTenantId(), '000000');
assert.strictEqual(config.getTokenKey(), 'genealogy_auth_token');
assert.strictEqual(config.getConfig().tokenHeaderName, 'Authorization');
store.genealogy_api_base_url = 'https://custom.example.test';
assert.strictEqual(config.getApiBaseUrl(), 'https://custom.example.test');
console.log('config tests passed');
```
- [ ] **Step 2: Run config test**
Run: `node tests\config.test.js`
Expected before implementation: FAIL if `config.js` is absent or lacks these methods.
Expected after implementation: PASS with `config tests passed`.
- [ ] **Step 3: Implement `config.js`**
Use this implementation:
```js
(function (root, factory) {
// 全局配置同时支持浏览器页面和 Node 测试。
if (typeof module === 'object' && module.exports) {
module.exports = factory;
return;
}
root.GenealogyConfig = factory(root);
})(typeof globalThis !== 'undefined' ? globalThis : window, function (root) {
'use strict';
var DEFAULT_ENV = 'development';
var API_BASE_URLS = {
development: 'https://test-genealogy-api.ddxcjp.cn',
production: ''
};
var CLIENT_ID = 'ced7e5f0498645c6ec642dcf450b036f';
var TENANT_ID = '000000';
var TOKEN_KEY = 'genealogy_auth_token';
var TOKEN_HEADER_NAME = 'Authorization';
var ENV_KEY = 'genealogy_env';
var BASE_URL_KEY = 'genealogy_api_base_url';
function readStorage(key) {
try {
return root.localStorage && root.localStorage.getItem(key);
} catch (error) {
return null;
}
}
function getEnv() {
return readStorage(ENV_KEY) || DEFAULT_ENV;
}
function getApiBaseUrl() {
return readStorage(BASE_URL_KEY) || API_BASE_URLS[getEnv()] || API_BASE_URLS.development;
}
function getConfig() {
return {
env: getEnv(),
apiBaseUrl: getApiBaseUrl(),
clientId: CLIENT_ID,
tenantId: TENANT_ID,
tokenKey: TOKEN_KEY,
tokenHeaderName: TOKEN_HEADER_NAME
};
}
return {
getConfig: getConfig,
getApiBaseUrl: getApiBaseUrl,
getClientId: function () { return CLIENT_ID; },
getTenantId: function () { return TENANT_ID; },
getTokenKey: function () { return TOKEN_KEY; },
getTokenHeaderName: function () { return TOKEN_HEADER_NAME; }
};
});
```
- [ ] **Step 4: Write utilities test**
Create or replace `tests/utils.test.js` with focused utility assertions:
```js
const assert = require('assert');
const StorageUtil = require('../utils/StorageUtil.js');
const FormUtil = require('../utils/FormUtil.js');
const RequestUtil = require('../utils/RequestUtil.js');
assert.strictEqual(FormUtil.trimOrUndefined(' 张三 '), '张三');
assert.strictEqual(FormUtil.trimOrUndefined(' '), undefined);
assert.strictEqual(FormUtil.toNumberOrUndefined('12'), 12);
assert.strictEqual(FormUtil.toNumberOrUndefined(''), undefined);
assert.strictEqual(FormUtil.toBoolean('on'), true);
assert.strictEqual(FormUtil.toBoolean('0'), false);
const store = {};
const storage = {
getItem: (key) => Object.prototype.hasOwnProperty.call(store, key) ? store[key] : null,
setItem: (key, value) => { store[key] = String(value); },
removeItem: (key) => { delete store[key]; }
};
StorageUtil.write(storage, 'token', 'abc');
assert.strictEqual(StorageUtil.read(storage, 'token'), 'abc');
StorageUtil.remove(storage, 'token');
assert.strictEqual(StorageUtil.read(storage, 'token'), null);
const calls = [];
const requester = RequestUtil.createRequester({
baseUrl: 'https://test-genealogy-api.ddxcjp.cn',
clientId: 'pc-client',
tokenHeaderName: 'Authorization',
getToken: () => 'token-x',
fetchImpl: async (url, options) => {
calls.push({ url, options });
return {
ok: true,
status: 200,
json: async () => ({ code: 200, data: { ok: true } })
};
}
});
requester('GET', '/genealogy/pc/auth/profile', {
query: { keyword: '汤 氏' }
}).then((data) => {
assert.deepStrictEqual(data, { ok: true });
assert.strictEqual(calls[0].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/pc/auth/profile?keyword=%E6%B1%A4+%E6%B0%8F');
assert.strictEqual(calls[0].options.headers.clientid, 'pc-client');
assert.strictEqual(calls[0].options.headers.Authorization, 'Bearer token-x');
console.log('utils tests passed');
});
```
- [ ] **Step 5: Implement utility files**
Implement the utilities with Chinese comments around storage try/catch, FormData detection, JSON response parsing and `code !== 200` error creation. `RequestUtil.createRequester` must omit `Authorization` when `requestOptions.auth === false`.
- [ ] **Step 6: Run utility tests**
Run: `node tests\utils.test.js`
Expected: PASS with `utils tests passed`.
---
### Task 2: API 客户端收紧到 PC YAML `paths`
**Files:**
- Modify: `public/js/api-client.js`
- Test: `tests/api-client.test.js`
**Interfaces:**
- Consumes: `GenealogyConfig`
- Consumes: `StorageUtil`
- Consumes: `RequestUtil.createRequester`
- Produces: `GenealogyApi.createClient(options)`
- Produces: `GenealogyApi.defaultClient`
- Produces PC methods:
- `login(body)`, `register(body)`, `loginBySms(body)`, `sendSmsCode(body)`
- `getProfile()`, `updateProfile(body)`, `changePassword(body)`, `resetPassword(body)`, `changePhone(body)`, `deactivateAccount(body)`, `logout()`
- `uploadFile(formData)`, `initResumableUpload(body)`, `uploadChunk(formData)`, `completeResumableUpload(body)`, `bindFileReference(body)`, `releaseFileReference(query)`
- `getRegionChildren(parentCode)`, `getRegionPath(regionCode)`, `searchRegions(query)`, `getRegion(regionCode)`
- `captchaRequire(query)`, `captchaChallenge(body)`, `captchaVerify(body)`, `legacyCaptcha()`
- Produces unsupported method behavior: methods for PC YAML 未覆盖业务 throw `Error` with `code === 'PC_API_NOT_AVAILABLE'` and no network request.
- [ ] **Step 1: Replace API client test**
Rewrite `tests/api-client.test.js` so it verifies only PC-confirmed paths and unsupported APP-era methods:
```js
const assert = require('assert');
const GenealogyApi = require('../public/js/api-client.js');
const calls = [];
const client = GenealogyApi.createClient({
baseUrl: 'https://test-genealogy-api.ddxcjp.cn',
clientId: 'client-x',
tenantId: 'tenant-x',
tokenKey: 'token-key',
tokenHeaderName: 'Authorization',
storage: { getItem: () => 'abc-token' },
fetchImpl: async (url, options) => {
calls.push({ url, options });
return {
ok: true,
status: 200,
json: async () => ({ code: 200, data: { url } })
};
}
});
(async () => {
await client.login({ tenantId: 'tenant-x', phone: '13800000000', password: 'md5' });
assert.strictEqual(calls[0].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/pc/auth/login');
assert.strictEqual(calls[0].options.headers.clientid, 'client-x');
assert.strictEqual(calls[0].options.headers.Authorization, undefined);
await client.getProfile();
assert.strictEqual(calls[1].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/pc/auth/profile');
assert.strictEqual(calls[1].options.headers.Authorization, 'Bearer abc-token');
await client.updateProfile({ nickName: '张三', provinceCode: '510000', cityCode: '510100', districtCode: '510104' });
assert.strictEqual(calls[2].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/pc/auth/profile');
assert.strictEqual(calls[2].options.method, 'PUT');
await client.uploadFile(new FormData());
assert.strictEqual(calls[3].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/pc/files/upload');
await client.getRegionChildren('51');
assert.strictEqual(calls[4].url, 'https://test-genealogy-api.ddxcjp.cn/genealogy/region/children?parentCode=51');
await client.captchaRequire({ sceneCode: 'WEB_H5_LOGIN', subject: '13800000000' });
assert.strictEqual(calls[5].url, 'https://test-genealogy-api.ddxcjp.cn/captcha/require?tenantId=tenant-x&clientId=client-x&sceneCode=WEB_H5_LOGIN&subject=13800000000');
assert.strictEqual(calls[5].options.headers.Authorization, undefined);
assert.throws(
() => client.listGenealogies(),
(error) => error.code === 'PC_API_NOT_AVAILABLE'
);
assert.strictEqual(calls.length, 6);
console.log('api-client tests passed');
})();
```
- [ ] **Step 2: Run API client test**
Run: `node tests\api-client.test.js`
Expected before implementation: FAIL while old APP paths or old scene tests remain.
Expected after implementation: PASS with `api-client tests passed`.
- [ ] **Step 3: Implement confirmed PC methods**
In `public/js/api-client.js`, remove APP auth/files paths. Map methods exactly:
```js
login: function (body) {
return request('POST', '/genealogy/pc/auth/login', { body: body, auth: false });
},
register: function (body) {
return request('POST', '/genealogy/pc/auth/register', { body: body, auth: false });
},
sendSmsCode: function (body) {
return request('POST', '/genealogy/pc/auth/sms/code', { body: body, auth: false });
},
loginBySms: function (body) {
return request('POST', '/genealogy/pc/auth/login/sms', { body: body, auth: false });
},
getProfile: function () {
return request('GET', '/genealogy/pc/auth/profile');
},
updateProfile: function (body) {
return request('PUT', '/genealogy/pc/auth/profile', { body: body });
}
```
Add the remaining PC auth/files/region/captcha methods with the same direct mapping from YAML `paths`.
- [ ] **Step 4: Implement unsupported method guard**
For old business methods whose PC paths do not exist, keep the method name only if current pages call it, but route it to:
```js
function createUnavailableMethod(name) {
return function () {
var error = new Error('PC 接口文档未提供该业务接口：' + name);
error.code = 'PC_API_NOT_AVAILABLE';
throw error;
};
}
```
Use a Chinese comment above the mapping: `// PC YAML 未提供这些业务 paths，保留方法名只用于阻止旧 APP 路径继续发请求。`
- [ ] **Step 5: Verify no APP auth/files network paths remain**
Run: `Select-String -Path public\js\api-client.js -Pattern '/genealogy/app/auth|/genealogy/app/files'`
Expected: no matches.
- [ ] **Step 6: Run API client test again**
Run: `node tests\api-client.test.js`
Expected: PASS with `api-client tests passed`.
---
### Task 3: 登录验证码与 `public/tac` 调用
**Files:**
- Modify: `public/js/auth-pages.js`
- Modify: `public/js/captcha-pages.js`
- Modify: `login.html`
- Modify: `register.html`
- Modify: `forgot-password.html`
- Test: `tests/auth-pages.test.js`
- Test: `tests/captcha-pages.test.js`
**Interfaces:**
- Consumes: `public/tac/css/tac.css`
- Consumes: `public/tac/js/tac.min.js`
- Consumes: `GenealogyApi.defaultClient.captchaRequire/challenge/verify`
- Produces: `AuthPages.getCaptchaScene('login') === 'WEB_H5_LOGIN'`
- Produces: `AuthPages.getCaptchaScene('register') === 'WEB_H5_REGISTER'`
- Produces: `AuthPages.getCaptchaScene('password-reset') === 'WEB_H5_FORGOT_PASSWORD'`
- Produces: `CaptchaPages.buildChallengeBody(options, api)`
- Produces: `CaptchaPages.buildVerifyBody(options, api)`
- Produces: `CaptchaPages.ensureToken(form, options)`
- [ ] **Step 1: Replace auth scene tests**
In `tests/auth-pages.test.js`, require these expectations:
```js
assert.strictEqual(AuthPages.getCaptchaScene('login'), 'WEB_H5_LOGIN');
assert.strictEqual(AuthPages.getCaptchaScene('register'), 'WEB_H5_REGISTER');
assert.strictEqual(AuthPages.getCaptchaScene('password-reset'), 'WEB_H5_FORGOT_PASSWORD');
```
- [ ] **Step 2: Replace captcha tests**
In `tests/captcha-pages.test.js`, all challenge/verify body tests must use `WEB_H5_LOGIN`:
```js
assert.deepStrictEqual(CaptchaPages.buildChallengeBody({
sceneCode: 'WEB_H5_LOGIN',
subject: '13800000000'
}, fakeApi), {
tenantId: 'tenant-x',
clientId: 'client-x',
sceneCode: 'WEB_H5_LOGIN',
subject: '13800000000'
});
```
- [ ] **Step 3: Run auth and captcha tests**
Run:
```powershell
node tests\auth-pages.test.js
node tests\captcha-pages.test.js
```
Expected before implementation: FAIL if `PC_LOGIN` or `PC_REGISTER` remains.
Expected after implementation: PASS.
- [ ] **Step 4: Implement scene mapping**
In `public/js/auth-pages.js`:
```js
function getCaptchaScene(formType) {
// PC/H5 认证场景来自后台验证码配置，客户端 Key 为 web_pc。
var map = {
login: 'WEB_H5_LOGIN',
register: 'WEB_H5_REGISTER',
'password-reset': 'WEB_H5_FORGOT_PASSWORD'
};
return map[formType] || '';
}
```
If `sceneCode` is empty, `ensureCaptcha` must return `true` without calling `/captcha/require` and must not fabricate `validToken`.
- [ ] **Step 5: Verify TAC assets in auth pages**
Run:
```powershell
Select-String -Path login.html,register.html,forgot-password.html -Pattern 'public/tac/css/tac.css|public/tac/js/tac.min.js|public/js/captcha-pages.js|name="validToken"|data-captcha-box'
```
Expected:
- `login.html` has TAC CSS, TAC JS, `captcha-pages.js`, hidden `validToken`, and `[data-captcha-box]`.
- `register.html` and `forgot-password.html` may keep TAC assets and hidden fields, but no PC/H5 scene is configured until backend confirms scene code.
---
### Task 4: 认证与资料页面只接 PC auth schema
**Files:**
- Modify: `public/js/auth-pages.js`
- Modify: `public/js/profile-pages.js`
- Modify: `public/js/security-pages.js`
- Modify: `login.html`
- Modify: `register.html`
- Modify: `forgot-password.html`
- Modify: `profile.html`
- Modify: `profile-data.html`
- Modify: `profile-security.html`
- Test: `tests/auth-pages.test.js`
- Test: `tests/profile-pages.test.js`
- Test: `tests/security-pages.test.js`
**Interfaces:**
- Consumes: `GenealogyApi.defaultClient`
- Produces request bodies:
- `PasswordLoginBody`: `grantType/tenantId/phone/password/validToken`
- `PasswordRegisterBody`: `grantType/tenantId/phone/password/nickName/registerSource/validToken`
- `PasswordResetBody`: `tenantId/phone/smsCode/newPassword/validToken`
- `ProfileUpdateBody`: `nickName/avatarOssId/sex/birthday/provinceCode/cityCode/districtCode`
- [ ] **Step 1: Update body-builder tests**
`tests/auth-pages.test.js` must assert `registerSource: 'PC'` for register body and no `APP_*` scene in any body.
`tests/profile-pages.test.js` must assert profile update uses `provinceCode/cityCode/districtCode`, not `regionCode/addressDetail`.
- [ ] **Step 2: Run focused tests**
Run:
```powershell
node tests\auth-pages.test.js
node tests\profile-pages.test.js
node tests\security-pages.test.js
```
Expected before implementation: FAIL where old scene/body fields remain.
Expected after implementation: PASS.
- [ ] **Step 3: Implement auth body builders**
Use PC YAML schema fields only. For register:
```js
function buildRegisterBody(values, config) {
var body = {
grantType: 'password',
tenantId: config.tenantId,
phone: values.phone,
password: values.password,
registerSource: 'PC'
};
if (values.nickName) body.nickName = values.nickName;
if (values.validToken) body.validToken = values.validToken;
return body;
}
```
- [ ] **Step 4: Implement profile body builder**
Use schema fields:
```js
function buildProfileUpdateBody(values) {
return removeEmpty({
nickName: values.nickName,
avatarOssId: toNumberOrUndefined(values.avatarOssId),
sex: values.sex,
birthday: values.birthday,
provinceCode: values.provinceCode,
cityCode: values.cityCode,
districtCode: values.districtCode
});
}
```
- [ ] **Step 5: Verify page script order**
Run:
```powershell
Select-String -Path login.html,register.html,forgot-password.html,profile.html,profile-data.html,profile-security.html -Pattern 'config.js|utils/StorageUtil.js|utils/FormUtil.js|utils/RequestUtil.js|public/js/api-client.js'
```
Expected: every page that uses `GenealogyApi` loads config and utils before `api-client.js`.
---
### Task 5: 文件上传和文件引用只切 PC files
**Files:**
- Modify: `public/js/upload-pages.js`
- Modify: upload-related page scripts that call `GenealogyApi.defaultClient.uploadFile`
- Test: `tests/upload-pages.test.js`
- Test: `tests/api-client.test.js`
**Interfaces:**
- Consumes: `GenealogyApi.defaultClient.uploadFile(formData)`
- Consumes: `GenealogyApi.defaultClient.initResumableUpload(body)`
- Consumes: `GenealogyApi.defaultClient.uploadChunk(formData)`
- Consumes: `GenealogyApi.defaultClient.completeResumableUpload(body)`
- Consumes: `GenealogyApi.defaultClient.bindFileReference(body)`
- Consumes: `GenealogyApi.defaultClient.releaseFileReference(query)`
- [ ] **Step 1: Add upload tests**
`tests/upload-pages.test.js` must verify:
- single upload calls `/genealogy/pc/files/upload`
- resumable init calls `/genealogy/pc/files/resumable/init`
- file reference body requires `bizType/bizTable/bizId/bizField`
- [ ] **Step 2: Run upload tests**
Run: `node tests\upload-pages.test.js`
Expected before implementation: FAIL if old APP file paths remain.
Expected after implementation: PASS.
- [ ] **Step 3: Implement upload mapping**
Only map file capability. Do not submit article/feed/album/ceremony/growth/memo business forms unless PC YAML provides their business endpoints.
- [ ] **Step 4: Verify no APP file path remains**
Run: `Select-String -Path public\js\api-client.js,public\js\upload-pages.js -Pattern '/genealogy/app/files'`
Expected: no matches.
---
### Task 6: 行政区划接口和资料地区字段
**Files:**
- Modify: `public/js/region-pages.js`
- Modify: `public/js/profile-pages.js`
- Test: `tests/region-pages.test.js`
- Test: `tests/profile-pages.test.js`
**Interfaces:**
- Consumes: `GET /genealogy/region/children`
- Consumes: `GET /genealogy/region/path/{regionCode}`
- Consumes: `GET /genealogy/region/search`
- Consumes: `GET /genealogy/region/{regionCode}`
- Produces profile fields: `provinceCode/cityCode/districtCode`
- [ ] **Step 1: Add region tests**
`tests/region-pages.test.js` must assert:
- empty parent loads province list with no required parent code.
- search requires `keyword`.
- selected province/city/district writes `provinceCode/cityCode/districtCode` to the form.
- [ ] **Step 2: Run region tests**
Run: `node tests\region-pages.test.js`
Expected before implementation: FAIL if form still expects `regionCode/addressDetail`.
Expected after implementation: PASS.
- [ ] **Step 3: Implement region mapping**
Use `GenealogyApi.defaultClient.getRegionChildren`, `getRegionPath`, `searchRegions`, `getRegion`. Do not create genealogy submit behavior here.
---
### Task 7: PC YAML 未覆盖页面降级为接口待确认
**Files:**
- Modify: page scripts that currently call APP-era business methods:
- `public/js/genealogy-pages.js`
- `public/js/join-apply-pages.js`
- `public/js/member-admin-pages.js`
- `public/js/article-pages.js`
- `public/js/feed-pages.js`
- `public/js/album-pages.js`
- `public/js/ceremony-pages.js`
- `public/js/growth-pages.js`
- `public/js/memo-pages.js`
- `public/js/generation-pages.js`
- `public/js/lineage-pages.js`
- `public/js/notification-pages.js`
- `public/js/help-pages.js`
- `public/js/promotion-pages.js`
- `public/js/feedback-pages.js`
- `public/js/vip-pages.js`
- Test: `tests/unsupported-pages.test.js`
**Interfaces:**
- Consumes: `PC_API_NOT_AVAILABLE` errors from `GenealogyApi`
- Produces: visible or console-safe page state that says PC interface is not configured, without issuing APP requests.
- [ ] **Step 1: Add unsupported-page smoke test**
Create `tests/unsupported-pages.test.js` to load each page script in Node with a fake client method that throws `{ code: 'PC_API_NOT_AVAILABLE' }`. Assert each script handles the error without rethrowing from its init function.
- [ ] **Step 2: Run unsupported-page test**
Run: `node tests\unsupported-pages.test.js`
Expected before implementation: FAIL for scripts that assume APP methods are valid.
Expected after implementation: PASS.
- [ ] **Step 3: Implement shared page fallback**
In each affected page script, catch `PC_API_NOT_AVAILABLE` and render a small existing-style empty state. Add a Chinese comment: `// PC YAML 未提供该业务接口，页面先展示接口待确认状态。`
- [ ] **Step 4: Verify no APP business path is emitted from API client**
Run: `Select-String -Path public\js\api-client.js -Pattern '/genealogy/app/'`
Expected: no network path matches.
---
### Task 8: 追踪表和执行记录
**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
**Interfaces:**
- Consumes: Task 1-7 verification results.
- Produces: updated status rows with exact timestamps, changed files, interface paths and verification commands.
- [ ] **Step 1: Mark task start before edits**
Before executing each PC task, update the row status from `待开始` to `进行中` with exact time from:
```powershell
Get-Date -Format "yyyy-MM-dd HH:mm:ss zzz"
```
- [ ] **Step 2: Mark task completion after verification**
After the task's verification commands pass, update status to `已完成` and record:
- completion time
- modified files
- interface paths
- verification commands
- verification result
- [ ] **Step 3: Keep missing interfaces in coverage matrix**
Any page whose main business path is absent from `genealogy-pc-openapi.yaml` remains in `PC YAML 未覆盖` or `接口待确认` and must not be promoted to full integration.
---
## Verification Gate
Run these before marking the replan execution complete:
```powershell
node tests\config.test.js
node tests\utils.test.js
node tests\api-client.test.js
node tests\auth-pages.test.js
node tests\captcha-pages.test.js
node tests\profile-pages.test.js
node tests\security-pages.test.js
node tests\upload-pages.test.js
node tests\region-pages.test.js
node tests\unsupported-pages.test.js
Get-ChildItem -Path public\js -Filter *.js | Where-Object { $_.Name -notin @('jquery360.js','jquery.min.js') } | Sort-Object Name | ForEach-Object { node --check $_.FullName }
Select-String -Path public\js\api-client.js -Pattern '/genealogy/app/'
Select-String -Path public\js\auth-pages.js,public\js\captcha-pages.js,tests\auth-pages.test.js,tests\captcha-pages.test.js -Pattern 'PC_LOGIN|PC_REGISTER|PC_PASSWORD_RESET|APP_LOGIN|APP_REGISTER|APP_FORGOT_PASSWORD'
git diff --check
```
Expected:
- All listed Node tests pass.
- Business JS syntax check passes.
- `api-client.js` contains no `/genealogy/app/` network path.
- Auth and captcha code/tests contain no stale APP/old PC scene defaults.
- `git diff --check` passes, or if this directory is not a Git repository, record the exact output.
## Self-Review
- Spec coverage: this plan covers latest PC YAML `paths`, test domain, config.js, utils/public-js separation, CSS/no style injection, Chinese comments, TAC login scene, profile schema mismatch, and PC-missing business interfaces.
- Placeholder scan: no implementation task asks the worker to invent missing PC endpoints or use APP paths as compatibility.
- Type consistency: `GenealogyConfig`, `StorageUtil`, `FormUtil`, `RequestUtil`, `GenealogyApi.createClient`, `AuthPages.getCaptchaScene`, and `CaptchaPages.ensureToken` names are consistent across tasks.
docs/superpowers/plans/2026-07-09-pc-auth-three-pages.md
+127
View File
@@ -0,0 +1,127 @@
# PC Auth Three Pages 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:** 按 `genealogy-pc-openapi.yaml` 和 Apifox 截图，把登录、注册、忘记密码三页与 PC 认证接口、验证中心接口对齐。
**Architecture:** 根目录 `config.js` 继续作为环境、`clientid`、`tenantId` 的唯一配置入口；`utils` 继续存放跨页面公共工具；页面业务逻辑集中在 `public/js/auth-pages.js`，接口调用集中在 `public/js/api-client.js`，验证码适配集中在 `public/js/captcha-pages.js`。页面差异样式只写入对应 CSS 文件。
**Tech Stack:** 原生 HTML/CSS/JavaScript、`public/tac` 滑动验证、Node 断言测试。
## Global Constraints
- 接口依据只使用 `genealogy-pc-openapi.yaml` 与用户补充的 Apifox 截图，不再使用 `APP.openapi.json`。
- 开发环境接口地址为 `https://test-genealogy-api.ddxcjp.cn`。
- PC `clientid` 为 `ced7e5f0498645c6ec642dcf450b036f`，租户 ID 为 `000000`。
- 登录验证码场景为 `WEB_H5_LOGIN`，注册验证码场景为 `WEB_H5_REGISTER`，忘记密码验证码场景为 `WEB_H5_FORGOT_PASSWORD`。
- 不在 JS 中注入样式；页面差异样式写入对应 CSS 文件，公共样式写入 `public/css/public.css`。
- 新增或修改的 HTML、CSS、JS 注释使用中文，代码保持可读，不压缩。
---
### Task 1: 记录专项计划
**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
- Create: `docs/superpowers/plans/2026-07-09-pc-auth-three-pages.md`
**Interfaces:**
- Consumes: 用户确认“可以”先做登录、注册、忘记密码三页。
- Produces: PC-009 专项计划记录。
- [x] **Step 1: 写入本计划**
创建本计划，明确页面、接口、验证码场景、样式和验证约束。
- [x] **Step 2: 写入追踪记录**
在追踪文档中新增 `PC-009`，状态为“进行中”，开始时间为 `2026-07-09 16:32:17 +08:00`。
### Task 2: 登录页补齐短信登录
**Files:**
- Modify: `login.html`
- Modify: `public/css/login.css`
- Modify: `public/js/auth-pages.js`
- Modify: `tests/auth-pages.test.js`
- Modify: `tests/api-client.test.js`
**Interfaces:**
- Consumes: `ApiClient.login(body)`、`ApiClient.loginBySms(body)`、`ApiClient.sendSmsCode(body)`、`CaptchaPages.ensureToken(form, options)`。
- Produces: 登录页同时支持密码登录和短信登录。
- [x] **Step 1: 页面增加登录方式切换**
在 `login.html` 的登录表单内增加模式切换按钮，密码登录区域保留 `phone/password/validToken`，短信登录区域增加 `phone/smsCode/validToken` 和发送验证码按钮。
- [x] **Step 2: CSS 写入登录页专属样式**
在 `public/css/login.css` 增加模式切换、隐藏区域、验证码行样式，不在 JS 中写样式。
- [x] **Step 3: JS 支持短信登录提交**
在 `public/js/auth-pages.js` 增加 `buildSmsLoginBody(values)`，提交时按当前模式调用 `/genealogy/pc/auth/login` 或 `/genealogy/pc/auth/login/sms`。
- [x] **Step 4: 发送短信复用场景码**
登录页短信验证码按钮使用 `data-scene-code="WEB_H5_LOGIN"`，忘记密码页继续使用 `WEB_H5_FORGOT_PASSWORD`。
- [x] **Step 5: 更新测试**
`tests/auth-pages.test.js` 增加短信登录 body 断言；`tests/api-client.test.js` 增加 `loginBySms` 和 `sendSmsCode` 路径/入参断言。
### Task 3: 注册和忘记密码复核
**Files:**
- Verify: `register.html`
- Verify: `forgot-password.html`
- Verify: `public/js/auth-pages.js`
**Interfaces:**
- Consumes: `/genealogy/pc/auth/register`、`/genealogy/pc/auth/sms/code`、`/genealogy/pc/auth/password/reset`。
- Produces: 注册和忘记密码页面确认继续按 PC 字段提交。
- [x] **Step 1: 注册页字段复核**
确认注册页只提交 `phone/password/nickName/validToken`，`grantType/tenantId/clientId/registerSource` 由 `api-client.js` 统一补齐。
- [x] **Step 2: 忘记密码页字段复核**
确认忘记密码页提交 `tenantId/phone/smsCode/newPassword/validToken`，不再出现邮箱找回文案。
### Task 4: 专项验证和完成记录
**Files:**
- Modify: `docs/pc-api-page-integration-tracker-2026-07-09.md`
**Interfaces:**
- Consumes: Task 2 和 Task 3 的实现结果。
- Produces: PC-009 完成记录和验证结果。
- [x] **Step 1: 运行测试**
运行：
```powershell
node tests\auth-pages.test.js
node tests\api-client.test.js
node tests\captcha-pages.test.js
```
期望全部输出 `passed`。
- [x] **Step 2: 运行语法检查**
运行：
```powershell
node --check public\js\auth-pages.js
node --check public\js\api-client.js
node --check public\js\captcha-pages.js
```
期望无输出且退出码为 0。
- [x] **Step 3: 更新追踪文档**
把 `PC-009` 状态改为“已完成”，写入完成时间、修改文件、接口路径、验证码场景和验证结果。
docs/superpowers/plans/2026-07-09-tac-captcha-auth.md
+95
View File
@@ -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**.