修改问题

2026-07-11 11:03:45 +08:00
parent edc0a58a54
commit db397a7917
38 changed files with 1082 additions and 7994 deletions
@@ -3,8 +3,7 @@
 创建时间：2026-07-09 15:14:58 +08:00  
 接口依据：`genealogy-pc-openapi.yaml`  
 接口基础地址：`http://182.61.18.23:8080`
-旧依据处理：`APP.openapi.json` 只作为历史误用记录，不再作为 PC 页面继续对接依据。  
-旧进度记录：`docs/api-page-integration-tracker-2026-07-09.md`
+接口依据：`genealogy-pc-openapi.yaml`

 ## 当前地址契约

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

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

 - 后台验证码配置截图中，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]` 容器。
@@ -70,8 +68,8 @@
 | PC-004 | 本地复核通过 | 文件上传页面 | `/genealogy/pc/files/*` | `node tests\upload-pages.test.js`、`node tests\api-client.test.js` 通过；文件上传仍需真实文件和后端授权进行端到端验证。 |
 | PC-005 | 本地复核通过 | 地区选择页面 | `/genealogy/region/*` | `node tests\region-pages.test.js`、`node tests\profile-pages.test.js` 通过。 |
 | PC-006 | 复核通过 | 页面覆盖矩阵 | PC YAML 覆盖边界 | 保持“公共能力不等于整页业务已对接”的边界，未覆盖业务继续受控失败。 |
-| PC-007 | 复核通过 | 实施规划 | `genealogy-pc-openapi.yaml` | 当前计划与 YAML `paths` 一致，不使用旧 APP 路径 fallback。 |
-| PC-008 | 复核通过 | PC YAML 未覆盖业务页面 | `PC_API_NOT_AVAILABLE` | `utils/ApiClient.js` 统一抛 `PC_API_NOT_AVAILABLE`，旧 `/genealogy/app/` 请求路径扫描无结果。 |
+| PC-007 | 复核通过 | 实施规划 | `genealogy-pc-openapi.yaml` | 当前计划与 YAML `paths` 一致，不使用旧路径 fallback。 |
+| PC-008 | 复核通过 | PC YAML 未覆盖业务页面 | `PC_API_NOT_AVAILABLE` | `utils/ApiClient.js` 统一抛 `PC_API_NOT_AVAILABLE`，过期请求路径扫描无结果。 |
 | PC-009 | 本地复核通过 | 登录、注册、找回密码 | PC auth、`/captcha/*` | 三页场景编码、表单契约、Axios 请求客户端和相关测试均通过；真实账号流程待业务数据联调。 |
 | PC-010 | 已复核（当前地址已同步） | `config.js`、`tests/config.test.js`、`utils/ApiClient.js` | API 基础地址 | 当前开发和生产地址均为 `http://182.61.18.23:8080`；地址唯一运行时来源为 `config.js`，`tests/config.test.js` 已同步断言。 |
 | PC-011 | 本地复核通过 | 三张认证页 TAC 弹窗 | `public/tac`、`/captcha/*` | 页面级挂载、移动端约束和结构测试通过；未修改 `tac.min.js`。 |
@@ -81,31 +79,31 @@
 | 分类 | 页面/模块 | 当前判断 | 处理方式 |
 | --- | --- | --- | --- |
 | 完整可闭环 | `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_*` 场景。 |
+| 接口存在但部分验证码场景待确认 | `register.html`、`forgot-password.html`、`profile-security.html` 中的换绑/注销相关动作 | PC YAML 有对应认证接口；注册场景为 `WEB_H5_REGISTER`，找回密码场景为 `WEB_H5_FORGOT_PASSWORD`，换绑和注销暂未提供 PC/H5 场景。 | 注册和找回密码可接 TAC；换绑、注销涉及验证码的提交先记录待确认，不套用未经确认的场景。 |
 | 资料接口可对接 | `profile.html`、`profile-data.html` 中用户资料读取/修改 | PC YAML 有 `/genealogy/pc/auth/profile`。 | 只处理用户资料读写；页面里其他非资料业务不因此视为完成。 |
 | 公共地区能力可保留 | `create-genealogy.html`、`profile-create-family.html`、`profile-data.html` 中地区选择控件 | PC YAML 有 `/genealogy/region/*`。 | 只保留和验证地区选择；创建家谱等主业务接口 PC YAML 未覆盖，仍待确认。 |
 | 文件能力可切换 | 文章、动态、相册、成长、备忘、祭祀等页面里的上传控件 | PC YAML 有 `/genealogy/pc/files/*`。 | 只把上传、分片、文件引用切到 PC 文件接口；文章/动态/相册等主业务接口仍待确认。 |
-| PC YAML 未覆盖 | 家谱主体、成员、字辈、世系、动态、文章、相册、祭祀、族务、VIP、通知、反馈、帮助、推广、姓氏、搜索等主业务页面 | 当前 PC YAML 没有这些业务路径。 | 不套用 APP 路径；等待补充 PC 接口后再逐页规划。 |
+| PC YAML 未覆盖 | 家谱主体、成员、字辈、世系、动态、文章、相册、祭祀、族务、VIP、通知、反馈、帮助、推广、姓氏、搜索等主业务页面 | 当前 PC YAML 没有这些业务路径。 | 等待补充 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：收到用户纠正，停止旧接口继续推进；读取 `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:41:40 +08:00：按最新 YAML 分析结果重写 `docs/superpowers/plans/2026-07-09-pc-api-replan.md`，新增 PC-007；明确旧路径不能作为 PC fallback，缺失业务接口统一降级为接口待确认。
 - 2026-07-09 15:44:18 +08:00：开始执行 PC-001/PC-002，先按 TDD 创建 `config.js` 和 `utils` 公共工具测试，再实现最小配置与工具层。
 - 2026-07-09 15:47:17 +08:00：完成 PC-001 和 PC-002 的公共工具层部分；`config.js` 位于根目录，`utils` 只放跨页面公共 JS，页面业务仍留在 `public/js`。
- 2026-07-09 15:51:34 +08:00：完成 PC-002 的 `api-client.js` 切换；旧 APP 路径不再作为网络请求路径，未覆盖业务统一抛 `PC_API_NOT_AVAILABLE`。
+- 2026-07-09 15:51:34 +08:00：完成 PC-002 的请求客户端切换；旧路径不再作为网络请求路径，未覆盖业务统一抛 `PC_API_NOT_AVAILABLE`。
 - 2026-07-09 15:55:28 +08:00：PC-003 认证页验证码阶段完成；登录使用 `WEB_H5_LOGIN`，未确认 PC/H5 场景的注册和找回密码不调用验证中心。
 - 2026-07-09 15:57:36 +08:00：收到用户补充截图，确认 PC `clientid` 为 `ced7e5f0498645c6ec642dcf450b036f`、客户端 Key 为 `web_pc`，新增注册场景 `WEB_H5_REGISTER` 和找回密码场景 `WEB_H5_FORGOT_PASSWORD`；同步修正配置、计划和认证页场景映射。
 - 2026-07-09 16:00:22 +08:00：PC-003 完成；认证页、资料页、安全页的 PC auth/captcha 接入和脚本顺序已验证。
 - 2026-07-09 16:03:23 +08:00：PC-004 完成；上传公共能力切换到 PC 文件接口，相关上传页已补齐公共层脚本顺序。
 - 2026-07-09 16:05:12 +08:00：PC-005 完成；地区选择只保留公共行政区划能力，创建家谱等主业务仍按 PC YAML 未覆盖处理。
- 2026-07-09 16:06:35 +08:00：PC-008 完成；PC YAML 未覆盖业务不会继续发送旧 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:06:35 +08:00：PC-008 完成；PC YAML 未覆盖业务不会继续发送过期请求，全量 Node 测试通过。
+- 2026-07-09 16:07:42 +08:00：收尾验证完成；全量 `tests/*.test.js` 通过，`public/js` 非压缩业务脚本 `node --check` 通过，过期请求路径、旧验证码场景、旧 PC clientId 扫描无输出；`git diff --check` 因当前目录不是 Git 仓库无法执行。
 - 2026-07-09 16:09:55 +08:00：开始登录、注册、找回密码三页专项核对；按 PC YAML 的 `PasswordLoginBody`、`PasswordRegisterBody`、`SmsCodeBody`、`PasswordResetBody` 修正页面字段、输入类型、验证码场景声明和文案。
 - 2026-07-09 16:12:10 +08:00：登录、注册、找回密码三页专项完成；三页表单已显式声明 `data-captcha-scene`，手机号输入改为 `type="tel"`、`inputmode="numeric"`、`maxlength="11"`，找回密码文案改为只支持注册手机号；`auth-pages.js` 优先读取页面 `data-captcha-scene`。验证：`node tests\auth-pages.test.js`、`node tests\captcha-pages.test.js`、`node tests\api-client.test.js` 通过；三页字段/脚本顺序扫描通过；旧邮箱文案和旧验证码场景扫描无输出。
 - 2026-07-09 16:19:11 +08:00：根据用户反馈“接口文档少了很多东西”重新核对 `genealogy-pc-openapi.yaml` 的真实 `paths`；确认当前 YAML 只有验证中心、认证登录、文件上传、行政区划四类共 25 个操作，虽然声明了家谱、成员、字辈、世系、家族圈、文章、相册、祭祀、族务、VIP、消息、反馈等标签和模型，但没有对应可调用路径。结论：这些业务页面不能继续视为已对接，只能保留 `PC_API_NOT_AVAILABLE`，等待后端补充 PC 接口文档。
@@ -309,3 +307,48 @@
 - 流程结果：注册成功清除 token 并跳转 `login.html`；当前登录响应从 `data.access_token` 取 JWT，且兼容 `token`、`accessToken`、`tokenValue` 后跳转 `profile.html`；个人资料无 token 或收到 HTTP/业务 `401` 时清 token 并跳转 `index.html`；确认退出无论接口结果都清 token 并跳转 `index.html`。
 - 修改文件：`tests/config.test.js`、`tests/utils.test.js`、`utils/ApiClient.js`、`tests/api-client.test.js`、`public/js/profile-pages.js`、`public/js/profile-common.js`、`profile.html`、`tests/profile-pages.test.js`、`tests/profile-logout-structure.test.js`。
 - 验证结果：`node tests/config.test.js`、`node tests/utils.test.js`、`node tests/api-client.test.js`、`node tests/auth-pages.test.js`、`node tests/profile-pages.test.js`、`node tests/profile-logout-structure.test.js`、`node --check utils/ApiClient.js`、`node --check public/js/profile-pages.js`、`node --check public/js/profile-common.js` 和全量 Node 测试均通过。
+
+## PC-026 安全页认证入口收敛
+
+- 状态：部分完成
+- 完成时间：2026-07-11
+- 页面范围：`profile-security.html`
+- 接口范围：`/genealogy/pc/auth/login/sms`、`/genealogy/pc/auth/phone`、`/genealogy/pc/auth/account/deactivate`、`/genealogy/pc/auth/logout`
+- 契约结果：`login.html` 是密码和短信登录的唯一入口；登录成功跳转 `profile.html`。已登录的账号安全页不得重复发起登录流程。退出登录和账号注销完成后均跳转 `index.html`。
+- 修改结果：删除安全页遗留的短信登录表单、旧接口说明、请求体构造和提交分支；安全页退出无论接口请求结果都跳转首页，账号注销成功后也跳转首页。
+- 后端阻塞：换绑手机仍无法形成完整 PC/H5 流程。`POST /genealogy/pc/auth/sms/code` 必填 `sceneCode` 和 `validToken`，但当前未定义换绑手机的 PC/H5 场景码；不得使用未经确认的场景替代。待后端提供场景码后，补充滑动验证、发送短信验证码和换绑提交链路。
+- 验证结果：先运行 `node tests/security-pages.test.js`，确认旧安全页短信登录导出仍存在而按预期失败；修复后该测试通过。全量验证待本项后续记录补充。
+
+## PC-027 PC-only 接口契约清理
+
+- 状态：已完成
+- 完成时间：2026-07-11
+- 契约所有者：`genealogy-pc-openapi.yaml` 是 PC/H5 页面接口的唯一依据；运行时请求由 `utils/ApiClient.js` 统一发起。
+- 修改结果：删除旧接口文档和错误对接记录；清除页面、脚本、规划和 PC YAML 中遗留的旧路径、场景码与文档引用；PC YAML 的验证码示例统一使用 `WEB_H5_LOGIN`，注册来源示例为 `PC`。
+- 登录确认：`login.html` 的短信登录继续经 `public/js/auth-pages.js` 调用 `utils/ApiClient.js`，请求 `POST /genealogy/pc/auth/login/sms`，验证码场景为 `WEB_H5_LOGIN`。
+- 验证结果：新增 `tests/pc-api-contract.test.js`。该测试确认旧接口文档与错误记录不存在，扫描当前运行代码、PC YAML 和有效规划没有遗留旧契约，并断言短信登录使用 PC 路径和 `WEB_H5_LOGIN`。
+
+## PC-028 当前 PC 接口页面覆盖
+
+- 状态：部分完成
+- 完成时间：2026-07-11
+- 接口清单：`genealogy-pc-openapi.yaml` 当前有 25 个操作；`tests/pc-endpoint-coverage.test.js` 对每项操作断言页面调用或明确后端阻塞原因。
+- 已形成页面闭环的 21 项操作：验证码查询/挑战/校验，注册、密码登录、短信登录、短信验证码，资料读取/修改，修改密码、找回密码、注销账号、退出登录，单文件上传、分片初始化/上传/完成，地区下级查询/搜索/路径/详情。
+- 文件上传结果：`profile-data.html` 的头像上传不再要求手填 OSS ID。文件不超过 4 MB 时调用单文件上传；超过 4 MB 时依次调用分片初始化、每片上传和完成上传，完成后回填同一 `avatarOssId`，由“保存资料”提交资料接口。
+- 地区结果：`profile-data.html` 支持按地区名称或编码搜索；选择结果会查询地区详情和路径，再回填省、市、区县选择器后提交资料接口。
+- 后端契约阻塞的 4 项操作：
+  1. `GET /auth/code`：接口是兼容旧图形验证码，但当前 PC 登录/注册请求体没有可提交的验证码字段。
+  2. `PUT /genealogy/pc/auth/phone`：发送短信前需要 PC/H5 换绑手机号验证码场景码，当前文档未提供。
+  3. `POST /genealogy/pc/files/reference`：缺少可由当前 PC 页面创建的业务表名和业务 ID 契约。
+  4. `DELETE /genealogy/pc/files/reference`：同样缺少业务表名、业务 ID 和业务字段的来源契约。
+- 浏览器验收顺序：
+  1. `register.html`：完成注册，确认跳转 `login.html` 且不保留登录态。
+  2. `login.html` 密码登录：完成滑块验证和登录，确认跳转 `profile.html`。
+  3. `login.html` 短信登录：完成滑块验证、发送短信和登录，确认跳转 `profile.html`。
+  4. `profile.html`：确认资料成功加载；清空本地 token 后重新进入，确认跳转首页。
+  5. `profile-data.html`：修改昵称、性别、生日后保存；上传小于等于 4 MB 的头像并保存资料。
+  6. `profile-data.html`：上传大于 4 MB 的头像，确认网络依次出现 `resumable/init`、`resumable/chunk`、`resumable/complete`，再保存资料。
+  7. `profile-data.html`：搜索地区名称或编码，选择结果，确认省市区回填后保存。
+  8. `forgot-password.html`：完成验证码、短信码和密码重置。
+  9. `profile-security.html`：分别测试修改密码、账号注销和退出登录；退出与注销成功后均回首页。
+- 验证结果：`node tests/pc-endpoint-coverage.test.js`、`node tests/upload-pages.test.js`、`node tests/region-pages.test.js`、`node tests/profile-pages.test.js`、`node tests/auth-pages.test.js`、`node tests/captcha-pages.test.js`、`node tests/api-client.test.js`、`node tests/security-pages.test.js` 均通过。