团队博客 1：团队项目核心信息

租易 - 快捷租房管理小程序：项目核心信息
1. 项目的需求分析和商业前景
a. NABCD
N (Need 需求)：
管理者（物业 / 托管公司）：需要高效管理分散的房源、收取租金、处理报修，目前依赖 Excel 和微信群，效率低下，对账困难。
房东：特别是拥有多套房产的房东，缺乏便捷的工具来管理租约、收租和了解物业状态。
租客：希望有稳定的线上渠道支付租金、一键报修、查看账单，并与管理方 / 房东便捷沟通。
A (Approach 做法)：开发一个微信小程序，提供三个不同权限的入口，后端采用微服务架构支撑业务运行：
管理者端：仪表盘总览、房源管理、租约管理、财务统计、工单分配。
房东端：我的房源、租约查看、租金收入查看。
租客端：我的账单、在线支付、一键报修、联系房东 / 管理方。
后端架构：包含 9 个业务微服务与 2 个运维组件，通过服务注册与发现实现高效调用，保障各功能模块稳定运行。
B (Benefit 好处)：
为管理者提供数字化管理工具，提升效率，降低沟通成本。
为房东提供透明的资产管理和收益查看。
为租客提供便捷的 “支付 - 报修” 一站式服务，提升租住体验。
后端微服务架构可支持功能灵活扩展，应对业务增长需求，同时降低单一服务故障对整体系统的影响。
C (Competitors 竞争)：竞争对手有 “贝壳找房”“自如” 等大型平台，但它们更侧重于交易前。我们专注于交易后的管理、支付与维护轻量化工具，切入细分市场，降低使用门槛；且后端采用微服务设计，相比传统单体架构，在扩展性和维护性上更具优势。
D (Delivery 交付)：通过微信小程序直接推广，初期与本地小型房产托管公司合作，让他们引导其管理的房东和租客使用。通过校园周边租房市场进行地推；后端服务支持本地一键启动与生产环境部署，可快速适配合作方需求，缩短落地周期。
b. 项目的新闻稿和 FAQ
新闻稿标题：《“租易” 小程序正式上线，致力成为租房管理领域的 “轻骑兵”》
FAQ：
Q: 使用 “租易” 收费吗？
A: 租客端完全免费。管理者 / 房东端的基础功能免费，高级数据分析功能未来考虑采用订阅制。
Q: 发布后预计的活跃用户数？
A: 我们预计在发布后 3 个月内，通过与 2-3 家本地托管公司合作，实现约 500 名月活跃用户（MAU）。
Q: 后端系统支持哪些部署方式？
A: 支持本地开发环境一键启动（依赖 Docker）与生产环境容器化部署，满足不同阶段的使用需求，且部署流程简单，无需复杂配置。
c. 软件的典型用户
王经理（物业管理者）：35 岁，负责管理一个拥有 200 套分散式公寓的托管公司，追求效率。
李女士（多套房房东）：45 岁，职业股民，拥有 5 套出租房产，关心资产状态和租金准时到账。
小张（年轻租客）：22 岁，大学生 / 应届生，习惯移动支付，追求生活便利。
d. 典型用户场景
场景：租客小张的卫生间水管漏水。
小张打开 “租易” 小程序，点击 “一键报修”，拍照描述问题后提交（前端操作触发msg-svc消息通知预准备，同时将报修数据暂存至后端）。
王经理的后台通过msg-svc立即收到工单通知，在系统内操作将工单分配给合作的维修师傅（操作同步至order-svc关联工单流程，更新工单状态）。
维修师傅接单、维修、完成后在小程序内确认（状态变更通过mcp-svc的分布式锁保障数据一致性，避免重复操作）。
小张收到msg-svc推送的完成通知，并可以对服务进行评价（评价数据存储至 MongoDB，同时关联对应工单记录）。整个流程线上化，无需反复打电话催促。
e. 发现用户需求的方法
解决自己的痛点：团队成员有租房经历，亲身感受过报修难、沟通不便的痛点。
深入面谈：与 2 位本地房产中介负责人和 5 位有租房经验的同学进行了半结构化访谈。
用户调查问卷：在校园内发放了线上问卷，回收有效问卷 120 份，量化了用户对在线支付、报修等功能的期待程度。
2. 项目的团队、估计和设计
a. 团队成员与团队模型
陈鉴祥：全栈开发 & AI 助手应用专员（同时负责后端微服务架构整体设计与服务间调用逻辑梳理）
张廷智：前端开发 (微信小程序)
何绍斌：后端开发 & 数据库设计（主导各业务微服务开发、MongoDB 数据库配置及 MinIO 文件存储集成）
郑权：项目经理
团队模型：我们采用功能团队模型，每位成员在主导自己领域的同时，也参与其他环节的讨论与评审。我们采用敏捷 Scrum 框架，由陈鉴祥担任 SCRUM Master。
b. Alpha 版功能列表
用户身份认证与多角色登录（依赖user-svc实现用户注册、登录、角色分配，通过cert-svc完成基础身份信息校验）
i. 必要需求
ii. 卫生属性
管理者 / 房东：房源信息管理（增删改查）（基于house-svc实现房源发布、审核、状态更新与上下架，文件上传功能对接file-svc）
i. 必要需求
ii. 核心功能
租客：在线查看账单与支付（模拟支付）（账单数据关联order-svc订单信息，支付功能通过pay-svc实现支付单生成、模拟支付与回调处理）
i. 必要需求
ii. 杀手功能
租客：一键报修 & 管理者：工单处理（报修数据触发order-svc工单创建，工单分配与状态更新通过mcp-svc保障数据一致性，消息通知依赖msg-svc）
i. 必要需求
ii. 核心功能、让人惊喜的功能（如果流程足够流畅）
c. 工作估计与方法
估计方法：采用计划扑克进行故事点估算。参考历史速度（Velocity）来预测每个 Sprint 能完成的工作量。
典型功能（在线支付）的 WBS:
设计支付界面 UI (1 天)
后端创建支付订单 API（基于pay-svc开发，关联order-svc订单数据，1.5 天）
集成微信支付 SDK（或模拟接口）（在pay-svc内实现，对接微信支付接口或开发模拟支付逻辑，2 天）
前端调用支付接口并处理回调（前端对接pay-svc接口，处理支付成功 / 失败回调，1.5 天）
支付状态更新与通知（支付状态同步至order-svc更新订单状态，通过msg-svc推送支付结果通知，1 天）
单元测试与联调（针对pay-svc、order-svc、msg-svc相关接口进行测试，保障服务间调用正常，1 天）
总计预估：8 人天
后端微服务开发额外工作项（以house-svc为例）：
服务初始化与 Consul 注册配置（0.5 天）
房源数据模型设计与 MongoDB 表结构创建（0.5 天）
房源增删改查 API 开发（1 天）
房源审核流程与状态流转逻辑实现（1 天）
对接file-svc实现房源图片上传功能（0.5 天）
单元测试与服务间联调（0.5 天）
总计预估：4 天
d. 收集 NPS（净推荐值）
我们计划在用户完成一次关键操作（如成功报修或支付）后，弹出一个简单的评分框（0-10 分），并询问 “您有多大可能向您的朋友或同事推荐‘租易’？”。同时，也会在阶段性项目结束后，通过用户问卷进行更深入的 NPS 调查；调查数据将通过后端接口存储至 MongoDB，便于后续统计分析。
3. 项目的具体开发和推进
a. 代码质量保证
Git Flow: 采用简化的 GitHub Flow 模型，即 main 分支为稳定版，所有新功能从 main 拉取 feature/* 分支开发（后端各微服务单独在对应 service 目录下开发，避免代码冲突），完成后通过 Pull Request 合并，强制要求至少一名其他成员进行代码审查。
代码规范：前端使用 ESLint，后端使用 Prettier 统一代码风格。在 PR 合并前，必须通过 CI 流水线（使用 GitHub Actions）的自动化测试（包括单元测试，后端需覆盖各微服务核心 API 测试）。
后端服务质量保障：各微服务启动后自动暴露 API 文档（地址：http://localhost:PORT/docs），便于接口测试与文档查阅；通过 Consul 实现服务健康检查，实时监控服务运行状态，出现故障时可及时发现。
b. AI 编码工具的应用
我们积极使用 GitHub Copilot 和 Cursor 等 AI 工具，主要用于：
生成重复性代码（如 CRUD API 模板，后端各微服务的基础接口可借助 AI 快速生成）。
编写单元测试用例（针对pay-svc支付逻辑、order-svc订单流程等核心模块，AI 辅助生成测试代码）。
辅助代码注释和文档生成（帮助完善各微服务 API 文档注释，提升代码可读性）。
确保正确性：我们坚持 TDD 原则。在实现一个支付功能前，先编写该功能的失败单元测试。然后利用 AI 生成代码草案，并运行测试直至通过。最后进行人工审查，确保代码逻辑与业务需求一致，而不仅仅是测试通过。
c. 推动开发进展
我们通过每日站会同步进度、困难和计划。站会记录（包括成员更新、遇到的阻塞问题）会简洁地发布在团队博客中，作为过程证据。具体格式遵循课程链接中的要求。
后端开发额外同步内容：各微服务开发进度、服务间调用问题、运维组件（MongoDB、MinIO、Consul）运行状态等，确保后端架构稳定支撑前端功能。
d. 参考团队博客
我们已仔细阅读福州大学团队的博客，从中学习了如何有效地进行任务分解、进度可视化和团队协作，特别是在 Beta 阶段如何根据用户反馈进行快速迭代。他们的经验对我们规划自己的 Sprint 非常有帮助；同时，我们也参考了微服务架构设计最佳实践，优化了后端服务拆分与调用逻辑。
e. 后端架构与部署说明
（1）整体架构
层级
组件
端口
说明
业务服务
user-svc
8001
用户注册 / 登录 / 头像 / 角色管理，支撑前端多角色登录功能

house-svc
8002
房源发布 / 审核 / 状态更新 / 上下架，为管理者 / 房东端房源管理提供后端支持

order-svc
8003
订单全流程 + 时间链 + 合同关联，涵盖工单创建、流转与租约订单管理

pay-svc
8004
支付单生成 / 模拟支付 / 回调处理，实现租客端在线支付功能

msg-svc
8005
模板消息 / 短信 / 站内信 / 弹窗推送，支撑工单通知、支付结果通知等场景

cert-svc
8006
身份认证 + 资质审核 + 电子签章，保障用户身份真实性与合同法律效力

file-svc
8007
文件上传 / 下载 / 权限控制（集成 MinIO），处理房源图片、报修照片、合同文件等

mcp-svc
8008
分布式锁 + 上下文缓存 + 全局配置，保障服务间数据一致性，统一系统配置

agent-svc
8009
智能客服 / 自然语言处理 / 代操作，未来可扩展智能找房、自动回复等功能
运维底座
Consul
8500
服务注册、发现、健康检查，实现后端服务动态调用与状态监控

MongoDB
27017
统一存储结构化数据，支撑各微服务数据持久化需求

MinIO
9000
统一文件对象存储（兼容 S3 协议），通过file-svc对外提供文件操作接口

（2）服务间调用链
用户操作（前端）→ user-svc（身份验证）→ 业务服务（如house-svc房源查询、order-svc工单创建）→ 支撑服务（如file-svc文件上传、msg-svc消息推送）→ mcp-svc（保障数据一致性）→ 数据存储（MongoDB/MinIO）。所有服务间调用均通过 InternalClient + Consul 自动发现，零硬编码地址，提升系统灵活性。
（3）核心流程说明（电子签章流程）
租客通过前端创建租约订单，order-svc生成订单并初始化合同（分配 contract_id）。
租客 / 房东在前端上传电子签名，请求发送至cert-svc，cert-svc关联订单 ID 存储签名文件（文件实际存储于 MinIO，通过file-svc处理），并更新合同状态为 tenant_signed/landlord_signed。
双方签名完成后，平台自动加盖公章，cert-svc将合同状态更新为 sealed。
msg-svc向租客 / 房东推送合同完成通知，前端可通过接口从file-svc获取合同 PDF 下载地址。
（4）部署与启动方式
本地开发环境一键启动：

1. 克隆仓库

git clone https://github.com/yourname/house-rental.git && cd house-rental

2. 启动运维底座（MongoDB + MinIO + Consul）

docker-compose -f docker-compose.infra.yml up -d

3. 安装公共依赖库

cd common && pip install -e .

4. 并行启动所有业务服务

./start-local.sh

访问运维组件控制台

Consul UI：http://localhost:8500（查看服务注册状态）
MinIO 控制台：http://localhost:9000（账号：admin，密码：password，管理文件存储）

通用接口调用示例：

用户注册（调用user-svc）

curl -X POST http://localhost:8001/api/user/register
-H "Content-Type: application/json"
-d '{"phone":"13800000000","password":"123456","id_card":"110101200001011234","real_name":"张三","role":"tenant"}'

房东发布房源（调用house-svc，需携带JWT令牌）

curl -X POST http://localhost:8002/api/house
-H "Authorization: Bearer "
-d '{"title":"朝阳两居","price":6000,"area":80,"address":"北京市朝阳区XX路","room_count":2,"hall_count":1,"toilet_count":1,"status":"pending_review"}'

租客创建订单（调用order-svc，自动关联合同）

curl -X POST http://localhost:8003/api/order
-H "Authorization: Bearer "
-d '{"house_id":"xxx","start_date":"2025-12-01","end_date":"2025-12-31","rent":6000,"deposit":6000}'

模拟支付（调用pay-svc）

curl -X POST http://localhost:8004/api/pay//simulate
-H "Authorization: Bearer "

智能客服对话（调用agent-svc）

curl -X POST http://localhost:8009/api/agent/chat
-H "Authorization: Bearer "
-d '{"message":"帮我找朝阳两居，月租6000左右"}'

生产环境部署：

构建服务镜像并启动所有组件

docker-compose -f docker-compose.prod.yml up -d

注意事项：
所有业务服务