@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/localized/zh-CN/skills/fec-vue3-project-standard/references/vue3-state-api-quality.md

@@ -0,0 +1,216 @@
+# Vue 3 状态、API 与质量模式
+
+## 状态管理（Pinia）
+
+| 状态类型           | 推荐方案                      |
+| ------------------ | ----------------------------- |
+| 组件内临时 UI 状态 | `ref` / `reactive`            |
+| 跨组件共享业务状态 | Pinia store                   |
+| 服务端数据缓存     | VueQuery / 自定义 composable  |
+| URL 驱动状态       | 路由参数 / `useRoute().query` |
+| 表单状态           | VeeValidate / FormKit         |
+
+### Pinia Store 规范
+
+使用 Composition API 风格（`setup store`）：
+
+```typescript
+// stores/authStore.ts
+export const useAuthStore = defineStore("auth", () => {
+  const user = ref<User | null>(null);
+  const token = ref<string | null>(localStorage.getItem("token"));
+
+  const isLoggedIn = computed(() => !!token.value);
+
+  async function login(credentials: LoginParams) {
+    const res = await authApi.login(credentials);
+    user.value = res.user;
+    token.value = res.token;
+    localStorage.setItem("token", res.token);
+  }
+
+  function logout() {
+    user.value = null;
+    token.value = null;
+    localStorage.removeItem("token");
+  }
+
+  return { user: readonly(user), isLoggedIn, login, logout };
+});
+```
+
+### Store 原则
+
+- 每个 store 职责单一，按领域拆分
+- 对外暴露 `readonly` 的状态，通过 action 修改
+- 不要在 store 中存放 UI 临时状态（modal 开关、表单输入等）
+- 服务端数据优先用请求库管理，而非手动存入 store
+
+## API 层规范
+
+### 请求实例
+
+```typescript
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.request.use((config) => {
+  const authStore = useAuthStore();
+  if (authStore.token) {
+    config.headers.Authorization = `Bearer ${authStore.token}`;
+  }
+  return config;
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      const authStore = useAuthStore();
+      authStore.logout();
+      router.push({ name: "Login" });
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+### API 函数
+
+```typescript
+// features/user/api.ts
+export function getUserList(
+  params: UserQueryParams,
+): Promise<PageResult<User>> {
+  return request.get("/users", { params });
+}
+
+export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return request.put(`/users/${id}`, data);
+}
+```
+
+- API 函数按 feature 组织，而非全部堆在一个文件
+- 请求参数和响应都有类型约束
+- 拦截器统一处理认证、错误格式化
+
+## 错误处理
+
+### 全局错误捕获
+
+```typescript
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+  reportError(err, { component: instance?.$options.name, info });
+};
+```
+
+### 组件级错误
+
+- 使用 `onErrorCaptured` 在父组件中捕获子组件错误
+- 数据请求失败需有用户可见的提示和重试机制
+- 不要吞掉错误（空 catch 块）
+
+## 自定义指令
+
+```typescript
+// directives/vPermission.ts
+export const vPermission: Directive<HTMLElement, string> = {
+  mounted(el, binding) {
+    const authStore = useAuthStore();
+    if (!authStore.hasPermission(binding.value)) {
+      el.parentNode?.removeChild(el);
+    }
+  },
+};
+```
+
+- 指令只处理 DOM 层面的操作
+- 业务逻辑不要放在指令中
+- 需要响应式更新时实现 `updated` 钩子
+
+## 样式规范
+
+- 使用 `<style scoped>` 隔离样式
+- 深度选择器使用 `:deep()` 而非已废弃的 `::v-deep`
+- 与项目现有样式体系保持一致
+- 动态样式优先使用 `:class` / `:style` 绑定
+- 复杂主题切换使用 CSS 变量
+- 主题/全局变量通过 CSS 变量或 Token 管理
+
+## 测试规范
+
+### 必须测试
+
+- 核心交互行为（点击、输入、提交）
+- 条件渲染（loading / error / empty / data）
+- Emits 的触发和 payload
+- 关键 composables 的返回值
+- Pinia store 的 action 和 getter
+
+### 测试风格
+
+```typescript
+describe("UserForm", () => {
+  it("should emit submit with valid data", async () => {
+    const wrapper = mount(UserForm);
+
+    await wrapper.find('[data-testid="username"]').setValue("test");
+    await wrapper.find("form").trigger("submit");
+
+    expect(wrapper.emitted("submit")?.[0]).toEqual([{ username: "test" }]);
+  });
+
+  it("should show validation error on empty submit", async () => {
+    const wrapper = mount(UserForm);
+    await wrapper.find("form").trigger("submit");
+    expect(wrapper.text()).toContain("用户名不能为空");
+  });
+});
+```
+
+### Store 测试
+
+```typescript
+describe("authStore", () => {
+  beforeEach(() => setActivePinia(createPinia()));
+
+  it("should login and set user", async () => {
+    const store = useAuthStore();
+    await store.login({ username: "admin", password: "pass" });
+    expect(store.isLoggedIn).toBe(true);
+  });
+});
+```
+
+
+## 反模式
+
+- 在模板驱动组件中内联大段业务逻辑
+- 本该用 computed 却使用大范围 watcher
+- 事件 payload 不明确
+- 在纯展示组件中直接混入原始 API 调用
+- ref 和 props 没有类型约束
+- 用 `watch` + 手动赋值模拟 computed
+- 在一个组件中混入无关职责
+- 用大范围全局样式覆盖去解决局部 UI 问题
+- 将所有状态推入 Pinia store，而非就近管理
+- 在 `components/` 中放业务耦合组件
+- 直接从 feature 内部深层路径导入，绕过 `index.ts`
+
+## 输出检查清单
+
+- [ ] 文件结构与项目约定一致（pages / features / components 分离）
+- [ ] 使用 `<script setup lang="ts">`
+- [ ] Props / Emits 类型完整
+- [ ] 解释性注释是否优先使用中文且点到要害
+- [ ] 可复用逻辑已提取到 composable
+- [ ] Loading / Error / Empty 状态均已处理
+- [ ] 路由组件使用动态 import 加载
+- [ ] 状态管理方案合理（就近原则）
+- [ ] API 调用有类型约束和统一错误处理
+- [ ] 样式使用 scoped 隔离
+- [ ] 关键行为有测试覆盖

package/localized/zh-CN/skills/fec-web-video-presentation/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: fec-web-video-presentation
+description: 用于将文章、演讲稿、课程、产品演示或口播解释转成可录制的 16:9 网页演示，包含步骤驱动场景、可选口播对齐、主题 Token 与录屏指导；中文触发词包括 网页视频、动态演示、口播稿转视频、可录屏演示、16:9 演示。
+---
+
+# 网页视频演示
+
+## 用途
+
+把文章、口播稿、课程、产品讲解或技术分享转成可录屏的 16:9 网页演示。产物应像一个可点击推进的视频舞台：每一步承载一个口播节拍，视觉设计服务内容节奏，并能用浏览器稳定录制。
+
+## 流程
+
+1. 判断输入形态
+   - 用户给文章或长文时，先拆成口播稿和 outline。
+   - 用户给现成口播稿时，保留原顺序，只补 outline、章节和 step。
+   - 用户只给主题但没有内容时，先要求素材、大纲或目标要点；不要替用户虚构整篇内容。
+
+2. 生成内容计划
+   - 按 [content-plan.md](references/content-plan.md) 输出 script 与 outline。
+   - script 决定讲述顺序和每个节拍；outline 决定章节、step、估时、屏幕信息和素材清单。
+   - outline 只描述内容密度和画面任务，不提前写死具体动画实现。
+
+3. 对齐演示系统
+   - 从 [theme-system.md](references/theme-system.md) 或 [starter-themes.json](data/starter-themes.json) 选择一个 starter theme，也可以按项目品牌重新定义 token。
+   - 使用 [create-video-presentation.mjs](scripts/create-video-presentation.mjs) 创建最小 Vite + React + TypeScript 演示骨架：
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs ./presentation --theme editorial-slate
+     ```
+   - 如只想预览可选主题或计划写入内容：
+     ```bash
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --list-themes
+     node skills/fec-web-video-presentation/scripts/create-video-presentation.mjs --dry-run ./presentation --theme editorial-slate
+     ```
+
+4. 实现章节
+   - 每章按 [chapter-craft.md](references/chapter-craft.md) 实现。
+   - 每个 step 独占舞台，屏幕只承载当前口播节拍需要用户理解的核心内容。
+   - 章节必须有可见的视觉演示、图形、布局变化、状态推进或数据/媒体呈现；不要交付纯文本幻灯片。
+   - 第一章应作为风格锚点优先完成并验收，再继续其它章节。
+
+5. 录屏和音频
+   - 使用 [recording-and-audio.md](references/recording-and-audio.md) 检查舞台比例、导航、录制模式和可选音频同步。
+   - 音频可以来自用户已有文件、宿主工具或项目自己的 TTS 流程；本技能不绑定特定 TTS 供应商。
+
+6. 交付前验证
+   - 浏览器打开演示，检查 16:9 缩放、键盘/点击推进、step 数、文本溢出、隐藏控件、控制台错误和录屏路径。
+   - 若章节数量、顺序或 step 数变化，重置本地持久化 key 或清理旧进度，避免恢复到不存在的 step。
+
+## 约束
+
+- 不把网页视频做成普通营销落地页、静态 PPT 或长滚动文章。
+- 不复制参考项目的主题、模板章节、长提示词或脚手架实现；按当前项目生成原创骨架。
+- 不在 outline 阶段锁死每个动画名称；动画应由章节内容关系驱动。
+- 不使用假数据、假引用、假产品截图或不可检查媒体填充画面。
+- 不让控件、页码、说明文字或调试面板污染录屏画面；必要控件默认隐藏或弱化。
+- 不为音频合成引入项目外供应商约定；TTS 属于可选适配层。
+
+## 预期输出
+
+输出 script、outline、可运行的 16:9 网页演示骨架或章节实现，并说明主题、章节/step 数、录屏方式、可选音频路径和验证结果。最终演示应可通过点击或键盘稳定推进，视觉节奏贴合口播内容，且适合浏览器录屏。

package/localized/zh-CN/skills/fec-web-video-presentation/data/starter-themes.json

@@ -0,0 +1,59 @@
+[
+  {
+    "id": "editorial-slate",
+    "name": "Editorial Slate",
+    "bestFor": "technical explainers, product narratives, engineering talks",
+    "tokens": {
+      "stageBg": "#f6f1e8",
+      "stageFg": "#17201b",
+      "mutedFg": "#69736d",
+      "accent": "#a83d2d",
+      "accent2": "#2b6b72",
+      "panel": "#fffaf0",
+      "line": "#d9cab8",
+      "shadow": "0 24px 80px rgba(23, 32, 27, 0.12)",
+      "fontDisplay": "Georgia, 'Times New Roman', serif",
+      "fontBody": "Inter, ui-sans-serif, system-ui, sans-serif",
+      "radius": "10px",
+      "stepDuration": "4200ms"
+    }
+  },
+  {
+    "id": "console-amber",
+    "name": "Console Amber",
+    "bestFor": "debug stories, infrastructure demos, security walkthroughs",
+    "tokens": {
+      "stageBg": "#10110f",
+      "stageFg": "#f5ead2",
+      "mutedFg": "#a99b80",
+      "accent": "#ffb84d",
+      "accent2": "#6bd5c8",
+      "panel": "#191a16",
+      "line": "#3c3529",
+      "shadow": "0 28px 90px rgba(0, 0, 0, 0.38)",
+      "fontDisplay": "ui-monospace, SFMono-Regular, Consolas, monospace",
+      "fontBody": "Inter, ui-sans-serif, system-ui, sans-serif",
+      "radius": "6px",
+      "stepDuration": "3800ms"
+    }
+  },
+  {
+    "id": "studio-paper",
+    "name": "Studio Paper",
+    "bestFor": "design reviews, lessons, product tours, calm keynote chapters",
+    "tokens": {
+      "stageBg": "#fbfbf7",
+      "stageFg": "#24211d",
+      "mutedFg": "#6f6a62",
+      "accent": "#2457a6",
+      "accent2": "#d95f37",
+      "panel": "#ffffff",
+      "line": "#dedbd2",
+      "shadow": "0 18px 64px rgba(36, 33, 29, 0.1)",
+      "fontDisplay": "Aptos Display, Avenir Next, ui-sans-serif, system-ui, sans-serif",
+      "fontBody": "Aptos, Avenir Next, ui-sans-serif, system-ui, sans-serif",
+      "radius": "14px",
+      "stepDuration": "4000ms"
+    }
+  }
+]

package/localized/zh-CN/skills/fec-web-video-presentation/references/chapter-craft.md

@@ -0,0 +1,37 @@
+# 章节编排
+
+## 阶段规则
+
+- 使用固定 16:9 舞台，通常为 1920 x 1080，并按视口缩放。
+- 章节是当前 step 的纯函数。
+- 一个 step 只聚焦一个视觉想法。
+- 列表每次只揭示一个有意义的条目。
+- 使用隐藏或低强调控件，让录制画面保持干净。
+- 大号文字在录屏和压缩后仍需保持可读。
+
+## 视觉决策
+
+实现章节前，先回答：
+
+- 当前 step 与上一个 step 的关系是什么：对比、揭示、缩放、序列、证明、结果，还是回顾？
+- 观众在这个 step 后应该记住什么？
+- 哪个源材料细节让画面比通用幻灯片更具体？
+- 这是图表、对象、引用、指标、时间线、界面状态，还是空间隐喻？
+- 哪些内容可以因为自身变化而运动，而不是因为所有元素都需要入场动画？
+
+## 反模式
+
+- 旁白逐条讲解时，却让大量 bullet 同步 stagger。
+- 无法解释内容的紫色渐变背景、漂浮装饰或通用卡片。
+- 伪造仪表盘、伪造截图、伪造引用或编造指标。
+- 浏览器中看似正常、但录制视频中不可读的小号正文。
+- 录制画面中持续可见的 chrome、大页码或操作说明。
+
+## 完成检查
+
+- 每个 step 都渲染完整画面。
+- 文本适配目标舞台尺寸。
+- 录制在任意 step 暂停时，章节仍然说得通。
+- 视觉状态遵循旁白顺序。
+- 使用的任何媒体都是本地、真实、为任务生成，或明确标记为占位。
+- 章节注册后，键盘和点击导航仍可正常工作。

package/localized/zh-CN/skills/fec-web-video-presentation/references/content-plan.md

@@ -0,0 +1,38 @@
+# 内容计划
+
+## 脚本
+
+除非用户另有要求，否则使用与源材料相同的语言。将书面文字改成适合口播的表达，但保留作者的主张、顺序、名称和重要数字。
+
+每份脚本都应：
+
+- 每个节拍只保留一个观点。
+- 移除脚注式支线，除非它们是叙事核心。
+- 标记不确定事实，不要把它们润色成确定断言。
+- 技术名称保持准确。
+- 优先使用无需回读即可口播的短句。
+
+## 大纲
+
+大纲是网页演示的实现契约。
+
+包含：
+
+- 标题和目标受众。
+- 总目标时长。
+- 带稳定 id 的章节。
+- 每章步骤数。
+- 每步一个屏幕任务。
+- 每章内容池：可用于视觉呈现的事实、数字、引用、示例、媒体、图表或 UI 状态。
+- 资产清单，包含负责人、路径、缺失状态和替代策略。
+
+避免：
+
+- 过早指定具体动画。
+- 指定 CSS 实现细节。
+- 将需要分别关注的多个列表项塞进同一个 step。
+- 为了让场景显得充实而加入无依据的主张。
+
+## 验收标准
+
+当另一位实现者无需再决定每章讲什么、每个 step 揭示什么、哪些源事实可用于视觉呈现，就能构建演示时，内容计划才算就绪。

package/localized/zh-CN/skills/fec-web-video-presentation/references/recording-and-audio.md

@@ -0,0 +1,33 @@
+# 录制与音频
+
+## 录制模式
+
+手动模式：
+
+- Click、Space、ArrowRight 或 PageDown 前进一个 step。
+- ArrowLeft 或 PageUp 返回。
+- 适合真人旁白现场录制。
+
+自动模式：
+
+- 使用项目数据中的每步时长。
+- 适合旁白音频已对齐，或需要干净录屏的场景。
+
+## 录制检查清单
+
+- 浏览器控制台无错误。
+- 舞台居中且缩放无变形。
+- 捕获画面中没有水平或垂直滚动条。
+- 控件仅在 hover 或 focus 时显示。
+- 仅在有帮助时持久化当前 step；章节顺序或 step 数变化后重置。
+- 完整录制前先录制 10 秒样片。
+
+## 音频策略
+
+音频是可选项。项目可以使用：
+
+- 用户提供的现有旁白文件。
+- 宿主原生 TTS 或配音工具。
+- 项目自有 TTS 管线。
+
+音频对齐保持供应商中立。将片段文本和文件路径存入项目数据，但不要把供应商专属 API 契约写进 skill。

package/localized/zh-CN/skills/fec-web-video-presentation/references/theme-system.md

@@ -0,0 +1,36 @@
+# 主题系统
+
+主题是起点，不是模板。主题定义录制画布的视觉气候，同时让各章节可以自由创建贴合内容的布局。
+
+## Token 角色
+
+使用语义化 CSS 变量：
+
+- `--stage-bg`
+- `--stage-fg`
+- `--muted-fg`
+- `--accent`
+- `--accent-2`
+- `--panel`
+- `--line`
+- `--shadow`
+- `--font-display`
+- `--font-body`
+- `--radius`
+- `--step-duration`
+
+## 起始主题策略
+
+内置起始主题刻意保持少量：
+
+- 用它们创建可运行骨架。
+- 当存在真实品牌或产品语境时，替换颜色和字体选择。
+- 不要让所有章节变得一模一样；保持字体和颜色一致，同时让每章的布局与视觉手法有所变化。
+
+## 自定义主题检查清单
+
+- 录制文本的对比度达标。
+- 强调色有清晰且不同的语义职责。
+- 背景在视频压缩后不会出现浑浊渐变。
+- 字体在 1080p 和较低分辨率二次上传中仍可读。
+- 动效可以降低强度且不破坏含义。