房产中介信息发布系统软件设计说明书

1. 引言

本设计说明书用于指导开发、测试与运维人员全面理解系统的结构与行为，明确各模块职责、接口约束、数据模型以及界面交互细节。通过对系统总体设计、详细设计、数据库结构和测试方案的阐述，确保后续协作过程具备统一的认知基础。说明书同时为教师或评审专家提供审查依据，也为未来的维护迭代留存完整的技术文档。

2. 项目概述

本系统定位为中小房产中介机构的轻量级信息发布平台，支持客户自助发布房源、浏览查询、留言互动，并提供管理员后台进行用户、房源与留言审核。整体采用前后端分离：后端 server.js 提供 REST API 与静态文件托管；前端 public/ 目录内以原生 HTML/CSS/JavaScript 配合 common.js 完成界面渲染与交互。数据库使用 MySQL，database/schema.sql 定义三类核心表：customers、properties、messages。系统提供脚本 scripts/init-db-node.js 和 init-admin.js 完成初始化。

3. 设计目标

• 功能性：实现注册/登录、房源发布与搜索、留言互动、个人中心管理、管理员审查等完整业务闭环。
• 可用性：界面布局遵循单页化结构，顶部导航统一由 common.js 动态渲染。
• 安全性：express-session 管理会话，bcrypt 加密密码；路由中以中间件划分普通客户与管理员权限。
• 可扩展性：后端将业务拆分为 routes/*.js 模块，结合 MySQL 连接池 config/database.js 降低资源消耗，便于横向扩展。
• 可维护性：大量注释说明函数职责，前端复用 apiRequest、showAlert 等公共方法；数据库层使用外键约束和软删除策略保证数据一致。

4. 总体架构设计

4.1 技术栈

• 前端：静态 HTML（public/*.html），统一引入 css/style.css 与各自 JS（index.js、properties.js 等）。
• 后端：Node.js（Express 4.x）、body-parser、express-session、multer（预留上传）、mysql2/promise。
• 数据库：MySQL 8.x，UTF8MB4 字符集。
• 部署：通过 npm start 启动后端，静态资源由同一进程提供。

4.2 逻辑分层

• 表现层：浏览器端页面，负责收集输入、展示数据、调用 API。
• 控制层：Express 路由（routes/auth.js 等）实现权限校验、参数验证及业务调度。
• 数据访问层：config/database.js 暴露的 pool 提供统一连接，所有 SQL 通过 pool.execute 执行。
• 数据层：MySQL 表结构支撑业务数据持久化，外键实现关联。

4.3 部署拓扑

单机部署时，Node 进程同时承担 API 与静态文件职责，浏览器直接访问 http://host:3000。若要扩展，可将静态资源托管至 CDN，再由反向代理（Nginx）将 /api/ 转发至 Node 集群。数据库独立部署，必要时开启主从复制。

5. 功能模块设计

5.1 用户与认证模块

routes/auth.js 提供注册、登录、登出、状态查询四类接口：

• POST /api/auth/register：校验必填字段、用户名和身份证唯一性，调用 bcrypt.hash 存储密码。
• POST /api/auth/login：校验用户名与密码，管理员默认凭证 admin/admin123 便于初始化。成功后在 req.session 写入 userId/username/role/name。
• POST /api/auth/logout：销毁 Session。
• GET /api/auth/current：返回当前登录用户信息，供前端刷新登录态。

5.2 客户模块

routes/customer.js 通过 requireAuth 中间件确保登录：

• GET /api/customer/profile：查询个人资料，返回 username/name/id_card/birth_date/gender/email/address/phone 等字段。
• PUT /api/customer/profile：允许修改资料与密码。若提供 oldPassword/newPassword，后端验证旧密后 bcrypt.hash 新密，并在用户名或密码改变时返回 needRelogin=true。
• GET /api/customer/properties：列出当前用户发布的房源（排除 status='deleted'）。
• DELETE /api/customer/properties/:id：软删除，验证房源归属后将 status 置为 deleted。

5.3 房产信息模块

routes/property.js 面向所有用户：

• GET /api/property：支持关键词、价格范围、户型筛选与分页，联合查询 customers 返回发布者姓名。
• GET /api/property/:id：返回详情（含联系方式）。
• POST /api/property：登录用户发布房源，自动生成 property_number（递增字符串），验证面积/价格等字段有效性。
• GET /api/property/types/list：返回去重后的户型列表供前端下拉框使用。

5.4 留言模块

routes/message.js：

• GET /api/message：查看全站留言及关联房源。
• GET /api/message/property/:propertyId：查看指定房源留言含回复链。
• POST /api/message：登录用户发布留言，可关联房源或回复其他留言。
• GET /api/message/my：返回当前用户留言供个人中心展示。

5.5 管理员模块

routes/admin.js 使用 requireAdmin 校验角色：

• 客户管理：GET /customers、GET /customers/:id、PUT /customers/:id、DELETE /customers/:id（禁止删除自己）。
• 房产管理：GET /properties（含全部非删除状态）、PUT /properties/:id 更新字段与 status、DELETE /properties/:id 软删除。
• 留言管理：GET /messages 查看全站留言，DELETE /messages/:id 物理删除。

6. 模块交互与数据流

• 前端 common.js 封装 apiRequest（默认 credentials:'include'），统一处理 JSON 和错误。
• 登录/注册：login.js、register.js 负责表单提交与提示，登录成功后依据角色跳转首页或后台。
• 房源展示：index.js 与 properties.js 构造查询参数，调用 /api/property，并在详情弹窗中并发获取房源与留言。
• 个人中心：profile.js 依次调用 loadProfile、loadMyProperties、loadMyMessages，Tab 切换通过 switchTab 控制。
• 留言回复：replyToMessage 记录目标 ID，submitReply 以 replyTo 字段提交，后端基于自关联查询展示回复链。
• 管理后台：admin.js 在 DOMContentLoaded 后检查权限、加载三大列表，并通过模态窗进行编辑。

7. 用户界面设计

7.1 导航与布局

• 所有页面共享顶部导航与 .main-content 主容器。
• updateNavMenu() 会根据登录状态动态渲染用户菜单：未登录显示 登录/注册，已登录显示用户名、个人中心、留言板、登出，管理员额外显示“管理员”入口。

7.2 核心页面

• 首页 (index.html)：包含搜索面板（关键词、价格、户型）和房源卡片网格（9条/页），卡片展示图片、编号、户型、面积、价格、发布人。
• 房产列表 (properties.html)：类似首页但提供“发布房产”按钮（登录用户可见），弹出 publishModal 填写房源数据。
• 留言板 (messages.html)：以列表形式展示留言及关联房源，登录用户可直接留言。
• 登录/注册页：居中卡片布局，使用 showLoginAlert 顶部提示。
• 个人中心 (profile.html)：Tab 切换“账号信息/我的房产/我的留言”。信息表单支持密码修改；“我的房产”以卡片列出并允许删除；“我的留言”显示时间线。
• 管理员后台 (admin.html)：Tab 切换“客户/房产/留言”，每个板块以表格呈现，配合模态窗编辑。

7.3 交互细节

• 所有表单在前端校验必填项与数值范围，失败时调用 showAlert。
• 模态窗由 openModal/closeModal 控制，点击遮罩可关闭。
• 分页按钮根据 currentPage/totalPages 动态禁用，分页集中在 5 页范围并使用“…”压缩。
• 留言列表使用 escapeHtml 防止 XSS。

8. 数据库设计

8.1 数据库概览

• 数据库：real_estate_agency，字符集 utf8mb4。
• 表：customers、properties、messages。
• 外键：properties.customer_id -> customers.id（删除客户时级联删除房源），messages.customer_id -> customers.id（级联删除），messages.property_id -> properties.id（删除房源时设 NULL），messages.reply_to -> messages.id（设 NULL）。
• 初始化：schema.sql 创建表后插入默认管理员（密码为 admin123 的 bcrypt 哈希）。

8.2 主要字段

• customers：username、password、name、id_card、birth_date、gender、email、address、phone、role、created_at、updated_at。
• properties：property_number、customer_id、building_area、interior_area、house_type、address、house_image、estimated_price、purchase_time、status（active/sold/deleted）、时间戳。
• messages：customer_id、property_id、content、reply_to、created_at、updated_at。

8.3 数据完整性

• customers.username、customers.id_card 唯一约束。
• 删除客户会级联删除其房产和留言；管理员删除房产或客户前会弹窗确认。
• 软删除通过 status 维持历史记录，避免直接物理删除。
• purchase_time 与 birth_date 使用 DATE 类型，适合统计与筛选。
• 所有时间字段默认 CURRENT_TIMESTAMP 并支持自动更新。

9. API 设计

9.1 规范

• 所有响应遵循 { success: boolean, data?: any, message?: string } 结构。
• 状态码：400（参数错误）、401（未登录）、403（权限不足）、404（不存在）、500（服务器错误）。
• Session 依赖 Cookie，前端通过 fetch 的 credentials:'include' 自动附带。

9.2 典型接口

• POST /api/auth/register：请求体包含 username/password/name/idCard/birthDate/gender/email/address/phone。
• POST /api/auth/login：{ username, password }。
• GET /api/property：Query 参数 keyword/minPrice/maxPrice/houseType/page/pageSize。
• POST /api/property：Body 含面积、户型、地址、图片 URL、价格、购买时间。
• GET /api/message/property/:propertyId：返回留言及回复信息。
• GET /api/admin/customers / PUT / DELETE 等管理端接口。

9.3 错误处理

• pool.execute 异常将被捕获并记录日志，返回 500 与“获取信息失败：xxx”提示。
• 针对唯一性冲突（ER_DUP_ENTRY），customer.js 提供特定的“用户名已被使用/身份证号已被注册”信息。
• 前端统一通过 showAlert 反馈错误，并在控制台记录堆栈。

10. 权限与安全设计

• 角色分为 customer 与 admin。
• Session：express-session 使用 secret='real_estate_secret_key_2024'，cookie.maxAge=24h。生产环境应启用 secure 和 SameSite。
• 密码加密：bcrypt（10 轮盐）；默认管理员密码仅用于初始登录，建议上线后修改。
• 输入校验：前后端均验证必填项、防止数值越界；SQL 查询使用参数绑定，避免注入。
• XSS 防护：留言展示前 escapeHtml；图片加载失败隐藏 IMG。
• CSRF：目前依赖 Session 同源策略，可在生产加入 CSRF Token 与 helmet 头部。
• 软删除策略防止数据丢失，重要操作需用户确认。

11. 会话与状态管理

• Session 默认存储在内存，适合开发环境；生产可替换为 Redis Store。
• getCurrentUser() 在页面加载时调用，刷新用户菜单与权限显示。
• checkAuth() / checkAdmin() 在需登录/管理员页面中调用，未满足条件会重定向。
• 登出后清除 Session 并跳转首页；修改用户名/密码后引导重新登录。

12. 数据校验与异常处理

• 后端在注册、发布房源、修改资料时执行严谨校验，包含空值、数值、正数判断。
• 捕获数据库错误后在控制台输出堆栈，响应中返回用户可理解的信息。
• 前端在提交前进行 trim() 和数据类型判断，减少无效请求。
• 删除操作统一使用 confirm() 二次确认。
• 留言内容通过 escapeHtml 显示，避免脚本注入。

13. 日志与监控设计

• server.js 启动时调用 testConnection() 并输出数据库连接状态。
• 路由内若出现异常，console.error 记录错误信息与堆栈。
• 生产可引入 winston、morgan 或集中日志系统，并结合 PM2 实现进程守护。
• 监控指标包括 API 响应时间、数据库连接池使用率、错误率等。

14. 部署与运行环境

• 依赖：Node.js ≥ 16，MySQL ≥ 8。
• 初始化：npm install → node scripts/init-db-node.js → npm start。
• 配置：config/database.js 中的 host/user/password/database 应在生产通过环境变量注入。
• 端口：缺省 3000，可设置 PORT 环境变量调整。
• 反向代理：可使用 Nginx 将静态资源与 /api 分流；HTTPS 证书由代理终止。
• 备份：定期备份 MySQL 与（未来）上传的图片资源。

15. 性能与扩展性

• 数据库索引：建议为 properties(status, house_type)、properties(estimated_price)、messages(property_id, created_at) 建立索引。
• 连接池：connectionLimit=10，可依据实际业务扩容。
• 缓存：可对户型列表与热门房源结果进行缓存（Redis）。
• 静态资源压缩与 CDN 可降低带宽占用。
• 横向扩展：将 Session 存储迁至 Redis，使多实例共享会话；数据库可开启读写分离。
• 可观测性：后续接入 APM（如 NewRelic、SkyWalking）监控关键接口。

16. 测试与验收策略

• 单元测试：建议使用 Jest + supertest 对路由进行模拟调用。
• 集成测试：编写 Postman/Insomnia 集合覆盖注册、登录、房源 CRUD、留言、管理员操作。
• UI 测试：手动或 Playwright 验证页面交互（登录流程、发布房源、留言回复、管理员操作）。
• 性能测试：JMeter/Locust 针对 /api/property、/api/property/:id、/api/message 等高频接口压测。
• 安全测试：重点检查身份绕过、越权访问、XSS、SQL 注入。
• 验收：以角色为主线进行端到端验证，确保客户与管理员核心流程可闭环。

17. 未来扩展规划

• 文件上传：利用 multer + 对象存储实现户型图/证件照上传。
• 通知机制：在留言、意向表达时通过短信/邮件通知房源发布者。
• 地图能力：引入地图 API 展示房源位置、进行地理围栏搜索。
• 支付 & 合同：支持意向金支付与电子合同流程。
• 数据看板：为管理员提供房源趋势、成交率等统计图表。
• 多语言/多角色：扩展为房东/买家双端，并提供英文界面。