docs(spec): 投影别名改双引号(PG 折叠未加引号的标识符)

Task 3 实现者实测发现:PostgreSQL 把未加引号的别名折叠成小写 ——
`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ {"realname":1},
写 AS "realName" 才是 {"realName":1}。规格原先给的示例(§R1.4 / §5.2 / §5.3)
照抄会**静默**产出小写 JSON 键 ⇒ 前端读不到字段。

- §R1.4 / §4 / §5.2 / §5.3:规范写法改为 `f_xxx AS "<JSON键>"`(带双引号)。
- §5.4:登记 db.rs 的键归一为**安全网**(能兜住漏引号的写法),但规范写法不依赖它。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-25 18:07:45 +08:00
1 parent 08c266537a
commit 0fef2fbfb7
1 file changed
+28 -8
+28 -8
View File
@@ -37,9 +37,17 @@
所有 SELECT **必须显式列出列名**。原因:react 版库(TypeORM `synchronize`)只有 entity 里的列,
官方 DDL 有 30~60 列。显式投影让本仓后端**能开 react 建出来的库**,且响应 JSON 与 react 逐字相同。
🔴 **每列还要显式 `AS <JSON键>`**(camelCase,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。
🔴 **每列还要显式 `AS "<JSON键>"`**(camelCase + **双引号**,见 §4)——`row_to_json` 用**列的输出名**当 JSON 键。
写成 `AS creator_time` 会得到 `"creator_time"`,react 是 `"creatorTime"` ⇒ 前端读不到字段。
🔴🔴 **别名必须加双引号**(2026-10-25 修订,Ruling P23)——
**PostgreSQL 会把未加双引号的标识符折叠成小写**:`AS realName` 的输出列名是 `realname`
⇒ `row_to_json` 出来的键是 `"realname"`,**不是** `"realName"` ⇒ 前端读不到字段,**且静默**。
实测:`SELECT row_to_json(q)::text FROM (SELECT 1 AS realName) q` ⇒ `{"realname":1}`;
写成 `AS "realName"` 才是 `{"realName":1}`。
⇒ **规范写法:`f_real_name AS "realName"`、`f_price::text AS "price"`。**
(`db.rs` 另有一层键归一兜底,见 §5.4 —— 它是**安全网**,不是本规范;规范写法本身不依赖它。)
### R1.5 numeric 列必须序列化成 JSON 字符串
`f_price` 回显 `"9.90"`,不是 `9.9`。手段:**在 SQL 投影里就 cast 成 text**(`f_price::text AS price`)。
`int` 列(`f_delete_mark` / `f_stock` / `f_is_administrator`)**保持数字**。
@@ -152,6 +160,9 @@ react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库
**规则**:列名去 `f_` 前缀 → 剩余部分按 `_` 拆 → camelCase。
🔴 **投影时别名一律写 `AS "<JSON键>"`(带双引号)** —— PG 会把未加引号的标识符折叠成小写
(`AS realName` ⇒ 键 `"realname"` ⇒ 前端读不到,**且静默**)。详见 §R1.4。
| 列 | JSON 键 |
|---|---|
| `f_id` | `id` |
@@ -249,9 +260,10 @@ react 的 `book.entity.ts` 上 `stock` 也有 `default: 0` ⇒ TypeORM 建的库
to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime
```
🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase)** ——
🔴 **投影的 `AS` 别名必须就是 §4 的 JSON 键(camelCase),且必须加双引号** ——
`row_to_json` 用的是**列的输出名**当 JSON 键。别名写成 `AS creator_time` 会得到 `"creator_time"`,
与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。**每一列**都要显式 `AS <JSON键>`。
与 react 的 `"creatorTime"` **对不上** ⇒ 前端所有字段读不到。
**每一列**都要显式 `AS "<JSON键>"`(**带双引号** —— PG 折叠未加引号的标识符,见 §R1.4)。
### 5.3 精确列清单(**投影真源**)
@@ -261,11 +273,12 @@ to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime
格式:`列名 → JSON 键`。列顺序 = react entity 的声明顺序。
🔴 **投影写法**:每列都写成 `f_xxx AS <JSON键>`(**别名 = 右边的 JSON 键,camelCase**)。
`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react。
例:`f_real_name AS realName`、`f_is_administrator AS isAdministrator`、
`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS creatorTime`、
`f_price` ⇒ `f_price::text AS price`(numeric 必须是字符串)。
🔴 **投影写法**:每列都写成 `f_xxx AS "<JSON键>"`(**别名 = 右边的 JSON 键,camelCase,且带双引号**)。
`row_to_json` 用的就是别名当 JSON 键 —— 别名写错 ⇒ 响应键名对不上 react;
**双引号漏了 ⇒ PG 折叠成小写 ⇒ 键名对不上且静默**(见 §R1.4)。
例:`f_real_name AS "realName"`、`f_is_administrator AS "isAdministrator"`、
`f_creator_time` ⇒ `to_char(f_creator_time, 'YYYY-MM-DD"T"HH24:MI:SS') || 'Z' AS "creatorTime"`、
`f_price` ⇒ `f_price::text AS "price"`(numeric 必须是字符串)。
**base_authorize**(9 列)
```
@@ -378,6 +391,13 @@ SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q
```
⇒ 取单列文本 ⇒ `serde_json::from_str`。**不要另起逐列类型映射分支。**
🔴 **键归一安全网**(`db.rs` 内建,Ruling P23):`query_json` 返回前会把 JSON 键还原成 camelCase ——
① 内层 SQL 里 `AS <别名>`(**含大写字母**)的别名 ⇒ 按作者原样还原(`AS realName` ⇒ `"realName"`);
② 键以 `f_` 开头 ⇒ 走 `column_to_json_key`(`f_real_name` ⇒ `realName`,与 `tdc-rs` 同思路)。
已加双引号的别名(`AS "realName"`)PG 原样保留 ⇒ 两条规则都不动它。
⇒ **两种写法都能出正确键**;但**规范写法是加双引号**(原生 PG 行为,不依赖这层解析)。
安全网存在的意义是:万一某处漏了双引号,**不会静默产出小写键**。
**绑定参数一律按 text 传**(`&str` / `Option<&str>` 都实现了 `ToSql`);
类型转换由 SQL 里的 `CAST` / 列上下文负责(PG 从目标列推断参数类型)。