# CRF-Editor

**Repository Path**: peakb_admin/CRF-Editor

## Basic Information

- **Project Name**: CRF-Editor
- **Description**: https://github.com/decade6666/CRF-Editor
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CRF 编辑器

[English](./README.en.md) | **中文**

## 项目介绍

CRF（Case Report Form，病例报告表）编辑器是一个用于临床研究的表单设计和管理工具。系统支持创建、编辑和管理临床研究项目中的各类表单，并能将表单导出为标准的 Word 文档格式。

### 主要功能

- **项目与权限管理**：创建和管理临床研究项目，支持账号密码登录、管理员用户管理、项目隔离与管理员独立工作台
- **访视管理**：定义和管理研究访视流程，支持访视序列和表单关联；支持矩阵式批量编辑访视与表单的关联关系
- **表单设计**：可视化全屏表单设计器，支持多种字段类型（文本、数值、日期、单选、多选等）、字段拖拽排序，并可为表单添加设计备注
- **实时预览与快编**：设计器底部提供实时预览，支持双击预览字段快速编辑标签、颜色、横向显示与默认值等实例属性
- **字段库 / 代码列表 / 单位管理**：统一管理字段定义、选项字典和测量单位，支持复用与标准化
- **导入能力**：支持模板库 `.db` 导入、项目数据库导入 / 整库合并导入，以及 Word `.docx` 导入对比预览与原文截图证据面板
- **导出能力**：支持 Word 导出与数据库导出；Word 导出内置短时频率限制，避免重复触发，并提供预览 / 导出严格表格字段一致性校验脚本
- **项目复制与 Logo**：支持项目深拷贝与运行时 Logo 上传、复制、删除联动处理
- **访视表单预览**：在访视管理面板中直接预览各表单的字段内容布局，并复用 Word 预览行高拖拽体验
- **会话管理**：顶栏显示 JWT 会话剩余时间，临近过期提醒，并支持点击续期
- **AI 与设置**：支持 AI 接口配置、连通性测试、导入导出路径等设置管理
- **全局模糊搜索与暗色模式**：项目、访视、表单、字段、代码列表五个标签页均内置搜索框，并支持亮色 / 暗色主题切换
- **桌面发行**：支持 PyInstaller 打包、本地浏览器自动打开与系统托盘运行

## 技术架构

### 技术栈

**后端**

- **框架**：FastAPI + Uvicorn
- **数据库**：SQLAlchemy ORM + SQLite
- **数据校验**：Pydantic v2
- **配置管理**：PyYAML
- **文档导出**：python-docx
- **测试框架**：pytest + hypothesis

**前端**

- **框架**：Vue 3 + Vite
- **组件库**：Element Plus
- **拖拽排序**：vuedraggable
- **测试框架**：node:test + 轻量属性测试工具（testProperty.js）

### 项目结构

```text
CRF-Editor/
├── config.yaml              # 应用配置文件（可选，位于项目根目录）
├── backend/
│   ├── main.py              # FastAPI 应用入口
│   ├── app_launcher.py      # PyInstaller 桌面入口
│   ├── requirements.txt     # Python 运行依赖
│   ├── requirements-dev.txt # Python 开发 / 测试依赖
│   ├── src/
│   │   ├── models/          # 数据模型层（SQLAlchemy ORM）
│   │   ├── repositories/    # 数据访问层
│   │   ├── services/        # 业务逻辑层（导入 / 导出 / 排序 / 克隆等）
│   │   ├── routers/         # API 路由层（认证、项目、访视、表单、字段等）
│   │   ├── schemas/         # 请求/响应数据结构（Pydantic）
│   │   ├── config.py        # 配置加载与原子更新
│   │   └── database.py      # SQLite 引擎、Session 与轻量迁移
│   └── tests/               # pytest / hypothesis 测试
├── frontend/
│   ├── src/
│   │   ├── components/      # Vue 组件
│   │   ├── composables/     # Vue composables
│   │   ├── styles/          # 全局样式
│   │   └── App.vue          # 根组件
│   ├── tests/               # node:test 前端回归测试
│   ├── package.json         # 前端依赖与脚本
│   ├── vite.config.js       # Vite 配置
│   └── README.md            # 前端模块说明
└── assets/
    └── logos/
        └── README.md        # 静态 Logo 资源说明
```

### AI 协作上下文

- 根级上下文：`.claude/CLAUDE.md`
- 后端模块上下文：`backend/.claude/CLAUDE.md`
- 前端模块上下文：`frontend/.claude/CLAUDE.md`
- 结构化索引：`.claude/index.json`

这些文档面向 AI 辅助开发，记录模块边界、入口、跨栈契约、测试策略与安全部署约束；功能、命令或测试入口变更时应同步更新。

## 安装教程

### 环境要求

- Python 3.10 或更高版本
- Node.js 18 或更高版本（前端开发时需要）
- Windows 系统（Word 导出功能依赖 Windows）

### 安装步骤

1. 克隆仓库

```bash
git clone https://github.com/your-username/CRF-Editor.git
cd CRF-Editor
```

2. 创建虚拟环境

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
```

3. 安装后端依赖

```bash
pip install -r backend/requirements.txt
```

4. 安装前端依赖

```bash
cd frontend
npm install
```

5. （可选）自定义配置

编辑项目根目录下的 `config.yaml`，可配置数据库路径、上传目录、服务端口等：

```yaml
database:
  path: crf_editor.db
storage:
  upload_path: uploads
server:
  host: 0.0.0.0
  port: 8888
auth:
  access_token_expire_minutes: 60
admin:
  username: admin
  bootstrap_password: change-this-before-production
```

公网部署建议优先使用根目录 `.env.example` 中列出的 `CRF_*` 环境变量，尤其是：

- `CRF_ENV=production`
- `CRF_AUTH_SECRET_KEY=<随机长密钥>`
- `CRF_AUTH_ACCESS_TOKEN_EXPIRE_MINUTES=60`
- `CRF_ADMIN_BOOTSTRAP_PASSWORD=<生产环境保留管理员初始密码>`

生产模式下有以下默认安全收敛：

- 必须通过 `CRF_AUTH_SECRET_KEY` 提供密钥，`config.yaml` 中的 secret 不再作为生产兜底
- `/docs`、`/redoc`、`/openapi.json` 默认关闭
- 响应统一附带基础安全头
- 登录与高成本导入接口启用单机内存限流
- 项目 Logo 禁止 SVG/XML，历史危险 Logo 读取也会被拒绝
- `template_path` 必须位于白名单目录内，且文件后缀必须为 `.db`

## 使用说明

### 启动服务

**方式一：生产模式**（先构建前端，再启动后端）

```bash
# 1. 构建前端
cd frontend
npm run build

# 2. 启动后端（后端托管前端静态文件）
cd ../backend
python main.py
```

服务启动后访问 `http://localhost:8888` 打开 Web 界面。

如果设置了 `CRF_ENV=production`：

- 访问 `/docs`、`/redoc`、`/openapi.json` 会返回 404
- 登录接口固定为 `POST /api/auth/login`
- 若不存在可用保留管理员，启动阶段会使用 `CRF_ADMIN_BOOTSTRAP_PASSWORD` 初始化或修复管理员账号；缺失时启动直接失败
- 登录接口与数据库 / Word 导入接口会返回统一 429 JSON：`{"detail":"操作过于频繁，请稍后重试"}`，并附带 `Retry-After`

**方式二：开发模式**（前后端分别启动，热更新）

```bash
# 终端 1：启动后端
cd backend
python main.py

# 终端 2：启动前端开发服务器
cd frontend
npm run dev
```

前端开发服务器启动后访问 `http://localhost:5173`，API 请求自动代理到后端 `http://127.0.0.1:8888`。

开发模式下 API 文档见 `http://localhost:8888/docs`；生产模式默认关闭。

**方式三：桌面打包入口**（适用于 PyInstaller 发行包）

```bash
cd backend
python app_launcher.py
```

桌面入口会在本地启动后端服务、自动打开浏览器，并保持系统托盘图标运行。

### 登录与管理员迁移说明

- 登录统一使用现有 `username` + 密码，请求入口为 `POST /api/auth/login`。
- 旧历史账号若尚未设置密码，development 下会收到迁移提示；production 下统一返回通用未授权。
- 管理员登录后默认进入独立的用户管理工作台，不显示普通项目列表、设计器与 CRF 编辑入口。
- 管理员可在用户管理工作台中为新用户设置初始密码，并为旧账号执行密码重置迁移。

### 基本操作流程

1. **管理员初始化（首次 production 启动）**：确认 `CRF_ADMIN_BOOTSTRAP_PASSWORD` 已配置，并在上线后立即审计保留管理员账号
2. **创建项目**：普通用户在项目管理界面创建新的临床研究项目
3. **定义访视**：添加研究访视节点，设置访视序列
4. **设计表单**：使用表单设计器创建 CRF 表单并维护设计备注
5. **添加字段**：从字段库选择或创建新字段，配置字段属性与实例显示样式
6. **关联表单**：将表单关联到相应的访视节点，并在访视页预览布局
7. **导入数据**：按需要执行模板库导入、项目数据库导入或 Word 导入对比预览
8. **导出结果**：将项目导出为 Word 文档或数据库模板

### Word 文档导出格式

导出的 Word 文档包含以下内容：

- **封面页**：试验名称、版本号、方案编号、中心编号、筛选号等信息
- **目录**：预渲染目录条目，打开即可查看与点击跳转；服务器装有 LibreOffice 时导出即带真实页码，否则在 Word 更新域后刷新页码
- **表单访视分布图**：矩阵表格显示表单与访视的关联关系
- **表单内容**：详细的表单字段定义和控件

## 上线安全注意事项

- 生产环境首次空库启动或发现保留管理员不可用时，系统会使用 `CRF_ADMIN_BOOTSTRAP_PASSWORD` 自动创建 / 修复保留管理员账号；该密码必须在受控环境中提供，且上线后应立即轮换或重置。
- 上线后应立即审计保留管理员账号是否存在、密码是否已完成接管、以及该账号是否仅在受控环境可访问。
- 部署前应轮换仓库中的历史 `auth.secret_key`，并只通过 `CRF_AUTH_SECRET_KEY` 注入新密钥。
- 若升级为多实例部署，当前单机内存限流不再足够，需要替换为共享存储限流方案。

## 测试

### 后端
```bash
cd backend
python -m pytest
```

### 前端
```bash
cd frontend
node --test tests/*.test.js
```

当前仓库中：
- `backend/tests/` 当前包含 39 个 `pytest` 回归文件，并包含部分 `hypothesis` 属性测试
- `frontend/tests/` 当前包含 25 个 `node:test` 源码级回归文件，并引入自研轻量属性测试工具（`testProperty.js`）
- 预览 / 导出严格表格字段一致性可通过 `backend/scripts/compare_word_table_parity.py` 对比浏览器预览 JSON 与导出的 `.docx`

## 参与贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: 添加某个功能'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

本项目采用 PolyForm Strict License 1.0.0 许可证，仅限非商业用途。详见 LICENSE 文件。

## 联系方式

如有问题或建议，请提交 Issue 或 Pull Request。