jiapu/docs/superpowers/specs/2026-07-29-remaining-pc-pages-design.md

剩余 PC 页面对接设计

目标

以 D:\WorkSpace\Java\Genealogy 中的 PC Controller、DTO、VO 和 Service 实现为本轮唯一运行时契约，开放当前仍为 pending、但后端 PC 能力已经形成闭环的页面。

后端目录全程只读。前端不得调用 /genealogy/app/**、后台管理端 /genealogy/**，不得猜测接口、字段、业务 ID、OSS ID、支付动作、邀请令牌或分享地址。

契约所有者

• utils/ApiClient.js 唯一拥有 PC method、path、query 和 body 白名单。
• 页面脚本只接收 ApiClient 解包后的业务数据，不自行拼接接口路径。
• 页面中的家谱、申请、反馈、套餐和订单 ID 只能来自 URL、当前家谱上下文或后端响应。
• 后端 PC Controller 继承共用 Support 类时，以 PC Controller 的 @RequestMapping 作为路径，以 Support 类方法、DTO、VO 和 Service 作为字段与行为依据；这不构成借用 APP 接口。

范围

1. 家谱创建

页面：profile-create-family.html。

接入：

• POST /genealogy/pc/genealogies
• GET /genealogy/pc/genealogies/quota
• GET /genealogy/pc/region/children?parentCode=0
• GET /genealogy/pc/region/children?parentCode={regionCode}

请求只提交 AppGenealogyCreateBody：

• 必填：genealogyName、surname、regionCode
• 可选：ancestralHall、originPlace、addressDetail、coverOssId、intro、visibility、joinMode

regionCode 由省市区选择产生；coverOssId 只能由文件上传产生。成功后使用响应中的真实 genealogyId 写入当前家谱上下文并进入家谱主页。额度不足、未登录业务用户、地区无效和服务端创建失败均展示后端错误，不降级到虚假成功。

2. 加入申请与审核

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

接入：

• POST /genealogy/pc/genealogies/{genealogyId}/join-applies
• GET /genealogy/pc/genealogies/join-applies/mine
• DELETE /genealogy/pc/genealogies/join-applies/{applyId}
• GET /genealogy/pc/genealogies/{genealogyId}/join-applies/pending
• PUT /genealogy/pc/genealogies/{genealogyId}/join-applies/{applyId}/audit

加入申请字段：

• applicantName：可选，最长 50
• phone：可选，最长 30
• relationDesc：可选，最长 100
• applyReason：可选，最长 500
• inviterUserId：仅后端 INVITE 模式使用；当前 PC 没有安全邀请来源，前端不展示、不提交

审核字段：

• status：必填，只允许 1 通过、2 拒绝
• auditRemark：可选，最长 500

申请列表、审核列表和写入结果使用完整 GenealogyJoinApplyVo。页面隐藏申请人、邀请人和审核人的内部用户 ID；手机号只在家谱管理员审核场景按后端响应展示。撤销只允许当前申请人的待审核申请；审核只对当前家谱待审核申请开放。重复提交、已处理申请、已是成员、家谱关闭加入和权限不足均使用真实错误分支。

3. 意见反馈与工单

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

接入：

• POST /genealogy/pc/feedback
• GET /genealogy/pc/feedback

请求只提交 AppFeedbackBody：

• feedbackContent：必填
• feedbackType：可选，空值由后端默认 advice
• contactInfo：可选

现有页面里的 feedbackTitle 不属于后端 DTO，不发送。工单页面与意见反馈页面共用 feedback-pages.js；“工单”是同一反馈记录在帮助中心的展示名称，不制造独立 ticket path。

列表和详情使用完整 FeedbackVo。详情页从 PC 反馈列表按 URL 中真实 feedbackId 匹配，未匹配时显示不存在，不回退到第一条。用户只展示反馈类型、内容、联系方式、处理状态、处理结果、处理时间和备注，不展示 appUserId、handlerId、手机号 enrichment 或原始 JSON。提交成功后重读列表并核对同一反馈 ID。

4. VIP 套餐和订单

页面：profile-services.html。

接入：

• GET /genealogy/pc/vip/packages
• POST /genealogy/pc/vip/orders
• GET /genealogy/pc/vip/orders

订单请求只提交 AppVipOrderBody：

• packageId：必填，只能来自套餐响应
• genealogyId：可选，只能来自用户家谱选项
• payType：可选，空值由后端默认 wechat

页面展示完整 VipPackageVo 中的套餐名称、说明、价格、原价、有效期、家谱/成员/存储限制与正常状态；展示 VipOrderVo 中的订单号、套餐、关联家谱、金额、支付类型、支付状态和有效期。

后端当前只落订单，没有 PC 支付发起、支付回调或取消接口。页面只允许“创建订单”和“刷新订单”，不显示“立即支付”“模拟成功”“取消订单”。新订单按后端 payStatus=0 展示为待支付，并明确支付能力尚未开放。

5. 家谱主页与权限入口收口

页面：profile-family-home.html、profile-admin-permissions.html。

家谱主页使用：

• GET /genealogy/pc/genealogies/{genealogyId}/overview

主页展示 AppGenealogyVo 可确认的家谱名称、编号、姓氏、地区、成员数、人物数、当前角色和能力；继续保留已经开放的世系、谱文、相册、视频、功德、祭祀和家族圈入口。没有家谱上下文时阻止业务请求并返回家谱选择页。

管理员权限能力已经由 profile-family-admin.html 的成员角色修改、移出、退出和谱主转移覆盖。profile-admin-permissions.html 不再维护第二套表单，改为携带家谱上下文进入成员管理页；所有现有导航同步指向唯一 owner 页面。

6. 保持阻断的页面和能力

以下能力在后端没有 PC Controller，不实施假功能：

• profile-invite.html：没有成员邀请、邀请令牌或邀请链接接口
• profile-share.html：没有家谱分享、二维码或奖励记录接口
• profile-data-reminders.html：没有资料完善提醒查询或配置接口
• 个人资料地区保存：ProfileUpdateBody 没有地区字段

后端备忘录和成长记录的 remindTime 继续由已经开放的对应页面维护，不把它们误作“资料完善提醒”接口。

页面脚本边界

• 扩展 public/js/genealogy-entry-pages.js：家谱创建、我的加入申请、撤销申请。
• 新增 public/js/join-review-pages.js：待审核申请与审核。
• 新增 public/js/feedback-pages.js：反馈提交、列表和基于列表的详情匹配。
• 新增 public/js/vip-pages.js：套餐、订单创建和订单列表。
• 新增 public/js/family-home-pages.js：家谱 overview 展示。
• public/js/member-admin-pages.js 继续作为家谱成员权限唯一实现，不复制到旧权限页。

每个脚本导出纯规范化、校验、渲染函数和页面初始化函数，沿用 UMD 结构、ProfileUI.requireGenealogyContext()、401/403 分流、可见文本转义、稳定字符串 ID、防重复提交和写后重读。

错误和隐私

• 401 清理登录态；403 保留登录态并展示权限不足。
• 没有家谱上下文时不发送家谱业务请求。
• 所有写操作使用单一 writePending 锁，提交按钮同步禁用。
• 后端响应缺少必需稳定 ID、返回不安全数字长 ID、状态不在已确认枚举内时，整条记录拒绝渲染。
• 普通页面不展示内部用户 ID、处理人 ID、OSS ID、原始 JSON。
• 创建、申请、审核、反馈和订单成功后均重读对应资源，不能仅凭成功提示宣称完成。

测试与阶段顺序

每个阶段严格执行 RED → GREEN → 聚焦回归：

1. ApiClient 契约：新增 method/path/query/body 白名单测试。
2. 家谱创建：额度、地区选择、上传派生封面、成功上下文。
3. 加入申请：申请、我的申请、撤销、审核和权限。
4. 反馈与工单：共享 DTO、列表详情匹配、隐私和无独立 ticket path。
5. VIP：套餐选择、订单白名单、待支付边界、无伪支付。
6. 家谱主页与权限入口：overview、上下文传播、唯一成员管理入口。
7. 更新 pending/PC scope/navigation 测试，运行全量测试并使用真实账号验证无家谱和有数据分支；没有测试数据时明确记录未覆盖，不制造记录。