社区服务平台开发文档

版本：v1.0 | 日期：2026-04-02 | 状态：待开发

---

一、项目概述

本平台为社区服务综合管理系统，分为风险预警和事件核查两大核心模块，通过 AI 智能体辅助完成风险等级自动判断和社会稳定形势综合研判。

技术栈

层级	技术
前端	React 19 + Ant Design 6 + React Router 7 + Vite
后端	NestJS
数据库	（待定，建议 PostgreSQL / MySQL）
AI 智能体	外部接口（流式返回支持 SSE）

---

二、数据结构

2.1 诉求记录表（complaints）

备注字段（remark）不在列表中展示，诉求内容（content）仅在详情中展示。

字段名	类型	说明
id	string	主键
petitioner	string	诉求人姓名
phone	string	联系电话（脱敏存储）
idNo	string	身份证号（脱敏存储）
project	string	涉及房地产项目
type	string	诉求类型（枚举）
personCount	number	涉及人数
householdCount	number	涉及户数
content	string	具体诉求内容（详情可见）
date	string	诉求日期
remark	string	备注（不展示在列表）
riskLevel	number | null	风险等级（1-12，null 表示未判断）
riskBasis	string | null	风险判断依据
riskCategory	string | null	风险分类（一般/较大/重大/特别重大）
isArchived	boolean	是否已归档
isChecked	boolean	是否已核查
checkedAt	string | null	核查时间
createdAt	string	创建时间
updatedAt	string	更新时间

诉求类型枚举：

• 物业纠纷
• 消防隐患
• 虚假宣传
• 车位纠纷
• 隔音效果
• 退房诉求
• 房屋质量
• 安保问题

风险等级分类规则（前端展示用）：

riskLevel 值	分类标签	颜色
1-3	一般	green
4-6	较大	orange
7-9	重大	red
10-12	特别重大	purple

---

三、功能模块详细说明

3.1 功能一：风险等级自动判断（定时任务）

3.1.1 触发机制

• 后端定时任务，每天执行一次（建议凌晨 2:00）
• 可通过管理接口手动触发

3.1.2 执行流程

后端定时任务
  ↓
调用 GET /complaints/all 查询全部数据
  ↓
过滤出 riskLevel 为 null 或空的记录，组成待判断数组
  ↓
若待判断数组为空 → 结束任务
  ↓
将待判断数组发送给 AI 智能体
  ↓
AI 智能体返回包含 riskLevel 和 riskBasis 的结果数组
  ↓
批量更新数据库中对应记录的 riskLevel 和 riskBasis 字段
  ↓
任务完成，记录日志

3.1.3 AI 智能体请求格式（草案）

请求 Body：

{
  "task": "risk_assessment",
  "data": [
    {
      "id": "xxx",
      "type": "退房诉求",
      "personCount": 20,
      "householdCount": 5,
      "content": "诉求内容..."
    }
  ]
}

AI 智能体响应格式：

{
  "results": [
    {
      "id": "xxx",
      "riskLevel": 8,
      "riskBasis": "诉求类型为退房诉求，涉及5户，属于高风险"
    }
  ]
}

3.1.4 后端接口

接口	方法	说明
GET /complaints	GET	获取诉求列表（支持分页、筛选）
POST /complaints/trigger-risk-check	POST	手动触发风险等级判断（管理用）

3.1.5 前端对应

风险预警列表通过 GET /complaints 获取数据，替换现有 mockData，展示字段包含 riskLevel 对应的风险等级标签。

---

3.2 功能二：社会稳定形势综合研判（流式返回）

3.2.1 用户操作流程

1. 用户在「社会稳定形势综合研判」区域输入关键信息、选择类型和时间
2. 点击「研判」按钮
3. 前端打开研判弹窗，开始显示流式生成内容
4. 后端查询数据库后转发给 AI 智能体，以 SSE 流式返回结果
5. 前端实时追加显示 AI 返回的文本内容（类 Word 文档格式）

3.2.2 前端请求格式

{
  "keyword": "农民工欠薪",
  "type": "农民工欠薪欠资",
  "timeRange": {
    "start": "2025-01-01",
    "end": "2025-03-31"
  }
}

3.2.3 后端处理流程

接收前端请求（keyword + type + timeRange）
  ↓
查询数据库：根据 type 精确匹配 + date 范围筛选 + keyword 模糊匹配 content/project
  ↓
将筛选结果 + 用户输入的关键信息组装成 Prompt
  ↓
调用 AI 智能体（SSE 流式接口）
  ↓
将 AI 流式响应透传给前端（NestJS SSE / Response stream）

3.2.4 后端接口

接口	方法	说明
POST /analysis/stream	POST	研判流式接口（SSE）

响应头：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

SSE 数据格式：

data: {"type":"chunk","content":"2025年天津市农民工欠薪情况分析..."}

data: {"type":"chunk","content":"一、基本情况..."}

data: {"type":"done"}

3.2.5 前端流式消费

// 使用 fetch + ReadableStream 消费 SSE
const response = await fetch('/api/analysis/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(params)
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // 解析 SSE 格式，追加到显示内容
  setContent(prev => prev + parseSSEChunk(chunk));
}

---

3.3 功能三：归档 → 跳转核查

3.3.1 流程

1. 在风险预警列表中，点击某条记录的「归档」按钮
2. 调用归档接口，将该记录标记为 isArchived: true
3. 成功后跳转至 /safe-checked（事件核查页面）
4. 事件核查页面调用 GET /complaints/archived 接口，获取已归档的核查列表并展示

3.3.2 归档接口

接口	方法	说明
PATCH /complaints/:id/archive	PATCH	归档指定记录
GET /complaints/archived	GET	获取已归档核查列表（支持分页、筛选）

归档接口响应：

{
  "success": true,
  "message": "归档成功"
}

3.3.3 核查列表筛选参数

参数	类型	说明
keyword	string	关键词（模糊匹配诉求人姓名、项目、类型）
page	number	页码
pageSize	number	每页数量

3.3.4 核查列表展示字段

字段	说明
序号	自动生成
诉求人姓名	petitioner
联系电话	phone
涉及房地产项目	project
诉求类型	type
涉及人数	personCount
涉及户数	householdCount
具体诉求内容	content（省略号截断，详情可见全文）
诉求日期	date
风险等级	riskLevel（Tag 展示）
风险判断依据	riskBasis
操作	详情 / 核查 / 删除

---

3.4 功能四：核查操作

3.4.1 流程

1. 在核查列表中，点击「核查」按钮，弹出核查确认弹窗
2. 弹窗展示该条记录基本信息，用户确认后提交
3. 调用核查接口，后端更新 isChecked 和 checkedAt 字段
4. 前端根据返回结果提示操作成功/失败，刷新列表

3.4.2 核查接口

接口	方法	说明
PATCH /complaints/:id/check	PATCH	执行核查操作
DELETE /complaints/:id	DELETE	删除记录

核查接口响应：

{
  "success": true,
  "checked": true,
  "checkedAt": "2026-04-02T10:00:00.000Z"
}

核查失败响应：

{
  "success": false,
  "checked": false,
  "message": "核查失败，请稍后重试"
}

3.4.3 前端处理

• success: true → message.success('核查成功') + 更新列表中该条记录状态
• success: false → message.error('核查失败，请稍后重试')

---

四、接口汇总

4.1 诉求管理

接口路径	方法	功能	说明
GET /complaints	GET	获取风险预警列表	支持 keyword/type/page/pageSize
GET /complaints/archived	GET	获取核查列表	已归档数据
PATCH /complaints/:id/archive	PATCH	归档	更新 isArchived
PATCH /complaints/:id/check	PATCH	核查	更新 isChecked/checkedAt
DELETE /complaints/:id	DELETE	删除	软删除或物理删除
POST /complaints/trigger-risk-check	POST	手动触发风险判断	管理接口

4.2 研判分析

接口路径	方法	功能	说明
POST /analysis/stream	POST	综合研判流式接口	SSE 流式返回

---

五、前端开发任务拆分

5.1 风险预警页（DangerCall）

• 对接 GET /complaints 替换 mockData
• 「归档」按钮调用 PATCH /complaints/:id/archive，成功后跳转 /safe-checked
• 「研判」按钮发起 POST /analysis/stream，弹窗中流式展示结果
• 研判弹窗支持 Markdown 格式渲染（类 Word 文档样式）
• 研判弹窗支持停止生成和复制全文

5.2 事件核查页（SafeChecked）

• 对接 GET /complaints/archived 替换 mockData
• 「核查」按钮调用 PATCH /complaints/:id/check，更新列表状态
• 「删除」按钮调用 DELETE /complaints/:id
• 「详情」弹窗展示完整诉求内容（content 字段）

5.3 通用

• 封装统一 HTTP 请求工具（baseURL、错误拦截、loading 状态）
• 封装流式请求 useStream Hook

---

六、后端开发任务拆分

6.1 NestJS 模块结构

src/
├── complaints/
│   ├── complaints.controller.ts
│   ├── complaints.service.ts
│   ├── complaints.module.ts
│   └── dto/
│       ├── query-complaints.dto.ts
│       └── check-complaint.dto.ts
├── analysis/
│   ├── analysis.controller.ts
│   ├── analysis.service.ts
│   └── analysis.module.ts
├── scheduler/
│   ├── risk-check.scheduler.ts    ← 定时任务
│   └── scheduler.module.ts
└── ai-agent/
    ├── ai-agent.service.ts        ← AI 智能体调用封装
    └── ai-agent.module.ts

6.2 开发任务

• 数据库 ORM 实体定义（complaints 表）
• 投诉列表 CRUD 接口
• 归档 / 核查接口
• 定时任务（每天风险等级批量判断）
• AI 智能体调用服务封装（风险判断 + 研判流式）
• 研判 SSE 流式接口

---

七、AI 智能体对接说明

智能体正在搭建中，以下为对接约定（待智能体方确认）

7.1 风险等级判断智能体

• 调用方式：POST 请求，同步返回
• 输入：待判断的诉求数组
• 输出：含 riskLevel（1-12）和 riskBasis 的结果数组
• Key字段依赖：type、personCount、householdCount、content

7.2 综合研判智能体

• 调用方式：POST 请求，SSE 流式返回
• 输入：用户输入的关键信息 + 数据库筛选出的相关诉求数据
• 输出：流式文本，格式类似 Word 研判报告
• 后端透传：NestJS 需将 AI SSE 流透传给前端

---

八、注意事项

1. 敏感数据：电话号码、身份证号在接口返回时需做脱敏处理（前端已使用 XXXX 格式）
2. 流式超时：研判接口需设置合理超时时间，建议 120s
3. 定时任务幂等：风险等级判断任务需保证幂等，已有 riskLevel 的记录不重复发送给 AI
4. 错误处理：AI 智能体调用失败时，前端需有友好提示，不影响主流程数据展示
5. 归档状态：已归档数据在风险预警列表中仍可查看，但归档按钮变为不可点击状态

---

九、开发周期建议

阶段	内容	人员
第1天	数据库设计确认、接口文档评审、NestJS 项目初始化	前后端
第2-3天	后端：CRUD 接口 + 归档/核查接口开发	后端
第2-3天	前端：替换 mockData + 归档跳转逻辑	前端
第4天	后端：AI 智能体调用封装 + 定时任务	后端
第4-5天	后端：研判 SSE 流式接口 + 前端流式消费	前后端
第5天	联调测试、问题修复	前后端