jiapu/docs/api-page-integration-tracker-2026-07-09.md

# 接口对接编号规划与状态追踪

创建时间：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 执行完成，状态从“进行中”改为“已完成”。