DjangoAdmin_Tornado_EleVue/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

DjangoAdmin Tornado+EleVue is a modular enterprise admin framework. This repo is the backend only — the Tornado REST API server. The Vue2.x + ElementUI frontend ("EleVue") is a separate project not in this repo (static/ and templates/ are mostly empty). Code comments are written in Chinese.

Key stack: Tornado 6.x, SQLAlchemy 2.0, Redis, JWT auth, Pydantic v2 (settings + validation schemas), bcrypt (double-salt password hashing). Python ≥3.10, managed via Poetry. The code lives under src/ (src is added to sys.path by the root app.py entry and by pytest's pythonpath).

Multi-database support: default driver is MySQL (pymysql, installed by default). PostgreSQL / SQL Server / SQLite / Oracle are supported via optional drivers — poetry install -E postgresql (psycopg2-binary) / -E mssql (pymssql) / -E oracle (oracledb); SQLite needs no extra install. Select via DB_DRIVER in .env (aliases: postgres=postgresql, sqlserver=mssql, sqlite3=sqlite); see .env for per-DB connection examples. When DB_DRIVER=sqlite, DB_DATABASE is the DB file path (host/port/user/password ignored); when DB_DRIVER=oracle, DB_DATABASE is the SERVICE_NAME. Engine/connection-pool options are dialect-aware in src/core/database.py (_connect_args, SQLite uses NullPool + check_same_thread=False). document/djangoadmin.tornado.elevue.sql is MySQL-only — for non-MySQL DBs create the schema via alembic upgrade head (Base.metadata.create_all) and seed via scripts/seed.py. The three join queries that used raw SQL+backticks (permission/menu/user services) were rewritten with SQLAlchemy ORM to stay dialect-agnostic.

⚠️ Two files named app.py exist intentionally: root app.py is the thin entry script (runs as __main__), src/app.py is the app factory (create_app()). Never import app from a context where the project root is sys.path[0] (e.g. pytest) — use from src.app import create_app there.

Common Commands

poetry install                       # 安装依赖（含 dev）
poetry run python app.py --port=8041 # 启动服务（默认端口 8041）
poetry run pytest                    # 全部测试（集成测试无服务时自动跳过）
poetry run pytest tests/unit         # 仅单元测试
poetry run flake8 src tests          # 代码规范检查
poetry run mypy src                  # 类型检查
poetry run ruff check --fix src tests
poetry run alembic upgrade head      # 数据库迁移
python scripts/seed_dict.py          # 初始化业务字典（dict/dict_item，幂等）
python scripts/migrate_db.py --help  # 跨库数据迁移（MySQL → PG/MSSQL/SQLite/Oracle，参数显式给出，不依赖 .env）
make install / dev / test / lint     # Makefile 封装

Gotchas:

• Configuration comes from .env via Pydantic Settings (src/config/settings.py). Keys: TORNADO_*, DB_*, REDIS_*, MAIL_*, JWT_*, CAPTCHA_*, UPLOAD_*, LOGIN_*, LOG_*. TORNADO_DEMO=True blocks all write endpoints. JWT_SECRET 必须配置（≥32 字节强随机，缺失/过弱启动即 fail-close 中止；生成：python -c "import secrets; print(secrets.token_urlsafe(48))"）。上传白名单/上限：UPLOAD_ALLOWED_EXTS（逗号分隔带点号）、UPLOAD_MAX_SIZE_MB。登录防爆破：LOGIN_FAIL_MAX / LOGIN_LOCK_SECONDS。
• 业务枚举字典（性别/友链/通知来源等）统一由 scripts/seed_dict.py 写入 dict/dict_item 表，业务代码经 common/utils/dict_util.py 读取（Redis 缓存，字典维护时自动失效）。config/constants.py 不再承载业务枚举，仅保留 SERIALIZE_EXCLUDE_FIELDS。
• The database schema is created from document/djangoadmin.tornado.elevue.sql (import into MySQL). Alembic is wired up (alembic/env.py aggregates src/modules.*.models) and can autogenerate.
• requirements.txt is a plain UTF-8 fallback; Poetry (pyproject.toml + poetry.lock) is the source of truth.

Architecture

Layered design. A request flows: Tornado handler (src/modules/<name>/handlers.py) → business logic (service.py) → repository (repository.py) → SQLAlchemy model (models.py). Input is validated with Pydantic schemas (schemas.py).

Startup: root app.py → src/bootstrap.py:main() (parses --port, installs SIGINT/SIGTERM graceful shutdown) → src/app.py:create_app() builds the tornado.web.Application with routes from src/api/v1/router.py:build_routes().

src/ packages

• src/config/ — settings.py (Pydantic Settings, computes DATABASE_URL/UPLOAD_DIR/SECRET_KEY), constants.py (仅 SERIALIZE_EXCLUDE_FIELDS；业务枚举已迁至 dict 表，经 common/utils/dict_util.py 读取), messages.py (含 PAGE_LIMIT/MAX_PAGE_LIMIT), logging.py (JSON structured logs).
• src/core/ — infrastructure: response.py (R.ok/R.failed/R.response → {code, data, msg, ok}; Codes class: SUCCESS=0/FAILED=1/UNAUTHORIZED=401/FORBIDDEN=403/…; 写完响应并把 body 存到 self._api_result 供日志装饰器解析，函数返回 None), exceptions.py (BaseAppError hierarchy + write_error 记录异常日志), jwt.py (JWT 签发/解析/黑名单/刷新), database.py (writer + optional reader engine, thread-local scoped_session db, Base), redis.py, logger.py, password.py (double-salt bcrypt), context.py (current_user_id/current_username/current_realname/current_trace_id contextvars), and base classes: BaseHandler（on_finish 统一关闭共享 DB 会话）, BaseRepository (generic CRUD + soft delete + audit; see conventions), BaseService (template-method CRUD — see below).
• src/modules/ — the ~20 business modules (auth, user, role, menu, dept, dict, config, level, position, city, notice, link, category, article, param, file_template, job, upload, operation_log, login_log). Each is a six-file package: models.py (SQLAlchemy, core.base_model.BaseModel gives id/create_user(String50)/create_time/update_user/update_time/is_delete + to_dict() which excludes password/salt/is_delete and is timezone-defensive), schemas.py (Pydantic XxxSchema/XxxStatusSchema, extra="ignore"), repository.py (extends BaseRepository, sets model), service.py (a XxxService(BaseService) subclass + xxx_service instance; only auth/upload keep fully bespoke functions — login, file upload), handlers.py (Tornado handlers extending BaseHandler, delegating to xxx_service), __init__.py. dict bundles Dict+DictItem, config bundles Config+ConfigItem+ConfigWeb, role bundles RoleMenu, user bundles UserRole and the profile/index handlers. operation_log / login_log are full audit-log modules: @operation_log records write ops (rich fields + param redaction + IP 归属地) and @login_log records login success/failure/logout; both expose list/detail/delete endpoints under /api/v1/operationlog and /api/v1/loginlog. Permission nodes (menu rows with type=1) are resolved by src/common/permission.py:get_permissions_list（Redis 缓存，角色/菜单变更按版本号失效）.
• src/common/ — middleware/ (authentication/cors/operation_log/login_log/trace_id, plus access_decorators.py holding @check_demo + @permission_required), utils/ (crypto bcrypt, captcha, file [mkdir + 魔术字节校验 verify_file_magic], rich_text [save_file/get_file_url/save_content，XSS 白名单清洗 + 路径穿越防护，图片/文件保存统一入口], ip2region [IP→省市区，日志归属地], dict_util [字典 Redis 缓存读取], helpers [parse_id_list/detect_os/detect_browser/detect_source/redact_params], validators), permission.py (跨模块权限解析).
• src/extensions/ — re-exports core singletons (sqlalchemy.py → Base/db/SessionLocal/engine/reader_engine/ReaderSession; redis.py → redis) and placeholder swagger.py/sentry.py.
• src/api/v1/ — one route module per resource (auth.py, users.py, roles.py, …), each exporting routes; router.py:build_routes() prefixes all with /api/v1 and adds /api/v1/health.

Request lifecycle / auth

• Every business handler subclasses src/core/base_handler.py:BaseHandler. Its prepare() is wrapped with @login_required, so every request except /api/v1/login, /api/v1/captcha, and OPTIONS requires a valid JWT in Authorization: Bearer <token>. The authenticated userId is stored in current_user_id (a contextvar) via src/common/middleware/authentication.py.
• Per-handler authorization uses @permission_required("sys:user:list") (src/common/middleware/access_decorators.py), which checks the user's permission nodes via common.permission.get_permissions_list（Redis 缓存，角色/菜单/用户角色变更时按版本号失效）. User id 1 (admin) bypasses all permission checks.
• Handlers are thin: mutating endpoints are wrapped with @check_demo (src/common/middleware/access_decorators.py), which blocks writes with a unified message when TORNADO_DEMO=True; handlers then delegate to the module's service. Responses go through R.ok/R.failed.
• 登录/登出安全：登录做防爆破（同一 IP+用户名 连续失败 LOGIN_FAIL_MAX 次后锁定 LOGIN_LOCK_SECONDS 秒，Redis 计数）；登出把当前 token 加入黑名单立即失效；POST /api/v1/token/refresh 可轮换签发新 token（旧 token 拉黑）。/api/v1/dict/data/{code} 提供字典下拉数据。

BaseService (template-method CRUD)

Simple modules subclass src/core/base_service.py:BaseService and only declare difference points to get standard CRUD for free: model/repo_cls, Pydantic create_schema/update_schema/status_schema, page_like_fields/page_eq_fields/page_order_by (pagination filters & sort), unique_fields ({field: message} uniqueness check), serialize_maps ({field: dict 字面映射或字典编码字符串}；str 值优先按 dict_util 字典编码解析，回落 config.constants 常量名；取值时兼容 int/str key), serialize_extra/detail_serialize (plain callables (item) -> dict for extra fields), options_filter (dropdown-list equality filter). Hooks to override for bespoke logic: _before_add/_before_update/_before_delete, _build_create_fields/_build_update_fields (update excludes None values so optional fields aren't NULLed). Standard methods: get_page（_parse_pagination 限制 page≥1、limit∈[1,MAX_PAGE_LIMIT]）, get_detail, get_options, add, update, delete, update_status (all take the Tornado handler, return R objects). Heavily-custom modules (user, menu) override add/update/get_page/_serialize_detail/_build_page_query to handle roles/city/permission-nodes; only auth/upload keep fully bespoke functions.

Service / repository conventions

• Repositories (src/core/base_repository.py): soft-delete convention (is_delete=0 = active). Convenience methods (get_by_id (ID-robust), get_by_ids, get_one, all, count, exists, exists_by_field(field, value, exclude_id), filter_by, paginate, create, update, soft_delete, batch_delete("1,2,3")) auto-append the soft-delete filter; filter(*criterion) is the raw escape hatch (no soft filter) for complex conditions. create/update auto-fill audit fields (create_user/update_user) from current_realname（操作者姓名）.
• BaseService standard methods wrap in try/finally: repo.close(); bespoke services call db.close() in a finally block.
• List handlers use page/limit query args (default PAGE_LIMIT=10); deletion endpoints accept comma-separated IDs; all deletes are soft (is_delete=1).
• Passwords are always salted via the double-salt bcrypt scheme in src/core/password.py (generate_salt/encrypt_password/verify_password); the salt is stored in the user salt column. src/common/utils/crypto.py is the facade: set_password(password) -> (salt, hashed) and check_password(password, salt, hashed) for setting/verifying, plus verify_user_password/is_legacy_hash for the login path. Legacy no-salt bcrypt hashes are accepted on login and auto-upgraded to the salt scheme (modules/auth/service.py:_verify_login_password). MD5 is intentionally not supported.
• BaseModel.to_dict() excludes password/salt/is_delete (config.constants.SERIALIZE_EXCLUDE_FIELDS) — never return raw model to_dict() output containing secrets to the API. Model instances do not expose save()/delete() — data access goes through repositories.

API / URL conventions

• All routes are under /api/v1. Handler naming: XxxListHandler, XxxDetailHandler, XxxAddHandler, XxxUpdateHandler, XxxDeleteHandler, XxxStatusHandler, XxxGetListHandler (last returns an option list for dropdowns). Route conventions preserved from the original app: /list?, /detail/(\d+), /add, /update, /delete/(\d+), /status, /getXxxList.
• To add a new feature: copy an existing simple module (e.g. link) across the six files, register a route module in src/api/v1/, and import it in router.py.

Tests

tests/unit covers core (jwt, response, crypto, BaseService, repository, serialization-security) and module schemas. tests/integration (health/captcha/DB/Redis) runs only when MySQL and Redis are reachable — verified via a real SELECT 1/ping in tests/integration/conftest.py, otherwise skipped. The root conftest.py was removed; pytest resolves src via [tool.pytest.ini_options].pythonpath = ["src"], and integration tests import the factory as from src.app import create_app.