|
|
# iTi-Flask
|
|
|
|
|
|
iTi-Flask 是 FastAPI 后端框架基座。
|
|
|
|
|
|
AI 修改框架代码或文档时优先读：
|
|
|
|
|
|
```text
|
|
|
.codex/skills/iti-flask-framework/SKILL.md
|
|
|
```
|
|
|
|
|
|
它提供业务项目常用的通用能力：
|
|
|
|
|
|
- FastAPI 应用工厂。
|
|
|
- dataclass 配置和 `.env` 加载。
|
|
|
- MySQL 默认数据库配置。
|
|
|
- SQLAlchemy 2 和 Alembic。
|
|
|
- JWT、权限依赖、错误处理、响应包装。
|
|
|
- 用户 token / 服务 token 的统一 Actor 依赖。
|
|
|
- 缓存、限流、事件总线。
|
|
|
- 模块注册、权限元数据、菜单 seed 元数据。
|
|
|
- 同步 HTTP 服务客户端。
|
|
|
- 运行日志和审计事件 sender。
|
|
|
- 单机轻量任务 runner。
|
|
|
- `/health` 和 `/ready` 健康检查。
|
|
|
- Copier 业务项目模板。
|
|
|
|
|
|
系统业务不在框架内。
|
|
|
需要用户、角色、菜单、字典、文件、日志等能力时，业务项目额外注册 `iti-system`。
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
框架本地开发：
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh install
|
|
|
```
|
|
|
|
|
|
Windows：
|
|
|
|
|
|
```bat
|
|
|
scripts\iti.cmd install
|
|
|
```
|
|
|
|
|
|
业务项目依赖：
|
|
|
|
|
|
```toml
|
|
|
dependencies = [
|
|
|
"iti-flask @ git+ssh://git@your-git/iTi/iTi-Flask.git@v0.2.0",
|
|
|
]
|
|
|
```
|
|
|
|
|
|
## 应用工厂
|
|
|
|
|
|
```python
|
|
|
from iti import create_app
|
|
|
|
|
|
from config import config
|
|
|
from my_app.modules.example import ExampleModule
|
|
|
|
|
|
app = create_app(
|
|
|
config_mapping=config,
|
|
|
modules=[ExampleModule()],
|
|
|
)
|
|
|
```
|
|
|
|
|
|
运行：
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh serve 8000
|
|
|
```
|
|
|
|
|
|
该命令会启动框架最小应用，可用于验证 `/health`、`/ready`。
|
|
|
|
|
|
## 业务项目生成
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh make-app ../my-business-app my_business_app
|
|
|
cd ../my-business-app
|
|
|
./app.sh init
|
|
|
./app.sh serve 8000
|
|
|
```
|
|
|
|
|
|
同步框架依赖和模板骨架：
|
|
|
|
|
|
```bash
|
|
|
./app.sh framework-sync
|
|
|
./app.sh template-check
|
|
|
./app.sh template-update
|
|
|
```
|
|
|
|
|
|
带 `iti-system`：
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh make-system-app ../my-system-app my_system_app
|
|
|
cd ../my-system-app
|
|
|
./app.sh init-system
|
|
|
```
|
|
|
|
|
|
所有脚本都带中文 help：
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh help
|
|
|
./app.sh help
|
|
|
```
|
|
|
|
|
|
发布框架：
|
|
|
|
|
|
```bash
|
|
|
./scripts/iti.sh release
|
|
|
./scripts/iti.sh release v0.2.1
|
|
|
```
|
|
|
|
|
|
## 文档
|
|
|
|
|
|
- [文档索引](docs/README.md)
|
|
|
- [架构](docs/ARCHITECTURE.md)
|
|
|
- [配置](docs/CONFIGURATION.md)
|
|
|
- [模块协议](docs/MODULES.md)
|
|
|
- [模板与导入导出](docs/EXCHANGE.md)
|
|
|
- [服务客户端](docs/SERVICE_CLIENT.md)
|
|
|
- [任务运行器](docs/TASKS.md)
|
|
|
- [数据库迁移](docs/MIGRATIONS.md)
|
|
|
- [种子数据](docs/SEEDS.md)
|
|
|
- [Copier 模板](docs/COPIER_TEMPLATE.md)
|
|
|
- [前端管理端接口契约](docs/FRONTEND_ADMIN_API_CONTRACT.md)
|
|
|
- [测试与部署方案](docs/TESTING_DEPLOYMENT.md)
|