# DEV_VISION

**Repository Path**: re-explor/dev_-vision

## Basic Information

- **Project Name**: DEV_VISION
- **Description**: 中医适宜技术防控青少年近视数据统计分析系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-16
- **Last Updated**: 2025-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DEV_VISION 项目简介

## 项目定位
DEV_VISION 是一套基于 Python+Flask+SQLAlchemy 的学生视力健康管理系统，采用全局唯一配置驱动架构，支持动态表单、智能查询、统计分析、日志追踪等核心功能，适配大规模业务场景。

**最新开发状态**: 微信小程序认证系统开发完成（2025-08-04）
- ✅ 后端系统：五大核心模块100%配置驱动，认证/权限/管理模块完整
- ✅ 微信小程序：登录注册功能完整实现，API接口正常工作
- 🔄 当前进行：学生绑定功能开发准备中

## 目录结构说明
- backend/      # 后端API、模型、服务、配置等
- frontend/     # 前端静态资源、模板、组件
- docs/         # 技术文档、需求规范、开发标准
- tests/        # 自动化、集成、回归、验证测试
  - temp/       # 临时测试文件目录（不受版本控制）
- scripts/      # 辅助脚本
- config/       # 配置子目录
- migrations/   # 数据库迁移
- ...           # 详见 docs/A-代码文件目录与功能说明.md

## 📁 文件管理和开发规范 (2025-08-30更新)

### 🔧 临时文件管理策略

**1. 临时文件分类和存放位置**：
- **测试临时文件**: 存放在 `tests/temp/` 目录
- **调试文件**: 以 `debug_*` 开头，存放在项目根目录或相关模块目录
- **临时测试脚本**: 以 `test_*_temp.*` 命名，存放在 `tests/temp/` 目录
- **备份文件**: 统一使用 `.backup` 或 `.bak` 后缀

**2. 命名规范**：
```
临时测试文件：test_[功能名]_[类型].[扩展名]
调试文件：debug_[功能名].[扩展名]  
备份文件：[原文件名].backup 或 [原文件名].bak
临时HTML文件：test_[功能名].html
```

**3. 生命周期管理**：
- **创建阶段**: 所有临时文件必须放在指定目录
- **使用阶段**: 及时清理不需要的临时文件
- **测试完成**: 自动/手动清理 `tests/temp/` 目录
- **提交前**: 检查确保没有临时文件被意外添加到git

**4. Git版本控制策略**：
```gitignore
# 临时文件和备份文件
*.backup
*.bak
*~
.swp

# 测试相关临时文件  
test_*.html
token_test.*
*_test_temp.*
debug*.*

# 测试临时目录
tests/temp/
```

### 🧪 测试文件管理规范

**1. 正式测试文件** (受版本控制):
- **位置**: `tests/` 目录根级
- **配置**: `conftest.py`, `pytest.ini`
- **覆盖**: API测试、集成测试、单元测试
- **命名**: `test_[模块名].py`

**2. 临时测试文件** (不受版本控制):
- **位置**: `tests/temp/` 目录
- **用途**: 快速验证、调试测试、临时脚本
- **清理**: 定期自动清理
- **命名**: `test_[功能名]_temp.[扩展名]`

**3. 测试环境隔离**：
- 使用独立的测试数据库 (`test.db`)
- pytest fixture确保测试间隔离
- 临时文件不影响正式测试运行

### 📋 开发流程中的文件管理

**1. 开发新功能时**：
```bash
# 1. 创建临时测试文件
echo "测试内容" > tests/temp/test_new_feature_temp.html

# 2. 运行测试
pytest tests/test_related_module.py

# 3. 清理临时文件
rm tests/temp/test_new_feature_temp.html
```

**2. 调试问题时**：
```bash
# 1. 创建调试脚本
python debug_issue_name.py

# 2. 问题解决后清理
rm debug_issue_name.py
```

**3. 提交代码前检查**：
```bash
# 检查是否有临时文件被意外跟踪
git status | grep -E "(backup|temp|debug)"

# 清理临时文件目录
rm -rf tests/temp/*
```

### 🔄 定期维护任务

**每周维护**：
- 清理 `tests/temp/` 目录
- 检查项目中是否有遗留的备份文件
- 验证 .gitignore 规则是否有效

**每月维护**：
- 检查git历史是否有临时文件被意外跟踪
- 更新文件管理规范（如有必要）
- 团队培训文件管理最佳实践

**紧急清理**：
```bash
# 清理所有备份文件
find . -name "*.backup" -delete
find . -name "*.bak" -delete

# 清理临时测试文件
rm -rf tests/temp/*

# 清理调试文件
find . -name "debug_*" -delete
```

## 数据库迁移与状态自检
提供两个常驻脚本确保迁移链路健康：

1. scripts/check_migration_status.py
  - 输出当前数据库 URI
  - 显示 alembic_version 当前 revision
  - 列出 migrations/versions 目录全部脚本（判断是否缺文件）
  - 检查关键字段 users.birth_date / users.address 是否已存在
  - 给出是否需要执行 `flask db upgrade` 的结论
  - 用途：本地开发自检 / CI 部署前健康检查

2. scripts/fix_alembic_version.py <target_revision>
  - 手动修复 alembic_version 表（当误删/损坏迁移文件导致链断时）
  - 仅修改 version_num，不执行自动升级；后续再自行运行 `flask db upgrade`
  - 仅在确认数据库为测试或已备份后使用

示例：
```
python scripts/check_migration_status.py
python scripts/fix_alembic_version.py ec078df35d89
flask db upgrade
```

## 用户资料可编辑字段动态配置 API
新增接口：GET /api/config/user_profile_editable_fields
- 数据来源：全局配置 constants_v2.CONFIG_REGISTRY['USER_PROFILE_EDITABLE_FIELDS']
- 作用：前端（含微信小程序）动态渲染用户资料编辑表单，避免硬编码字段列表
- 返回字段自动附带 options_source 对应的选项数组（如 gender_options）

前端可缓存一分钟左右，减少请求次数；当后台追加字段时无需前端发布。

## 🚀 环境配置和启动方式

### 📦 **依赖管理**
```powershell
# 开发环境 - 标准安装
pip install -r requirements.txt

# 生产服务器 - 分步安装（推荐）
pip install --upgrade pip
pip install cryptography --upgrade  # 预先安装易冲突包
pip install -r requirements_server.txt

# 依赖诊断工具
python scripts/dependency_manager.py
```

### 🔧 **开发环境启动**
```powershell
# 1. 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 2. 安装/更新依赖
pip install -r requirements.txt

# 3. 启动开发服务器
.\run.ps1
# 或手动启动：python app_dev.py
```

### 🏭 **生产环境部署**
```powershell
# 完整部署指南请参考：PRODUCTION_DEPLOY_GUIDE.md

# 快速启动
cd C:\VISION_HEALTH
git pull origin main
& ".venv\Scripts\Activate.ps1"
.\run_production_en.ps1
```

## 启动方式
- **开发环境**：
  1. 配置 .env、flaskenv 等环境变量
  2. 激活虚拟环境：`.\.venv\Scripts\Activate.ps1`
  3. 安装依赖：`pip install -r requirements.txt`
  4. 启动后端：`.\run.ps1` (推荐) 或 `python app_dev.py` (调试模式，端口5000)
  5. 启动微信小程序：使用微信开发者工具打开miniprogram目录
- **生产环境**：
  1. 详细部署请参考 `PRODUCTION_DEPLOY_GUIDE.md`
  2. 快速启动：`.\run_production_en.ps1`
  3. 后端生产入口：`app.py` (通过waitress服务器)

## 🚨 开发者快速指南

### 虚拟环境激活 (每次开发前必须执行)
```bash
# PowerShell中执行
.\.venv\Scripts\Activate.ps1
# 确认终端显示 (.venv) 前缀
```

### 标准导入模板使用
```python
# 所有测试、检查、修复脚本统一使用
from standard_imports_template import *

# 数据库操作标准模式
with get_app_context():
    # 在此处编写所有数据库操作
    users = db.session.query(User).all()
```

### 已验证的模型导入路径
```python
# ✅ 正确的导入路径 (已验证)
from backend.models.user import User
from backend.models.role import Role  
from backend.models.permission import Permission
from backend.models.student import Student
from backend.models.intervention import InterventionRecord  # 注意：不是 Intervention
from backend.models.vision import VisionRecord
```

### 常用脚本模板
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from standard_imports_template import *

def main():
    with get_app_context():
        # 您的代码
        print("脚本运行成功")

if __name__ == "__main__":
    main()
```

### 权限相关查询
```python
# 获取用户权限
user_perms = get_user_permissions(user_id)

# 检查权限是否存在  
exists = check_permission_exists('user:write')

# 检查角色是否有权限
has_perm = check_role_has_permission(role_id, permission_id)
```

### 🔧 故障排除

**导入错误**:
- ✅ 使用 `from standard_imports_template import *`
- ✅ 确保虚拟环境已激活

**无输出问题**:
- ✅ PowerShell中Python命令有延迟，需要等待
- ✅ 使用 `python script.py` 而不是 `python -c "..."`

**权限问题**:
- ✅ Admin已有全部90个权限
- ⚠️ 如果遇到403错误，检查权限装饰器是否使用 `permission.code` (不是 `permission.name`)
- ⚠️ 修改代码后必须重启Flask服务

**服务重启**:
```bash
# 修改Python代码后必须重启
Stop-Process -Name "python" -Force
.\run_enhanced.ps1
```

## 微信小程序
- **目录**: `miniprogram/`
- **状态**: 认证系统开发完成
- **功能**: 微信登录、手机号注册登录、个人中心、权限控制
- **API**: `http://localhost:5000/api/miniprogram`
- **文档**: `docs/D-附件14-微信小程序功能需求规范.md`

## 开发规范
- 严格遵守全局唯一配置驱动原则，所有字段、选项、显示名、选项池只在全局唯一配置表定义一次，禁止重复
- 代码、文档、测试同步推进，所有进展以 docs/系统全貌与任务追踪（AI专用）.md 为唯一标准
- 详见 docs/B-业务标准规范.md、docs/C-技术实现规范.md

## 文档体系
- docs/A-代码文件目录与功能说明.md
- docs/B-业务标准规范.md
- docs/C-技术实现规范.md
- docs/D-功能需求手册.md
- docs/系统全貌与任务追踪（AI专用）.md

## 贡献与协作
- 所有开发、测试、文档同步请严格按分工规范执行
- 发现问题请及时在 docs/系统全貌与任务追踪（AI专用）.md 记录