# custody

**Repository Path**: rejey1985/custody

## Basic Information

- **Project Name**: custody
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学生托管与辅导一体化系统

面向 K12 托管 + 课后辅导机构的 SaaS 管理系统，覆盖招生、报名、排课、托管签到、作业打印、周度点评、家校互动、续费、财务统计等全业务闭环。

## 一、业务概览

| 角色 | 主要能力 |
|------|----------|
| 平台管理员 | 多租户管理（机构）、系统字典、全局配置 |
| 机构管理员 | 学校/托管班/员工/课程/排课/打印机/费用/报表 |
| 招生老师 | 学生录入、报名、续费；数据权限：仅本人招生的学生 |
| 托管老师 | 今日名单、人脸/手动签到、作业打印与完成通知、周度点评；数据权限：仅本人任教托管班 |
| 辅导老师 | 课次点名、课堂记录、补课安排 |
| 家长 | 绑定孩子、上传作业、请假、查看点评、接收通知（小程序订阅 / 公众号模板 / SMS） |

### 核心业务流程

1. 托管日流程：从学校接回 → 人脸签到 → 午餐 / 午休 → 送回学校（晚托同理，放学接回后签到、完成作业、通知家长接）
2. 作业闭环：家长上传照片 → 机构批量打印（PDFBox 合并 + IPP 网络打印）→ 学生完成 → 老师标记完成并通知家长
3. 辅导报名规则：**周一~周五每学生最多报 1 门**；周末不限门数但校验时段冲突
4. 续费：**不修改原记录**，生成新的 enrollment，通过 `renew_from_id` 串联历史；支持保留/变更/新增/退课；费用采用三金额模型
5. 费用三金额模型：`expected_amount`（应收）/ `actual_amount`（实收 = 应收 − 优惠）/ `paid_amount`（已付）。欠费 = 实收 − 已付，优惠 = 应收 − 实收
6. 家校互动：每周自动生成点评草稿，老师录入学习态度/作业/出勤评分+文字+照片后发布；家长可评论互动

## 二、技术栈

### 后端
- Java 17 + Spring Boot 3.2 多模块
- Spring Security + JWT（支持账号/密码、小程序 code2session、公众号 OAuth2）
- MyBatis-Plus 3.5 + 多租户拦截器（按 `tenant_id` 自动注入）
- 数据权限：基于 `LoginUser` 角色 + 托管班列表 + 招生人的服务层过滤
- MySQL 8 / Redis 7 / RabbitMQ / MinIO
- 人脸识别：独立 Python `face-service`（InsightFace ArcFace 512d 特征）+ Java 侧 1:N 余弦相似度 + Redis 班级级缓存
- 作业打印：Apache PDFBox 图片转 PDF/合并 + cups4j IPP 直连网络打印机
- 导入：EasyExcel 读取《托管收支表-录入格式.xlsx》

### 前端
- uni-app (Vue 3 + Pinia + Vite)
- 同一代码库编译 H5 / 微信小程序 / 公众号 WebView

## 三、目录结构

```
custody/
├─ db/                     MySQL DDL（按业务模块拆分）
├─ backend/                Spring Boot 多模块
│  ├─ custody-common/      多租户、JWT、统一响应、异常、OSS
│  ├─ custody-auth/        登录（账号/小程序/公众号）
│  ├─ custody-admin/       租户/学校/员工/字典
│  ├─ custody-student/     学生、家长、绑定审核
│  ├─ custody-custody/     托管报名、名单、签到、作业、点评
│  ├─ custody-course/      课程、排班、报名、点名、请假、补课
│  ├─ custody-finance/     费用、续费中心、Excel 导入
│  ├─ custody-print/       打印机、PDF 合并、IPP 打印任务
│  ├─ custody-notify/      通知路由（小程序/公众号/SMS）
│  ├─ custody-face/        特征抽取适配 + 1:N 匹配
│  └─ custody-boot/        启动模块（application.yml）
├─ face-service/           Python FastAPI + InsightFace
├─ frontend/               uni-app 工程
└─ deploy/                 docker-compose、nginx、Dockerfile
```

## 四、快速启动

### 前置条件
- Docker 24+ / Docker Compose v2
- JDK 17（本地开发）
- Node 18+（前端开发）
- Python 3.10+（face-service 本地开发，非必须，容器即可）

### 一键启动（推荐）

```bash
cd deploy
cp .env.example .env   # 按需修改密钥
docker compose up -d
```

初始化：
1. `mysql` 容器首次启动会自动执行 `db/` 下所有 SQL（多租户 + 业务表 + 初始账号）。
2. 访问 `http://<host>` 打开前端；API 通过 `/api/` 代理到 `backend:8080`。
3. MinIO 控制台：`http://<host>:9001`（minio / minio123），需新建 `custody` bucket。
4. RabbitMQ 控制台：`http://<host>:15672`。

### 默认账号

- 平台：`admin / admin123`（`tenantId=1`）

### 本地开发

**后端**：
```bash
cd backend
mvn -DskipTests package
cd custody-boot
mvn spring-boot:run
```

**前端**：
```bash
cd frontend
npm i
npm run dev:h5           # H5
npm run dev:mp-weixin    # 微信小程序（导入 dist/dev/mp-weixin 到微信开发者工具）
```

**face-service**：
```bash
cd face-service
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 7001
```

## 五、数据初始化

### 1. 导入示例 Excel

用管理员登录后调用：
```
POST /api/excel/import  （multipart: file=托管收支表-录入格式.xlsx）
```
自动导入：学生名单、家长联系方式、周一至周日课程表 → 生成课程 / 排班 / 报名。

### 2. 录入学生人脸
```
POST /api/custody/face/enroll  （multipart: file=照片, studentId）
```
调用 face-service 抽取 512d 特征，写入 `student.face_feature`，同时缓存到 Redis。

### 3. 配置打印机
机构管理员后台新增打印机（`ipp_url`，如 `ipp://192.168.1.50:631/printers/BrotherA4`），托管老师在"作业管理"页点击"批量打印今日作业"。

## 六、扩展点

- **通知**：当前 `NotifyService` 记录 `notification_log`，上线前接入微信小程序订阅消息与公众号模板 API、短信网关。
- **微信支付**：`fee_record` 的 `pay_method / pay_trade_no` 预留，可接入微信商户号扫码/JSAPI 支付。
- **AI 周度点评**：在 `WeeklyReviewService.generateDraft` 接入大模型对本周签到/作业数据做总结草稿。
- **统计报表**：`custody-admin` 可扩展收支/出勤/招生看板。

## 七、许可

内部项目模板，按机构实际业务进行裁剪。