jiapuapp/docs/release-blockers.md

上线前待处理事项

2026-08-22：下方关于后端能力“尚未实现”的描述属于历史快照。最新源码与 MuMu 点击联调结果、当前真实阻塞项以 《APP 前后端联调结果与后端处理单（2026-08-22）》 为准。

更新时间：2026-08-17

2026-08-17 更新：需要直接交给后端执行的缺口、源码核对结果和接口验收标准统一记录在 《后端开发对接任务单》。本文件继续保留发布、安全和环境阻塞；下方较早的参考项目差距描述如与新任务单冲突，以任务单为准。

本文只记录当前前端仓库无法独立闭环的事项。完成后应删除对应条目，不能将本文当作长期豁免。

已核对范围

• 参考项目 C:\Users\Rain\Desktop\job\Jiapu-App 共注册 78 个路由；pages/index/video/video2.nvue、video3.nvue、video4.nvue 均为有效视频页，已纳入逐项对比并在当前项目补齐纵向观看。pages/index/genealogyList/ancestorsOrder.vue 仅有 67 字节空壳，不作为待迁移功能。全部参考路由已按业务能力映射到当前 59 个页面。
• 后端目录 C:\Users\Rain\Desktop\job\Genealogy 已可读取完整源码；2026-08-17 已完成 APP 认证、VIP、族人档案、视频评论、权限、回收站与删除引擎的静态核对。该目录当前不是可识别的 Git 工作树，本轮没有修改或运行后端；前端契约仍以仓库内唯一的 genealogy-app-openapi.yaml 为准。

P0：Android 原生隐私弹窗链接指向错误或过期协议

• 现状：androidPrivacy.json 中“用户协议”仍指向旧 H5 内容 id=62。2026-08-13 实测该公开页面标题为“会员服务协议”，正文生效日期为 2021-08-08，与 App 内合规接口返回的《代代相传家谱用户协议》（版本 1.0，生效日期 2026-08-10）不是同一文档；id=63 的隐私政策也仍是旧内容源。原生弹窗发生在 WebView 和 App 内页面加载前，不能直接复用当前 Vue 合规页。
• 责任端：后端合规内容维护者 / H5 发布负责人 / Android 发布负责人。
• 处理要求：为当前 user_agreement 和 privacy_policy 提供无需登录、可在系统 WebView 打开的稳定 HTTPS 正文地址，再替换 androidPrivacy.json 两处首轮提示和两处二次确认链接。页面正文、版本号、生效日期、主体和联系方式必须与当前合规接口一致；不得继续用会员协议冒充用户协议。
• 验收：全新安装后点击原生弹窗的两个链接，分别打开 2026-08-10 生效的正式用户协议与隐私政策；拒绝、二次确认、同意路径均正常；抓包确认正文地址无需用户令牌且全程 HTTPS。

P0：正式隐私政策缺少 uni-app/DCloud 运行时披露

• 现状：当前线上 privacy_policy 正文详细列出了阿里云 OSS、阿里云短信和微信支付，但没有说明产品基于 DCloud uni-app（5+ App/Wap2App）开发，也没有披露相应运行时为统计分析、启动与异常日志所处理的设备标识信息。DCloud 的 Android 应用市场合规自查明确要求在 App 隐私政策中补充这部分说明；该正文由后端合规内容管理，前端不能自行改写线上法律文本。
• 责任端：隐私合规负责人 / 后端合规内容维护者。
• 处理要求：由合规负责人按正式包实际启用的 DCloud 模块、统计配置和 SDK 清单核实处理目的、信息类型、共享对象、隐私政策链接及关闭方式，再更新 privacy_policy 新版本并重新发布；不能照抄超出实际能力的模板字段。
• 验收：正式隐私政策逐项覆盖安装包实际 SDK 与权限；DCloud 隐私合规检测和目标应用商店人工审核通过；App 内正文与 Android 原生弹窗链接打开的是同一生效版本。

P0：认证契约将无盐 MD5 摘要直接作为密码凭据

• 现状：唯一 OpenAPI 的注册、密码登录、修改密码和找回密码统一要求客户端提交 32 位 MD5，当前前端只能按该契约调用。无盐 MD5 是快速、可离线猜测且可重放的固定凭据；它不能替代 TLS，也不符合现代密码存储应使用逐用户盐值和有成本密码派生算法的要求。前端不能单方面改算法，否则现有账号与后端认证会全部失配。
• 责任端：后端认证负责人 / 安全负责人 / OpenAPI 维护者。
• 处理要求：先确认服务端数据库是否还会对收到的 MD5 再使用 Argon2id、scrypt、bcrypt 或 PBKDF2 等带盐算法存储；若没有，必须制定密码凭据迁移。新契约应明确传输只依赖 HTTPS，服务端保存逐用户盐值的慢哈希；如需兼容旧账号，应在一次成功登录后升级存储，并定义旧契约下线时间，不能长期接受两套等价入口。
• 验收：数据库泄露场景下不存在可直接重放登录的客户端 MD5 凭据；新注册与改密只产生带盐慢哈希；旧账号迁移、并发登录、忘记密码和回滚均有服务端自动测试；OpenAPI 与客户端在同一版本切换。

P0：会话令牌仍存放在普通应用缓存

• 现状：当前 utils/session.js 通过 uni.setStorageSync 持久化 Bearer access_token。该接口只提供应用本地缓存能力，仓库中没有使用 Android Keystore、iOS Keychain 或由其保护的加密封装，也没有可验证的令牌备份排除策略。令牌被提取后可直接代表用户访问家谱及重要证件等敏感数据，前端 JavaScript 内置固定加密密钥不能解决此问题。
• 责任端：App 原生安全负责人 / 认证后端负责人 / 发布负责人。
• 处理要求：正式 App 使用经过审查的原生安全存储插件，以 Android Keystore 和 iOS Keychain 保护会话材料；禁止把密钥硬编码进前端资源。后端同时提供短期访问令牌、可撤销的刷新令牌、设备/会话管理和异常吊销能力，并明确备份恢复、换机、卸载和设备锁屏后的行为。
• 验收：正式签名包的动态与静态安全测试确认普通缓存、备份和日志中没有明文会话令牌；退出登录、注销、改密和服务端吊销后旧令牌立即失效；新安装、换机和备份恢复不会继承可用会话。

P0：VIP 后端仍是微信单渠道契约

• 现状：前端已经按 OpenAPI 接入微信、支付宝和余额三种方式，并根据 capability 动态展示可用渠道。后端 PaymentOrderVo 已有微信 prepayId 和签名字段，但 VipPurchaseCapabilityVo 没有 paymentMethods，AppVipOrderBody 没有 paymentMethod，支付结果也没有渠道判别字段与支付宝/余额结果。
• 责任端：C:\Users\Rain\Desktop\job\Genealogy 后端支付模块。
• 处理要求：按唯一 OpenAPI 同步 capability、下单体和支付结果；微信继续返回完整预支付参数，支付宝返回 APP 支付订单字符串，余额支付在服务端事务内完成扣款与会员开通。
• 验收：三种渠道分别覆盖成功、取消、失败和超时查询；同一订单不能重复支付或重复开通，余额不足不能返回伪成功。

P0：微信开放平台和云打包参数未提供

• 现状：manifest.json 已启用 Payment 模块，但仓库没有可确认的正式微信 AppID、Android 包名/签名对应关系、iOS Universal Links 和发布签名材料。
• 责任端：发布负责人 / 微信开放平台管理员。
• 处理要求：在 HBuilderX 云打包配置中填写正式参数并完成微信开放平台校验。密钥、证书密码和 AppSecret 不得提交到仓库。
• 验收：Android 与 iOS 正式签名包都能拉起微信，支付后能返回应用并由服务端确认订单状态。

P1：推广绑定前端已完成，等待后端实现

• 现状：注册页已支持推荐码，个人中心已提供“我的推荐”、复制和分享入口；后端注册体仍没有 referralCode，也没有推荐资料、归属或分佣服务。
• 责任端：产品负责人 / 后端负责人。
• 处理要求：按唯一 OpenAPI实现注册时一次绑定和 /referrals/me；服务端落实防自邀、防重复绑定、并发幂等和收益归属，前端不接受本地伪造统计。
• 验收：分享、首次绑定、无推荐码、自邀、重复绑定、并发注册和收益入账均有服务端测试。

P1：微信快捷登录前端已完成，等待后端实现和正式配置

• 现状：前端已启用 OAuth 模块并完成 uni.login({ provider: "weixin" }) 授权码登录、取消和失败状态；后端 AppAuthController 仍没有 /auth/login/wechat，正式微信开放平台参数也未提供。
• 责任端：产品负责人 / 后端认证负责人 / 微信开放平台管理员。
• 处理要求：按唯一 OpenAPI 实现一次性授权码交换、已有账号匹配/绑定和冲突响应，并配置正式微信开放平台参数；AppSecret 不得进入前端仓库。
• 验收：Android/iOS 正式包都能完成首次授权、已有账号登录、取消授权、重复登录和账号冲突，客户端不直接信任微信展示资料。

P1：宣传视频前后端主体已存在，等待收紧评论契约和联调

• 现状：当前前端已有独立平台视频页，支持播放、点赞、一级评论和删除；后端 AppPlatformVideoController 已有列表、详情、点赞和评论。后端评论请求仍允许 parentCommentId，与本期平台视频只保留一级评论的契约冲突。
• 责任端：产品负责人 / 后端内容负责人。
• 处理要求：后端去掉平台评论 parentCommentId 输入并清理或迁移已有回复数据；按 placement、platform 和上下线时间返回有效视频。
• 验收：首页入口、列表播放、空状态、失效视频、点赞幂等和一级评论可在正式环境验证。

P1：细粒度权限前端已完成，后端缺动态权限目录

• 现状：前端成员管理已按动态目录渲染分组权限并读取/保存成员授权。后端成员权限 GET/PUT 已存在，但没有 /permission-catalog；前端不会重新硬编码参考项目的 auth_str。
• 责任端：产品负责人 / 后端权限负责人 / OpenAPI 维护者。
• 处理要求：基于后端唯一权限定义实现 /permission-catalog，返回权限编码、名称、分组和禁用原因；保存接口返回最终权限集合并由服务端统一判权。
• 验收：新增权限无需前端发版即可出现；所有页面显示能力与服务端鉴权一致，越权请求被拒绝。

P1：永久注销前端已完成，后端缺 APP 谱主入口

• 现状：前端设置页已完成归档前置、不可用原因、脱敏手机号、精确家谱名和短信双确认。后端已有管理员使用的删除资格检查、任务和执行引擎，但没有 APP 谱主发码/提交入口，AppGenealogyVo 也没有能力投影字段。
• 责任端：产品负责人 / 后端家谱负责人 / 数据合规负责人。
• 处理要求：按唯一 OpenAPI 为现有删除引擎增加 owner-only APP 包装，校验已归档、阻塞任务、精确名称和短信码；成功后立即撤销所有成员端的家谱上下文。
• 验收：非谱主、未归档、名称不符、错码和阻塞任务均拒绝；成功提交可审计、任务失败可追踪重试，成员不能继续访问该家谱。

P1：真实写操作与商店发布仍需发布环境验收

• 现状：本轮 MuMu 点击测试使用已登录账号，避免对现有家谱执行删除、撤销邀请、上传、提现等不可逆或会产生真实数据的操作；也未持有应用商店账号和正式签名材料。
• 责任端：测试负责人 / 发布负责人。
• 处理要求：使用专用测试租户走通创建、编辑、上传、邀请、撤销、注销和提现审核等流程，再进行 Android/iOS 正式构建与商店隐私合规检查。
• 验收：测试数据可清理，关键写操作、失败重试和权限边界均有记录；正式包安装、升级、冷启动和回退流程通过。

P1：多数创建接口缺少跨会话幂等契约

• 现状：前端已对创建家谱、成员、谱文、动态、相册、视频、祭祀和成长记录等写操作增加当前页面生命周期内的重复提交保护，但应用重启、页面重载、请求超时后重试会丢失这层状态。唯一 OpenAPI 目前只有提现请求提供稳定的 requestId，其余创建接口没有定义可跨会话重放的幂等键，因此客户端无法保证弱网重试只产生一条业务数据。
• 责任端：各业务后端负责人 / OpenAPI 维护者。
• 处理要求：由服务端统一定义幂等键的所有者、作用域、有效期和重放响应语义，并通过租户、用户、操作类型和幂等键建立持久化唯一约束；不能只依赖单进程内存锁或前端按钮禁用。相同幂等键携带不同业务参数时应明确拒绝。
• 验收：双击、请求超时、连接中断、应用重启后使用同一幂等键重试，服务端只创建一次并返回同一业务结果；同键不同参数被拒绝；并发请求有自动化覆盖。

P1：大文件上传没有真实分片和明确大小契约

• 现状：当前上传初始化、分片、完成三段接口已经接入，文件上传已与普通 API 的 15 秒超时分离，独立放宽为 120 秒。但客户端仍固定 totalChunks: 1、chunkSize: 文件总大小，视频会作为一个完整请求上传。唯一 OpenAPI 没有声明图片/视频最大大小、服务端允许的分片大小和分片数量上限，因此前端无法据此安全拆分或给出准确限制。普通小图片不受此项影响，较大视频仍可能受内存和弱网影响。
• 责任端：文件服务负责人 / OpenAPI 维护者 / 前端负责人。
• 处理要求：由文件服务先确定最大文件大小、推荐分片大小、并发数、断点续传和过期上传清理规则，并写入唯一 OpenAPI；随后客户端按字节范围计算每片 MD5，逐片上传，不能继续把完整视频称作分片。
• 验收：在弱网环境上传接近上限的视频，中断后可继续或明确重新开始；任一分片大小、MD5 或顺序错误均被服务端拒绝；客户端不会一次性把完整大视频读入内存，上传超时后也不会留下不可识别状态。

P1：隐私政策声明与当前客户端能力不完全一致

• 现状：当前客户端只在用户主动选择上传内容时读取相册或媒体库，没有调用相机，也没有接入系统推送通知；线上隐私政策的“设备权限”章节仍声明可能申请相机和通知权限。前端已只配置实际需要的相册读取权限，没有为了匹配文案增加无用权限。
• 责任端：隐私合规负责人 / 后端内容运营。
• 处理要求：按最终正式包逐项核对权限清单。若本期不接入拍摄和系统推送，应从线上隐私政策删除相机、通知相关声明；若本期确实接入，则需先完成对应产品功能、运行时授权时机和拒绝授权后的降级流程，再更新正式包权限。
• 验收：Android 与 iOS 正式包的权限清单、运行时弹窗、应用商店隐私标签及线上隐私政策逐项一致，普通浏览页面不会提前申请媒体权限。

P1：公共内容接口的线上匿名访问不符合 OpenAPI

• 现状：唯一 OpenAPI 将官网文章、官网单页、帮助列表/详情和推广列表标记为 security: []。2026-08-13 使用必需的 clientid、tenantId 且不带 Authorization 抽查线上环境时，GET /genealogy/app/site/articles、GET /genealogy/app/site/pages/{pageKey}、GET /genealogy/app/help-articles、GET /genealogy/app/help-articles/{helpId} 和 GET /genealogy/app/promotions 均返回业务 401；同样声明匿名的行政区划和合规文档接口可以正常读取，说明不是公共请求头缺失。GET /genealogy/app/genealogies/public 虽然名称包含 public，但没有覆盖全局 SaToken，线上返回 401 与当前 OpenAPI 一致，不属于本项偏差。当前帮助与推广页面只从登录后的个人中心进入，前端暂时沿用会话请求以保持线上功能。
• 责任端：后端鉴权配置维护者。
• 处理要求：按 OpenAPI 对上述公共内容只读接口放行匿名访问；公共请求仍应保留租户与客户端头，不应依赖用户令牌。若产品决定必须登录，则应先修改 OpenAPI 和产品入口，再由前端统一收口，不能让线上行为与唯一契约长期分叉。
• 验收：无 Authorization 请求上述接口均返回业务成功；携带过期令牌不会导致公共页面跳转登录；帮助文章、推广位和官网公共内容能在退出登录状态正常读取。

P2：MuMu 的 Chromium 图块内存警告仍存在

• 现状：六张通用长背景已从 1440×3600 缩至 720×1800，并改为按视口裁切，图片体积由约 31.7 MB 降至约 13.9 MB；页面实测没有缺图。MuMu 中的 HBuilder 调试基座冷启动仍会输出 8 条 tile memory limits exceeded，PSS 约 159 MB。
• 已确认边界：警告来自调试基座的 Chromium 渲染进程，当前没有对应的 Vue 异常或页面缺失；仅靠继续压缩单张背景无法证明可以消除。
• 责任端：测试负责人 / 前端负责人。
• 处理要求：使用正式签名包在至少一台中端 Android 真机复测首页、个人中心和世系页；通过 Android Studio Profiler 确认是调试基座开销还是页面合成层问题。
• 验收：正式包连续浏览核心页面不出现缺图、闪白或崩溃；若仍有警告，取得可定位到具体图层的 trace 后再调整对应页面，不能无依据继续降画质。

P2：推广封面素材清晰度不足

• 现状：MuMu 实测“我的 → 应用推广”时，服务端返回的“数字家谱，从今天开始”封面被放大后明显模糊；同页文字、边框和本地品牌图均清晰，可排除整个页面缩放异常。
• 责任端：推广内容运营 / 后端文件管理。
• 处理要求：在推广管理端替换为适合横向卡片的高清封面，建议有效宽度不低于 1200 px，并保留合理宽高比；不要让客户端对低分辨率缩略图进行放大。
• 验收：Android 设备 1×、2×、3× 密度下查看推广中心和首页推荐位，图片无明显锯齿、马赛克或拉伸变形。

P2：HBuilder 调试基座重启时漏部署运行时文件

• 现状：首次启用 androidPrivacy.json 后，HBuilder 调试基座重启曾缺少 __uniappview.html 和 uni-app-view.umd.js，显示 ERR_FILE_NOT_FOUND。本轮测试通过把本地编译产物重新部署到 MuMu 后恢复，项目编译产物本身包含这两个文件。
• 责任端：测试环境维护者。
• 处理要求：下次运行前由 HBuilderX 重新执行“运行到 Android App 基座”，不要依赖本轮模拟器内的临时部署结果。
• 验收：清理并重建调试基座后可连续冷启动三次，且不再出现 ERR_FILE_NOT_FOUND。