@captain_z/zsk-skills 0.1.0

package/frontend/feature-tasks-frontend/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: zsk:feature-tasks-frontend
+description: Frontend component/page feature task template — 7-category
+  mandatory (事实源对齐 / Props 契约 / UE-MCP 刷新 / UE 状态 / 测试 / 视觉回归 / 质量门禁). Enforces
+  TDD-first, contract-driven, evidence-before-assertion.
+category: resource
+domain: frontend
+tier: optional
+change_type: feature
+related:
+  - ../../sdlc/task-structure/SKILL.md
+  - ../../sdlc/task-evidence/SKILL.md
+  - ../../sdlc/task-tracking/SKILL.md
+  - ../dor-dod-frontend/SKILL.md
+  - ../spec-frontend/SKILL.md
+  - ../testing-web/SKILL.md
+  - ../i18n/SKILL.md
+triggers:
+  - frontend feature tasks
+  - component tasks template
+  - 7 category tasks
+  - Props UE state visual regression
+---
+
+# Feature Tasks · Frontend（7 类强制任务）
+
+> **用途**：前端**新功能**（组件 / 页面）的任务列表模板，直接复制到 `docs/{module}/tasks.md`
+> **适用**：新组件 / 新页面 / 新能力 / 新接入点（有 UI 的变更）
+> **非组件类 Feature**（接口 / 纯数据 / 构建工具）：用 [`zsk:task-structure`](../../sdlc/task-structure/SKILL.md) 通用框架，不走本模板
+
+## 核心纪律
+
+- **测试驱动优先**：能 TDD 就 TDD（`superpowers:test-driven-development`）
+- **契约驱动**：Props / Event / API 类型引自 Spec，不自造
+- **强制 7 类任务**：组件类需求至少覆盖下述 7 个类别
+- **证据先于断言**：每任务完成必须有验证链接
+
+## 7 类强制任务
+
+| # | 类别 | 目标 | 典型工作量 |
+| --- | --- | --- | --- |
+| 1 | 事实源对齐 | Spec / Design / API / UE 契约已冻结 | XS |
+| 2 | Props / API 契约实现 | 类型引入 + Props + Event 回调 | S |
+| 3 | UE / MCP 上下文刷新 | Figma 读取结果落盘到 ue-mcp.md | XS |
+| 4 | UE 状态实现 | loading / empty / error / hover / focus / selected | M |
+| 5 | 测试实现（TDD） | 单元 + 集成 + a11y | M |
+| 6 | 视觉回归 | Figma 对照 + 差异记录 | S |
+| 7 | 质量门禁准备 | lint / type-check / 覆盖率 / 三语 | XS |
+
+## 完整模板（复制到 `docs/{module}/tasks.md`）
+
+```md
+# Tasks: {模块} — {需求名}
+
+> 变更类型：Feature · 领域：Frontend（组件类）
+> 模块唯一标识：{module-id}
+> 关联文档：proposal.md / spec.md / design.md / api-contract.md / ue-mcp.md
+> 责任人：@{handle}
+> 日期：{YYYY-MM-DD}
+
+## 任务概述
+
+{1–2 句话描述本轮迭代做什么、不做什么}
+
+## DoR（启动前门禁）
+
+见 `zsk:dor-dod` + `zsk:dor-dod-frontend` 清单，全勾方可启动。
+
+- [ ] （逐项勾选）
+
+---
+
+## 任务列表
+
+### 1. 事实源对齐（XS / 0.5 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：无（前置对齐任务）
+
+子任务：
+- [ ] 1.1 Spec / Design 冻结核对（FR/NFR/US/AC 编号齐全）
+- [ ] 1.2 `{{config.paths.api_contracts}}` 下类型已同步后端
+- [ ] 1.3 `ue-mcp.md` 已登记（有 Figma 输入时）
+- [ ] 1.4 本轮涉及的 ADR 已 Accepted
+
+交付物：核对记录（本任务本身的勾选）
+验证：Spec / Design / api-contract / ue-mcp 文件 diff 链接
+
+---
+
+### 2. Props / API 契约实现（S / 1 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：FR-1, FR-2（示例，引自 spec.md）
+
+子任务：
+- [ ] 2.1 从后端生成的 types 引入（`import type { XxxResponse } from '{{config.paths.api_contracts}}/...'`）
+- [ ] 2.2 Props 接口声明（对照 spec.md `Component Public Contract`）
+- [ ] 2.3 Event 回调实现（`onChange` / `onSelect` / ...）
+- [ ] 2.4 service 层封装（引用 `{{config.paths.services_entry}}`，不新建 request 实例）
+
+交付物：组件 Props / Event 类型 · service 调用代码
+验证：单元测试覆盖类型边界 · 手动触发 event，log 捕获回调参数
+
+---
+
+### 3. UE / MCP 上下文刷新（XS / 0.5 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：NFR-4（i18n）、NFR-5（兼容性）
+
+子任务：
+- [ ] 3.1 Figma MCP 读取当前 snapshot
+- [ ] 3.2 结果落盘到 `docs/{module}/ue-mcp.md`（人读摘要）
+- [ ] 3.3 `{{config.paths.design_assets}}/{module}/{snapshot}/description.md` 归档（完整快照）
+
+交付物：刷新后的 `ue-mcp.md` · description.md 快照
+验证：快照文件存在性检查
+
+---
+
+### 4. UE 状态实现（M / 2 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：FR-3, FR-4（示例）
+
+子任务：
+- [ ] 4.1 loading / empty / error 三态（对照 spec.md UE 状态矩阵）
+- [ ] 4.2 hover / focus-visible / selected / disabled
+- [ ] 4.3 组件特有状态（search-hit / lazy-loading / ...）
+- [ ] 4.4 键盘交互（Tab / Enter / Space / Esc / 方向键）
+
+交付物：所有状态的 JSX 实现 · 状态对应样式
+验证：逐一触发每个状态并截图 · 对照 Figma 状态矩阵
+
+---
+
+### 5. 测试实现（M / 2 人天，TDD 优先）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：全体 P0 FR 的验收路径
+
+子任务：
+- [ ] 5.1 单元测试（Props / hooks / utils / 归一化函数）
+- [ ] 5.2 集成测试（组件 + service + 路由）
+- [ ] 5.3 a11y 测试（axe-core + 键盘矩阵回归）
+- [ ] 5.4 AC 到测试的映射（每条 AC 至少一条测试）
+
+交付物：`__tests__/` 目录下的测试文件 · 覆盖率报告
+验证：`test` 全绿 + 覆盖率 ≥ `{{config.quality.testing.unit_coverage_min}}%`；新增代码 `{{config.quality.testing.new_code_coverage}}%`
+
+详细工具链见 [`zsk:testing-web`](../testing-web/SKILL.md)
+
+---
+
+### 6. 视觉回归（S / 1 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：NFR-2（a11y）、所有视觉 FR
+
+子任务：
+- [ ] 6.1 Figma 关键节点截图（参考 `zsk:figma-to-code` 的还原判定）
+- [ ] 6.2 实现截图
+- [ ] 6.3 差异记录到 `docs/{module}/archive/{YYYY-MM-DD}-visual-regression/`
+- [ ] 6.4 差异 > 还原判定阈值 → 修复再截 / 在 design.md ADR 解释保留
+
+交付物：before (Figma) / after (实现) 截图对照 · 差异记录
+验证：对照文件存在 + 差异在阈值内
+
+---
+
+### 7. 质量门禁准备（XS / 0.5 人天）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：兜底 — FR 覆盖矩阵全绿
+
+子任务：
+- [ ] 7.1 `lint` / `type-check` 零 error（`{{config.scripts.lint}}` / `{{config.scripts.type_check}}`）
+- [ ] 7.2 `test` 覆盖率达标（`{{config.scripts.test}}`）
+- [ ] 7.3 i18n 多语（语言清单 `{{config.i18n.languages}}`）同 commit 同步
+- [ ] 7.4 依赖无高危（按栈扫描）
+- [ ] 7.5 包体积增量 < 10%（或有 ADR 豁免）
+
+交付物：门禁证据（见 [`zsk:task-evidence`](../../sdlc/task-evidence/SKILL.md) 的校验记录模板）
+验证：整表勾选完整，每行有链接
+
+---
+
+## 任务依赖
+
+\`\`\`mermaid
+graph LR
+  T1[1.事实源对齐] --> T2[2.Props/API]
+  T1 --> T3[3.UE/MCP 刷新]
+  T2 --> T4[4.UE 状态]
+  T3 --> T4
+  T2 --> T5[5.测试]
+  T4 --> T6[6.视觉回归]
+  T6 --> T7[7.质量门禁]
+\`\`\`
+
+## 阻塞记录 / 里程碑
+
+见 [`zsk:task-tracking`](../../sdlc/task-tracking/SKILL.md) 模板。
+
+## 总工作量
+
+- T-shirt：`M`
+- 人天：`7.0`
+- 工期：`{按并行度压缩的日历天}`
+
+## 证据记录
+
+DoR / DoD / FR 覆盖矩阵 / AC 勾选 / 校验记录 → 见 [`zsk:task-evidence`](../../sdlc/task-evidence/SKILL.md) 的模板。
+
+---
+
+## DoD（关闭前门禁）
+
+见 `zsk:dor-dod` + `zsk:dor-dod-frontend` 清单，全勾方可合并。
+```
+
+## Skip 规则
+
+| 场景 | 可跳过的任务 |
+| --- | --- |
+| 文案微调 | 3（UE/MCP）、6（视觉回归）可简化 |
+| 仅接入现有组件 | 4（UE 状态）可简化（只做新增状态） |
+| 后端已稳定上线 | 2 可部分提前（类型先同步，Props 跟 UE 一起做） |
+
+**不能省**：1（事实源对齐）、5（测试）、7（质量门禁）。
+
+## 反模式（禁止）
+
+- ❌ 跳过事实源对齐直接写代码（Spec / Design 未冻结 → 必返工）
+- ❌ 测试放到最后一把梭哈（TDD 精神丧失）
+- ❌ 视觉回归只截 after 不截 before
+- ❌ 质量门禁"事后补证据 PR"
+- ❌ 任务 > 2 人天不拆（blocker 影响扩大）

package/frontend/i18n/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: zsk:i18n
+description: Frontend module i18n implementation — unified entry (i18n.t with
+  mandatory fallback), key namespace structure (namespace.module.leaf_key),
+  three-language sync rule (commit-atomic), ICU MessageFormat for plural/select,
+  Intl.* for date/number/currency, RTL declaration, React Trans component for
+  JSX interpolation. Replaces standards/i18n for frontend scope.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-naming/SKILL.md
+  - ../a11y-web/SKILL.md
+  - ../../system/nfr-baseline/SKILL.md
+triggers:
+  - i18n implementation
+  - key namespace
+  - fallback baseline
+  - ICU plural
+  - three language sync
+  - Intl.DateTimeFormat
+  - RTL
+  - Trans component
+---
+
+# i18n · 国际化实现（Web）
+
+> **范围**：前端 i18n 的**具体实现** — 入口 / key 命名 / 三语同步 / ICU / Intl.* / JSX 插值 / RTL
+> **前置纪律**：国际化**开发当下完成**，禁止"先中文、最后补翻译"
+> **基线语言**：`{{config.i18n.languages}}` 的第一个（通常 `zh_CN`）是事实源
+
+## 1. 统一入口（强制）
+
+### 标准调用
+
+```ts
+import { i18n } from '{{config.i18n.entry}}';
+
+i18n.t('{{config.i18n.namespace}}.order.empty', '暂无订单');
+i18n.t('{{config.i18n.namespace}}.order.total', '共{total}条', { total });
+```
+
+### 签名
+
+```ts
+i18n.t(key: string, fallback: string, values?: Record<string, unknown>): string
+```
+
+- `key`：必填，遵循命名规则（见下节）
+- `fallback`：**必填**，**必须等于基线语言文案**
+- `values`：可选，占位符替换 / ICU 参数
+
+### 禁止
+
+- ❌ 缺 fallback：`i18n.t('order.empty')`
+- ❌ fallback 非基线语言：`i18n.t('order.empty', 'No data')`（基线是中文时）
+- ❌ 非标准签名：`i18n.t({ k: 'x', d: 'y' })`
+- ❌ 跳过统一入口直接调底层 SDK
+- ❌ FC 组件函数体硬编码基线语言文案（`<div>暂无订单</div>` 不经 i18n）
+
+### 全局 i18n 工具边界
+
+`{{config.i18n.entry}}` **只允许**：
+
+- `i18n.t`
+- `i18n.getI18nStringToObj`
+- `i18n.getValueByI18n`
+
+**禁止**掺入：领域化命名 / 业务映射表 / UI 副作用 / 业务逻辑。
+
+## 2. Key 命名规则
+
+### 结构
+
+```
+{{config.i18n.namespace}}.<module>.<leaf_key>
+```
+
+| 段 | 约定 | 示例 |
+| --- | --- | --- |
+| namespace | 项目配置决定 | `app` / `admin` |
+| module | lowerCamelCase | `order` / `userProfile` |
+| leaf_key | snake_case，语义优先 | `empty` / `load_failed` / `btn_confirm` |
+
+### 示例
+
+```
+app.order.list.empty
+app.order.list.error.network
+app.userProfile.avatar.alt
+app.common.btn.confirm
+```
+
+### 硬规则
+
+- 全小写 + `.` 分隔；不含中文、空格、下划线在层级分隔位
+- **一旦发布不可重命名**；必须调整时：
+  1. 新旧 key 同时存在一段时间
+  2. 全量迁移所有语言文件 + 所有调用点
+  3. 迁移完成移除旧 key（独立 commit）
+- key 语义优先于位置（不要 `page1.btn3`，用 `order.detail.submit`）
+
+### 与 react-naming 对齐
+
+见 [`react-naming`](../react-naming/SKILL.md) 的 i18n key 命名条目。
+
+## 3. 语言文件规范
+
+### 基线 + 非基线
+
+- **基线语言**（通常 `zh_CN`）：事实源，不允许空字符串占位
+- **非基线语言**：不得缺 key；暂时无法翻译**必须占位 + 任务追踪**
+
+### JSON 规则
+
+- 必须合法：禁止注释、禁止重复 key
+- 按模块分组并字母序排序，方便 diff
+- 所有语言文件 key 结构**完全一致**
+
+### 三语同步（硬门禁）
+
+**同一 PR 内**必须同时提交所有语言文件（见 `{{config.i18n.languages}}`）：
+
+- 新增 key → 每种语言都加
+- 删除 key → 每种语言都删
+- 改文案 → 对应语言改（fallback 同步改）
+
+CI 必查：语言文件 key 数量一致 + key 路径一致。
+
+## 4. ICU MessageFormat
+
+涉及**复数 / 性别 / 枚举**文案时使用 ICU，不得用字符串拼接。
+
+### 复数（plural）
+
+```ts
+i18n.t(
+  'app.order.count',
+  '{count, plural, =0 {无订单} one {# 个订单} other {# 个订单}}',
+  { count },
+);
+```
+
+### 选择（select）
+
+```ts
+i18n.t(
+  'app.user.status',
+  '{status, select, active {活跃} inactive {禁用} other {未知}}',
+  { status },
+);
+```
+
+### 硬规则
+
+- 所有语言文件**同步使用 ICU 结构**（不得某语言退化为拼接）
+- `other` 分支必填（兜底）
+- 不允许在 TS 代码里手写 `if (count === 0) ... else if (count === 1) ...` 后调用 `i18n.t`
+
+## 5. Intl.* · 日期 / 数字 / 货币
+
+### 禁止硬编码
+
+- ❌ `YYYY-MM-DD` 硬格式化
+- ❌ `toLocaleString()` 不传 locale（不同环境行为不一致）
+- ❌ `${price.toFixed(2)}元` 假定货币 / 区域
+
+### 正确用法
+
+```ts
+// 日期
+new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' }).format(date);
+
+// 数字
+new Intl.NumberFormat(locale, { minimumFractionDigits: 2 }).format(value);
+
+// 货币
+new Intl.NumberFormat(locale, { style: 'currency', currency: 'CNY' }).format(price);
+
+// 相对时间
+new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(-1, 'day'); // "1 天前"
+```
+
+`locale` 从 i18n 运行时读取，不在组件内硬写。
+
+### 时区
+
+- 默认跟随浏览器
+- 业务必须指定（如"始终 UTC+8"）→ 在 `spec.md` NFR 声明，并使用 `timeZone` 选项
+
+## 6. React JSX 插值
+
+### 简单占位
+
+```tsx
+<div>{i18n.t('app.order.total', '共{total}条', { total })}</div>
+```
+
+### 复杂插值（Trans 组件）
+
+文本中需要嵌入 JSX（链接、加粗、图标）时：
+
+```tsx
+<Trans
+  i18nKey="app.order.read_terms"
+  defaults="请阅读<link>使用条款</link>后提交"
+  components={{ link: <a href="/terms" /> }}
+/>
+```
+
+优于字符串拼接 + `dangerouslySetInnerHTML`。
+
+### 禁止
+
+- ❌ 字符串拼接构造可见文案（`'共' + total + '条'`）
+- ❌ 用 `dangerouslySetInnerHTML` 注入翻译文本（XSS 风险）
+
+## 7. 可访问属性的文案
+
+JSX 里**所有**对用户可见或被读屏读出的字符串都要 i18n：
+
+| 属性 | 示例 |
+| --- | --- |
+| `aria-label` | `aria-label={i18n.t('app.modal.close', '关闭')}` |
+| `alt` | `alt={i18n.t('app.avatar.alt', '用户头像')}` |
+| `title` | `title={i18n.t(...)}` |
+| `placeholder` | `placeholder={i18n.t(...)}` |
+| 错误消息 | `form.setError(...)` 的消息 |
+| Toast / 通知 | `notify({ message: i18n.t(...) })` |
+
+与 [`a11y-web`](../a11y-web/SKILL.md) 的 aria 实现配合。
+
+## 8. RTL（右到左）
+
+### 当前模块不支持 RTL
+
+在 `spec.md` NFR 声明"暂不支持 RTL（语言清单不含 ar / he）"。
+
+### 支持 RTL 时
+
+1. 使用 **CSS 逻辑属性**：
+   - `margin-inline-start` / `padding-inline-end`（不用 `left/right`）
+   - `inset-inline-start` / `border-inline-*`
+2. 图标方向适配（箭头、翻页、返回）
+3. `dir="rtl"` 通过 `<html dir>` 或容器属性注入
+4. 测试：Playwright 切换 locale 验证布局镜像
+
+## 9. 组件实践
+
+### Hook 封装（减少 import）
+
+```ts
+// useT.ts
+export function useT() {
+  return { t: i18n.t };
+}
+
+// 组件
+const { t } = useT();
+<button>{t('app.common.btn.confirm', '确认')}</button>
+```
+
+不是硬性要求，项目内一致即可。
+
+### 避免在渲染时做重活
+
+`Intl.DateTimeFormat` 实例化有开销。高频场景**缓存实例**：
+
+```ts
+const dateFormatter = useMemo(
+  () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+  [locale],
+);
+```
+
+## 反模式（禁止）
+
+- ❌ "先中文、最后补翻译"
+- ❌ 字符串拼接构造可见文案
+- ❌ 缺 fallback 或 fallback ≠ 基线文案
+- ❌ 三语不同 commit 提交
+- ❌ 复数 / 选择用 if / switch 而非 ICU
+- ❌ 日期 / 数字硬编码
+- ❌ 把业务逻辑塞进 i18n 工具
+- ❌ `aria-label` / `alt` / `placeholder` 硬编码
+
+## 质量门禁
+
+- [ ] 所有可见文案 / a11y 属性走 `i18n.t`
+- [ ] 每次 `i18n.t` 调用有合法 fallback
+- [ ] Key 结构符合 `{{config.i18n.namespace}}.<module>.<leaf_key>`
+- [ ] 三语（`{{config.i18n.languages}}`）同 commit 同步
+- [ ] 复数 / 选择用 ICU
+- [ ] 日期 / 数字用 `Intl.*`
+- [ ] RTL 支持在 `spec.md` 有声明
+- [ ] CI 通过语言文件一致性检查