26 KiB
26 KiB
接口对接规划与进度记录
基本信息
- 项目路径:
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。 - 业务代码不压缩,保持展开、可读;需要解释意图、边界或接口字段映射的位置使用中文注释。
- 第三方库、压缩库、已存在乱码文件不做无关重写,避免引入额外风险。
核心闭环范围
-
共享接口层
- 新增统一 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。
- 新增统一 API 客户端,负责
-
登录注册找回
login.html->POST /genealogy/app/auth/loginregister.html->POST /genealogy/app/auth/registerforgot-password.html->POST /genealogy/app/auth/sms/code,PUT /genealogy/app/auth/password/reset- 密码按文档要求提交 32 位 MD5,复用已有
public/js/md5.js。
-
家谱核心
create-genealogy.html->POST /genealogy/app/genealogiesprofile-families.html->GET /genealogy/app/genealogies/mineplaza.html->GET /genealogy/app/genealogies/publicfamily-detail.html->GET /genealogy/app/genealogies/{genealogyId}
-
个人资料与反馈
profile.html、profile-data.html->GET /genealogy/app/auth/profileprofile-feedback.html、submit-ticket.html->GET/POST /genealogy/app/feedback
-
拦截处理
public/js/page-effects.js当前会拦截登录、注册、创建家谱、个人中心页面并显示“功能待开发”。- 对已接入接口的页面移除该拦截,保留未接入页面的提示。
验证计划
- 新增共享 API 客户端测试,先确认测试失败,再实现通过。
- 检查核心页面均加载共享脚本和页面脚本。
- 用静态结构检查确认接口路径、表单字段、脚本引用存在。
- 运行语法检查或 Node 烟测,确保 JS 可加载、核心方法可调用。
- 检查新增样式是否位于 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 测试通过,四个业务 JSnode --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 测试通过,六个业务 JSnode --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 测试全部通过,六个业务 JSnode --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 测试全部通过,七个业务 JSnode --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 测试全部通过,八个业务 JSnode --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 测试全部通过,九个业务 JSnode --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 测试全部通过,十个业务 JSnode --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 测试全部通过,十一个业务 JSnode --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 测试通过,十二个业务 JSnode --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 测试通过,十三个业务 JSnode --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 测试通过,十四个业务 JSnode --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 测试通过,十五个业务 JSnode --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 测试通过,十六个业务 JSnode --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 测试通过,十七个业务 JSnode --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 测试通过,十八个业务 JSnode --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 测试通过,十九个业务 JSnode --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 测试通过,二十个业务 JSnode --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、业务 JSnode --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、业务 JSnode --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、业务 JSnode --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、业务 JSnode --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、业务 JSnode --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、业务 JSnode --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、业务 JSnode --check、页面挂载点检查均通过,未发现样式注入片段和 TODO 类占位;git diff --check因当前目录不是 Git 仓库无法执行。