jiapu/docs/PC接口对接规划.md

PC 接口字段与页面落地规划（供 AI 执行）

文档状态：规划，不代表当前代码已经完成 基线日期：2026-07-27 当前本地快照：根目录 PC.openapi.json，OpenAPI 3.1.0 使用对象：另一台电脑上的执行 AI 本轮边界：只写规划；执行 AI 才能修改页面、脚本和测试

0. 强制要求：必须打开 Apifox 查看

执行 AI 在修改任何代码前，必须实际登录并打开 Apifox 的“家谱”项目，进入每一个本轮接口的详情页逐项查看。不得只读取 PC.openapi.json、Apifox 本地缓存、旧截图或历史文档。

每个接口都必须在 Apifox 详情页记录：

1. method、完整 path、接口状态和所属 PC 目录；
2. Path、Query、Header、Cookie 和 Body 的全部字段；
3. 每个字段的类型、必填/可选/条件必填、默认值、枚举、格式、长度和取值范围；
4. 字段说明、示例值、关联字典和条件显示规则；
5. 请求体中折叠对象、数组元素和嵌套字段的完整结构；
6. 成功响应、失败响应、列表元素、详情对象和分页结构的完整字段；
7. 登录要求、角色权限、业务前置条件和错误码；
8. Apifox 页面有但 OpenAPI 导出遗漏的字段或说明。

核对结果必须写入本规划对应模块的字段表，并为每个字段标明 U/S/F/A/R/I/V 分类、使用页面、数据来源和提交时机。Apifox 详情没有确认的字段不得进入代码；Apifox 与导出文件不一致时，以现场核对结果形成问题清单，先让接口 owner 修正并重新导出，再实施。

1. 最终目标

执行 AI 要把 Apifox 中的 PC 接口准确落到现有 PC 页面，最终同时满足：

1. 请求体中的必填字段、可选字段全部有明确页面归属。
2. 字段被明确分成：
   • 用户输入；
   • 用户选择；
   • 文件选择后自动生成；
   • 页面上下文自动带入；
   • 接口响应后只读展示；
   • 仅内部保存、不得展示或手工填写；
   • 纯前端校验字段、不得发给后端。
3. ID、Token、clientid、tenantId、OSS ID、分页参数等系统字段不得让用户手工输入。
4. 下拉框和选择器必须有真实数据源；没有选项接口时不得改成“请输入 ID”。
5. Apifox 未展开的响应 DTO、未声明的枚举和互相冲突的路径不得靠前端猜测。
6. APP 接口不得用于填补 PC 接口缺口。
7. 所有家谱内业务必须使用真实 genealogyId，不得写死示例值。
8. 每一阶段必须有契约测试、页面行为测试和真实联调结果。

2. 执行 AI 的工作协议

执行 AI 开始前必须按顺序完成：

1. 阅读项目根目录 AGENTS.md。
2. 检查工作树，只修改本计划点名的文件；保留用户已有改动。
3. 登录 Apifox，打开“家谱”项目，逐条核对实时 PC 接口详情。
4. 从 Apifox 重新导出最新 OpenAPI，和仓库 PC.openapi.json 做结构化差异比较。
5. 完成第 5 节“契约阻断项”；阻断项未解决的模块只保留页面设计，不接真实写操作。
6. 按第 8 节阶段顺序施工，每完成一阶段立即验证，不能把所有模块一次性混改。

遇到以下情况时，停止当前模块并整理成一份待后端确认清单，同时继续其他不受影响的模块：

• Apifox 页面和导出文件的 method、path、必填性、枚举或类型不一致；
• 响应仍是无属性的 ObjectResult / ListResult；
• 选择字段没有合法选项来源；
• 更新接口没有说明“字段不传”和“传 null/空串”的区别；
• 页面需要的业务能力在 PC 目录中不存在。

不得通过兼容多个旧字段、读取 APP DTO、保留旧路径 fallback 或展示原始 JSON 绕过阻断。

3. 契约依据与优先级

发生冲突时按以下顺序处理：

1. Apifox “家谱”项目中当前 PC 接口详情；
2. 从该详情当场重新导出的 OpenAPI 文件；
3. 本规划中的字段和流程分类；
4. 当前仓库代码；
5. 旧规划和历史交接记录。

通常以 Apifox 的 PC 目录作为 PC 前端接口的正式契约源。2026-07-28 用户明确指定本轮直接以 D:/WorkSpace/Java/Genealogy/doc/apifox/genealogy-pc-openapi.yaml 对接，因此该 YAML 是本轮冻结契约；在线 Apifox 的旧重复记录不再覆盖它。utils/ApiClient.js 是前端路径和请求方法的唯一 owner。页面脚本只能调用 ApiClient 业务方法，不能直接拼 URL 或调用 Axios。

旧 OpenAPI 文件不再作为新增功能依据，只用于结构化差异比较和追踪导出遗漏。

如果 Apifox 在线内容发生变化，先更新本地 OpenAPI、本规划的受影响章节和契约测试，再修改运行时代码。不得让文档、测试和运行时同时保留两套契约。

4. 当前基线与复核结论

4.1 当前导出范围

当前 PC.openapi.json 共 96 个操作、15 个标签、68 个 Schema：

模块	操作数	当前主要页面
验证中心	3	登录、注册、找回密码、安全设置
认证登录	11	login.html、register.html、forgot-password.html、个人资料和安全页
文件上传	3	所有头像、图片、附件和视频选择控件
家谱	1	profile-families.html
家族圈	14	profile-feed.html、profile-feed-edit.html、待新增动态详情页
行政区划	8	个人资料及以后需要地区的表单
字辈谱	6	profile-generation.html
世系人物	12	profile-tree.html
内容文章	1	profile-article.html、profile-article-edit.html
相册	2	profile-album.html
视频	5	profile-video.html、待新增视频编辑页
贺礼邀约	4	profile-gift.html、邀约管理面板
祭祀	2	profile-gift.html
族务记录	20	成长、亲友、备忘录、功德录页面
消息通知	4	profile-messages.html
合计	96

4.2 已对照到的 Apifox 现状

本机 Apifox 缓存中的“家谱”项目包含 APP、PC、共享区划等 246 条接口记录。当前导出的 96 条路径均能在该项目缓存的接口树中找到，但存在以下差异：

1. Apifox 缓存同时保留了两条逻辑相同的短信接口：

   • 错误旧路径：genealogy/pc/auth/sms/{operationCode}/code
   • 正确路径：/genealogy/pc/auth/sms/{operationCode}/code

   当前导出只保留正确路径。执行前必须在 Apifox 删除或正式废弃缺少 / 的旧定义，前端只实现正确路径。

2. 导出文件同时含 /genealogy/region/* 和 /genealogy/pc/region/* 两套共 8 个区划操作；两套的参数、响应和描述完全相同。执行前必须由后端选定一套唯一正式路径并删除另一套。选定后实际唯一操作数应从 96 收口为 92。

3. 旧版“85 接口规划”已经失效。新增范围主要包括 PC 区划 4 条、视频列表/新增/详情/修改 4 条、功德列表/新增/详情/修改 4 条。

4. 当前 96 个操作全部被声明为需要 Authorization，连注册、登录、短信发送和验证中心也不例外。这与未登录流程冲突，必须在 Apifox 逐项修正 security。

5. 当前有 21 个成功响应使用无业务属性的 ObjectResult，12 个使用无元素 Schema 的 ListResult；另有 LineagePersonTreeView 名义上是专用 DTO，但没有任何属性。

4.3 2026-07-28 补齐版 YAML 与在线 Apifox 复核

补齐文件 genealogy-pc-openapi.yaml 含 98 个 path、137 个 HTTP operation、17 个 tag、319 个 schema；旧 PC.openapi.json 含 71 个 path、96 个 operation、68 个 schema。补齐文件新增了家谱、成员、相册、文章、祭祀、通知、反馈、VIP 和官网内容等路径及 DTO，但它还不能替代在线 Apifox：

1. 已实际登录并打开 Apifox“家谱”项目的 PC 模块。在线概览显示 142 个接口、87 个数据模型，与补齐 YAML 的 137 个 HTTP operation 不一致。

2. 在线“认证登录”目录仍显示 12 个接口，同时存在：

   • 错误旧路径：genealogy/pc/auth/sms/{operationCode}/code
   • 正确路径：/genealogy/pc/auth/sms/{operationCode}/code

   补齐 YAML 只包含正确路径，因此 C02 在线尚未完成。

3. 补齐 YAML 给注册、密码登录、短信登录和短信发送标了 security: []；在线密码登录详情仍展示必需的 Authorization API Key，并显示 Auth 1。因此 C03 的导出定义和在线详情冲突。

4. 在线 GET /genealogy/pc/auth/profile 成功响应仍为泛型 ObjectResult；展开后的 data 只有任意附加属性，没有 ProfileView 字段。补齐 YAML 同样引用泛型 ObjectResult，C04/C06 未完成。

5. ProfileUpdateBody.avatar 仍为 integer<int64>，而 FileUploadVo.ossId、LineagePersonView.avatarOssId 等 OSS ID 为 string；部分头像字段也仍为 integer<int64>。C10 未完成。

6. 已用真实登录响应和后端 AppLoginVo 复核：token 的唯一 JSON 字段是 access_token；原 YAML 的 token、accessToken、tokenValue、userId、tenantId、clientId 均不是该响应的直接字段，现已删除。

7. ProfileUpdateBody 仍只有 nickName、realName、avatar、sex、birthday、email，没有地区字段，也没有说明缺省、null、空串的清空语义。C07/C18 未完成。

用户已明确要求本轮直接按补齐 YAML 施工，所以在线旧短信路径和公开接口 security 残留不再阻断本轮实现。YAML 自身仍存在的 profile 泛型响应、头像 ID 类型冲突和更新清空语义缺失继续保留为阻断项，前端不得自行补造。

5. 实施前必须解决的契约阻断项

以下事项不是前端自由选择，必须先在 Apifox 明确：

编号	问题	影响	完成条件
C01	两套区划路径完全重复	页面和客户端会形成双路径	Apifox 只保留一套；导出和客户端只出现一次
C02	短信接口有缺少开头 / 的旧记录	可能生成错误 URL	删除/废弃旧记录，只保留正确路径
C03	所有操作均要求 Authorization	未登录流程无法成立	注册、登录、找回、验证、短信等逐项标明公开；登录后接口明确鉴权
C04	33 个操作使用泛型对象/列表响应	列表、详情、编辑回填和 ID 来源不确定	为每个业务资源增加明确 View/DTO Schema
C05	LineagePersonTreeView 没有属性	世系树只能猜字段	补齐节点 ID、人物资料、配偶、子女和递归结构
C06	用户资料响应未展开	个人资料无法可靠回填	增加 ProfileView，明确所有可读字段
C07	ProfileUpdateBody 没有地区字段	现居地区无法保存	明确增加地区编码字段或删除“保存地区”功能
C08	区划响应没有元素 DTO	下拉选项的 code/name/level 不受契约约束	增加 RegionView 及列表/路径响应
C09	上传初始化响应未展开，却描述了 instant=true	秒传、续传和 uploadId 状态不明确	增加初始化响应 DTO，明确 instant、已传分片和 OSS 信息
C10	OSS ID 类型冲突	可能发生 JS 精度丢失或校验失败	所有 ossId、avatar、avatarOssId、视频和附件 ID 统一为 string
C11	completed 只有 string 类型，无枚举	不能决定复选框提交 0/1、true/false 或其他值	Apifox 增加枚举和中文含义
C12	feedType、recordType、registerSource 等无枚举	无法判断文本输入还是选择项	明确为自由文本，或补全枚举
C13	多个日期字段没有 format/时区规则	页面值和后端解析可能不一致	明确 date 或 date-time，并统一时区
C14	只有配额，没有我的家谱/成员入口	无法取得 genealogyId、成员或受邀用户选项	增加 PC 家谱列表/选项和成员选项接口，或明确外部上下文契约
C15	bindingMode=SPECIFIED 需要 appUserId，但无业务用户选项接口	不能提供合法选择器	增加家谱成员/业务用户选项接口
C16	邀约的 inviteeUserIds 没有选项接口	不能让管理员选择受邀人	增加同一家谱成员选项接口
C17	视频、成长、亲友、备忘、功德、通知响应未展开	无法安全展示、编辑或单条操作	分别增加资源 View 和列表/详情响应
C18	更新接口未说明缺省、null、空串语义	可选字段可能无法清空	Apifox 对每个可清空字段写明更新规则
C19	多数 View 没有 canEdit / canDelete 等权限字段	页面无法可靠决定按钮可见性	增加能力字段，或提供明确且可实现的角色规则
C20	文章、相册、祭祀只有删除操作	没有真实 ID 来源和完整资源流程	补全 PC 列表/详情/新增/修改后才开放页面

当前复核状态：

阻断项	状态	在线/补齐文件证据
C02	本轮按 YAML 解决	只实现带 / 的正确路径，不保留旧路径 fallback
C03	本轮按 YAML 解决	验证、注册、登录、短信、找回使用 security: []；其他认证接口携带 Bearer
C04/C06	阻断	profile GET 在线及 YAML 都只有泛型 ObjectResult
C07	阻断	ProfileUpdateBody 没有地区字段
C01/C08	前端按后端 PC 实链解决	只调用 /genealogy/pc/region/*；列表按 RegionSelectVo 的 regionCode/regionName/regionLevel 读取，不保留公共路径 fallback
C09	前端按后端 PC 实链解决	SysOssResumableInitVo 明确提供 uploadId/instant/ossId/url/fileName/uploadedChunks，完成响应使用 SysOssUploadVo
C10	前端边界解决	后端初始化 ossId 为 Long、完成响应为 string；浏览器统一转十进制字符串，隐藏回填且不转 Number
C13	后续日期模块仍阻断	本阶段上传与区划响应不消费日期；其他模块仍需逐字段核验 Java 日期类型
C18	阻断	未说明可选更新字段的省略、null、空串语义

阶段 0 验收标准：

• Apifox 中不存在旧短信路径和双区划路径；
• 重新导出的 OpenAPI 只包含一套正式契约；
• 公开与鉴权接口标记正确；
• 本阶段要实现的每个列表/详情都有明确响应 DTO；
• 所有枚举、日期和 ID 类型已确定；
• 将旧输入发送给后端时会明确失败，前端不保留兼容读取。

6. 页面字段分类标准

执行 AI 对每个请求字段都要采用下面一种处理类型：

类型	含义	页面处理
U：用户输入	姓名、标题、正文、手机号等	可见输入框/文本域，展示必填或选填
S：用户选择	枚举、人员、字辈、地区、状态等	单选、下拉、多选、日期或开关；选项必须有真实来源
F：文件派生	OSS ID、文件名、MD5、大小等	用户只选文件；值由上传组件生成并隐藏
A：自动填写	header、租户、上下文 ID、分页、默认值等	页面不可编辑，由统一 owner 注入
R：响应只读	创建时间、计数、发布人、状态文本等	列表、详情、徽标或只读信息
I：内部状态	token、challengeId、validToken、资源 ID 等	仅内存/安全存储/URL 中保存，不显示原值
V：前端校验	确认密码、注销确认文字等	可见但不得发给后端

通用规则：

1. 必填字段使用明确的必填标识，并在提交前校验。
2. 可选字段也必须有页面归属；不填写时直接省略，除非 Apifox 明确要求传 null。
3. 枚举必须使用选择控件，禁止自由文本。
4. 外键 ID 必须使用搜索/选择控件，禁止“请输入人物 ID”“请输入 OSS ID”。
5. sortOrder、status 这类管理字段：
   • 有管理权限时放在“高级设置”；
   • 普通用户使用隐藏默认值；
   • 后端未返回权限时不得自行开放高级设置。
6. 所有 int64 ID 在浏览器中按字符串保存和比较。
7. 响应中的 code、msg 由请求层统一处理；业务页只消费 data 或 rows/total。

7. 字段、页面和流程规划

7.1 全局自动字段

字段	类型	唯一来源	规则
clientid	A	ApiClient 配置	每个需要它的请求自动加 Header，不进入表单或 body
Authorization	I/A	登录响应 token	仅鉴权接口携带；注册登录等公开接口不携带
tenantId	A	环境配置	登录、注册、验证等自动带入，不让用户输入
genealogyId	I/A	PC 家谱上下文	profile-common.js 读取和传播；缺失时阻止家谱内请求
feedId、commentId、personId、poemId、articleId、albumId、photoId、videoId、ceremonyId、giftId、recordId、relativeId、memoId、meritId、notificationId	I/A	列表/详情响应或 URL	由被点击记录带入，禁止文本框输入
pageNum、pageSize	A/S	分页组件	页码由组件维护；用户只操作翻页/每页条数
ossId / mediaOssIds	F/I	文件上传响应	页面展示预览和文件名，隐藏保存 ID
sortOrder	S/A	高级设置或默认值	不得把空字符串转成 0；未填写时省略
status	S/A	权限化状态选择或默认值	枚举 0=正常、1=停用；不得把 1 标成“草稿”

7.2 验证中心与认证登录

页面字段矩阵

字段	必填性	类型	页面/流程	处理
operationCode	必填 path	A	所有认证动作	页面动作固定为 password-login、sms-login、register、forgot-password、phone-change 或 account-deactivate
clientid	必填 header	A	所有认证请求	ApiClient 自动注入
tenantId	必填	A	所有登录/验证表单	环境配置自动注入
subject	require 可选，challenge/verify 必填	A	验证流程	从当前手机号/账号派生，用户不重复填写
grantType	必填	A	注册、登录、短信、找回	密码动作固定 password，短信动作固定 sms
phone	必填	U	登录、注册、找回、换绑	手机号输入和格式校验
password	必填	U/A	密码登录、注册	用户输入明文，提交前生成 32 位 MD5；日志不得记录
oldPassword	必填	U/A	修改密码	同上
newPassword	必填	U/A	修改/重置密码	同上
confirmPassword	前端字段	V	注册、修改、找回	只比较一致性，不发送
smsCode	必填	U	短信登录、注册、找回、换绑、注销	4 位验证码输入
nickName	可选	U	注册	昵称输入
registerSource	可选	A	注册	当前端固定 PC；Apifox 需确认枚举
validToken	条件必填	I/A	密码登录、发送短信	验证成功后仅存内存，使用一次即清除
challengeId	必填	I/A	验证校验	挑战响应自动回填
providerCode、captchaType	可选	A	验证校验	挑战响应决定，用户不可修改
payload.track	条件必填	A	天爱验证码	控件原样生成轨迹、尺寸和时间
payload.uuid	条件必填	I/A	系统图形验证码	挑战响应回填
payload.code	条件必填	U	系统图形验证码	用户输入图片答案

天爱控件产生的嵌套字段全部属于 A，不得另做表单让用户填写：

• bgImageWidth、bgImageHeight：控件实际显示尺寸，必填；
• templateImageWidth、templateImageHeight：模板实际显示尺寸，可选；
• startTime、stopTime：操作开始和结束毫秒时间戳，必填；
• left、top：控件最终偏移，可选；
• trackList：必填轨迹数组；
• 每个轨迹点的 x、y、t、type 均由控件生成；
• data：不同验证码类型的扩展数据，原样提交。

验证和登录响应字段：

响应字段	类型	页面处理
required	R/A	决定是否进入挑战流程
providerCode、captchaType	I/A	选择正确验证码控件
sceneCode	I/R	服务端解析结果，可用于只读诊断；不得回传
ttlSeconds、expireSeconds	R/A	倒计时和过期重试
challengeId、uuid	I	只在当前挑战内保存
img	R	系统图形验证码图片
payload	I/A	天爱控件初始化数据
passed	R/A	决定校验成功或失败
validToken	I	一次性票据，不显示、不落长期存储
message	R	安全地显示验证结果
access_token	string / I	登录接口 data；密码或短信登录成功时立即保存，后续仅用于 Bearer 鉴权
expire_in	integer / I/R	登录接口 data；登录成功时取得，可用于会话到期提示，不由用户填写
client_id、clientKey、deviceType、userType	string / I/R	登录接口 data；登录成功时取得，仅作会话上下文或诊断，不回传为用户输入
profile	object / R	登录接口 data.profile；登录成功后取得，可用于页面只读展示或资料页初始回填
profile.userId、profile.tenantId、profile.userNo	integer/string、string、string / I/R	后端自动产生；不得让用户手工填写，业务 ID 超出 JS 安全整数时保持字符串
profile.phone、profile.nickName、profile.realName、profile.email	string/null / R	后端用户资料；登录成功后只读展示或作为资料页回填，编辑时仍只提交 ProfileUpdateBody 允许字段
profile.avatar	integer/string/null / R	后端头像 OSS ID；只读回填，用户换头像必须经文件选择和上传组件产生，禁止手填 OSS ID
profile.sex	enum 0/1/2 / R	后端用户资料；页面映射男/女/未知
profile.birthday	date/null / R	后端用户资料；页面按日期展示
profile.registerSource、profile.loginIp、profile.loginDate	string/null / R/I	后端自动产生；只读或内部诊断，不作为表单输入
profile.status	string / R/I	后端账号状态；只读或内部诊断，不作为表单输入
profile.clientKey、profile.deviceType	string / I/R	后端登录上下文；只读或内部诊断

认证业务流程

密码登录：

1. 用户输入手机号和密码。
2. 以 password-login + tenantId + phone 调用 require。
3. 若 required=false，直接提交密码登录。
4. 若需要验证，调用 challenge，展示服务端指定控件，再调用 verify。
5. 得到 validToken 后与 MD5 密码一起登录。
6. 成功后只读取并保存 data.access_token；token、accessToken、tokenValue 均视为非法旧响应，不做兼容读取。

短信类动作：

1. 用户输入手机号。
2. 按当前动作完成 require → challenge → verify。
3. 把一次性 validToken 提交给发送短信接口。
4. 用户输入短信码后执行短信登录、注册、找回、换绑或注销。
5. validToken 不进入最终注册、短信登录、换绑或注销 body，除非 Apifox 明确修改契约。

个人资料字段

ProfileUpdateBody 的所有字段必须进入 profile-data.html：

字段	必填性	类型	控件
nickName	可选	U	文本，最长 30
realName	可选	U	文本，最长 30
avatar	可选	F/I	图片上传、预览、删除；隐藏保存 OSS ID
sex	可选	S	男 0、女 1、未知 2，三项都要有
birthday	可选	S	日期选择器，yyyy-MM-dd
email	可选	U	email 输入，最长 100

现有页面整改点：

• 当前 avatarOssId 字段名与请求契约 avatar 不一致；
• 补齐 YAML 中 avatar 仍是 integer<int64>，但示例值已超过 JavaScript 安全整数范围；浏览器边界必须按十进制字符串保留精度，且只能由上传响应自动回填，不能转 Number 或让用户手填；
• 缺少 realName、email 和性别“未知”；
• 页面现居地区、父亲、微信/QQ、学历/职业不在 ProfileUpdateBody，不得混入保存请求；
• 在后端增加地区字段前，“保存地区”按钮必须关闭或改成纯查询演示；
• GET /auth/profile 必须补齐 ProfileView 后才能严格回填。

7.3 文件上传

用户在任何业务页只操作“选择文件、取消、重试”；下面字段全部自动产生：

阶段	字段	必填性	类型	来源
初始化	uploadId	必填	I/A	客户端生成一次并贯穿全过程
初始化	fileName	必填	F	File.name
初始化	fileMd5	必填	F	文件内容计算
初始化	totalSize	必填	F	File.size
初始化	totalChunks	必填	F	根据大小和分片大小计算
初始化	chunkSize	必填	A	上传组件统一配置，默认示例 4 MiB，最后一片除外
初始化	contentType	可选	F	File.type
分片	chunkIndex	必填	A	上传循环生成
分片	chunkMd5	必填	F	当前分片计算
分片	file	必填	F	当前 Blob
完成	uploadId/fileName/fileMd5/totalSize/totalChunks	必填	I/A/F	必须与初始化一致

响应处理：

• FileUploadVo.ossId：I，隐藏写入业务表单；
• url、thumbnailUrl：R，用于预览；
• fileName、originalName：R，用于文件列表；
• 初始化 instant=true 时直接读取 ossId/url/fileName 完成秒传；instant=false 时使用服务端 uploadId 与 uploadedChunks 跳过已上传分片；
• 初始化 Long ossId 和完成响应 string ossId 均在浏览器边界转为十进制字符串；
• 上传成功但业务保存失败时，当前契约没有释放引用接口，必须让后端补充生命周期规则。

统一由 public/js/upload-pages.js 管理分片、进度、重试、取消、MD5 和隐藏 ID。各业务页面不得复制上传算法，也不得出现“请输入 OSS ID”的可见输入框。

7.4 家谱上下文与配额

GET /genealogy/pc/genealogies/quota 只负责在 profile-families.html 展示：

响应字段	类型	页面呈现
createUsed、createLimit、createRemaining	R	创建额度已用/上限/剩余
canCreate	R	控制“创建家谱”是否可用
joinUsed、joinLimit、joinRemaining	R	加入额度已用/上限/剩余
canJoin	R	控制“加入家谱”是否可用

-1 显示为“不限”，不能参与普通减法或显示负数。

配额响应不包含 genealogyId，不能替代“我的家谱”。在 C14 完成前：

• 所有家谱内页面缺少真实 genealogyId 时必须阻止请求；
• 不显示静态家谱卡片作为真实数据；
• 不从 APP 接口获取家谱；
• 不允许用户手工输入家谱 ID。

7.5 行政区划

本 PC 前端只实现 /genealogy/pc/region/*，不调用重复的 /genealogy/region/*，也不保留 fallback。

字段	必填性	类型	页面处理
parentCode	可选 query	A/S	省级不传；选择上一级后自动查询下级
regionCode	必填 path	I/A	从被选择的区划记录带入
keyword	必填 query	U	搜索框
level	可选 query	S	1 省、2 市、3 区县、4 乡镇街道、5 村社区
limit	可选 query	A	搜索组件固定合理上限，不让用户自由输入
clientid	可选 header	A	统一请求层注入

真实 Java RegionSelectVo 已明确 regionCode、regionName、regionLevel 等字段。个人资料当前仍没有可保存的地区字段，因此区划组件只提供级联、搜索和路径回显，不提交到资料更新接口。

7.6 家族圈

页面归属：

• profile-feed.html：分页列表、点赞、轻量评论；
• profile-feed-edit.html：新增和编辑；
• 新增 profile-feed-detail.html：详情、完整评论树、回复、通知跳转和分享深链。

写入字段

字段	必填性	类型	页面处理
genealogyId	必填 path	I/A	家谱上下文
feedId	详情/修改/删除必填	I/A	列表记录或 URL
feedType	可选	A 或 S	当前默认隐藏 text；Apifox 补枚举后才能改成选择
feedContent	必填	U	正文编辑器
mediaOssIds	可选	F/I	多文件上传结果拼成英文逗号串，用户只看缩略图
sortOrder	可选	S/A	管理员高级设置；普通发布默认省略/0
status	可选	S/A	0 正常、1 停用；不得显示为“发布/草稿”
parentCommentId	可选	I/A	点击“回复”后自动带入；一级评论省略或 null
commentContent	必填	U	评论输入，最多 1000 字
pageNum/pageSize	可选	A/S	分页组件

动态响应字段

字段	页面处理
feedId、genealogyId	I，用于路由和后续操作
genealogyNo、genealogyName	R，详情来源信息
publisherUserId	I，用于权限判断，但不能单独代替后端鉴权
publisherNickName、publisherStatus	R，发布人和状态
feedType、feedContent	R，类型和正文
mediaOssIds	I/F，解析后通过文件 URL 规则展示，不直接显示 ID
likedByMe	R，决定点赞按钮状态
likeCount、commentCount	R，计数
pinned、pinnedTime	R，置顶徽标和时间
sortOrder、status	R/管理信息
remark	R，仅在产品确认需要时展示，不能当正文
createTime、updateTime	R，发布时间和编辑时间

评论响应字段：

• commentId、genealogyId、feedId、parentCommentId、appUserId、parentAppUserId：I；
• appUserNickName、appUserAvatar、parentAppUserNickName：R；
• commentContent：R；为 null 且 userDeleted=1 时显示“该评论已删除”占位；
• replyCount：R，控制“展开回复”；
• commentLevel：R，root 或 reply；
• status、createTime：R。

流程：

1. 列表首屏调用分页接口，不同时调用非分页接口重复取数。
2. 点击记录进入详情，以 genealogyId + feedId 取详情。
3. 一级评论调用 comments 分页；回复只调用对应 comment 的 replies 分页。
4. 点赞、取消、评论、删除成功后以接口返回和重新读取结果校正计数。
5. 删除有回复的评论后保留占位，不从 DOM 直接移除整棵回复。

7.7 字辈谱

profile-generation.html 同时提供“单条维护”和“批量维护”。

单条字段：

字段	必填性	类型	控件
generationNo	必填	U/S	正整数世代序号
generationText	必填	U	最长 50
description	可选	U	文本域，最长 500
sortOrder	可选	U/S	管理员高级数字字段
status	可选	S	0 正常、1 停用
poemId	修改必填 path	I/A	列表记录

批量字段：

字段	必填性	类型	控件
poemText	必填	U	文本域，最长 26000；支持合同中列出的分隔符
disableMissing	可选	S	复选框，必须有“将停用后续世代、不删除历史”的确认说明

批量流程必须是 preview → 用户检查 → save：

• 预览展示 createCount、updateCount、keepCount、disableCount；
• 逐项结果来自 items；每项展示 generationNo、oldGenerationText、newGenerationText、oldStatus、newStatus、action、warning；
• poemId、genealogyId 是内部字段；
• 保存前再次确认，因为服务端会基于最新数据重新计算差异。

普通展示列表使用正常字辈接口；管理页面使用 management 接口以包含停用项。

7.8 世系人物

全部操作集中在 profile-tree.html，详情和编辑可使用抽屉/弹窗，但所有字段都要有明确控件。

字段	必填性	类型	页面处理
bindingMode	必填	S	NONE 不绑定、SELF 当前账号、SPECIFIED 指定账号
appUserId	SPECIFIED 时必填	S/I	从真实业务用户选项选择；没有接口时禁用 SPECIFIED，禁止文本 ID
personNo	可选	U/A	高级设置可填；留空由服务端生成
name	必填	U	姓名
aliasName	可选	U	别名/曾用名
sex	可选	S	0 男、1 女、2 未知
generation	可选	S/I	从正常字辈列表选择世代
generationName	可选	A/R	随字辈选项自动回填并只读显示
fatherId	可选	S/I	世系人物搜索选择器
motherId	可选	S/I	世系人物搜索选择器
avatarOssId	可选	F/I	上传头像自动回填
birthDate	可选	S	date-time 选择器
birthLunar	可选	S	0 公历、1 农历开关
birthPlace	可选	U	出生地文本
deathDate	可选	S	date-time 选择器
deathLunar	可选	S	0 公历、1 农历开关
deathPlace	可选	U	逝世地
burialPlace	可选	U	安葬地
personStatus	可选	S	0 健在、1 已故、2 未知
biography	可选	U	人物简介
sortOrder	可选	U/S	管理高级设置
remark	可选	U	备注
relationName	可选	U	仅“添加配偶”快捷流程显示

人物响应字段按以下方式使用：

• personId、genealogyId、appUserId、fatherId、motherId、avatarOssId：I；
• genealogyName、genealogyNo：R；
• appUserNickName：R，显示绑定账号；
• personNo、name、aliasName、sex、generation、generationName：R/编辑回填；
• fatherName、motherName、spouseNames：R；
• 出生、逝世、安葬、状态、简介、备注、排序字段：R/编辑回填。

关系流程：

1. 先选中一个现有 personId 作为关系锚点。
2. 点击父母、子女、兄弟姐妹或配偶。
3. 打开完整 LineagePersonBody 表单，创建的是一个新人物并建立关系，不是绑定两个现有人物 ID。
4. 配偶流程才显示 relationName。
5. 当前没有解除关系接口，页面不得伪造“解除关系”。
6. DELETE 是逻辑停用；存在正常子女时可能失败，确认文案不能写成物理删除。

列表筛选：

• keyword：U，搜索姓名、别名或人物编号；
• generation：S，从字辈接口选择；
• personStatus：S，0/1/2；
• pageNum/pageSize：分页组件自动维护。

LineagePersonTreeView 补全前，不得继续依靠多个字段 fallback 猜树结构。

7.9 视频

计划新增 profile-video-edit.html，profile-video.html 负责列表。

字段	必填性	类型	页面处理
videoTitle	必填	U	标题
videoDesc	可选	U	说明文本域
coverOssId	可选	F/I	封面上传、预览、隐藏 ID
videoOssId	必填	F/I	视频文件上传；不得输入 ID
durationSeconds	可选	F/A/R	从视频元数据读取，只读显示
sortOrder	可选	U/S	管理高级设置
status	可选	S	0 正常、1 停用
genealogyId、videoId	path	I/A	上下文和记录

流程：选视频 → 分片上传 → 得到 videoOssId → 可选封面上传 → 填标题说明 → 保存 → 重新读取详情。

当前视频列表、详情、新增和修改均返回泛型对象/列表。C17 完成前可以完成静态表单布局和 ApiClient 契约测试，但不得把真实 CRUD 页面标记为已完成。

7.10 贺礼邀约与祭祀

邀约字段：

字段	必填性	类型	页面处理
inviteeUserIds	必填	S/I	家谱成员多选；提交完整名单，空数组表示取消全部未响应邀请
inviteStatus	必填	S	当前用户只能选择 ACCEPTED 接受或 DECLINED 拒绝
genealogyId、ceremonyId	path	I/A	活动上下文

邀约响应在 profile-gift.html 展示：

• invitationId、genealogyId、ceremonyId、inviteeUserId：I；
• inviteStatus：R，PENDING/ACCEPTED/DECLINED/CANCELED 徽标；
• inviteVersion：I/R，只在管理审计需要时显示；
• deliveredTime、readTime、responseTime：R；
• ceremonyTitle、ceremonyTime、location、locationAddress：R；
• longitude、latitude：地图定位内部值，页面显示地图/地址而非原始数字。

“我的邀请”接口有完整响应，可独立实现接受/拒绝流程。管理端替换受邀人依赖 C16，且必须先有真实活动 ID。

当前没有祭祀活动列表、详情、新增、修改和献礼列表/新增接口。现有 profile-gift-edit.html 中的 ceremonyType、ceremonyTitle、ceremonyTime、location、ceremonyDesc、coverOssId 不属于任何现有 PC 写入 DTO，必须继续保持禁用，不得向猜测路径提交。

两条删除接口只能在后端补齐列表和详情、产生稳定 ID 后开放：

• 删除活动是逻辑删除活动及祭品并释放封面引用；
• 删除祭品只操作被选中的真实 giftId；
• 删除确认必须说明影响范围。

7.11 成长记录

页面：profile-growth.html、profile-growth-edit.html。

字段	必填性	类型	页面处理
lineagePersonId	可选	S/I	世系人物搜索选择器，禁止 ID 输入框
recordType	可选	U 或 S	C12 未解决前按 Apifox 明确结果决定，不能猜枚举
recordTitle	必填	U	标题
recordContent	可选	U	正文编辑器
recordDate	可选	S	日期控件，等待 C13 明确格式
remindTime	可选	S	日期时间控件
mediaOssIds	可选	F/I	多附件上传
sortOrder	可选	U/S	管理高级设置
status	可选	S	0 正常、1 停用

列表、详情、新增和修改响应仍是泛型对象。补齐 GrowthRecordView 前不得展示原始 JSON，也不得猜 recordId 开启编辑和删除。

7.12 亲友记录

页面：profile-relative.html、profile-relative-edit.html。

字段	必填性	类型	页面处理
relativeName	必填	U	亲友姓名
relationName	可选	U	关系名称
eventName	可选	U	事件名称
eventTime	可选	S	日期时间选择器
giftAmount	可选	U	金额输入，明确精度和非负规则后校验
recordContent	可选	U	内容
mediaOssIds	可选	F/I	多附件上传
sortOrder	可选	U/S	管理高级设置
status	可选	S	0 正常、1 停用

补齐 RelativeRecordView 前只完成页面字段布局和请求契约，不开放真实列表、编辑和删除。

7.13 备忘录

页面：profile-memo.html、profile-memo-edit.html。

字段	必填性	类型	页面处理
memoTitle	必填	U	标题
memoContent	可选	U	内容
remindTime	可选	S	日期时间
completed	可选	S	应为开关；C11 明确提交值前保持禁用
mediaOssIds	可选	F/I	多附件上传
sortOrder	可选	U/S	管理高级设置
status	可选	S	0 正常、1 停用

completed 表示业务完成状态，status 表示记录正常/停用，两者不能合并。补齐 MemoView 前不得猜 memoId 或响应字段。

7.14 功德记录

页面：profile-merit.html、profile-merit-edit.html。

字段	必填性	类型	页面处理
donorName	必填	U	功德人姓名
meritType	可选	S	donation 捐赠、repair 修祠、public 公益、other 其他
meritTitle	必填	U	标题
meritContent	可选	U	内容
amount	可选	U	金额
meritTime	可选	S	date-time
sortOrder	可选	U/S	管理高级设置
status	可选	S	0 正常、1 停用

现有页面错误地使用了 service，但契约枚举中不存在该值；必须删除 service，增加 repair 和 public。现有页面还缺少 sortOrder、status。

列表、详情、新增和修改仍是泛型响应。补齐 MeritRecordView 后再开放完整 CRUD。

7.15 消息通知

页面：profile-messages.html。

字段	必填性	类型	页面处理
readStatus	可选 query	S	全部=省略、未读=0、已读=1
notificationId	单条已读必填 path	I/A	从被点击通知记录带入
未读数量 data	响应	R	顶部徽标，int64 按安全数值/字符串处理

通知列表当前是 ListResult<object>，没有通知 ID、标题、正文、类型、时间、已读状态和目标深链。补齐 NotificationView 前：

• 可以调用未读数量和全部已读；
• 不得展示原始对象；
• 不得猜 notificationId 开放单条已读；
• 不得根据未声明字段拼详情跳转。

7.16 当前只有删除能力的模块

模块	当前操作	页面策略
内容文章	删除文章	profile-article* 保持设计；没有列表/详情时不开放删除
相册	删除相册、删除照片	profile-album.html 保持设计；不使用静态 ID 调删除
祭祀	删除活动、删除祭品	活动 CRUD 和礼物列表补齐前保持禁用

删除按钮必须由真实响应中的 ID 和权限字段产生。禁止用 DOM 序号、示例 ID 或 URL 猜测资源 ID。

8. 分阶段执行顺序

阶段 0：冻结契约

工作：

1. 完成第 5 节 C01-C20 的本阶段相关项。
2. 从 Apifox 重导 OpenAPI。
3. 写契约快照测试，统计操作、请求字段、required、枚举、response $ref。
4. 确认旧路径和旧字段会失败，不保留兼容代码。

验证：

• JSON 可被解析；
• 实际接口数与收口后的 Apifox 一致；
• 0 个重复逻辑路径；
• 本轮实现模块不存在泛型业务响应；
• 登录注册等公开接口不带 Authorization。

阶段 1：请求基础设施、验证和认证

工作：

1. 收口 config.js、AxiosRequestUtil.js、ApiClient.js 的 header、token、tenant 和错误处理。
2. 完成验证中心、登录、注册、短信、找回、换绑、注销、退出。
3. 完成个人资料全部 6 个写入字段。
4. 为每条认证流程测试 body 中不存在 clientId、sceneCode 和旧验证码字段。

验证：

• 密码、短信两种登录成功；
• 验证策略开/关两条路径都成功；
• 一次性 validToken 不能复用；
• 401 清除登录态，403 保留登录态；
• 确认密码等 V 类字段未进入请求。

阶段 2：文件上传和区划

前提：C01、C08、C09、C10、C13 完成。

工作：

1. 实现单分片小文件和多分片大文件同一流程。
2. 实现秒传、进度、重试、重复提交锁。
3. 只保留一套区划 API，并实现级联、搜索、路径回显。
4. 所有业务页移除可见 OSS ID 输入框。

验证：

• 普通图片、最后一片不足 chunkSize、大视频、秒传分别通过；
• MD5、大小、分片数量与初始化一致；
• 页面刷新后的业务对象能重新显示文件；
• 区划不同时请求两套路径。

阶段 3：家谱上下文

前提：C14 完成，或产品正式给出可验证的外部上下文契约。

工作：

1. profile-common.js 成为 genealogyId 的唯一 owner。
2. 我的家谱页提供真实选择入口。
3. 所有家谱内链接传播同一个 ID，切换家谱时清空旧页面状态。

验证：

• 无 ID 不发请求；
• 切换两个家谱不串数据；
• ID 始终按字符串处理；
• 不存在示例 ID 和 APP 请求。

阶段 4：已具备明确 DTO 的家谱模块

顺序：

1. 家族圈；
2. 字辈谱；
3. 世系人物；
4. 我的贺礼邀请。

每个模块采用同一闭环：

1. ApiClient 方法和契约测试；
2. 列表/详情读取；
3. 新增；
4. 修改；
5. 删除/停用；
6. 权限、空状态、错误状态、重复提交；
7. 写入后重新读取验证。

阶段 5：补齐 DTO 后的资源模块

顺序：

1. 视频；
2. 成长记录；
3. 亲友记录；
4. 备忘录；
5. 功德记录；
6. 消息通知。

任何模块的 View/List DTO 未补齐时，只完成表单布局和契约测试，不宣称真实功能完成。

阶段 6：后端补齐后再开放的模块

范围：

• 文章；
• 相册/照片；
• 祭祀活动/祭品；
• 管理员邀约名单；
• 指定账号绑定世系人物；
• 家谱和成员管理；
• 世系关系解除。

这些模块不允许通过 APP 接口或猜测路径提前实现。

9. 文件级施工建议

执行 AI 应优先修改现有 owner，避免页面各自复制逻辑：

文件	职责
PC.openapi.json	当次 Apifox 导出快照，不手工补字段
config.js	环境、API 基础地址、非敏感客户端配置
utils/ApiClient.js	所有正式 PC method/path/query/body
utils/AxiosRequestUtil.js	header、鉴权、响应解包、401/403
utils/FormUtil.js	表单取值、空可选字段省略、前端校验
public/js/profile-common.js	登录页外的家谱上下文
public/js/upload-pages.js	唯一上传流程
public/js/auth-pages.js / security-pages.js	认证业务流程
public/js/feed-pages.js	家族圈
public/js/generation-pages.js	字辈
public/js/lineage-pages.js	世系
public/js/growth-pages.js、relative-pages.js、memo-pages.js	对应族务记录
新增专用视频/功德/邀约脚本	仅在 DTO 完整后新增

不得创建一个包揽所有业务的巨型页面脚本，也不得为了单一页面引入通用框架。

10. 测试与验收

10.1 必须新增或更新的测试

1. OpenAPI 契约快照：
   • operation 数；
   • method/path；
   • body Schema；
   • required；
   • enum；
   • response $ref；
   • 公开/鉴权标记。
2. ApiClient 契约测试：
   • URL、query、body、header；
   • int64 ID 不转 Number；
   • 可选空字段被省略；
   • 旧路径/旧字段不存在。
3. 页面字段覆盖测试：
   • 每个请求 Schema 字段都能在本规划的 U/S/F/A/I/V 分类中找到；
   • 用户可编辑字段有对应 name；
   • 自动字段没有可见文本输入；
   • 枚举选项和值与 Apifox 一致。
4. 流程测试：
   • 验证与短信；
   • 上传；
   • 家谱上下文；
   • 列表 → 详情 → 编辑 → 重读；
   • 删除/停用；
   • 401/403/404/409/422/429。
5. 安全测试：
   • 富文本经过净化；
   • 密码、token、validToken 不写日志；
   • 外链和上传文件类型受限；
   • 错误消息不直接插入 HTML。

10.2 建议验证命令

先跑最小相关测试，再跑全量：

node --test tests/api-client-contract.test.js
node --test tests/auth-pages.test.js tests/captcha-pages-contract.test.js
node --test tests/feed-pages.test.js tests/generation-pages.test.js tests/lineage-pages.test.js
node --test tests/growth-pages.test.js tests/relative-pages.test.js tests/memo-pages.test.js tests/notification-pages.test.js
node --test tests/*.test.js

执行 AI 若新增测试文件，应在本节补上精确命令。

10.3 模块完成定义

一个模块只有同时满足以下条件才可标记完成：

1. Apifox 契约无未决冲突。
2. 所有请求字段已分类并落到页面。
3. 列表和详情响应有明确 DTO。
4. ApiClient 不存在旧路径或 fallback。
5. 页面有加载、空、成功、校验失败、无权限和网络失败状态。
6. 写操作防重复提交。
7. 成功写入后通过重新读取验证。
8. 相关测试和全量测试通过。
9. 没有原始 JSON、手填 ID、示例业务数据或 APP 接口冒充真实能力。

11. 执行完成后的报告格式

执行 AI 每个阶段只报告：

Changed: 修改了哪些 owner、页面和契约。
Verified: 运行了哪些测试，真实联调覆盖了哪些流程。
Blocked: 哪些字段或流程仍缺 Apifox/后端契约，具体缺什么。
Next: 下一阶段可以开始的最小范围。

不得用“应该可以”“大概完成”代替测试证据。