391 lines
14 KiB
Markdown
391 lines
14 KiB
Markdown
# CONDO 后端数据库模型
|
||
|
||
更新日期：2026-07-31
|
||
业务依据：当前前端页面、字段和运行规则
|
||
|
||
## 1. 设计原则
|
||
|
||
- 当前前端是生产数据库和 API 的业务规格。
|
||
- 生产表与本地导入预演分开；历史批次通过受控 importer 写入生产表，不把原始 Excel 作为数据库运行时依赖。
|
||
- 所有新对象仅位于现有 `booking_test` 数据库的 `condon` schema；不改动其他 schema 的对象、数据、角色或权限。
|
||
- 一个 Usage Record 代表一间房的一次使用。
|
||
- 每个业主房号独立管理权益余额。
|
||
- 所有 Use 和 Balance 都由后端计算，不能信任前端传来的结果。
|
||
- V1 只实现实时新增使用记录；取消、冲正、调整、账户状态和用户角色不预建。
|
||
|
||
## 2. 当前前端字段
|
||
|
||
### 2.1 Owner Account
|
||
|
||
- No.
|
||
- Transfer Date
|
||
- Name
|
||
- Room No.
|
||
- Room Type
|
||
- Unit No.
|
||
- Member No.
|
||
- Remaining stay privileges
|
||
|
||
### 2.2 Usage History
|
||
|
||
1. Confirmation No.
|
||
2. Check-in
|
||
3. Check-out
|
||
4. Night
|
||
5. Use
|
||
6. Balance
|
||
7. Used Room Type
|
||
8. Remark
|
||
|
||
关系为：
|
||
|
||
- `Night = Check-out - Check-in`
|
||
- `Use = Night × Multiplier`
|
||
- `Balance After = Balance Before - Use`
|
||
|
||
历史导入另外保留 `Room`、`Total` 和来源定位字段；前端新建记录仍默认 Room=1，余额由后端维护。
|
||
|
||
## 3. 房型使用规则
|
||
|
||
### 3.0 酒店房型代码定义
|
||
|
||
| 代码 | 酒店定义 |
|
||
| --- | --- |
|
||
| RM1 | No balcony TWN（4+4 F） |
|
||
| RM2 | Superior King（6F） |
|
||
| RM3 | Superior TWN（4+4 F） |
|
||
| RM4 | Superior TWN（6+4 F） |
|
||
| UG1 | Deluxe King（6F） |
|
||
| UG2 | Deluxe TWN（6+4 F） |
|
||
| SU1 | Junior Suite King（6F） |
|
||
| SU2 | Junior Suite King（6F），Pool view |
|
||
| SU6 | Junior Suite TWN（4+4 F） |
|
||
| SU3 | Two bedroom / Family room（1 room King + 1 room TWN） |
|
||
| AC1 | Handicap King |
|
||
| AC2 | Handicap TWN |
|
||
|
||
历史源文件中的泛称（如 `Superior Room`、`Deluxe Room`、`Junior Suite (One Bedroom)`）可能缺少 King/TWN/Pool view 信息，不能仅凭文字强制映射；历史原文应保留。当前已部署模型只初始化 AC2，AC1 是否加入生产代码及其扣减规则需单独确认。
|
||
|
||
### 3.1 房型分级
|
||
|
||
| Tier | 房型 |
|
||
| --- | --- |
|
||
| 1 | RM1、RM2、RM3、RM4、UG1、UG2 |
|
||
| 2 | SU1、SU2、SU6 |
|
||
| 3 | SU3 |
|
||
|
||
AC2 不属于自动分级，继续采用当前前端的人工倍数规则。
|
||
|
||
### 3.2 自动倍数矩阵
|
||
|
||
| 购买房型 | 使用 RM/UG | 使用 SU1/SU2/SU6 | 使用 SU3 |
|
||
| --- | ---: | ---: | ---: |
|
||
| RM/UG | 1 | 2 | 3 |
|
||
| SU1/SU2/SU6 | 1 | 1 | 2 |
|
||
| SU3 | 1 | 1 | 1 |
|
||
|
||
等价计算公式：
|
||
|
||
```text
|
||
Multiplier = max(1, Used Tier - Purchased Tier + 1)
|
||
```
|
||
|
||
后端必须根据 Owner Account 的 Purchased Room Type 和 Usage Record 的 Used Room Type 重新计算倍数。普通请求不能直接指定 multiplier。
|
||
|
||
购买或使用 AC2 时请求可以携带人工 multiplier，后端校验范围为当前前端支持的 1–3。
|
||
|
||
新业务 Usage Record 保存实际使用的 `applied_multiplier` 和 `rule_version`；legacy 导入记录使用 `applied_multiplier=NULL`、`rule_version=legacy-source`，以源 Use/Balance 为事实。
|
||
|
||
## 4. 推荐数据表
|
||
|
||
```mermaid
|
||
erDiagram
|
||
ROOM_TYPES ||--o{ OWNER_ACCOUNTS : purchased_as
|
||
OWNER_ACCOUNTS ||--o{ ENTITLEMENT_PERIODS : owns
|
||
BOOKINGS ||--o{ USAGE_RECORDS : contains
|
||
OWNER_ACCOUNTS ||--o{ USAGE_RECORDS : creates
|
||
ROOM_TYPES ||--o{ USAGE_RECORDS : used_as
|
||
ENTITLEMENT_PERIODS ||--o{ USAGE_RECORDS : applies_to
|
||
ENTITLEMENT_PERIODS ||--o{ ENTITLEMENT_LEDGER : records
|
||
USAGE_RECORDS ||--o| ENTITLEMENT_LEDGER : deducts
|
||
```
|
||
|
||
### 4.0 `condon.bookings`
|
||
|
||
一条 Confirmation 对应一条 booking；同一 booking 可以关联多条 `usage_records`。因此 `usage_records.confirmation_no` 不设唯一约束，而是引用本表主键。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `confirmation_no` | `varchar(64)` PK | 预订 Confirmation，当前新业务要求纯数字 |
|
||
| `created_at` | `timestamptz` | 首次出现时间 |
|
||
|
||
### 4.1 `condon.room_types`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `code` | `varchar(16)` PK | RM3、SU1、AC2 等 |
|
||
| `entitlement_tier` | `smallint` nullable | 自动规则为 1–3；AC2 为空 |
|
||
| `requires_manual_multiplier` | `boolean` | AC2 为 true，其他房型为 false |
|
||
| `created_at` | `timestamptz` | 创建时间 |
|
||
| `updated_at` | `timestamptz` | 更新时间 |
|
||
|
||
约束：
|
||
|
||
- 自动房型必须 `entitlement_tier IN (1, 2, 3)` 且 `requires_manual_multiplier = false`。
|
||
- 人工房型必须 `entitlement_tier IS NULL` 且 `requires_manual_multiplier = true`。
|
||
- 初始化代码仅包含 RM1、RM2、RM3、RM4、UG1、UG2、SU1、SU2、SU6、SU3、AC2。
|
||
|
||
### 4.2 `condon.owner_accounts`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | `uuid` PK | 内部不可变主键 |
|
||
| `account_no` | `integer` nullable | 前端 No. |
|
||
| `transfer_date` | `date` nullable | Transfer Date |
|
||
| `owner_name` | `text` | 前端显示名称 |
|
||
| `room_no` | `varchar(32)` | 业主房号 |
|
||
| `purchased_room_type_code` | FK | 购买房型 |
|
||
| `unit_no` | `varchar(32)` | Unit No. |
|
||
| `member_no` | `varchar(32)` | Member No.，按文本保存 |
|
||
| `created_at` | `timestamptz` | 创建时间 |
|
||
| `updated_at` | `timestamptz` | 更新时间 |
|
||
|
||
约束：
|
||
|
||
- `account_no` 在非空时唯一。
|
||
- `room_no` 唯一。
|
||
- `purchased_room_type_code` 引用 `condon.room_types(code)`。
|
||
- 姓名、Unit No.、Member No. 不作为内部主键。
|
||
- 本表不保存余额；余额的单一权威来源是 `condon.entitlement_periods.current_balance`。
|
||
|
||
### 4.3 `condon.entitlement_periods`
|
||
|
||
每个 Owner Account 每个权益年度一条记录。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | `uuid` PK | 权益期间 ID |
|
||
| `owner_account_id` | FK | 所属业主账户 |
|
||
| `period_year` | `smallint` | 权益年度 |
|
||
| `period_start` | `date` | 当前规则为 1 月 1 日 |
|
||
| `period_end` | `date` | 当前规则为 12 月 31 日 |
|
||
| `annual_grant` | `integer` | 当前规则为 15 晚 |
|
||
| `carry_forward` | `integer` | 上期结转 |
|
||
| `current_balance` | `integer` | 唯一权威余额缓存 |
|
||
| `row_version` | `integer` | 防止并发重复扣减 |
|
||
| `created_at` | `timestamptz` | 创建时间 |
|
||
| `updated_at` | `timestamptz` | 更新时间 |
|
||
|
||
约束：
|
||
|
||
- `(owner_account_id, period_year)` 唯一。
|
||
- `period_start` 和 `period_end` 必须分别为该年的 1 月 1 日和 12 月 31 日。
|
||
- `annual_grant >= 0`。
|
||
- `carry_forward >= 0`。
|
||
- `current_balance >= 0`。
|
||
- `row_version >= 1`。
|
||
|
||
`current_balance` 用于快速显示；所有余额变化必须与 ledger 在同一事务内完成。
|
||
|
||
### 4.4 `condon.usage_records`
|
||
|
||
一行对应前端 Usage History 的一行。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | `uuid` PK | 内部记录 ID |
|
||
| `owner_account_id` | FK | 所属 Owner Account |
|
||
| `entitlement_period_id` | FK | 扣减的权益年度 |
|
||
| `confirmation_no` | `varchar(64)` | Confirmation No. |
|
||
| `check_in` | `date` | Check-in |
|
||
| `check_out` | `date` | Check-out |
|
||
| `night_count` | `integer` | Night |
|
||
| `used_room_type_code` | FK nullable | 可映射到标准代码的 Used Room Type；历史泛称可为空 |
|
||
| `raw_used_room_type` | `text` | 源文件原始房型文本 |
|
||
| `applied_multiplier` | `smallint nullable` | 新记录为 1–3；legacy 历史统一为空 |
|
||
| `rule_version` | `varchar(32)` | 规则版本 |
|
||
| `use_nights` | `integer` | Use |
|
||
| `balance_before` | `integer` | 扣减前余额 |
|
||
| `balance_after` | `integer` | Balance |
|
||
| `room_count` | `integer` | 源历史 Room；当前最新批次均为 1 |
|
||
| `remark` | `text` | Remark |
|
||
| `idempotency_key` | `uuid` | 防止重复请求 |
|
||
| `source_sheet` | `varchar(128) nullable` | Excel 子表名 |
|
||
| `source_row` | `integer nullable` | Excel 行号 |
|
||
| `source_sequence` | `integer nullable` | 子表 No.，保留源顺序 |
|
||
| `import_batch` | `varchar(128) nullable` | 导入批次标识 |
|
||
| `created_at` | `timestamptz` | 录入时间 |
|
||
|
||
约束：
|
||
|
||
- `confirmation_no` 引用 `condon.bookings`，满足当前前端的纯数字规则；同一号允许多条 usage。
|
||
- `check_out > check_in`。
|
||
- `night_count = check_out - check_in`。
|
||
- 新记录 `applied_multiplier BETWEEN 1 AND 3`，且 `use_nights = night_count × applied_multiplier`。
|
||
- legacy 记录 `applied_multiplier IS NULL`，源 `Use`、`Total`、`Balance` 原样保存。
|
||
- `balance_before >= use_nights`。
|
||
- `balance_after = balance_before - use_nights`。
|
||
- `balance_after >= 0`。
|
||
- `idempotency_key` 唯一。
|
||
- Check-in 和 Check-out 必须在同一个权益年度内；跨年度请求在 V1 明确拒绝。
|
||
|
||
### 4.5 `condon.entitlement_ledger`
|
||
|
||
保存每一次年度新增、结转和使用扣减。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `id` | `uuid` PK | 流水 ID |
|
||
| `entitlement_period_id` | FK | 所属权益期间 |
|
||
| `usage_record_id` | FK nullable | 使用扣减对应的记录 |
|
||
| `entry_type` | `varchar(20)` | annual_grant、carry_forward、usage |
|
||
| `delta_nights` | `integer` | 增加为正，扣减为负 |
|
||
| `balance_before` | `integer` | 变动前余额 |
|
||
| `balance_after` | `integer` | 变动后余额 |
|
||
| `occurred_at` | `timestamptz` | 发生时间 |
|
||
|
||
约束：
|
||
|
||
- `balance_after = balance_before + delta_nights`。
|
||
- `balance_after >= 0`。
|
||
- 一条 Usage Record 只能产生一笔 usage debit。
|
||
- annual_grant 和非零 carry_forward 为正数，usage 为负数。
|
||
- usage 必须引用 Usage Record；annual_grant 和 carry_forward 不引用 Usage Record。
|
||
|
||
### 4.6 `condon.schema_migrations`
|
||
|
||
仅记录 `condon` 自身的迁移版本，不借用 `public`。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `version` | `varchar(64)` PK | 迁移版本 |
|
||
| `checksum` | `varchar(64)` | SQL 内容校验值 |
|
||
| `applied_at` | `timestamptz` | 应用时间 |
|
||
|
||
导入批次和拒绝行保存在仓库内的本地审计产物中；数据库只保存已接受记录的 `import_batch` 与来源定位字段。
|
||
|
||
## 5. 后端保存事务
|
||
|
||
前端提交：
|
||
|
||
```json
|
||
{
|
||
"ownerAccountId": "uuid",
|
||
"confirmationNo": "26090001",
|
||
"checkIn": "2026-09-01",
|
||
"checkOut": "2026-09-04",
|
||
"usedRoomType": "SU1",
|
||
"manualMultiplier": null,
|
||
"remark": "",
|
||
"idempotencyKey": "uuid"
|
||
}
|
||
```
|
||
|
||
后端处理：
|
||
|
||
1. 校验 idempotency key 是否已处理。
|
||
2. 校验 Confirmation No. 为纯数字且未使用。
|
||
3. 读取 Owner Account、Purchased Room Type 和当前权益期间。
|
||
4. 计算 Night。
|
||
5. 根据购买/使用房型 tier 计算 multiplier；AC2 校验人工 multiplier。
|
||
6. 计算 `Use = Night × Multiplier`。
|
||
7. 开启事务并锁定对应 entitlement period，同时检查 row version。
|
||
8. 校验余额足够。
|
||
9. 写入 Usage Record 和 ledger debit；Confirmation 通过 booking 1:N 关系复用。
|
||
10. 更新 current balance 和 row version。
|
||
11. 提交事务并返回完整 Usage History 数据。
|
||
|
||
任一步失败都整体回滚，避免出现“余额已扣但记录未保存”或相反的情况。
|
||
|
||
前端传来的 Night、Use、Balance 和自动 multiplier 只用于即时预览，不能作为后端权威值。
|
||
|
||
数据库函数：
|
||
|
||
- `condon.calculate_multiplier(...)`：返回自动倍率或校验 AC2 手动倍率。
|
||
- `condon.open_entitlement_period(...)`：按 15 晚年度新增和上一年度余额结转建立新期间，写入年度新增 ledger，并在结转大于 0 时写入结转 ledger。
|
||
- `condon.create_usage_record(...)`：完成计算、行锁、余额验证、usage/ledger 写入和余额更新。
|
||
|
||
三个函数均使用显式 schema 名、固定安全 `search_path` 和调用者权限，不修改角色或全局权限。
|
||
|
||
## 6. API 读取模型
|
||
|
||
### Owner Accounts
|
||
|
||
返回：
|
||
|
||
- `id`
|
||
- `accountNo`
|
||
- `transferDate`
|
||
- `name`
|
||
- `roomNo`
|
||
- `purchasedRoomType`
|
||
- `unitNo`
|
||
- `memberNo`
|
||
- `remainingStayPrivileges`
|
||
|
||
### Usage History
|
||
|
||
返回：
|
||
|
||
- `id`
|
||
- `confirmationNo`
|
||
- `ownerAccountId`
|
||
- `ownerName`
|
||
- `ownerRoomNo`
|
||
- `checkIn`
|
||
- `checkOut`
|
||
- `night`
|
||
- `use`
|
||
- `balance`
|
||
- `usedRoomType`
|
||
- `remark`
|
||
- `createdAt`
|
||
|
||
这组返回值可以直接支持全局 Usage History、账户详情、Confirmation 搜索和当前排序规则。
|
||
|
||
## 7. Dashboard 计算
|
||
|
||
- Owner rooms：Owner Account 数量。
|
||
- Remaining privileges：当前 entitlement period 的 `current_balance` 总和。
|
||
- Used this year：当前期间 Usage Record 的 `use_nights` 总和。
|
||
- Room Type：按 Owner Account 的 purchased room type 计数。
|
||
- Used Room Type：按 Usage Record 的 `night_count` 汇总实际房晚；一条记录代表一间房，所以不乘 Room 数量。
|
||
- 月度 Use：按 Check-in 月份汇总 `use_nights`。
|
||
|
||
所有 Dashboard 指标由同一权益期间和已保存的 Usage Record 生成，不能继续使用静态图表值。
|
||
|
||
## 8. 推荐索引
|
||
|
||
- `owner_accounts(account_no)` 唯一（允许多个 NULL）。
|
||
- `owner_accounts(room_no)` 唯一。
|
||
- `owner_accounts(member_no)`。
|
||
- `owner_accounts(purchased_room_type_code)`。
|
||
- `entitlement_periods(owner_account_id, period_year)` 唯一。
|
||
- `bookings(confirmation_no)` 主键；usage 通过 Confirmation 外键关联。
|
||
- `usage_records(import_batch, source_sheet, source_row)` 部分唯一索引。
|
||
- `usage_records(owner_account_id, created_at, id)`。
|
||
- `usage_records(entitlement_period_id)`。
|
||
- `usage_records(used_room_type_code, check_in)`。
|
||
- `entitlement_ledger(entitlement_period_id, occurred_at, id)`。
|
||
- `entitlement_ledger(usage_record_id)` 唯一（允许 annual_grant/carry_forward 为 NULL）。
|
||
|
||
## 9. V1 明确不预建的规则
|
||
|
||
1. Usage Record 取消、冲正和人工余额调整。
|
||
2. 房屋转让时的余额归属与历史账户处理。
|
||
3. 真实用户登录、角色和操作人追踪。
|
||
4. 跨权益年度的一次使用；V1 返回明确错误。
|
||
5. 新历史批次的业务纠正与房型映射；已确认的 `(2)` 批次已导入，后续批次继续走预演流程。
|
||
|
||
这些能力以后通过独立迁移扩展，不在基础表中预先加入未经确认的字段。
|
||
|
||
## 10. 推荐实施顺序
|
||
|
||
1. 只读盘点 `booking_test`，确认目标 schema 和业务表状态。
|
||
2. 本地编写版本化迁移、精确回滚和 SQL allowlist 安全检查。
|
||
3. 应用 `001_create_condon_schema` 与 `002_legacy_import_and_bookings`。
|
||
4. 生成最新工作簿本地导入预演批次，排除无 Confirmation 行并逐条校验。
|
||
5. 在空业务表中单事务导入 owner、权益期间、booking、legacy usage 和 ledger。
|
||
6. 通过只读逐条比对及 API smoke 后再开放前端读取。
|
||
7. 新增 usage 继续只调用数据库计算倍率的 v2 写入路径。
|