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	已由后端 PC 实链接决	GET /genealogy/pc/genealogies/mine 和 /options 返回完整 AppGenealogyVo，genealogyId 从响应取得	前端只从真实列表选择，不允许手填 ID
C15	bindingMode=SPECIFIED 需要 appUserId，但无业务用户选项接口	不能提供合法选择器	增加家谱成员/业务用户选项接口
C16	邀约的 inviteeUserIds 没有选项接口	不能让管理员选择受邀人	增加同一家谱成员选项接口
C17	视频、成长、亲友、备忘、功德、通知响应未展开	无法安全展示、编辑或单条操作	分别增加资源 View 和列表/详情响应
C18	更新接口未说明缺省、null、空串语义	可选字段可能无法清空	Apifox 对每个可清空字段写明更新规则
C19	多数 View 没有 canEdit / canDelete 等权限字段	页面无法可靠决定按钮可见性	增加能力字段，或提供明确且可实现的角色规则
C20	文章、相册、祭祀只有删除操作	没有真实 ID 来源和完整资源流程	补全 PC 列表/详情/新增/修改后才开放页面
C21	家族圈动态只返回 mediaOssIds，PC 没有 OSS ID 批量解析/访问 URL 接口	已上传图片只能统计数量，不能在列表和详情安全回显缩略图	PC 增加按 OSS ID 返回授权 URL、文件名和媒体类型的接口，或让动态 View 直接返回媒体对象数组
C22	停用动态不会出现在普通列表，普通详情接口也拒绝读取	管理员可以停用，但停用后无法从 PC 页面重新读取、恢复或验证最终状态	增加包含停用记录的管理列表/详情，或增加独立的状态恢复接口
C23	VideoVo 只返回 coverOssId / videoOssId，没有 PC 文件访问 URL 或解析接口	可以维护视频记录，但不能安全播放视频或回显封面	视频 View 直接返回授权 URL，或增加按 OSS ID 获取文件访问地址的 PC 接口
C24	视频列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法从页面重新读取和恢复	增加视频 management 列表/详情，或增加独立状态恢复接口
C25	GrowthRecordVo 只返回附件 mediaOssIds，没有 PC 文件访问 URL 或解析接口	可以维护附件引用，但不能安全预览、下载或回显文件名	成长记录 View 返回附件对象，或增加按 OSS ID 获取授权地址、文件名和类型的 PC 接口
C26	成长记录列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法写后重读、恢复或再次编辑	增加成长记录 management 列表/详情，或增加独立状态恢复接口
C27	giftAmount 只有 number / BigDecimal 类型，没有精度、范围和正负规则	前端不能自行限定两位小数、最大金额或禁止负数	Apifox 明确 scale、precision、minimum/maximum 和负数业务含义
C28	RelativeRecordVo 只返回附件 mediaOssIds，没有 PC 文件访问 URL 或解析接口	可以维护附件引用，但不能安全预览、下载或回显文件名	亲友记录 View 返回附件对象，或增加按 OSS ID 获取授权地址、文件名和类型的 PC 接口
C29	亲友记录列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法写后重读、恢复或再次编辑	增加亲友记录 management 列表/详情，或增加独立状态恢复接口
C30	MemoVo 只返回附件 mediaOssIds，没有 PC 文件访问 URL 或解析接口	可以维护附件引用，但不能安全预览、下载或回显文件名	备忘录 View 返回附件对象，或增加按 OSS ID 获取授权地址、文件名和类型的 PC 接口
C31	备忘录列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法写后重读、恢复或再次编辑	增加备忘录 management 列表/详情，或增加独立状态恢复接口
C32	功德金额只有 number / BigDecimal 类型，没有精度、范围和正负规则	前端不能自行限定两位小数、最大金额或禁止负数	Apifox 明确 scale、precision、minimum/maximum 和负数业务含义
C33	功德记录列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法写后重读、恢复或再次编辑	增加功德记录 management 列表/详情，或增加独立状态恢复接口
C34	YAML NotificationView 声明了家谱编号/名称、发送人昵称/手机号和业务摘要，但 PC toVo 未填充这些字段	页面可能长期显示空白，导出契约与真实 PC 响应不一致	后端补齐字段，或从 PC Schema 删除不会返回的字段并明确隐私策略
C35	PC 谱文后端列表支持可选 categoryId，YAML 未声明该 query，且没有文章分类选项接口	前端无法可靠提供分类筛选或编辑分类	YAML 补齐 query，并提供当前家谱文章分类选项接口
C36	ArticleVo 只返回 coverOssId，没有 PC 文件访问 URL	谱文可维护封面引用，但不能安全回显封面图片	Article View 返回封面 URL，或增加 OSS ID 授权解析接口
C37	谱文列表只返回正常记录，详情拒绝读取停用记录	status=1 后无法写后重读或恢复	增加谱文 management 列表/详情，或独立状态恢复接口
C38	AlbumVo / AlbumPhotoVo 只返回 coverOssId / ossId，没有 PC 文件访问 URL	相册和照片记录可维护，但不能安全回显封面或照片内容	View 返回授权 URL，或增加 OSS ID 授权解析接口
C39	相册和照片列表只返回正常记录，且没有停用记录的 management 入口	status=1 后无法从页面重读、恢复或再次编辑	增加相册/照片 management 列表，或独立状态恢复接口
C40	CeremonyVo 只返回 coverOssId，没有 PC 文件访问 URL	活动记录可维护，但不能安全回显封面	View 返回封面授权 URL，或增加 OSS ID 授权解析接口
C41	活动列表和详情只允许读取正常记录	status=1 后无法从页面重读、恢复或再次编辑	增加活动 management 列表/详情，或独立状态恢复接口
C42	CeremonyGiftBody.giftAmount 的 YAML 没有精度和最大值，后端实际拒绝负数	页面可按后端约束拒绝负数，但不能自行限定小数位或最大金额	YAML 补充 minimum、scale、precision 和 maximum
C43	YAML 成员更新角色枚举含 owner/visitor，PC 后端 DTO 只接受 admin/editor/member	按 YAML 展示会产生必然失败的写入	YAML 收紧枚举；本轮前端按 PC 后端校验冻结为三种可分配角色
C44	GenealogyMemberVo 声明昵称、手机号、家谱和世系人物名称等字段，PC toVo 实际只填充 ID、成员名、角色、关系、来源和时间	列表部分说明可能长期为空，手机号还有隐私风险	后端补齐非敏感展示字段并删除手机号，或从 PC Schema 删除不会返回的字段
C45	PC 没有世系关系解除接口	页面无法合法解除父母、配偶、子女或兄弟姐妹关系	后端增加带权限和关系完整性校验的解除接口
C46	成员更新只在 lineagePersonId != null 时写入，没有解除成员与世系人物绑定的语义	下拉留空只能表示“不修改”，不能完成解绑	增加明确解绑接口或约定可验证的 null/空值语义

当前复核状态：

阻断项	状态	在线/补齐文件证据
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
C11（备忘录）	本轮按后端 PC 实链解决	YAML 仍只有 string；PC AppMemoServiceImpl 明确校验 completed 只能为 0/1，含义为否/是，前端冻结为未完成/已完成
C13	后续日期模块仍阻断	本阶段上传与区划响应不消费日期；其他模块仍需逐字段核验 Java 日期类型
C17（成长记录）	本轮按后端 PC 实链解决	YAML 响应仍为泛型；PC PcGrowthRecordController 明确返回 GrowthRecordVo，前端只冻结该 PC 响应，不读取 APP 路径
C17（亲友记录）	本轮按后端 PC 实链解决	YAML 响应仍为泛型；PC PcRelativeRecordController 明确返回 RelativeRecordVo，前端只冻结该 PC 响应，不读取 APP 路径
C17（备忘录）	本轮按后端 PC 实链解决	YAML 响应仍为泛型；PC PcMemoController 复用的 PC 支持层明确返回 MemoVo，前端只冻结该 PC 响应，不读取 APP 路径
C17（功德记录）	本轮按后端 PC 实链解决	YAML 响应仍为泛型；PC PcMeritRecordController 复用的 PC 支持层明确返回 MeritRecordVo，前端只冻结该 PC 响应，不读取 APP 路径
C17（消息通知）	本轮按 YAML 详情 DTO 和后端 PC 实链解决	详情为完整 NotificationView；列表导出仍是泛型数组，但 PC 控制器实际返回同一 NotificationVo。前端只接受直接数组，不读取 APP 路径
C20（谱文）	本轮按后端 PC 实链解决	PC 控制器实际具备列表、详情、新增、修改、删除并返回 ArticleVo；页面不再只开放删除
C18	阻断	未说明可选更新字段的省略、null、空串语义
C34	阻断非核心展示	PC 实际未填充 genealogyNo/genealogyName/senderNickName/senderPhone/bizSummary；页面兼容空值并始终隐藏手机号，核心通知读取和已读闭环不依赖这些字段
C35	阻断分类能力	本轮不发送 YAML 未声明的 categoryId query，也不提供手填分类 ID
C36/C37	阻断非核心展示/停用管理	本轮不猜封面 URL，并固定提交 status=0，避免产生不可重读谱文
C20（相册/照片）	本轮按后端 PC 实链接决	PC 控制器具备相册列表、新增、修改、删除和照片列表、新增、删除；页面只从响应取得稳定 ID
C38/C39	阻断非核心展示/停用管理	本轮不猜文件 URL，并固定提交 status=0，避免产生不可重读的相册或照片
C20（祭祀活动/祭品）	本轮按后端 PC 实链接决	PC 控制器具备活动完整 CRUD 和祭品列表、新增、删除；页面只使用响应中的稳定 ID
C16	本轮按后端 PC 实链接决	members/options 返回同一家谱成员及真实 appUserId；管理员邀约名单只允许选择正常且已绑定账号的成员
C15	本轮按后端 PC 实链接决	members/options 是当前家谱真实业务账号的唯一选择源；SPECIFIED 只提交正常且已绑定账号成员的 appUserId
C40/C41	阻断非核心展示/停用管理	本轮不猜封面 URL，并固定提交 status=0，避免产生不可重读活动
C42	阻断金额精度/上限	前端只执行后端已确认的非负校验，不自行限制小数位和最大金额
C43	前端按后端 PC 实链收紧	成员角色选择器只允许 admin/editor/member；不发送 YAML 中后端拒绝的 owner/visitor
C44	阻断非核心 enrichment	页面兼容未填充名称，始终隐藏成员、邀请人手机号和内部用户 ID；核心成员管理不依赖这些字段
C45/C46	阻断	页面不提供世系关系解除，也不把空 lineagePersonId 解释为解绑

阶段 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，不能替代“我的家谱”。当前由 GET /genealogy/pc/genealogies/mine 返回完整 AppGenealogyVo：

• profile-families.html 从真实列表生成家谱入口；
• genealogyId 在浏览器边界保持字符串，并由 profile-common.js 统一读取和传播；
• 所有家谱内页面缺少真实 genealogyId 时必须阻止请求并回到家谱选择入口；
• 不显示静态家谱卡片，不从 APP 接口获取家谱，不允许用户手工输入家谱 ID；
• 切换家谱通过进入新的带 genealogyId URL 完成整页导航，旧页面模块状态不会复用。

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 直接移除整棵回复。

2026-07-28 家族圈实施状态：

• ApiClient 的 14 个家族圈 PC 操作已由契约测试锁定；页面首屏只调用 /feeds/page，评论和回复分别调用各自的 /page。
• 已新增 profile-feed-detail.html，以 genealogyId + feedId 形成稳定详情深链；列表、详情和编辑链接都保留字符串 ID。
• 列表和详情消费 AppFamilyFeedVo 的发布人、点赞状态与计数、评论计数、置顶、状态和时间字段；评论消费 FamilyFeedCommentVo 的归属、父评论、层级、删除占位、回复计数和时间字段。
• GET /genealogy/pc/genealogies/{genealogyId} 的 canEditContent/canManage 控制编辑和高级设置，GET /genealogy/pc/auth/profile 的 userId 结合响应中的发布人/评论人 ID 控制本人删除按钮；后端仍执行最终权限校验。
• 发布图片只允许文件选择；mediaOssIds 为隐藏的上传派生字段，多文件结果使用英文逗号连接，不允许手填 OSS ID。
• 新增、修改、点赞、取消点赞、评论和删除均有同资源动作锁；成功后重新读取详情、分页列表或评论分页以校正页面状态。
• status=1 使用后端定义的“停用”语义，不再显示为“草稿”。C21、C22 未解决前，图片缩略图回显和停用记录恢复仍属于后端阻断，不宣称这两项闭环完成。
• 已在真实 Chrome 登录态验证：当前账号的 /genealogies/mine 返回空列表；无家谱上下文时家族圈不发业务请求，所有发布入口统一改写到 profile-families.html?next=profile-feed-edit.html。发布表单实测为多文件选择、隐藏 OSS ID、普通用户隐藏且禁用管理字段。由于账号没有家谱，本轮不能进行真实动态列表/详情读取或写操作联调。

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 接口以包含停用项。

当前实现状态：

• 页面先读取家谱详情，以 canEditContent 决定调用正常列表还是 management 列表；无维护权限时不渲染新增、编辑、停用和批量维护控件，后端继续执行最终权限校验。
• genealogyId 只来自家谱上下文，poemId 只来自列表响应；所有业务 ID 在浏览器边界保持字符串，不提供手工 ID 输入。
• 单条新增、修改和状态切换成功后重新读取列表；批量维护严格执行 preview → 当前请求体签名确认 → save → 重新读取列表。
• 批量预览逐项校验 action、状态、必需的新旧文本和内部 ID，并核对四类汇总计数；勾选 disableMissing 时保存确认明确说明只停用后续世代、不删除历史。
• 已在真实 Chrome 登录态验证无家谱上下文分支：不发送字辈业务请求，新增按钮和批量面板隐藏，家谱上下文入口统一返回家谱选择页。当前账号家谱列表为空，因此正常/management 列表、单条写入和批量写入仍缺少真实家谱数据联调证据。

7.8 世系人物

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

字段	必填性	类型	页面处理
bindingMode	必填	S	NONE 不绑定、SELF 当前账号、SPECIFIED 指定账号
appUserId	SPECIFIED 时必填	S/I	从当前家谱 members/options 的正常且已绑定账号成员中选择；禁止文本 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 猜树结构。

当前实现状态：

• 已接入 PC 世系树、普通列表、分页列表、人物选项、详情、新增、修改、逻辑停用，以及父母、子女、兄弟姐妹、配偶四类关系新增；成功写入后统一重新读取树、列表、分页和选项，返回稳定 personId 时再读取详情。
• 页面先读取家谱详情，canEditContent 只控制新增、编辑、停用和关系维护；树、列表、详情、筛选和分页保持只读可用，后端继续执行最终查看和编辑权限校验。
• LineagePersonBody 的全部字段均有明确来源：世代从正常字辈列表选择并自动回填字辈，父母从世系人物选项选择，头像通过统一上传组件产生隐藏 avatarOssId，所有业务 ID 在浏览器边界保持字符串且不可手填。
• 新增和编辑人物开放 NONE、SELF、SPECIFIED；SPECIFIED 选择器只消费当前家谱 members/options，过滤未绑定账号、停用成员和当前账号，不显示手机号，不允许手填 appUserId。
• 编辑已绑定其他账号的人物时，用详情响应的 appUserId 精确匹配同一成员选项；真实选项不存在时不伪造回填，保存会被前端校验阻止。
• 分页查询已接入 keyword、generation、personStatus、pageNum/pageSize；详情展示家谱、绑定账号、父母、配偶、出生、逝世、安葬、人物状态、简介和备注等响应字段。
• DELETE 确认明确使用“停用”语义，并提示存在正常子女时后端会拒绝；页面没有伪造解除关系或物理删除。
• 已在真实 Chrome 登录态验证无家谱上下文分支：不发送世系业务请求，读区域显示选择家谱提示，新增、关系维护和完整表单隐藏，分页与配偶专用字段不误显示，所有家谱链接返回家谱选择页。当前账号家谱列表为空，因此真实树、列表、详情和写操作仍缺少有数据账号联调证据。
• C18 仍适用于本模块：可选字段清空语义未明确，本轮仅提交非空值，不宣称可选字段清空闭环。
• SPECIFIED 账号绑定相关聚焦测试 42/42 通过；真实账号页面验证统一留到阶段 6 收尾执行。

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 → 可选封面上传 → 填标题说明 → 保存 → 重新读取详情。

YAML 的视频响应仍使用泛型 ObjectResult / ListResult，但后端已存在独立 PcVideoController，其 PC method/path 与 YAML 一致，并明确返回 VideoVo。根据本轮“后端源码可作为可靠补充契约”的约定，页面响应字段由该 PC 控制器及 VideoVo 冻结：

• I：videoId、genealogyId、coverOssId、videoOssId、publisherUserId；
• R：genealogyNo、genealogyName、surname、publisherNickName、publisherPhone、publishTime、viewCount、remark；
• U/R：videoTitle、videoDesc；
• F/A/R：durationSeconds；
• U/S/R：sortOrder；
• A/R：status，当前固定提交 0。

当前接入状态：

• profile-video.html 已接入正常视频列表、详情读取、权限化编辑/删除入口、空错状态和无家谱上下文分支；
• 新增 profile-video-edit.html，新增和修改只提交 VideoBody 七个字段；视频与封面都通过统一分片上传产生隐藏 OSS ID，不允许手填；
• 选择视频文件后由浏览器媒体元数据自动读取时长，durationSeconds 只读；
• 保存成功后使用稳定 videoId 重新读取详情，再返回列表；删除确认明确会释放视频和封面文件引用，删除后重读列表；
• 后端 BigNumberSerializer 对超出 JavaScript 安全整数范围的 Long 输出字符串，对安全整数输出 number；前端接受两种输入并统一保留为字符串；
• C23 未解决前只显示文件“已上传”，不猜测 OSS URL，不宣称播放或封面预览完成；
• C24 未解决前不开放 status=1，避免产生无法重新读取和恢复的停用视频；
• 2026-07-29 已在真实登录 Chrome 验证无家谱上下文：视频列表不发业务请求，发布入口及编辑表单保持隐藏，所有上下文链接返回家谱选择页，控制台无错误。当前账号没有家谱，真实列表、详情、上传和 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.html 已使用 GET /genealogy/pc/genealogies/ceremony-invitations/mine 展示当前账号的邀请列表和响应内详情；仅 PENDING 邀请显示接受/拒绝，并向 PUT /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations/me 提交唯一字段 inviteStatus，成功后重读列表。内部 ID 和坐标不直接展示，坐标仅用于生成地图链接。2026-07-29 使用真实账号联调，PC “我的邀请”接口成功返回空数组，页面空状态和鉴权正常；由于当前账号没有待响应邀请，真实接受/拒绝写入仍待有邀请数据时复核。后端仓库中的同组 AppCeremonyController 仍以 /genealogy/app/genealogies 为基础路径，与冻结 YAML 的 /genealogy/pc 不一致，但线上 PC mine 路径已实际可用，前端继续以 YAML 为唯一契约，不回退 APP 路径。

当前没有祭祀活动列表、详情、新增、修改和献礼列表/新增接口。现有 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	可选	A	当前固定提交 0 正常；C26 解决前不开放 1 停用

YAML 的列表、详情、新增和修改响应仍是泛型对象，但后端已存在独立 PcGrowthRecordController，其 PC method/path 与 YAML 一致，并明确返回 GrowthRecordVo。根据本轮“后端源码可作为可靠补充契约”的约定，页面响应字段由该 PC 控制器及 GrowthRecordVo 冻结：

• I：recordId、genealogyId、appUserId、lineagePersonId、mediaOssIds；
• R：genealogyNo、genealogyName、surname、appUserNickName、appUserPhone、lineagePersonNo、lineagePersonName、remark；
• U/R：recordType、recordTitle、recordContent；
• S/R：recordDate、remindTime；
• U/S/R：sortOrder；
• A/R：status，当前固定提交 0。

当前接入状态：

• profile-growth.html 已接入当前账号成长记录列表、详情、编辑和删除入口；列表接口不传后端额外的 all 参数，只消费当前 YAML 声明的请求；
• profile-growth-edit.html 已接入新增和修改；lineagePersonId 只从真实世系人物选项接口选择，recordId 只来自列表响应或 URL，均按字符串处理且不能手填；
• recordType 后端 DTO 和服务均为不带枚举的自由字符串，因此保留可选文本输入；recordDate 提交 yyyy-MM-dd，remindTime 由 datetime-local 转为后端 Date 接受的 yyyy-MM-dd HH:mm:ss；
• 多附件通过统一分片上传产生隐藏 mediaOssIds，支持保留、追加和清除附件选择，不显示 OSS ID；
• 新增和修改成功后必须使用稳定 recordId 重读同一条详情并校验身份，再返回列表；删除成功后重读列表，确认文案明确逻辑删除且会释放附件引用；
• C18 未解决前，标题以外可选文本、人物和日期字段清空不宣称闭环；前端对空可选字段保持省略，附件清除使用后端已明确的空引用处理；
• C25 未解决前只显示附件数量，不猜测 OSS URL、文件名或下载地址；C26 未解决前固定 status=0，不产生无法重新读取和恢复的停用记录；
• 2026-07-29 已在真实登录 Chrome 验证无家谱上下文：列表和详情不发成长记录业务请求，编辑表单及页头保存按钮隐藏，入口统一返回家谱选择页。当前账号没有家谱，真实列表、详情、世系选项、上传和 CRUD 写入仍待有数据账号验证。

7.12 亲友记录

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

字段	必填性	类型	页面处理
relativeName	必填	U	亲友姓名
relationName	可选	U	关系名称
eventName	可选	U	事件名称
eventTime	可选	S	日期时间选择器
giftAmount	可选	U	金额输入；只提交 JSON 序列化后数值不变的有限数字，C27 解决前不猜精度、范围或非负规则
recordContent	可选	U	内容
mediaOssIds	可选	F/I	多附件上传
sortOrder	可选	U/S	管理高级设置
status	可选	A	当前固定提交 0 正常；C29 解决前不开放 1 停用

YAML 的列表、详情、新增和修改响应仍是泛型对象，但后端已存在独立 PcRelativeRecordController，其 PC method/path 与 YAML 一致，并明确返回 RelativeRecordVo。根据本轮“后端源码可作为可靠补充契约”的约定，页面响应字段由该 PC 控制器及 RelativeRecordVo 冻结：

• I：relativeId、genealogyId、appUserId、mediaOssIds；
• R：genealogyNo、genealogyName、surname、appUserNickName、appUserPhone、remark；
• U/R：relativeName、relationName、eventName、recordContent；
• S/R：eventTime；
• U/R：giftAmount，后端 BigDecimal 响应按字符串保留；
• U/S/R：sortOrder；
• A/R：status，当前固定提交 0。

当前接入状态：

• profile-relative.html 已接入当前账号亲友记录列表、详情、编辑和删除入口；列表接口不传后端额外的 all 参数，只消费当前 YAML 声明的请求；
• profile-relative-edit.html 已接入新增和修改；relativeId 只来自列表响应或 URL，按字符串处理且不能手填；
• eventTime 使用 datetime-local，提交前转为后端 Date 接受的 yyyy-MM-dd HH:mm:ss，并校验真实月日和时分秒；
• giftAmount 请求按 YAML 的 number 提交；提交前比较用户十进制输入与 JSON.stringify(Number(value)) 的精确数值，序列化会改值的超大或高精度金额直接拒绝。后端 BigDecimal 响应按原字符串展示，不转回 Number；
• 多附件通过统一分片上传产生隐藏 mediaOssIds，支持保留、追加和清除附件选择，不显示 OSS ID；
• 新增和修改成功后必须使用稳定 relativeId 重读同一条详情并校验身份，再返回列表；删除成功后重读列表，确认文案明确逻辑删除且会释放附件引用；
• C18 未解决前，可选文本、时间和金额字段的清空不宣称闭环；附件清除使用后端已明确的空引用处理；
• C27 未解决前不增加两位小数、最大金额或非负限制；C28 未解决前只显示附件数量；C29 未解决前固定 status=0，并拒绝编辑停用响应，避免意外恢复；
• 2026-07-29 已在真实登录 Chrome 验证无家谱上下文：列表和详情不发亲友记录业务请求，编辑表单及页头保存按钮隐藏，入口统一返回家谱选择页。当前账号没有家谱，真实列表、详情、上传和 CRUD 写入仍待有数据账号验证。

7.13 备忘录

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

字段	必填性	类型	页面处理
memoTitle	必填	U	标题
memoContent	可选	U	内容
remindTime	可选	S	datetime-local 选择，提交为 yyyy-MM-dd HH:mm:ss 并校验真实日期
completed	可选	S	PC 后端已核验：0 未完成、1 已完成；创建默认 0
mediaOssIds	可选	F/I	多附件上传自动产生；隐藏保存，允许追加和清除，不允许手填
sortOrder	可选	U/S	安全整数；创建默认 0
status	可选	I/A	页面固定隐藏提交 0；不开放不可重读的停用状态

PC MemoVo 响应字段及页面用途：

字段	类型	标记	页面处理
memoId、genealogyId、appUserId	Long	I	仅从 PC 响应取得并按十进制字符串保存；用于详情、编辑、删除和写后重读，不显示、不手填
genealogyNo、genealogyName、surname	string	R	家谱上下文只读信息；当前备忘录页不重复展示
appUserNickName	string	R	详情显示记录人
appUserPhone	string	I	隐私字段，不渲染
memoTitle、memoContent、remindTime、completed	string	R	列表摘要、详情展示和编辑回填
mediaOssIds	string	I	只统计附件数量并回填隐藏上传字段，不暴露原始 OSS ID
sortOrder	Long	I	编辑回填；列表顺序由后端负责
status	string	I	仅接受正常记录 0；停用响应拒绝进入编辑器
remark	string	R	详情只读展示，MemoBody 不含此字段，因此不提交

completed 表示业务完成状态，status 表示记录正常/停用，两者不能合并。列表、详情、新增、修改和删除只调用 /genealogy/pc/genealogies/{genealogyId}/memos 及其 /{memoId} 子路径；列表不发送后端管理专用的 all 查询。新增/修改成功后使用稳定 memoId 重读同一详情，删除后重读列表。

• C18 未解决前，可选内容和提醒时间的清空不宣称闭环；附件清除使用后端已明确的空引用处理；
• C30 未解决前只显示附件数量；C31 未解决前固定 status=0，拒绝编辑停用响应，避免意外恢复；
• 2026-07-29 已在真实登录 Chrome 验证无家谱上下文：列表和详情显示明确提示，编辑表单及页头保存按钮隐藏，控制台无错误。当前账号没有可用家谱，真实列表、详情、上传和 CRUD 写入仍待有数据账号验证。

7.14 功德记录

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

字段	必填性	类型	页面处理
donorName	必填	U	功德人姓名
meritType	可选	S	donation 捐赠、repair 修祠、public 公益、other 其他
meritTitle	必填	U	标题
meritContent	可选	U	内容
amount	可选	U	YAML number；提交前拒绝 JSON 序列化会改变精确数值的输入，不自行限制小数位、范围或正负
meritTime	可选	S	datetime-local 选择，提交为后端示例和 Date 接受的 yyyy-MM-dd HH:mm:ss
sortOrder	可选	U/S	安全整数；创建默认 0
status	可选	I/A	页面固定隐藏提交 0；不开放不可重读的停用状态

PC MeritRecordVo 响应字段及页面用途：

字段	类型	标记	页面处理
meritId、genealogyId、appUserId	Long	I	仅从 PC 响应取得并按十进制字符串保存；用于详情、编辑、删除和写后重读，不显示、不手填
genealogyNo、genealogyName、surname	string	R	家谱上下文只读信息；当前功德页不重复展示
appUserNickName	string	R	详情显示记录人
appUserPhone	string	I	隐私字段，不渲染
donorName、meritType、meritTitle、meritContent	string	R	列表摘要、详情展示和编辑回填；HTML 内容转义后展示
amount	BigDecimal	R	按响应原始字符串展示，不转回 Number
meritTime	Date	R	列表、详情展示和 datetime-local 编辑回填
sortOrder	Long	I	编辑回填；列表顺序由后端负责
status	string	I	仅接受正常记录 0；停用响应拒绝进入编辑器
remark	string	R	详情只读展示，MeritRecordBody 不含此字段，因此不提交

现有页面中的契约外 service 已删除，补齐 repair 和 public；由于 MeritRecordBody 没有附件字段，功德页不借用其他模块的 mediaOssIds 或上传控件。ApiClient 的新增和修改方法再次按 8 个 YAML 字段白名单过滤，调用者额外传入 appUserId、mediaOssIds 等字段也不会发送。

• 列表、详情、新增、修改和删除只调用 /genealogy/pc/genealogies/{genealogyId}/merit-records 及其 /{meritId} 子路径；
• 新增/修改成功后使用稳定 meritId 重读同一详情，删除成功后重读列表；
• C18 未解决前，可选内容、金额和时间的清空不宣称闭环；C32 未解决前不增加两位小数、最大金额或非负限制；C33 未解决前固定 status=0 并拒绝编辑停用响应；
• PC 写操作最终由 assertCanEditContent 鉴权；当前 View 没有 canEdit/canDelete，页面保留操作入口并明确处理 403，不猜角色字段；
• 2026-07-29 已在真实登录 Chrome 验证无家谱上下文：列表和详情显示明确提示，编辑表单及页头保存按钮隐藏，契约外类型和附件控件不存在，控制台无错误。当前账号没有可用家谱，真实列表、详情和 CRUD 写入仍待有数据账号验证。

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

7.15 消息通知

页面：profile-messages.html。

接口冻结：

• GET /genealogy/pc/notifications：可选 query readStatus=0|1，返回非分页直接数组；全部通知时省略 query。
• GET /genealogy/pc/notifications/unread-count：返回非负 int64 未读数量。
• GET /genealogy/pc/notifications/{notificationId}：读取当前账号可见的正常通知详情。
• POST /genealogy/pc/notifications/{notificationId}/read：将当前账号的一条正常未读通知标记已读。
• POST /genealogy/pc/notifications/read-all：将当前账号全部未读通知标记已读。
• 五个接口均由 ApiClient 自动携带 Bearer 和 clientid；页面不采集 Header。YAML 未声明业务错误码；前端统一处理未登录/401、403、404、业务失败和网络失败。

字段	必填性 / 类型	标记	页面用途、来源与提交时机
query readStatus	可选 string；枚举 0/1	S	消息页筛选选择；全部=省略、未读=0、已读=1；切换筛选时提交
path notificationId	详情/单条已读必填 int64	I/A	从列表响应的稳定十进制字符串取得；点击详情或“标记已读”时自动进入 path，不允许手填或转 Number
notificationId	响应 int64	I	列表行内部关联详情和已读动作；不在可见页面展示
genealogyId	响应 int64，可空	I	仅保留为响应内部上下文；不展示、不提交、不允许手填
genealogyNo	响应 string	R	详情只读候选字段；当前 PC 未填充，不作为功能依赖
genealogyName	响应 string	R	详情只读展示；当前 PC 可能为空
senderUserId	响应 int64，可空	I	内部关联字段；不展示、不提交
senderNickName	响应 string	R	详情只读展示；当前 PC 可能为空
senderPhone	响应 string	I	隐私字段，页面始终隐藏
noticeType	响应 string，无枚举/默认值	R	列表和详情只读展示；不据此猜测跳转
noticeTitle	响应 string	R	列表和详情标题，转义后展示
noticeContent	响应 string	R	列表摘要和详情正文，转义后展示
bizType	响应 string，无枚举/默认值	R	详情只读展示；不据此拼业务 URL
bizId	响应 int64，可空	I	内部业务关联字段；PC 未提供目标路由契约前不展示、不跳转
bizSummary	响应 string	R	详情只读展示；当前 PC 可能为空
publishTime	响应 string date-time	R	列表和详情只读展示，不由页面提交
readStatus	响应 string；枚举 0/1	R	0=未读、1=已读；仅正常未读记录显示单条已读按钮
readTime	响应 string date-time，可空	R	详情只读展示，未读时为空
status	响应 string；枚举 0/1	I	仅用于确认正常状态 0 才能执行单条已读，不提供页面编辑
remark	响应 string	R	详情只读展示
未读数量 data	响应 int64	R	顶部计数；只接受非负安全整数

响应和权限边界：

• YAML 的详情对象没有声明字段级 required、长度、范围或默认值；页面不补造限制，并兼容可选展示字段为空。
• PC 后端按当前 APP_USER 登录账号隔离通知，只返回 status=0 的正常通知；列表按接收记录倒序，非分页。
• 详情和单条已读必须命中当前账号的接收记录；重复单条已读保持已读状态，页面仍做写操作防重复。
• C34 未解决前，genealogyNo/genealogyName/senderNickName/senderPhone/bizSummary 不能被视为稳定可用；手机号即使后端补齐也不展示。
• 页面不展示原始 JSON，不使用 APP 接口，不开放删除，不根据 bizType/bizId 猜业务深链。
• 2026-07-29 已在真实登录 Chrome 验证当前账号：未读数为 0，全部和仅未读筛选均成功同步，空列表/空详情状态正确。账号暂无通知，因此有数据详情和单条/全部已读真实写入仍待有数据时复核。

7.16 谱文

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

请求字段	必填性 / 类型	标记	页面来源与提交时机
categoryId	可选 int64	I/S	C35 未解决前省略；没有真实分类选项时不提供输入框
articleTitle	必填 string	U	编辑页标题；保存时提交
articleSummary	可选 string	U	编辑页摘要；非空时提交
coverOssId	可选 string/int64	F/I	选择封面并完成统一上传后自动产生；隐藏保存，禁止手填
articleContent	必填 string	U	wangEditor 正文；同步到 textarea 后提交
authorName	可选 string	U	编辑页落款；非空时提交
sortOrder	可选 int64	U/S	编辑页安全整数；非空时提交
status	可选 string 0/1	A/I	C37 未解决前固定隐藏提交 0
genealogyId、articleId	path int64	I/A	家谱上下文和列表/详情响应；按十进制字符串处理，不显示、不手填

PC ArticleVo 响应字段及页面用途：

字段	类型	标记	页面处理
articleId、genealogyId	Long	I	列表、详情、编辑、删除和写后重读的稳定 ID
genealogyNo、genealogyName、surname	string	R	家谱只读上下文
categoryId	Long，可空	I	仅内部保留；无分类选项源时不回填为可编辑 ID
categoryName、categoryCode	string	R	详情分类只读展示
articleTitle、articleSummary、articleContent、authorName	string	R/U	列表、详情展示和编辑回填；可见内容均转义
coverOssId	Long，可空	I	编辑隐藏回填；C36 未解决前不拼封面 URL
publishTime、viewCount	Date/Long	R	详情发布时间和浏览量
sortOrder	Long	I/U	编辑回填；列表顺序由后端负责
status	string 0/1	I	只允许正常记录进入编辑器
remark	string	R	详情只读展示，不进入 ArticleBody

接入边界：

• 列表、详情、新增、修改和删除只调用 /genealogy/pc/genealogies/{genealogyId}/articles 及其 /{articleId} 子路径；
• YAML 响应仍为泛型包装，但 PC 控制器明确返回 ArticleVo，前端严格校验该 VO，不读取 APP 路径；
• 新增/修改成功后使用稳定 articleId 重读同一详情；删除后重读列表；所有写操作防重复；
• 页面先读取家谱详情，只有 canEditContent/canManage 显示新增、编辑和删除；后端继续执行最终权限校验；
• C35 未解决前不开放分类筛选/编辑；C36 未解决前不猜封面地址；C37 未解决前不开放停用；
• 相关聚焦测试 49/49 通过；真实账号页面验证统一留到阶段 6 收尾执行。

7.17 相册与照片

页面：profile-album.html、profile-album-edit.html、profile-album-detail.html。

相册请求字段：

请求字段	必填性 / 类型	标记	页面来源与提交时机
albumName	必填 string	U	编辑页相册名称；保存时提交
albumDesc	可选 string	U	编辑页描述；非空时提交
coverOssId	可选 string/int64	F/I	选择封面并完成统一上传后自动产生；隐藏保存，禁止手填
sortOrder	可选 int64	U/S	编辑页安全整数；非空时提交
status	可选 string 0/1	A/I	C39 未解决前固定隐藏提交 0
genealogyId、albumId	path int64	I/A	家谱上下文及相册响应；按十进制字符串处理，不显示、不手填

照片请求字段：

请求字段	必填性 / 类型	标记	页面来源与提交时机
ossId	必填 string/int64	F/I	选择照片并完成统一上传后自动产生；隐藏保存，禁止手填
photoTitle、photoDesc、photographer	可选 string	U	照片表单；非空时提交
shootTime	可选 date	S	日期选择器；非空时提交 YYYY-MM-DD
sortOrder	可选 int64	U/S	照片表单安全整数；非空时提交
status	可选 string 0/1	A/I	C39 未解决前固定隐藏提交 0
albumId、photoId	path int64	I/A	相册和照片响应；按十进制字符串处理，不显示、不手填

PC 响应字段及页面用途：

对象	字段	标记	页面处理
AlbumVo	albumId、genealogyId	I	列表、编辑、详情、删除和写后重读的稳定 ID
AlbumVo	genealogyNo、genealogyName、surname	R	家谱只读上下文
AlbumVo	albumName、albumDesc	R/U	列表/详情展示和编辑回填；可见内容均转义
AlbumVo	coverOssId	F/I	编辑隐藏回填；C38 未解决前不拼封面 URL
AlbumVo	photoCount	R	列表和详情照片数量
AlbumVo	sortOrder、status	I/U	编辑回填；只允许正常记录进入编辑器
AlbumVo	remark	R	详情只读展示，不进入请求 Body
AlbumPhotoVo	photoId、genealogyId、albumId	I	照片删除和写后重读的稳定 ID
AlbumPhotoVo	genealogyNo、genealogyName、surname、albumName	R	家谱与相册只读上下文
AlbumPhotoVo	ossId	F/I	文件引用；C38 未解决前不拼照片 URL
AlbumPhotoVo	photoTitle、photoDesc、photographer、shootTime	R/U	照片列表展示；可见内容均转义
AlbumPhotoVo	sortOrder、status	I	列表顺序和正常状态校验
AlbumPhotoVo	remark	R	只读展示，不进入请求 Body

接入边界：

• 相册只调用 /genealogy/pc/genealogies/{genealogyId}/albums 及其 /{albumId} 子路径；照片只调用该相册下的 /photos 及 /{photoId}；
• 后端没有单独的相册详情接口，详情和编辑页必须重读相册列表并用响应中的稳定 albumId 精确匹配；
• YAML 响应仍为泛型包装，前端只接受后端 PC 控制器实际返回的 AlbumVo / AlbumPhotoVo 直接数组，不读取 APP 路径；
• 新增/修改相册后重读相册列表；新增/删除照片后重读照片列表；所有写操作防重复；
• 页面先读取家谱详情，只有 canEditContent/canManage 显示新增、编辑、删除和照片维护；
• C38 未解决前不猜文件地址；C39 未解决前不开放停用；
• 相关聚焦测试 49/49 通过；真实账号页面验证统一留到阶段 6 收尾执行。

7.18 祭祀活动、祭品与管理员受邀名单

页面：profile-ceremony.html、profile-gift-edit.html、profile-ceremony-detail.html；当前账号收到的邀请继续由 profile-gift.html 负责。

活动请求字段：

请求字段	必填性 / 类型	标记	页面来源与提交时机
ceremonyType	必填 string，无枚举	U	编辑页活动类型；保存时提交，不借用其他端枚举
ceremonyTitle	必填 string	U	编辑页标题；保存时提交
ceremonyDesc	可选 string	U	编辑页说明；非空时提交
ceremonyTime	可选 date-time	S	日期时间选择器；转换为后端 Date 可解析格式后提交
location	可选 string	U	编辑页地点名称；非空时提交
locationAddress	可选 string，最长 300	U	编辑页详细地址；非空时提交
longitude	可选 number，[-180, 180]	U/S	与纬度同时填写并保存
latitude	可选 number，[-90, 90]	U/S	与经度同时填写并保存
coverOssId	可选 string/int64	F/I	选择封面并完成统一上传后自动产生；隐藏保存，禁止手填
sortOrder	可选 int64	U/S	编辑页安全整数；非空时提交
status	可选 string 0/1	A/I	C41 未解决前固定隐藏提交 0
genealogyId、ceremonyId	path int64	I/A	家谱上下文和活动响应；按十进制字符串处理，不显示、不手填

祭品与受邀名单请求字段：

请求字段	必填性 / 类型	标记	页面来源与提交时机
giverName	可选 string	U	祭品表单赠送人姓名；非空时提交
giftAmount	必填 number，后端要求非负	U	祭品表单金额；添加祭品时提交；C42 未解决前不限制精度和最大值
giftMessage	可选 string	U	祭品留言；非空时提交
inviteeUserIds	必填、唯一 int64 数组，可为空	S/I	从 members/options 的正常且已绑定账号成员多选产生；更新名单时提交完整数组，禁止手填
giftId、invitationId、inviteeUserId	path/response int64	I/A	只从 PC 响应取得；用于删除、名单匹配和写后重读，不显示原值

PC 响应字段及页面用途：

对象	字段	标记	页面处理
CeremonyVo	ceremonyId、genealogyId、sponsorUserId	I	活动 CRUD、详情和写后重读的稳定 ID
CeremonyVo	genealogyNo、genealogyName、surname	R	家谱只读上下文
CeremonyVo	sponsorNickName	R	发起人只读展示
CeremonyVo	sponsorPhone	I	隐私字段，始终不展示
CeremonyVo	ceremonyType、ceremonyTitle、ceremonyDesc、ceremonyTime、location、locationAddress	R/U	列表/详情展示和编辑回填；可见内容均转义
CeremonyVo	longitude、latitude	I/S	仅用于生成安全地图链接，不直接展示数值
CeremonyVo	coverOssId	F/I	编辑隐藏回填；C40 未解决前不拼封面 URL
CeremonyVo	giftCount、giftAmount	R	详情祭品数量与礼金合计
CeremonyVo	sortOrder、status	I/U	编辑回填；只允许正常记录进入编辑器
CeremonyVo	remark	R	详情只读展示，不进入请求 Body
CeremonyGiftVo	giftId、genealogyId、ceremonyId、giverUserId	I	祭品删除、关联和写后重读的稳定 ID
CeremonyGiftVo	genealogyNo、genealogyName、surname、ceremonyTitle	R	家谱与活动只读上下文
CeremonyGiftVo	giverNickName、giverName、giftAmount、giftMessage、giftTime	R	祭品列表展示；可见内容均转义
CeremonyGiftVo	giverPhone	I	隐私字段，始终不展示
CeremonyGiftVo	status、remark	R/I	正常状态校验和只读备注
CeremonyInvitationVo	全部 ID、版本	I	邀请状态匹配和更新后的重读校验，不显示原值
CeremonyInvitationVo	inviteStatus、投递/阅读/响应时间	R	管理员邀请列表只读展示
GenealogyMemberVo 选项	appUserId	I/S	受邀人的唯一真实业务用户 ID 来源
GenealogyMemberVo 选项	memberName、appUserNickName	R/S	受邀人选择器标签；手机号不展示

接入边界：

• 活动只调用 /genealogy/pc/genealogies/{genealogyId}/ceremonies 及 /{ceremonyId}；祭品只调用其 /gifts 子路径；
• 管理员邀请列表和替换只调用同一活动下的 /invitations 与 /invitees，受邀人来源只调用当前家谱 /members/options；
• 新增/修改活动后重读同一详情，新增/删除祭品后重读祭品列表，更新受邀人后重读邀请列表；所有写操作防重复；
• 页面先读取家谱详情，只有 canEditContent/canManage 显示活动、祭品和受邀名单维护；
• 空数组允许取消全部尚未响应邀请；响应过的历史邀请由后端保留状态，前端不伪造删除；
• C40 未解决前不猜封面地址；C41 未解决前不开放停用；C42 未解决前不猜金额精度和上限；
• 相关聚焦测试 56/56 通过；真实账号页面验证统一留到阶段 6 收尾执行。

7.19 家谱成员管理、退出与谱主转移

页面：profile-family-admin.html。

成员修改请求字段：

请求字段	必填性 / 类型	标记	页面来源与提交时机
memberName	可选 string，最长 50	U	管理员编辑表单；非空时提交
relationName	可选 string，最长 100	U	管理员编辑表单；后端明确接收空串时可清空
roleType	可选 string，admin/editor/member	S	按当前管理者和目标角色过滤；保存时提交，不发送 owner/visitor
lineagePersonId	可选 int64	S/I	从当前家谱世系人物选项选择；非空时提交，留空表示不修改而不是解绑
genealogyId、memberId	path int64	I/A	家谱上下文和成员列表响应；按字符串处理，不显示、不手填

退出与谱主转移：

字段/操作	必填性 / 类型	标记	页面来源与提交时机
DELETE /members/me	无 Body	S/A	当前正常成员二次确认后提交；谱主不显示退出按钮
targetMemberId	必填 int64	S/I	谱主从当前正常成员列表选择新谱主；禁止选择自己和手填 ID
DELETE /members/{memberId}	path int64	S/I	管理员从真实成员行执行“移出家谱”；谱主不可被移出

PC GenealogyMemberVo 响应字段及页面用途：

字段	标记	页面处理
memberId、genealogyId、appUserId、lineagePersonId、inviterUserId	I	当前成员匹配、修改、移出、转让和世系绑定的稳定 ID；不显示原值
genealogyNo、genealogyName、surname	R	C44 未解决前允许为空的家谱只读上下文
appUserNickName、lineagePersonNo、lineagePersonName、memberName	R/U	成员列表标签和编辑回填；可见内容均转义
appUserPhone、inviterPhone	I	隐私字段，始终不展示
roleType	R/S	响应可含 owner/admin/editor/member/visitor；修改只提交三种后端可分配角色
relationName	R/U	列表展示和编辑回填
joinSource、inviterNickName、joinTime	R	加入来源只读说明；C44 未填充时允许为空
status	I	列表只接受后端返回的正常状态 0

权限与状态边界：

• 所有账号可按家谱查看权限读取正常成员；只有家谱详情 canManage=true 时显示修改和移出；
• 谱主不能直接修改或移出；只有谱主可管理管理员、分配 admin 或转让谱主；管理员只能管理非管理员成员并分配 editor/member；
• 普通成员、编辑和管理员可退出家谱；谱主必须先转让谱主。退出和移出只停用成员关系，不删除世系人物；
• 更新后重读成员列表并核对同一 memberId；移出后核对该成员不再出现在正常列表；谱主转移后重读家谱详情和成员列表；
• 页面没有直接新增成员接口；新增成员必须通过后端已有的加入/邀请业务闭环；
• C44 未解决前不依赖 enrichment 字段并隐藏手机号；C45/C46 未解决前不伪造关系解除或成员-世系人物解绑；
• 相关聚焦测试 49/49 通过；真实账号页面验证统一留到阶段 6 收尾执行。

7.20 家谱创建与加入申请契约

页面：profile-create-family.html、join-genealogy.html、profile-join-family.html、profile-join-review.html。

AppGenealogyCreateBody：

字段	类型	必填	来源	页面与提交时机
genealogyName	string	是	U	创建页谱名；提交时发送
surname	string	是	U	创建页姓氏；提交时发送
regionCode	string	是	S	省市区选择器自动取最后一级；提交时发送
ancestralHall、originPlace、addressDetail、intro	string	否	U	创建页可选输入；非空时发送
coverOssId	int64/string	否	F	封面上传成功后自动产生；不允许手填
visibility	string enum 0/1/2	否	S	私密/公开/成员可见
joinMode	string enum 0/1/2	否	S	关闭/审核/邀请模式

实现边界：

• 创建只调用 POST /genealogy/pc/genealogies，提交前读取 GET /genealogy/pc/genealogies/quota；
• 地区选项复用 /genealogy/pc/region/children?parentCode=...，不手写地区编码；
• 创建成功后使用响应中的稳定 genealogyId 重读同一家谱，匹配后进入家谱主页；
• 申请页先从 GET /genealogy/pc/genealogies/options 选择响应中的家谱，再调用 POST /genealogy/pc/genealogies/{genealogyId}/join-applies；
• 我的申请页调用 GET /genealogy/pc/genealogies/join-applies/mine；只有 status=0 的响应项可以调用 DELETE /genealogy/pc/genealogies/join-applies/{applyId}；
• 审核页只从当前家谱上下文取得 genealogyId，先读取家谱详情并要求 canManage=true，再读取 GET /genealogy/pc/genealogies/{genealogyId}/join-applies/pending；
• 审核只调用 PUT /genealogy/pc/genealogies/{genealogyId}/join-applies/{applyId}/audit，status=1 通过、status=2 拒绝；
• inviterUserId 没有安全 PC 邀请来源，本轮加入申请契约不发送该字段；
• 创建/申请/审核页面均无家谱 ID、申请 ID、用户 ID 或 OSS ID 文本输入，所有写操作防重复并在成功后重读对应资源。

AppGenealogyJoinApplyBody：

字段	类型/约束	必填	来源	页面与提交时机
applicantName	string，最长 50	否	U	申请页姓名；非空时提交
phone	string，最长 30	否	U	申请页联系电话；非空时提交
relationDesc	string，最长 100	否	U	申请页关系说明；非空时提交
applyReason	string，最长 500	否	U	申请页申请理由；非空时提交
inviterUserId	int64/string	邀请模式条件必填	I	PC 无安全来源，不展示、不发送；邀请模式继续阻断

GenealogyJoinApplyVo 与审核：

字段	类型/枚举	来源	页面用途
applyId、genealogyId	int64/string	R/I	响应按钮属性和写入 path；不显示、不手填
genealogyName、surname	string	R	我的申请列表只读展示
applicantName、phone、relationDesc、applyReason	string	R	管理员待审核列表；只展示申请人主动提交的 phone
auditTime、auditRemark	datetime/string	R	我的申请审核结果展示
status	string 0/1/2/3	R	待审核/通过/拒绝/撤销；仅 0 可撤销
appUserId、inviterUserId、auditUserId	int64/string	I	普通列表和审核列表均不展示
appUserPhone、inviterPhone、auditPhone	string	I	账号/邀请/审核人员隐私字段均不展示
审核 status	string 1/2	S	管理员点击通过或拒绝时提交
审核 auditRemark	string，最长 500	U	拒绝时可选填写，非空时提交

7.21 意见反馈与工单契约

页面：profile-feedback.html、submit-ticket.html、my-tickets.html、ticket-detail.html。

后端只提供统一反馈集合：

• POST /genealogy/pc/feedback：当前业务用户提交反馈；
• GET /genealogy/pc/feedback：读取当前业务用户自己的反馈列表；
• 没有独立 ticket path；“工单”只是帮助中心对同一反馈记录的页面名称；
• 没有用户侧回复、追问、关闭或删除接口，页面不制造这些操作。

AppFeedbackBody：

字段	类型/约束	必填	来源	页面与提交时机
feedbackType	string enum advice/bug/complaint/other	否	S	两个提交页选择；空值省略并由后端默认 advice
feedbackContent	string，非空	是	U	问题或建议正文；提交时发送
contactInfo	string	否	U	用户主动提供的联系方式；非空时发送
feedbackTitle	—	—	V	旧页面字段不属于 DTO，已从表单移除且不发送

FeedbackVo：

字段	类型/枚举	来源	页面用途
feedbackId	int64/string	R/I	提交后重读匹配、列表详情链接和 URL；不展示、不手填
feedbackType、feedbackContent、contactInfo	string	R	列表或详情只读展示
handleStatus	string 0/1/2/3	R	待处理/处理中/已处理/已关闭
handleResult、handleTime、remark	string/datetime	R	后端存在时在详情展示
status	string 0/1	I	响应有效性校验，不提供用户修改入口
appUserId、handlerId	int64/string	I	内部用户/处理人编号，不展示
appUserNickName、appUserPhone	string	I	后台 enrichment，不在用户页面展示

实现边界：

• ApiClient 是 GET/POST path 和三字段 body 白名单唯一 owner；
• 提交使用防重复锁；成功响应必须包含稳定字符串 feedbackId；
• 提交后重读我的反馈列表并精确找到同一 feedbackId，否则不宣称成功；
• 工单详情从 URL 读取列表响应产生的 feedbackId，只在我的列表中精确匹配，不回退第一条；
• 401 清理登录态；403 保留登录态并显示后端权限错误；页面不展示原始 JSON。

7.22 VIP 套餐与会员订单契约

页面：profile-services.html。

PC 端只开放三条业务用户接口：

• GET /genealogy/pc/vip/packages：读取可购买套餐，成功响应 List<VipPackageVo>，无分页结构；
• POST /genealogy/pc/vip/orders：创建当前业务用户的会员订单，body 为 AppVipOrderBody，成功响应 VipOrderVo；
• GET /genealogy/pc/vip/orders：读取当前业务用户的订单，成功响应 List<VipOrderVo>，无分页结构；
• 三条接口均要求 APP_USER 登录态；创建接口有后端防重复提交；
• PC Controller 没有支付发起、支付回调、取消、关闭或退款接口，页面不得制造这些动作。

AppVipOrderBody：

字段	类型/约束	必填	来源	页面与提交时机
packageId	int64，稳定字符串 ID	是	S/I	用户点击套餐响应生成的卡片时选择；创建订单时发送，禁止手填
genealogyId	int64，稳定字符串 ID	否	S/I	用户从“我的家谱”响应生成的下拉项中选择；非空时创建订单发送，禁止手填
payType	string；后端空值默认 wechat	否	A	PC 页面不提供支付方式选择且默认省略；等待后端开放真实支付能力后再确认枚举

VipPackageVo：

字段	类型/枚举	来源	页面用途
packageId	int64/string	R/I	套餐卡片选择和订单 body；不展示、不手填
packageName、packageDesc	string	R	套餐名称和说明
packageType	string vip/storage	R	显示为会员套餐/存储扩容；未知值整条过滤
price、originalPrice	decimal，非负	R	价格展示；不参与前端金额计算
durationValue	integer，非负，可空	R	与期限单位组合展示
durationUnit	string permanent/day/month/year	R	永久/天/月/年
genealogyLimit、memberLimit、storageLimitMb	integer，非负，可空	R	套餐额度只读展示
featureJson	string/JSON	I	契约未说明用户侧展示结构，当前不解析、不展示
sortOrder	integer	I	后端列表顺序 owner，前端不重新排序
status	string 0/1	I	只接受正常 0 套餐；不提供修改入口
remark	string	R	非空时作为套餐补充说明展示

VipOrderVo：

字段	类型/枚举	来源	页面用途
orderId	int64/string	R/I	创建后重读精确匹配；不展示、不手填
orderNo	string	R	订单列表展示
packageId	int64/string	R/I	响应有效性校验，不展示
packageName	string	R	订单套餐名称
genealogyId	int64/string，可空	R/I	响应有效性校验，不展示
genealogyNo、genealogyName	string，可空	R	关联家谱信息展示
orderAmount、payAmount	decimal，非负	R	订单金额和应付金额展示；以后端值为准
payType	string，可空	R	后端返回时只读展示，不作为支付入口
payStatus	string 0/1/2/3	R	待支付/已支付/已关闭/已退款
payTime、expireTime	datetime，可空	R	支付和有效期信息展示
status	string 0/1	I	响应有效性校验，不提供修改入口
remark	string	R	非空时展示
appUserId、appUserNickName、appUserPhone	int64/string	I	当前账号及 enrichment 字段，不在页面展示

实现边界：

• ApiClient 是三条 path 与三字段请求白名单唯一 owner；
• 页面启动时并行读取套餐、我的家谱和订单；所有业务 ID 仅来自响应；
• 创建使用前端防重复锁；创建响应必须是完整有效 VipOrderVo，随后重读订单列表并精确找到同一 orderId 才宣称成功；
• 页面省略 payType，由后端使用已确认的默认值；不展示后端尚未提供的支付、取消或退款按钮；
• 401 清理登录态；403 保留登录态并展示后端错误；非法套餐、订单、金额、枚举或不安全数字 ID 整条过滤。

7.23 家谱主页只读概览契约

页面：profile-family-home.html。

只使用两条现有 PC 读取接口：

• GET /genealogy/pc/genealogies/{genealogyId}/overview：返回当前家谱 AppGenealogyVo；
• GET /genealogy/pc/genealogies/{genealogyId}/lineage/tree：返回 List<LineagePersonTreeView>；
• genealogyId 只从 profile-common.js 的当前家谱上下文取得，两条请求使用同一个稳定字符串 ID；
• 后端 overview 当前实际复用家谱详情服务，不包含文章、相册、视频、祭祀或动态聚合统计。

AppGenealogyVo 主页字段：

字段	类型/约束	来源	页面用途
genealogyId	int64/string	I/A/R	当前上下文、两条请求 path、响应一致性校验；不展示、不手填
genealogyNo	string	R	家谱编号只读展示
genealogyName	string，非空	R	页面标题和概览名称
surname	string	R	姓氏只读展示
ancestralHall	string，可空	R	堂号非空时展示
originPlace	string，可空	R	祖籍非空时展示
regionFullName	string，可空	R	完整地区非空时展示
memberCount、personCount	integer，非负	R	家谱成员数和世系人物数；不在前端计算
status	string 0/1	I	只接受正常 0 响应
canManage	boolean	I	严格为 true 时显示家谱管理入口
canEditContent	boolean	I	保留为内容权限上下文，主页不据此制造写操作
ownerUserId、coverOssId	int64/string	I	当前主页不展示、不手填
其余地址、角色、成员状态字段	对应 DTO 类型	I	当前主页不消费，不输出原始 JSON

LineagePersonTreeView：

字段	类型/结构	来源	页面用途
personId、genealogyId	int64/string	R/I	树节点稳定标识和响应校验；不直接展示
name、generationName、人物摘要字段	string	R	复用世系页的安全节点渲染
relationType	string father/mother/spouse/child/adoptive	R	关系数据；主页不提供关系写操作
relationName	string	R	非空时作为关系说明
spouses、children	LineagePersonTreeView[]	R	递归世系预览

实现边界：

• lineage-pages.js 是世系节点规范化和树 HTML 的唯一 owner；主页不得复制一套树字段解释；
• 页面并行读取概览和世系树，只展示基础信息、后端已有计数和真实树；
• /genealogy/dashboard/overview 是后台权限接口，不属于 PC 家谱主页契约，前端不调用；
• PC 没有成员邀请创建或分享接口，“邀请家人”只显示阻断说明，不提供可点击操作；
• 主页没有写请求；401 清理登录态，403 保留登录态并显示读取错误。

7.24 帮助中心文章契约

页面：help.html。契约 owner：utils/ApiClient.js 的 helpArticles / helpArticleDetail 和 public/js/help-pages.js。

接口：

method	完整 path	目录	鉴权	页面时机
GET	/genealogy/pc/help-articles	内容文章 / PC 帮助文章列表	APP_USER 登录态	帮助中心初始化或用户点击刷新
GET	/genealogy/pc/help-articles/{helpId}	内容文章 / PC 帮助文章详情	APP_USER 登录态	用户从列表点击“查看完整解答”

请求字段：

位置	字段	必填	类型/约束	分类	页面来源与提交时机
Query	helpCategory	否	string；后端按完全相等过滤	S	当前页面不提供猜测分类选项，因此初始化时省略；后端提供正式分类字典后才能开放选择
Path	helpId	是	int64；前端始终按非零十进制字符串处理	I	只能来自列表响应；用户点击该文章详情时进入 path
Header	clientid	基础请求自动	string	A	AxiosRequestUtil 统一填写；页面不输入
Header	Authorization	是	Bearer <access_token>	A	AxiosRequestUtil 从登录态自动填写；页面不读取、不展示 token
Body	—	—	两个接口均无 Body	—	—

HelpArticleVo 响应字段：

字段	类型	分类	页面使用
helpId	int64/string	I	校验稳定 ID、绑定列表项并精确重读详情；不向用户显示
helpCategory	string	R	列表和详情分类文字，可空
helpTitle	string	R	列表标题，空值使整条响应失败
helpContent	string	R	详情正文；转义并保留换行，不执行响应 HTML
coverOssId	int64/string	I	当前响应没有文件 URL，页面不显示、不拼接、不允许手填
sortOrder	int64	I	仅后端排序，不展示
viewCount	int64/string	R	非负十进制计数；详情 GET 会由后端累计浏览量
status	string	I	只接受正常值 0；停用文章整条拒绝
remark	string	I	后台备注，不展示

响应与错误边界：

• 列表响应必须是直接数组，不接受分页 rows 猜测；任一元素缺少稳定 ID、标题、正文或正常状态时整批失败；
• 详情必须返回与 path 中相同的 helpId，不回退到列表第一条；
• YAML 把两条接口标为 security: []，但 PcHelpArticleController 没有 @SaIgnore，部署环境无 token 实测返回“认证失败”；按用户指定的后端项目为准，当前客户端必须携带登录 token，此项作为 Apifox/后端冲突保留；
• 后端只声明统一成功包装，未提供帮助文章专属失败码；详情不存在或停用时按业务错误展示，不制造 404 枚举；
• 无登录态或 401 清理登录状态并进入登录页；403 保留登录态并展示读取错误；
• 页面只有读取动作，不提供编辑、发布、分类管理、封面 OSS ID 或成员邀请操作。

7.25 应用推广契约

页面：app.html 的“应用推广”区域。契约 owner：utils/ApiClient.js 的 promotions 和 public/js/app-promotion-pages.js。

接口：

method	完整 path	目录	鉴权	页面时机
GET	/genealogy/pc/promotions	应用推广 / PC 应用推广列表	APP_USER 登录态	应用下载页初始化；仅在本地已有登录 token 时请求一次

请求字段：

位置	字段	必填	类型/约束	分类	页面来源与提交时机
Query	platform	否	string；SQL 字典 gen_promotion_platform：all 全部（默认）、app APP、pc PC、wechat 小程序	A	应用下载页初始化时固定发送 pc；服务端返回 platform=pc 或 platform=all 的正常记录，不让用户选择或手填
Header	clientid	基础请求自动	string	A	AxiosRequestUtil 统一填写；页面不输入
Header	Authorization	是	Bearer <access_token>	A	AxiosRequestUtil 从登录态自动填写；页面不读取、不展示 token
Path	—	—	无 Path 参数	—	—
Body	—	—	无 Body	—	—

AppPromotionVo 列表元素字段：

字段	类型	必填/约束	分类	页面使用
promotionId	int64/string	SQL BIGINT NOT NULL 主键；前端按非零十进制字符串处理	I	稳定绑定卡片，不展示、不允许手填
promotionKey	string	SQL varchar(80) NOT NULL DEFAULT 'banner'	I	后台识别字段，页面不展示、不提交
promotionTitle	string	SQL varchar(200) NOT NULL；页面要求非空	R	推广卡片标题，HTML 转义后展示
promotionDesc	string	SQL varchar(500) DEFAULT ''，可空	R	推广卡片说明，HTML 转义后展示
coverOssId	int64/string	可空；响应没有可访问文件 URL	I	不显示、不拼接 URL、不允许用户手填 OSS ID
targetUrl	string	SQL varchar(500) DEFAULT ''，可空；页面只接受绝对 http/https URL	R	合法时作为新窗口外链；危险、相对或无效地址降级为不可点击卡片
platform	string	SQL varchar(30) NOT NULL DEFAULT 'all'；字典枚举 all/app/pc/wechat	I	仅后端筛选，当前页面不展示
sortOrder	int64	SQL BIGINT NOT NULL DEFAULT 0；后端按升序排序，同序按 promotionId 降序	I	仅后端排序，页面不二次解释或展示
status	string	SQL char(1) NOT NULL DEFAULT '0'；0 正常、1 停用，页面只接受 0	I	停用或缺失状态的记录使整批响应失败
remark	string	SQL varchar(500) DEFAULT NULL，可空	I	后台备注，不展示

响应、权限与错误边界：

• 成功响应经统一请求层解包后必须是直接 AppPromotionVo[]，不是分页结构；任一元素缺少稳定 ID、标题或正常状态时整批失败；
• 空数组显示“当前暂无应用推广”；未登录时页面本身仍可浏览，但推广区域只显示登录入口且不发请求；
• YAML 把该接口标为 security: []，并且未导出真实 Query platform；后端 PcPromotionApiController 没有 @SaIgnore，全局拦截器要求 APP_USER 登录态。SQL 字典已确认 all/app/pc/wechat，服务层按“请求平台或 all”过滤，因此当前实现携带登录 token 并固定发送 platform=pc；
• SQL gen_app_promotion 另有 (tenant_id, platform, status, del_flag) 和 (tenant_id, sort_order) 索引；del_flag、租户及审计字段不属于 AppPromotionVo，页面不接收、不展示；
• 401 清理失效 token 并把推广区域切回登录提示；403、网络失败或畸形响应只在推广区域显示读取失败，不跳转、不清理有效登录态；
• 后端只声明统一成功包装，未提供推广专属失败响应和错误码；字段长度、默认值及平台枚举已由后端 SQL 冻结，不再作为阻断项；
• 页面没有推广新增、编辑、上下架、排序、封面上传能力，不调用 APP 或后台管理接口，也不向用户暴露推广 ID、推广键或 OSS ID。

7.26 官网资讯契约

页面：news.html、article-detail.html。契约 owner：utils/ApiClient.js 的 siteArticles、utils/AxiosRequestUtil.js 的公开请求鉴权语义和 public/js/site-news-pages.js。

接口：

method	完整 path	目录	鉴权	页面时机
GET	/genealogy/pc/site/articles	站点内容 / PC 站点文章列表	公开，auth: false	资讯列表初始化、分类切换后的页面初始化，以及详情页按列表响应 ID 精确重读

请求字段：

位置	字段	必填	类型/约束	分类	页面来源与提交时机
Query	articleType	否	string；SQL 字典 gen_site_article_type：news 新闻（默认）、notice 公告、download 下载	S	用户点击固定分类链接后从 URL Query 取得；“全部”省略该字段，非法值不发请求
Query	limit	否	integer，客户端只允许 1–100；服务端正数最大取 100	A	列表和详情重读均由页面固定提交 100
Header	clientid	基础请求自动	string	A	AxiosRequestUtil 统一填写；页面不输入
Header	Authorization	不发送	—	—	方法设置 auth: false；即使本地已有 token 也不发送，公开请求 401/403 不清理既有登录态
Path	—	—	无 Path 参数	—	—
Body	—	—	无 Body	—	—

SiteArticleVo 列表元素字段：

字段	类型	必填/约束	分类	页面使用
articleId	int64/string	SQL BIGINT NOT NULL 主键；前端按非零十进制字符串处理	I	只用于生成详情链接和精确匹配，不展示、不允许手填
articleType	string	SQL varchar(50) NOT NULL DEFAULT 'news'；枚举 news/notice/download	R	转换为新闻、公告、下载标签；枚举外记录使整批失败
articleTitle	string	SQL varchar(200) NOT NULL；页面要求非空	R	列表和详情标题，HTML 转义
articleSummary	string	SQL varchar(500) DEFAULT ''，可空	R	列表摘要和详情导语，HTML 转义
articleContent	string	SQL text，可空	R	详情正文；HTML 转义并只保留换行，不执行响应 HTML
coverOssId	int64/string	SQL BIGINT，可空；没有文件 URL 契约	I	不显示、不拼接 URL、不允许手填
externalUrl	string	SQL varchar(500) DEFAULT ''，可空	R	只接受绝对 HTTP/HTTPS；合法时显示安全新窗口外链
publishTime	string/date	SQL datetime，可空	R	列表和详情发布时间文本，HTML 转义
sortOrder	int64	SQL BIGINT NOT NULL DEFAULT 0	I	仅后端排序，不展示
status	string	SQL char(1) NOT NULL DEFAULT '0'；0 正常、1 停用	I	页面只接受 0，其他值使整批失败
remark	string	SQL varchar(500) DEFAULT NULL，可空	I	后台备注，不展示

响应、详情与错误边界：

• 成功响应经统一请求层解包后必须是直接 SiteArticleVo[]；不接受分页 rows、旧字段别名或任一非法元素；
• 服务端只查正常状态，按 sortOrder ASC、publishTime DESC、articleId DESC 排序；页面保持服务端顺序；
• 后端没有站点文章单条详情接口；详情 ID 只能来自列表链接，详情页重读 { limit: 100 } 后精确匹配同一字符串 ID，不存在时不得回退第一条；
• 标题、摘要、正文、类型和时间全部转义；正文只保留换行，危险或相对外链不渲染；
• 空数组显示“当前暂无资讯”；非法分类/详情 ID 不发请求；网络、业务或畸形响应只更新内容区域，不跳转登录；
• YAML 已导出 method/path、articleType、limit 和 security: []，但响应只引用通用列表结果，未导出 SiteArticleVo 11 个字段；完整字段、长度、默认值和枚举由后端 VO、SQL 与字典补齐；
• 2026-07-30 使用本地页面对当前部署环境做匿名实测时，接口返回“认证失败，无法访问系统资源”；页面保持在资讯页且不清理已有 token。该行为与 YAML 的 security: [] 冲突，后端需确认部署环境是否遗漏公开放行；前端不通过附带登录 token 绕过公开契约；
• coverOssId 的文件 URL 和站点文章单条详情接口继续作为后端契约阻断；页面不猜 URL、不制造详情路径；
• 本批不修改 about/culture/privacy/terms/surname，也不复用登录后的家谱谱文 CRUD 脚本。

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. 我的贺礼邀请。

当前进度：阶段 4 已按顺序完成。家族圈的列表、正常状态详情、新增、修改、删除、点赞、评论、回复、权限显隐、空/错状态、防重复和写后重读已接入，C21 图片 URL 回显和 C22 停用记录管理继续阻断；字辈谱的正常/management 权限分流、单条新增修改和状态切换、批量预览保存、响应校验、防重复、写后重读及无家谱上下文分支已接入；世系人物的树、列表、分页、详情、完整字段表单、权限显隐、四类关系新增、逻辑停用、防重复和写后重读已接入，C15 继续阻断新增 SPECIFIED 账号绑定，C18 继续阻断可选字段清空闭环；我的贺礼邀请已接入当前账号列表、响应内详情、PENDING 接受/拒绝、长 ID 校验、权限/空错状态、防重复和写后重读，C16 继续阻断管理员替换受邀人。真实账号已验证邀请读取和空状态；该账号没有待响应邀请，接受/拒绝真实写入仍待有数据时复核。下一阶段为阶段 5，按顺序先核对视频 DTO 是否已完整。

每个模块采用同一闭环：

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

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

顺序：

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

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

当前进度：阶段 5 已按顺序完成。视频、成长记录、亲友记录、备忘录、功德记录和消息通知均已按对应 PC 契约开放；各模块的文件 URL、停用记录、可选字段清空和金额业务边界仍按 C18、C23–C34 保持阻断，不通过 APP 接口或猜测字段补齐。

阶段 6：当前 PC 契约可闭环模块

已完成：

• 谱文列表、详情、新增、修改和删除；
• 相册列表、新增、修改、删除，以及照片列表、新增和删除；
• 祭祀活动列表、详情、新增、修改和删除，祭品列表、新增和删除；
• 管理员受邀名单读取和完整替换，当前账号邀请读取与响应；
• 从同家谱正常成员选项中选择账号完成 SPECIFIED 世系人物绑定；
• 家谱成员列表、修改、移出、当前成员退出和谱主转移；
• 个人中心、家谱首页和家谱内容页的稳定入口。

契约收口：

• replaceCeremonyInvitees(genealogyId, ceremonyId, inviteeUserIds) 只接收真实成员选项产生的 ID 数组，utils/ApiClient.js 唯一封装 { inviteeUserIds }；
• /members/options 严格按 YAML 不发送 Query；后端存在但 YAML 未定义的 keyword 不进入前端契约；
• 成员角色构造边界只接受 admin/editor/member，owner/visitor 在请求构造前失败；
• 所有业务 ID 来自 URL、上下文或响应选项，页面不提供手填 ID/OSS ID。

仍阻断：

• C35–C46 中记录的分类选项、文件 URL、停用记录、金额业务精度/上限、响应 enrichment 与解绑契约；
• 世系关系解除没有 PC 接口；成员移出/退出不会伪造成世系关系解除或成员与世系人物解绑；
• 真实账号 19181970173 已验证登录和无家谱上下文分支：阶段 6 页面均阻止业务请求、隐藏管理操作并返回家谱选择页，浏览器控制台无错误。该账号当前无家谱数据，因此列表有数据态、详情以及真实写操作仍待有数据账号复核，未制造家谱或业务记录。

阶段 7：剩余 PC 页面分批开放

首批已完成家谱生命周期 ApiClient 契约和创建家谱页面：额度、三级地区、封面上传派生、严格 DTO 校验、防重复与创建后重读均已接入。第二批已完成申请加入、我的申请、撤销和管理员审核页面；家谱/申请 ID 均来自响应或当前上下文，写后重读确认。第三批已完成意见反馈和工单展示：四页共用 PC 反馈集合、提交后三字段白名单重读、详情精确匹配和隐私过滤。第四批已完成 VIP 套餐、我的家谱选项和会员订单：页面不手填业务 ID，不伪造支付能力，创建后重读同一订单确认。第五批已完成家谱主页只读概览：复用 PC overview 与世系树，权限控制管理入口，不制造聚合统计或邀请能力。第六批已完成帮助中心：登录后读取 PC 帮助文章列表，列表响应产生详情 ID，详情精确重读并安全展示正文；Apifox 的匿名标记与后端实际鉴权冲突已记录。第七批已完成应用下载页的 PC 推广列表：未登录不发请求，登录后固定发送 SQL 字典确认的 platform=pc，只读取服务端返回的 pc + all 正常记录，外链仅允许绝对 HTTP/HTTPS；推广 ID、后台键和 OSS ID 均不向用户开放。第八批已完成官网资讯列表与详情：公开请求不发送或清理 token，分类使用 SQL 字典 news/notice/download，详情 ID 只来自列表响应并通过重读列表精确匹配；YAML 通用响应缺失完整 SiteArticleVo，且当前部署环境匿名访问仍返回认证失败，两项差异均已记录。成员邀请、分享和资料完善提醒没有 PC Controller，继续阻断。

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/video-pages.js	视频列表、详情、编辑、上传元数据和 CRUD
public/js/growth-pages.js、relative-pages.js、memo-pages.js	对应族务记录
public/js/ceremony-pages.js	当前用户贺礼邀请列表、响应内详情和接受/拒绝
public/js/article-pages.js、album-pages.js	谱文、相册和照片
public/js/ceremony-admin-pages.js	祭祀活动、祭品与管理员邀约
public/js/member-admin-pages.js	成员修改、移出、退出和谱主转移

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

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: 下一阶段可以开始的最小范围。

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