From 5ef6da5b53825f872cf3c5426d0f61ce19dc403d Mon Sep 17 00:00:00 2001
From: NoahLan <6995syu@163.com>
Date: Sun, 10 May 2026 03:24:09 +0800
Subject: [PATCH] chore: add helper scripts for project commands

---
 README.md                             |  34 +++++--
 copier-template/README.md.jinja       |  27 ++++--
 copier-template/scripts/app.cmd.jinja | 127 +++++++++++++++++++++++++
 copier-template/scripts/app.sh.jinja  |  94 +++++++++++++++++++
 docs/COPIER_TEMPLATE.md               |  54 +++++++++--
 docs/README.md                        |  12 ++-
 scripts/iti.cmd                       | 129 ++++++++++++++++++++++++++
 scripts/iti.sh                        | 103 ++++++++++++++++++++
 8 files changed, 554 insertions(+), 26 deletions(-)
 create mode 100644 copier-template/scripts/app.cmd.jinja
 create mode 100644 copier-template/scripts/app.sh.jinja
 create mode 100644 scripts/iti.cmd
 create mode 100644 scripts/iti.sh

diff --git a/README.md b/README.md
index 00afad5..059d292 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,13 @@ iTi-Flask 是 FastAPI 后端框架基座。
 框架本地开发：
 
 ```bash
-uv sync --extra dev
+./scripts/iti.sh install
+```
+
+Windows：
+
+```bat
+scripts\iti.cmd install
 ```
 
 业务项目依赖：
@@ -55,17 +61,33 @@ app = create_app(
 运行：
 
 ```bash
-uv run uvicorn app:app --reload
+./scripts/iti.sh serve 8000
 ```
 
+该命令会启动框架最小应用，可用于验证 `/health`、`/ready`。
+
 ## 业务项目生成
 
 ```bash
-uvx copier copy ./copier-template ../my-business-app
+./scripts/iti.sh make-app ../my-business-app my_business_app
 cd ../my-business-app
-uv sync --extra dev
-uv run alembic upgrade head
-uv run uvicorn app:app --reload
+./scripts/app.sh init
+./scripts/app.sh serve 8000
+```
+
+带 `iti-system`：
+
+```bash
+./scripts/iti.sh make-system-app ../my-system-app my_system_app
+cd ../my-system-app
+./scripts/app.sh init-system
+```
+
+所有脚本都带中文 help：
+
+```bash
+./scripts/iti.sh help
+./scripts/app.sh help
 ```
 
 ## 文档
diff --git a/copier-template/README.md.jinja b/copier-template/README.md.jinja
index 57526bd..ce582ca 100644
--- a/copier-template/README.md.jinja
+++ b/copier-template/README.md.jinja
@@ -12,32 +12,41 @@ FastAPI 业务后端项目。
 ## 初始化
 
 ```bash
-uv sync --extra dev
-uv run alembic upgrade head
+./scripts/app.sh init
+```
+
+Windows：
+
+```bat
+scripts\app.cmd init
 ```
 
 {% if include_system %}
 同步系统 migration 和 seed：
 
 ```bash
-uv run iti-system migrations sync --target migrations/versions
-uv run alembic upgrade head
-uv run iti-system seed system app:app
+./scripts/app.sh init-system
+```
+
+Windows：
+
+```bat
+scripts\app.cmd init-system
 ```
 {% endif %}
 
 ## 开发
 
 ```bash
-uv run uvicorn app:app --reload
-uv run pytest -q
+./scripts/app.sh serve 8000
+./scripts/app.sh test
 ```
 
 ## 数据库迁移
 
 ```bash
-uv run alembic revision --autogenerate -m "alice add example table"
-uv run alembic upgrade head
+./scripts/app.sh migration "alice add example table"
+./scripts/app.sh migrate
 ```
 
 规则：
diff --git a/copier-template/scripts/app.cmd.jinja b/copier-template/scripts/app.cmd.jinja
new file mode 100644
index 0000000..3672807
--- /dev/null
+++ b/copier-template/scripts/app.cmd.jinja
@@ -0,0 +1,127 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "ROOT_DIR=%SCRIPT_DIR%.."
+pushd "%ROOT_DIR%" >nul
+
+set "COMMAND=%~1"
+if "%COMMAND%"=="" set "COMMAND=help"
+shift /1
+
+if "%COMMAND%"=="help" goto help
+if "%COMMAND%"=="-h" goto help
+if "%COMMAND%"=="--help" goto help
+if "%COMMAND%"=="install" goto install
+if "%COMMAND%"=="test" goto test
+if "%COMMAND%"=="serve" goto serve
+if "%COMMAND%"=="migrate" goto migrate
+if "%COMMAND%"=="migration" goto migration
+if "%COMMAND%"=="heads" goto heads
+if "%COMMAND%"=="current" goto current
+{% if include_system %}if "%COMMAND%"=="system-sync" goto system_sync
+if "%COMMAND%"=="system-seed" goto system_seed
+if "%COMMAND%"=="init-system" goto init_system
+{% endif %}if "%COMMAND%"=="init" goto init
+
+echo 未知命令：%COMMAND% 1>&2
+echo. 1>&2
+goto help_error
+
+:help
+echo {{ project_name }} 项目脚本
+echo.
+echo 用法：
+echo   scripts\app.cmd ^<命令^> [参数]
+echo.
+echo 常用命令：
+echo   help                     显示帮助
+echo   install                  安装开发依赖：uv sync --extra dev
+echo   test                     运行测试：uv run pytest -q
+echo   serve [端口]             本地启动，默认 8000
+echo   migrate                  执行 Alembic upgrade head
+echo   migration ^<说明^>         生成 migration，说明建议以作者名开头
+echo   heads                    查看 Alembic heads
+echo   current                  查看当前 Alembic 版本
+{% if include_system %}echo   system-sync              同步 iti-system migration 到当前项目
+echo   system-seed              初始化 / 更新系统 seed
+echo   init-system              system-sync + migrate + system-seed
+{% endif %}echo   init                     install + migrate{% if include_system %} + system-seed{% endif %}
+echo.
+echo 示例：
+echo   scripts\app.cmd install
+echo   scripts\app.cmd serve 8000
+echo   scripts\app.cmd migration "alice add order table"
+{% if include_system %}echo   scripts\app.cmd init-system
+{% endif %}popd >nul
+exit /b 0
+
+:help_error
+call :help
+exit /b 2
+
+:install
+uv sync --extra dev
+goto end
+
+:test
+uv run pytest -q
+goto end
+
+:serve
+set "PORT=%~1"
+if "%PORT%"=="" set "PORT=8000"
+uv run uvicorn app:app --reload --port "%PORT%"
+goto end
+
+:migrate
+uv run alembic upgrade head
+goto end
+
+:migration
+set "MESSAGE=%~1"
+if "%MESSAGE%"=="" (
+  echo 缺少 migration 说明。示例：scripts\app.cmd migration "alice add order table" 1>&2
+  exit /b 2
+)
+uv run alembic revision --autogenerate -m "%MESSAGE%"
+goto end
+
+:heads
+uv run alembic heads
+goto end
+
+:current
+uv run alembic current
+goto end
+
+{% if include_system %}:system_sync
+uv run iti-system migrations sync --target migrations/versions
+goto end
+
+:system_seed
+uv run iti-system seed system app:app
+goto end
+
+:init_system
+uv run iti-system migrations sync --target migrations/versions
+if errorlevel 1 goto end
+uv run alembic upgrade head
+if errorlevel 1 goto end
+uv run iti-system seed system app:app
+goto end
+
+{% endif %}:init
+uv sync --extra dev
+if errorlevel 1 goto end
+{% if include_system %}uv run iti-system migrations sync --target migrations/versions
+if errorlevel 1 goto end
+{% endif %}uv run alembic upgrade head
+if errorlevel 1 goto end
+{% if include_system %}uv run iti-system seed system app:app
+{% endif %}goto end
+
+:end
+set "EXIT_CODE=%ERRORLEVEL%"
+popd >nul
+exit /b %EXIT_CODE%
diff --git a/copier-template/scripts/app.sh.jinja b/copier-template/scripts/app.sh.jinja
new file mode 100644
index 0000000..09211c1
--- /dev/null
+++ b/copier-template/scripts/app.sh.jinja
@@ -0,0 +1,94 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT_DIR"
+
+show_help() {
+  cat <<'EOF'
+{{ project_name }} 项目脚本
+
+用法：
+  ./scripts/app.sh <命令> [参数]
+
+常用命令：
+  help                     显示帮助
+  install                  安装开发依赖：uv sync --extra dev
+  test                     运行测试：uv run pytest -q
+  serve [端口]             本地启动，默认 8000
+  migrate                  执行 Alembic upgrade head
+  migration <说明>         生成 migration，说明建议以作者名开头
+  heads                    查看 Alembic heads
+  current                  查看当前 Alembic 版本
+{% if include_system %}  system-sync              同步 iti-system migration 到当前项目
+  system-seed              初始化 / 更新系统 seed
+  init-system              system-sync + migrate + system-seed
+{% endif %}  init                     install + migrate{% if include_system %} + system-seed{% endif %}
+
+示例：
+  ./scripts/app.sh install
+  ./scripts/app.sh serve 8000
+  ./scripts/app.sh migration "alice add order table"
+{% if include_system %}  ./scripts/app.sh init-system
+{% endif %}
+EOF
+}
+
+command=${1:-help}
+shift || true
+
+case "$command" in
+  help|-h|--help)
+    show_help
+    ;;
+  install)
+    uv sync --extra dev
+    ;;
+  test)
+    uv run pytest -q
+    ;;
+  serve)
+    port=${1:-8000}
+    uv run uvicorn app:app --reload --port "$port"
+    ;;
+  migrate)
+    uv run alembic upgrade head
+    ;;
+  migration)
+    message=${1:-}
+    if [ -z "$message" ]; then
+      echo "缺少 migration 说明。示例：./scripts/app.sh migration \"alice add order table\"" >&2
+      exit 2
+    fi
+    uv run alembic revision --autogenerate -m "$message"
+    ;;
+  heads)
+    uv run alembic heads
+    ;;
+  current)
+    uv run alembic current
+    ;;
+{% if include_system %}  system-sync)
+    uv run iti-system migrations sync --target migrations/versions
+    ;;
+  system-seed)
+    uv run iti-system seed system app:app
+    ;;
+  init-system)
+    uv run iti-system migrations sync --target migrations/versions
+    uv run alembic upgrade head
+    uv run iti-system seed system app:app
+    ;;
+{% endif %}  init)
+    uv sync --extra dev
+{% if include_system %}    uv run iti-system migrations sync --target migrations/versions
+{% endif %}    uv run alembic upgrade head
+{% if include_system %}    uv run iti-system seed system app:app
+{% endif %}    ;;
+  *)
+    echo "未知命令：$command" >&2
+    echo >&2
+    show_help >&2
+    exit 2
+    ;;
+esac
diff --git a/docs/COPIER_TEMPLATE.md b/docs/COPIER_TEMPLATE.md
index b93180c..95b08ec 100644
--- a/docs/COPIER_TEMPLATE.md
+++ b/docs/COPIER_TEMPLATE.md
@@ -6,11 +6,19 @@
 ## 生成
 
 ```bash
-uvx copier copy ./copier-template ../my-business-app
+./scripts/iti.sh make-app ../my-business-app my_business_app
 cd ../my-business-app
-uv sync --extra dev
-uv run alembic upgrade head
-uv run uvicorn app:app --reload
+./scripts/app.sh init
+./scripts/app.sh serve 8000
+```
+
+Windows：
+
+```bat
+scripts\iti.cmd make-app ..\my-business-app my_business_app
+cd ..\my-business-app
+scripts\app.cmd init
+scripts\app.cmd serve 8000
 ```
 
 ## 参数
@@ -37,6 +45,8 @@ uv run uvicorn app:app --reload
 - 示例 FastAPI 模块
 - 示例 SQLAlchemy 模型
 - 示例测试
+- `scripts/app.sh`
+- `scripts/app.cmd`
 
 ## 系统业务
 
@@ -44,7 +54,37 @@ uv run uvicorn app:app --reload
 生成后执行：
 
 ```bash
-uv run iti-system migrations sync --target migrations/versions
-uv run alembic upgrade head
-uv run iti-system seed system app:app
+./scripts/app.sh init-system
+```
+
+Windows：
+
+```bat
+scripts\app.cmd init-system
+```
+
+## 生成项目脚本
+
+模板会生成两份脚本：
+
+- `scripts/app.sh`：Linux / macOS / Git Bash。
+- `scripts/app.cmd`：Windows CMD。
+
+常用命令：
+
+```bash
+./scripts/app.sh help
+./scripts/app.sh install
+./scripts/app.sh test
+./scripts/app.sh serve 8000
+./scripts/app.sh migration "alice add order table"
+./scripts/app.sh migrate
+```
+
+带 `iti-system` 的项目还会有：
+
+```bash
+./scripts/app.sh system-sync
+./scripts/app.sh system-seed
+./scripts/app.sh init-system
 ```
diff --git a/docs/README.md b/docs/README.md
index 59f00e8..ebc95da 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,13 +17,17 @@ iTi-Flask 文档只描述框架自身。
 ## 常用命令
 
 ```bash
-uv sync --extra dev
-uv run --extra dev pytest
-uv run --extra dev mypy
+./scripts/iti.sh help
+./scripts/iti.sh install
+./scripts/iti.sh test
+./scripts/iti.sh check
 ```
 
 生成业务项目：
 
 ```bash
-uvx copier copy ./copier-template ../my-business-app
+./scripts/iti.sh make-app ../my-business-app my_business_app
+./scripts/iti.sh make-system-app ../my-system-app my_system_app
 ```
+
+Windows 使用 `scripts\iti.cmd`。
diff --git a/scripts/iti.cmd b/scripts/iti.cmd
new file mode 100644
index 0000000..2fbffab
--- /dev/null
+++ b/scripts/iti.cmd
@@ -0,0 +1,129 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "ROOT_DIR=%SCRIPT_DIR%.."
+pushd "%ROOT_DIR%" >nul
+
+set "COMMAND=%~1"
+if "%COMMAND%"=="" set "COMMAND=help"
+shift /1
+
+if "%COMMAND%"=="help" goto help
+if "%COMMAND%"=="-h" goto help
+if "%COMMAND%"=="--help" goto help
+if "%COMMAND%"=="install" goto install
+if "%COMMAND%"=="test" goto test
+if "%COMMAND%"=="check" goto check
+if "%COMMAND%"=="serve" goto serve
+if "%COMMAND%"=="migrate" goto migrate
+if "%COMMAND%"=="migration" goto migration
+if "%COMMAND%"=="heads" goto heads
+if "%COMMAND%"=="current" goto current
+if "%COMMAND%"=="make-app" goto make_app
+if "%COMMAND%"=="make-system-app" goto make_system_app
+
+echo 未知命令：%COMMAND% 1>&2
+echo. 1>&2
+goto help_error
+
+:help
+echo iTi-Flask 开发脚本
+echo.
+echo 用法：
+echo   scripts\iti.cmd ^<命令^> [参数]
+echo.
+echo 常用命令：
+echo   help                         显示帮助
+echo   install                      安装开发依赖：uv sync --extra dev
+echo   test                         运行测试：uv run pytest -q
+echo   check                        运行测试和 mypy
+echo   serve [端口]                 启动框架示例应用，默认 8000
+echo   migrate                      执行当前仓库 Alembic upgrade head
+echo   migration ^<说明^>             生成 migration，说明建议以作者名开头
+echo   heads                        查看 Alembic heads
+echo   current                      查看当前 Alembic 版本
+echo   make-app ^<目录^> [包名]        从 copier-template 生成业务项目
+echo   make-system-app ^<目录^> [包名] 生成带 iti-system 的业务项目
+echo.
+echo 示例：
+echo   scripts\iti.cmd install
+echo   scripts\iti.cmd test
+echo   scripts\iti.cmd serve 8000
+echo   scripts\iti.cmd make-app ..\hsyh-erp hsyh_erp
+echo   scripts\iti.cmd make-system-app ..\hsyh-mes-phase2 hsyh_mes_phase2
+popd >nul
+exit /b 0
+
+:help_error
+call :help
+exit /b 2
+
+:install
+uv sync --extra dev
+goto end
+
+:test
+uv run pytest -q
+goto end
+
+:check
+uv run pytest -q
+if errorlevel 1 goto end
+uv run mypy
+goto end
+
+:serve
+set "PORT=%~1"
+if "%PORT%"=="" set "PORT=8000"
+uv run uvicorn iti.app:create_app --factory --reload --port "%PORT%"
+goto end
+
+:migrate
+uv run alembic upgrade head
+goto end
+
+:migration
+set "MESSAGE=%~1"
+if "%MESSAGE%"=="" (
+  echo 缺少 migration 说明。示例：scripts\iti.cmd migration "alice add order table" 1>&2
+  exit /b 2
+)
+uv run alembic revision --autogenerate -m "%MESSAGE%"
+goto end
+
+:heads
+uv run alembic heads
+goto end
+
+:current
+uv run alembic current
+goto end
+
+:make_app
+set "INCLUDE_SYSTEM=false"
+goto make_project
+
+:make_system_app
+set "INCLUDE_SYSTEM=true"
+goto make_project
+
+:make_project
+set "TARGET=%~1"
+set "PACKAGE=%~2"
+if "%TARGET%"=="" (
+  echo 缺少目标目录。示例：scripts\iti.cmd make-app ..\my-app my_app 1>&2
+  exit /b 2
+)
+if "%PACKAGE%"=="" (
+  for %%I in ("%TARGET%") do set "PACKAGE=%%~nxI"
+  set "PACKAGE=!PACKAGE:-=_!"
+)
+for %%I in ("%TARGET%") do set "PROJECT_NAME=%%~nxI"
+uvx copier copy "%CD%\copier-template" "%TARGET%" -d project_name="!PROJECT_NAME!" -d project_slug="!PACKAGE!" -d include_system="%INCLUDE_SYSTEM%"
+goto end
+
+:end
+set "EXIT_CODE=%ERRORLEVEL%"
+popd >nul
+exit /b %EXIT_CODE%
diff --git a/scripts/iti.sh b/scripts/iti.sh
new file mode 100644
index 0000000..edecb44
--- /dev/null
+++ b/scripts/iti.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+cd "$ROOT_DIR"
+
+show_help() {
+  cat <<'EOF'
+iTi-Flask 开发脚本
+
+用法：
+  ./scripts/iti.sh <命令> [参数]
+
+常用命令：
+  help                         显示帮助
+  install                      安装开发依赖：uv sync --extra dev
+  test                         运行测试：uv run pytest -q
+  check                        运行测试和 mypy
+  serve [端口]                 启动框架示例应用，默认 8000
+  migrate                      执行当前仓库 Alembic upgrade head
+  migration <说明>             生成 migration，说明建议以作者名开头
+  heads                        查看 Alembic heads
+  current                      查看当前 Alembic 版本
+  make-app <目录> [包名]        从 copier-template 生成业务项目
+  make-system-app <目录> [包名] 生成带 iti-system 的业务项目
+
+示例：
+  ./scripts/iti.sh install
+  ./scripts/iti.sh test
+  ./scripts/iti.sh serve 8000
+  ./scripts/iti.sh make-app ../hsyh-erp hsyh_erp
+  ./scripts/iti.sh make-system-app ../hsyh-mes-phase2 hsyh_mes_phase2
+
+说明：
+  - 默认生成项目使用 copier-template 里的 Git 依赖配置。
+  - 临时本地验证可在生成时按 copier 交互改成 file://。
+EOF
+}
+
+command=${1:-help}
+shift || true
+
+case "$command" in
+  help|-h|--help)
+    show_help
+    ;;
+  install)
+    uv sync --extra dev
+    ;;
+  test)
+    uv run pytest -q
+    ;;
+  check)
+    uv run pytest -q
+    uv run mypy
+    ;;
+  serve)
+    port=${1:-8000}
+    uv run uvicorn iti.app:create_app --factory --reload --port "$port"
+    ;;
+  migrate)
+    uv run alembic upgrade head
+    ;;
+  migration)
+    message=${1:-}
+    if [ -z "$message" ]; then
+      echo "缺少 migration 说明。示例：./scripts/iti.sh migration \"alice add order table\"" >&2
+      exit 2
+    fi
+    uv run alembic revision --autogenerate -m "$message"
+    ;;
+  heads)
+    uv run alembic heads
+    ;;
+  current)
+    uv run alembic current
+    ;;
+  make-app|make-system-app)
+    target=${1:-}
+    package=${2:-}
+    if [ -z "$target" ]; then
+      echo "缺少目标目录。示例：./scripts/iti.sh make-app ../my-app my_app" >&2
+      exit 2
+    fi
+    if [ -z "$package" ]; then
+      package=$(basename "$target" | tr '-' '_')
+    fi
+    include_system=false
+    if [ "$command" = "make-system-app" ]; then
+      include_system=true
+    fi
+    uvx copier copy "$ROOT_DIR/copier-template" "$target" \
+      -d project_name="$(basename "$target")" \
+      -d project_slug="$package" \
+      -d include_system="$include_system"
+    ;;
+  *)
+    echo "未知命令：$command" >&2
+    echo >&2
+    show_help >&2
+    exit 2
+    ;;
+esac