初始化

2026-09-15 15:25:05 +07:00
commit 77c16ab4a2
1310 changed files with 132250 additions and 0 deletions
@@ -0,0 +1,258 @@
+---
+name: frontend-project-standards
+description: 为当前仓库输出可维护的 Vue3 + TypeScript 前端代码规范，覆盖组件分层、hooks 抽离、service 接口封装、错误处理与命名规范。用于新功能开发、页面重构、接口改造、复杂逻辑拆分与可维护性治理场景。
+---
+
+# 前端项目规范
+
+## 适用范围
+本规范适用于以下所有变更：
+- `src/views/**`：路由级页面容器及其私有 `components/`、`hooks/`。
+- `src/components/**`：跨模块复用组件，以及形如 `src/components/<module>/{components,hooks,types.ts,index.vue}` 的"组件即模块"容器（参考 `src/components/HomeHeader/`）。
+- `src/hooks/**`：全局/通用 composable。
+- `src/service/**`：接口封装层。
+- `src/stores/**`：Pinia store。
+- `src/utils/**`：纯工具函数（无状态、非 Vue 特定）。
+
+需遵循的项目上下文：
+- 技术栈：Vue 3 + TypeScript + Vite + Pinia + Vant。
+- 请求链路：`src/service/*.ts` -> `src/utils/request.ts` -> axios。`request` 实例除标准 `get/post/put/delete` 外还提供 `deletes`（form 形式 DELETE），不要新增同义包装。
+- 路径别名：从 `src` 导入时统一使用 `@/`。
+
+## 触发条件
+满足任一条件，必须先加载并按本规范输出：
+- 用户消息中出现：前端规范、规范、可维护性、重构、refactor、抽 hook、抽 composable、接口封装、service、错误处理、loading/error/empty、拆分大文件、整改、治理、frontend-project-standards、@fps、/fps。
+- 改动范围涉及 `*.vue`、`src/hooks/**`、`src/service/**`、`src/components/**`、`src/views/**`、`src/stores/**`，且包含结构、接口、状态、交互或业务逻辑调整。
+- 用户提供 PRD/Figma/截图要求"按本仓库结构落地"。
+- PR 自检、code review、规范审查类任务。
+
+轻量豁免：仅改文案、样式数值、静态资源路径、纯 class 调整时，可只做最小变更并说明“不涉及分层/API/hook 调整”，无需强行套完整交付结构。
+
+## 快捷指令
+团队可直接在对话中使用以下短指令触发对应工作流，每条都映射到 `prompt-templates.md` 的具体模板：
+
+| 指令 | 含义 | 对应模板 |
+| --- | --- | --- |
+| `@fps:new <页面/模块>` | 新页面或新模块开发（container + hooks + service 全套分层） | 模板 1 |
+| `@fps:refactor <文件路径>` | 拆分大文件 / 抽 hook / 行为不变重构 | 模板 2 |
+| `@fps:api <接口描述> -> <页面>` | 新增接口并接入页面（service typed 方法 + hook + view 三步） | 模板 3 |
+| `@fps:fix <问题描述>` | 修 bug 同时做最小必要规范化 | 模板 4 |
+| `@fps:review <文件/diff>` | 仅做规范审查，不大改代码 | 模板 5 |
+| `@fps:hook <逻辑描述>` | 仅产出单一职责 hook（state/computed/actions） | 模板 1 子集 |
+
+调用约定：
+- 任何指令默认带上"输出分层说明 + hooks 变更 + API 变更 + 错误覆盖 + 自检结果"五项交付。
+- 指令后可追加自由描述，越具体越好（目标文件、行为约束、是否允许重命名等）。
+- 不带任何指令时，按 `## 触发条件` 自动判定是否启用本规范。
+- 若某项交付不涉及，简短标注“不涉及”，不要为了满足格式新增无意义文件或抽象。
+
+## 强制规则（必须遵守）
+
+### 0) 通用工程准则（最高优先级）
+- 可维护性 > 短期省事；规则冲突时按 类型安全 > 分层正确性 > 局部简洁性 排序。
+- **不引入新依赖**：除非用户明确要求，否则不增加 npm/yarn 依赖、不替换现有库（axios/Pinia/Vant 不替换）。
+- **对齐项目结构**：所有新文件必须落入"适用范围"描述的目录形态，不另起新目录约定。
+- **优先复用既有逻辑**：动手前先在 `src/hooks`、`src/utils`、`src/service`、`src/stores` 检索可复用项；找到 ≥70% 匹配即扩展或参数化，不重复造轮。
+- **避免过度设计**：见 `### 0.1)`。
+- 历史代码受限暂时无法满足规则时，必须明确说明约束并给出分阶段改造计划。
+
+### 0.1) 反过度设计（硬规则）
+**默认顺序：先写最小可行实现（MVP），出现下方"复用/复杂度信号"再抽象。**
+
+判定信号（命中任一即"过度"，必须回退到更简方案）：
+- 仅以“未来可能复用”为理由，为只有 1 个调用方的逻辑创建 hook / 工具 / 组件；至少出现 2 处调用、明确跨页面复用价值，或命中本规范的复杂度/职责边界阈值时再抽。
+- 为只有一种实参的"泛型/策略/工厂"提前预留扩展点（如未被使用的泛型参数、单实现的 strategy map）。
+- 引入空壳 wrapper：组件 / 函数 / 类除转发外不做事（可直接使用被包装对象）。
+- 配置爆炸：用 5+ 个布尔/枚举 props 控制一个组件多种形态，应拆为多个组件。
+- 未使用的导出：新增 export 在本次改动范围内无人调用。
+- 为不存在的需求设计接口字段、状态分支、loading 子态。
+- 自造已被现有依赖覆盖的能力（已用 Vant/Pinia/axios 拦截器/`@/utils/request` 时不再造轮）。
+- 抽象层数 ≥ 3（view -> hook -> hook -> service）且中间层无独立职责。
+- 单文件代码量小于 80 行却被拆成 3 个文件（除非命名/职责必要）。
+- 单一页面被拆成大量细碎展示组件，组件之间只是传递原样 props/slot，无法形成清晰职责边界。
+
+输出要求：
+- 涉及"是否抽象/拆分/泛化"的决策点，必须显式给一句话理由（命中哪条复用信号或复杂度阈值）。
+- 找不到理由时，默认走"内联实现 / 单文件 / 字面量参数"的最简路径。
+- 抽象阈值另见 `### 2) hooks 抽离` 中的硬性拆分触发条件，二者取严。
+- 页面私有 hook 因复杂副作用或业务域拆分而创建时，不要求跨页面复用；但必须具备独立职责，不能只是移动代码。
+
+### 1) 组件分层
+- `src/views/**/index.vue` 作为页面容器，负责路由参数、hooks 组装、子组件编排。
+- 页面私有组件放在 `src/views/**/components/`。
+- 跨模块复用组件放在 `src/components/`。
+- 展示组件禁止直接调接口，避免承载重业务副作用。
+- 模板相关逻辑留在组件内，复杂业务分支和副作用迁移到 hooks。
+- 不为了“看起来分层”把一个页面拆成很多小组件。只有满足以下任一条件才拆组件：
+  - 该 UI 区块会复用，或未来已有明确复用场景；
+  - 区块模板/交互复杂，独立后能显著降低容器理解成本；
+  - 区块拥有清晰业务语义边界（如用户面板、订单卡片、筛选栏），而不是纯布局切片。
+- 仅用于排版、单次使用且逻辑简单的片段，优先留在当前组件内。
+
+### 2) hooks 抽离
+- 满足任一条件必须抽离 hook：
+  - 同文件存在多个副作用块（`watch`、`watchEffect`、生命周期）；
+  - 一个大 `setup` 中混合了业务状态和 UI 状态；
+  - 逻辑具备跨页面复用价值。
+- hook 命名统一为 `useXxx.ts`。
+- 放置规则：
+  - 全局/通用逻辑 -> `src/hooks/`；
+  - 模块专属逻辑 -> `src/views/<module>/hooks/`。
+- hook 输出保持最小且清晰：`state`、`computed`、`actions`。
+- 页面私有 hook 的价值来自“隔离副作用/业务域”，不来自文件数量；单纯把几行状态搬出去不算合格抽离。
+- hook 内必须清理定时器、监听器、订阅等资源。
+- 大文件硬性拆分触发条件（满足任一即拆）：
+  - 非样式代码超过 350 行；
+  - 单文件含 4 个及以上 `watch/watchEffect/生命周期` 块；
+  - 单文件混合 3 个及以上业务域（如分页 + 权限 + 埋点）。
+- `src/views/**/utils/` 下的重业务文件优先迁移到 `src/views/**/hooks/`，工具函数保持纯函数化。
+
+### 3) 接口封装
+- 禁止在 `.vue` 或 hooks 中直接调用 `axios`/`fetch`。
+- 接口新增或调整统一在 `src/service/*.ts` 中用 class static 方法实现，并保持项目现有风格。
+- 统一复用 `src/utils/request.ts` 的 `request.get/post/put/delete`。
+- 新增/修改的接口方法必须有入参和返回值类型（避免新增 `any`）。
+- URL 路径和参数组装留在 service 层，不放到视图/组件层。
+- 历史代码若仍有 `any`，本次改动不得继续扩散；应在改动范围内增量替换为明确类型。
+
+### 4) 错误处理
+- 网络层与 HTTP 状态码处理继续由 `src/utils/request.ts` 统一兜底。
+- 业务异步动作仍需本地容错：
+  - `loading` 开关必须成对出现（`finally` 或等价方案）；
+  - 失败时必须设置可预期兜底状态（`error`、空态、安全默认值）；
+  - 仅在需要用户动作引导时显示用户提示。
+- 禁止吞错（`catch {}`）以及仅 `console` 不落状态。
+- 需要继续抛错时，必须保留明确原因与必要上下文。
+- 异步后会变更 UI 状态的动作，必须覆盖失败分支并防止状态不一致。
+
+### 5) 类型纪律
+- view/hook/service 中禁止新增宽泛 `any`。
+- service 边界优先使用显式 `interface/type`。
+- 无法确认类型时优先 `unknown`，使用前做类型收窄。
+- 路由参数标准化要显式处理（例如 `String(route.query.id || '')`）。
+
+### 6) 命名规范（对齐主流最佳实践）
+- 目录名统一 `kebab-case`（如 `user-profile`）。
+- 非组件文件统一 `kebab-case`（如 `media-content.ts`、`use-xxx` 不使用，hook 文件仍保持 `useXxx.ts`）。
+- Vue 组件文件名使用 `PascalCase.vue`（如 `UserProfileCard.vue`）；页面入口保持 `index.vue`。
+- class、type、interface、enum 名称使用 `PascalCase`。
+- 变量、函数、方法使用 `camelCase`；常量使用 `UPPER_SNAKE_CASE`。
+- 布尔变量必须带语义前缀：`is/has/can/should`（如 `isLoading`、`hasPaid`）。
+- 事件处理函数统一 `handleXxx`；计算属性使用业务语义命名，不使用无意义缩写。
+- 禁止拼音、无语义缩写、单字符命名（循环计数器 `i/j` 除外）。
+
+### 7) 历史命名兼容策略（增量治理）
+- 历史文件允许保留旧命名，不强制一次性全量重命名。
+- 任何新增文件、新增目录、以及被修改代码中的新增符号，必须遵循最新命名规范。
+- 若本次改动涉及重命名风险较高区域，可采用“行为不变优先”的分阶段治理：本次先保证增量合规，后续单独提交命名清理任务。
+- 禁止在新代码中复制旧命名反模式（即使同文件已有旧风格）。
+
+## 交付输出要求
+完成编码任务时，输出中必须包含：
+1. 分层说明：哪些留在 view/container，哪些在 component/hook/service。
+2. hooks 变更：新增或调整了哪些 hook、各自单一职责是什么。
+3. 接口变更：新增/修改的 service 方法及其类型定义。
+4. 错误覆盖：哪些异步路径已补齐失败兜底与状态恢复。
+5. 维护性收益：如何降低耦合，便于后续功能扩展。
+6. 自检结果：`reference.md` 中检查项的通过情况。
+7. **闭环校验结果**：按 `## 完工闭环校验` 给出逐项通过/未通过，未通过需附文件/行号。
+
+若某项未发生变更，写“不涉及”即可；不要为了输出完整而新增 wrapper、空组件、空 hook 或空 service。
+
+## 改造工作流
+按以下顺序执行：
+1. 识别目标文件中的职责混杂点。
+2. 必要时拆分为 container + hooks + 展示组件；组件拆分以清晰职责边界为准，不以数量为目标。
+3. 将直接请求逻辑迁移到 service 层。
+4. 在 service 边界与 hook 状态处补强类型。
+5. 补齐 loading/error/empty 等状态保护。
+6. 执行自检清单并先修复不通过项。
+7. **执行 `## 完工闭环校验`**，仅针对本次改动文件。
+8. 最终确认无本规范违规项。
+
+## 完工闭环校验（仅检查本次改动）
+**强制收尾步骤**。范围严格限定在"本次新增/修改/重命名"的文件，**不扩到全仓**，不修复历史问题（除非用户明确要求）。
+
+### 必执行动作（Agent）
+- 对所有改动文件调用 `ReadLints`（一次性传入改动文件路径数组），确认无新增报错。
+- 若改动了 `*.vue` 内的 `<script setup lang="ts">` 或新增 `.ts`，须在心中跑一遍 IDE 类型解析：所有 import 路径可达、命名/默认导出对齐、`@/` 别名能正确解析。
+- 若仓库已配置 `tsc --noEmit` / `vue-tsc`，仅在用户要求时执行；默认依赖 `ReadLints` 增量结果。
+
+### 校验清单（逐项过）
+1. **类型与 lint 闭环**
+   - [ ] `ReadLints` 对改动文件返回 0 新增报错；历史已有报错可保留并显式列出。
+2. **引入与路径闭环**
+   - [ ] 新增/修改的 `import` 路径存在且大小写正确。
+   - [ ] 命名导出 / 默认导出与源文件实际声明一致。
+   - [ ] `@/` 别名指向正确的真实路径。
+   - [ ] 仅类型用途的导入使用 `import type { ... }`。
+   - [ ] 不留未使用的 `import`、ref、computed、props、emits。
+3. **类型边界闭环**
+   - [ ] service 方法 params/response 类型已声明并被 hook/view 正确消费。
+   - [ ] 无新增宽泛 `any`；`unknown` 已做类型收窄。
+   - [ ] props / emits / defineExpose 类型完整，无隐式 any。
+   - [ ] 全局类型（如 `Types.*`）引用路径与 `src/typings` 实际声明一致。
+4. **行为闭环**
+   - [ ] 异步动作 loading 开关成对，error/empty 兜底到位。
+   - [ ] hook 内定时器、`watch` 句柄、事件监听、订阅在 `onUnmounted` 释放。
+   - [ ] 模板引用的 ref/computed 都有定义且被使用，无孤儿。
+5. **范围纪律**
+   - [ ] 改动未扩散到无关文件。
+   - [ ] 历史已有问题未顺手"乱改"；如确需顺带修复，单独列在"附带修复"区块。
+   - [ ] 输出区块内显式列出"已校验文件清单"和"未校验/不在范围"的文件。
+
+### 输出格式（强制）
+完工时必须附以下区块：
+
+```markdown
+### 闭环校验结果
+**已校验文件**：
+- src/xxx/yyy.vue
+- src/xxx/hooks/useZzz.ts
+- src/service/xxx.ts
+
+**校验项**
+- [x] 类型与 lint 闭环（ReadLints 0 新增报错）
+- [x] 引入与路径闭环
+- [x] 类型边界闭环
+- [x] 行为闭环
+- [x] 范围纪律
+
+**未通过项**（如有）：
+- <文件:行号> <问题描述> <建议>
+```
+
+## 反模式（禁止）
+- 超大 `setup` 同时处理路由、接口、业务规则、DOM 行为。
+- 在模板、UI 组件或临时 util 中直接发请求，绕过 service。
+- 一个 hook 混合多个无关业务域。
+- 已知结构场景下继续使用宽泛 `any`。
+- 异步失败分支未做状态回滚或兜底。
+- 对已超大文件（如 500+ 行）继续堆逻辑而不拆分。
+- 把埋点逻辑混入通用分页/权限 hook。
+- **过度设计**：单调用方就抽 hook/util/组件、未被使用的泛型与策略点、空壳 wrapper、5+ 布尔 props 的"全能组件"、未使用的 export、为不存在的需求设计字段或子态、自造已被现有依赖覆盖的能力（违反 `### 0.1)`）。
+
+## PR 自检清单（必须通过）
+- [ ] `.vue` 或 hook 文件中无新增直接请求调用。
+- [ ] 新增/修改 service 方法均具备入参和返回类型。
+- [ ] 无新增宽泛 `any`。
+- [ ] 异步动作具备完整 loading/error/fallback 处理。
+- [ ] 长逻辑已按业务域拆入聚焦 hooks。
+- [ ] 新增目录/文件/符号命名符合命名规范。
+- [ ] 历史命名仅保留存量，新增/改动部分全部符合新规范。
+- [ ] **未触发 `### 0.1)` 任一过度设计信号**；如有抽象/拆分动作，已说明触发的复用或复杂度信号。
+- [ ] **完工闭环校验已执行且通过**（仅对本次改动文件，`ReadLints` 0 新增报错，import/类型/行为四类闭环全过）。
+- [ ] 输出内容包含“交付输出要求”中的全部项目。
+
+## 术语对照（统一用词）
+- container：页面容器（`src/views/**/index.vue`）。
+- presentational component：展示组件（偏 UI，无接口副作用）。
+- hook/composable：可复用业务逻辑单元（`useXxx.ts`）。
+- service：接口封装层（`src/service/*.ts`）。
+- request layer：统一请求层（`src/utils/request.ts`）。
+
+## 参考资料
+- 代码模板见 [reference.md](reference.md)。
+- 仓库场景示例见 [examples.md](examples.md)。
+- 团队提问模板见 [prompt-templates.md](prompt-templates.md)。
+- 命名规范详表见 [naming-conventions.md](naming-conventions.md)。
@@ -0,0 +1,87 @@
+# 仓库场景示例
+
+## 示例 A：重构大型视图工具文件
+
+### 场景
+`src/views/<module>/utils/` 下某文件同时包含：
+- 路由参数解析，
+- 分页加载，
+- 权限判断，
+- 事件埋点，
+- 章节切换。
+
+### 目标拆分
+- `index.vue`（容器页）：路由绑定 + hooks 组装。
+- `hooks/useEpisodeList.ts`：列表分页/刷新逻辑。
+- `hooks/useEpisodeAccess.ts`：权限校验与付费弹窗逻辑。
+- `hooks/useReadEvents.ts`：阅读进度与埋点上报逻辑。
+- `service/<module>.ts`：集中承载接口定义与类型边界。
+
+### 期望结果
+- 每个 hook 只负责一个业务域。
+- 容器页仅做编排与组件通信。
+- 接口调用统一收敛到 service class 方法。
+- 所有异步动作具备失败兜底状态。
+
+## 示例 B：新增接口的正确姿势
+
+### 错误示例
+- 在 `.vue` 中直接调用 `request.get()`。
+- 返回值不定义类型，使用点到处强转。
+
+### 正确示例
+1. 在 `src/service/<domain>.ts` 中新增方法：
+   - 入参类型明确，
+   - 返回值类型明确，
+   - 不混入视图逻辑。
+2. hook 调用 service，并映射到本地状态。
+3. view 仅消费 hook 对外暴露的数据和动作。
+
+## 示例 C：页面动作的错误处理
+
+### 必备模式
+- 异步前先 `loading = true`。
+- 使用 `try/catch/finally` 包裹异步调用。
+- `catch` 中设置 `error = true`，并将关键数据恢复到安全默认值。
+- `finally` 中关闭 loading，避免状态泄漏。
+
+### 需要避免
+- `catch (e) { console.log(e) }`，但不修改任何状态。
+- 仅在成功分支关闭 loading。
+
+## 示例 D：页面组件拆分克制
+
+### 应该拆
+- 用户信息面板、会员卡片、菜单宫格这类具备清晰业务语义的区块。
+- 交互复杂、模板较长，独立后能明显降低 `index.vue` 理解成本的区块。
+- 已有复用或确定会复用的 UI/业务组件。
+
+### 不应该拆
+- 只有几行 HTML/CSS 的布局容器。
+- 只接收原样 props 再原样渲染，没有独立语义或交互的小片段。
+- 为了凑 `components/` 目录，把一个页面按视觉切片拆成大量一次性组件。
+
+### 期望结果
+- `index.vue` 负责页面编排，不变成所有状态和副作用的大杂烩。
+- `components/` 数量服务于职责边界，不以“越多越规范”为目标。
+- 简单静态片段可以留在页面或父组件内。
+
+## 示例 E：大文件拆分触发（mediaContentInfo 类场景）
+
+### 触发条件
+当类似 `src/views/acgModule/utils/mediaContentInfo.ts` 的文件持续叠加以下逻辑时：
+- 列表分页逻辑，
+- 权限与付费闸门逻辑，
+- 阅读进度与埋点逻辑，
+- 路由同步逻辑。
+
+### 推荐拆分方案
+1. `useMediaEpisodePaging.ts`：分页、刷新、列表合并规则。
+2. `useMediaEpisodeAccess.ts`：权限校验、付费弹窗状态、购买成功处理。
+3. `useMediaReadReport.ts`：进度计算与埋点派发。
+4. 协调文件保持轻量：仅组装 hooks 并对 view 暴露统一 API。
+
+### 完成标准
+- 不存在跨多个业务域的“大而全 hook”。
+- 埋点逻辑不直接修改分页状态。
+- 权限逻辑不直接承担列表拉取职责。
@@ -0,0 +1,87 @@
+# 命名规范（Vue3 + TypeScript）
+
+本规范参考 Vue 官方风格与 TypeScript 主流实践，目标是统一可读性、可检索性、可维护性。
+
+## 0) 历史代码兼容原则
+
+- 存量代码可暂时保留历史命名，不做一次性全量改名。
+- 增量从严：新增文件、目录、类型、变量、函数、组件命名必须符合本规范。
+- 改动旧文件时，至少保证“新增/修改行”不引入旧命名反模式。
+- 大范围改名需单独评估风险（路由、动态导入、缓存键、埋点字段），建议独立 PR 分批执行。
+
+## 1) 目录与文件命名
+
+- 目录名：`kebab-case`
+  - 示例：`src/views/user-center/`
+- 页面入口文件：`index.vue`
+- 组件文件：`PascalCase.vue`
+  - 示例：`UserProfileCard.vue`
+- hooks/composable 文件：`useXxx.ts`
+  - 示例：`useMediaEpisodePaging.ts`
+- 其他 TS 文件：`kebab-case.ts`
+  - 示例：`media-content-parser.ts`
+- 样式文件：`kebab-case.scss`
+
+## 2) 代码符号命名
+
+- class/type/interface/enum：`PascalCase`
+  - 示例：`UserProfileService`、`MediaListItem`、`ApiError`
+- 变量/函数/方法：`camelCase`
+  - 示例：`fetchMediaList`、`buildRequestParams`
+- 常量：`UPPER_SNAKE_CASE`
+  - 示例：`DEFAULT_PAGE_SIZE`
+- 布尔变量：`is/has/can/should + PascalCase`
+  - 示例：`isLoading`、`hasPermission`
+- Promise 异步动作：动词开头
+  - 示例：`fetchUserInfo`、`loadEpisodeList`
+
+## 3) Vue 约定命名
+
+- 事件处理函数统一 `handleXxx`
+  - 示例：`handleSubmit`、`handleEpisodeChange`
+- 事件命名（emit）使用 `kebab-case`
+  - 示例：`episode-change`、`submit-success`
+- props 命名在代码中使用 `camelCase`，模板中可使用 `kebab-case`。
+- 计算属性命名以业务语义为主，避免 `data1`、`tempVal` 这类占位名。
+
+## 4) 类型命名细则
+
+- DTO/接口模型建议加语义后缀：
+  - 入参：`XxxParams`
+  - 返回：`XxxResp` 或 `XxxResponse`
+  - 列表项：`XxxItem`
+- 错误类型建议统一：`XxxError`
+- 避免使用 `IUser` 这类 `I` 前缀接口命名。
+
+## 5) 禁止项
+
+- 禁止拼音命名（业务专有词且已有共识除外）。
+- 禁止无语义缩写（如 `tmp`, `obj2`, `aaa`）。
+- 禁止单字符业务变量命名（循环计数器 `i/j/k` 除外）。
+- 禁止同一模块混用多种命名风格。
+
+## 6) 快速示例
+
+```ts
+// good
+const DEFAULT_RETRY_COUNT = 2;
+
+interface QueryMediaListParams {
+  pageNumber: number;
+  pageSize: number;
+}
+
+async function fetchMediaList(params: QueryMediaListParams) {
+  // ...
+}
+
+const isListEmpty = computed(() => state.list.length === 0);
+```
+
+```ts
+// bad
+const retryCountDefault = 2; // 常量未使用 UPPER_SNAKE_CASE
+interface IQuery {} // 不建议 I 前缀
+async function getdata(d: any) {} // 命名与类型均不规范
+const temp = computed(() => state.list.length === 0); // 语义弱
+```
@@ -0,0 +1,83 @@
+# 提问模板（团队可直接复制）
+
+以下模板用于稳定触发 `frontend-project-standards`，并确保输出符合本规范的交付结构。
+
+## 模板 1：新页面开发（标准版）
+
+```text
+请按 frontend-project-standards 开发新页面：<页面路径或模块名>。
+要求：
+1) 页面按 container + components + hooks + service 分层；
+2) 接口统一走 src/service/*.ts，禁止在 .vue/hook 里直接 request；
+3) 补齐 loading/error/empty 状态与错误处理；
+4) 不新增宽泛 any；
+5) 命名遵循 naming-conventions.md（历史可保留，新增/改动必须新规范）；
+6) 不要把单一页面过度拆成很多 component，只有复用、复杂交互或清晰业务边界时才拆。
+
+交付时请输出：
+- 分层说明
+- hooks 变更
+- API 变更与类型
+- 错误处理覆盖
+- 维护性收益
+- 自检结果
+```
+
+## 模板 2：重构大文件（如 mediaContentInfo）
+
+```text
+请按 frontend-project-standards 重构：<目标文件路径>。
+当前文件职责混杂，请拆分为多个单一职责 hook，并保持原有行为不回退。
+要求重点：
+1) 分离分页、权限/付费、埋点上报、路由同步等业务域；
+2) 保持 service 层接口边界清晰并补齐类型；
+3) 异步流程加上失败兜底与状态恢复；
+4) 组件拆分保持克制，避免把页面按视觉小块切成大量一次性 component；
+5) 完成后给出迁移说明（旧逻辑 -> 新结构映射）。
+```
+
+## 模板 3：新增接口并接入页面
+
+```text
+请按 frontend-project-standards 完成接口接入：
+- 新增接口：<接口描述>
+- 接入页面：<页面路径>
+
+要求：
+1) 在 src/service/<domain>.ts 新增 typed 方法（params/response）；
+2) 页面只通过 hook 使用 service；
+3) 禁止组件层直接请求；
+4) 输出本次 API contract（字段说明 + 类型）。
+```
+
+## 模板 4：问题修复（带规范化）
+
+```text
+请按 frontend-project-standards 修复问题：<问题描述>。
+除修复 bug 外，还要完成最小必要规范化：
+1) 抽离与 bug 相关的混杂逻辑到 hook；
+2) 补齐错误处理分支，避免静默失败；
+3) 确保不新增 any，不绕过 service；
+4) 给出回归风险点和验证步骤。
+```
+
+## 模板 5：仅做规范审查（不大改代码）
+
+```text
+请按 frontend-project-standards 对以下改动做规范审查并给出修正建议：
+<文件路径或 diff 范围>
+
+请按严重程度输出：
+1) 违反分层/hook/API/错误处理规范的问题；
+2) 每个问题的最小修复方案；
+3) 可选优化项；
+4) 最后给出 PR 自检清单通过情况。
+```
+
+## 建议补充信息（提高一次成功率）
+
+- 目标文件路径
+- 是否允许拆文件/重命名
+- 行为兼容要求（必须保持 / 可调整）
+- 优先级（性能、可维护性、上线速度）
+- 是否需要同时补测试
@@ -0,0 +1,148 @@
+# 参考模板
+
+## 1) Service 方法模板
+
+```ts
+import request from '@/utils/request';
+
+export interface QueryListParams {
+  pageNumber: number;
+  pageSize: number;
+  mediaId?: string;
+}
+
+export interface QueryListResp {
+  list: Array<{
+    id: string;
+    title: string;
+  }>;
+  total: number;
+}
+
+export default class ExampleApi {
+  static queryList(params: QueryListParams): Promise<QueryListResp> {
+    return request.get('/example/list', params);
+  }
+}
+```
+
+## 2) Hook 模板（单一职责）
+
+```ts
+import { reactive } from 'vue';
+import ExampleApi, { QueryListParams } from '@/service/example';
+
+export function useExampleList(initialParams: QueryListParams) {
+  const state = reactive({
+    loading: false,
+    error: false,
+    list: [] as Array<{ id: string; title: string }>,
+    total: 0,
+  });
+
+  const fetchList = async (params = initialParams) => {
+    state.loading = true;
+    state.error = false;
+
+    try {
+      const res = await ExampleApi.queryList(params);
+      state.list = res.list || [];
+      state.total = Number(res.total || 0);
+    } catch (err) {
+      state.error = true;
+      state.list = [];
+      state.total = 0;
+    } finally {
+      state.loading = false;
+    }
+  };
+
+  return {
+    state,
+    fetchList,
+  };
+}
+```
+
+## 3) 容器页模板（Container View）
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoute } from 'vue-router';
+import { useExampleList } from './hooks/useExampleList';
+
+const route = useRoute();
+const mediaId = computed(() => String(route.query.id || ''));
+
+const { state, fetchList } = useExampleList({
+  pageNumber: 1,
+  pageSize: 30,
+  mediaId: mediaId.value,
+});
+
+fetchList();
+</script>
+```
+
+## 4) 错误处理最低检查项
+
+- 每个异步动作都具备成对的 loading 开关。
+- 请求失败时会落到确定性兜底状态。
+- 接口细节与类型由 service 层承载。
+- UI 层能展示空态/错误态，不允许静默失败。
+
+## 5) 旧代码 any 的渐进迁移模式
+
+```ts
+// 改造前
+// static getMediaHot(data: any) {
+//   return request.get('/media/hot', data);
+// }
+
+// 改造后（增量迁移）
+export interface GetMediaHotParams {
+  pageNumber: number;
+  pageSize: number;
+  moduleId?: string;
+}
+
+export interface GetMediaHotResp {
+  list: Types.Acg.MediaContentListItem[];
+  total: number;
+}
+
+static getMediaHot(data: GetMediaHotParams): Promise<GetMediaHotResp> {
+  return request.get('/media/hot', data);
+}
+```
+
+## 6) PR 自检输出模板
+
+在实现说明中必须附上以下区块（与 `SKILL.md` 保持一致）：
+
+```markdown
+### 自检结果
+- [x] view/hook 层没有直接请求调用
+- [x] service 边界方法具备明确类型
+- [x] 未新增宽泛 any
+- [x] 异步失败分支具备兜底状态
+- [x] 混杂职责已拆分为聚焦 hooks/components
+```
+
+## 7) 轻量自动校验命令（可执行）
+
+在仓库根目录执行以下命令进行快速自检：
+
+```bash
+# 1) 优先检查本次改动的 view/hook 文件是否直接调用 request
+rg "request\\.(get|post|put|delete|deletes)\\(" <changed-view-or-hook-files>
+
+# 2) 检查本次改动文件是否引入 any（人工结合 diff 判断）
+rg "\\bany\\b" <changed-files>
+```
+
+判定规则：
+- 命令 1 预期为“无结果”；有结果则说明可能绕过 service。
+- 命令 2 不要求仓库清零，但本次改动不应新增宽泛 `any`。
+- 只有在做全仓治理或用户明确要求时，才扩展到 `src/views src/hooks src/service` 全量扫描。