youngth-guard/README.md

留守儿童心理风险早期感知与干预平台 MVP

家校社联动的留守儿童心理风险早期感知与干预平台，基于 FastAPI + Vue 3 + PostgreSQL 构建的全栈应用，实现低侵入式心理风险感知和轻干预建议。

---

🎯 项目概述

核心价值

• 教师端：及时发现高风险学生，获得个性化关怀建议
• 家长端：了解孩子心理状态，获得沟通指导
• 管理员：掌握区域风险分布，优化资源配置

MVP 边界

• ✅ 目标用户: 小学高年级（4-6年级）留守儿童、教师、家长
• ✅ 核心场景: 校园观察 + 家庭关怀
• ✅ 数据采集: 文本观察记录（不保存音频）
• ✅ 风险分级: 3级（低/中/高）
• ✅ 分析方式: 关键词匹配 + 多因素评分
• ❌ 不涉及: 硬件研发、医学诊断、生物特征采集

代码统计

• 后端: ~1,781 行 Python
• 前端: ~1,001 行 Vue/JavaScript
• 总计: ~2,800 行代码
• 测试通过率: 91.66% (22/24)

---

🏗 项目架构

┌─────────────────────────────────────────────────────────┐
│                       用户层                            │
├──────────────┬──────────────┬──────────────────────────┤
│  教师端(Web)  │  家长端(H5)   │   管理员端(Web)          │
└──────┬───────┴──────┬───────┴──────────┬──────────────┘
       │              │                  │
       └──────────────┴──────────────────┘
                      │
              ┌───────▼───────┐
              │  API Gateway   │
              │   (FastAPI)    │
              └───────┬────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
   ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
   │ 学生管理 │  │ 风险分析 │  │ 干预管理 │
   └────┬────┘  └────┬────┘  └────┬────┘
        │             │             │
        └─────────────┴─────────────┘
                      │
              ┌───────▼────────┐
              │  PostgreSQL     │
              │  (数据持久化)    │
              └────────────────┘

目录结构

youngth-guard/
├── backend-fastapi/              # FastAPI 后端服务
│   ├── app/
│   │   ├── main.py              # 应用入口
│   │   ├── db.py                # 数据库配置
│   │   ├── models.py            # SQLAlchemy 模型
│   │   ├── schemas.py           # Pydantic 数据模型
│   │   ├── crud.py              # 数据库操作
│   │   ├── api.py               # API 路由
│   │   ├── risk_analyzer.py     # 风险分析引擎
│   │   └── seed.py              # 演示数据
│   └── pyproject.toml           # 项目配置
│
├── frontend-vue3-dashboard/      # Vue 3 前端应用
│   ├── src/
│   │   ├── api/                 # API 客户端
│   │   ├── components/          # 通用组件
│   │   │   ├── RiskBadge.vue
│   │   │   └── StudentCard.vue
│   │   ├── router/              # 路由配置
│   │   ├── stores/              # Pinia 状态管理
│   │   │   ├── student.js
│   │   │   └── observation.js
│   │   ├── views/               # 页面组件
│   │   │   ├── teacher/
│   │   │   │   ├── StudentList.vue
│   │   │   │   └── StudentDetail.vue
│   │   │   └── parent/
│   │   │       └── Home.vue
│   │   ├── App.vue
│   │   └── main.js
│   ├── package.json
│   └── tailwind.config.js
│
├── frontend-simple/              # 纯 HTML 演示版本
│   └── index.html               # 单文件应用
│
├── .claude/                      # Claude Code 配置
│   ├── settings.json            # 自动审批配置
│   ├── templates/               # 全局配置模板
│   └── HOW_TO_USE_GLOBALLY.md   # 全局使用指南
│
├── scripts/
│   └── test/
│       └── run-all-tests.sh     # 完整测试套件
│
├── reports/                      # 测试报告目录
│   └── test/
│       └── test-report-*.md     # 自动生成的测试报告
│
├── docs/
│   ├── PLAN.md                  # 执行计划
│   ├── ACCEPTANCE.md            # 验收报告
│   ├── CONFIGURATION.md         # 配置管理指南
│   └── AUTO_APPROVE_GUIDE.md    # 自动审批指南
│
├── docker-compose.yml            # Docker 编排
├── .env.example                  # 环境变量模板
├── CHANGELOG.md                  # 变更日志
└── README.md                     # 项目文档（本文件）

---

🚀 快速开始

前置要求

• Python 3.11+
• Node.js 21+
• Docker & Docker Compose
• PostgreSQL 16 (通过 Docker 提供)

1. 克隆项目

git clone https://github.com/yourusername/youngth-guard.git
cd youngth-guard

2. 配置环境变量

cp .env.example .env
# 根据需要修改配置

3. 启动数据库

docker-compose up -d db

4. 启动后端

cd backend-fastapi

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
pip install -e ".[dev]"

# 运行服务
uvicorn app.main:app --reload --port 8000

访问 API 文档：http://localhost:8000/docs

5. 启动前端

cd frontend-vue3-dashboard

# 安装依赖
npm install

# 启动开发服务器
npm run dev

访问前端应用：http://localhost:5173

6. 初始化演示数据

在前端页面点击"初始化演示数据"按钮，或通过 API：

curl -X POST http://localhost:8000/api/seed

---

📋 核心功能

1. 教师端

学生列表页面

• ✅ 学生卡片展示（姓名、班级、风险等级）
• ✅ 年级筛选
• ✅ 风险等级筛选
• ✅ 风险统计看板（总数、高/中/低风险）
• ✅ 初始化演示数据

学生详情页面

• ✅ 学生基本信息（监护人、联系方式、是否留守）
• ✅ 最新风险评估（风险分数、风险标签、干预建议）
• ✅ 观察记录历史（教师观察、家长观察）
• ✅ 重新分析风险功能

2. 家长端

• ✅ 孩子状态查看（选择孩子、查看风险等级）
• ✅ 风险等级展示（清晰的色彩标识）
• ✅ 关怀建议（个性化建议文本）
• ✅ 最近观察记录（查看最近3条）
• ✅ 温馨提示（心理健康关怀指南）

3. 风险分析引擎

关键词库（15个类别）

• 情绪困扰：焦虑、孤独、沮丧
• 社交问题：被欺负、被孤立、冷暴力
• 身体异常：失眠、食欲不振、头痛
• 行为异常：多动、自伤、打架
• 学习困难：注意力、成绩下降、厌学
• ...等15个维度

多因素评分模型

1. 关键词匹配 (基础分)
   • 每个匹配的关键词加权累积
   • 不同类别有不同权重
2. 历史积累 (+30% max)
   • 短期内多次观察到风险信号
3. 时间加权 (+15% max)
   • 最近一周的观察权重更高

风险等级判定

• 高风险 (≥70): 需要专业干预
• 中风险 (50-69): 需要重点关注
• 低风险 (<50): 继续观察

---

🧪 测试与验证

运行完整测试

./scripts/test/run-all-tests.sh

测试覆盖范围

测试类别	测试项	状态
环境检查	Python/Node/Docker/Git/PostgreSQL	✅ 5/5
数据库连接	容器状态、端口监听、连接正常	✅ 3/3
后端 API	健康检查、学生列表、观察记录、文档	✅ 3/5
前端构建	依赖安装、关键文件完整性	✅ 2/2
配置文件	.env、docker-compose、settings.json	✅ 4/4
代码质量	Python/Vue 代码统计	✅ 2/2
集成测试	数据初始化、学生列表、风险分析	✅ 3/3
总计	24 项测试	✅ 22/24 (91.66%)

查看测试报告

# 查看最新报告
cat reports/test/test-report-*.md | tail -100

# 或在浏览器中查看 Markdown 渲染

---

🛠 技术栈

后端

• FastAPI 0.100+: 现代化 Python Web 框架
• SQLAlchemy 2.0: ORM 框架（使用 Mapped 类型）
• Pydantic v2: 数据验证（使用 ConfigDict）
• Uvicorn: ASGI 服务器
• PostgreSQL 16: 关系数据库
• psycopg: PostgreSQL 驱动

前端

• Vue 3: 渐进式 JavaScript 框架（Composition API）
• Vue Router 4: 官方路由管理器
• Pinia: 状态管理
• Axios: HTTP 客户端
• Tailwind CSS 3: 实用优先的 CSS 框架
• Vite 6: 下一代前端构建工具

DevOps

• Docker & Docker Compose: 容器化部署
• GitHub Actions: CI/CD（已配置但目前改为手动部署）
• 环境变量管理: .env 文件统一配置
• 自动化测试: Bash 脚本 + API 测试

---

⚙️ 配置管理

详见 docs/CONFIGURATION.md

关键配置项

# 数据库配置
POSTGRES_DB=psychology
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5433

# 服务端口
BACKEND_PORT=8000
FRONTEND_PORT=3000

# Docker 端口映射
DB_EXTERNAL_PORT=5433

环境切换

# 开发环境
ENV=development
DEBUG=true
CORS_ORIGINS=*

# 生产环境
ENV=production
DEBUG=false
CORS_ORIGINS=https://yourdomain.com

---

🔄 Claude Code 自动执行

本项目已配置为 Claude Code 2小时不断档自动执行模式，可实现最少审批中断的自动化开发。

核心配置

• 自动审批配置: .claude/settings.json
• 全局模板: .claude/templates/settings-global.json
• 使用指南: .claude/HOW_TO_USE_GLOBALLY.md

在其他项目中使用

# 方法 1: 直接复制
cp .claude/templates/settings-global.json /path/to/new/project/.claude/settings.json

# 方法 2: 创建符号链接
mkdir -p ~/.claude/templates
cp .claude/templates/settings-global.json ~/.claude/templates/
cd /path/to/new/project
mkdir -p .claude
ln -s ~/.claude/templates/settings-global.json .claude/settings.json

详见 .claude/HOW_TO_USE_GLOBALLY.md

---

📊 质量保证

代码规范

• Python: Black + Ruff
• JavaScript: ESLint + Prettier
• Git: Conventional Commits

测试策略

• ✅ 环境检查: 验证所有依赖工具
• ✅ 数据库测试: 连接、数据完整性
• ✅ API 测试: 所有端点验证
• ✅ 集成测试: 端到端业务流程
• ✅ 前端构建: 依赖和文件完整性

质量门槛

• 代码覆盖率: 目标 >80%
• 测试通过率: >90%
• API 响应时间: <200ms
• 前端首屏加载: <2s

---

🚢 部署

Docker Compose 部署

# 构建镜像
docker-compose build

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

手动部署

后端

cd backend-fastapi
pip install -e .
uvicorn app.main:app --host 0.0.0.0 --port 8000

前端

cd frontend-vue3-dashboard
npm install
npm run build
# 将 dist/ 目录部署到 Nginx/Apache

---

📖 文档

• 执行计划 - MVP 实施详细计划
• 验收报告 - 功能验收和测试报告
• 配置管理指南 - 环境变量和配置说明
• 自动审批指南 - Claude Code 自动化配置
• 全局使用指南 - 在其他项目中复用配置
• 变更日志 - 版本更新记录

---

🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

Commit 规范

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具链更改

---

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

---

👥 团队

本项目由 Claude Code 自动执行框架辅助开发，实现了：

• ✅ 2小时不断档自动执行
• ✅ 完整的测试验证机制
• ✅ 可追溯的开发过程
• ✅ 专业的文档和报告

---

📞 联系方式

如有问题或建议，欢迎：

• 提交 Issue
• 发起 Pull Request
• 发送邮件至 [[email protected]]

---

🙏 致谢

感谢以下开源项目：

• FastAPI
• Vue.js
• Tailwind CSS
• PostgreSQL
• Claude Code

---

最后更新: 2025-12-15 项目版本: MVP v1.0