uni-app-feature

# uni-app 业务功能开发指南 ## 职责边界 本 Skill 负责业务代码：页面、业务组件、API 接入、页面级交互、Pinia 业务状态、移动端样式和跨端功能。 以下内容转交 `uni-app-tooling`： - 启动 H5、APP、小程序、模拟器、真机或开发者工具； - env、代理、localhost、跨域、请求地址和 401 排障； - API 同步命令、pages/manifest 生成、typecheck、lint、build 和打包； - 平台 SDK、证书、签名、原生插件和构建产物问题。 组合任务先完成业务实现，再由 `uni-app-tooling` 负责静态检查和平台验证。任何启动项目或外部工具的操作都必须先询问用户。 ## 参考规范 开始前按需读取： | 场景 | 文档 | |---|---| | uni-app 页面、API、状态、样式与跨端通用规范 | [uni-app-spec.md](../lingman-core/uni-app/uni-app-spec.md) | | 仅当目标是 p708 或架构高度相似项目时 | [p708-verified-patterns.md](../lingman-core/uni-app/p708-verified-patterns.md) | | 开发后的检查、运行和构建 | [tooling-guide.md](../lingman-core/uni-app/tooling-guide.md) | 共享文档只提供规则和索引。目标项目当前源码、配置和用户要求优先级更高。 ## Step 1 — 探测目标项目 开始编码前必须读取真实文件，不凭模板假设： 1. `package.json`：uni-app 路线、Vue/TS、UI 库、Pinia、脚本和包管理器。 2. 页面和 Manifest 配置源：`definePage()`、`pages.config.*`、`manifest.config.*`、Vite 插件或直接维护的 JSON。 3. `uno.config.*`、全局样式和主题 Store：单位、语义变量、safelist、安全区。 4. API 目录、请求桥接、拦截器、Token Store 和统一错误处理。 5. 主包、分包、TabBar、登录路由和相似页面。 6. 已有业务组件、Hooks、工具函数和 Store，避免重复实现。 7. 目标交付平台以及必须保留的其他平台。 只有实际存在自动 API 体系时，才套用自动生成目录规则；不得为了符合 Skill 主动创建 `src/api/auto/`。 ## Step 2 — 判断任务模式 | 模式 | 处理重点 | |---|---| | 页面模式 | 页面声明、路由、生命周期、加载/空态/错误、导航与安全区 | | API 接入模式 | 复用自动 API 和请求桥接、类型推导、错误态与竞态 | | 组件模式 | 复用优先、职责边界、Props/Emits、独立状态和跨端兼容 | | 状态模式 | 页面私有状态与 Pinia 共享状态划分、持久化和登出清理 | | 样式模式 | 项目 UI 库、UnoCSS/rpx、主题变量、safelist 和 scoped | | 媒体模式 | 平台分支、请求竞态、页面显隐和完整资源释放 | 一个需求可包含多个模式，但只做一次项目探测和一份统一变更清单。 ## Step 3 — 页面开发 ### 页面声明与导航 - 先找相似页面，沿用其 `definePage()`、导航栏、布局和返回方式。 - 使用生成式 pages 的项目修改页面声明/配置源，不直接把生成 JSON 当唯一编辑入口。 - 判断是否为 TabBar 页面：TabBar 使用 `uni.switchTab()`，普通页面按场景使用其他导航 API 或项目封装。 - 二级页考虑页面栈为空时的返回兜底。 - 路由只传必要且稳定的标识；敏感数据、大对象和易变播放地址不塞入 URL。 ### 生命周期与取数 - 首次加载使用项目现有页面生命周期；每次显示都需刷新时再使用 `onShow`。 - 避免在 `onLoad` 和 `onShow` 无条件重复请求。 - TabBar 缓存页必须处理 `onHide`，不能只依赖卸载。 - 页面卸载时清理定时器、监听器、请求序号和页面资源。 ### 页面状态 列表或详情页根据复杂度覆盖： - 首屏 loading； - 空数据； - 首屏失败与重试； - 下拉刷新； - 加载更多、到底和加载更多失败； - 记录级操作中状态； - 请求竞态与旧响应丢弃。 不要为了套模板引入页面并不需要的状态。 ## Step 4 — API 接入 1. 搜索项目已有自动 API 或手写 API，优先复用。 2. 若存在自动 API： - 从项目真实自动目录导入； - 不手改生成文件、配套类型或元数据； - 不重复手写 URL 和 DTO； - 使用项目已有 `Get/Post/Put/Delete` 或等价桥接； - 返回类型优先通过 `Awaited<ReturnType<...>>` 推导。 3. API 不存在时： - 不在自动目录手工补接口； - 说明需要更新后端契约或执行既有同步流程； - 同步和环境排障转给 `uni-app-tooling`。 4. 特殊第三方协议或非标准响应可在自动目录外增加窄幅 wrapper，只处理兼容、组合调用或响应形状。 5. 页面层不重复展示底层已经统一展示的请求错误，但要保留错误态和重试入口。 6. ID 类型必须遵循生成类型和项目现有处理；Java `Long` 不得无条件转 `number`。 ## Step 5 — 列表、搜索与竞态 - 新搜索、新筛选和刷新统一重置分页状态。 - 搜索输入使用防抖；立即搜索前清理定时器，卸载时再次清理。 - 使用递增序号、AbortController 或项目现有机制阻止旧响应覆盖新结果。 - 加载更多前检查 loading/finished；追加数据按稳定主键去重。 - 首屏错误和加载更多错误分开处理。 - 启停、删除、提交等按记录维护处理中状态，防止重复操作。 - 状态修改成功后立即同步当前列表；当前筛选不再匹配时移除记录并更新总数。 优先复用 p708 中 `src/pages/detection-task/index.vue` 和现有列表组件的成熟模式，但不要逐字复制不相关业务常量。 ## Step 6 — Pinia 状态边界 适合页面/组件局部状态： - 表单输入、弹窗开关、当前分页、局部 loading、临时媒体实例。 适合 Pinia： - 多页面共享业务状态； - TabBar 缓存页之间共享状态； - Token、用户、字典、主题、设置和业务角标； - 需要跨页面恢复的筛选或一次性导航意图。 规则： - 复用项目已有 Store，禁止建立平行认证、主题或字典体系。 - 不把 PeerConnection、MediaStream、DOM、计时器等不可序列化资源放入 Store。 - 持久化前确认项目插件和 storage 适配；临时状态通常不持久化。 - 退出登录时清理与当前账号相关的业务状态。 ## Step 7 — 组件与样式 ### 组件复用 优先级： 1. 项目现有业务组件； 2. 项目 UI 组件库； 3. 项目已有 Hooks/工具； 4. 确有复用价值时新增业务组件。 不要重新封装按钮、输入框、弹窗、Toast 等 UI 库已有基础组件。复杂页面中的独立列表、详情弹层、媒体播放器等适合抽取。 ### Wot Design Uni 与 UnoCSS 若项目使用 Wot Design Uni 或同类组件库： - 优先使用 `wd-*` 组件与全局 `useToast()`/Message 能力； - UnoCSS 数值尺寸类显式带单位，例如 `p-24rpx`、`top-0px`； - 移动端布局优先沿用 `rpx`； - 使用项目语义主题变量（按项目真实前缀），不批量散落固定颜色； - 动态图标加入 safelist 或改为静态类； - 局部复杂样式使用 scoped SCSS，第三方组件覆盖限制 `:deep()` 作用域； - 处理顶部、底部安全区和 TabBar 高度。 如果目标项目使用其他 UI 库或主题体系，以真实项目为准，不强制引入 Wot。 ## Step 8 — 视频与媒体专项 ### 平台边界 - H5：浏览器 video、WebRTC、MediaStream 和 DOM 操作只能存在于 H5 分支或 H5 专用组件。 - APP：使用项目真实可播放地址和原生 video 能力，不能假设浏览器 WebRTC 实现可复用。 - 其他端：使用平台支持能力并提供不可用兜底。 ### 资源释放 至少检查： - `onHide`、`onUnload`、`onBeforeUnmount` 的职责； - 停止 MediaStreamTrack； - 关闭 PeerConnection； - pause video，清空 `srcObject` 和 `src`； - 清理计时器、AbortController、watch 和事件监听； - 失活时通过 active 或条件渲染停止播放器； - 切换媒体源或数据源时，阻止旧信令/请求回写。 自动播放失败可能来自浏览器策略，不能一律标记为流地址错误。 ## Step 9 — 变更与检查 实施前列出受影响文件和关键行为；增量修改只改必要文件，不做无关格式化或架构重写。 编码完成后检查： - 自动生成目录未手改； - 页面声明和导航方式正确； - 已复用 API、Store、UI 组件和主题； - 分页、搜索、防抖、竞态和重复提交完整； - 条件编译只包围平台差异； - 视频和副作用在隐藏/卸载时释放； - 未泄露敏感信息； - 未经要求未新增测试文件。 静态检查和构建按 `uni-app-tooling` 执行。若需要启动项目、模拟器或真机验收，必须先询问用户。 ## 输出要求 完成后简要说明： ```text 实现内容： - ... 关键复用： - API / 组件 / Store / 工具：... 跨端处理： - APP：... - H5：... - 小程序：... 待验证： - typecheck / lint / build / 运行态（由 uni-app-tooling 执行或说明未执行原因） ```