Metadata-Version: 2.5
Name: shenjicore
Version: 0.6.4
Summary: 轻量、规范、AI 可循的 FastAPI 后端基础框架
Author: ShenjiCore Developers
License: MIT
License-File: LICENSE
Keywords: backend,fastapi,framework,shenji
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic-settings>=2.9
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: uvicorn>=0.30
Provides-Extra: auth
Requires-Dist: pyjwt>=2.8; extra == 'auth'
Provides-Extra: dev
Requires-Dist: aiomysql>=0.2; extra == 'dev'
Requires-Dist: cryptography>=42.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: minio>=7.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: file
Requires-Dist: openpyxl>=3.1; extra == 'file'
Provides-Extra: hikvision
Requires-Dist: httpx>=0.27; extra == 'hikvision'
Requires-Dist: opencv-python-headless>=4.8; extra == 'hikvision'
Provides-Extra: httpclient
Requires-Dist: httpx>=0.27; extra == 'httpclient'
Provides-Extra: minio
Requires-Dist: minio>=7.2; extra == 'minio'
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2; extra == 'mysql'
Requires-Dist: cryptography>=42.0; extra == 'mysql'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: scheduler
Requires-Dist: croniter>=1.4; extra == 'scheduler'
Provides-Extra: tasks
Provides-Extra: yolo-vision
Requires-Dist: imageio-ffmpeg>=0.5; extra == 'yolo-vision'
Requires-Dist: opencv-python-headless>=4.8; extra == 'yolo-vision'
Requires-Dist: ultralytics>=8.3; extra == 'yolo-vision'
Description-Content-Type: text/markdown

# ShenjiCore 神机核

**轻量、规范、AI 可循**的 FastAPI 开发约定层，为 Web 应用、AI 交互流
（SSE / WebSocket）、算法服务与设备接入等后端场景提供统一底座。

## 适用场景

| 业务形态 | 后端要支撑的能力 |
|---|---|
| **Web / 企业应用** | 鉴权、CRUD、任务与审批流 |
| **AI 交互流** | 大模型流式交互（SSE / WebSocket）、多轮对话编排、交互流程状态机 |
| **算法服务** | 推理 API、结果上报、事件告警推送、模型管理 |
| **设备接入** | 设备云端控制、遥测数据接入、任务下发与回执、云边端协同接口 |

**核心原则**：无论上层是 Web 应用、算法服务还是设备终端，后端代码结构
只有一套约定——`action → domain → dao` 单向分层、统一响应信封、集中错误码、
自动路由注册。开发者与 AI 按同一套规范编码，业务形态再多也不失控。

## 为什么是"约定"而非"魔法"

团队后端代码一致性低、AI 生成的代码风格不可控。ShenjiCore 通过**约定**约束代码：

- **统一分层**：`action → domain → dao → schema → common`，单向依赖
- **统一响应**：所有接口（含错误）同一种信封 `{code, message, data}`
- **统一异常**：集中错误码 + `ErrorSpec` 常量，杜绝魔法数字
- **统一路由**：action 目录自动注册，新增接口不改 main.py
- **统一插件**：核心之外的业务能力一律插件化（`PLUGINS=` 配置即开关）
- **统一脚手架**：`shenjicore init` 生成标准骨架，AI 按 `docs/CONVENTIONS.md` 编码

核心保持极简，无重型第三方依赖，只保留 FastAPI 生态，核心依赖 5 个：
`fastapi` + `uvicorn` + `pydantic` + `pydantic-settings` + `python-dotenv`
（后两者为配置读取所必需）。

**核心 + 插件**：核心只做骨架（应用组装、统一响应/异常、自动路由、脚手架），
数据库、认证、AI 交互流、视觉算法、设备接入等业务能力一律以**插件**形式加载
（`shenjicore/plugins/*`，可选安装、配置即开关）。装插件不会污染核心：

```bash
# .env —— 启用插件（导入路径列表）
PLUGINS=[
  "shenjicore.plugins.mysql",
  "shenjicore.plugins.auth",
]
```

```python
# main.py —— 或显式传入插件（不配 PLUGINS= 时）
from shenjicore import run
from shenjicore.plugins.mysql import MysqlPlugin

if __name__ == "__main__":
    run(plugins=[MysqlPlugin()])
```

```bash
pip install "shenjicore[mysql]"     # 安装 MySQL 插件依赖（aiomysql），不装不影响核心
pip install "shenjicore[auth]"   # 安装 Auth 插件依赖（PyJWT），不装不影响核心
pip install "shenjicore[redis]"  # 安装 Redis 插件依赖（redis），不装不影响核心
pip install "shenjicore[minio]"  # 安装 MinIO 插件依赖（minio），不装不影响核心
pip install "shenjicore[hikvision]"  # 安装海康插件依赖（httpx + opencv），不装不影响核心
pip install "shenjicore[file]"    # 安装文件插件依赖（openpyxl 可选：Excel 导出），不装不影响核心
pip install "shenjicore[scheduler]"  # 安装定时任务插件依赖（croniter：cron 表达式），不装不影响核心
pip install "shenjicore[httpclient]"  # 安装 HTTP 客户端插件依赖（httpx），不装不影响核心
pip install "shenjicore[yolo_vision]"  # 安装 YOLO 视觉插件依赖（ultralytics + opencv + imageio-ffmpeg）
pip install "shenjicore[tasks]"   # 任务平台插件无额外依赖（队列复用 redis、归档复用 mysql 各自 extra）
```

## 快速开始

```bash
pip install shenjicore         # 核心依赖（fastapi/uvicorn/pydantic）自动带上，无需再装
shenjicore init --name my_service --port 9140
cd my_service
cp .env.example .env           # 端口等值由 .env 提供；不复制则回落默认 8000
python main.py
```

三步起服务（`init` → `cp .env` → `python main.py`）。打开
`http://127.0.0.1:9140/api/docs` 查看文档，`GET /api/hello/greet` 验证分层示例。
main.py 只需两行：

```python
from shenjicore import run

if __name__ == "__main__":
    run()      # 自动发现 common/config.py 的 Settings、action/ 路由目录、.env
```

## 目录结构

```
shenjicore/
├── shenjicore/               # 框架包本体（核心，5 个依赖）
│   ├── core/               # 核心：app 工厂 / 错误 / 响应 / 配置 / 日志 / 中间件
│   │   ├── app.py          # create_app（CORS、异常处理、健康检查、路由、插件注册）
│   │   ├── errors.py       # ErrorSpec + ShenError + 公共错误码
│   │   ├── response.py     # ok() / page() 统一响应
│   │   ├── config.py       # ShenSettings（pydantic-settings 基类，多环境分层）
│   │   ├── log.py          # 日志（标准库，文本/JSON 双模式，自动带 request_id）
│   │   ├── middleware.py   # 请求 ID + 访问日志 + 安全响应头（OWASP 基线）
│   │   ├── request_id.py   # request_id ContextVar（日志串联的上下文）
│   │   └── time.py         # 统一时间（北京时间，全框架含插件唯一入口）
│   ├── plugin.py           # ★ 插件机制：ShenPlugin 基类 + register_plugins
│   ├── plugins/            # 官方插件（可选安装）：mysql / auth / rbac / audit / redis /
│   │                       #   minio / hikvision / file / httpclient / scheduler /
│   │                       #   tasks / yolo_vision 全部已实现
│   ├── router.py           # action 目录自动注册（ENABLE_ROUTER / URL_PREFIX）
│   └── cli.py              # shenjicore init 脚手架
├── docs/
│   ├── CONVENTIONS.md      # ★ 开发规范（分层/接口/错误码/命名/插件/AI 约定）
│   ├── USER_GUIDE.md       # ★ 使用说明书（全部已实现功能的完整用法）
│   ├── ROADMAP.md          # 后续规划
│   └── PUBLISHING.md       # 发布指南（版本 / 发版流程 / 质量门槛）
├── CHANGELOG.md            # 版本变更记录（Keep a Changelog 风格）
├── LICENSE                 # MIT 许可正文（随包分发）
├── .github/workflows/ci.yml  # CI 模板（lint + 全量测试 + MySQL service）
└── tests/                  # 框架测试（1295 收集：1273 通过 + 22 跳过）
                            #   覆盖 core 与全部已实现插件（mysql/auth/rbac/audit/redis/
                            #   minio/hikvision/file/httpclient/scheduler/tasks）
                            #   各插件测试数随时增删，`pytest --collect-only -q` 可复算
```

## 开发

```bash
pip install -e ".[dev]"
ruff check .        # 代码检查
pytest              # 测试
```

## 路线图

见 `docs/ROADMAP.md`：**已完成** MySQL 插件（连接池/DAO/事务/多表查询/死锁重试）、
Auth 插件（scrypt/JWT/API Key）、Redis 插件（缓存/分布式锁/限流/信号量）、MinIO 插件、
海康插件、文件插件（分片/直传/Excel 导入导出）、任务平台、调度器、HTTP 客户端、
RBAC 与审计。**下一步**：AI 交互流（SSE/WebSocket，需先验证中间件对流式响应的
缓冲问题）、Device 插件（具身智能设备接入与遥测）、代码生成器、模板项目仓库。

> 注：Vision 插件经裁决（2026-08-31）不单独建立——帧级识别走海康 `stream.on_frame`
> 回调，推理服务调用归 HTTP 客户端插件；`yolo_vision` 插件（推理引擎封装）已实现。

## 文档

- `docs/USER_GUIDE.md` — **使用说明书**：所有已实现功能的完整用法
  （配置 / 响应与错误码 / 日志 / 时间 / 路由 / 插件 / DB / Auth / API Key / Redis / 完整示例）
- `docs/CONVENTIONS.md` — 开发规范（分层 / 接口 / 错误码 / 命名 / AI 约定，唯一规范来源）
- `docs/ROADMAP.md` — 路线图
