From 627eb8a37a0484f5e29734b7bbf55c4d02341c02 Mon Sep 17 00:00:00 2001 From: NoahLan <6995syu@163.com> Date: Thu, 4 Jun 2026 15:08:26 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=85=BC=E5=AE=B9windows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex/skills/iti-flask-framework/SKILL.md | 4 ++++ README.md | 9 ++++++++ copier-template/README.md.jinja | 20 +++++----------- docs/CONFIGURATION.md | 4 ++-- docs/COPIER_TEMPLATE.md | 7 +++--- docs/SEEDS.md | 2 +- docs/TESTING_DEPLOYMENT.md | 27 ++++++++++++++-------- 7 files changed, 44 insertions(+), 29 deletions(-) diff --git a/.codex/skills/iti-flask-framework/SKILL.md b/.codex/skills/iti-flask-framework/SKILL.md index c07a540..f8f2b93 100644 --- a/.codex/skills/iti-flask-framework/SKILL.md +++ b/.codex/skills/iti-flask-framework/SKILL.md @@ -58,6 +58,9 @@ iTi-Flask 是 FastAPI 后端框架基座。 - `copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md.jinja` - 需要保持一致的已生成项目 skill 副本 - 生成项目必须保留 `.copier-answers.yml`，否则不能用 `copier update` 同步模板。 +- `iticli` 是独立工具，安装命令用 `uv tool install git+https://git.noahlan.cn/iti-framework/iti-flask-cli.git`。 +- Windows 安装 `iticli` 后需要运行 `uv tool update-shell` 并重新打开终端。 +- `iticli init` 和 `iticli docker ...` 会在 `.env` 不存在时从 `.env.example` 创建。 - 已生成项目同步框架依赖用 `iticli update framework`。 - 已生成项目检查和同步模板用 `iticli template check`、`iticli template update`。 - 模板项目的 Alembic 命令必须显式使用 `-c migrations/alembic.ini`。 @@ -65,6 +68,7 @@ iTi-Flask 是 FastAPI 后端框架基座。 ## 命令 +- 安装 CLI：`uv tool install git+https://git.noahlan.cn/iti-framework/iti-flask-cli.git` - 安装框架开发依赖：`iticli install` - 运行框架测试：`iticli test` - 启动最小应用：`iticli run dev 8000` diff --git a/README.md b/README.md index 0bd76fc..0ba1f29 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,15 @@ AI 修改框架代码或文档时优先读： ## 安装 +安装 `iticli`： + +```bash +uv tool install git+https://git.noahlan.cn/iti-framework/iti-flask-cli.git +uv tool update-shell +``` + +Windows 安装后重新打开终端。 + 框架本地开发： ```bash diff --git a/copier-template/README.md.jinja b/copier-template/README.md.jinja index 48bf195..2558f18 100644 --- a/copier-template/README.md.jinja +++ b/copier-template/README.md.jinja @@ -21,15 +21,10 @@ AI 修改本项目时优先读： ## 初始化 ```bash -cp .env.example .env iticli init ``` -Windows： - -```bat -iticli init -``` +`iticli init` 会在 `.env` 不存在时从 `.env.example` 创建。 {% if include_system %} 同步系统 migration 和 seed： @@ -38,11 +33,6 @@ iticli init iticli init system ``` -Windows： - -```bat -iticli init system -``` {% endif %} ## 开发 @@ -52,23 +42,25 @@ iticli run dev iticli test ``` -不同环境直接在命令前设 `APP_ENV`，或把环境名作为 `run` 的第一个参数： +不同环境把环境名作为 `run` 的第一个参数。 +迁移命令使用 `--env` 指定环境： ```bash iticli run dev iticli run test 8000 -APP_ENV=prod iticli migrate +iticli migrate --env prod ``` ## Docker ```bash -cp .env.example .env iticli docker up iticli docker logs iticli docker down ``` +`iticli docker ...` 会在 `.env` 不存在时从 `.env.example` 创建。 + {% if database_dialect == "postgresql" %} `docker-compose.yml` 默认只启动应用，数据库使用外部 PostgreSQL。 需要本地 PostgreSQL 时使用： diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index deb7b1d..d949d61 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -6,8 +6,8 @@ ## 环境选择 ```bash -APP_ENV=dev uv run uvicorn main:app --reload -APP_ENV=prod uv run uvicorn main:app +iticli run dev +iticli run prod ``` 也可以显式传入： diff --git a/docs/COPIER_TEMPLATE.md b/docs/COPIER_TEMPLATE.md index 3d93df8..e298b5a 100644 --- a/docs/COPIER_TEMPLATE.md +++ b/docs/COPIER_TEMPLATE.md @@ -26,11 +26,12 @@ copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-pro iticli create ../my-business-app iticli create --database postgresql ../my-postgres-app cd ../my-business-app -cp .env.example .env iticli init iticli run dev 8000 ``` +`iticli init` 会在 `.env` 不存在时从 `.env.example` 创建。 + Windows： ```bat @@ -132,7 +133,7 @@ iticli update framework iticli template check ``` -该命令执行 `uvx copier update --defaults --pretend --vcs-ref HEAD`。 +该命令执行 `uv tool run copier update --defaults --pretend --vcs-ref HEAD`。 业务项目按模板更新项目骨架： @@ -140,7 +141,7 @@ iticli template check iticli template update ``` -该命令执行 `uvx copier update --defaults --vcs-ref HEAD`。 +该命令执行 `uv tool run copier update --defaults --vcs-ref HEAD`。 它依赖 `.copier-answers.yml` 里的 `_src_path` 和 `_commit`。 模板更新前，业务项目工作区必须干净。 执行后检查 diff，再运行测试。 diff --git a/docs/SEEDS.md b/docs/SEEDS.md index 085bebc..ec27de6 100644 --- a/docs/SEEDS.md +++ b/docs/SEEDS.md @@ -16,7 +16,7 @@ 系统包提供： ```bash -PYTHONPATH=. uv run iti-system seed system app:create_app +iticli init system ``` 它会写入默认角色、管理员、系统菜单、字典和配置。 diff --git a/docs/TESTING_DEPLOYMENT.md b/docs/TESTING_DEPLOYMENT.md index faabaae..bdc5f69 100644 --- a/docs/TESTING_DEPLOYMENT.md +++ b/docs/TESTING_DEPLOYMENT.md @@ -30,11 +30,14 @@ CREATE DATABASE my_business_app_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unico 执行： ```bash -export DATABASE_URL='mysql+pymysql://root:password@127.0.0.1:3306/iti_test?charset=utf8mb4' -uv run python -m alembic upgrade head -uv run iti-system migrations sync --target migrations/versions -PYTHONPATH=. uv run iti-system seed system app:create_app -uv run uvicorn main:app --reload +DATABASE_URL=mysql+pymysql://root:password@127.0.0.1:3306/iti_test?charset=utf8mb4 +``` + +把连接串写入业务项目 `.env.local` 后执行： + +```bash +iticli init system +iticli run dev ``` ## PostgreSQL 集成验证 @@ -49,9 +52,14 @@ CREATE DATABASE my_business_app_test; 执行： ```bash -export DATABASE_URL='postgresql+psycopg://postgres:password@127.0.0.1:5432/iti_test' -uv run python -m alembic upgrade head -uv run uvicorn main:app --reload +DATABASE_URL=postgresql+psycopg://postgres:password@127.0.0.1:5432/iti_test +``` + +把连接串写入业务项目 `.env.local` 后执行： + +```bash +iticli migrate +iticli run dev ``` 验证： @@ -68,12 +76,13 @@ curl http://127.0.0.1:8000/ready 模板生成项目已经包含 Docker Compose： ```bash -cp .env.example .env iticli docker up iticli docker logs iticli docker down ``` +`iticli docker ...` 会在 `.env` 不存在时从 `.env.example` 创建。 + 如需本地数据库： ```bash