diff --git a/docs/contract.md b/docs/contract.md index 10d5a56..4228a3a 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -223,9 +223,23 @@ pub fn valid_column(name: &str) -> Option; | `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 () 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 () 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= 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= 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=`、 + `f_item_type='module'`、`f_item_id=`、`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**)