@wneng/create-keel 0.2.1 → 0.3.2

package/src/standards/templates/tech-stack-web.md.eta

@@ -0,0 +1,36 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 前端 / Web 技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **审计可追溯**：升级历史进 git，PR review 看得到
+- **可重现构建**：CI cache 一致；六个月后能装出同一棵 lockfile
+
+## policy 三档
+
+policy 字段的语义、调整流程、不钉的例外，与 [tech-stack-server.md](tech-stack-server.md) 一致。本文件不重复。
+
+## Web 特有的考虑
+
+- React / Vue 的 minor 升级常带 hooks API 改动；新增 `policy: minor` 表示"先发 warning，看到再合"
+- `typescript` 单独列为 minor：tsc 主版本变化几乎一定要改代码
+- bundler（Vite / Webpack）和 polyfill 工具链版本若进 production bundle，必须钉；纯 dev 工具不进本表
+
+## 关联
+
+- 编码规范：[coding-style-typescript.md](coding-style-typescript.md)
+- UI 设计系统：[../05-前端客户端详细设计/ui-design-system.md](../05-前端客户端详细设计/ui-design-system.md)（启用 design 角色或 full 档时存在）
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/ui-design-system.md.eta

@@ -0,0 +1,70 @@
+# UI 设计系统
+
+> 这是 UI / 视觉真值的入口。设计稿仍在 Figma；本文件 + `web/src/design-tokens.ts` 是工程侧能消费的版本。
+>
+> governance-lint 的 `GOV.UI.TOKEN_DRIFT` 检查会比对本文件 token 表与 `design-tokens.ts` 的 export 名集合，发现差异即阻断。
+
+## Token 表
+
+下面三类 token 是 design-tokens.ts 的真值；改一项，必须同 PR 改 ts 文件中对应 export。
+
+### 颜色
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `colorPrimary` | `#2563EB` | 主操作按钮、链接 |
+| `colorSurface` | `#FFFFFF` | 卡片 / 模态背景 |
+| `colorTextDefault` | `#0F172A` | 默认文本 |
+| `colorTextMuted` | `#64748B` | 次要 / 辅助文本 |
+| `colorBorder` | `#E2E8F0` | 分隔线 / 输入框边框 |
+| `colorDanger` | `#DC2626` | 错误状态、危险操作 |
+
+### 间距（spacing scale）
+
+按 4px 基线倍数；**禁止**使用任意像素值。
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `space1` | `4px` | 紧凑（图标到文字） |
+| `space2` | `8px` | 表单字段内 |
+| `space3` | `12px` | 默认内边距 |
+| `space4` | `16px` | 卡片内边距 |
+| `space6` | `24px` | 卡片间距 |
+| `space8` | `32px` | 区块间距 |
+
+### 字号（typography）
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `fontHeading1` | `32px / 1.25 / 600` | 页面 H1 |
+| `fontHeading2` | `24px / 1.3 / 600` | 区块标题 |
+| `fontBody` | `14px / 1.5 / 400` | 正文 |
+| `fontCaption` | `12px / 1.4 / 400` | 辅助说明 |
+
+## 组件命名
+
+组件库统一前缀，避免与第三方库冲突：
+
+- `KButton` —— 主按钮 / 次按钮 / 危险按钮三态由 prop 切换
+- `KModal` —— 模态对话框；标题 / 内容 / footer 三槽位
+- `KFormItem` —— 表单单项；label + 控件 + 错误提示
+
+新增组件命名遵循同前缀；超过组件库范围（业务组件）走 PascalCase 不加前缀。
+
+## 调整流程
+
+1. 设计在 Figma 改 token；导出 SVG / PNG 到 `docs/design/figma-exports/`
+2. 同 PR 改本文件 token 表 + `web/src/design-tokens.ts` 中对应 export
+3. CI 跑 `governance-lint`：本表 token 名集合必须等于 design-tokens.ts 的 export 集合
+4. 若故意要让两边不同（极少见），删除本文件，改用其他 token 真值（需要新 ADR）
+
+## 何时**不**用本系统
+
+- 第三方组件库自带的 token：直接用；不要 wrap 一层把它们重命名成 K 前缀
+- 一次性的展示页（活动 banner、营销页）：可以脱离本系统，但不要把脱离的 token 散播到通用组件中
+
+## 关联
+
+- 配色无障碍要求：所有 `colorText*` 与对应 `colorSurface*` 的对比度必须 ≥ 4.5:1（WCAG AA）
+- 设计稿源：`docs/design/figma-exports/`
+- 二进制 Figma 源文件：走 LFS（见 [`docs/governance/assets.md`](../governance/assets.md)）

package/src/templates/ci-gitee/files/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+# Pull Request
+
+> 来自 keel scaffolder（@wneng/create-keel <%= it.scaffolderVersion %>）
+> 完整规则见 [`docs/governance/git-workflow.md`](../docs/governance/git-workflow.md)
+
+## 概述（What & Why）
+
+<!-- 一句话讲清楚这个 PR 改了什么、为什么 -->
+
+## 关联引用
+
+<!-- 至少填一项；契约 / 设计 / spec 三选一 -->
+
+- 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
+- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- spec：`.kiro/specs/<feature>/`（如适用）
+
+## 变更类型
+
+- [ ] feat — 新增能力
+- [ ] fix — 缺陷修复
+- [ ] docs — 文档变更
+- [ ] refactor — 重构（无行为变化）
+- [ ] chore — 维护性变更
+- [ ] spike — 临时探索（必须在合入前补齐契约 / 文档）
+
+## 自检清单（Pre-merge）
+
+完整 checklist 见 [`docs/governance/checklists.md`](../docs/governance/checklists.md)。最常踩的 5 个坑：
+
+- [ ] 改了 `contracts/` → `contracts/CHANGELOG.md` 已同步更新
+- [ ] 触了 on-demand 目录 → 用户已说出 trigger keyword（"更新部署手册" / "更新合规证据" / "更新宣发" / "更新设计稿"）
+- [ ] **未**直接写 `docs/11-市场与对外材料/published/` 或 `docs/10-合规与安全/evidence/`（read-only）
+- [ ] AI 生成代码 → commit 用 `feat(ai): ...` / `chore(ai): ...` 前缀；PR 打 `ai-generated` 标签
+- [ ] 改了 `docs/governance/<file>.md` → AGENTS.md §7 对应摘要已同步
+
+## CI
+
+- [ ] 本地 `npm test` / `mvn test` / `pytest` 等已通过
+- [ ] `governance-lint` 本地通过：`node tools/governance-lint/index.js --strict`
+- [ ] 没有提交 secret / 私钥 / 真实 PII
+
+## 影响范围
+
+<!-- 列出受影响的执行环境 / 模块 / 服务 -->
+
+- [ ] `server/`（后端）
+- [ ] `web/`（前端）
+- [ ] `mobile/`（移动端）
+- [ ] `miniapp/`（小程序）
+- [ ] `agent/`（桌面 / CLI）
+- [ ] `contracts/`（契约）
+- [ ] `deploy/` / `ops/`（部署 / 基础设施）
+- [ ] 仅 docs
+
+## 回滚预案
+
+<!-- 如果合入后发现问题，怎么回滚？哪些数据 / 配置需要清理？ -->
+
+## 备注 / 截图
+
+<!-- 可选 -->

package/src/templates/ci-gitee/fragment.yaml

@@ -1,5 +1,5 @@
 name: ci-gitee
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   ci: gitee
 priority: 20
@@ -7,3 +7,6 @@ files:
   - from: files/pipeline.yml
     to: .gitee/pipelines/ci.yml
     render: true
+  - from: files/PULL_REQUEST_TEMPLATE.md
+    to: .gitee/PULL_REQUEST_TEMPLATE.md
+    render: true

package/src/templates/ci-github/files/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+# Pull Request
+
+> 来自 keel scaffolder（@wneng/create-keel <%= it.scaffolderVersion %>）
+> 完整规则见 [`docs/governance/git-workflow.md`](../docs/governance/git-workflow.md)
+
+## 概述（What & Why）
+
+<!-- 一句话讲清楚这个 PR 改了什么、为什么 -->
+
+## 关联引用
+
+<!-- 至少填一项；契约 / 设计 / spec 三选一 -->
+
+- 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
+- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- spec：`.kiro/specs/<feature>/`（如适用）
+
+## 变更类型
+
+- [ ] feat — 新增能力
+- [ ] fix — 缺陷修复
+- [ ] docs — 文档变更
+- [ ] refactor — 重构（无行为变化）
+- [ ] chore — 维护性变更
+- [ ] spike — 临时探索（必须在合入前补齐契约 / 文档）
+
+## 自检清单（Pre-merge）
+
+完整 checklist 见 [`docs/governance/checklists.md`](../docs/governance/checklists.md)。最常踩的 5 个坑：
+
+- [ ] 改了 `contracts/` → `contracts/CHANGELOG.md` 已同步更新
+- [ ] 触了 on-demand 目录 → 用户已说出 trigger keyword（"更新部署手册" / "更新合规证据" / "更新宣发" / "更新设计稿"）
+- [ ] **未**直接写 `docs/11-市场与对外材料/published/` 或 `docs/10-合规与安全/evidence/`（read-only）
+- [ ] AI 生成代码 → commit 用 `feat(ai): ...` / `chore(ai): ...` 前缀；PR 打 `ai-generated` 标签
+- [ ] 改了 `docs/governance/<file>.md` → AGENTS.md §7 对应摘要已同步
+
+## CI
+
+- [ ] 本地 `npm test` / `mvn test` / `pytest` 等已通过
+- [ ] `governance-lint` 本地通过：`node tools/governance-lint/index.js --strict`
+- [ ] 没有提交 secret / 私钥 / 真实 PII
+
+## 影响范围
+
+<!-- 列出受影响的执行环境 / 模块 / 服务 -->
+
+- [ ] `server/`（后端）
+- [ ] `web/`（前端）
+- [ ] `mobile/`（移动端）
+- [ ] `miniapp/`（小程序）
+- [ ] `agent/`（桌面 / CLI）
+- [ ] `contracts/`（契约）
+- [ ] `deploy/` / `ops/`（部署 / 基础设施）
+- [ ] 仅 docs
+
+## 回滚预案
+
+<!-- 如果合入后发现问题，怎么回滚？哪些数据 / 配置需要清理？ -->
+
+## 备注 / 截图
+
+<!-- 可选 -->

package/src/templates/ci-github/fragment.yaml

@@ -1,5 +1,5 @@
 name: ci-github
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   ci: github
 priority: 20
@@ -7,3 +7,6 @@ files:
   - from: files/ci.yml
     to: .github/workflows/ci.yml
     render: true
+  - from: files/PULL_REQUEST_TEMPLATE.md
+    to: .github/PULL_REQUEST_TEMPLATE.md
+    render: true

package/src/templates/docs-skeleton/files/README.md

@@ -66,7 +66,7 @@ docs/
 | `governance/` | 11 个固定文件名 | ADR-0001 + governance-lint |
 | `assets/` | `diagrams/` + `images/` + `design/` | [`governance/assets.md`](governance/assets.md) 引用约定 |
 | `references/` | `standards/` + `vendors/` + `legal/` | [`governance/docs-references.md`](governance/docs-references.md) 元数据规则 |
-| `过程文档/` | `drafts/` + `meeting-notes/` + `spike-investigations/` + 三份索引 | AGENTS.md §5 |
+| `过程文档/` | `drafts/` + `meeting-notes/` + `spike-investigations/` | AGENTS.md §5 |
 
 ### 5.2 软建议（按项目实际调整）
 
@@ -125,10 +125,10 @@ warning 不是 error——允许"有 PRD 但还没开始设计"的过渡状态
 
 `docs/governance/` 承载从 AGENTS.md 拆出的专项规则（CI、安全、Git、资产、集成、ops/deploy、tools/scripts、checklist 等）。索引见 [`governance/README.md`](governance/README.md)。
 
-<% if (it.options.integrations) { %>## 7. 集成对接入口
+<% if (it.options.integrations) { %>## 8. 集成对接入口
 
 `docs/06-集成对接/` 已通过 `integrations=true` 启用。完整规则见 [`governance/integrations.md`](governance/integrations.md)。
-<% } else { %>## 7. 集成对接
+<% } else { %>## 8. 集成对接
 
 本仓库未启用 `integrations`。如果未来需要与外部仓库 / 团队对接（例如本仓库只做后端，前端在另一仓库），手动建立 `docs/06-集成对接/` 并参考 [`governance/integrations.md`](governance/integrations.md)。
 <% } %>

package/src/templates/docs-skeleton/files/governance-checklists.md

@@ -4,7 +4,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 # 完整检查清单
 
-> 入口摘要在 `AGENTS.md` §13。本文件提供完整可勾选清单。
+> 入口摘要在 `AGENTS.md` §9。本文件提供完整可勾选清单。
 
 ## 1. 开发前核对（功能开发启动前）
 
@@ -19,7 +19,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 ## 2. 提交前核对（PR 发起前）
 
 - [ ] `contracts/CHANGELOG.md` 已同步更新
-- [ ] 破坏性变更已按 §6 升级 MAJOR
+- [ ] 破坏性变更已按 [`contracts/README.md`](../../contracts/README.md) 的 SemVer 规则升级 MAJOR
 - [ ] 生成代码已重新生成且 `git diff` 为空
 - [ ] `docs/README.md` 已按需同步（目录地图 / 分类入口 / 子目录约定）
 - [ ] 若启用 `integrations` 且契约变更影响某 pair，该 pair 已同步
@@ -48,7 +48,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 ## 5. 新增脚本 / 工具核对
 
-- [ ] 已按 §12.3 判定归属（`scripts/` 或 `tools/`）
+- [ ] 已按 [`tools-scripts.md`](tools-scripts.md) 判定归属（`scripts/` 或 `tools/`）
 - [ ] `scripts/` 脚本顶部注释包含用途、参数、幂等性、危险级别
 - [ ] `scripts/README.md` 索引已更新
 - [ ] `tools/` 工具含独立 `README.md` 与版本号

package/src/templates/docs-skeleton/files/governance-security.md

@@ -10,8 +10,12 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 ### 1.1 版本管理
 
-- 新增依赖使用**精确版本**（pinned），禁止开放范围
-- `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` / `pom.xml` 都遵循同一原则
+- **建议**新增依赖使用精确版本（pinned），尤其是安全敏感库（加密、token、SSO）
+- 实操中允许两种策略：
+  - **lockfile-based**（默认）：`package.json` 用 `^` 范围 + 提交 `package-lock.json` / `yarn.lock`，CI 跑 `npm ci`（严格按 lockfile）。Node / npm 生态的事实标准
+  - **fully-pinned**：`package.json` 用 `=` 精确版本。安全敏感项目或需要 SBOM 严格匹配时使用
+- 真值：lockfile（不是 `package.json`）。`package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` 必须提交
+- 工程规范的 `tech-stack-<env>.md` 钉死表 + `governance-lint stack-pinning` 是更细粒度的版本守门（参见 ADR-0004）
 - 升级依赖独立 PR，便于回滚
 
 ### 1.2 漏洞扫描

package/src/templates/docs-skeleton/files/usage-quickstart.md

@@ -35,9 +35,20 @@ npx @wneng/create-keel create my-full \
   --agent rust-desktop --deploy kubernetes --contract rest+events \
   --ai kiro --license apache-2.0 --gitLfs --integrations \
   --ci github --roles qa,field,data,legal-security,marketing,design \
+  --engineering-standards full \
   --yes
 ```
 
+### 0.1.1 工程规范是另一个正交维度
+
+档位决定 *目录与角色* 的启用范围；`--engineering-standards <tier>` 决定 *栈版本钉死、编码风格、模块边界、UI 设计系统* 的生成范围：
+
+| `--engineering-standards` | 启用 | 默认 |
+|---|---|---|
+| `lite` | 仅每语言 `coding-style-<lang>.md` + 对应 lint 配置 | —— |
+| `standard` | + `tech-stack-<env>.md` + `module-boundaries.md` + （multi-app + JS/TS）`dependency-cruiser.config.cjs` | ✓ `--yes` 默认 |
+| `full` | + `ui-design-system.md` + `web/src/design-tokens.ts`（启用 frontend 时） | —— |
+
 **已有项目升档**：
 
 | 升档动作 | 操作 |

package/src/templates/root-files/files/CODEOWNERS

@@ -0,0 +1,40 @@
+# CODEOWNERS — review routing for <%= it.options.projectName %>
+#
+# Format: path-pattern  @owner1 @owner2
+# - Match order matters: later rules override earlier ones.
+# - Replace placeholder owners (`@TBD`) with real Git accounts before
+#   the first PR. CI rejects merging when CODEOWNERS still contains @TBD.
+#
+# References:
+# - AGENTS.md §3.1 (PR review obligations)
+# - docs/governance/git-workflow.md (PR template + CODEOWNERS rules)
+
+# Default owner for everything not matched below.
+*                                       @TBD
+
+# Architecture and contracts: high-impact paths require named reviewers.
+/AGENTS.md                              @TBD
+/contracts/                             @TBD
+/docs/02-系统方案与架构/                @TBD
+/docs/governance/                       @TBD
+
+# Per-execution-environment routing (placeholders; adjust per team).
+/server/                                @TBD
+/web/                                   @TBD
+<% if (it.options.mobile !== 'none') { %>/mobile/                                @TBD
+<% } %><% if (it.options.miniapp !== 'none') { %>/miniapp/                               @TBD
+<% } %><% if (it.options.agent !== 'none') { %>/agent/                                 @TBD
+<% } %>
+
+# Operations & deployment.
+/ops/                                   @TBD
+/deploy/                                @TBD
+
+# CI configuration.
+<% if (it.options.ci === 'github') { %>/.github/                               @TBD
+<% } else if (it.options.ci === 'gitee') { %>/.gitee/                                @TBD
+<% } %>
+
+# Tooling.
+/tools/                                 @TBD
+/scripts/                               @TBD

package/src/templates/root-files/fragment.yaml

@@ -18,3 +18,6 @@ files:
   - from: files/.editorconfig
     to: .editorconfig
     render: false
+  - from: files/CODEOWNERS
+    to: CODEOWNERS
+    render: true