@captain_z/zsk-skills 0.1.0

package/system/nfr-baseline/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: zsk:nfr-baseline
+description: Project NFR baseline (inherited or established) — 7-category
+  framework (performance / a11y / security / i18n / compatibility /
+  observability / reliability) and the deviation-declaration discipline.
+  Web-specific values (CWV thresholds, WCAG AA, browser matrix, 三语) live in
+  frontend/nfr-web.md.
+category: resource
+domain: system
+tier: optional
+related:
+  - ../adr/SKILL.md
+  - ../../frontend/nfr-web/SKILL.md
+  - ../../sdlc/spec/SKILL.md
+triggers:
+  - NFR baseline
+  - non functional requirements
+  - quality attributes
+  - ISO 25010
+  - deviation declaration
+---
+
+# System: NFR Baseline（系统级非功能需求基线 · 通用框架）
+
+> **定位**：系统级非功能需求的**基线框架**；模块 `spec.md` 的 NFR 章节继承本基线，只记录**偏离或加严**项
+> **参考规范**：ISO/IEC 25010
+> **填充位置**：`docs/system/nfr-baseline.md`
+> **Web 项目具体阈值**：Core Web Vitals / WCAG AA / 浏览器矩阵 / 三语 i18n 等见 [`frontend/nfr-web`](../../frontend/nfr-web/SKILL.md)
+> **继承规则**：模块未显式声明的，按本基线执行
+
+## 为什么需要
+
+- 避免每个模块 `spec.md` 重抄相同的 NFR 目标
+- 系统级调整时一处改、全局生效
+- 偏离基线必须在模块 spec 显式声明（便于审阅）
+
+## 7 类 NFR 框架（通用）
+
+| 类别 | 关注点 | 典型子项 |
+| --- | --- | --- |
+| **1. 性能** | 响应时间 / 吞吐 / 资源占用 | 首屏 / 交互响应 / 并发请求 / 内存 / CPU |
+| **2. 可访问性** | 辅助技术可用、包容性 | WCAG 等级 / 键盘 / 焦点 / 对比度（见 `quality/a11y-principles`） |
+| **3. 安全** | 机密性 / 完整性 / 可用性 | 鉴权 / CVE 响应 / 脱敏 / 供应链（见 `quality/security-owasp`） |
+| **4. 国际化** | 多语言 / 本地化 | 语言清单 / 入口 / fallback / ICU / RTL |
+| **5. 兼容性** | 运行环境范围 | 浏览器 / OS / 设备 / 分辨率 / 离线 |
+| **6. 可观测性** | 发生什么、为什么 | 错误上报 / 性能埋点 / trace / 日志脱敏 |
+| **7. 可靠性** | 故障恢复 / 降级 | 超时 / 重试 / 错误边界 / 回滚 / 熔断 |
+
+## 模板（只保留框架，不带阈值）
+
+```md
+# 系统级 NFR 基线
+
+> 版本：{YYYY-MM-DD}
+> 维护人：{姓名}
+> 关联：`../quality/*` / `../frontend/*`（分领域规范）、模块 `spec.md` 的 NFR 章节
+> Web 场景补充：见 `frontend/nfr-web.md`
+
+## 1. 性能基线
+
+| 指标 | 目标 | 度量方式 | 超限处理 |
+| --- | --- | --- | --- |
+| 首屏 / 初始渲染 | {按平台填} | {工具} | 有 ADR 豁免 |
+| 交互响应 | {目标} | {工具} |  |
+| 资源占用上限 | {目标} | {工具} |  |
+
+## 2. 可访问性基线
+
+- 等级：{WCAG 2.1 AA 或其他}
+- 键盘操作矩阵：见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md)
+- 焦点管理 / 对比度 / aria 要求：见 `quality/a11y-principles`
+- 自动化扫描门槛：{按平台填}
+
+## 3. 安全基线
+
+- 鉴权机制：{token / session / OAuth / ...}
+- 权限校验：前端 UI 层 + **后端最终校验**
+- CVE 响应时限：{高危 24h / 中危当迭代 / 低危排期}
+- 依赖许可证：{白名单，默认禁 GPL / AGPL}
+- 详细规范：见 [`quality/security-owasp`](../../quality/security-owasp/SKILL.md)
+
+## 4. 国际化基线
+
+- 语言清单：{按项目填}（第一个为基线）
+- 入口：唯一 `{{config.i18n.entry}}`
+- Key 命名空间：`{{config.i18n.namespace}}.<module>.<leaf_key>`
+- Fallback：必填，等于基线语言文案
+- ICU：复数 / 选择场景必须用
+- 详细规范：见 [`frontend/i18n`](../../frontend/i18n/SKILL.md)（前端）
+
+## 5. 兼容性基线
+
+### 运行环境矩阵
+| 平台 / 浏览器 | 最低版本 | 优先级 |
+| --- | --- | --- |
+
+### 响应式断点 / 设备尺寸（若适用）
+| 断点 | 最小宽度 | 布局策略 |
+| --- | --- | --- |
+
+## 6. 可观测性基线
+
+- 错误上报：所有未捕获异常 + 关键业务错误
+- 性能上报：关键指标持续采样
+- 关键交互埋点：{按场景列}
+- 脱敏：上报前过滤敏感字段
+- trace ID：请求响应含 trace ID，便于与后端关联
+
+## 7. 可靠性基线
+
+- 超时策略：默认请求超时 {N}s
+- 重试：读接口自动重试 N 次（指数退避）；写接口不自动重试
+- 错误边界：每个模块入口有错误边界（前端等效机制）
+- 降级 UI：关键页面有兜底（loading / error / empty 三态）
+- 回滚：每次发布有回滚预案（见 [`quality/release`](../../quality/release/SKILL.md)）
+```
+
+## 偏离声明规则
+
+模块 `spec.md` 中如需偏离基线，必须在 NFR 章节写：
+
+```md
+## NFR（继承 system/nfr-baseline.md）
+
+### 偏离项
+| 维度 | 基线 | 本模块 | 理由 |
+| --- | --- | --- | --- |
+| 首屏 | < 2.5s | < 1.5s | 核心交互路径，加严 |
+| 响应式 | Tablet+ | Desktop only | 管理后台场景 |
+```
+
+## 与其他 skill 的关系
+
+| 本文件章节 | 详细规范落地 |
+| --- | --- |
+| 性能基线（Web） | [`frontend/performance-web`](../../frontend/performance-web/SKILL.md) + [`frontend/nfr-web`](../../frontend/nfr-web/SKILL.md) |
+| 可访问性基线 | [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md) + [`frontend/a11y-web`](../../frontend/a11y-web/SKILL.md)（Web） |
+| 安全基线 | [`quality/security-owasp`](../../quality/security-owasp/SKILL.md) + [`frontend/security-web`](../../frontend/security-web/SKILL.md)（Web） |
+| 国际化基线 | [`frontend/i18n`](../../frontend/i18n/SKILL.md) |
+| 兼容性基线（Web 浏览器矩阵） | [`frontend/nfr-web`](../../frontend/nfr-web/SKILL.md) |
+| 可靠性基线 | [`quality/release`](../../quality/release/SKILL.md) + `sdlc/design` |
+
+## 修订规则
+
+- 基线变更必须通过 ADR
+- 新增维度 → 新增 ADR + 更新本文件 + 同步分领域规范
+- 收紧基线 → 评估存量偏离，逐步收敛
+- 放宽基线 → 必须有强业务理由
+
+## 质量门禁
+
+- [ ] 七大维度基线全覆盖
+- [ ] 每条基线有度量方式
+- [ ] 偏离声明规则清晰
+- [ ] 与分领域规范交叉一致
+- [ ] 变更走 ADR

package/system/project-constraints-template/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: zsk:project-constraints-template
+description: Project constraints template for new-project bootstrap — captures
+  import origins, forbidden libraries/patterns, required wrappers, naming
+  conventions, quality gates, branch/release conventions in one SYSTEM-SPEC
+  chapter. The project-side constitutional constraint table, complementary to
+  project-config.yaml (mechanical values).
+category: resource
+domain: system
+tier: optional
+related:
+  - ../adr/SKILL.md
+  - ../nfr-baseline/SKILL.md
+  - ../../meta/philosophy/SKILL.md
+triggers:
+  - project constraints
+  - SYSTEM-SPEC
+  - import origins
+  - forbidden packages
+  - red lines
+  - project initialization
+---
+
+# Project Constraints Template（项目约束速查表模板）
+
+> **定位**：任何新项目启动时，拷贝本模板到项目根（例如 `SYSTEM-SPEC.md` 的"项目约束"章节，或单独文件 `PROJECT-CONSTRAINTS.md`），填入本项目的实际值。
+> **为什么需要**：zsk skill set 提供**项目无关**的方法论模板；本文件是**项目侧**的"宪法级约束"单一事实源，让 AI / 人在 coding 阶段一眼看完本项目的硬约束。
+> **优先级**：本模板填完后 > 通用 zsk skills；与项目 `SYSTEM-SPEC.md` 是同一层。
+> **维护**：所有约束变动必须通过 ADR（见 [`zsk:adr`](../adr/SKILL.md)）。
+
+## 何时用
+
+- **新项目初始化**：拷贝本模板，填入实际值，作为 `SYSTEM-SPEC.md` 的一章或独立 `PROJECT-CONSTRAINTS.md`
+- **现有项目补齐**：如果项目还没显式写 Import Origins 表，就补一次
+- **技术栈变更**：升级前后各更新一次
+
+## 模板（复制并填写）
+
+```md
+# 项目约束速查表 — {{项目名}}
+
+> 版本：{{YYYY-MM-DD}}
+> 维护人：{{姓名}}
+> 关联 ADR：{{ADR 列表}}
+> 优先级：本文件 > `docs/.best-practices/*` 通用模板
+
+## 1. 框架与构建
+
+| 维度 | 选型 | 版本锁 | ADR |
+| --- | --- | --- | --- |
+| 框架 | {{React / Vue / Svelte / ...}} | {{版本范围}} | {{ADR-XXXX}} |
+| 语言 | {{TypeScript / JavaScript}} | {{版本}} | — |
+| 构建 | {{Webpack / Vite / Rspack / ...}} | {{版本}} | {{ADR-XXXX}} |
+| 样式 | {{Less / Sass / CSS Modules / Tailwind / ...}} | {{版本}} | {{ADR-XXXX}} |
+| 样式命名 | {{BEM / Atomic / Utility-first}} | — | — |
+
+## 2. Import 起源（强约束）
+
+> 这是 coding 阶段的**硬约束**。违反会被 Reviewing / Verify 阻断。
+
+| 能力 | 必须从这里引入 | 禁止从这里引入 | 示例 |
+| --- | --- | --- | --- |
+| **UI 组件** | `{{项目 UI 库包名}}` | 其他 UI 库 | `import { Button } from '{{UI 库}}';` |
+| **i18n** | `{{项目 i18n 入口}}` | 第三方 i18n 库直接调用 | `import { t } from '{{i18n 入口}}';` |
+| **HTTP 客户端** | `{{项目 HTTP 入口}}` | `fetch` / `axios` 裸调 | `import { request } from '{{HTTP 入口}}';` |
+| **路由** | `{{路由库包名}}` | 其他路由库 | `import { Route } from '{{路由库}}';` |
+| **状态管理（异步）** | `{{TanStack Query / SWR / ...}}` | Redux / MobX / 自研 | — |
+| **状态管理（共享）** | `{{Jotai / Zustand / Context / ...}}` | Redux / 自研 | — |
+| **图标** | `{{项目图标库}}` | 自己手绘 SVG 放 `src/` | — |
+| **工具函数** | `{{项目 utils 目录}}` | 第三方 lodash 等逐个引 | — |
+| **Services** | `{{services_entry}}` | 新建 request 实例 | — |
+
+## 3. 必用封装（强约束）
+
+> 以下场景必须走项目封装，不得绕过。
+
+| 场景 | 必用封装 | 理由 |
+| --- | --- | --- |
+| HTTP 请求 | `{{封装函数名}}` | 统一拦截 / 超时 / 鉴权 / 错误码归一化 |
+| 表单校验 | `{{校验 schema 工具}}` | 统一错误文案 + 国际化 |
+| 日期 / 数字格式 | `{{Intl 封装 / moment 封装}}` | 统一时区 / 精度 / 本地化 |
+| 日志上报 | `{{上报 SDK}}` | 脱敏 / 采样 / 关联 traceId |
+| 错误边界 | `{{项目 ErrorBoundary}}` | 统一错误 UI + 上报 |
+| 权限判断 | `{{权限 Hook / util}}` | 前端防误操作 + 后端最终校验 |
+
+## 4. 禁用清单（Red Lines）
+
+### 禁用的包 / 库
+
+| 包名 | 禁用原因 | 替代 | ADR |
+| --- | --- | --- | --- |
+| {{如 Redux}} | {{学习成本 / 与 TanStack 冲突}} | {{Jotai + TanStack Query}} | {{ADR-XXXX}} |
+
+### 禁用的语法 / 模式
+
+| 模式 | 禁用原因 | 替代 |
+| --- | --- | --- |
+| `any` / `as any` 双层断言 | 类型安全 | 具体类型 / unknown + 收窄 |
+| `@ts-ignore` / `@ts-nocheck` | 绕过类型检查 | 修真正的类型问题 |
+| `dangerouslySetInnerHTML` | XSS 风险 | 文本节点 / 经审 HTML 库 |
+| `eval` / `new Function` | 安全风险 | 逻辑重构 |
+| 硬编码中文 / 英文文案 | i18n 违规 | `{{i18n 函数}}('key', fallback)` |
+| 裸 `fetch` / `axios` | 绕过统一拦截 | 项目 HTTP 入口 |
+| 新建 request 实例 | 请求散落 | 复用 `{{services_entry}}` |
+| 直接在组件里 `console.log` | 生产泄漏 | 封装的 logger（可按环境关） |
+| `<img>` 无 `width/height` | CLS 风险 | 必须声明尺寸 |
+
+## 5. 目录与命名
+
+| 对象 | 规范 | 说明 |
+| --- | --- | --- |
+| 组件目录 | {{components_root}} | kebab-case 目录 + `index.tsx` |
+| 服务入口 | {{services_entry}} | 单一出口，按域划分 |
+| i18n 入口 | {{i18n_entry}} | 统一 `t()` 出口 |
+| hooks | {{hooks_root}} | 跨模块复用放这里 |
+| 模块文档 | `docs/{module}/` | 一个业务模块一个目录 |
+| 静态资源 | {{static_assets_path}} | 图片 / 字体 / 其他 |
+
+### 命名规则
+
+| 对象 | 规范 | 示例 |
+| --- | --- | --- |
+| React 组件 | PascalCase | `FeatureList` |
+| 文件（非组件） | kebab-case | `feature-utils.ts` |
+| 变量 / 函数 | camelCase | `featureList` |
+| 常量（模块级） | UPPER_SNAKE_CASE | `MAX_DEPTH` |
+| 类型 / 接口 | PascalCase | `FeatureNode` |
+| Hook | `use` 前缀 | `useFeatureQuery` |
+| 布尔 | `is` / `has` / `can` / `should` 前缀 | `isLoading` |
+| 事件 Handler | `handle` 前缀 | `handleSelect` |
+| 事件 Props | `on` 前缀 | `onSelect` |
+
+## 6. 国际化约束
+
+| 项 | 本项目要求 |
+| --- | --- |
+| 语言清单 | {{如 zh_CN / en / zh_TW}}（基线为 {{首个语言}}） |
+| 入口 | {{i18n_entry}} 的 `t()` |
+| Key 命名空间 | `{{项目命名空间}}.<module>.<leaf_key>`（例：`app.featureList.empty`） |
+| Fallback | 必填，等于基线语言文案 |
+| 同步要求 | 新增 key 必须同 commit 同步所有语言文件 |
+| 评审门禁 | 缺一语 / 缺 fallback / 硬编码文案 → 打回 |
+
+## 7. 质量门禁（本项目具体值）
+
+| 门禁 | 本项目命令 | 基线 |
+| --- | --- | --- |
+| lint | `{{lint 命令}}` | 零 error |
+| type-check | `{{type-check 命令}}` | 零 error |
+| unit test | `{{test 命令}}` | 覆盖率 ≥ {{N}}% |
+| build | `{{build 命令}}` | 成功 |
+| Lighthouse Performance | CI 跑 | ≥ {{分数}} |
+| axe-core | CI 跑 | 零 critical/serious |
+| 包体积（单 chunk） | Bundle Analyzer | ≤ {{KB}}KB（gzip） |
+| 依赖许可证 | 自动扫描 | 不含 {{禁用清单，如 GPL/AGPL}} |
+
+## 8. 分支与发布
+
+| 项 | 本项目约定 |
+| --- | --- |
+| 主干分支 | `{{main/test/master}}` |
+| Feature 分支 | `{{feature/{scope}}}` |
+| Fix 分支 | `{{fix/{id}}}` |
+| Refactor 分支 | `{{refactor/{scope}}}` |
+| Commit 规范 | Conventional Commits |
+| 版本策略 | SemVer（`major.minor.patch`） |
+| Changelog | Keep a Changelog |
+| 部署流水线 | {{Jenkins / GitHub Actions / ...}} |
+
+## 9. 环境矩阵
+
+| 环境 | 域名 / URL | 用途 |
+| --- | --- | --- |
+| dev | {{域名}} | 本地 / 开发分支 |
+| test | {{域名}} | 集成测试 |
+| pre | {{域名}} | UAT / 预发 |
+| prod | {{域名}} | 生产 |
+
+## 10. ADR 索引（本项目决策）
+
+| ADR | 决策 | 状态 |
+| --- | --- | --- |
+| {{ADR-0001}} | {{决策名}} | Accepted |
+| {{ADR-0002}} | {{决策名}} | Accepted |
+
+完整列表 → `docs/system/adrs/`。
+```
+
+## 填表指南
+
+### 第 1 步：对照 `_config/project-config.template.md`
+
+先把 `_config/project-config.template.md` 拷贝到仓库根 `project-config.md`，填入 frontmatter 所有 `<fill-me>` 值 + 正文叙述。本模板中的 `{{...}}` 会从 frontmatter 取值。
+
+### 第 2 步：逐节填写
+
+按"1. 框架 → 2. Import 起源 → ..."顺序填。没有的列留空或写"本项目不涉及"。
+
+### 第 3 步：加入 SYSTEM-SPEC 或单独成文
+
+推荐放入 `SYSTEM-SPEC.md` 作为"项目约束速查表"章节。也可独立为 `PROJECT-CONSTRAINTS.md` 文件，通过 `SYSTEM-SPEC.md` 引用。
+
+### 第 4 步：约束所有 ADR
+
+每条 Import 起源 / 必用封装 / 禁用项，**最好**都有对应 ADR（Context / Decision / Rationale / Alternatives / Consequences）。
+
+## 与通用 best-practices 的边界
+
+| 这里（项目约束速查表） | 通用 `docs/.best-practices/` |
+| --- | --- |
+| **本项目必须这样做** | **一般做法可以这样** |
+| 冲突时**胜出** | 冲突时**让步** |
+| 每个项目值不同 | 跨项目复用 |
+| 有 ADR 追溯 | 无 ADR（方法论本身） |
+
+## 反模式（禁止）
+
+- ❌ 把项目约束写进 `docs/.best-practices/`（会污染通用模板）
+- ❌ 约束无 ADR 支持（无法追溯"为什么选这个"）
+- ❌ Import 起源只写"推荐"不写"必用 / 禁用"（约束不够硬）
+- ❌ 约束定下后不更新（老约束对不上新代码）
+
+## 当约束变更
+
+1. 写新 ADR（status = Proposed）
+2. 团队评审
+3. 通过后 → ADR status = Accepted
+4. 更新本表对应行
+5. 更新 `CHANGELOG.md`
+6. 如有代码需迁移 → 列入下一轮 proposal
+
+## 扩展：自动化约束
+
+可选的工具链集成：
+
+- **ESLint `no-restricted-imports`**：把"禁用的包 / 路径"落到 lint 规则
+- **dependency-cruiser**：检查跨层依赖
+- **`.npmrc` / `.yarnrc`**：锁定包源 / 版本策略
+- **pre-commit hook**：检查 i18n 三文件同步、硬编码文案
+
+本模板只定**约束是什么**，执行 / 自动化在项目 CI 配置里。