# 黄金样板对标指引与占位符约定

本文件是生成 `.claude/rules/*.md` 时的**质量基准**与**占位符词典**。step-03 生成任一维度文件前，应先回顾本文件，确保产出与黄金样板「同构、同质」。

---

## 一、黄金样板位置

`{project-root}/.claude/rules/`（即本 skill 安装服务的 rules 目录，pj-incentive）是经人工沉淀的 13 个成品级 rules，是所有维度文件的**目标形态**。

- 通用维度样板：`java-backend.md`、`security.md`、`api-design.md`、`database-oracle.md`、`database-mysql.md`、`gateway.md`、`frontend-vue.md`、`frontend-js.md`、`frontend-css-html.md`
- 特定维度样板：`xxl-job.md`、`file-import-export.md`、`async-export.md`
- 总纲样板：`CLAUDE.md`

> 注意：黄金样板里出现的具体服务标识（`zqyl-pj-incentive`、`com.yljr`、`票据对接费用`、Handler 类名等）是 pj-incentive 专有的。复用到新服务时，**通用维度**用占位符参数化后注入新服务真值；**特定维度**必须用新服务的真实扫描结果替换，**严禁照抄 pj-incentive 的类名清单**。

---

## 二、每个维度文件的目标形态（统一结构）

无论通用还是特定，正文都遵循这套骨架，与黄金样板保持一致：

1. `# {维度标题}` 一级标题
2. 若干 `## {小节}`：规约条目（短句、可执行、含 ❌→✅ 倾向）
3. **代码模板块**（```java / ```vue / ```javascript）：给出可直接套用的范式
4. **「已有基础设施清单」表**（仅特定维度）：列出本服务真实存在的类/组件/Handler
5. `## 新增 XXX Checklist`：勾选式清单
6. `## 常见错误模式`：`❌ ... → ✅ ...` 对照

**篇幅基准**：通用维度 80-200 行；特定维度 200-400 行（含真实清单表与代码模板）。

---

## 三、frontmatter 规则（与黄金样板完全一致）

- **通用维度**：文件首部必须有 YAML frontmatter，**仅一个字段 `globs`**，值为字符串数组，`---` 包裹。示例：
  ```
  ---
  globs: ["**/*.java"]
  ---
  ```
- **特定维度**：**无 frontmatter**，直接以 `# 标题` 开头。在标题下方用一句话注明触发场景（如「> 新增定时任务、修改 Job Handler 时主动加载本规范」），靠总纲 `CLAUDE.md` 的索引表声明「按需加载」。

---

## 四、占位符约定（词典）

占位符分两套，均区别于 step 文件的 `{skill-root}` 路径变量：
- **后端通用维度**用双花括号 `{{大写下划线}}`（由 step-02/step-04 据 detect-stack 探测真值注入，见下表）。
- **前端维度**用单花括号小驼峰 `{feModule}`/`get{FeModule}Status`/`{feModule}.js`（**无 detect-stack 自动来源**，靠扫前端代码或人工替换，见替换原则末条）。

| 占位符 | 含义 | pj-incentive 实参（示例） | 探测来源 |
|--------|------|--------------------------|----------|
| `{{SERVICE_NAME}}` | 服务工件名 | `zqyl-pj-incentive` | pom.xml `<artifactId>` |
| `{{API_CONTEXT}}` | 对外 API 上下文路径（`-api` 结尾） | `zqyl-pj-incentive-api` | bootstrap/网关配置或 `{{SERVICE_NAME}}-api` |
| `{{BASE_PACKAGE}}` | 基础包名 | `com.yljr` | `src/main/java` 下顶层包 |
| `{{MODULE_CN}}` | 模块中文名 | `票据对接费用` | 需求文档/CLAUDE.md，缺失则留占位并报告 |
| `{{NACOS_GROUP}}` | Nacos 配置分组 | `ZQYL_PJ_INCENTIVE_GROUP` | bootstrap.properties |
| `{{ORACLE_VERSION}}` | Oracle 版本 | `11.2.0.4` | 配置/依赖，缺失填团队默认并报告 |
| `{{MAIN_CLASS}}` | 启动类全名 | `com.yljr.StartApplication` | `@SpringBootApplication` 所在类 |
| `{{SERVER_PORT}}` | 服务端口 | `8133` | application*.properties |

**替换原则**：
- 探测到真值 → 直接替换。
- 探测不到 → 保留占位符原样写入，并在对标报告「需人工补充」列出该占位符与所在文件。
- 占位符**只用于通用维度 baselines**；特定维度的真实信息靠 `extraction-recipes.md` 的扫码配方填充，不用占位符。
- **CLAUDE.md 总纲专用占位符**（`{{TECH_LANGUAGE}}`/`{{TECH_FRAMEWORK}}`/`{{TECH_DATABASE}}`/`{{TECH_MIDDLEWARE}}`、`{{INDEX_TABLE}}`、`{{MAIN_CLASS}}`）不在上表、不用于 baselines，由 **step-04** 据 detect-stack 的 `signals`/`pomDeps`/`springBootClass` 填充（映射见 step-04）。
- **前端占位（单花括号，独立一套）**：`{feModule}`（前端 Vuex 模块名）/`get{FeModule}Status`（枚举 getter）/`{feModule}.js`（前端接口文件），用于 `frontend-vue.md` baseline 与 `async-export.md`/`file-import-export.md` 的前端引用。**无 detect-stack 自动来源**——前端维度命中时扫本服务前端代码（Vuex 模块/接口文件）确定真值替换；扫不到、或本服务无前端（未命中前端维度）则保留占位并在报告「需人工补充」登记。step-03 自检须确认不残留 `{feModule}`/`{FeModule}`。

---

## 五、写作语气（对齐 skill-creator 与黄金样板）

- 用简体中文，祈使句，短条目。
- 解释「为什么」而非堆砌 MUST（黄金样板即如此）。
- 代码示例优先给「✅ 正确 / ❌ 禁止」对照，便于 LLM 对齐。
- 不臆造规约：通用维度只搬黄金样板既有条文；特定维度只写扫码确证的事实，无实例时明确标注「团队规范模板，本服务暂无实例」。