zen-scale 禅修量表系统 开发者参与指南

仓库地址：https://gitee.com/justinlee_pb/zen-scale.git

一、项目简介

zen-scale：禅修专用量表采集、数据管理、统计分析工具，面向禅修科研、正念量表填写与数据导出，欢迎开发者、测试人员、科研人员共同参与维护迭代。

二、参与前置准备

1. 安装 Git 工具
2. 拥有 Gitee 账号，联系仓库所有者 justinlee_pb 申请仓库开发权限
3. 准备项目运行所需环境（根据项目技术栈自行配置）

三、开发者完整参与流程

1. 拉取项目到本地

打开终端 / Git Bash，执行克隆命令：

git clone https://gitee.com/justinlee_pb/zen-scale.git
cd zen-scale

2. 保持主分支干净，新建功能分支

严禁直接在 master 分支修改、提交代码 每次开发新功能/修复bug，单独创建分支：

# 先同步远程最新代码
git pull origin master

# 创建并切换分支
# 新增功能：feat-xxx
# 修复bug：fix-xxx
# 优化性能/逻辑：opt-xxx
# 文档、量表更新：doc-xxx
git checkout -b feat-add-ffmq-scale

3. 本地开发完成后提交代码

# 暂存所有变更文件
git add .

# 规范提交备注格式
git commit -m "feat: 新增FFMQ正念五因素量表录入模块"

# 将本地分支推送到远程仓库
git push origin feat-add-ffmq-scale

4. 提交 Pull Request（PR）合并请求

1. 访问仓库主页：https://gitee.com/justinlee_pb/zen-scale
2. 顶部菜单打开「Pull Request」→ 新建PR
3. 源分支：你新建的功能分支；目标分支：master
4. PR描述填写：
   • 修改内容
   • 新增/调整量表名称
   • 自测情况、有无数据库改动
5. 提交等待作者审核，审核通过后合并入主分支

四、普通用户参与（无开发权限）

1. 反馈Bug、提需求

仓库主页 → Issues → 新建Issue 分类填写： 1）Bug反馈：操作步骤、报错信息、系统环境、截图 2）量表新增需求：量表名称、量表维度、计分规则、文献来源 3）功能优化建议：使用场景、预期交互效果

2. 文档补充

若熟悉各类禅修、正念量表，可在Issue上传量表原文、计分标准，由维护者录入系统。

五、仓库所有者初始化上传代码（justinlee_pb自用）

Gitee网页端操作：

1. 右上角 + → 新建仓库
2. 仓库名：zen-scale，简介：禅修量表采集与数据分析系统
3. 不勾选 README、.gitignore、开源协议，创建空仓库

本地已有代码上传命令：

# 进入本地项目文件夹
cd 你的zen-scale本地目录

# 仅首次配置一次Git账号
git config --global user.name "justinlee_pb"
git config --global user.email "你的Gitee绑定邮箱"

git init
git add .
git commit -m "init: zen-scale禅修量表系统初始代码"
git remote add origin https://gitee.com/justinlee_pb/zen-scale.git
git push -u origin master

六、常用开发快捷命令

# 拉取主分支最新代码
git pull origin master

# 查看全部本地分支
git branch

# 切回主分支
git checkout master

# 丢弃本地未提交的全部修改
git checkout .

# 查看提交日志
git log

七、开发规范要求

1. 分支命名统一：feat- / fix- / opt- / doc- 前缀
2. 提交备注统一格式：类型: 修改内容，描述清晰简短
3. 涉及量表、数据库结构改动必须在PR中重点说明
4. 提交前自测页面、表单、计分导出功能，禁止提交无法运行代码
5. 所有代码合并必须走PR审核流程

八、常见问题处理

1. 推送提示权限不足 Gitee个人设置 → 私人令牌，新建令牌，推送弹窗密码填入令牌字符串。

2. 远程已有文件，推送冲突

   git pull origin master --allow-unrelated-histories
   # 手动解决冲突后重新提交推送
   git add .
   git commit -m "merge: 解决远程代码冲突"
   git push

3. 提示远程origin已存在

   git remote remove origin
   git remote add origin https://gitee.com/justinlee_pb/zen-scale.git

九、联系方式

仓库负责人：justinlee_pb 开发权限申请、量表相关疑问、项目沟通，可在仓库Issues留言。