docs: 业务表 DDL 逐字对齐 react entity(列宽 + f_stock 默认值)

读 react 三个 business entity 源码后发现原 DDL 描述有 3 处偏差:
- demo_item.f_status 实际 varchar(32)(原写 50)
- book_shop_book.f_isbn 实际 varchar(32)(原写 50)
- book_shop_book.f_stock 实际带 default: 0(原写「只有 f_delete_mark 有默认值」)

第三处是真契约分歧:§7.6 路径 2(带 id 但行不存在)在 react 里 f_stock 得 0,
按原描述实现会得 NULL。已同步修正 §5.1 与 §7.6。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-25 17:42:45 +08:00
1 parent b32269dd37
commit 28de290be5
1 file changed
+43 -12
+43 -12
View File
@@ -223,9 +223,23 @@ pub fn valid_column(name: &str) -> Option<String>;
| `book_shop_book` | `f_id` / `f_title` / `f_author` / `f_isbn` / `f_category` / `f_price numeric(12,2)` / `f_stock int` / `f_creator_user_id` / `f_creator_time` / `f_delete_mark` |
业务表主键 `f_id VARCHAR(50) PRIMARY KEY`,时间列 `TIMESTAMP(0) WITHOUT TIME ZONE`。
🔴 **`f_delete_mark INT DEFAULT 0`** —— react entity 上有 `default: 0`,
§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖这个 DB 默认值补出 `0`。
其余业务列**不得**有 DB 默认值(§7.6 路径 2 要求"没给就是 NULL")。
🔴 **业务表的列宽与默认值必须逐字对齐 react 的 TypeORM entity**
(`demo-item.entity.ts` / `product.entity.ts` / `book.entity.ts`)——
这是「两版后端可开同一个库」能成立的**前提**:TypeORM `synchronize` 建的库与我们的 `schema.sql`
必须是同一张表,否则一边 `synchronize` 会 `ALTER` 掉另一边建好的列。
| 表 | 逐字 DDL |
|---|---|
| `demo_item` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / **`f_status VARCHAR(32)`** / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
| `shop_product` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / `f_price NUMERIC(12,2)` / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
| `book_shop_book` | `f_id VARCHAR(50) PRIMARY KEY` / `f_title VARCHAR(255)` / `f_author VARCHAR(100)` / **`f_isbn VARCHAR(32)`** / `f_category VARCHAR(50)` / `f_price NUMERIC(12,2)` / **`f_stock INTEGER DEFAULT 0`** / `f_creator_user_id VARCHAR(50)` / `f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE` / `f_delete_mark INTEGER DEFAULT 0` |
🔴 **有 DB 默认值的只有两处**:`f_delete_mark`(三张表都有)与 **`book_shop_book.f_stock`**。
react 的 `book.entity.ts` 上 `stock` 也有 `default: 0` ⇒ TypeORM 建的库同样带这个默认值。
§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)依赖它们补出 `0`。
其余业务列(`f_title` / `f_status` / `f_price` / `f_author` / `f_isbn` / `f_category` /
`f_creator_user_id` / `f_creator_time`)**不得**有 DB 默认值(§7.6 路径 2 要求"没给就是 NULL")。
### 5.2 时间列口径
官方 DDL 是 `TIMESTAMP(0) WITHOUT TIME ZONE`(秒精度、无时区)。
@@ -606,8 +620,10 @@ SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q
`f_creator_time`=now、`f_delete_mark`=0。
2. **有 `id` 但库里查不到该行** ⇒ **用这个 id 新建**:
- 写入 body 里**该实体的已知列**(§5.3 的列集),**不加任何默认值**:
没有 `f_creator_time` ⇒ NULL;没有 `f_status` / `f_price` / `f_stock` ⇒ NULL;
- `f_delete_mark`:body 没给 ⇒ **0**(业务表该列 DDL 带 `DEFAULT 0`)。
没有 `f_creator_time` ⇒ NULL;没有 `f_status` / `f_price` ⇒ NULL;
- `f_delete_mark`:body 没给 ⇒ **0**(业务表该列 DDL 带 `DEFAULT 0`);
- `f_stock`(**仅 `book_shop_book`**):body 没给 ⇒ **0**(该列 DDL 也带 `DEFAULT 0`,
与 react 的 `book.entity.ts` 一致 ⇒ 两版后端开同一个库时结果相同)。
3. **有 `id` 且库里查得到** ⇒ 覆盖更新:**只覆盖 body 里出现的该实体已知列**(`Object.assign` 语义),
body 没出现的列保持原值。
- 三个模块**共用**一条规则:**body 里不属于该实体列集的键一律忽略**(不建列、不报错)。
@@ -675,18 +691,29 @@ SELECT row_to_json(q)::text AS _row FROM (<sql>) AS q
### 8.6 两段式种子
**`ensure_base()`(每次启动都跑,幂等)**
- 按 `f_en_code` 补内置角色(**已存在的不覆盖**)
- 按 `f_url_address` 补内置菜单(**含软删行也不复活**)
- 取库里 `f_en_code='admin'` 的真实角色行;取所有 `f_delete_mark=0` 且 urlAddress 命中内置菜单清单的行;
对其中尚未在 `base_authorize`(`f_object_type='role' AND f_object_id=<adminRoleId> AND f_item_type='module'`)里的行补授权
- **只补缺项**:不覆盖已改值
- 补内置角色:查 `base_role` 的**全部行**(🔴 **不按 `f_delete_mark` 过滤**),
凡 `f_en_code` 命中内置清单(`admin` / `user`)的**一律视为已存在** ⇒ 不补、不覆盖。
缺的行按 §8.5 的值插入。
- 补内置菜单:查 `base_module` 的**全部行**(🔴 **含软删行**),
凡 `f_url_address` 命中内置清单的**一律视为已存在** ⇒ **不复活**软删的菜单。
缺的行按 §8.4 的值插入(`f_tenant_id='0'`、`f_enabled_mark=1`、`f_delete_mark=0`)。
- 补 admin 授权:
- 取 `base_role` 中 `f_en_code='admin'` 的行(🔴 **不按 `f_delete_mark` 过滤**,取到软删行也用它);
- 取 `base_module` 中 `f_delete_mark=0` **且** `f_url_address` 命中内置清单的行(`builtin_live`);
- 查 `base_authorize` 中 `f_object_type='role' AND f_object_id=<adminRoleId> AND f_item_type='module'`
的**全部行**(🔴 **不按 `f_delete_mark` 过滤** ⇒ 软删的授权行也算「已授权」⇒ 不补);
- `builtin_live` 里没出现在上述集合中的行 ⇒ 补一条授权
(`f_id`=UUID v4、`f_tenant_id='0'`、`f_object_type='role'`、`f_object_id=<adminRoleId>`、
`f_item_type='module'`、`f_item_id=<menuId>`、`f_sort_code=0`、`f_delete_mark=0`)
- **只补缺项**:不覆盖已改值(人工改名/调序会被保留)
**`first_seed()`(仅 `base_user` 行数为 0 时跑一次)**
- 建 `admin` 用户:`f_id`=UUID v4、`f_account='admin'`、`f_real_name='管理员'`、
`f_password=md5_hex('123456')`、`f_is_administrator=1`、`f_organize_id='0'`、
`f_creator_user_id='admin'`、`f_creator_time`=now、`f_enabled_mark=1`、`f_delete_mark=0`、`f_tenant_id='0'`
- 建一条 `base_role_relation`:`f_object_type='user'`、`f_object_id='admin'`、`f_role_id='role_admin'`、
`f_sort_code=0`、`f_delete_mark=0`、`f_tenant_id='0'`、`f_id`=UUID v4
- 建一条 `base_role_relation`:`f_object_type='user'`、🔴 **`f_object_id='admin'`(账号名,不是 UUID!)**、
`f_role_id='role_admin'`、`f_sort_code=0`、`f_delete_mark=0`、`f_tenant_id='0'`、`f_id`=UUID v4
(react 源码里就是 `'admin'`,**逐字照抄**;admin 本人是管理员,不靠这条授权吃饭)
---
@@ -838,6 +865,10 @@ pub struct AppState {
3. **标识符白名单自检**(不过 ⇒ 秒退 exit 1),放在开库**之前**
4. `Db::open` / `Db::open_temp` ⇒ `ensure_schema()`
5. `seed::ensure_base()` ⇒ 若用户数为 0 则 `seed::first_seed()`
🔴 **种子失败 ⇒ 打印人话错误 + `exit 1`(启动期不变量破了就立刻退出)**,
与第 3 步的白名单自检同一处置。react 的 `onModuleInit` 是 try/catch + `logger.warn` 后**继续跑**,
本仓**刻意不同**(react 那边是 NestJS 容器里已挂载的应用,退出不了;本仓是单二进制,退出更干净)。
这条**不在 HTTP 契约面上**(服务要么正常起来,要么根本不起来)。
6. `build_router(state)` + 404 兜底 + 405 改写中间件 + **catch-all(panic/未捕获异常 ⇒ HTTP 200 + `code=400`)** + `with_state(state)`(**链尾**)
7. `TcpListener::bind` ⇒ 绑定失败打印人话 + exit 1(**不 panic**)