# 概念层 (Concepts)

概念层是**名字层**：每个业务名词先以"名字 + 名词解释"存在，先于一切结构（表、页面、接口、旅程）。它是蓝图体系的根——所有跨层引用（journey / table / PageFlow / DTO）的身份都从概念出发。

## 认知顺序：名词在先，结构在后

```
名词（概念）：商户 —— 业务先说这个词，先解释它是什么
   ↓ 派生
词根（短语）：mer —— 为了字段名发明缩写
   ↓ 长出
结构：merchant 表 / 商户列表页 / 入驻旅程 —— 各维度引用"商户"
```

- **概念是本源**：业务人员嘴里只有"商户"，`mer` 是工程师后来为字段名发明的代号。
- **短语（词根）是派生**：概念引用短语，不是短语解释概念。
- **结构是生长**：表、页面、journey 都是概念"长出"的结构，各自引用概念名。

## 与词典（_dictionary.ts）的关系

| | 词典（dictionary） | 概念（concepts） |
|---|---|---|
| 单位 | 词根（mer / rate） | 完整名词（商户 / 银联报文） |
| 主键 | 短语本身 | 名词标识 |
| 内容 | 短语 + label + 描述 | 名词 + 经典段落解释 |
| 服务对象 | 字段命名校验（lint field） | 所有维度的引用身份 |
| 认知顺序 | 后于概念存在（缩写是派生的） | **先于一切存在** |

**两者并存，互不反转**：`_dictionary.ts` 维持现状（词根字典，服务字段命名）；`_concepts.ts` 是新的概念清单（服务跨层身份）。概念通过 `phrase` 字段引用词根，把"名词 → 缩写"的派生关系显式化。

## 规范位置：schema/_concepts.ts

**所有概念统一定义在 `schema/_concepts.ts`**，一个文件一处定义（与 `_dictionary.ts` 同规则）。`table.ts` / journey / PageFlow 引用概念，禁止内联。

## 定义形态

```ts
// schema/_concepts.ts
import { defineConcept } from '@pylonts/dsl';

export const merchant = defineConcept('merchant', {
  title: '商户',
  description: '入驻平台并签约收单的商家。由 BD 录入，平台审核，提交银联开通后获得登录资格，可登录商户端进行订单核销。',
  phrase: mer,                        // 引用词根（_dictionary.ts 的实体短语）
});

export const unionpayReport = defineConcept('unionpay-report', {
  title: '银联报文',
  description: '提交给银联的商户资料报文，银联审核后返回审核结果。',
});
```

- `name`：概念标识（kebab-case，跨层身份契约——journey / 表 / 页面都叫这个名字）。
- `title`：中文名。
- `description`：**经典段落**——一段话讲清楚"这是什么、干什么用的"，像文档术语表里的一条。
- `phrase?`：引用 `_dictionary.ts` 的词根条目（实体短语），表达"这个概念在字段命名里缩写为什么"。
- 一个概念可以还没有任何结构（没有表、没有页面）——**概念本身就是一个完整的存在**。

## 蓝图态 → 锚定态：概念是跳板

概念层解决"journey 不能等一切都好了才串起来"的矛盾：

```
journey 步骤："商户入驻"（名字）
    │ ① 引用概念（只需名字存在）
    ▼
概念：merchant（名词 + 解释）          ← 跳板，先于一切存在
    │ ② 概念长出结构
    ▼
表 / 页面 / 接口（引用概念名）
    │ ③ 结构生成实现
    ▼
DDL / 路由 / 契约产物
```

- **蓝图态**：journey 引用概念名即可串线——概念不需要表、不需要页面，只需要名字存在。
- **锚定态**：概念长出结构后，同一引用自然升级（引用依然有效，只是"对象"变厚了）。
- **名字未长出结构的比例 = 细化度**：概念清单可统计"系统共 N 个概念，M 个已落表"——这是蓝图完成度的天然度量。

## 身份契约

概念名是**跨层身份**的唯一来源：

- journey 说"商户入驻" → 引用 `merchant` 概念
- 表说 `merchant.table.ts` → 引用 `merchant` 概念
- 页面说"商户列表页" → 引用 `merchant` 概念
- lint 检查字段 `mer_id` → 查概念的 `phrase`（词根 `mer`）

所有维度说同一个词，指同一个概念；校验"引用的概念是否存在"是各维度的第一道闸门。

## 校验草案

| 规则 | 检查 |
|------|------|
| C1 | `name` 唯一、kebab-case；一文件一概念清单（`_concepts.ts` 专用名） |
| C2 | `description` 必填（经典段落，非空） |
| C3 | `phrase` 引用必须指向 `_dictionary.ts` 中已定义的短语条目 |
| C4 | 下游引用（journey / table / PageFlow / DTO）引用的概念必须存在于 `_concepts.ts` |
| C5 | 概念引用词根时，词根必须与该概念的中文语义一致（人工评审裁决） |

## 消费者（未来）

| 消费者 | 用途 |
|--------|------|
| journey（蓝图/旅程） | 步骤引用概念名——跨 app 业务线的身份锚点 |
| table.ts | 表归属概念（现有 `phrase` 链接的上一级） |
| PageFlow | 页面归属概念 |
| lint | 跨层身份校验（C4） |
| 文档/评审 | 概念清单渲染为术语表（markdown） |