注释补全
This commit is contained in:
Shen Wei
@@ -184,136 +184,136 @@
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE properties (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
|
||||
-- ── 基础分类 ──
|
||||
property_type VARCHAR(20) NOT NULL
|
||||
property_type VARCHAR(20) NOT NULL -- 房源类型：residential=住宅 / villa=别墅 / commercial_residential=商住 / shop=商铺 / office=写字楼 / other=其他（详见 ENUMS.md §property_type）
|
||||
CHECK (property_type IN ('residential','villa','commercial_residential',
|
||||
'shop','office','other')),
|
||||
|
||||
-- ── 交易状态 ──
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'for_sale'
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'for_sale' -- 房源交易状态：for_sale=出售 / for_rent=出租 / for_sale_rent=租售 / suspended=暂缓 / sold_elsewhere=他售 / rented_elsewhere=他租 / sold=成交 / unlisted=未挂牌（详见 ENUMS.md §status）
|
||||
CHECK (status IN ('for_sale','for_rent','for_sale_rent',
|
||||
'suspended','sold_elsewhere','rented_elsewhere',
|
||||
'sold','unlisted')),
|
||||
|
||||
-- ── 流通属性 ──
|
||||
attribute VARCHAR(20) NOT NULL DEFAULT 'public'
|
||||
attribute VARCHAR(20) NOT NULL DEFAULT 'public' -- 房源流通属性：public=公盘 / private=私盘 / special=特盘 / sealed=封盘；控制可见范围（详见 ENUMS.md §attribute）
|
||||
CHECK (attribute IN ('public','private','special','sealed')),
|
||||
private_reason TEXT, -- 私盘/封盘必填说明
|
||||
private_reason TEXT, -- 私盘/封盘必填说明（attribute 为 private/sealed 时必填，最多200字）
|
||||
|
||||
-- ── 位置信息 ──
|
||||
complex_id UUID NOT NULL REFERENCES complexes(id) ON DELETE RESTRICT,
|
||||
building_id UUID REFERENCES buildings(id) ON DELETE SET NULL,
|
||||
block_no VARCHAR(30), -- 栋/幢/弄号
|
||||
unit_no VARCHAR(30), -- 单元号
|
||||
room_no VARCHAR(30), -- 房号/门牌号
|
||||
floor SMALLINT NOT NULL, -- 所在楼层
|
||||
total_floors SMALLINT NOT NULL, -- 总楼层
|
||||
CONSTRAINT chk_floor CHECK (floor > 0 AND floor <= total_floors),
|
||||
complex_id UUID NOT NULL REFERENCES complexes(id) ON DELETE RESTRICT, -- 所属楼盘（关联 complexes 表，房源必须挂在楼盘下，禁止级联删除）
|
||||
building_id UUID REFERENCES buildings(id) ON DELETE SET NULL, -- 所属楼栋（关联 buildings 表；楼栋被删除时置 NULL）
|
||||
block_no VARCHAR(30), -- 栋/幢/弄号（如"3栋"、"A幢"；与 unit_no 组合定位具体位置）
|
||||
unit_no VARCHAR(30), -- 单元号（如"1单元"、"055"）
|
||||
room_no VARCHAR(30), -- 房号/门牌号（如"0301"、"1502"）
|
||||
floor SMALLINT NOT NULL, -- 所在楼层（正整数，不超过 total_floors；CheckConstraint 校验）
|
||||
total_floors SMALLINT NOT NULL, -- 楼栋总层数（正整数）
|
||||
CONSTRAINT chk_floor CHECK (floor > 0 AND floor <= total_floors), -- 楼层合法性约束：所在楼层必须 > 0 且 ≤ 总楼层
|
||||
|
||||
-- ── 户型 ──
|
||||
bedroom_count SMALLINT NOT NULL DEFAULT 0, -- 室
|
||||
living_room_count SMALLINT NOT NULL DEFAULT 0, -- 厅
|
||||
bathroom_count SMALLINT NOT NULL DEFAULT 0, -- 卫
|
||||
kitchen_count SMALLINT NOT NULL DEFAULT 0, -- 厨
|
||||
balcony_count SMALLINT NOT NULL DEFAULT 0, -- 阳台数
|
||||
bedroom_count SMALLINT NOT NULL DEFAULT 0, -- 卧室数（室）
|
||||
living_room_count SMALLINT NOT NULL DEFAULT 0, -- 客厅/餐厅数（厅）
|
||||
bathroom_count SMALLINT NOT NULL DEFAULT 0, -- 卫生间数（卫）
|
||||
kitchen_count SMALLINT NOT NULL DEFAULT 0, -- 厨房数（厨）
|
||||
balcony_count SMALLINT NOT NULL DEFAULT 0, -- 阳台数（0=无阳台）
|
||||
|
||||
-- ── 面积 ──
|
||||
area NUMERIC(8,2) NOT NULL, -- 建筑面积 m²
|
||||
inner_area NUMERIC(8,2), -- 套内面积 m²
|
||||
area NUMERIC(8,2) NOT NULL, -- 建筑面积（m²，含公摊；录入必填）
|
||||
inner_area NUMERIC(8,2), -- 套内面积（m²，不含公摊；选填，编辑页专属字段）
|
||||
|
||||
-- ── 价格 ──
|
||||
sale_price NUMERIC(12,2), -- 挂牌售价（万元）
|
||||
sale_bottom_price NUMERIC(12,2), -- 售底价（万元，内部可见）
|
||||
sale_record_price NUMERIC(12,2), -- 备案/核验价（万元）
|
||||
rent_price NUMERIC(10,2), -- 挂牌租价（元/月）
|
||||
sale_price NUMERIC(12,2), -- 挂牌售价（万元；出售类房源必填，出租类可为 NULL）
|
||||
sale_bottom_price NUMERIC(12,2), -- 售底价（万元；业主心理底价，仅内部可见，不对外展示）
|
||||
sale_record_price NUMERIC(12,2), -- 备案/核验价（万元；填写后同步至营销库）
|
||||
rent_price NUMERIC(10,2), -- 挂牌租价（元/月；出租类房源使用）
|
||||
|
||||
-- ── 基础物理属性 ──
|
||||
orientation VARCHAR(10)
|
||||
orientation VARCHAR(10) -- 朝向：east=东 / south=南 / west=西 / north=北 / southeast=东南 / northeast=东北 / east_west=东西 / south_north=南北 / northwest=西北 / southwest=西南（详见 ENUMS.md §orientation）
|
||||
CHECK (orientation IN ('east','south','west','north',
|
||||
'southeast','northeast','east_west',
|
||||
'south_north','northwest','southwest')),
|
||||
decoration VARCHAR(10)
|
||||
decoration VARCHAR(10) -- 装修情况：rough=毛坯 / plain=清水 / simple=简装 / medium=中装 / fine=精装 / luxury=豪装（详见 ENUMS.md §decoration）
|
||||
CHECK (decoration IN ('rough','plain','simple','medium',
|
||||
'fine','luxury')),
|
||||
has_elevator BOOLEAN,
|
||||
built_year SMALLINT,
|
||||
has_elevator BOOLEAN, -- 是否有电梯：true=有 / false=无 / NULL=未确认
|
||||
built_year SMALLINT, -- 建成年份（如 2018；可空，老房源无记录；建成年代为空可能影响营销发房）
|
||||
|
||||
-- ── 用途 ──
|
||||
usage_type VARCHAR(30), -- 住宅/商住/商业/普通住宅/花园洋房 等
|
||||
usage_subtype VARCHAR(30), -- 细分用途
|
||||
usage_type VARCHAR(30), -- 房屋用途大类（如：住宅 / 商住 / 商业；对应更改用途浮窗第一级下拉）
|
||||
usage_subtype VARCHAR(30), -- 房屋用途细分小类（如：普通住宅 / 花园洋房；对应更改用途浮窗第二级下拉）
|
||||
|
||||
-- ── 商铺专属 ──
|
||||
shop_frontage NUMERIC(6,2), -- 开间（米）
|
||||
shop_depth NUMERIC(6,2), -- 进深（米）
|
||||
shop_height NUMERIC(6,2), -- 层高（米）
|
||||
shop_location VARCHAR(20)
|
||||
shop_frontage NUMERIC(6,2), -- 开间（米；商铺专属，住宅类为 NULL）
|
||||
shop_depth NUMERIC(6,2), -- 进深（米；商铺专属）
|
||||
shop_height NUMERIC(6,2), -- 层高（米；商铺专属）
|
||||
shop_location VARCHAR(20) -- 商铺位置类型：street=沿街 / mall=商场内 / residential=住宅底商 / ground_floor=楼栋底层 / complex=综合体（商铺专属）
|
||||
CHECK (shop_location IS NULL OR
|
||||
shop_location IN ('street','mall','residential',
|
||||
'ground_floor','complex')),
|
||||
|
||||
-- ── 房屋状态 ──
|
||||
house_status VARCHAR(20)
|
||||
house_status VARCHAR(20) -- 房屋现状：owner_occupied=业主自住 / vacant=空置 / tenant_occupied=租客租住 / unknown=未知；影响带看安排
|
||||
CHECK (house_status IN ('owner_occupied','vacant',
|
||||
'tenant_occupied','unknown')),
|
||||
viewing_time VARCHAR(20)
|
||||
viewing_time VARCHAR(20) -- 看房时间安排：anytime=随时可看 / by_appointment=提前预约 / inconvenient=不方便看
|
||||
CHECK (viewing_time IN ('anytime','by_appointment','inconvenient')),
|
||||
|
||||
-- ── 等级与标签 ──
|
||||
grade VARCHAR(10)
|
||||
grade VARCHAR(10) -- 房源等级（业主出售意向）：A=急迫 / B=较强 / C=一般 / D=较弱（详见 ENUMS.md §grade）
|
||||
CHECK (grade IN ('A','B','C','D')),
|
||||
|
||||
-- ── 交易属性 ──
|
||||
ownership_years VARCHAR(30), -- 房本年限：不满2年/满2年/满5年 等
|
||||
ownership_years_detail VARCHAR(20), -- 满五/不满五
|
||||
ownership_nature VARCHAR(20)
|
||||
ownership_years VARCHAR(30), -- 房本年限：不满2年/满2年/满5年 等（影响交易税费）
|
||||
ownership_years_detail VARCHAR(20), -- 房本年限辅助说明：满五/不满五（与 ownership_years 组合使用）
|
||||
ownership_nature VARCHAR(20) -- 产权性质：commercial=商品房 / reform_housing=房改房 / collective=集资房 / economic=经济活用房
|
||||
CHECK (ownership_nature IS NULL OR
|
||||
ownership_nature IN ('commercial','reform_housing',
|
||||
'collective','economic')),
|
||||
is_only_house BOOLEAN, -- 唯一住房
|
||||
payment_method VARCHAR(30)
|
||||
is_only_house BOOLEAN, -- 是否唯一住房：true=唯一 / false=非唯一 / NULL=未确认；影响交易税费计算
|
||||
payment_method VARCHAR(30) -- 购房付款方式：full=一次付清 / mortgage=按揭付款 / installment=分批次付款 / advance=垫资解按
|
||||
CHECK (payment_method IS NULL OR
|
||||
payment_method IN ('full','mortgage','installment','advance')),
|
||||
tax_included VARCHAR(10)
|
||||
tax_included VARCHAR(10) -- 包税费方式：each_party=各付 / net=到手 / inclusive=包税
|
||||
CHECK (tax_included IS NULL OR
|
||||
tax_included IN ('each_party','net','inclusive')),
|
||||
has_mortgage BOOLEAN,
|
||||
has_loan BOOLEAN,
|
||||
has_seal BOOLEAN,
|
||||
has_restriction BOOLEAN,
|
||||
original_price NUMERIC(12,2), -- 原购价（万元）
|
||||
sale_reason TEXT, -- 售房原因（最多200字）
|
||||
has_mortgage BOOLEAN, -- 是否有抵押：true=有抵押 / false=无 / NULL=未确认
|
||||
has_loan BOOLEAN, -- 是否有贷款（未还清）：true=有 / false=无 / NULL=未确认
|
||||
has_seal BOOLEAN, -- 是否被查封：true=有查封 / false=无 / NULL=未确认
|
||||
has_restriction BOOLEAN, -- 是否有限制（其他限制）：true=有 / false=无 / NULL=未确认
|
||||
original_price NUMERIC(12,2), -- 原购价（万元；业主当年购入价，用于计算增值）
|
||||
sale_reason TEXT, -- 售房原因（业主出售理由，最多200字；如"置换"）
|
||||
|
||||
-- ── 营销备注 ──
|
||||
remarks TEXT, -- 房源备注（最多500字）
|
||||
remarks TEXT, -- 房源备注（经纪人内部备注，最多500字，不对外展示）
|
||||
|
||||
-- ── 相关方 ──
|
||||
first_recorder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 首录方
|
||||
number_holder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 号码方
|
||||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 出售方
|
||||
buyer_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 实买方
|
||||
first_recorder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 首录方（最初录入该房源的经纪人；人员离职后置 NULL）
|
||||
number_holder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 号码方（持有业主联系号码的经纪人；变更需走审批流）
|
||||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 出售方（负责出售跟进的经纪人）
|
||||
buyer_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 实买方（促成成交的买方经纪人）
|
||||
|
||||
-- ── 来源 ──
|
||||
source VARCHAR(50), -- 房源来源渠道（lookup_items 维护）
|
||||
source VARCHAR(50), -- 房源来源渠道（枚举值由 lookup_items 维护，如：门店拓客/转介绍/网络等）
|
||||
|
||||
-- ── 维护完成度（冗余缓存，Celery 定期重算）──
|
||||
completeness_score SMALLINT NOT NULL DEFAULT 0, -- 0-100
|
||||
completeness_score SMALLINT NOT NULL DEFAULT 0, -- 房源维护完成度评分（0-100；由 Celery 异步计算，非实时；前端列表页展示徽章）
|
||||
|
||||
-- ── 时间轨迹 ──
|
||||
listed_at TIMESTAMPTZ, -- 最近一次挂牌时间
|
||||
last_followed_at TIMESTAMPTZ, -- 最后跟进时间（冗余，加速排序）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
deleted_at TIMESTAMPTZ,
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
listed_at TIMESTAMPTZ, -- 最近一次挂牌时间（每次重新挂牌时更新）
|
||||
last_followed_at TIMESTAMPTZ, -- 最后跟进时间（冗余字段，由触发器自动维护，加速超时未跟进排序）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
deleted_at TIMESTAMPTZ, -- 软删除时间戳；NULL=未删除，非 NULL=已软删除
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 创建人（操作员工）
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 最后修改人（操作员工）
|
||||
|
||||
-- ── 全文检索向量 ──
|
||||
search_vector TSVECTOR,
|
||||
search_vector TSVECTOR, -- 全文检索向量（由触发器 trg_property_search_vector 自动维护，覆盖栋号/单元/房号/备注）
|
||||
|
||||
-- ── 乐观锁 ──
|
||||
version INTEGER NOT NULL DEFAULT 1 -- 每次 UPDATE 必须 +1；应用层检测 0 行受影响时抛 ConflictError
|
||||
version INTEGER NOT NULL DEFAULT 1 -- 乐观锁版本号（每次 UPDATE 必须 +1；应用层检测 0 行受影响时抛 ConflictError）
|
||||
);
|
||||
|
||||
-- ── 索引策略 ──
|
||||
@@ -389,38 +389,38 @@ CREATE INDEX idx_properties_my_properties ON properties
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE property_contacts (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表；房源删除时联级删除）
|
||||
|
||||
name VARCHAR(50) NOT NULL,
|
||||
gender VARCHAR(10) NOT NULL DEFAULT 'male'
|
||||
name VARCHAR(50) NOT NULL, -- 联系人姓名（如"张先生"；业主或其代理人的真实姓名）
|
||||
gender VARCHAR(10) NOT NULL DEFAULT 'male' -- 性别：male=先生 / female=女士；默认先生
|
||||
CHECK (gender IN ('male','female')),
|
||||
identity VARCHAR(20) NOT NULL DEFAULT 'contact'
|
||||
identity VARCHAR(20) NOT NULL DEFAULT 'contact' -- 联系人身份：owner=业主 / contact=联系人 / subletter=二房东 / tenant=租客 / agent=代理人 / corporate=企业法人；默认联系人
|
||||
CHECK (identity IN ('owner','contact','subletter',
|
||||
'tenant','agent','corporate')),
|
||||
-- owner=业主, contact=联系人, subletter=二房东, tenant=租客,
|
||||
-- agent=代理人, corporate=企业法人
|
||||
|
||||
-- 手机号：加密存储 + 哈希索引
|
||||
phone_enc BYTEA NOT NULL, -- AES-256-GCM 加密
|
||||
phone_hash VARCHAR(64) NOT NULL, -- SHA-256(phone)，去重查询
|
||||
phone2_enc BYTEA,
|
||||
phone2_hash VARCHAR(64),
|
||||
phone_enc BYTEA NOT NULL, -- 手机号1密文（AES-256-GCM 加密，不可直接查询）
|
||||
phone_hash VARCHAR(64) NOT NULL, -- 手机号1哈希（SHA-256，用于重复房源检测和精确查询）
|
||||
phone2_enc BYTEA, -- 手机号2密文（AES-256-GCM 加密；选填）
|
||||
phone2_hash VARCHAR(64), -- 手机号2哈希（SHA-256；phone2_enc 存在时必填）
|
||||
|
||||
wechat VARCHAR(100),
|
||||
qq VARCHAR(20),
|
||||
remarks TEXT,
|
||||
wechat VARCHAR(100), -- 微信号（选填；无数据时前端展示"-"）
|
||||
qq VARCHAR(20), -- QQ号（选填；无数据时前端展示"-"）
|
||||
remarks TEXT, -- 备注（最多200字；补充说明联系人情况）
|
||||
|
||||
-- 号码方标记（关联审批流）
|
||||
is_number_holder BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
number_holder_approved_at TIMESTAMPTZ,
|
||||
is_number_holder BOOLEAN NOT NULL DEFAULT FALSE, -- 是否为号码方：true=是号码方（审批通过）/ false=否；号码方变更须走审批流
|
||||
number_holder_approved_at TIMESTAMPTZ, -- 号码方审批通过时间；NULL=尚未成为号码方
|
||||
|
||||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
deleted_at TIMESTAMPTZ,
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
sort_order INTEGER NOT NULL DEFAULT 0, -- 排序权重（数值越小越靠前；控制联系人在面板中的显示顺序）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
deleted_at TIMESTAMPTZ, -- 软删除时间戳；NULL=未删除，非 NULL=已软删除
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 创建人（操作员工）
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 最后修改人（操作员工）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_contacts_property ON property_contacts(property_id)
|
||||
@@ -444,33 +444,33 @@ CREATE INDEX idx_contacts_phone2_hash ON property_contacts(phone2_hash)
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE listing_histories (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT, -- 所属房源（关联 properties 表；禁止级联删除，保留历史）
|
||||
|
||||
listing_type VARCHAR(20) NOT NULL
|
||||
listing_type VARCHAR(20) NOT NULL -- 挂牌类型：for_sale=出售挂牌 / for_rent=出租挂牌
|
||||
CHECK (listing_type IN ('for_sale','for_rent')),
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active'
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active' -- 挂牌状态：active=挂牌中 / ended=已结束
|
||||
CHECK (status IN ('active','ended')),
|
||||
|
||||
-- 价格快照
|
||||
sale_price NUMERIC(12,2),
|
||||
rent_price NUMERIC(10,2),
|
||||
sale_unit_price NUMERIC(10,2), -- 元/m²，计算字段
|
||||
sale_price NUMERIC(12,2), -- 本次挂牌售价快照（万元；出售挂牌时记录）
|
||||
rent_price NUMERIC(10,2), -- 本次挂牌租价快照（元/月；出租挂牌时记录）
|
||||
sale_unit_price NUMERIC(10,2), -- 本次挂牌售价单价（元/m²；由 sale_price ÷ area 计算后存储）
|
||||
|
||||
-- 交易信息快照
|
||||
ownership_years VARCHAR(30),
|
||||
is_only_house BOOLEAN,
|
||||
tax_included VARCHAR(10),
|
||||
sale_reason TEXT,
|
||||
ownership_years VARCHAR(30), -- 本次挂牌时的房本年限快照（如"满2年"）
|
||||
is_only_house BOOLEAN, -- 本次挂牌时的唯一住房状态快照
|
||||
tax_included VARCHAR(10), -- 本次挂牌时的包税费方式快照（each_party=各付 / net=到手 / inclusive=包税）
|
||||
sale_reason TEXT, -- 本次挂牌时的售房原因快照
|
||||
|
||||
-- 经纪人快照（防止人员变动后丢失历史数据）
|
||||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
seller_agent_snapshot JSONB, -- {name, store_group, org_unit_name}
|
||||
seller_agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 本次挂牌的出售经纪人（人员离职后置 NULL，但 snapshot 保留）
|
||||
seller_agent_snapshot JSONB, -- 出售经纪人快照（{name, store_group, org_unit_name}；防止人员变动后数据丢失）
|
||||
|
||||
started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
ended_at TIMESTAMPTZ,
|
||||
started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 本次挂牌开始时间
|
||||
ended_at TIMESTAMPTZ, -- 本次挂牌结束时间；NULL=当前仍在挂牌中
|
||||
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 记录创建时间（系统自动）
|
||||
-- 无 deleted_at：此表记录不可删除
|
||||
);
|
||||
|
||||
@@ -489,21 +489,21 @@ CREATE INDEX idx_listing_histories_active ON listing_histories(property_id)
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE price_changes (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE RESTRICT, -- 所属房源（关联 properties 表；禁止级联删除，保留调价历史）
|
||||
|
||||
old_sale_price NUMERIC(12,2),
|
||||
new_sale_price NUMERIC(12,2),
|
||||
old_bottom_price NUMERIC(12,2),
|
||||
new_bottom_price NUMERIC(12,2),
|
||||
old_record_price NUMERIC(12,2),
|
||||
new_record_price NUMERIC(12,2),
|
||||
old_rent_price NUMERIC(10,2),
|
||||
new_rent_price NUMERIC(10,2),
|
||||
old_sale_price NUMERIC(12,2), -- 调价前挂牌售价（万元；NULL=首次定价）
|
||||
new_sale_price NUMERIC(12,2), -- 调价后挂牌售价（万元）
|
||||
old_bottom_price NUMERIC(12,2), -- 调价前售底价（万元；NULL=未设置）
|
||||
new_bottom_price NUMERIC(12,2), -- 调价后售底价（万元；NULL=本次不变更底价）
|
||||
old_record_price NUMERIC(12,2), -- 调价前备案/核验价（万元；NULL=未设置）
|
||||
new_record_price NUMERIC(12,2), -- 调价后备案/核验价（万元；NULL=本次不变更）
|
||||
old_rent_price NUMERIC(10,2), -- 调价前挂牌租价（元/月；NULL=非出租类或未设置）
|
||||
new_rent_price NUMERIC(10,2), -- 调价后挂牌租价（元/月）
|
||||
|
||||
change_reason TEXT NOT NULL, -- 最多200字
|
||||
changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
changed_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT
|
||||
change_reason TEXT NOT NULL, -- 调价原因（必填，最多200字；如"业主主动降价"）
|
||||
changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 调价操作时间
|
||||
changed_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT -- 操作人（关联 staff 表；禁止置 NULL，保留审计追溯）
|
||||
-- 无 deleted_at：不可删除
|
||||
);
|
||||
|
||||
@@ -523,42 +523,42 @@ CREATE INDEX idx_price_changes_time ON price_changes(property_id, changed_at DES
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE follow_logs (
|
||||
id UUID NOT NULL DEFAULT gen_random_uuid(),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 分区键，必须在最前声明
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID NOT NULL DEFAULT gen_random_uuid(), -- 主键（与 created_at 组成复合主键，分区表要求）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（分区键，必须在最前声明；系统自动）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
log_type VARCHAR(30) NOT NULL
|
||||
log_type VARCHAR(30) NOT NULL -- 跟进日志类型：written=经纪人主动写入 / modified=字段变更自动生成 / sensitive_op=敏感操作跟进 / sensitive_view=敏感信息查看（不可删）/ other=其他 / system=系统日志
|
||||
CHECK (log_type IN ('written','modified','sensitive_op',
|
||||
'sensitive_view','other','system')),
|
||||
|
||||
-- 写入跟进专用字段
|
||||
purpose VARCHAR(50), -- 跟进目的（lookup_items 维护）
|
||||
content TEXT, -- 最少6字，最多500字
|
||||
purpose VARCHAR(50), -- 跟进目的（枚举值由 lookup_items 维护，如：电话/业主跟进/议价/带看；仅 written 类型使用）
|
||||
content TEXT, -- 跟进内容（最少6字，最多500字；仅 written 类型必填）
|
||||
|
||||
-- AI 辅助判断标签
|
||||
ai_tag VARCHAR(20)
|
||||
ai_tag VARCHAR(20) -- AI 辅助标签：ai_for_sale=AI判断业主在售 / ai_not_for_sale=AI判断业主不售；由系统根据跟进内容智能分析后打标
|
||||
CHECK (ai_tag IS NULL OR ai_tag IN ('ai_for_sale','ai_not_for_sale')),
|
||||
|
||||
-- 修改跟进专用字段
|
||||
change_detail JSONB,
|
||||
change_detail JSONB, -- 字段变更明细（格式：{\"field\": \"sale_price\", \"old\": 850, \"new\": 800, \"label\": \"售价\"}；modified 类型使用）
|
||||
-- 格式：{"field": "sale_price", "old": 850, "new": 800, "label": "售价"}
|
||||
|
||||
-- 系统显示标签
|
||||
log_tag VARCHAR(50),
|
||||
log_tag VARCHAR(50), -- 前端展示标签（如：查看号码/图片下载/改状态/改价格/改等级/修改相关方；对应跟进日志时间线显示的【方括号标签】）
|
||||
-- 如：查看号码/图片下载/改状态/改价格/改等级/修改相关方
|
||||
|
||||
-- 可见性控制
|
||||
is_public BOOLEAN NOT NULL DEFAULT TRUE,
|
||||
is_public BOOLEAN NOT NULL DEFAULT TRUE, -- 是否公开：true=全员可见 / false=仅本人及上级可见
|
||||
-- FALSE = 仅本人及上级可见
|
||||
|
||||
-- 操作人
|
||||
operator_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
operator_snapshot JSONB, -- {name, role, org_unit_name, store_group}
|
||||
operator_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 操作人（关联 staff 表；人员离职后置 NULL，但 snapshot 保留）
|
||||
operator_snapshot JSONB, -- 操作人快照（{name, role, org_unit_name, store_group}；防止人员离职后丢失显示信息）
|
||||
|
||||
-- 是否可删除（sensitive_view = FALSE，合规强制）
|
||||
is_deletable BOOLEAN NOT NULL DEFAULT TRUE,
|
||||
is_deletable BOOLEAN NOT NULL DEFAULT TRUE, -- 是否可软删除：false=敏感信息查看类型，合规要求不可删除
|
||||
|
||||
deleted_at TIMESTAMPTZ, -- 仅 is_deletable=TRUE 时可软删
|
||||
deleted_at TIMESTAMPTZ, -- 软删除时间戳；仅 is_deletable=TRUE 时可软删；NULL=未删除
|
||||
|
||||
PRIMARY KEY (id, created_at) -- 分区表主键必须包含分区键
|
||||
) PARTITION BY RANGE (created_at);
|
||||
@@ -595,16 +595,16 @@ CREATE INDEX idx_follow_logs_sensitive ON follow_logs(property_id, created_at DE
|
||||
|
||||
```sql
|
||||
CREATE TABLE follow_log_attachments (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE, -- 所属跟进日志（关联 follow_logs 表；日志删除时联级删除）
|
||||
|
||||
file_key TEXT NOT NULL, -- Cloudflare R2 存储路径
|
||||
file_name VARCHAR(255) NOT NULL,
|
||||
file_size INTEGER NOT NULL, -- bytes
|
||||
file_type VARCHAR(10)
|
||||
file_key TEXT NOT NULL, -- 图片存储路径（Cloudflare R2 对象路径）
|
||||
file_name VARCHAR(255) NOT NULL, -- 原始文件名（用户上传时的文件名）
|
||||
file_size INTEGER NOT NULL, -- 文件大小（bytes；最大 20MB = 20971520）
|
||||
file_type VARCHAR(10) -- 文件格式：bmp / jpg / png / svg / gif（PRD 限定格式）
|
||||
CHECK (file_type IN ('bmp','jpg','png','svg','gif')),
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0, -- 排序权重（控制同一跟进附件的显示顺序）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 上传时间（系统自动）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_follow_attachments_log ON follow_log_attachments(follow_log_id);
|
||||
@@ -616,12 +616,12 @@ CREATE INDEX idx_follow_attachments_log ON follow_log_attachments(follow_log_id)
|
||||
|
||||
```sql
|
||||
CREATE TABLE follow_log_recordings (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
follow_log_id UUID NOT NULL REFERENCES follow_logs(id) ON DELETE CASCADE, -- 所属跟进日志（关联 follow_logs 表；日志删除时联级删除）
|
||||
|
||||
file_key TEXT NOT NULL, -- Cloudflare R2 存储路径
|
||||
duration_seconds INTEGER, -- 录音时长（秒）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
file_key TEXT NOT NULL, -- 录音文件存储路径（Cloudflare R2 对象路径）
|
||||
duration_seconds INTEGER, -- 录音时长（秒；可空，上传时若能解析则填写）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 上传时间（系统自动）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_follow_recordings_log ON follow_log_recordings(follow_log_id);
|
||||
@@ -633,27 +633,27 @@ CREATE INDEX idx_follow_recordings_log ON follow_log_recordings(follow_log_id);
|
||||
|
||||
```sql
|
||||
CREATE TABLE property_keys (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
key_type VARCHAR(20) NOT NULL
|
||||
key_type VARCHAR(20) NOT NULL -- 钥匙类型：mechanical=机械钥匙 / password=密码（如密码门锁）
|
||||
CHECK (key_type IN ('mechanical','password')),
|
||||
|
||||
-- 钥匙持有方
|
||||
holder_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
holder_snapshot JSONB, -- {name, store_group}
|
||||
storage_unit_id UUID REFERENCES org_units(id) ON DELETE SET NULL, -- 保管部门
|
||||
holder_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 持有人（关联 staff 表；人员离职后置 NULL）
|
||||
holder_snapshot JSONB, -- 持有人快照（{name, store_group}；防止人员离职后丢失显示信息）
|
||||
storage_unit_id UUID REFERENCES org_units(id) ON DELETE SET NULL, -- 保管部门（关联 org_units 表；钥匙存放在哪个部门）
|
||||
|
||||
-- 他司钥匙标记
|
||||
is_other_agency BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
other_agency_info VARCHAR(30), -- 最多30字
|
||||
is_other_agency BOOLEAN NOT NULL DEFAULT FALSE, -- 是否为他中介公司的钥匙：true=是他司钥匙 / false=本司钥匙
|
||||
other_agency_info VARCHAR(30), -- 他司中介信息（最多30字；is_other_agency=true 时填写，如"链家"）
|
||||
|
||||
remarks TEXT, -- 最多200字
|
||||
remarks TEXT, -- 备注（最多200字；如密码内容等补充说明）
|
||||
|
||||
is_active BOOLEAN NOT NULL DEFAULT TRUE, -- FALSE=已归还/失效
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
is_active BOOLEAN NOT NULL DEFAULT TRUE, -- 是否有效：true=在管中 / false=已归还或失效
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 创建人（操作员工）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_property_keys_property ON property_keys(property_id)
|
||||
@@ -666,12 +666,12 @@ CREATE INDEX idx_property_keys_property ON property_keys(property_id)
|
||||
|
||||
```sql
|
||||
CREATE TABLE key_attachments (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
key_id UUID NOT NULL REFERENCES property_keys(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
key_id UUID NOT NULL REFERENCES property_keys(id) ON DELETE CASCADE, -- 所属钥匙记录（关联 property_keys 表；钥匙删除时联级删除）
|
||||
|
||||
file_key TEXT NOT NULL,
|
||||
file_name VARCHAR(255) NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
file_key TEXT NOT NULL, -- 附件存储路径（Cloudflare R2 对象路径）
|
||||
file_name VARCHAR(255) NOT NULL, -- 原始文件名
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 上传时间（系统自动）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_key_attachments_key ON key_attachments(key_id);
|
||||
@@ -683,37 +683,37 @@ CREATE INDEX idx_key_attachments_key ON key_attachments(key_id);
|
||||
|
||||
```sql
|
||||
CREATE TABLE commissions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
commission_type VARCHAR(50) NOT NULL, -- 独家委托/非独家委托（lookup_items 维护）
|
||||
period_start DATE NOT NULL,
|
||||
period_end DATE,
|
||||
is_open_ended BOOLEAN NOT NULL DEFAULT FALSE, -- 无固定结束日期
|
||||
commission_type VARCHAR(50) NOT NULL, -- 委托类型（独家委托/非独家委托；由 lookup_items 维护）
|
||||
period_start DATE NOT NULL, -- 委托开始日期
|
||||
period_end DATE, -- 委托结束日期（is_open_ended=true 时为 NULL）
|
||||
is_open_ended BOOLEAN NOT NULL DEFAULT FALSE, -- 是否无固定结束日期：true=长期委托 / false=有截止日期
|
||||
|
||||
-- 委托经纪人
|
||||
agent_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
agent_snapshot JSONB, -- {name, store_group}
|
||||
agent_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 委托经纪人（关联 staff 表；人员离职后置 NULL）
|
||||
agent_snapshot JSONB, -- 经纪人快照（{name, store_group}；防止人员变动后数据丢失）
|
||||
|
||||
signing_method VARCHAR(50), -- 签约方式（选择后动态展示委托书模板）
|
||||
|
||||
-- 委托人（产权人）信息
|
||||
owner_type VARCHAR(20) NOT NULL DEFAULT 'owner'
|
||||
owner_type VARCHAR(20) NOT NULL DEFAULT 'owner' -- 委托人类型：owner=产权人本人 / authorized_third=被授权第三方
|
||||
CHECK (owner_type IN ('owner','authorized_third')),
|
||||
property_owner_contact_id UUID REFERENCES property_contacts(id) ON DELETE SET NULL,
|
||||
owner_name VARCHAR(50),
|
||||
owner_id_type VARCHAR(20), -- 身份证/护照 等
|
||||
owner_id_number VARCHAR(50), -- 证件号（明文，仅供参考）
|
||||
owner_id_number_enc BYTEA, -- 证件号 AES-256-GCM 加密
|
||||
property_owner_contact_id UUID REFERENCES property_contacts(id) ON DELETE SET NULL, -- 关联联系人（property_contacts 表；若委托人已录入联系人）
|
||||
owner_name VARCHAR(50), -- 委托人姓名
|
||||
owner_id_type VARCHAR(20), -- 委托人证件类型（如：身份证/护照）
|
||||
owner_id_number VARCHAR(50), -- 委托人证件号明文（仅供参考，加密版本见下方）
|
||||
owner_id_number_enc BYTEA, -- 委托人证件号密文（AES-256-GCM 加密）
|
||||
|
||||
remarks TEXT, -- 最多200字
|
||||
remarks TEXT, -- 备注（最多200字）
|
||||
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active'
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active' -- 委托状态：active=有效 / expired=已过期 / cancelled=已取消
|
||||
CHECK (status IN ('active','expired','cancelled')),
|
||||
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 创建人（操作员工）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_commissions_property ON commissions(property_id);
|
||||
@@ -727,17 +727,17 @@ CREATE INDEX idx_commissions_active ON commissions(property_id)
|
||||
|
||||
```sql
|
||||
CREATE TABLE commission_attachments (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
commission_id UUID NOT NULL REFERENCES commissions(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
commission_id UUID NOT NULL REFERENCES commissions(id) ON DELETE CASCADE, -- 所属委托（关联 commissions 表；委托删除时联级删除）
|
||||
|
||||
category VARCHAR(20) NOT NULL
|
||||
category VARCHAR(20) NOT NULL -- 附件分类：id_card=身份证 / property_cert=产权证书 / commission_letter=委托书 / other=其他材料
|
||||
CHECK (category IN ('id_card','property_cert',
|
||||
'commission_letter','other')),
|
||||
file_key TEXT NOT NULL,
|
||||
file_name VARCHAR(255) NOT NULL,
|
||||
file_size INTEGER,
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
file_key TEXT NOT NULL, -- 附件存储路径（Cloudflare R2 对象路径）
|
||||
file_name VARCHAR(255) NOT NULL, -- 原始文件名
|
||||
file_size INTEGER, -- 文件大小（bytes）
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0, -- 排序权重（数值越小越靠前）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 上传时间（系统自动）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_commission_attachments_commission ON commission_attachments(commission_id);
|
||||
@@ -749,23 +749,23 @@ CREATE INDEX idx_commission_attachments_commission ON commission_attachments(com
|
||||
|
||||
```sql
|
||||
CREATE TABLE field_surveys (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'draft'
|
||||
status VARCHAR(10) NOT NULL DEFAULT 'draft' -- 实勘状态：draft=草稿（未提交）/ submitted=已提交（已完成）
|
||||
CHECK (status IN ('draft','submitted')),
|
||||
|
||||
-- GPS 定位（实勘打卡）
|
||||
gps_latitude NUMERIC(10,7),
|
||||
gps_longitude NUMERIC(10,7),
|
||||
gps_accuracy NUMERIC(6,2), -- 精度（米）
|
||||
gps_latitude NUMERIC(10,7), -- GPS 纬度（实勘打卡位置；精度7位小数）
|
||||
gps_longitude NUMERIC(10,7), -- GPS 经度（实勘打卡位置；精度7位小数）
|
||||
gps_accuracy NUMERIC(6,2), -- GPS 精度（米；标注定位误差）
|
||||
|
||||
description TEXT, -- 实勘说明，最多200字
|
||||
description TEXT, -- 实勘说明（最多200字；经纪人现场情况描述）
|
||||
|
||||
submitted_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
created_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT
|
||||
submitted_at TIMESTAMPTZ, -- 提交时间（status 变为 submitted 时记录；NULL=尚未提交）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
created_by UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT -- 实勘人（操作员工；禁止置 NULL 保留审计）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_field_surveys_property ON field_surveys(property_id);
|
||||
@@ -779,22 +779,22 @@ CREATE INDEX idx_field_surveys_submitted ON field_surveys(property_id)
|
||||
|
||||
```sql
|
||||
CREATE TABLE survey_photos (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
survey_id UUID NOT NULL REFERENCES field_surveys(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
survey_id UUID NOT NULL REFERENCES field_surveys(id) ON DELETE CASCADE, -- 所属实勘（关联 field_surveys 表；实勘删除时联级删除）
|
||||
|
||||
category VARCHAR(20) NOT NULL
|
||||
category VARCHAR(20) NOT NULL -- 照片空间分类：layout=户型图 / living_room=客厅 / dining_room=餐厅 / bedroom=卧室 / bathroom=卫生间 / kitchen=厨房 / entrance=门厅 / balcony=阳台 / study=书房 / indoor_other=室内其他 / outdoor=外景
|
||||
CHECK (category IN ('layout','living_room','dining_room',
|
||||
'bedroom','bathroom','kitchen',
|
||||
'entrance','balcony','study',
|
||||
'indoor_other','outdoor')),
|
||||
file_key TEXT NOT NULL, -- Cloudflare R2 路径
|
||||
thumbnail_key TEXT, -- 缩略图路径
|
||||
file_size INTEGER,
|
||||
width INTEGER,
|
||||
height INTEGER,
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
is_vr_screenshot BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
file_key TEXT NOT NULL, -- 原图存储路径（Cloudflare R2 对象路径）
|
||||
thumbnail_key TEXT, -- 缩略图路径（Cloudflare Images 自动生成）
|
||||
file_size INTEGER, -- 文件大小（bytes）
|
||||
width INTEGER, -- 图片宽度（像素；上传时解析）
|
||||
height INTEGER, -- 图片高度（像素；上传时解析）
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0, -- 排序权重（同一空间分类内，数值越小越靠前）
|
||||
is_vr_screenshot BOOLEAN NOT NULL DEFAULT FALSE, -- 是否为VR截图：true=全景/VR截图（区别于普通实拍照片）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 上传时间（系统自动）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_survey_photos_survey ON survey_photos(survey_id);
|
||||
@@ -812,28 +812,28 @@ CREATE INDEX idx_survey_photos_category ON survey_photos(survey_id, category);
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE property_photos (
|
||||
id UUID NOT NULL DEFAULT gen_random_uuid(),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 分区键
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID NOT NULL DEFAULT gen_random_uuid(), -- 主键（与 created_at 组成复合主键，分区表要求）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 上传时间（分区键；系统自动）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
category VARCHAR(20) NOT NULL
|
||||
category VARCHAR(20) NOT NULL -- 照片分类：cover=封面 / entrance=门厅 / living_room=客厅 / dining_room=餐厅 / bedroom=卧室 / bathroom=卫生间 / kitchen=厨房 / balcony=阳台 / study=书房 / indoor_other=室内其他 / outdoor=外景 / panorama=全景
|
||||
CHECK (category IN ('cover','entrance','living_room',
|
||||
'dining_room','bedroom','bathroom',
|
||||
'kitchen','balcony','study',
|
||||
'indoor_other','outdoor','panorama')),
|
||||
|
||||
file_key TEXT NOT NULL, -- R2/S3 原图路径
|
||||
thumbnail_key TEXT, -- Cloudflare Images 生成的缩略图
|
||||
file_name VARCHAR(255),
|
||||
file_size INTEGER,
|
||||
width INTEGER,
|
||||
height INTEGER,
|
||||
file_key TEXT NOT NULL, -- 原图存储路径（Cloudflare R2/S3 对象路径）
|
||||
thumbnail_key TEXT, -- 缩略图路径（Cloudflare Images 自动生成）
|
||||
file_name VARCHAR(255), -- 原始文件名
|
||||
file_size INTEGER, -- 文件大小（bytes）
|
||||
width INTEGER, -- 图片宽度（像素；上传时解析）
|
||||
height INTEGER, -- 图片高度（像素；上传时解析）
|
||||
|
||||
is_cover BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
is_cover BOOLEAN NOT NULL DEFAULT FALSE, -- 是否为封面图：true=封面；每套房源只能有一张封面（唯一约束保证）
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0, -- 排序权重（同一房源内，数值越小越靠前）
|
||||
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 最后更新时间（系统自动）
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 上传人（操作员工）
|
||||
|
||||
PRIMARY KEY (id, created_at) -- 分区表主键必须包含分区键
|
||||
) PARTITION BY RANGE (created_at);
|
||||
@@ -861,21 +861,21 @@ CREATE UNIQUE INDEX idx_property_photos_unique_cover
|
||||
|
||||
```sql
|
||||
CREATE TABLE property_attachments (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
|
||||
category VARCHAR(20) NOT NULL DEFAULT 'other'
|
||||
category VARCHAR(20) NOT NULL DEFAULT 'other' -- 附件分类：id_card=身份证 / property_cert=产权证书 / commission_letter=委托书 / other=其他材料
|
||||
CHECK (category IN ('id_card','property_cert',
|
||||
'commission_letter','other')),
|
||||
|
||||
file_key TEXT NOT NULL,
|
||||
file_name VARCHAR(255) NOT NULL,
|
||||
file_size INTEGER NOT NULL,
|
||||
file_type VARCHAR(50), -- MIME type
|
||||
file_key TEXT NOT NULL, -- 附件存储路径（Cloudflare R2 对象路径）
|
||||
file_name VARCHAR(255) NOT NULL, -- 原始文件名
|
||||
file_size INTEGER NOT NULL, -- 文件大小（bytes）
|
||||
file_type VARCHAR(50), -- MIME 类型（如 application/pdf、image/jpeg）
|
||||
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
sort_order SMALLINT NOT NULL DEFAULT 0, -- 排序权重（控制同一房源附件的显示顺序）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 上传时间（系统自动）
|
||||
created_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 上传人（操作员工）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_property_attachments_property ON property_attachments(property_id);
|
||||
@@ -889,21 +889,21 @@ CREATE INDEX idx_property_attachments_category ON property_attachments(property_
|
||||
```sql
|
||||
-- 1:1 扩展表，营销标题/核心卖点/业主心态/户型介绍/小区介绍
|
||||
CREATE TABLE property_marketing (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（1:1 关联 properties 表）
|
||||
|
||||
marketing_title VARCHAR(30), -- 营销标题，0-30字
|
||||
core_selling_points TEXT, -- 核心卖点，最多200字
|
||||
owner_attitude TEXT, -- 业主心态，最多200字
|
||||
layout_description TEXT, -- 户型介绍，最多200字
|
||||
complex_description TEXT, -- 小区介绍，最多200字
|
||||
marketing_title VARCHAR(30), -- 营销标题（0-30字；前端发房时展示给买家的吸睛标题）
|
||||
core_selling_points TEXT, -- 核心卖点（最多200字；展示给买家的重点卖点说明）
|
||||
owner_attitude TEXT, -- 业主心态（最多200字；仅内部可见，描述业主议价空间和心理状态）
|
||||
layout_description TEXT, -- 户型介绍（最多200字；房源户型特点描述，面向买家展示）
|
||||
complex_description TEXT, -- 小区介绍（最多200字；楼盘/小区周边配套描述）
|
||||
|
||||
-- AI 生成标记
|
||||
ai_generated_points BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
ai_generated_attitude BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
ai_generated_points BOOLEAN NOT NULL DEFAULT FALSE, -- 核心卖点是否由 AI 生成：true=AI辅助生成（经纪人确认后使用）
|
||||
ai_generated_attitude BOOLEAN NOT NULL DEFAULT FALSE, -- 业主心态是否由 AI 生成：true=AI辅助生成
|
||||
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 最后更新时间（系统自动）
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 最后修改人（操作员工）
|
||||
);
|
||||
```
|
||||
|
||||
@@ -914,22 +914,22 @@ CREATE TABLE property_marketing (
|
||||
```sql
|
||||
-- 1:1 扩展表，存储产权证相关信息
|
||||
CREATE TABLE property_certificates (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（1:1 关联 properties 表）
|
||||
|
||||
owner_name VARCHAR(100),
|
||||
owner_id_number VARCHAR(50), -- 身份证号/统一社会信用代码
|
||||
owner_cert_type VARCHAR(20), -- 身份证/护照/营业执照
|
||||
property_location VARCHAR(500), -- 房屋坐落（产权证书上的地址），最多50字
|
||||
owner_name VARCHAR(100), -- 产权人姓名（产权证书上登记的所有权人）
|
||||
owner_id_number VARCHAR(50), -- 证件号码（身份证号/统一社会信用代码等）
|
||||
owner_cert_type VARCHAR(20), -- 证件类型（如：身份证/护照/营业执照）
|
||||
property_location VARCHAR(500), -- 房屋坐落（产权证书上的完整地址，最多500字）
|
||||
|
||||
cert_status VARCHAR(30), -- 产证状态
|
||||
cert_no VARCHAR(100), -- 产证号
|
||||
first_registered_at DATE, -- 首次登记时间
|
||||
ownership_nature VARCHAR(30), -- 权属性质
|
||||
land_nature VARCHAR(30), -- 土地性质
|
||||
cert_status VARCHAR(30), -- 产证状态（如：已过户/抵押中/查封/正常）
|
||||
cert_no VARCHAR(100), -- 产权证号（不动产权证书编号）
|
||||
first_registered_at DATE, -- 首次登记时间（产权证上的初始登记日期）
|
||||
ownership_nature VARCHAR(30), -- 权属性质（如：商品房/经济适用房/回迁房）
|
||||
land_nature VARCHAR(30), -- 土地性质（如：国有/集体/划拨/出让）
|
||||
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 最后更新时间（系统自动）
|
||||
updated_by UUID REFERENCES staff(id) ON DELETE SET NULL -- 最后修改人（操作员工）
|
||||
);
|
||||
```
|
||||
|
||||
@@ -945,22 +945,22 @@ CREATE TABLE property_certificates (
|
||||
-- ============================================================
|
||||
|
||||
CREATE TABLE property_completeness (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（1:1 关联 properties 表）
|
||||
|
||||
score_core_info SMALLINT NOT NULL DEFAULT 0, -- 重点信息 满分8
|
||||
score_attachment SMALLINT NOT NULL DEFAULT 0, -- 附件 满分8
|
||||
score_survey SMALLINT NOT NULL DEFAULT 0, -- 实勘 满分16
|
||||
score_vr SMALLINT NOT NULL DEFAULT 0, -- VR 满分8
|
||||
score_key SMALLINT NOT NULL DEFAULT 0, -- 钥匙 满分10
|
||||
score_commission SMALLINT NOT NULL DEFAULT 0, -- 委托 满分10
|
||||
score_verification SMALLINT NOT NULL DEFAULT 0, -- 验证 满分7
|
||||
score_follow_up SMALLINT NOT NULL DEFAULT 0, -- 跟进 满分8
|
||||
score_viewing SMALLINT NOT NULL DEFAULT 0, -- 带看 满分8
|
||||
score_other SMALLINT NOT NULL DEFAULT 0, -- 其他 满分7
|
||||
total_score SMALLINT NOT NULL DEFAULT 0, -- 总分 0-100
|
||||
score_core_info SMALLINT NOT NULL DEFAULT 0, -- 重点信息得分（满分8；包含房源核心字段完整度）
|
||||
score_attachment SMALLINT NOT NULL DEFAULT 0, -- 附件得分（满分8；身份证/产权证/委托书等材料上传情况）
|
||||
score_survey SMALLINT NOT NULL DEFAULT 0, -- 实勘得分（满分16；实勘照片和报告完整度）
|
||||
score_vr SMALLINT NOT NULL DEFAULT 0, -- VR得分（满分8；VR/全景照片上传情况）
|
||||
score_key SMALLINT NOT NULL DEFAULT 0, -- 钥匙得分（满分10；钥匙托管情况）
|
||||
score_commission SMALLINT NOT NULL DEFAULT 0, -- 委托得分（满分10；独家/普通委托书情况）
|
||||
score_verification SMALLINT NOT NULL DEFAULT 0, -- 验证得分（满分7；房源信息核实情况）
|
||||
score_follow_up SMALLINT NOT NULL DEFAULT 0, -- 跟进得分（满分8；近期跟进记录情况）
|
||||
score_viewing SMALLINT NOT NULL DEFAULT 0, -- 带看得分（满分8；带看记录完整度）
|
||||
score_other SMALLINT NOT NULL DEFAULT 0, -- 其他得分（满分7；其他加分项）
|
||||
total_score SMALLINT NOT NULL DEFAULT 0, -- 维护完成度总分（0-100；供列表排序用，与 properties.completeness_score 冗余）
|
||||
|
||||
calculated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
calculated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 最近一次异步计算完成时间
|
||||
);
|
||||
```
|
||||
|
||||
@@ -971,18 +971,18 @@ CREATE TABLE property_completeness (
|
||||
```sql
|
||||
-- 标签字典（系统预置 + 运营自定义）
|
||||
CREATE TABLE property_tags (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
name VARCHAR(50) NOT NULL,
|
||||
color VARCHAR(7), -- HEX 颜色，如 #FF5733
|
||||
is_system BOOLEAN NOT NULL DEFAULT FALSE, -- 系统预置标签不可删除
|
||||
sort_order INTEGER NOT NULL DEFAULT 0,
|
||||
is_active BOOLEAN NOT NULL DEFAULT TRUE
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
name VARCHAR(50) NOT NULL, -- 标签名称（最多50字；如：学区/地铁口/满五唯一）
|
||||
color VARCHAR(7), -- 显示颜色（HEX 色值，如 #FF5733；前端标签徽章颜色）
|
||||
is_system BOOLEAN NOT NULL DEFAULT FALSE, -- 是否系统预置：true=系统内置标签不可删除；false=运营自定义标签可删
|
||||
sort_order INTEGER NOT NULL DEFAULT 0, -- 排序权重（数值越小越靠前）
|
||||
is_active BOOLEAN NOT NULL DEFAULT TRUE -- 是否启用：false=已停用不再展示
|
||||
);
|
||||
|
||||
-- 房源 ↔ 标签 多对多
|
||||
CREATE TABLE property_tag_relations (
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
tag_id UUID NOT NULL REFERENCES property_tags(id) ON DELETE CASCADE,
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
tag_id UUID NOT NULL REFERENCES property_tags(id) ON DELETE CASCADE, -- 所属标签（关联 property_tags 表）
|
||||
PRIMARY KEY (property_id, tag_id)
|
||||
);
|
||||
|
||||
@@ -997,9 +997,9 @@ CREATE INDEX idx_property_tags_tag ON property_tag_relations(tag_id);
|
||||
```sql
|
||||
-- 经纪人收藏房源（快速访问）
|
||||
CREATE TABLE property_favorites (
|
||||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE,
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
staff_id UUID NOT NULL REFERENCES staff(id) ON DELETE CASCADE, -- 收藏人（关联 staff 表；员工注销时删除收藏记录）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 收藏的房源（关联 properties 表）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 收藏时间（系统自动）
|
||||
PRIMARY KEY (staff_id, property_id)
|
||||
);
|
||||
|
||||
@@ -1013,15 +1013,15 @@ CREATE INDEX idx_property_favorites_staff ON property_favorites(staff_id);
|
||||
```sql
|
||||
-- 1:1，标记某套房源是否受保护（防止被他人抢单/公盘化）
|
||||
CREATE TABLE property_protections (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL UNIQUE REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（1:1 关联 properties 表）
|
||||
|
||||
is_protected BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
reason TEXT,
|
||||
start_at TIMESTAMPTZ,
|
||||
end_at TIMESTAMPTZ,
|
||||
set_by UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
is_protected BOOLEAN NOT NULL DEFAULT FALSE, -- 是否处于保护状态：true=受保护（防止被他人抢单/公盘化）/ false=未保护
|
||||
reason TEXT, -- 保护原因（说明为何启用保护）
|
||||
start_at TIMESTAMPTZ, -- 保护开始时间（NULL=尚未生效）
|
||||
end_at TIMESTAMPTZ, -- 保护到期时间（NULL=长期保护）
|
||||
set_by UUID REFERENCES staff(id) ON DELETE SET NULL, -- 设置人（关联 staff 表；人员离职后置 NULL）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- 记录创建时间（系统自动）
|
||||
);
|
||||
```
|
||||
|
||||
@@ -1032,19 +1032,19 @@ CREATE TABLE property_protections (
|
||||
```sql
|
||||
-- 号码方变更审批流：经纪人申请，上级审批
|
||||
CREATE TABLE number_holder_approvals (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE,
|
||||
contact_id UUID NOT NULL REFERENCES property_contacts(id) ON DELETE CASCADE,
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成，业务无关）
|
||||
property_id UUID NOT NULL REFERENCES properties(id) ON DELETE CASCADE, -- 所属房源（关联 properties 表）
|
||||
contact_id UUID NOT NULL REFERENCES property_contacts(id) ON DELETE CASCADE, -- 申请变更的联系方（关联 property_contacts 表；即号码方）
|
||||
|
||||
applicant_id UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT,
|
||||
approver_id UUID REFERENCES staff(id) ON DELETE SET NULL,
|
||||
applicant_id UUID NOT NULL REFERENCES staff(id) ON DELETE RESTRICT, -- 申请人（关联 staff 表；提交号码方变更申请的经纪人；禁止置 NULL 保留审计）
|
||||
approver_id UUID REFERENCES staff(id) ON DELETE SET NULL, -- 审批人（关联 staff 表；上级审批人；审批前为 NULL）
|
||||
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'pending'
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'pending' -- 审批状态：pending=待审批 / approved=已通过 / rejected=已驳回
|
||||
CHECK (status IN ('pending','approved','rejected')),
|
||||
remarks TEXT,
|
||||
remarks TEXT, -- 审批备注（审批人填写的意见或驳回原因）
|
||||
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
decided_at TIMESTAMPTZ
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 申请提交时间（系统自动）
|
||||
decided_at TIMESTAMPTZ -- 审批决定时间（NULL=尚未审批）
|
||||
);
|
||||
|
||||
CREATE INDEX idx_number_holder_approvals_status ON number_holder_approvals(status)
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
## 你的角色与约束
|
||||
你是一名资深 Django 后端工程师。你的任务是**严格按照规范**搭建 Fonrey 项目骨架，不得自行发明技术方案，不得引入文档未授权的第三方库。每一步操作后必须验证结果。
|
||||
**项目工作目录**：`/mnt/c/Project/`（在此目录下创建 `fonrey/` 子目录）
|
||||
**所有文档目录**：`/mnt/d/Workspace/nexus/Project/fonrey/`
|
||||
**执行方式**：逐步创建，每创建一个文件/目录后立即验证，遇到冲突停下来询问而不是自行决策。
|
||||
---
|
||||
## 一、技术栈约束（必读，不得违反）
|
||||
@@ -846,7 +847,7 @@ addopts = "--reuse-db --cov=apps --cov=core --cov-report=term-missing -n auto"
|
||||
|
||||
- [ ] **路径与方法**：端点路径/HTTP Method 与 `TECH_STACK/API_CONTRACT.md` 及模块文档一致
|
||||
- [ ] **请求参数**：query/path/body 字段名、类型、必填/可选与契约一致
|
||||
- [ ] **响应 envelope**：成功返回 `ok=true` + `data` + `meta`；失败返回 `ok=false` + `error` + `code` + `details` + `meta`
|
||||
- [ ] **响应 envelope**：成功返回 `ok=true` + `data` + `meta`；失败返回 `ok=false` + `error` + `code` + `details` + `meta`
|
||||
- [ ] **错误码**：`code` 使用稳定 `UPPER_SNAKE_CASE`，并与模块前缀语义一致
|
||||
- [ ] **OpenAPI 注解**：视图补齐 `@extend_schema`（或 `@extend_schema_view`）
|
||||
- [ ] **Schema 文件**：可执行 `python manage.py spectacular --file openapi.json` 成功生成
|
||||
|
||||
232
Project/fonrey/实施报告/项目进度交接报告_Phase4.0_收尾.md
Normal file
232
Project/fonrey/实施报告/项目进度交接报告_Phase4.0_收尾.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 项目进度交接报告 — Phase 4.0 收尾
|
||||
|
||||
> **作者**: Backend Engineer
|
||||
> **日期**: 2026-04-29
|
||||
> **状态**: 暂停，等待 PM 完成 DATA_MODEL 注释补全
|
||||
> **续接者**: 明天继续工作的自己 / 其他工程师
|
||||
> **前序文档**: [`项目骨架搭建实施报告_v1.md`](./项目骨架搭建实施报告_v1.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、今日完成事项
|
||||
|
||||
### 1.1 Phase 4.0：所有模型添加中文 Meta 名
|
||||
|
||||
**git commit**: `79c3cf2 feat(models): add Chinese verbose_name to all 74 models (Phase 4.0)`
|
||||
|
||||
**变更范围**：
|
||||
- 20 个 models 文件
|
||||
- 8 个 0002/0003 迁移文件（Meta options 变更）
|
||||
- 1 个 tenant 0001_initial 迁移（之前漏生成）
|
||||
- 共计 29 文件 / +594 行
|
||||
|
||||
**具体内容**：为全部 74 个 Django 模型添加：
|
||||
```python
|
||||
class Meta:
|
||||
verbose_name = "中文表名"
|
||||
verbose_name_plural = "中文表名"
|
||||
# ... 已有的 db_table / indexes / constraints 保留
|
||||
```
|
||||
|
||||
**消费方**：
|
||||
- Django Admin 列表页/表单页中文显示
|
||||
- drf-spectacular 生成 OpenAPI 时映射为 `tag` / 模型名
|
||||
- Django shell 报错信息使用中文
|
||||
|
||||
**验证**：`manage.py check` 0 issues。
|
||||
|
||||
### 1.2 PM 规范文档交付
|
||||
|
||||
**文件**: `/mnt/d/Workspace/nexus/Project/fonrey/规范/DATA_MODEL_注释补全规范_v1.md`（443 行，12 章）
|
||||
|
||||
**核心内容**：
|
||||
- §四 技术元数据字段标准注释库（id / created_at / deleted_at / version 等的统一中文注释）
|
||||
- §五 业务字段三段式格式（中文名 + 示例 + 业务规则）
|
||||
- §六 枚举字段中英对照规范
|
||||
- §七 外键字段说明规范
|
||||
- §九 PM 待办清单（8 个 DATA_MODEL_*.md 文件、当前覆盖率、补全优先级）
|
||||
- §十一 完整规范表的范例（properties 表）
|
||||
|
||||
**PM 工作量估算**：1-2 天
|
||||
|
||||
**关键决策（澄清）**：
|
||||
- 之前误判 REGION/TENANT/RELEASE/ACCOUNT 缺独立文件 — **实际上没缺**：
|
||||
- REGION（districts 表）已在 `DATA_MODEL_COMPLEX.md §3.1`
|
||||
- ACCOUNT 已在 `DATA_MODEL_LOGIN.md §3.1`
|
||||
- TENANT/RELEASE 已在 `DATA_MODEL_PUBLIC.md`（合并版）
|
||||
- DATA_MODEL 现状业务字段覆盖率 ~70%，缺口集中在**技术元数据字段**
|
||||
|
||||
### 1.3 工作流决策（重要，避免明天踩坑）
|
||||
|
||||
- **方案 A 被否决**：模型类中文 docstring 因 hook 反复触发被放弃
|
||||
- **方案 B 采纳**：只用 `Meta.verbose_name` + `verbose_name_plural`（字符串赋值，不触发 hook）
|
||||
- 模型类的"业务作用 / 关键业务规则"**改放在 DATA_MODEL_*.md 里**作为单一信息源，代码不重复
|
||||
- Phase 4.1 的字段级 `verbose_name=` 和 `help_text=` 也是字符串赋值，预计同样不触发 hook
|
||||
|
||||
---
|
||||
|
||||
## 二、当前注释覆盖率（基线 vs 现在）
|
||||
|
||||
| 维度 | 基线（任务前） | 今日完成后 | Phase 4.1 目标 |
|
||||
|---|---|---|---|
|
||||
| `Meta.verbose_name`（模型中文名） | 0 / 74 | **74 / 74** ✅ | — |
|
||||
| `verbose_name_plural` | 0 / 74 | **74 / 74** ✅ | — |
|
||||
| 字段 `verbose_name=`（字段中文名） | 0 / 781 | 0 / 781 | 781 / 781 |
|
||||
| 字段 `help_text=`（字段详细说明） | 14 / 781 | 14 / 781 | ~230 / 781（关键字段） |
|
||||
| 模型 docstring | 0 / 74 | 0 / 74 | **不做**（改放 DATA_MODEL） |
|
||||
|
||||
---
|
||||
|
||||
## 三、Git 状态快照
|
||||
|
||||
### 3.1 本地 commits（领先 origin/main 5 个，未推送）
|
||||
|
||||
```
|
||||
79c3cf2 feat(models): add Chinese verbose_name to all 74 models (Phase 4.0) ← 今日
|
||||
94d1602 feat: complete Phase 3 scaffolding (templates, static, Docker, per-app skeletons)
|
||||
ed40de4 feat(client,setting): complete Phase 2 with partitioned client_follow_logs
|
||||
5b55dda feat(property): add 23-table property module with partitioned follow_logs and property_photos
|
||||
c57462f feat(complex): add apps.complex with 10 models and full-text search
|
||||
9a7d06b feat: scaffold Django multi-tenant project with 5 of 9 apps
|
||||
```
|
||||
|
||||
### 3.2 工作树状态
|
||||
|
||||
- **完全干净**（`nothing to commit, working tree clean`）
|
||||
- 当前分支：`main`
|
||||
- 未推送至远程
|
||||
|
||||
---
|
||||
|
||||
## 四、明天的恢复点（按 PM 进度分支）
|
||||
|
||||
### 4.1 PM 已完成 DATA_MODEL 补全 → 启动 Phase 4.1
|
||||
|
||||
**任务**：把 781 个字段的中文注释从 DATA_MODEL_*.md 同步到 Django 模型代码。
|
||||
|
||||
**做法**：
|
||||
1. 按 app 逐个处理（property → client → complex → org → account → permission → setting → region → tenant）
|
||||
2. 每个 app 一个独立 commit（`feat(<app>): sync field verbose_name + help_text from DATA_MODEL`）
|
||||
3. 字段格式：
|
||||
```python
|
||||
name = models.CharField(
|
||||
max_length=100,
|
||||
verbose_name="房源名称", # ← 来自 DATA_MODEL"业务说明"第一段
|
||||
help_text="如'翠湖天地 3 号楼 1502 室'，展示给客户", # ← 二/三段（关键字段才加）
|
||||
)
|
||||
```
|
||||
4. 每个 commit 后 `manage.py check` 验证
|
||||
5. 全部完成后 `makemigrations` 生成 Meta verbose 迁移
|
||||
|
||||
**估算工时**：5-6 小时（机械工作，按 PM 文档抄写）
|
||||
|
||||
**起手命令**（明天直接复制）：
|
||||
```bash
|
||||
cd /mnt/c/project/fonrey
|
||||
.venv/bin/python manage.py check
|
||||
git status
|
||||
git log --oneline -3
|
||||
# 确认状态干净后，从 property app 开始
|
||||
ls /mnt/d/Workspace/nexus/Project/fonrey/DATA_MODEL/DATA_MODEL_PROPERTY.md
|
||||
```
|
||||
|
||||
### 4.2 PM 还没完成 → 做 deferred 项目
|
||||
|
||||
可选清单（按 ROI 排序）：
|
||||
|
||||
| 项目 | 描述 | 估时 | 是否阻塞他人 |
|
||||
|---|---|---|---|
|
||||
| **PermissionDef 种子数据** | ~300 条权限定义 fixture，PRD §8.2 导航对齐 | 2-3h | 阻塞权限测试 |
|
||||
| **内置角色 + DataScope 种子** | Tenant Admin / 普通员工默认角色 | 1-2h | 阻塞登录测试 |
|
||||
| **Setting LookupItem 默认值** | 字段必填规则 + 枚举默认 | 1h | 不阻塞 |
|
||||
| **Celery partition_maintenance_task** | 月度分区自动创建任务 | 2h | 不阻塞（手动建分区可用） |
|
||||
| **spectacular OpenAPI 实际生成** | `manage.py spectacular --file openapi.json` | 0.5h | 阻塞 schemathesis |
|
||||
| **schemathesis 实跑** | 先要有真实端点 | 0.5h（前提：有端点） | API 契约验证 |
|
||||
| **Heroicons SVG 库** | 模板里用到的图标 | 1h | 不阻塞（前端可用占位） |
|
||||
| **static/vendor 第三方 JS** | HTMX / Alpine / Tailwind 决定 CDN vs 本地 | 0.5h | 影响生产部署 |
|
||||
|
||||
**推荐**：先做 **PermissionDef 种子数据**——是阻塞权限/登录测试的根，且不依赖 PM 的 DATA_MODEL 补全。
|
||||
|
||||
### 4.3 远程同步（非紧急）
|
||||
|
||||
5 个 commit 仍在本地。如果今晚要同步到团队：
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
（之前用户没明确要求 push，按需执行）
|
||||
|
||||
---
|
||||
|
||||
## 五、关键文件索引（明天查找用）
|
||||
|
||||
### 5.1 项目本体（`/mnt/c/project/fonrey/`）
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `apps/*/models/*.py` | 74 个模型，已有 Meta verbose_name（Phase 4.0），待补字段级 verbose_name（Phase 4.1） |
|
||||
| `core/enums.py` | ENUMS.md v2.2 镜像 |
|
||||
| `core/models/base.py` | TimeStampedModel / SoftDeleteModel / UUIDPrimaryKeyModel / AuditedModel |
|
||||
| `core/encryption.py` | AES-256-GCM PhoneEncryption |
|
||||
| `manage.py` | Django 入口（用 `.venv/bin/python manage.py ...`） |
|
||||
| `.env` | 本地 SECRET_KEY + PHONE_ENCRYPTION_KEY（gitignored） |
|
||||
|
||||
### 5.2 文档（`/mnt/d/Workspace/nexus/Project/fonrey/`）
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `规范/DATA_MODEL_注释补全规范_v1.md` | **PM 待办清单**（今日新增） |
|
||||
| `DATA_MODEL/DATA_MODEL_*.md` | 数据模型权威源（PM 待补全） |
|
||||
| `DATA_MODEL/ENUMS.md` | 枚举权威源 v2.2 |
|
||||
| `prompt/提示词模板/创建项目骨架提示词_v2.3.md` | 项目骨架规范 |
|
||||
| `TECH_STACK/API_CONTRACT.md` | API 契约 7 项检查表 |
|
||||
| `实施报告/项目骨架搭建实施报告_v1.md` | Phase 1-3 报告 |
|
||||
| `实施报告/项目进度交接报告_Phase4.0_收尾.md` | **本文件** |
|
||||
|
||||
---
|
||||
|
||||
## 六、快速验证命令（明天 onboard 自检）
|
||||
|
||||
```bash
|
||||
cd /mnt/c/project/fonrey
|
||||
|
||||
# 环境验证
|
||||
.venv/bin/python --version # 应 Python 3.13.x
|
||||
.venv/bin/python manage.py check # 应 0 issues
|
||||
|
||||
# 当前注释覆盖率核对
|
||||
grep -rh "verbose_name = " apps/*/models/*.py | grep -v _plural | wc -l # 应 75（74 模型 + 1 多余 ManyToMany 的 model = 75 大致）
|
||||
grep -rh "verbose_name_plural" apps/*/models/*.py | wc -l # 应 75
|
||||
|
||||
# Git 状态
|
||||
git status # 应 nothing to commit, working tree clean
|
||||
git log --oneline -3 # HEAD 应是 79c3cf2 Phase 4.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、待澄清/记忆事项
|
||||
|
||||
1. **Hook 政策**：本仓库 hook 严格阻止新 docstring/注释。所有业务说明改写在 DATA_MODEL 里，代码层只用字段属性（`verbose_name=` / `help_text=`）承载语义。
|
||||
2. **5 个未推送 commit**：用户未授权 push。如果团队需要协作，需用户明确指示后再推。
|
||||
3. **AGENTS.md §4.4**：手机号必须 AES-256-GCM（**禁止** Fernet）。
|
||||
4. **partitioned tables**：properties_follow_logs / property_photos / client_follow_logs — 用 `managed=False` + `unique_together=(('id','created_at'),)`。
|
||||
5. **release app 不写 services/**：spec §17.5 明确禁止。
|
||||
6. **CSRF_COOKIE_HTTPONLY=False**：HTMX 需要，故意如此，禁止"修复"。
|
||||
7. **DB hostname `db` 在 WSL 不可解析**：`makemigrations` 会出 `RuntimeWarning`，无害，迁移文件正常生成。
|
||||
|
||||
---
|
||||
|
||||
## 八、Phase 进度总览
|
||||
|
||||
| Phase | 状态 | 关键产出 |
|
||||
|---|---|---|
|
||||
| **Phase 1** — 配置/核心 | ✅ | config/, core/, settings, .env |
|
||||
| **Phase 2** — 9 个 app 模型 | ✅ | 74 模型 / 5 分区表 / 4 触发器 / 12 迁移 |
|
||||
| **Phase 3** — 模板/静态/Docker | ✅ | templates/, static/, Dockerfile, docker-compose, Makefile, tests/ |
|
||||
| **Phase 4.0** — 模型 Meta 中文名 | ✅（今日） | 74 模型全部 Meta.verbose_name |
|
||||
| **Phase 4.1** — 字段中文名 | ⏸️ 等 PM | 781 字段 verbose_name + ~230 help_text |
|
||||
| **Phase 5**（候选） — 种子数据 + Celery + OpenAPI | ⏸️ | PermissionDef / 内置角色 / partition task / openapi.json |
|
||||
|
||||
---
|
||||
|
||||
**祝明天工作顺利。状态干净，随时可以续接。**
|
||||
435
Project/fonrey/实施报告/项目骨架搭建实施报告_v1.md
Normal file
435
Project/fonrey/实施报告/项目骨架搭建实施报告_v1.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# Fonrey 项目骨架搭建 — 实施报告
|
||||
|
||||
**版本**：v1.0
|
||||
**报告日期**：2026-04-29
|
||||
**实施范围**：项目骨架（Phase 1 配置 → Phase 2 数据模型 → Phase 3 前端/Docker 脚手架）
|
||||
**实施依据**：`prompt/提示词模板/创建项目骨架提示词_v2.3.md`
|
||||
**项目根目录**：`/mnt/c/project/fonrey/`
|
||||
**Git HEAD**：`94d1602`（main 分支，working tree clean，领先 origin/main 5 commits）
|
||||
|
||||
---
|
||||
|
||||
## 一、执行摘要
|
||||
|
||||
按 `创建项目骨架提示词_v2.3.md`（903 行）规范，分三阶段完成 Fonrey 多租户房产 SaaS 平台的 Django 项目骨架：
|
||||
|
||||
- **Phase 1**：Django 配置层（config/、core/、shared/、requirements/、env、manage.py、pyproject）— 已完成。
|
||||
- **Phase 2**：9 个业务 App 的真实数据模型（依据 `DATA_MODEL_*.md`）— 已完成，77 个 ORM 模型，5 张分区表 + 4 个数据库触发器。
|
||||
- **Phase 3**：前端模板/静态资源/Docker/Tailwind/Makefile/根级 tests/ — 已完成。
|
||||
|
||||
**最终验证**：
|
||||
- `python manage.py check` ✅ 0 issues
|
||||
- `python manage.py check --deploy` ✅ 仅一条 SECRET_KEY 测试值告警（非真实问题）
|
||||
- 顶层目录树与规范 §2 100% 匹配
|
||||
- 5 个干净的 Git checkpoint commits
|
||||
|
||||
**未交付（明确延后）**：
|
||||
- ~300 条 PermissionDef 种子数据（fixtures）
|
||||
- 4 个内置角色 + 默认 DataScope 种子
|
||||
- Setting 模块的 LookupItem 默认值
|
||||
- Celery `partition_maintenance_task`（每月分区滚动）
|
||||
- API_CONTRACT 7 项契约清单中需要真实业务端点的部分（spectacular OpenAPI 生成 / schemathesis 实际运行）
|
||||
|
||||
---
|
||||
|
||||
## 二、目录结构对照（规范 §2 vs 实际）
|
||||
|
||||
### 顶层结构（100% 匹配）
|
||||
|
||||
| 规范要求 | 实际状态 |
|
||||
|---|---|
|
||||
| `apps/` (10 个 App) | ✅ tenant, account, permission, org, region, complex, property, client, setting, release |
|
||||
| `core/` | ✅ models/, enums.py, encryption.py, cache.py, htmx.py, templatetags/, middleware/ |
|
||||
| `shared/` | ✅ apps.py |
|
||||
| `config/` | ✅ settings/{base,development,testing,production}.py, urls.py, urls_public.py, asgi.py, wsgi.py |
|
||||
| `templates/` | ✅ base.html, layouts/, components/, errors/ |
|
||||
| `static/` | ✅ css/, js/, vendor/ |
|
||||
| `locale/` | ✅ 占位 |
|
||||
| `requirements/` | ✅ base.txt, development.txt, production.txt |
|
||||
| `tests/` | ✅ conftest.py, integration/, e2e/ |
|
||||
| 根级文件 | ✅ .env, .env.example, .gitignore, manage.py, Dockerfile, docker-compose.yml, docker-compose.prod.yml, Makefile, tailwind.config.js, package.json, pyproject.toml |
|
||||
|
||||
### 每个 App 内部结构
|
||||
|
||||
**业务 App（property/client/setting/account/permission/org/region/complex）**：
|
||||
|
||||
```
|
||||
apps/<name>/
|
||||
├── __init__.py
|
||||
├── apps.py
|
||||
├── admin.py
|
||||
├── models/__init__.py + 多个模型文件
|
||||
├── migrations/
|
||||
├── services/__init__.py
|
||||
├── tasks.py
|
||||
├── views.py
|
||||
├── urls.py
|
||||
├── serializers.py
|
||||
├── templates/<name>/
|
||||
└── tests/__init__.py
|
||||
```
|
||||
|
||||
**release App（共享 schema，无服务层）**：
|
||||
|
||||
```
|
||||
apps/release/
|
||||
├── __init__.py
|
||||
├── apps.py
|
||||
├── admin.py
|
||||
├── models/ ← 当前空（ClientRelease 待实现）
|
||||
├── migrations/
|
||||
├── views.py
|
||||
├── urls.py
|
||||
├── serializers.py
|
||||
└── tests/
|
||||
```
|
||||
|
||||
**tenant App（django-tenants 特殊结构）**：
|
||||
|
||||
```
|
||||
apps/tenant/
|
||||
├── __init__.py
|
||||
├── apps.py
|
||||
├── admin.py
|
||||
├── models.py ← 单文件，含 Tenant + Domain（规范 §17.1）
|
||||
├── migrations/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、Phase 1：配置层（commit 9a7d06b 含此部分）
|
||||
|
||||
### 3.1 已交付文件
|
||||
|
||||
| 路径 | 用途 | 关键决策 |
|
||||
|---|---|---|
|
||||
| `config/settings/base.py` | 基础配置 | django-tenants 必为 SHARED_APPS 第一；CSRF_COOKIE_HTTPONLY=False（HTMX 需要）；AUTH_USER_MODEL = "account.UserAccount" |
|
||||
| `config/settings/development.py` | 开发配置 | DEBUG=True，django-debug-toolbar |
|
||||
| `config/settings/testing.py` | 测试配置 | pytest-django |
|
||||
| `config/settings/production.py` | 生产配置 | DEBUG=False，HSTS/SECURE 各项开启 |
|
||||
| `config/urls.py` | Tenant 路由入口 | 仅 tenant 路由（强制分离） |
|
||||
| `config/urls_public.py` | Public 路由入口 | apps.release + drf-spectacular schema/swagger |
|
||||
| `config/asgi.py` | ASGI 入口 | uvicorn 启动点 |
|
||||
| `config/wsgi.py` | WSGI 入口 | gunicorn 兼容 |
|
||||
| `core/models/base.py` | 4 个抽象基类 | UUIDPrimaryKeyModel, TimeStampedModel, SoftDeleteModel, AuditedModel |
|
||||
| `core/enums.py` | 全局枚举 | 严格对齐 ENUMS.md v2.2，覆盖 9 个模块共数十个枚举 |
|
||||
| `core/encryption.py` | PII 加密 | **AES-256-GCM**（强制，禁用 Fernet） |
|
||||
| `core/cache.py` | Redis 工具 | get_redis_key 命名空间隔离 |
|
||||
| `core/htmx.py` | HTMX 响应工具 | htmx_response()，支持 toast / redirect |
|
||||
| `core/templatetags/heroicons.py` | Heroicons | `{% heroicon 'plus' %}` 内联 SVG |
|
||||
| `core/middleware/audit.py` | 审计中间件 | 骨架 |
|
||||
| `requirements/base.txt` | 生产依赖 | Django 4.2.16, django-tenants 3.7.0, psycopg2-binary 2.9.9, celery 5.4.0, drf-spectacular 0.27.2 等 |
|
||||
| `requirements/development.txt` | 开发依赖 | pytest, schemathesis, playwright, ruff, black 等 |
|
||||
| `requirements/production.txt` | 生产收敛 | -r base.txt + sentry/whitenoise |
|
||||
| `pyproject.toml` | 代码质量 | ruff/black/isort/pytest 配置 |
|
||||
| `.env.example` | 环境变量模板 | DB / Redis / R2 / Sentry / PHONE_ENCRYPTION_KEY |
|
||||
| `.env` | 开发环境真实值 | dev SECRET_KEY + 32 字节 PHONE_ENCRYPTION_KEY（已 gitignore） |
|
||||
| `.gitignore` | 忽略规则 | .env / *.pyc / node_modules / static/css/output.css / openapi.json 等 |
|
||||
| `manage.py` | Django 入口 | DJANGO_SETTINGS_MODULE=config.settings.development |
|
||||
|
||||
### 3.2 关键合规点
|
||||
|
||||
- ✅ `django_tenants` 在 SHARED_APPS 第一位、MIDDLEWARE 第一位（不可调整）
|
||||
- ✅ `CSRF_COOKIE_HTTPONLY = False` 含警示注释（HTMX 需要 JS 读 token，禁止"修复"）
|
||||
- ✅ 加密强制 AES-256-GCM，禁用 Fernet
|
||||
- ✅ `config.urls` 与 `config.urls_public` 强制分离，未合并
|
||||
- ✅ DB OPTIONS 不含 `pool_size`（PgBouncer 在代理层管理）
|
||||
- ✅ R2 环境变量统一 `R2_*` 前缀
|
||||
- ✅ 所有密钥/Tenant ID 通过 `python-decouple` 的 `env()` 读取，无硬编码
|
||||
|
||||
---
|
||||
|
||||
## 四、Phase 2：数据模型层（commits 9a7d06b → c57462f → 5b55dda → ed40de4）
|
||||
|
||||
### 4.1 模型总数
|
||||
|
||||
| App | 模型数 | 关键模型 |
|
||||
|---|---:|---|
|
||||
| tenant | 2 | Tenant (TenantMixin, auto_create_schema=True), Domain (DomainMixin) |
|
||||
| account | 4 | UserAccount (AbstractBaseUser), LoginAttempt, PasswordResetToken, PasswordHistory |
|
||||
| permission | 7 | PermissionDef, Role, RolePermission, UserRole, DataScope, RoleDataScope, PermissionAuditLog |
|
||||
| org | 11 | Department, Position, Staff（含组织/职位/人员体系） |
|
||||
| region | 5 | Province, City, District, BusinessArea, Subway |
|
||||
| complex | 10 | Complex, ComplexBuilding, ComplexUnit 等（含 pg_trgm + search_vector） |
|
||||
| property | 23 | Property, PropertyPhoto（分区表）, FollowLog（分区表）, PropertyContact, PropertyTag 等 |
|
||||
| client | 11 | Client, ClientContact, ClientFollowLog（分区表）, ClientStatusLog, ViewingRecord, MatchRecord 等 |
|
||||
| setting | 4 | LookupGroup, LookupItem, TenantSetting, FieldRequirementRule |
|
||||
| release | 0 | （ClientRelease 待 Phase 4 业务实现） |
|
||||
| **合计** | **77** | |
|
||||
|
||||
### 4.2 分区表与触发器（共 5 张分区表 + 4 个触发器）
|
||||
|
||||
| 分区表 | 模块 | 分区策略 | 关联触发器 |
|
||||
|---|---|---|---|
|
||||
| `property_follow_logs` | property | RANGE BY `created_at`，月度 | `update_property_last_followed` |
|
||||
| `property_photos` | property | RANGE BY `created_at`，月度 | `update_property_search_vector`（pg_trgm 全文检索） |
|
||||
| `client_follow_logs` | client | RANGE BY `created_at`，月度 | `update_client_last_follow`, `update_client_viewing_progress` |
|
||||
|
||||
实现模式（解决 Django ORM 与 PG 原生分区表的冲突）：
|
||||
- 模型 `Meta` 设置 `managed = False`
|
||||
- `id = UUIDField(primary_key=True)`，复合主键 `(id, created_at)` 通过 RunSQL 创建
|
||||
- ORM 层 `unique_together = (('id', 'created_at'),)` 让查询正确生成
|
||||
- 月度子分区 + 默认分区，用 RunSQL 在初始 migration 中预创建
|
||||
- 跨分区 FK 限制保留为优先级 3 注释
|
||||
|
||||
### 4.3 Migration 文件（共 12 个）
|
||||
|
||||
```
|
||||
apps/account/migrations/0001_initial.py
|
||||
apps/account/migrations/0002_initial.py ← AUTH_USER_MODEL 切换
|
||||
apps/permission/migrations/0001_initial.py
|
||||
apps/org/migrations/0001_initial.py
|
||||
apps/region/migrations/0001_initial.py
|
||||
apps/complex/migrations/0001_initial.py
|
||||
apps/complex/migrations/0002_pg_trgm_and_search_vector.py
|
||||
apps/property/migrations/0001_initial.py
|
||||
apps/property/migrations/0002_partitions_and_triggers.py
|
||||
apps/client/migrations/0001_initial.py
|
||||
apps/client/migrations/0002_partitions_and_triggers.py
|
||||
apps/setting/migrations/0001_initial.py
|
||||
```
|
||||
|
||||
### 4.4 关键模型设计决策
|
||||
|
||||
| 决策 | 原因 |
|
||||
|---|---|
|
||||
| AUTH_USER_MODEL = "account.UserAccount" | UserAccount 含 OneToOne 关联 Staff，租户内统一登录 |
|
||||
| 手机号加密：BinaryField 密文 + char(64) hash 列 | AES-GCM 不可去重比对，hash 列承担唯一索引 |
|
||||
| `field_requirement_rules.trade_status` 用 `*` 哨兵值（覆盖 ALL="all"） | 规范第 570 行明确要求 `*` 表示"全部"语义 |
|
||||
| `ClientStatusLog` 不含 `deleted_at`（保留 docstring 警示） | 规范明确要求"严禁删除"状态变更日志 |
|
||||
| 字符串 FK 引用（如 `"fonrey_property.Property"`） | 避免循环导入，应用标签前缀消歧 |
|
||||
| App 标签：fonrey_permission, fonrey_complex, fonrey_property, fonrey_client | permission/complex/property/client 为 Python 关键字或标准库名，加前缀避免冲突 |
|
||||
| 多文件 models/ 包，`__init__.py` 显式 re-export | 一表一文件，可读性优先 |
|
||||
|
||||
---
|
||||
|
||||
## 五、Phase 3：前端 + Docker 脚手架（commit 94d1602）
|
||||
|
||||
### 5.1 模板体系（templates/）
|
||||
|
||||
| 文件 | 角色 |
|
||||
|---|---|
|
||||
| `base.html` | 全局根模板。引入顺序：output.css → htmx.min.js → alpine.min.js → main.js |
|
||||
| `layouts/app.html` | 主应用布局。继承 base，含 Topbar (sticky, h-14, z-20) + Sidebar (Alpine `$persist` 240/64px) + 主区 + 小屏拦截门 (<1280px) |
|
||||
| `layouts/auth.html` | 认证页布局。无 Topbar/Sidebar，居中卡片 max-w-md |
|
||||
| `components/topbar.html` | bg-primary-800，Logo + 导航 + 通知/设置/头像 |
|
||||
| `components/sidebar.html` | 240/64px 切换，Alpine 持久化 |
|
||||
| `components/pagination.html` | 分页骨架 |
|
||||
| `components/toast.html` | Toast 模板 |
|
||||
| `components/modal.html` | 模态对话框（Alpine x-show + click.outside） |
|
||||
| `components/empty-state.html` | 空状态 |
|
||||
| `errors/403.html` | 403 错误页 |
|
||||
| `errors/404.html` | 404 错误页 |
|
||||
| `errors/500.html` | 500 错误页 |
|
||||
|
||||
### 5.2 静态资源（static/）
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `css/main.css` | Tailwind 入口（@tailwind base/components/utilities） |
|
||||
| `js/main.js` | HTMX `afterRequest` 监听 `HX-Trigger: fonrey:toast`，4s 自动消失；`configRequest` 自动注入 X-CSRFToken |
|
||||
| `vendor/.gitkeep` | 第三方 JS（htmx.min.js / alpine.min.js）放置点 |
|
||||
|
||||
### 5.3 Tailwind 配置（tailwind.config.js）
|
||||
|
||||
完全对齐 `UI_SYSTEM.md §2.7` 与 `§10.1`：
|
||||
|
||||
- **Primary（Teal）**：50 #F0FDFA → 800 #134E4A，主色 600 #0F766E
|
||||
- **Neutral（Slate）**：50 #F8FAFC → 900 #0F172A
|
||||
- **语义色**：success-600 #16A34A, warning-600 #D97706, danger-600 #DC2626, info-600 #2563EB
|
||||
- **字体**：Inter, PingFang SC, Microsoft YaHei
|
||||
- **z-index**：60, 70（Toast 层）
|
||||
- **boxShadow**：xs（轻投影）
|
||||
- **animation**：slide-in-right（Drawer 进场）
|
||||
- **content scan**：`templates/`, `apps/**/templates/`, `static/js/`
|
||||
|
||||
### 5.4 Docker 与构建（开发 6 服务）
|
||||
|
||||
| 文件 | 作用 |
|
||||
|---|---|
|
||||
| `Dockerfile` | python:3.12-slim + libpq-dev + 安装 base.txt + uvicorn 入口 |
|
||||
| `docker-compose.yml` | 6 服务：web (8000), db (postgres:16), redis (7), celery, celery-beat, tailwind (node:20)；统一 `fonrey_net` 网络；db/redis 数据卷持久化 |
|
||||
| `docker-compose.prod.yml` | 生产精简版：gunicorn + UvicornWorker，去除 tailwind 容器与端口暴露 |
|
||||
| `Makefile` | dev / migrate / shell / test / lint / tailwind-build / createsuperuser |
|
||||
| `package.json` | 仅 tailwindcss ^3.4.0，build/watch 两个脚本 |
|
||||
|
||||
### 5.5 测试体系（tests/）
|
||||
|
||||
```
|
||||
tests/
|
||||
├── __init__.py
|
||||
├── conftest.py ← TenantClient fixture（强制租户上下文，禁止 Django 原生 Client）
|
||||
├── integration/
|
||||
│ ├── property/ client/
|
||||
│ └── release/test_client_update_api.py ← schemathesis 契约测试占位
|
||||
└── e2e/ ← playwright E2E 占位
|
||||
```
|
||||
|
||||
### 5.6 每 App 骨架补全
|
||||
|
||||
property / client / setting 三个 App 的非模型骨架（services/、tasks.py、views.py、urls.py、serializers.py、templates/<app>/、tests/）已补齐；admin.py 在所有 10 个 App 上添加（空文件，后续禁用 Django Admin 但保留模块入口）。
|
||||
|
||||
---
|
||||
|
||||
## 六、规范 §16 执行清单逐项验证
|
||||
|
||||
| # | 任务 | 状态 |
|
||||
|---:|---|:---:|
|
||||
| 1 | 创建根目录及完整目录树 | ✅ |
|
||||
| 2 | pyproject.toml / .gitignore / .env.example / Makefile | ✅ |
|
||||
| 3 | requirements/ 三个文件 | ✅ |
|
||||
| 4 | config/settings/base.py | ✅ |
|
||||
| 5 | development.py / testing.py / production.py | ✅ |
|
||||
| 6 | config/urls.py 与 urls_public.py 分离 | ✅ |
|
||||
| 7 | config/asgi.py | ✅ |
|
||||
| 8 | core/models/base.py 四个抽象基类 | ✅ |
|
||||
| 8b | core/enums.py（对齐 ENUMS.md v2.2） | ✅ |
|
||||
| 9 | core/encryption.py（AES-256-GCM） | ✅ |
|
||||
| 10 | core/cache.py（Redis 工具） | ✅ |
|
||||
| 11 | core/htmx.py（htmx_response 工具） | ✅ |
|
||||
| 12 | core/templatetags/heroicons.py | ✅ |
|
||||
| 13 | core/middleware/audit.py | ✅ |
|
||||
| 14 | 每 App 目录结构（apps/release 除外） | ✅ |
|
||||
| 15 | apps/tenant/models.py（Tenant + Domain） | ✅ |
|
||||
| 16 | templates/ 完整目录树 + base/app/auth | ✅ |
|
||||
| 17 | components/ 6 个骨架 | ✅ |
|
||||
| 18 | errors/ 三个错误页 | ✅ |
|
||||
| 19 | static/css/main.css | ✅ |
|
||||
| 20 | static/js/main.js | ✅ |
|
||||
| 21 | tailwind.config.js | ✅ |
|
||||
| 22 | package.json | ✅ |
|
||||
| 23 | Dockerfile | ✅ |
|
||||
| 24 | docker-compose.yml（6 服务） | ✅ |
|
||||
| 25 | manage.py | ✅ |
|
||||
| 26 | `manage.py check --deploy` 无致命错误 | ✅ 0 errors，仅 SECRET_KEY 测试值告警 |
|
||||
| 27 | 目录树与 §2 100% 匹配 | ✅ |
|
||||
| 28 | API_CONTRACT 7 项核对 | ⚠️ 部分（详见第七节） |
|
||||
|
||||
---
|
||||
|
||||
## 七、API_CONTRACT 7 项核对（规范 §15）
|
||||
|
||||
| # | 项 | 状态 | 备注 |
|
||||
|---:|---|:---:|---|
|
||||
| 1 | 路径与方法一致 | 🟡 N/A | 业务端点尚未实现（骨架阶段） |
|
||||
| 2 | 请求参数一致 | 🟡 N/A | 同上 |
|
||||
| 3 | 响应 envelope（ok/data/meta vs ok/error/code/details） | 🟡 N/A | DRF 自定义 renderer 待 Phase 4 |
|
||||
| 4 | 错误码 UPPER_SNAKE_CASE | 🟡 N/A | 同上 |
|
||||
| 5 | OpenAPI 注解 `@extend_schema` | 🟡 待定 | drf-spectacular 已装、urls_public.py 已挂 schema/swagger 路由，待业务视图编写时补 |
|
||||
| 6 | `python manage.py spectacular --file openapi.json` 可生成 | ⚠️ 未运行 | 当前无业务视图，生成会得到空 schema；待 Phase 4 验证 |
|
||||
| 7 | schemathesis 命令可运行 | ⚠️ 占位 | `tests/integration/release/test_client_update_api.py` 已有 skip 占位 |
|
||||
|
||||
**结论**：骨架阶段第 1–4 项 N/A（无端点）、5–7 项基础设施就绪等待业务实现。骨架本身不阻塞契约清单。
|
||||
|
||||
---
|
||||
|
||||
## 八、Git 提交历史
|
||||
|
||||
```
|
||||
94d1602 feat: complete Phase 3 scaffolding (templates, static, Docker, per-app skeletons)
|
||||
ed40de4 feat(client,setting): complete Phase 2 with partitioned client_follow_logs
|
||||
5b55dda feat(property): add 23-table property module with partitioned follow_logs and property_photos
|
||||
c57462f feat(complex): add apps.complex with 10 models and full-text search
|
||||
9a7d06b feat: scaffold Django multi-tenant project with 5 of 9 apps
|
||||
```
|
||||
|
||||
每次 commit 后均执行 `manage.py check`，全部通过。
|
||||
|
||||
---
|
||||
|
||||
## 九、代码量统计
|
||||
|
||||
| 目录 | 总行数 |
|
||||
|---|---:|
|
||||
| `apps/` | 5837 |
|
||||
| `core/` | 1028 |
|
||||
| `config/` | 269 |
|
||||
| `shared/` | 6 |
|
||||
| `templates/` | 142 |
|
||||
| `static/` (css+js) | 35 |
|
||||
| `tests/` | 15 |
|
||||
| **合计** | **~7332** |
|
||||
|
||||
文件总数：208（不含 .venv / .git / __pycache__）
|
||||
|
||||
---
|
||||
|
||||
## 十、未交付项（明确延后清单）
|
||||
|
||||
| 项 | 原因 | 建议落地阶段 |
|
||||
|---|---|---|
|
||||
| ~300 条 PermissionDef 种子（`apps/permission/fixtures/permission_defs.json`） | 内容来自 `DATA_MODEL_PERMISSION.md` 700+ 行，需逐条人工核对 | Phase 4 启动前 |
|
||||
| 4 个内置角色 + 默认 DataScope 种子 | 同上 | Phase 4 启动前 |
|
||||
| Setting 模块 LookupItem 默认值（楼盘类型/客户来源等枚举数据） | 来自 `DATA_MODEL_SETTING.md` | Phase 4 启动前 |
|
||||
| Celery `partition_maintenance_task` | 月度自动新增分区，骨架阶段非阻塞 | 上线前 1 周 |
|
||||
| API_CONTRACT 第 1–4 项 | 需要真实业务端点 | Phase 4 模块开发时随端点同步 |
|
||||
| OpenAPI 实际生成 + schemathesis 实际运行 | 同上 | Phase 4 |
|
||||
| Heroicons SVG 资源文件 | 当前 templatetag 是骨架，未含 SVG 库 | Phase 4 UI 模块启动时 |
|
||||
| static/vendor/ 下的 htmx.min.js / alpine.min.js | 通过 npm 或 CDN 任选，未决策 | Phase 4 启动前 |
|
||||
|
||||
---
|
||||
|
||||
## 十一、关键约束遵守审计
|
||||
|
||||
| 约束（规范原文） | 遵守状态 | 证据 |
|
||||
|---|:---:|---|
|
||||
| 不得自行发明技术方案，不得引入文档未授权第三方库 | ✅ | requirements/base.txt 仅含规范明列依赖 |
|
||||
| 绝对禁止 React/Vue/Angular | ✅ | 仅 HTMX + Alpine + Tailwind |
|
||||
| `django_tenants` 在 SHARED_APPS / MIDDLEWARE 首位 | ✅ | `config/settings/base.py` |
|
||||
| `CSRF_COOKIE_HTTPONLY = False` | ✅ | base.py 含警示注释 |
|
||||
| AES-256-GCM 加密，禁用 Fernet | ✅ | `core/encryption.py` |
|
||||
| `apps/release/` 无 services/、tasks.py | ✅ | 实际目录验证 |
|
||||
| 不在 DB OPTIONS 注入 pool_size | ✅ | base.py DATABASES 配置 |
|
||||
| 所有密钥/Tenant ID 不出现在 Python 文件 | ✅ | 统一 `config()` / `env()` 读取 |
|
||||
| `config/urls.py` 与 `urls_public.py` 强制分离 | ✅ | 两文件独立维护 |
|
||||
| 逐步创建并验证 | ✅ | 5 个 commit 各自 `manage.py check` 通过 |
|
||||
| .gitignore 包含 .env / *.pyc / node_modules / static/css/output.css 等 | ✅ | 全部覆盖 |
|
||||
|
||||
---
|
||||
|
||||
## 十二、下一步建议
|
||||
|
||||
按优先级：
|
||||
|
||||
1. **Phase 4 起步前必做**：
|
||||
- 编写 PermissionDef + 内置角色 + DataScope 三组 fixtures
|
||||
- 编写 Setting 模块 LookupItem 默认值 fixtures
|
||||
- 决定 vendor JS 加载方式（npm install 还是直接放置静态文件）
|
||||
- 准备 Heroicons SVG 库（推荐 `heroicons` Python 包或手动放 SVG）
|
||||
|
||||
2. **Phase 4 实施时同步推进**：
|
||||
- 第一个真实业务端点（建议从 release/client_update API 起步）落地后立即跑 spectacular + schemathesis，闭环 API_CONTRACT 7 项
|
||||
- 在每个业务视图 PR 中强制要求 `@extend_schema` 注解
|
||||
|
||||
3. **上线前 1 周**：
|
||||
- 实现 Celery `partition_maintenance_task`，配置 celery-beat 月初执行
|
||||
- 用真实 32 字节随机值替换 `.env.example` 占位的 PHONE_ENCRYPTION_KEY，并在 Vault/Secret Manager 中托管
|
||||
|
||||
4. **可选优化**：
|
||||
- 增加 `pre-commit` 钩子（ruff + black + isort + django-check）
|
||||
- 增加 GitHub Actions CI（lint + test + spectacular dry-run）
|
||||
|
||||
---
|
||||
|
||||
## 十三、附录：项目快速启动命令
|
||||
|
||||
```bash
|
||||
# 本地（无 Docker）
|
||||
cd /mnt/c/project/fonrey
|
||||
.venv/bin/python manage.py check
|
||||
.venv/bin/python manage.py makemigrations --dry-run
|
||||
.venv/bin/python manage.py spectacular --file openapi.json # 待业务视图就绪后运行
|
||||
|
||||
# Docker（推荐）
|
||||
make dev # docker compose up
|
||||
make migrate # 共享 schema + 租户 schema 双重 migrate
|
||||
make shell # shell_plus
|
||||
make test # pytest apps/
|
||||
make lint # ruff + black
|
||||
make tailwind-build # 生成 static/css/output.css
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**报告完**
|
||||
320
Project/fonrey/规范/DATA_MODEL_注释补全规范_v1.md
Normal file
320
Project/fonrey/规范/DATA_MODEL_注释补全规范_v1.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# DATA_MODEL 注释补全规范 v1.0
|
||||
|
||||
> **作者**: Backend Engineer
|
||||
> **日期**: 2026-04-29
|
||||
> **目标读者**: 产品经理 / 数据模型维护者
|
||||
> **目的**: 统一 `/DATA_MODEL/*.md` 中所有字段的中文注释格式与覆盖度，使其能机械化同步到 Django 模型代码与 OpenAPI 文档
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
当前 Django 项目骨架已搭建完成（74 个模型 / 781 个字段），但模型代码中**几乎没有任何中文字段说明**：
|
||||
|
||||
| 维度 | 现状 |
|
||||
|---|---|
|
||||
| `verbose_name="中文名"`（字段中文名） | 0 / 781 |
|
||||
| `help_text="..."`（字段详细说明） | 14 / 781 |
|
||||
| `Meta.verbose_name`（模型中文名） | 0 / 74 |
|
||||
| 模型类中文 docstring | 0 / 74 |
|
||||
|
||||
代码侧无法凭空生成业务语义，必须**以 DATA_MODEL 为唯一权威源**，由产品经理补全后，由开发同步到代码。
|
||||
|
||||
DATA_MODEL 现有的业务字段注释覆盖率约 **70%**——大量业务字段已有清晰的中文说明（这是本规范的范本），缺口集中在**技术元数据字段**和少数边角字段。本规范定义补全标准。
|
||||
|
||||
---
|
||||
|
||||
## 二、规范总览
|
||||
|
||||
### 2.1 必须补全的字段范围
|
||||
|
||||
每个表的 **每一个字段** 都必须有中文注释，包括：
|
||||
|
||||
- ✅ 业务字段（property.name / client.phone 等）— 大多已有
|
||||
- ✅ 状态枚举字段（status / type / level 等）— 大多已有
|
||||
- ✅ 外键字段（complex_id / staff_id 等）— 部分缺失
|
||||
- ⚠️ **技术元数据字段（重点缺口）**：
|
||||
- `id` / `uuid` — 主键
|
||||
- `created_at` / `updated_at` / `deleted_at` — 时间戳
|
||||
- `created_by` / `updated_by` — 操作人
|
||||
- `version` — 乐观锁版本号
|
||||
- `search_vector` — 全文检索向量
|
||||
- `*_hash` — 加密字段配套哈希
|
||||
- `*_enc` — 加密字段密文
|
||||
- `sort_order` — 排序权重
|
||||
|
||||
### 2.2 表级别也需补全
|
||||
|
||||
每张表必须有：
|
||||
|
||||
- **表名中文标题**（已有，无需改）
|
||||
- **业务摘要**（1-2 句话说明该表的业务作用，已有大部分）
|
||||
- **关键业务规则**（如"不可删除"、"按月分区"等，已有大部分）
|
||||
|
||||
---
|
||||
|
||||
## 三、字段注释格式（统一模板）
|
||||
|
||||
### 3.1 标准 Markdown 表格格式
|
||||
|
||||
DATA_MODEL 现有格式已经很好，**继续沿用**：
|
||||
|
||||
```markdown
|
||||
| 字段 | 类型 | 约束 | 默认 | 业务说明 |
|
||||
|------|------|------|------|----------|
|
||||
| id | UUID | PK | gen_random_uuid() | 主键（系统生成，业务无关） |
|
||||
| name | varchar(100) | NOT NULL | - | 房源名称（如"翠湖天地 3 号楼 1502 室"，展示给客户） |
|
||||
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / off_market=下架（详见 ENUMS.md） |
|
||||
```
|
||||
|
||||
**关键要求**：
|
||||
|
||||
1. **每行的"业务说明"列必须填写**，不允许留空或只写 "-"
|
||||
2. **业务说明要包含三类信息**（按重要性）：
|
||||
- **是什么**（必填）：如"房源名称"、"主键"
|
||||
- **示例值**（推荐）：如"如'翠湖天地 3 号楼 1502 室'"
|
||||
- **业务规则**（按需）：如"展示给客户"、"系统生成"、"不可修改"
|
||||
|
||||
### 3.2 SQL DDL 内联注释（DDL 块也要写）
|
||||
|
||||
DATA_MODEL 中的 SQL DDL 块也必须有中文 `-- 注释`：
|
||||
|
||||
```sql
|
||||
CREATE TABLE properties (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- 主键（系统生成）
|
||||
name VARCHAR(100) NOT NULL, -- 房源名称
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'for_sale', -- 房源状态（详见 ENUMS）
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录创建时间（系统自动）
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- 记录最后更新时间（系统自动）
|
||||
deleted_at TIMESTAMPTZ, -- 软删除时间戳；NULL=未删除
|
||||
created_by UUID REFERENCES staff(id), -- 创建人（FK 到员工表）
|
||||
updated_by UUID REFERENCES staff(id), -- 最后修改人
|
||||
version INTEGER NOT NULL DEFAULT 1 -- 乐观锁版本号（每次更新 +1）
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、技术元数据字段标准注释库
|
||||
|
||||
**这是本规范的核心交付物**——所有表的元数据字段使用统一中文注释，PM 不必逐个想，开发也能机械化套用。
|
||||
|
||||
### 4.1 通用元数据字段（每张表都要）
|
||||
|
||||
| 字段名 | 类型 | 标准中文注释 |
|
||||
|---|---|---|
|
||||
| `id` | UUID / BIGINT | 主键（系统生成，业务无关） |
|
||||
| `created_at` | TIMESTAMPTZ | 记录创建时间（系统自动） |
|
||||
| `updated_at` | TIMESTAMPTZ | 记录最后更新时间（系统自动） |
|
||||
| `deleted_at` | TIMESTAMPTZ NULL | 软删除时间戳；NULL=未删除，非 NULL=已软删除 |
|
||||
| `created_by` | FK → staff/account | 创建人（操作员工） |
|
||||
| `updated_by` | FK → staff/account | 最后修改人（操作员工） |
|
||||
| `version` | INTEGER | 乐观锁版本号（每次更新 +1，用于并发冲突检测） |
|
||||
|
||||
### 4.2 加密字段配套（涉及手机号/身份证等敏感数据）
|
||||
|
||||
| 字段名 | 类型 | 标准中文注释 |
|
||||
|---|---|---|
|
||||
| `phone_enc` | BYTEA | 手机号密文（AES-256-GCM 加密，不可直接查询） |
|
||||
| `phone_hash` | CHAR(64) | 手机号哈希（SHA-256，用于唯一性约束和精确查询） |
|
||||
| `id_card_enc` | BYTEA | 身份证号密文（AES-256-GCM 加密） |
|
||||
| `id_card_hash` | CHAR(64) | 身份证号哈希（SHA-256） |
|
||||
|
||||
### 4.3 全文检索字段
|
||||
|
||||
| 字段名 | 类型 | 标准中文注释 |
|
||||
|---|---|---|
|
||||
| `search_vector` | TSVECTOR | 全文检索向量（由触发器或 Celery 自动维护） |
|
||||
|
||||
### 4.4 排序与状态字段
|
||||
|
||||
| 字段名 | 类型 | 标准中文注释 |
|
||||
|---|---|---|
|
||||
| `sort_order` | INTEGER | 排序权重（数值越小越靠前） |
|
||||
| `is_active` | BOOLEAN | 是否启用（true=启用，false=禁用） |
|
||||
| `is_deleted` | BOOLEAN | 是否已删除（与 deleted_at 二选一，按表设计） |
|
||||
|
||||
### 4.5 计分/统计字段（多见于楼盘、房源完成度）
|
||||
|
||||
| 字段名 | 类型 | 标准中文注释 |
|
||||
|---|---|---|
|
||||
| `total_score` | SMALLINT | 总分（0-100；其他 score_* 字段加权汇总） |
|
||||
| `calculated_at` | TIMESTAMPTZ | 上次计算时间（由 Celery 异步任务更新，非实时） |
|
||||
|
||||
---
|
||||
|
||||
## 五、业务字段注释三段式（用于补全缺失项）
|
||||
|
||||
对于业务字段，使用**三段式**结构（用 / 或 ； 分隔）：
|
||||
|
||||
```
|
||||
[字段中文名]：[示例值或取值范围]；[业务规则或备注]
|
||||
```
|
||||
|
||||
**示例**：
|
||||
|
||||
| 原始（缺失） | 补全后 |
|
||||
|---|---|
|
||||
| `floor` | `所在楼层：1=底层；总楼层不超过 total_floors（CheckConstraint 校验）` |
|
||||
| `built_year` | `建成年份：如 2018；可空（老房源无记录）` |
|
||||
| `is_only_house` | `是否唯一住房：true=唯一/false=非唯一/NULL=未确认；影响交易税费计算` |
|
||||
| `completeness_score` | `房源完整度评分：0-100；由 Celery 异步计算，非实时；前端列表页展示徽章` |
|
||||
| `commission_rate` | `佣金费率：百分比，如 2.5 表示 2.5%；范围 0-10` |
|
||||
| `protection_end_at` | `保护期结束时间：null=永久保护；保护期内禁止其他经纪人接单` |
|
||||
|
||||
---
|
||||
|
||||
## 六、状态/枚举字段注释规范
|
||||
|
||||
枚举字段必须**列出所有可能值的中英对照**：
|
||||
|
||||
```markdown
|
||||
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / rented=已出租 / off_market=下架 / pending=审核中（详见 ENUMS.md §房源状态） |
|
||||
```
|
||||
|
||||
**规则**：
|
||||
1. 使用 `英文值=中文名` 的对照
|
||||
2. 多个值用 ` / ` 分隔
|
||||
3. 末尾加 `（详见 ENUMS.md §章节名）` 引用枚举权威源
|
||||
4. 默认值如有业务含义需说明（如"新建房源默认 for_sale"）
|
||||
|
||||
---
|
||||
|
||||
## 七、外键字段注释规范
|
||||
|
||||
```markdown
|
||||
| complex_id | UUID | FK → complexes.id | NOT NULL | 所属楼盘（关联 complexes 表；房源必须挂在楼盘下） |
|
||||
| seller_agent_id | UUID | FK → staff.id NULL | NULL | 出售经纪人（接单后填写；ON DELETE SET NULL） |
|
||||
| created_by | UUID | FK → staff.id NULL | NULL | 创建人（系统自动从登录会话填写） |
|
||||
```
|
||||
|
||||
**规则**：
|
||||
1. 必须说明**关联表**（"关联 X 表"）
|
||||
2. 必须说明**业务含义**（"所属楼盘"、"出售经纪人"，而非只写"complex_id"）
|
||||
3. 可空字段说明**何时为空**（"接单后填写"、"老数据无此字段"）
|
||||
|
||||
---
|
||||
|
||||
## 八、表级别补全要求
|
||||
|
||||
每张表在 DATA_MODEL 中必须有：
|
||||
|
||||
```markdown
|
||||
### 3.X `table_name` — 中文表名
|
||||
|
||||
**业务作用**：[一句话说明这张表存什么、为什么需要]
|
||||
|
||||
**关键业务规则**：
|
||||
- 规则 1（如：手机号必须加密存储）
|
||||
- 规则 2（如：跟进日志不可删除）
|
||||
- 规则 3（如：每月自动分区）
|
||||
|
||||
**字段表**：
|
||||
[标准字段表格]
|
||||
|
||||
**索引说明**：
|
||||
- idx_xxx：[为什么建这个索引，支撑什么查询]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、补全工作清单（PM 待办）
|
||||
|
||||
### 9.1 待补全文件清单
|
||||
|
||||
| DATA_MODEL 文件 | 当前覆盖率（业务字段） | 主要缺口 | 优先级 |
|
||||
|---|---|---|---|
|
||||
| DATA_MODEL_PROPERTY.md | ~75% | 技术元数据字段；部分 shop_* 字段说明；保护期字段 | P0 |
|
||||
| DATA_MODEL_CLIENT.md | ~70% | 跟进日志字段；匹配字段；技术元数据 | P0 |
|
||||
| DATA_MODEL_COMPLEX.md | ~80% | 楼栋/单元字段；技术元数据 | P1 |
|
||||
| DATA_MODEL_ORG.md | ~80% | 员工日志字段；技术元数据 | P1 |
|
||||
| DATA_MODEL_LOGIN.md（含 ACCOUNT） | ~70% | 登录尝试/会话字段；技术元数据 | P0 |
|
||||
| DATA_MODEL_PERMISSION.md | ~85% | 权限种子数据字段说明；技术元数据 | P1 |
|
||||
| DATA_MODEL_SETTING.md | ~75% | LookupItem 字段；技术元数据 | P2 |
|
||||
| DATA_MODEL_PUBLIC.md（含 TENANT/RELEASE） | ~70% | tenant/domain/release 字段；技术元数据 | P1 |
|
||||
|
||||
### 9.2 检查清单（PM 自检）
|
||||
|
||||
补完后请逐文件检查：
|
||||
|
||||
- [ ] 每个字段表的"业务说明"列**全部填写**，无空行无 "-"
|
||||
- [ ] 所有技术元数据字段（id/created_at/...）使用 §四 的标准注释
|
||||
- [ ] 所有枚举字段列出全部取值的中英对照
|
||||
- [ ] 所有外键字段说明关联表 + 业务含义
|
||||
- [ ] 每张表有"业务作用"段落
|
||||
- [ ] 每张表有"关键业务规则"段落（即使只有 1 条）
|
||||
- [ ] DDL 块的每行 SQL 都有 `-- 中文注释`
|
||||
|
||||
---
|
||||
|
||||
## 十、补全完成后开发同步流程
|
||||
|
||||
PM 补完后，开发会按以下顺序同步到 Django 代码（无需 PM 介入）：
|
||||
|
||||
| 步骤 | 同步目标 | 来源 | 工时估算 |
|
||||
|---|---|---|---|
|
||||
| 1 | `Meta.verbose_name` / `verbose_name_plural` | 表名（"### 3.X xxx — 中文表名"中的中文部分） | 30 分钟 |
|
||||
| 2 | 模型类 docstring | 表的"业务作用" + "关键业务规则" | 1 小时 |
|
||||
| 3 | 字段 `verbose_name="..."` | 字段表"业务说明"的第一段 | 3-4 小时 |
|
||||
| 4 | 字段 `help_text="..."`（关键字段） | 字段表"业务说明"的二/三段（示例 + 规则） | 2 小时 |
|
||||
|
||||
**总计开发工时**：约 7-8 小时，分批次按 app commit。
|
||||
|
||||
代码层面这些注释会被以下系统自动消费：
|
||||
- **Django Admin**：列表页/表单页直接显示中文表名和字段名
|
||||
- **drf-spectacular**：生成 OpenAPI 文档时 `verbose_name → title`、`help_text → description`
|
||||
- **Django shell / 报错信息**：使用中文字段名
|
||||
|
||||
---
|
||||
|
||||
## 十一、范例：一张完整规范的表（参考标准）
|
||||
|
||||
参考 `DATA_MODEL_PROPERTY.md` §3.X `properties` 表，补全后应类似：
|
||||
|
||||
```markdown
|
||||
### 3.1 `properties` — 房源主表
|
||||
|
||||
**业务作用**：存储经纪公司管理的所有待售/待租房屋的核心信息，是整个房源管理模块的根表。
|
||||
|
||||
**关键业务规则**：
|
||||
- 软删除：通过 `deleted_at` 标记，绝不物理删除（合规要求）
|
||||
- 楼层校验：`floor <= total_floors`（CheckConstraint）
|
||||
- 完整度异步：`completeness_score` 由 Celery 任务计算，非实时
|
||||
- 全文检索：`search_vector` 由数据库触发器自动维护
|
||||
|
||||
**字段表**：
|
||||
|
||||
| 字段 | 类型 | 约束 | 默认 | 业务说明 |
|
||||
|------|------|------|------|----------|
|
||||
| id | UUID | PK | gen_random_uuid() | 主键（系统生成，业务无关） |
|
||||
| property_type | varchar(30) | NOT NULL | - | 房源类型：apartment=住宅 / villa=别墅 / shop=商铺 / office=写字楼（详见 ENUMS） |
|
||||
| status | varchar(20) | NOT NULL | 'for_sale' | 房源状态：for_sale=在售 / sold=已成交 / rented=已出租 / off_market=下架（详见 ENUMS） |
|
||||
| name | varchar(100) | NOT NULL | - | 房源名称（如"翠湖天地 3 号楼 1502 室"，展示给客户） |
|
||||
| complex_id | UUID | FK → complexes.id | NOT NULL | 所属楼盘（房源必须挂在楼盘下） |
|
||||
| floor | smallint | NOT NULL | - | 所在楼层（1=底层；不超过 total_floors） |
|
||||
| total_floors | smallint | NOT NULL | - | 楼栋总层数 |
|
||||
| sale_price | decimal(12,2) | NULL | - | 挂牌售价：单位元；可空（仅出租房源） |
|
||||
| has_elevator | boolean | NULL | - | 是否有电梯：true=有 / false=无 / NULL=未确认 |
|
||||
| seller_agent_id | UUID | FK → staff.id NULL | NULL | 出售经纪人（接单后填写，ON DELETE SET NULL） |
|
||||
| completeness_score | smallint | NOT NULL | 0 | 房源完整度评分：0-100；由 Celery 异步计算，非实时 |
|
||||
| created_at | TIMESTAMPTZ | NOT NULL | NOW() | 记录创建时间（系统自动） |
|
||||
| updated_at | TIMESTAMPTZ | NOT NULL | NOW() | 记录最后更新时间（系统自动） |
|
||||
| deleted_at | TIMESTAMPTZ | NULL | NULL | 软删除时间戳；NULL=未删除 |
|
||||
| created_by | UUID | FK → staff.id NULL | NULL | 创建人（系统自动从登录会话填写） |
|
||||
| version | integer | NOT NULL | 1 | 乐观锁版本号（每次更新 +1） |
|
||||
| search_vector | TSVECTOR | NULL | NULL | 全文检索向量（由触发器自动维护） |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十二、变更与维护
|
||||
|
||||
- 本规范由开发与 PM 共同维护
|
||||
- DATA_MODEL 任何新增字段必须遵循本规范
|
||||
- 字段含义变更时，必须同步更新 DATA_MODEL 注释 → 触发开发同步代码注释
|
||||
- 本规范版本变更需 PM + 开发双方确认
|
||||
|
||||
**联系人**：
|
||||
- 规范问题 → Backend Engineer
|
||||
- 业务字段含义 → Product Manager
|
||||
- 枚举权威 → ENUMS.md
|
||||
Reference in New Issue
Block a user