commit fe43ea473cf264161b9bd003e1b31cda2c0b03e0 Author: xiaji Date: Mon May 18 16:08:04 2026 +0800 添加社区服务中心综合管理平台系统规划书 diff --git a/系统规划书.md b/系统规划书.md new file mode 100644 index 0000000..a90ab92 --- /dev/null +++ b/系统规划书.md @@ -0,0 +1,850 @@ +# 社区服务中心综合管理平台 — 系统规划书 + +--- + +## 一、项目概述 + +### 1.1 项目背景 + +社区服务中心是基层社会治理的核心枢纽，承担着代理代办、代发代收、代销代购、代开证明、公益服务、民意反映与政策咨询等七大类数十项便民服务。当前业务多依赖纸质台账与人工流转，存在以下痛点： + +- **流程不透明**：居民无法实时查询办理进度，需多次跑腿 +- **数据孤岛**：各业务线台账独立，无法形成居民画像与数据联动 +- **统计困难**：缺乏数字化手段，月度/年度统计依赖人工汇总 +- **服务可及性差**：居民需到现场办理，缺少线上渠道 + +### 1.2 项目目标 + +建设一套基于 Django 的社区服务中心综合管理平台，实现： + +1. **全业务线上化**：七大类服务全部纳入系统管理 +2. **流程可追溯**：每笔业务从申请到办结全程留痕 +3. **数据一体化**：居民信息统一管理，业务数据互通 +4. **统计可视化**：提供多维度数据看板，辅助决策 +5. **服务便捷化**：居民可通过微信小程序/网页提交申请、查询进度 + +### 1.3 项目范围 + +| 维度 | 范围 | +|------|------| +| 用户群体 | 普通居民（前端申请）、社区网格员（移动端核验）、社区管理员（后台管理）、街道审核员（跨社区审批）、系统管理员（系统运维） | +| 业务域 | 代理代办、代发代收、代销代购、代开证明、公益服务、民意反映、社区治理 | +| 技术栈 | Django 5.x + Django REST Framework + PostgreSQL + Redis + Vue 3 / 微信小程序 | +| 部署方式 | 初期单机部署，后期可容器化上云 | + +--- + +## 二、系统架构设计 + +### 2.1 总体架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 前端展示层 │ +│ ┌──────────┐ ┌──────────────┐ ┌───────────────────┐ │ +│ │ 管理后台 │ │ 居民小程序 │ │ 数据看板大屏 │ │ +│ │ (Vue 3) │ │ (WeChat Mini)│ │ (ECharts) │ │ +│ └────┬─────┘ └──────┬───────┘ └────────┬──────────┘ │ +└───────┼───────────────┼───────────────────┼─────────────┘ + │ │ │ + ▼ ▼ ▼ +┌─────────────────────────────────────────────────────────┐ +│ API 网关层 │ +│ Django REST Framework + JWT Auth │ +│ CORS / Rate Limit / API Versioning │ +└─────────────────────────┬───────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 业务逻辑层 (Django) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │ +│ │代理代办 │ │代发代收 │ │代销代购 │ │代开证明 │ │ +│ │模块 │ │模块 │ │模块 │ │模块 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │公益服务 │ │民意反映 │ │社区治理 │ │ +│ │模块 │ │模块 │ │模块 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │用户权限 │ │通知消息 │ │数据统计 │ │ +│ │模块 │ │模块 │ │模块 │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────┬───────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 数据持久层 │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ PostgreSQL │ │ Redis │ │ MinIO/OSS │ │ +│ │ (主数据库) │ │ (缓存/会话) │ │ (文件存储) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +### 2.2 技术选型与决策记录 + +| 决策项 | 选型 | 备选方案 | 选择理由 | +|--------|------|----------|----------| +| 后端框架 | Django 5.x + DRF | Flask, FastAPI | 自带 Admin、ORM 成熟、生态丰富、社区业务 CRUD 密集型适合 | +| 数据库 | PostgreSQL 15+ | MySQL, SQLite | JSON 字段支持好、扩展性强、社区版免费 | +| 缓存 | Redis 7+ | Memcached | 支持数据结构丰富，可用于会话、队列、缓存 | +| 前端管理后台 | Vue 3 + Element Plus | React, Ant Design | 国内生态好、组件丰富、上手快 | +| 居民端 | 微信小程序 | H5, 支付宝小程序 | 社区居民微信覆盖率高、无需安装 | +| 文件存储 | MinIO / 阿里云 OSS | 本地磁盘 | 初期 MinIO 自建，后期可迁移云存储 | +| 任务队列 | Celery + Redis | Django-Q, Huey | 生态成熟、支持定时任务、社区文档丰富 | +| 部署 | Docker Compose | K8s, 裸机 | 初期规模小，Docker Compose 足够，后期可平滑迁移 K8s | + +### 2.3 Django 项目结构 + +``` +community_center/ +├── manage.py +├── config/ +│ ├── settings/ +│ │ ├── base.py +│ │ ├── development.py +│ │ └── production.py +│ ├── urls.py +│ ├── wsgi.py +│ └── celery.py +├── apps/ +│ ├── accounts/ # 用户与权限 +│ ├── residents/ # 居民信息管理 +│ ├── agency/ # 代理代办服务 +│ ├── distribution/ # 代发代收服务 +│ ├── legal_psych/ # 代销代购（法律与心理援助） +│ ├── certification/ # 代开证明 +│ ├── public_service/ # 公益服务 +│ ├── feedback/ # 民意反映与政策咨询 +│ ├── governance/ # 社区治理 +│ ├── notification/ # 通知消息 +│ └── statistics/ # 数据统计 +├── templates/ +├── static/ +├── media/ +├── requirements/ +│ ├── base.txt +│ ├── development.txt +│ └── production.txt +├── docker-compose.yml +├── Dockerfile +└── .env.example +``` + +--- + +## 三、功能模块详细设计 + +### 3.1 用户与权限模块 (accounts) + +#### 3.1.1 用户角色 + +| 角色 | 主要职责 | 典型权限范围 | +|------|----------|--------------| +| 普通居民 | 浏览服务事项、提交申请、查询进度、评价反馈、提意见建议 | 本人信息、本人申请单、公共服务查询 | +| 社区网格员 | 初步审核申请、上门核验、代填代报、通知领取物资/证明 | 辖区居民信息、待办任务、物资发放登记 | +| 社区管理员 | 事项配置、审批流转、统计报表、志愿者管理、活动发布 | 全部居民数据、审批权限、系统配置 | +| 街道审核员 | 对需上级审批的事项（如低保申请、医疗救助）进行终审 | 跨社区申请单、特殊事项审核 | +| 系统管理员 | 用户管理、角色权限、日志审计、数据备份 | 全部系统功能 | + +#### 3.1.2 核心功能 + +- 用户注册/登录（居民支持微信授权登录） +- 基于 Django Guardian 的对象级权限控制 +- 角色分配与权限管理 +- 操作日志审计 + +#### 3.1.3 数据模型 + +```python +ROLE_CHOICES = [ + ('resident', '普通居民'), + ('grid_worker', '社区网格员'), + ('community_admin', '社区管理员'), + ('street_auditor', '街道审核员'), + ('system_admin', '系统管理员'), +] + +class User(AbstractBaseUser): + phone = models.CharField(max_length=11, unique=True) + name = models.CharField(max_length=50) + id_card = models.CharField(max_length=18, blank=True) + role = models.CharField(choices=ROLE_CHOICES) + community = models.ForeignKey('Community') + is_staff = models.BooleanField(default=False) + +class Community(models.Model): + name = models.CharField(max_length=100) + address = models.CharField(max_length=300) + contact_phone = models.CharField(max_length=11) + director = models.ForeignKey(User) +``` + +### 3.2 居民信息管理模块 (residents) + +#### 3.2.1 核心功能 + +- 居民档案 CRUD（姓名、身份证、住址、联系方式、家庭成员关系） +- 居民标签体系（低保户、残疾人、退役军人、独居老人等） +- 家庭关系图谱 +- 居民信息变更记录 + +#### 3.2.2 数据模型 + +```python +class Resident(models.Model): + name = models.CharField(max_length=50) + id_card = models.CharField(max_length=18, unique=True) + gender = models.CharField(choices=GENDER_CHOICES) + birth_date = models.DateField() + phone = models.CharField(max_length=11) + address = models.TextField() + community = models.ForeignKey(Community) + tags = models.ManyToManyField('ResidentTag') + family = models.ForeignKey('Family', null=True) + +class ResidentTag(models.Model): + name = models.CharField(max_length=30) + category = models.CharField(choices=TAG_CATEGORY_CHOICES) + +class Family(models.Model): + head = models.ForeignKey(Resident) + address = models.TextField() +``` + +### 3.3 代理代办服务模块 (agency) + +#### 3.3.1 业务分类与流程 + +``` +居民提交申请 → 经办人受理 → 审核材料 → 办理/代办 → 结果通知 → 归档 +``` + +#### 3.3.2 业务子类 + +| 子类编码 | 业务名称 | 所需材料 | 办理时限 | +|----------|----------|----------|----------| +| A01 | 生育服务证代办 | 身份证、结婚证、户口本 | 5个工作日 | +| A02 | 独生子女证代办 | 身份证、户口本、出生证明 | 5个工作日 | +| A03 | 老年优待证代办 | 身份证、照片 | 3个工作日 | +| A04 | 暂住证代办 | 身份证、居住证明 | 5个工作日 | +| A05 | 残疾证代办 | 身份证、医院诊断证明 | 7个工作日 | +| A06 | 最低生活保障金申请 | 身份证、收入证明、困难证明 | 15个工作日 | +| A07 | 困难人员临时救助申请 | 身份证、困难说明 | 10个工作日 | +| A08 | 重残生活困难补助申请 | 身份证、残疾证 | 10个工作日 | +| A09 | 特困人员医疗救助申请 | 身份证、医疗费用清单 | 10个工作日 | +| A10 | 低保/优抚对象租房申请 | 身份证、低保证/优抚证明 | 15个工作日 | +| A11 | 失业/求职登记代理 | 身份证、学历证明 | 3个工作日 | +| A12 | 新生儿登记代理 | 出生证明、父母身份证 | 3个工作日 | +| A13 | 丧偶登记代理 | 身份证、配偶死亡证明 | 3个工作日 | +| A14 | 养犬登记代理 | 身份证、犬只免疫证明 | 5个工作日 | +| A15 | 出租房屋登记代理 | 房产证、租赁合同 | 5个工作日 | +| A16 | 流动人口婚育证明验证 | 身份证、原籍婚育证明 | 3个工作日 | +| A17 | 子女入托/借读证明代办 | 身份证、居住证明 | 3个工作日 | +| A18 | 党团组织关系转接代办 | 身份证、组织关系介绍信 | 5个工作日 | +| A19 | 退休人员医保关系转移代办 | 身份证、退休证明 | 7个工作日 | +| A20 | 退休人员医疗费报销代办 | 身份证、医疗费用清单 | 10个工作日 | + +#### 3.3.3 数据模型 + +```python +class AgencyServiceCategory(models.Model): + code = models.CharField(max_length=10, unique=True) + name = models.CharField(max_length=100) + required_docs = models.JSONField(default=list) + processing_days = models.IntegerField() + description = models.TextField(blank=True) + +class AgencyApplication(models.Model): + STATUS_CHOICES = [ + ('draft', '草稿'), + ('submitted', '已提交'), + ('accepted', '已受理'), + ('processing', '办理中'), + ('completed', '已办结'), + ('rejected', '已退回'), + ] + applicant = models.ForeignKey(Resident) + category = models.ForeignKey(AgencyServiceCategory) + status = models.CharField(choices=STATUS_CHOICES, default='draft') + submitted_at = models.DateTimeField() + accepted_at = models.DateTimeField(null=True) + completed_at = models.DateTimeField(null=True) + handler = models.ForeignKey(User, null=True) + remarks = models.TextField(blank=True) + +class AgencyDocument(models.Model): + application = models.ForeignKey(AgencyApplication) + doc_type = models.CharField(max_length=50) + file = models.FileField(upload_to='agency_docs/') + uploaded_at = models.DateTimeField(auto_now_add=True) + +class AgencyStatusLog(models.Model): + application = models.ForeignKey(AgencyApplication) + from_status = models.CharField(max_length=20) + to_status = models.CharField(max_length=20) + operator = models.ForeignKey(User) + created_at = models.DateTimeField(auto_now_add=True) + note = models.TextField(blank=True) +``` + +### 3.4 代发代收服务模块 (distribution) + +#### 3.4.1 业务子类 + +| 子类编码 | 业务名称 | 类型 | +|----------|----------|------| +| D01 | 避孕药具发放 | 代发 | +| D02 | 除"四害"药品代售 | 代售 | +| D03 | 爱心捐赠物品代收 | 代收 | + +#### 3.4.2 数据模型 + +```python +class DistributionCategory(models.Model): + code = models.CharField(max_length=10, unique=True) + name = models.CharField(max_length=100) + dist_type = models.CharField(choices=[('issue', '代发'), ('sell', '代售'), ('collect', '代收')]) + +class DistributionRecord(models.Model): + category = models.ForeignKey(DistributionCategory) + resident = models.ForeignKey(Resident) + operator = models.ForeignKey(User) + quantity = models.IntegerField() + unit = models.CharField(max_length=10) + record_date = models.DateField() + remarks = models.TextField(blank=True) + +class DonationItem(models.Model): + donor_name = models.CharField(max_length=50) + donor_phone = models.CharField(max_length=11) + item_name = models.CharField(max_length=100) + item_count = models.IntegerField() + received_at = models.DateTimeField(auto_now_add=True) + receiver = models.ForeignKey(User) + status = models.CharField(choices=[('received', '已接收'), ('distributed', '已发放')]) +``` + +### 3.5 代销代购（法律与心理援助）模块 (legal_psych) + +#### 3.5.1 业务子类 + +| 子类编码 | 业务名称 | +|----------|----------| +| L01 | 法律援助联系 | +| L02 | 民事调解 | +| L03 | 消费者权益维护 | +| L04 | 心理咨询服务 | + +#### 3.5.2 数据模型 + +```python +class LegalPsychService(models.Model): + SERVICE_TYPE_CHOICES = [ + ('legal_aid', '法律援助'), + ('mediation', '民事调解'), + ('consumer_rights', '消费者权益'), + ('psychology', '心理咨询'), + ] + applicant = models.ForeignKey(Resident) + service_type = models.CharField(choices=SERVICE_TYPE_CHOICES) + description = models.TextField() + status = models.CharField(choices=STATUS_CHOICES) + assigned_counselor = models.ForeignKey('Counselor', null=True) + created_at = models.DateTimeField(auto_now_add=True) + closed_at = models.DateTimeField(null=True) + +class Counselor(models.Model): + name = models.CharField(max_length=50) + specialty = models.CharField(max_length=100) + phone = models.CharField(max_length=11) + is_active = models.BooleanField(default=True) +``` + +### 3.6 代开证明模块 (certification) + +#### 3.6.1 业务子类 + +| 子类编码 | 证明类型 | +|----------|----------| +| C01 | 居住证明 | +| C02 | 残疾证明 | +| C03 | 流动人口证明 | +| C04 | 抚恤金申请证明 | +| C05 | 残疾保障金申请证明 | +| C06 | 子女助学金申请证明 | +| C07 | 减免学费证明 | + +#### 3.6.2 数据模型 + +```python +class CertType(models.Model): + code = models.CharField(max_length=10, unique=True) + name = models.CharField(max_length=100) + template = models.FileField(upload_to='cert_templates/') + required_fields = models.JSONField(default=list) + +class CertApplication(models.Model): + applicant = models.ForeignKey(Resident) + cert_type = models.ForeignKey(CertType) + purpose = models.TextField() + status = models.CharField(choices=STATUS_CHOICES) + cert_number = models.CharField(max_length=30, unique=True, null=True) + issued_at = models.DateTimeField(null=True) + issuer = models.ForeignKey(User, null=True) + pdf_file = models.FileField(upload_to='certs/', null=True) +``` + +### 3.7 公益服务模块 (public_service) + +#### 3.7.1 业务子类 + +| 子类编码 | 业务名称 | +|----------|----------| +| P01 | 志愿者登记 | +| P02 | 志愿服务时间储蓄证明 | +| P03 | 志愿者培训及社区服务安排 | +| P04 | 邻里互助组织 | +| P05 | 书画展/合唱队/秧歌队等兴趣小组 | +| P06 | 棋牌/阅览/健身/聚会设施预约 | +| P07 | 轮椅借用 | +| P08 | 市民学校课程 | +| P09 | 医疗保健服务 | +| P10 | 社区单位资源共享 | + +#### 3.7.2 数据模型 + +```python +class Volunteer(models.Model): + resident = models.ForeignKey(Resident) + registered_at = models.DateField() + skills = models.CharField(max_length=200, blank=True) + total_hours = models.FloatField(default=0) + is_active = models.BooleanField(default=True) + +class VolunteerServiceRecord(models.Model): + volunteer = models.ForeignKey(Volunteer) + activity = models.ForeignKey('Activity') + hours = models.FloatField() + date = models.DateField() + verified = models.BooleanField(default=False) + verified_by = models.ForeignKey(User, null=True) + +class Activity(models.Model): + title = models.CharField(max_length=200) + activity_type = models.CharField(choices=ACTIVITY_TYPE_CHOICES) + description = models.TextField() + start_time = models.DateTimeField() + end_time = models.DateTimeField() + location = models.CharField(max_length=200) + max_participants = models.IntegerField(null=True) + current_participants = models.IntegerField(default=0) + status = models.CharField(choices=ACTIVITY_STATUS_CHOICES) + organizer = models.ForeignKey(User) + +class FacilityBooking(models.Model): + facility = models.ForeignKey('Facility') + resident = models.ForeignKey(Resident) + booking_date = models.DateField() + start_time = models.TimeField() + end_time = models.TimeField() + status = models.CharField(choices=[('pending', '待确认'), ('confirmed', '已确认'), ('cancelled', '已取消')]) + +class Facility(models.Model): + name = models.CharField(max_length=100) + facility_type = models.CharField(choices=FACILITY_TYPE_CHOICES) + description = models.TextField(blank=True) + is_available = models.BooleanField(default=True) +``` + +### 3.8 民意反映与政策咨询模块 (feedback) + +#### 3.8.1 业务子类 + +| 子类编码 | 业务名称 | +|----------|----------| +| F01 | 向部门/单位提意见、要求、困难、建议 | +| F02 | 向政府部门咨询政策、办事手续 | + +#### 3.8.2 数据模型 + +```python +class Feedback(models.Model): + FEEDBACK_TYPE_CHOICES = [ + ('opinion', '意见'), + ('demand', '要求'), + ('difficulty', '困难'), + ('suggestion', '建议'), + ('policy_inquiry', '政策咨询'), + ('procedure_inquiry', '办事手续咨询'), + ] + submitter = models.ForeignKey(Resident) + feedback_type = models.CharField(choices=FEEDBACK_TYPE_CHOICES) + title = models.CharField(max_length=200) + content = models.TextField() + target_department = models.CharField(max_length=100, blank=True) + status = models.CharField(choices=[ + ('submitted', '已提交'), + ('forwarded', '已转交'), + ('replied', '已回复'), + ('closed', '已关闭'), + ]) + reply = models.TextField(blank=True) + replier = models.ForeignKey(User, null=True) + created_at = models.DateTimeField(auto_now_add=True) + replied_at = models.DateTimeField(null=True) +``` + +### 3.9 社区治理模块 (governance) + +#### 3.9.1 核心功能 + +- 社区治理目标管理（文明向上、健康安全、生活便利、环境整洁、民主自治） +- "一窗式"服务窗口管理 +- 公共服务/公益服务/便民服务整合调度 +- 居民自治事务管理 + +#### 3.9.2 数据模型 + +```python +class GovernanceGoal(models.Model): + title = models.CharField(max_length=200) + category = models.CharField(choices=[ + ('civilized', '文明向上'), + ('healthy', '健康安全'), + ('convenient', '生活便利'), + ('clean', '环境整洁'), + ('democratic', '民主自治'), + ]) + description = models.TextField() + target_date = models.DateField() + responsible_person = models.ForeignKey(User) + progress = models.IntegerField(default=0) + status = models.CharField(choices=[('in_progress', '进行中'), ('completed', '已完成')]) + +class OneWindowService(models.Model): + window_number = models.CharField(max_length=10) + staff = models.ForeignKey(User) + service_categories = models.ManyToManyField(AgencyServiceCategory) + is_active = models.BooleanField(default=True) + +class ServiceIntegration(models.Model): + service_type = models.CharField(choices=[ + ('public', '公共服务'), + ('welfare', '公益服务'), + ('convenience', '便民服务'), + ]) + name = models.CharField(max_length=200) + provider = models.CharField(max_length=100) + contact = models.CharField(max_length=11) + description = models.TextField() +``` + +### 3.10 通知消息模块 (notification) + +#### 3.10.1 核心功能 + +- 站内消息推送 +- 微信模板消息通知 +- 短信通知（对接短信网关） +- 公告管理 + +#### 3.10.2 数据模型 + +```python +class Notification(models.Model): + recipient = models.ForeignKey(User) + title = models.CharField(max_length=200) + content = models.TextField() + notification_type = models.CharField(choices=[ + ('system', '系统通知'), + ('business', '业务通知'), + ('announcement', '公告'), + ]) + is_read = models.BooleanField(default=False) + created_at = models.DateTimeField(auto_now_add=True) + +class Announcement(models.Model): + title = models.CharField(max_length=200) + content = models.TextField() + is_pinned = models.BooleanField(default=False) + published_at = models.DateTimeField() + publisher = models.ForeignKey(User) +``` + +### 3.11 数据统计模块 (statistics) + +#### 3.11.1 核心功能 + +- 业务量统计（按类型、时间段、经办人） +- 居民画像分析（年龄分布、标签分布、家庭结构） +- 办理时效分析（平均办理时长、超时率） +- 满意度统计 +- 数据导出（Excel/PDF） + +#### 3.11.2 实现方式 + +- 使用 Django ORM 聚合查询 + Celery 定时任务预计算 +- 前端 ECharts 可视化 +- 关键指标缓存至 Redis，定时刷新 + +--- + +## 四、数据库设计 + +### 4.1 ER 关系概览 + +``` +Community 1──N User +Community 1──N Resident +Resident 1──N AgencyApplication +Resident 1──N DistributionRecord +Resident 1──N LegalPsychService +Resident 1──N CertApplication +Resident 1──N Feedback +Resident 1──1 Volunteer +Resident N──1 Family +AgencyApplication N──1 AgencyServiceCategory +AgencyApplication 1──N AgencyDocument +AgencyApplication 1──N AgencyStatusLog +Volunteer 1──N VolunteerServiceRecord +Activity 1──N VolunteerServiceRecord +Activity 1──N ActivityRegistration +Facility 1──N FacilityBooking +``` + +### 4.2 公共字段约定 + +所有业务表均包含以下公共字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| created_at | DateTimeField | 创建时间，auto_now_add | +| updated_at | DateTimeField | 更新时间，auto_now | +| created_by | ForeignKey(User) | 创建人 | +| is_deleted | BooleanField | 逻辑删除标记，default=False | + +### 4.3 索引策略 + +- 所有外键字段自动建索引 +- `id_card` 字段建唯一索引 +- `status` + `created_at` 联合索引（用于按状态筛选+排序） +- `resident_id` + `created_at` 联合索引（用于查询某居民的业务记录） + +--- + +## 五、接口设计 + +### 5.1 API 规范 + +- 遵循 RESTful 风格 +- 统一响应格式： + +```json +{ + "code": 200, + "message": "success", + "data": { } +} +``` + +- 分页响应格式： + +```json +{ + "code": 200, + "message": "success", + "data": { + "count": 100, + "next": "/api/v1/agency/applications/?page=2", + "previous": null, + "results": [ ] + } +} +``` + +### 5.2 核心 API 列表 + +| 模块 | 方法 | 路径 | 说明 | +|------|------|------|------| +| 认证 | POST | /api/v1/auth/login/ | 登录 | +| 认证 | POST | /api/v1/auth/wechat/ | 微信授权登录 | +| 认证 | POST | /api/v1/auth/refresh/ | 刷新Token | +| 居民 | GET/POST | /api/v1/residents/ | 居民列表/新增 | +| 居民 | GET/PUT | /api/v1/residents/{id}/ | 居民详情/修改 | +| 代理代办 | GET/POST | /api/v1/agency/applications/ | 申请列表/新增 | +| 代理代办 | GET/PATCH | /api/v1/agency/applications/{id}/ | 申请详情/更新状态 | +| 代理代办 | POST | /api/v1/agency/applications/{id}/accept/ | 受理 | +| 代理代办 | POST | /api/v1/agency/applications/{id}/complete/ | 办结 | +| 代发代收 | GET/POST | /api/v1/distribution/records/ | 发放/收取记录 | +| 法律心理 | GET/POST | /api/v1/legal-psych/services/ | 服务申请列表/新增 | +| 代开证明 | GET/POST | /api/v1/cert/applications/ | 证明申请列表/新增 | +| 代开证明 | POST | /api/v1/cert/applications/{id}/issue/ | 开具证明 | +| 公益服务 | GET/POST | /api/v1/public/activities/ | 活动列表/发布 | +| 公益服务 | POST | /api/v1/public/activities/{id}/register/ | 活动报名 | +| 公益服务 | GET/POST | /api/v1/public/facilities/bookings/ | 设施预约 | +| 民意反映 | GET/POST | /api/v1/feedback/ | 意见/咨询列表/提交 | +| 民意反映 | POST | /api/v1/feedback/{id}/reply/ | 回复 | +| 统计 | GET | /api/v1/statistics/overview/ | 总览数据 | +| 统计 | GET | /api/v1/statistics/agency/ | 代理代办统计 | +| 统计 | GET | /api/v1/statistics/resident-profile/ | 居民画像 | +| 通知 | GET | /api/v1/notifications/ | 通知列表 | +| 公告 | GET | /api/v1/announcements/ | 公告列表 | + +### 5.3 认证与权限 + +- 管理后台：JWT Token 认证（Access Token 2h + Refresh Token 7d） +- 小程序端：微信 OpenID 关联 + JWT Token +- 权限控制：基于 Django Guardian 的对象级权限 +- API 限流：DRF Throttling（匿名 100次/h，认证 1000次/h） + +--- + +## 六、非功能性需求 + +### 6.1 性能要求 + +| 指标 | 目标值 | +|------|--------| +| API 平均响应时间 | < 200ms | +| 并发用户数 | ≥ 200 | +| 数据库查询 | 单次 < 50ms | +| 文件上传 | 支持 ≤ 20MB | + +### 6.2 安全要求 + +| 项目 | 措施 | +|------|------| +| 传输安全 | 全站 HTTPS | +| 认证安全 | JWT + 黑名单机制 | +| 数据安全 | 敏感字段加密存储（身份证号等） | +| SQL 注入 | ORM 参数化查询 | +| XSS | 模板自动转义 + CSP 头 | +| CSRF | Django 内置 CSRF 中间件 | +| 日志审计 | 关键操作全量记录 | +| 备份策略 | 每日全量备份 + 实时 WAL 归档 | + +### 6.3 可用性要求 + +| 指标 | 目标值 | +|------|--------| +| 系统可用率 | ≥ 99.5% | +| 故障恢复时间 | < 2h | +| 数据恢复点 | < 1h | + +--- + +## 七、部署架构 + +### 7.1 初期部署方案（单机 Docker Compose） + +```yaml +# docker-compose.yml 概要 +services: + web: + build: . + command: gunicorn config.wsgi:application --bind 0.0.0.0:8000 + volumes: + - ./media:/app/media + depends_on: + - db + - redis + environment: + - DATABASE_URL=postgres://... + - REDIS_URL=redis://... + + celery-worker: + build: . + command: celery -A config worker -l info + depends_on: + - db + - redis + + celery-beat: + build: . + command: celery -A config beat -l info + depends_on: + - redis + + db: + image: postgres:15 + volumes: + - pgdata:/var/lib/postgresql/data + + redis: + image: redis:7-alpine + + nginx: + image: nginx:alpine + ports: + - "80:80" + - "443:443" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf + - ./static:/app/static + - ./media:/app/media + +volumes: + pgdata: +``` + +### 7.2 后期扩展方案 + +- 应用层：Docker Swarm / K8s 水平扩展 +- 数据库：读写分离 + 连接池 (PgBouncer) +- 缓存：Redis Sentinel 高可用 +- 文件存储：迁移至阿里云 OSS +- 监控：Prometheus + Grafana +- 日志：ELK Stack + +--- + +## 八、开发计划 + +### 8.1 阶段划分 + +| 阶段 | 内容 | 交付物 | +|------|------|--------| +| 第一阶段 | 基础框架搭建 + 用户权限 + 居民管理 | 可运行的基础系统 | +| 第二阶段 | 代理代办 + 代开证明（核心业务） | 核心业务可用 | +| 第三阶段 | 代发代收 + 法律心理 + 公益服务 | 业务全覆盖 | +| 第四阶段 | 民意反映 + 社区治理 + 通知消息 | 功能完善 | +| 第五阶段 | 数据统计 + 小程序端 | 全功能交付 | +| 第六阶段 | 测试优化 + 部署上线 | 生产环境运行 | + +### 8.2 技术债务管理 + +- 每个阶段结束进行代码审查 +- 核心模块单元测试覆盖率 ≥ 80% +- API 集成测试覆盖核心流程 +- 性能测试在第五阶段完成后执行 + +--- + +## 九、风险与应对 + +| 风险 | 影响 | 概率 | 应对措施 | +|------|------|------|----------| +| 居民隐私数据泄露 | 高 | 低 | 加密存储、权限最小化、审计日志 | +| 业务流程变更频繁 | 中 | 高 | 状态机可配置化、模板化证明 | +| 并发量超预期 | 中 | 低 | Redis 缓存、数据库连接池、限流 | +| 微信接口变动 | 低 | 中 | 抽象微信服务层、接口版本化 | +| 第三方短信服务不可用 | 低 | 低 | 多供应商备选、消息队列缓冲 | + +--- + +## 十、术语表 + +| 术语 | 说明 | +|------|------| +| 一窗式服务 | 居民到一个窗口即可办理所有业务的服务模式 | +| 居民标签 | 对居民分类标记，如低保户、残疾人、独居老人等 | +| 时间储蓄 | 志愿者服务时长记录，可用于兑换社区服务 | +| WAL | Write-Ahead Logging，PostgreSQL 事务日志 | +| DRF | Django REST Framework | +| ADR | Architecture Decision Record，架构决策记录 | + +--- + +*文档版本：v1.0* +*编写日期：2026年5月18日*