iTi-Flask/docs/ARCHITECTURE.md

架构

iTi-Flask 是 FastAPI 框架基座。 它约束业务项目的工程方式，但不接管业务代码。

分层

• iti.app：应用工厂，组装 FastAPI、错误处理、模块、服务客户端、任务 runner、健康检查。
• iti.config：dataclass 配置，默认 dev/test/prod 均使用 MySQL。
• iti.db：SQLAlchemy 2 Base、session、Alembic metadata。
• iti.auth：JWT、Principal、Actor、用户权限依赖、服务 token 依赖。
• iti.responses：自动 envelope、@raw_response、响应工具。
• iti.modules：模块协议、权限元数据、菜单 seed 元数据。
• iti.service_client：同步 HTTP JSON 服务客户端。
• iti.tasks：单进程轻量任务注册和调度。
• iti.audit：审计事件、diff、脱敏和异步 HTTP sender，不拥有日志表。
• iti.logging_config：运行日志配置。
• iti.cache、iti.limiter、iti.events：常用通用能力。
• iti.health：/health 和 /ready。

应用创建流程

create_app() 按顺序执行：

1. 解析配置。
2. 创建 FastAPI。
3. 写入 app.state.config/cache/limiter/permission_provider。
4. 配置 SQLAlchemy engine 和 sessionmaker。
5. 注册中间件、错误处理和运行日志。
6. 初始化服务客户端。
7. 初始化任务 runner。
8. 初始化审计 sender。
9. 初始化模块并运行 init_app、register_tasks。
10. 注册健康检查。
11. 注册模块路由、权限元数据和菜单 seed 元数据。
12. 安装自动 envelope。

API 约定

业务 JSON API 默认返回 HTTP 200 envelope：

{"data": {}, "code": 200, "message": "成功"}

业务错误也包装进 envelope：

{"data": null, "code": 403, "message": "权限不足"}

成功时 code 固定为 200。 业务错误、参数错误、框架 HTTP 错误都保留原始业务码，例如 403、404、405、429。 框架默认提供 JSON 错误响应，不提供服务端 HTML 错误页。

服务间 API 也默认使用 envelope。 框架服务客户端会自动识别 envelope 和 HTTP status。 如果响应体是 envelope，则优先按 code 判断业务结果。 框架仍允许 raw 响应：

• @raw_response
• raw_response_paths
• Response / FileResponse / StreamingResponse

默认 raw：

• /health
• /ready
• /docs
• /openapi.json
• /redoc

鉴权

用户接口使用 JWT。 服务间调用使用静态服务 token。

双入口接口使用 require_actor()：

• 用户 token 走权限码。
• 服务 token 只校验可信服务。
• 任一通过即可。

审计

iti-flask 只产生和发送审计事件。 它不写 sys_log。

审计事件通过 service_client 发到配置的 audit_service_name。 当前常见接收方是注册了 iti-system 的主业务项目。

审计发送默认异步、不阻塞业务。 diff 由业务显式提供 before / after 快照。

运行日志

运行日志由框架配置。 默认控制台输出。 生产可开启滚动文件：

• runtime/logs/app.log
• runtime/logs/error.log

请求摘要默认写入 app log。 摘要包含 method、path、HTTP status、业务 code、duration、actor、ip 和 trace id。

系统包边界

iti-system 只承载系统域业务：

• auth。
• user / role / menu / dept。
• config / dict。
• file / upload。
• log 查询和审计接收。
• user attributes。

业务项目单独使用 iti-flask 时，仍可使用鉴权依赖、权限 provider、数据库、迁移、缓存、限流、事件和任务。 加入 iti-system 时，只替换权限 provider 并增加系统域路由。