# 开发进度、注意事项与遗留问题

> 本文档记录已确认的开发进度、跨页面实现约定与尚未解决的问题。每完成一个页面的细化并验收后，必须同步更新本文档、接口文档和该页面操作说明。

## 2026-07-31 实际状态

- 人才端统一请求、会话、支付/退款、订单、动态人才码、资讯、权益专题、商户详情、配偶就业、加油手机号、停车车牌、子女信息和学校详情等一期后端链路已落地；开发环境使用 `config/api.uts` 中的地址，页面不直接拼接请求。
- 之前表格中的“后端接口层：未开始”以及各页面“真实接口待接入”属于接口接入前的历史记录，不能作为当前开发判断依据。详细端点以 `docs/项目接口对接说明.md`、`services/portal.uts` 和服务端 Controller 为准。
- 本轮明确不实现二期：酒店/体检预约、电影券码、洗车凭证审核、停车录入扩展、服务浏览记录、家属附属卡运营、微信客服及其管理后台配置。页面保留基础入口或安全提示，不使用虚假成功数据代替后台闭环。
- 当前剩余工作集中在真机验收、正式域名/隐私配置、真实数据补录和后端业务规则确认；不应因旧表格文字重复开发已完成能力。

## 历史页面进度（接口接入前）

| 项目项 | 状态 | 说明 |
| --- | --- | --- |
| uni-app X 工程骨架 | 已完成 | 以 `.uvue` + `.uts` 为主，面向微信小程序运行。 |
| 微信小程序 AppID | 已配置 | `wx6ae2cadfea28fce1` 已写入 `manifest.json`。 |
| 页面路由骨架 | 已完成 | `pages.json` 已注册人才端 60 个页面，完整覆盖登录、五个主模块、权益专题、商户/商品、支付预约、使用记录和个人中心业务。 |
| 首页视觉首版 | 进行中 | 已接入自定义顶部栏、城市图片、资讯和自定义底部导航，仍需逐项按设计稿细化。 |
| 登录页视觉与交互骨架 | 已完成 | 已提供微信授权、手机号登录和协议确认入口；用户协议与隐私协议统一进入现有富文本协议页，等待真实登录及协议接口。 |
| 人才资讯列表页 | 已完成视觉与静态 ID 跳转首版 | 已完成列表、缩略图和首页入口，首页及列表条目均携带稳定 `newsId`；真实分页接口待接入。 |
| 资讯详情页 | 已完成视觉、ID 与富文本状态首版 | 已按 `newsId` 加载对应标题、发布信息、浏览量及 `rich-text` 正文，并补齐加载、空、失败、重试状态；真实详情接口待接入。 |
| 人才权益页 | 已完成视觉首版 | 已按设计图完成顶部主图、搜索、八类权益入口、推荐权益列表和底部导航；动态分类、搜索及列表接口待接入。 |
| 人才权益搜索页 | 已完成视觉与交互首版 | 已完成搜索输入、搜索历史、历史回填和清空确认；真实搜索结果接口待接入。 |
| 暖心食享餐饮页 | 已完成视觉与交互首版 | 已完成可配置主图、横向图册切换、动态菜名与描述、餐饮商户列表；后台专题配置接口待接入。 |
| 暖心食享商家页 | 已完成视觉、交互与商品 ID 链路首版 | 已完成沉浸式头图、商户信息、消费购买/权益详情切换、套餐列表和出示人才码入口；套餐使用稳定 `productId` 并携带 `merchantId` 进入商品链路，真实商户与支付接口待接入。 |
| 暖心食享商品详情页 | 已完成视觉、交互与参数链路首版 | 已完成商品头图、价格、图片与纯文本详情、四项固定购买须知和立即购买入口；页面按 `productId` 展示不同套餐并继续传递 `merchantId`、`productId`、`orderId`，真实详情接口待接入。 |
| 订单支付页 | 已完成视觉、交互与订单上下文首版 | 已按路由业务 ID 展示对应商品摘要和金额，优惠券选择保留订单上下文；确认支付使用 `redirectTo` 进入成功页，避免返回重复支付，真实微信支付接口待接入。 |
| 优惠券选择页 | 已完成视觉与交互首版 | 已完成可用优惠券列表、选择回填及暂无优惠券空状态；真实优惠券与订单试算接口待接入。 |
| 支付成功页 | 已完成视觉与流程栈首版 | 已完成支付结果、待核销状态、订单号和查看使用记录入口；返回及按钮均重置流程进入待核销使用记录，真实支付结果查询待接入。 |
| 人才卡页 | 已完成视觉与交互首版 | 已按设计图完成卡面、动态码展示、服务专员、咨询电话和底部导航；真实人才卡及动态码接口待接入。 |
| 独立人才码页 | 已完成视觉与交互首版 | 商户详情、停车人才码状态和学生托付统一进入可返回的独立亮码页；真实动态码接口待接入。 |
| 人才政策页 | 已完成视觉与交互首版 | 已完成顶部主图、分页政策列表、加载/到底/空状态和底部导航；真实政策列表接口待接入。 |
| 人才政策详情页 | 已完成视觉与交互首版 | 已完成顶部图片、政策摘要和图片加纯文本说明；真实详情接口待接入。 |
| 个人中心页 | 已完成视觉与交互首版 | 已按设计图完成用户信息卡、升级人才卡、家庭附属卡、使用记录、设置及退出登录入口；真实用户与人才卡接口待接入。 |
| 设置页与协议详情 | 已完成视觉与交互首版 | 设置页和登录页共用用户协议、隐私与权限富文本页面，支持按来源返回；真实安全清洗协议富文本与退出登录接口待接入。 |
| 人才卡升级申请页 | 已完成视觉与交互首版 | 已完成默认单组资料、动态添加/删除、日期选择、图片选择、提交校验和成功状态；真实文件上传及审核接口待接入。 |
| 家庭附属卡管理页 | 已完成视觉与交互首版 | 已完成绑定家属、审核状态、新增申请入口、解除绑定确认和空状态；真实附属卡查询、申请及解绑接口待接入。 |
| 新增家属申请页 | 已完成视觉与交互首版 | 已完成基础资料、关系选择、前端校验、提交反馈和管理页待审核状态联动；真实实名校验及申请接口待接入。 |
| 家属卡申请提交成功页 | 已完成视觉与交互首版 | 已完成提交结果与返回列表入口；真实结果以后端申请状态为准。 |
| 家属卡解绑页 | 已完成视觉与交互首版 | 已完成家属选择、解绑校验、二次确认和管理页空状态联动；真实解绑资格及接口待接入。 |
| 家属卡暂未开放页 | 已完成视觉与交互首版 | 已完成人才等级不满足时的提示页；真实开放资格由后台返回。 |
| 使用记录页 | 已完成视觉与交互首版 | 已完成自定义导航、全部/待支付/待核销/已取消/待处理/已领取六类状态筛选、矢量业务图标、分页加载、到底和空状态；已完成记录在全部列表中查看，真实记录列表接口待接入。 |
| 待支付页 | 已完成视觉与订单时效首版 | 已按 `expireAt` 恢复支付倒计时，页面隐藏清理、重新显示恢复；商家地址已统一为攀枝花东区，支付成功替换当前页，真实订单试算及微信支付接口待接入。 |
| 待使用页 | 已完成视觉与交互首版 | 已完成核销二维码、商品与商家摘要、导航/电话、订单信息和退款申请确认；真实动态核销码、订单状态及退款接口待接入。 |
| 已完成订单页 | 已完成视觉与交互首版 | 已完成商品、商家、金额、下单时间和核销时间展示；真实历史订单详情接口待接入。 |
| 已取消订单页 | 已完成视觉与交互首版 | 已完成商品、商家、取消前金额构成和取消时间展示；真实取消原因及退款状态接口待接入。 |
| 待处理预约页 | 已完成视觉与交互首版 | 已完成等待状态、机构导航/电话、预约详情和联系专员入口；真实处理进度、预约及专员接口待接入。 |
| 酒店预约页 | 已完成视觉、日期校验与流程栈首版 | 入住默认日期和可选最小日期动态取当天，离店日期必须晚于入住日期；提交成功替换表单页，真实日期、库存和预约接口待接入。 |
| 酒店预约提交成功页 | 已完成视觉与流程栈首版 | 已完成预约提交结果，返回与按钮均进入待处理使用记录，不会回到已提交预约表单；真实预约单结果查询待接入。 |
| 免费权益页 | 已完成视觉与交互首版 | 已完成酒店免费券二维码、剩余使用次数和权益说明展示；真实动态券码与核销状态待接入。 |
| 怡乐生活页 | 已完成视觉与交互首版 | 已完成夜景专题头图、横向图册、休闲文娱介绍和观影服务分页列表；真实专题与服务接口待接入。 |
| 电影院商户详情页 | 已完成视觉与交互首版 | 已完成沉浸式影院头图、商户地址、导航/电话、消费购买与权益详情切换、零元电影券领取及领取确认弹窗；真实商户、库存及领券接口待接入。 |
| 电影券领券成功页 | 已完成视觉与交互首版 | 已完成年度权益进度、领取/剩余/总计统计、电影兑换码展示和复制，并与使用记录“已领取”详情共用；真实用户券详情及兑换码接口待接入。 |
| 畅行无忧行服务页 | 已完成视觉与交互首版 | 已完成沉浸式头图、横向图册居中放大、橙色悬浮介绍卡、加油/停车/洗车分类及分页列表状态；真实专题配置与行服务接口待接入。 |
| 加油商家详情与手机号提交成功页 | 已完成视觉与交互首版 | 已完成加油站信息、9.4折权益、地图/电话、纯文本使用说明、后台门店表格与单店定位、手机号输入校验及成功反馈；真实商户、门店与手机号登记接口待接入。 |
| 停车服务商详情、车牌信息与提交成功页 | 已完成视觉与交互首版 | 已完成“填写车牌/出示人才码”双底部状态、双车牌表单模式和独立提交成功反馈；真实停车服务与登记结果接口待接入。 |
| 自助洗车服务商详情页 | 已完成视觉与交互首版 | 已完成服务信息卡、服务点说明、底部单一“去洗车”按钮，并预留外部小程序/业务域名网页两种跳转；真实详情与外链配置接口待接入。 |
| 惠享好物购物服务页 | 已完成视觉与交互首版 | 已完成沉浸式头图、横向居中图册、悬浮介绍卡、购房/购车/家电/数码/图书五分类及分页列表状态；真实专题与购物服务接口待接入。 |
| 购物服务统一详情页 | 已完成视觉与交互首版 | 购房/购车/家电/数码/图书全部使用信息展示详情，展示头图、优惠、人才卡、地址和纯文本权益，底部仅保留“联系专员”；真实详情与专员接口待接入。 |
| 臻享礼遇综合服务页 | 已完成视觉与交互首版 | 已完成沉浸式头图、居中图册、悬浮介绍卡、免费体检/配偶推荐就业/金融服务/行政审批/学生托付五分类及分页列表状态；真实专题与综合服务接口待接入。 |
| 配偶推荐就业流程 | 已完成视觉与交互首版 | 已完成权益说明、九项配偶资料填写、学历/在编状态选择、手机号与身份证校验、已提交待处理结果及使用记录联动；真实申请与处理状态接口待接入。 |
| 行政审批详情页 | 已完成视觉与交互首版 | 已完成沉浸式头图、免费标识、机构地址/权益说明/咨询电话列表、拨号联动和窗口信息弹窗；真实机构列表与窗口信息接口待接入。 |
| 金融服务商家详情页 | 已完成视觉与交互首版 | 复用购房购车统一详情结构，已完成机构信息、人才卡标签、地图/电话、纯文本权益详情和联系专员入口；真实金融服务详情与专员接口待接入。 |
| 学生托付详情页 | 已完成视觉与交互第二轮修正 | 学校名称已支持进入学校介绍富文本详情，定位/电话保持独立操作；真实权益说明、学校列表与详情接口待接入。 |
| 学校介绍详情页 | 已完成视觉与交互首版 | 已完成学校名称/地址快照、后台富文本渲染结构、内部滚动及加载/空/失败状态；真实详情接口待接入。 |
| 添加子女信息页 | 已完成视觉与交互首版 | 已完成姓名、性别、出生年月、最多 3 张亲属关系证明材料的选择/删除及提交回填；支持审核不通过资料回填与重新提交，真实材料上传、新增子女和审核接口待接入。 |
| 子女信息列表页 | 已完成视觉与交互首版 | 已完成子女信息卡片、审核不通过原因与修改入口；重新提交后原记录恢复待审核且不重复新增，真实子女列表与审核接口待接入。 |
| 体检医院详情页 | 已完成视觉与交互首版 | 臻享礼遇免费体检列表以 `type=medical` 接入 merchant 体检模式，完成预约/权益详情双状态、体检套餐列表和编号使用说明；真实医院与套餐接口待接入。 |
| 体检套餐详情页 | 已完成视觉与交互首版 | 已完成沉浸式头图、套餐信息、医院导航/电话和检查项目男女适用表格；真实套餐与检查项目接口待接入。 |
| 体检预约页 | 已完成视觉、日期校验与流程栈首版 | 期望日期默认次日、最小可选日期动态取当天，提交前校验日期；成功后替换表单页，真实初始化与预约接口待接入。 |
| 体检预约提交成功页 | 已完成视觉与流程栈首版 | 已完成预约提交结果和待处理状态，返回与按钮均进入待处理使用记录；真实预约结果查询待接入。 |
| 主要分页列表加载状态 | 已完成统一状态与失败重试 | 推荐权益、权益搜索、吃/游/住/娱/行/购/享、人才政策和使用记录共 11 页已统一使用 `initialLoading`、`loadingMore`、`hasLoaded`、`hasMore`、`initialError`、`loadMoreError`，支持首屏及下一页点击重试。 |
| 后端接口层 | 未开始 | 当前页面使用静态演示数据，尚未创建请求封装或真实接口。 |
| 页面级操作文档 | 已完成当前静态页面覆盖 | `docs/pages/` 已登记 `pages.json` 的 60 个注册页面，并补充通用商户不同业务模式说明；后续随接口和交互变更持续维护。 |

## 已落实的实现约定

- 首页使用自定义导航栏（`navigationStyle: custom`），通过 `uni.getMenuButtonBoundingClientRect()` 适配微信右上角胶囊位置。
- 首页使用自定义底部导航，不启用 `pages.json` 原生 `tabBar`。
- 五模块自定义底部导航使用默认/选中两套图标资源：当前页面图标与文字显示橙色，其余普通导航项显示灰色；中间人才卡按钮保持设计稿的橙色主入口样式。
- 首页、人才权益、人才卡、人才政策、个人中心属于同级主页面，自定义底部导航切换统一使用 `uni.reLaunch`，不得使用 `uni.navigateTo`，避免出现二级页面的左滑入动画和错误页面栈。
- 支付、预约、申请等完成页进入使用记录时统一使用 `uni.reLaunch` 关闭已完成流程，避免用户返回后重复提交；所有页面返回统一调用 `utils/navigation.uts` 的 `safeBack(fallbackUrl, delta)`，页面栈足够时原路返回，处于栈底或栈深不足时进入明确的业务兜底页，页面代码禁止直接调用 `uni.navigateBack`。
- 支付、酒店预约和体检预约在提交成功后必须使用 `uni.redirectTo` 替换表单页；成功页左上角返回不得依赖旧页面栈，统一进入对应状态的使用记录。
- 待支付倒计时必须以后端订单绝对失效时间 `expireAt` 为准，页面 `onShow` 重新计算，`onHide/onUnload` 清理定时器；不得仅在首次进入时从固定秒数递减。
- 酒店和体检预约日期选择器的最小日期动态取设备当天，提交时必须再次校验，禁止保留固定的历史日期。
- 商户、停车服务和学生托付等业务场景的“出示人才码”统一进入 `/pages/talent-code/talent-code` 独立亮码页，不得 `navigateTo` 到无返回按钮的平级人才卡主页面。
- 餐饮购买链路固定使用 `merchantId → productId → orderId`：商户套餐不得只传名称，商品详情和订单支付不得写死商品 ID，优惠券往返及支付成功页必须保留当前订单上下文；展示快照只用于静态首屏，正式数据仍按业务 ID 请求。
- 本地静态资源放在 `static/` 下，引用统一使用 `/static/...` 绝对路径。
- 首页顶部城市图使用 `static/home-assets/home-banner-v2.jpg`；如替换图片，请使用新文件名以规避微信开发者工具资源缓存。
- 首页顶部标题当前实际使用 `static/home-assets/home-title-left-v3.png`。原字体文件超过微信预览包限制，因此开发预览阶段使用透明 PNG，不直接打包原始完整字体。
- 人才权益原始顶图约 9.1MB，项目内使用压缩后的 `static/benefits-assets/benefits-hero.jpg`（1080×607，约 140KB），禁止将原图直接加入小程序包。
- 小程序预览主包上限为 4MB。娱页面图片和首页城市小卡图已使用面向显示尺寸的 WebP 资源；新增或替换资源后必须检查编译目录总大小并预留至少 200KB 余量，原始大图保留在项目外的 `icon/` 素材库中，不得直接放入 `static/`。
- **体验版专题素材规则**：吃／游／住／娱／行／购／享每个专题最多保留 2 张唯一演示图片，图册可保留多个滑动项但必须循环复用这两张图；商户、商品、支付、预约和订单详情优先复用所属专题图片，不再单独打包重复封面。完整素材保留在项目外 `icon/`，正式全量版由后台/CDN加载；每次新增图片前必须先检查编译包体并保留安全余量。
- 暖心食享演示菜名使用 `static/fonts/food-calligraphy-subset.ttf` 字体子集，编译后以内联字体使用；完整“古典艺术行楷简”（5.35MB）不进包，放服务器 `/uploads/fonts/gudian-xingkai.ttf`，由 `App.uvue` 启动时 `uni.loadFontFace` 动态加载（`family: 'FoodCalligraphyFull'`，`global: true`），专题页 `.scene-name/.dish-name` 优先用它、失败回退子集与系统字体。**覆盖范围**：7 个专题页顶部大图的那行名称（吃/游/住/娱/行/购/享）——吃用 `.dish-name`，其余用 `.scene-name`；住—舒心安居与娱—怡乐生活原先没有（或只有子集）声明，已按同一套字体链补上。
- 所有“顶部背景全图/沉浸式头图”页面统一使用固定自定义导航栏：导航栏必须放在纵向滚动容器外，返回按钮和标题不得随内容滚走；初始状态透明叠加在头图上，页面上滑超过 `64px` 后渐显橙色实体渐变背景，背景使用 `linear-gradient(180deg, #F26A38 0%, #EE542B 100%)` 和 `280ms ease-out` 透明度过渡；导航高度、底部留白和微信胶囊适配保持与首页一致。除非设计图明确要求不同，后续同类页面必须按此方式交付。当前已应用：首页、人才权益、暖心食享、商家详情、商品详情、人才政策。
- 吃／游／住／娱等“顶图 + 图册 + 介绍文案 + 列表导航”专题页，介绍卡必须置于正常文档流并由内容自然撑高，同时通过统一的 `-66rpx` 负外边距向上覆盖顶图，保留悬浮效果；列表导航区固定使用介绍卡底部后的 `48rpx` 间距。不得通过固定介绍卡高度或固定 `padding-top` 猜测文案高度，后台文案变更为多行时，服务列表必须自动向下顺延。
- **全量发版要求**：正式全量发布时，需按发布包策略注入完整的“古典艺术行楷简”字体包，并复核微信小程序分包/总体积限制、字体授权及真机渲染效果；开发预览阶段继续使用标题图片，避免超过预览包限制。
- 中文源码、JSON 和 Markdown 必须保持 UTF-8 编码。
- 页面纵向滚动约定：不涉及列表、动态多组表单或长图文/富文本详情的静态页面，禁止使用纵向 `scroll-view`，并必须在 `pages.json` 配置微信小程序原生 `disableScroll: true`，以禁用真机页面级回弹；页面内容按一屏布局交付。仅列表、分页、动态表单及内容高度不可预知的资讯/政策/商品/协议详情允许纵向滚动。

## 开发注意事项

1. 微信预览代码包存在约 4MB 的限制。新增图片、字体或视频前先检查体积；大图优先压缩为 JPG/WebP，固定艺术字优先导出透明图片或制作字体子集。
2. 自定义导航栏必须预留微信胶囊区域，不能用固定状态栏高度替代设备信息。
3. 自定义底部导航需同时兼容 `safe-area-inset-bottom`，且避免重复额外绘制底部手势条安全区。
4. 修改视觉时先区分资源加载、图层遮挡、尺寸定位三类问题；不要仅靠追加边距修正。
5. 每个细化页面开始前，先创建页面操作说明的草稿；接口字段明确后同步补入接口文档。
6. 接入后台前不得在前端存放 AppSecret、管理端令牌或其他敏感信息。
7. 资讯详情正文按富文本 HTML 对接：服务端必须进行安全清洗，前端使用 `rich-text` 渲染，并统一处理图片宽度、HTTPS 地址和附件预览。

## 分页列表统一加载规范（固定）

> 本规范为项目级固定约定。后续凡是需要分页、上滑加载或加载更多的列表页面，默认按本节实现；若设计图有特殊要求，需在对应页面文档中明确记录差异。

| 项目 | 固定规则 |
| --- | --- |
| 触发方式 | 使用纵向 `scroll-view` 的 `scrolltolower`，默认 `lower-threshold="80"`，进入底部阈值后加载下一页。 |
| 分页追加 | 新数据追加到已有列表末尾，不清空已展示内容；演示阶段每批 4 条，真实 `pageSize` 以后端协议为准。 |
| 状态拆分 | 必须分别维护 `initialLoading`、`loadingMore`、`hasLoaded` 和 `hasMore`；禁止使用同一个 `isLoading` 同时代表首屏与触底加载。 |
| 重复请求保护 | `initialLoading` 或 `loadingMore` 为真、或 `hasMore` 为假时禁止再次触发加载更多。 |
| 首屏加载 | 首次请求及分类/搜索条件重置后展示内容区加载状态；此时不得展示空状态、到底提示或底部加载更多。 |
| 加载更多 | 仅在首屏成功且已有列表内容时，于列表底部显示橙色旋转动画和固定文案“正在加载”；已有内容必须保留。 |
| 到底状态 | `hasLoaded` 为真、列表非空且后台明确无下一页后，显示分隔线和固定文案“已经到底了”。 |
| 空状态 | `hasLoaded` 为真且首次请求成功返回空数组时才展示居中空状态，禁止请求期间提前闪现空状态。 |
| 失败状态 | 请求失败时保留已有列表，显示“加载失败，点击重试”；不得误显示“已经到底了”，也不得清空已加载内容。 |
| 数据主键 | 循环渲染必须使用后台稳定唯一 ID 作为 `key`，不得使用数组下标或可能重复的名称。 |
| 状态重置 | 切换分类、搜索词或筛选条件时重置页码、`hasMore` 和错误状态，再重新请求第一页。 |
| 加载完成判断 | 优先使用后台 `hasNext` / `total`；若后台仅返回数组，则当返回数量小于 `pageSize` 时判定没有下一页。 |
| 首屏失败 | 设置 `initialError=true`、`initialLoading=false`、`hasLoaded=false`，显示局部失败状态和“重新加载”；不得同时展示空状态或到底状态。 |
| 加载更多失败 | 设置 `loadMoreError=true`、`loadingMore=false`，保留已有列表、页码和 `hasMore`，显示“加载失败，点击重试”；不得推进游标或显示到底。 |
| 点击重试 | 首屏重试重新请求第一页；加载更多重试继续请求失败的下一页。请求开始时清理对应错误状态，并继续使用防重复请求锁。 |
| 筛选切换 | 切换分类、关键词或状态时同时清理 `initialError`、`loadMoreError`，旧筛选的失败状态不得污染新列表。 |

当前已应用 11 个页面/列表：人才权益“推荐权益”、人才权益搜索/全部商家、吃—暖心食享、游—悦览花城、住—舒心安居、娱—怡乐生活、行—畅行无忧、购—惠享好物、享—臻享礼遇、人才政策、使用记录。上述页面已拆分 `initialLoading`、`loadingMore`、`hasLoaded`、`hasMore`、`initialError`、`loadMoreError`；首屏完成前不展示空/到底状态，触底加载不覆盖现有内容，失败可点击重试。

开发者工具可使用路由参数 `previewState=initialError` 预览一次首屏失败，或使用 `previewState=loadMoreError` 在首次触底时预览一次加载更多失败；错误只触发一次，点击重试后恢复正常演示数据。正式接口接入后保留状态字段和重试逻辑，移除演示失败开关。

## 后台非分页子列表状态规范（固定）

详情页、管理页中由单次接口全量返回的机构、学校、家庭成员、券、套餐、门店和检查项目等子列表，不强行增加分页，但必须区分以下状态：

| 状态 | 页面要求 |
| --- | --- |
| 加载中 | 保持页面标题、返回及其他已加载详情可用，列表区域显示局部加载动画。 |
| 成功有数据 | 正常展示列表；操作按钮只绑定有效业务 ID。 |
| 成功空数据 | 展示与业务匹配的空文案，不显示空表头、空白卡片或可提交按钮。 |
| 加载失败 | 展示局部错误和“重新加载”，不得把失败当成空数据。 |
| 点击重试 | 只重新请求当前子列表，不清空商户、医院、权益说明等页面其他信息。 |

静态阶段统一支持 `previewState=initialError` 预览一次子列表失败、`previewState=empty` 预览空数据；重试后恢复正常演示内容。当前已应用：行政审批机构、学生托付学校、子女信息、可解绑家属、电影院券、商户普通/酒店套餐、适用门店、体检套餐和体检检查项目。

## 遗留问题

> 2026-07-22 全量审计后的详细待办、优先级与验收标准见：[7.22 人才端遗留问题列表](./7.22遗留问题列表.md)。

| 编号 | 问题 | 影响 | 后续处理 |
| --- | --- | --- | --- |
| I-001 | 首页尚未完成逐像素设计稿验收 | 首页视觉可能仍有间距、字号和图标差异 | 后续继续按设计图逐区域细化。 |
| I-002 | 微信开发者工具曾出现资源缓存导致顶图不刷新 | 本地预览可能与源码不一致 | 修改资源后使用新文件名，并执行“清除全部缓存 + 重新编译”。 |
| I-003 | 尚未提供后台接口、鉴权方式和数据字典 | 页面只能展示静态数据 | 后端资料到位后按《项目接口对接说明》创建请求层并逐页接入。 |
| I-004 | 页面操作说明需随接口联调持续更新 | 当前 60 个注册页面已完成静态阶段覆盖，但真实字段和异常码尚未联调 | 后端接口接入时逐页补充字段、枚举、错误码和验收结果。 |
| I-005 | 登录页尚未接入真实鉴权与协议正文 | 用户无法完成真实登录 | 等待后端提供登录接口、令牌策略与协议内容。 |
| I-006 | 人才权益页当前为静态演示数据 | 搜索、分类切换和权益列表尚不能反映后台数据 | 后端提供权益分类、分页列表和搜索接口后接入，并补齐加载/空/失败状态。 |

## 更新记录

| 日期 | 更新内容 |
| --- | --- |
| 2026-07-15 | 初始化本开发记录；登记当前工程骨架、首页实现约定及遗留问题。 |
| 2026-07-15 | 新增登录页视觉与交互骨架，并建立页面操作说明。 |
| 2026-07-15 | 按设计图重构人才权益页，压缩并接入顶图与分类图标，新增人才权益页面操作说明。 |
| 2026-07-15 | 新增人才权益搜索页，并打通人才权益页搜索框与搜索按钮入口。 |
| 2026-07-15 | 新增暖心食享餐饮专题页，接入压缩菜品图、可滑动图册、动态名称描述及餐饮商户列表。 |
| 2026-07-16 | 按设计图重构暖心食享商家详情页，新增套餐购买、权益详情、导航电话及人才码入口。 |
| 2026-07-16 | 新增暖心食享商品详情页，按图片数组与纯文本字段分离展示，并固定四类购买须知。 |
| 2026-07-16 | 新增订单支付页，打通商品详情购买入口，并预留订单确认、优惠券和微信支付接口边界。 |
| 2026-07-16 | 新增优惠券选择页，同时实现可用列表和暂无优惠券状态，并打通订单支付页回填。 |
| 2026-07-16 | 商家详情团购演示数据扩充至 8 条，并落实顶部全图页面固定导航与上滑实体背景的全局交付规范。 |
| 2026-07-16 | 新增支付成功页，接入用户提供的支付成功图片，并打通订单支付与使用记录演示流程。 |
| 2026-07-16 | 按设计图重构人才卡页，接入亮码享优惠、在线咨询、拨打电话资源，并预留动态人才码安全接口。 |
| 2026-07-16 | 按设计图重构人才政策列表并新增政策详情页，接入政策顶图、分页状态和图文详情接口预留。 |
| 2026-07-20 | 新增“游—悦览花城”文旅权益专题页，复用专题图册与分页列表交互，并补齐入口及操作说明。 |
| 2026-07-20 | 新增“住—舒心安居”住宿权益专题页，接入酒店图片、双分类服务列表及统一图册交互。 |
| 2026-07-20 | 新增酒店预约页，打通酒店商户房型“预约”入口，房型仅展示、酒店地址替换说明文字，并补齐预约接口预留。 |
| 2026-07-20 | 新增酒店预约提交成功页，复用预约确认插画并打通酒店预约提交后的使用记录入口。 |
| 2026-07-23 | 完成 P0-008 至 P0-011：支付/预约成功流程移除原表单栈，待支付按订单失效时间恢复倒计时，统一攀枝花东区演示地址与动态预约日期，登录协议接入现有富文本页面。 |
| 2026-07-23 | 完成 P1-001：11 个主要分页列表统一拆分 `initialLoading`、`loadingMore`、`hasLoaded`，首屏请求不再提前展示空状态或底部加载动画。 |
| 2026-07-23 | 完成 P3-001～P3-006：按 60 个注册路由补齐项目页面树和操作说明覆盖，修正重复编号，更新分页应用范围、首页标题资源及资讯/商户/酒店/登录旧交互说明。 |
| 2026-07-23 | 完成 P1-002：11 个主要分页页补齐 `initialError`、`loadMoreError`、首屏重试和下一页重试，失败时保留已有内容且不误显示到底；60 页面 UTS 编译通过。 |
| 2026-07-23 | 完成 P1-003：人才资讯升级为完整分页状态；行政机构、学校、子女、解绑家属、电影券、商户套餐/门店、体检套餐/检查项目统一补齐非分页列表四态与重试。 |
| 2026-07-20 | 新增酒店免费权益页，打通“出示免费券”入口并预留动态券码与券状态接口。 |
| 2026-07-20 | 新增“娱—怡乐生活”专题页，接入大剧院与影城素材、图册交互、观影服务列表及人才权益分类入口。 |
| 2026-07-20 | 为体验版统一瘦身专题素材：吃／游／住／娱各仅保留 2 张唯一图片，图册循环复用，商户、商品、支付、预约及订单详情复用所属专题图片。 |
| 2026-07-21 | 新增电影院商户详情页，接通怡乐生活影城入口，完成商户信息、地图/电话、消费购买/权益详情切换和电影兑换券领取交互，并继续复用娱乐模块两张体验版图片。 |
| 2026-07-21 | 新增电影券领券成功页，去除设计图标注不需要的年度权益明细行，打通确认领取跳转、兑换码复制及使用记录“已领取”详情入口。 |
| 2026-07-21 | 新增“行—畅行无忧”专题页，复用两张轻量演示图实现图册居中交互，补齐分类服务列表加载/到底/空状态、人才权益入口、路由及页面操作说明。 |
| 2026-07-21 | 新增加油商家详情状态，畅行无忧加油服务改为携带 `type=transport` 进入统一商家详情，并补齐地图、电话、使用说明、权益详情和人才码入口。 |
| 2026-07-21 | 将加油商家详情底部操作改为手机号登记，新增输入弹窗、11位手机号校验和独立提交成功页面；手机号不写入本地持久化存储。 |
| 2026-07-21 | 将加油商家详情“权益详情”改为“适用门店”，新增后台门店表格结构及每行独立微信地图定位入口。 |
| 2026-07-21 | 新增停车服务商详情状态，完成免费权益、使用说明/停车场地址切换、停车场列表定位及底部车牌登记弹窗。 |
| 2026-07-21 | 为停车服务预留后台底部动作枚举，支持 `plate` 填写车牌和 `talentCode` 出示人才码两种状态，演示列表可直接预览。 |
| 2026-07-21 | 将填写车牌改为独立“车牌信息”页，新增 `withParking` 停车场搜索＋车牌与 `simple` 仅车牌两种后台配置状态。 |
| 2026-07-21 | 加高车牌信息页顶部渐变区、收紧停车场与车牌字段间距，并将停车场输入升级为名称/地址模糊搜索及下拉结果必选交互。 |
| 2026-07-21 | 新增车牌提交成功页，车牌表单校验通过后进入结果页，并支持直接返回停车服务商详情。 |
| 2026-07-21 | 将车牌号改为分段填写：先选省份简称和车牌首字母，再输入后5位数字/字母，并补齐分段校验及非法字符过滤。 |
| 2026-07-21 | 新增自助洗车服务商详情页，畅行无忧洗车服务接入独立详情，底部仅保留“去洗车”按钮，并预留外部小程序和业务域名网页跳转配置。 |
| 2026-07-21 | 新增“购—惠享好物”专题页，接通人才权益入口，完成横向图册、悬浮介绍卡、五类购物服务导航及分页加载/到底/空状态。 |
| 2026-07-21 | 新增购物服务统一详情页，五类购物列表全部改为信息展示模式，底部仅保留联系专员按钮，并预留商家电话、地图坐标和专员信息接口。 |
| 2026-07-21 | 新增“享—臻享礼遇”专题页，接通人才权益入口，完成横向图册、悬浮介绍卡、五类综合服务导航及分页加载/到底/空状态。 |
| 2026-07-22 | 臻享礼遇列表导航分类调整：政务服务改为行政审批、教育托管改为学生托付，仅改分类导航名称，图册展示名称保持原样，并同步页面操作说明与接口文档。 |
| 2026-07-22 | 新增体检医院详情（merchant 体检模式）、体检套餐详情、体检预约与预约提交成功页；臻享礼遇免费体检列表以 `type=medical` 接入，表单与成功页复用酒店预约流程布局与图标。 |
| 2026-07-22 | 按三张设计稿新增配偶推荐就业完整流程，完成权益说明页、配偶资料表单、提交待处理结果页，并补充使用记录待处理演示数据。 |
| 2026-07-22 | 按设计图新增行政审批详情页，臻享礼遇“行政审批”分类接入独立详情，完成机构列表、咨询电话拨号与窗口信息弹窗，并补齐页面操作说明与接口预留。 |
| 2026-07-22 | 新增金融服务商家详情页，复用购房购车统一信息展示结构，臻享礼遇"金融服务"列表接入独立详情并携带机构参数，底部保留联系专员入口。 |
| 2026-07-22 | 新增学生托付详情页（子女托管），完成使用说明/学校地址标签切换、学校列表、底部出示人才码和子女信息双按钮；同时新增子女信息列表页，臻享礼遇"学生托付"分类接入独立详情。 |
| 2026-07-22 | 修复预约/支付/申请完成页进入使用记录后的返回栈：统一关闭完成流程，使用记录在栈底时安全返回个人中心，避免首页面调用 `navigateBack` 报错。 |
| 2026-07-22 | 对照设计图二次修正学生托付详情页：调整标题、卡种标签、说明卡和学校列表布局，底部双按钮统一为渐变样式并接入素材库二维码/子女信息图标。 |
| 2026-07-22 | 继续收紧学生托付使用说明卡高度，固定学校表格行高并让文字垂直居中，同时统一定位与电话图标为同色蓝色线性样式。 |
| 2026-07-22 | 按设计图重构子女信息页为固定导航、独立列表滚动和固定底部操作三段式布局，修复内容覆盖，并统一卡片高度、间距、字段列宽及审核状态胶囊。 |
| 2026-07-22 | 新增添加子女信息页，完成原生性别/日期选择、最多 3 张证明材料上传与删除、表单校验，并打通提交后返回子女信息列表的待审核演示流程。 |
| 2026-07-22 | 修复人才卡游客状态纵向空间过度压缩问题：按卡面原图比例恢复三类卡片高度、改为完整适配展示，并放宽介绍文案、申请按钮和申请条件区域的间距与字号。 |
| 2026-07-22 | 完成子女信息审核不通过后的重新提交流程：驳回卡片展示原因和修改入口，编辑页回填原资料，重新提交后更新原记录为待审核且不重复新增。 |
| 2026-07-22 | 统一金融服务详情页配色：机构信息区改为详情页浅灰底，摘要与卡种标签统一暖橙色，正文改为灰蓝色，并统一标题下划线、操作图标和底部栏视觉。 |
| 2026-07-22 | 调整使用记录列表语义：订单卡片标题统一展示商家/服务机构名称，并按餐饮、住宿、影院、医疗、景区、停车、加油、洗车、购物和综合服务类型映射本地图标。 |
| 2026-07-22 | 开发人才权益“全部商家”页面：点击全部进入搜索页聚合模式，默认按 sort 升序展示跨分类商家，支持关键词切换、分类标签、类型详情跳转、触底加载、到底及空状态。 |
| 2026-07-22 | 新增学校介绍详情页：学生托付学校名称可点击进入，详情按学校 ID 预留后台富文本加载，并补齐固定导航、长内容滚动、空状态、失败重试和富文本安全约定。 |
| 2026-07-22 | 修复登录页栈底返回错误：页面栈首位时隐藏返回按钮，返回操作增加栈深检查与首页兜底；新增独立人才码页，商户详情和学生托付亮码入口统一改为可返回的二级页面。 |
| 2026-07-22 | 修复 P0-001 通用商户详情参数丢失：推荐权益、暖心食享、悦览花城、舒心安居及搜索结果统一传递 `merchantType`、名称、图片、地址和优惠快照；详情页按餐饮、酒店、景区、公寓等类型初始化展示，并同步地图名称与地址。 |
| 2026-07-22 | 修复 P0-004 全局返回栈风险：新增 `utils/navigation.uts` 统一 `safeBack`，54 个带返回行为的页面全部接入并清除页面内直接 `navigateBack`；支持业务兜底路由、优惠券来源动态兜底及车牌流程 `delta=2` 返回。 |
| 2026-07-22 | 修复 P0-006 资讯详情富文本缺失：静态正文改由 `contentHtml` 驱动 `rich-text`，实现首屏加载、正文空、加载失败、重新加载四种状态，并记录服务端白名单清洗要求。 |
| 2026-07-22 | 修复 P0-005 资讯详情参数丢失：首页置顶与普通资讯、人才资讯列表统一使用稳定 `newsId` 跳转，详情页按 ID 映射不同静态正文，无效 ID 进入空状态。 |