新增笔记

Project/fonrey/UI_DESIGN/楼盘管理/区域管理_UI.md

@@ -0,0 +1,181 @@
+# 区域管理 UI 设计文档
+
+> **任务编号**：06（P0-B）  
+> **覆盖范围**：`US-COMPLEX-003`（管理员维护区域管理：城区/商圈）  
+> **输出文件**：`UI_DESIGN/区域管理_UI.html`  
+> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（列表页模板、Top Bar + Sidebar 壳层、表格/分页规范）  
+> **竞品截图参考**：
+> - `Project/fonrey/screenshots/楼盘管理/区域管理.png`
+> - `Project/fonrey/screenshots/楼盘管理/商圈管理.png`
+> - `Project/fonrey/screenshots/楼盘管理/编辑商圈.png`
+> - `Project/fonrey/screenshots/楼盘管理/查看关联.png`
+
+---
+
+## 1. 目标与范围
+
+### 1.1 页面目标
+
+区域管理页用于运营/数据管理员统一维护“城区-商圈”两级地理字典，并支撑楼盘、房源、客源模块的区域筛选与统计。
+
+核心目标：
+
+1. 在同一业务页面支持“城区管理 / 商圈管理”双子模块切换
+2. 支持关键词检索、区域过滤、有无坐标过滤
+3. 支持批量操作（合并城区、合并商圈、转移商圈）
+4. 支持新增/修改商圈弹窗维护
+5. 支持查看商圈关联关系（标准区域映射）
+
+### 1.2 本任务边界
+
+- ✅ 包含：壳层、模块 Tab、子 Tab、筛选区、批量区、表格、分页、弹窗校验、关联关系弹窗
+- ✅ 包含：竞品截图中的关键文案与字段结构（城区/商圈/关联关系）
+- ⛔ 不包含：真实后端 CRUD、真实关联跳转、真实地图 API、真实权限鉴权
+
+---
+
+## 2. 信息架构
+
+### 2.1 壳层结构（统一后台模板）
+
+- **Top Bar（固定 56px）**：品牌 + 一级导航 + 用户区
+- **Sidebar（固定 240px）**：房源管理二级导航
+- **Main Content（`ml-60 pt-[72px]`）**：
+  1. 面包屑 + 页面标题
+  2. 模块 Tab（楼盘 / 区域管理 / 学校管理 / 应用标准数据）
+  3. 区域管理子 Tab（城区管理 / 商圈管理）
+  4. 筛选区 + 批量区 + 列表区 + 分页区
+
+### 2.2 区域管理子模块
+
+#### A. 城区管理
+- 筛选：城区名称关键词 + 有无坐标（不限/有坐标/无坐标）
+- 列表字段：城区名称 / 商圈数量 / 楼盘数量 / 坐标 / 操作
+- 操作：修改、设置坐标、合并城区、新增城区
+
+#### B. 商圈管理
+- 筛选：商圈名称关键词 + 区域过滤（标签）+ 有无坐标
+- 列表字段：城区名称 / 商圈名称（含“标准”标签）/ 楼盘数量 / 坐标 / 操作
+- 操作：修改、查看关联关系、设置坐标、合并商圈、转移商圈、新增商圈
+
+### 2.3 关联关系视图（弹窗承载）
+
+- 触发：商圈列表行内「查看关联关系」
+- 筛选：标准区域（下拉）、本地区域（下拉）
+- 列表字段：标准城市 / 标准城区 / 标准商圈 / 关联本地商圈 / 本地商圈所属城区 / 操作（变更）
+- 支持批量修改按钮（勾选后启用）
+
+---
+
+## 3. 关键交互设计
+
+### 3.1 子 Tab 切换
+
+- 点击「城区管理 / 商圈管理」切换内容区
+- 切换后保留当前模块壳层和分页区风格一致
+
+### 3.2 筛选与重置
+
+- 点击「查询」执行前端过滤
+- 点击「重置」清空关键词与标签筛选，恢复默认列表
+- 坐标筛选支持：不限 / 有坐标 / 无坐标
+
+### 3.3 批量操作启用规则
+
+- 未勾选时：批量按钮禁用态
+- 勾选 1 条及以上：批量按钮启用
+- 提示区实时显示：`已选本页 N 条`
+
+### 3.4 新增/编辑弹窗
+
+#### 城区弹窗
+- 标题：新增城区 / 修改城区
+- 字段：
+  - 城区名称（必填）
+  - 城区简称（选填）
+- 校验：城区名称为空时提示“请输入城区名称”
+
+#### 商圈弹窗
+- 标题：新增商圈 / 修改商圈
+- 字段：
+  - 所属城区（必填，下拉）
+  - 商圈名称（必填，文本）
+- 校验：
+  - 未选城区：`请选择所属城区`
+  - 未填商圈名称：`请输入商圈名称`
+
+### 3.5 设置坐标弹窗
+
+- 支持城区/商圈两种来源
+- 字段：纬度、经度
+- 校验：任一为空时提示“请完整填写经纬度”
+
+### 3.6 查看关联关系弹窗
+
+- 保持“查看关联情况”核心信息结构
+- 支持顶部筛选 + 列表 + 批量修改占位
+- 点击「变更」仅触发原型提示（无真实提交）
+
+---
+
+## 4. 状态矩阵
+
+| 状态 | 触发 | 页面反馈 |
+|---|---|---|
+| 默认态 | 首次进入页面 | 默认显示“城区管理”，加载城区列表 |
+| 子模块切换 | 点击子 Tab | 切换到对应列表和筛选区 |
+| 查询态 | 输入关键词并查询 | 列表按条件过滤 |
+| 空结果态 | 条件过严 | 表格显示“暂无匹配数据” |
+| 勾选态 | 勾选行/全选 | 批量按钮启用，显示已选条数 |
+| 弹窗校验失败 | 必填缺失提交 | 字段下方红字错误，弹窗保持打开 |
+| 保存成功（原型） | 校验通过提交 | 关闭弹窗 + Toast 成功提示 |
+| 主题策略 | 统一后台视觉 | 页面内不包含 Light/Dark/System 切换控件 |
+
+---
+
+## 5. 字段与数据模型映射（DATA_MODEL_COMPLEX）
+
+| UI 字段 | 数据模型字段 |
+|---|---|
+| 城区名称 | `districts.name` |
+| 城区简称 | `districts.short_name` |
+| 所属城市 | `districts.city` |
+| 商圈名称 | `business_areas.name` |
+| 所属城区 | `business_areas.district_id -> districts.id` |
+| 商圈坐标 | `business_areas.latitude` / `business_areas.longitude` |
+| 城区坐标（原型占位） | `districts` 扩展坐标字段（PRD层业务占位） |
+| 商圈数量 | `COUNT(business_areas.id)`（按城区聚合） |
+| 楼盘数量 | `COUNT(complexes.id)`（按城区/商圈聚合） |
+| 关联本地商圈 | `business_areas.name`（映射结果） |
+| 标准城市/城区/商圈 | 标准区域字典（独立映射域，原型以 mock 展示） |
+
+---
+
+## 6. 可访问性与规范
+
+- 表格列头使用 `<th scope="col">`
+- 纯图标按钮补充 `aria-label`
+- 弹窗支持 `Esc` 关闭
+- 错误提示采用“字段下方红字文本”，不只依赖颜色
+- 焦点样式统一 `focus-visible:ring-2 focus-visible:ring-primary-600/40`
+- 页面保持浅色后台主题，不引入主题切换控件
+
+---
+
+## 7. 验收清单
+
+- [x] 壳层结构：Top Bar + Sidebar + Main
+- [x] 模块 Tab 与子 Tab 结构完整
+- [x] 城区管理筛选/列表/批量/分页完整
+- [x] 商圈管理筛选/列表/批量/分页完整
+- [x] 商圈编辑弹窗字段与校验符合 PRD Story 10
+- [x] 关联关系视图字段与交互符合 PRD Story 11
+- [x] 页面内不包含 Light/Dark/System 主题切换控件
+- [ ] 控制台 0 报错（待本地预览验证）
+
+---
+
+## 8. 后续衔接
+
+- 本页评审通过后，进入任务07：组织人事（`US-ORG-001~003`）
+- 区域字典（城区/商圈）将作为房源/客源筛选条件来源，需保持命名与状态一致

Project/fonrey/UI_DESIGN/楼盘管理/楼盘详情_UI.md

@@ -0,0 +1,176 @@
+# 楼盘详情 UI 设计文档
+
+> **任务编号**：05（P0-B）  
+> **覆盖范围**：`US-COMPLEX-001`（管理员录入与维护楼盘基础信息）  
+> **关联需求参考**：`PRD/房源管理/楼盘管理模块PRD.md` Story 2~8（楼盘详情分区信息架构）  
+> **输出文件**：`UI_DESIGN/楼盘详情_UI.html`  
+> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（Top Bar + Sidebar 壳层、详情页模板、表单与校验规范）
+
+---
+
+## 1. 目标与范围
+
+### 1.1 页面目标
+
+楼盘详情页用于运营/数据管理员在单个楼盘维度完成“查看 + 维护”闭环：
+
+1. 查看楼盘基础档案（基本信息、对口学校、其他信息）
+2. 管理楼栋与结构（楼层/房号）
+3. 查看与维护楼盘图片、附件
+4. 查看价格走势与周边配套信息
+
+### 1.2 本任务边界
+
+本任务交付“楼盘详情静态高保真原型”，重点完成信息架构与关键交互演示。
+
+- ✅ 包含：壳层、详情头部、分区 Tab、编辑抽屉、必填校验、批量操作占位、分页占位
+- ✅ 包含：底部固定操作区（编辑态）且按钮右对齐
+- ⛔ 不包含：真实接口联动、地图 API、图表库渲染、上传存储、权限后端判定
+
+---
+
+## 2. 信息架构
+
+### 2.1 壳层结构（统一后台模板）
+
+- **Top Bar（固定 56px）**：品牌 + 一级导航 + 用户区
+- **Sidebar（固定 240px）**：房源管理二级导航
+- **Main Content（`ml-60 pt-[72px]`）**：
+  1. 面包屑 + 楼盘标题 + 锁定标签 + 顶部动作按钮
+  2. 楼盘详情分区 Tab（8 个）
+  3. Tab 内容区域
+
+### 2.2 楼盘详情分区 Tab（页面级）
+
+1. 楼盘信息（默认）
+2. 楼栋管理
+3. 结构管理
+4. 楼盘照片
+5. 楼盘附件
+6. 周边配套
+7. 楼盘价格走势
+8. 销控盘
+
+### 2.3 楼盘信息分区结构（默认 Tab）
+
+- **基本信息**：城区商圈、地址、建筑类型、楼栋结构、别名、竣工年限、坐标等
+- **对口学校**：学校名称/类型/性质/等级表格
+- **其他信息**：面积、容积率、绿化率、物业信息、车位信息、供水供电、备注
+- **右侧辅助面板**：维护完成度、锁定状态、相关员工、快捷操作
+
+---
+
+## 3. 关键交互设计
+
+### 3.1 页面级交互
+
+1. 点击分区 Tab 切换对应内容（单页切换）
+2. 顶部「解锁楼盘」按钮触发提示（原型态）
+3. 顶部「编辑楼盘信息」打开右侧编辑抽屉
+
+### 3.2 编辑抽屉（楼盘信息维护）
+
+- 抽屉分为：基本信息 / 学校信息 / 其他信息 三段
+- 必填字段校验：
+  - 物业类型（必填）
+  - 楼栋结构（必填）
+- 小区名称、小区地址为只读灰底展示
+- 底部固定操作区：
+  - `取消`（次按钮）
+  - `保存`（主按钮）
+- 底部操作区始终固定，按钮右对齐
+
+### 3.3 楼栋管理交互
+
+- 关键词搜索单元名
+- 行勾选 + 表头全选
+- 批量按钮（批量设置/合并/移动）随选中状态启用
+- 每行操作：编辑 / 结构管理
+
+### 3.4 结构管理交互
+
+- 左侧单元列表（可切换当前单元）
+- 右侧楼层-房号矩阵
+- 房号勾选后启用“批量编辑房号/合并房号”
+- 提示区显示“已选 N 条”与异常结构入口占位
+
+### 3.5 其他分区交互（原型演示）
+
+- 楼盘照片：分类切换（楼盘图片/户型图/楼盘VR）+ 户型过滤占位
+- 楼盘附件：上传入口占位 + 附件列表
+- 周边配套：分类切换（交通/教育/医疗/购物/生活/娱乐）+ 地图占位
+- 价格走势：司内/市场子 Tab 切换 + 图表占位 + 明细表
+
+---
+
+## 4. 状态矩阵
+
+| 状态 | 触发 | 页面反馈 |
+|---|---|---|
+| 默认态 | 首次进入页面 | 默认激活“楼盘信息”Tab，展示详情概览 |
+| Tab 切换 | 点击分区 Tab | 内容区域切换，对应 Tab 高亮 |
+| 打开编辑 | 点击“编辑楼盘信息” | 右侧抽屉滑入，加载当前字段值 |
+| 校验失败 | 抽屉内点击保存且必填缺失 | 字段下方显示错误文本 + 保持抽屉打开 |
+| 保存成功（原型） | 抽屉内点击保存且校验通过 | 抽屉关闭 + Toast“楼盘信息已保存（原型）” |
+| 楼栋批量态 | 勾选楼栋行 | 批量按钮启用，显示已选条数 |
+| 结构批量态 | 勾选房号 | 矩阵批量按钮启用，显示已选条数 |
+| 空数据态 | 学校/附件/成交明细为空 | 使用“暂无数据”占位与引导文案 |
+| 主题策略 | 全局后台视觉 | 页面内不提供 Light/Dark/System 切换控件 |
+
+---
+
+## 5. 字段与数据模型映射（DATA_MODEL_COMPLEX）
+
+| UI 字段 | 数据模型字段 |
+|---|---|
+| 楼盘名称（只读） | `complexes.name` |
+| 城区商圈 | `complexes.district_id` + `complex_business_areas` |
+| 小区地址（只读） | `complexes.address` |
+| 概要地址 | `complexes.address_summary` |
+| 物业类型（多选） | `complexes.property_usage_types` |
+| 楼栋结构 | `complexes.building_structure` |
+| 建筑类型 | `complexes.building_type` |
+| 土地使用年限 | `complexes.land_use_years` |
+| 竣工年限 | `complexes.built_years` |
+| 权属类别 | `complexes.ownership_category` |
+| 单元总数/总户数 | `complexes.total_units` / `complexes.total_households` |
+| 经纬度坐标 | `complexes.latitude` / `complexes.longitude` |
+| 对口学校 | `complex_schools` + `schools` |
+| 楼栋列表 | `buildings` |
+| 楼层房号矩阵 | `room_units` |
+| 图片资源 | `complex_photos` |
+| 附件 | `complex_attachments` |
+| 价格走势 | `complex_price_trends` |
+| 锁定标签 | `lock_building` / `lock_room` / `lock_info` / `lock_standard_room` |
+
+---
+
+## 6. 可访问性与规范
+
+- 表格列头使用语义化 `<th scope="col">`
+- 抽屉与弹层支持 `Esc` 关闭
+- 纯图标按钮均带 `aria-label`
+- 表单错误提示为“字段下方红字 + 文本说明”，不只靠颜色
+- 所有可交互控件支持 `focus-visible:ring-2`
+- 页面采用统一浅色后台主题，不包含主题切换控件
+
+---
+
+## 7. 验收清单
+
+- [x] 壳层结构：Top Bar + Sidebar + Main
+- [x] 楼盘详情头部信息与锁定标签完整
+- [x] 8 个分区 Tab（楼盘信息/楼栋/结构/照片/附件/配套/价格/销控盘）完整
+- [x] 楼盘信息包含“基本信息/对口学校/其他信息”三段
+- [x] 编辑抽屉具备必填校验（物业类型、楼栋结构）
+- [x] 编辑态底部按钮固定且右对齐
+- [x] 楼栋管理与结构管理具备勾选 + 批量操作演示
+- [x] 页面内不包含主题切换控件
+- [ ] 控制台 0 报错（待本地预览验证）
+
+---
+
+## 8. 后续衔接
+
+- 本页评审通过后，继续任务06：区域管理（`US-COMPLEX-003`）
+- 区域管理将与本页“城区商圈”字段形成前后联动（字典数据来源一致）