fizzleaf
157 lines
8.2 KiB
Markdown
157 lines
8.2 KiB
Markdown
# 剩余 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/provinces`
|
||
- `GET /genealogy/pc/region/children/{parentCode}`
|
||
|
||
请求只提交 `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 测试，运行全量测试并使用真实账号验证无家谱和有数据分支；没有测试数据时明确记录未覆盖，不制造记录。
|
||
|