# delphi-admin

**Repository Path**: shock_hack_admin/delphi-admin

## Basic Information

- **Project Name**: delphi-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DelphiAdmin

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Delphi](https://img.shields.io/badge/Delphi-12%20Athens-blue)](https://www.embarcadero.com/products/delphi)
[![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D)](https://vuejs.org/)

通用后台管理系统 — **DelphiMVCFramework (Indy EXE) + Vue 3 / Element Plus**,支持 SQLite / SQL Server 双数据库。

核心特性:**前端元数据驱动的自动生成引擎** — 80% 的 CRUD 模块零代码交付,只需在 Entity 类上标注 Delphi Attribute,前后端 CRUD 自动生成。

---

## ✨ 功能特性

| 模块 | 说明 | 实现方式 |
|------|------|---------|
| **自动生成引擎** | Attribute 声明式 CRUD,Schema API + ResourcePage 动态渲染 | 引擎 |
| 认证 | JWT + token_version 撤销 + 登录验证码 + 登录失败锁定 | 手写 |
| 多租户 | 共享库行级隔离,PlatformAdmin 全库可见 | 框架 |
| RBAC 权限 | 角色 / 菜单 / 按钮级权限,动态路由 + v-permission | 手写 |
| DataScope | 五级数据权限(全部/本部门及以下/本部门/仅本人/自定义) | 手写 |
| 用户管理 | 用户 CRUD + 角色分配 | 手写 |
| 角色管理 | 角色 CRUD + 权限分配 + DataScope 配置 | 手写 |
| 菜单管理 | 目录/菜单/按钮树形管理 | 手写 |
| 部门管理 | 树形 CRUD,自动维护 ancestors | 引擎 |
| 多租户管理 | 租户 CRUD + 模拟登录 | 手写 |
| 字典管理 | 字典类型 + 字典数据,动态下拉数据源 | 引擎 |
| 参数配置 | 系统参数键值对 | 引擎 |
| 通知公告 | 引擎端到端 tracer-bullet 模块 | 引擎 |
| 操作日志 | 写操作审计日志中间件 | 中间件 |
| 登录日志 | 登录成功/失败记录 | 手写 |
| 在线用户 | 在线会话 + 强制下线 | 手写 |
| 定时任务 | Cron 表达式调度 + 任务日志 | 手写 |
| i18n / 暗黑主题 | 国际化 + 深色模式 | 配置 |

## 🧱 技术栈

| 层 | 技术 |
|----|------|
| 后端框架 | [DelphiMVCFramework](https://github.com/danieleteti/delphimvcframework) (DMVC) |
| 部署形态 | Indy 独立 EXE (`TMVCListener`),可注册 Windows Service |
| ORM | MVCActiveRecord (FireDAC) |
| 数据库 | SQLite (开发) / SQL Server (生产),`config.ini` 一键切换 |
| 认证 | JWT + `token_version` 撤销 (ADR-0003) |
| 权限 | RBAC + DataScope 五级 (ADR-0005) |
| 前端 | Vue 3 + Vite + Element Plus + Pinia + TypeScript |

## 📁 项目结构

```
DelphiAdmin/
├── server/
│   ├── DelphiAdmin.Server/            # Indy EXE 主工程(Bootstrap / WebModule)
│   ├── DelphiAdmin.Server.AdminEngine/ # ★ 自动生成引擎(Attribute/Registry/Schema/ResourceController)
│   ├── DelphiAdmin.Server.Common/     # 配置、JWT、租户过滤、操作日志中间件、定时任务等
│   ├── DelphiAdmin.Server.Controllers/# 业务控制器(Auth/User/Role/Menu/Dept/Monitor/Admin…)
│   ├── DelphiAdmin.Server.Entities/   # Entity 定义(AdminEntity 基类 + 业务实体)
│   ├── DelphiAdmin.Server.Services/   # 服务层(Auth/Captcha)
│   └── DelphiAdmin.Server.Tests/      # DUnitX 测试
├── web/admin/                         # Vue 3 前端
│   └── src/
│       ├── components/ResourcePage/   # ★ 元数据驱动通用 CRUD 组件
│       ├── views/                     # 业务页面(含 ResourcePage 薄封装)
│       ├── router/ + store/           # 动态路由(菜单驱动)+ Pinia
│       └── api/                       # API 封装
├── sql/
│   ├── sqlite/init.sql                # SQLite 建表脚本
│   ├── seed.sql                       # 种子数据(默认账号/菜单/字典)
│   └── migration/                     # 增量迁移脚本
├── docs/
│   ├── adr/                           # 架构决策记录 (9 个, ADR-0001 ~ 0009)
│   └── specs/                         # 规格说明
├── config.ini.example                 # 配置模板(复制为 config.ini)
├── CONTEXT.md                         # 领域术语表
└── compile.cmd                        # 一键编译脚本
```

## 🚀 快速开始

### 环境要求

| 依赖 | 版本 |
|------|------|
| Delphi | 12 Athens (或更高, 64-bit) |
| DMVCFramework | 最新版 (含 ActiveRecord) |
| Node.js | 18+ |

### 1. 后端

```bash
# ① 配置 DMVC 源码路径:编辑 compile.cmd 中的 DMVC_SRC / DMVC_LIB
# ② 一键编译(生成 DelphiAdminServer.exe 与测试程序)
compile.cmd

# ③ 准备配置:复制模板并按需修改(端口/数据库/JWT 密钥)
copy config.ini.example config.ini

# ④ 初始化数据库:用 SQLite 客户端执行 sql/sqlite/init.sql 和 sql/seed.sql

# ⑤ 运行
server\DelphiAdmin.Server\DelphiAdminServer.exe
# → 监听 http://localhost:8080

# ⑥ 跑测试
server\DelphiAdmin.Server.Tests\DelphiAdminServerTests.exe
```

> **config.ini 已加入 .gitignore**,请勿提交真实配置与密钥。

### 2. 前端

```bash
cd web/admin
npm install
npm run dev
# → http://localhost:5173 (API 代理到 localhost:8080)
```

### 3. 默认账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| PlatformAdmin(平台管理员) | `admin` | `admin123` |
| TenantAdmin(租户管理员) | `tenantadmin` | `admin123` |

## ⚙️ 配置说明 (`config.ini`)

| 节 | 键 | 说明 |
|----|----|------|
| `[server]` | `port` | 监听端口,默认 8080 |
| `[database]` | `driver` | `SQLite` 或 `SQLServer` |
| `[database]` | `sqlite_path` | SQLite 数据库文件路径 |
| `[database]` | `sqlserver_*` | SQL Server 连接参数 |
| `[jwt]` | `secret` | **必须替换**为强随机密钥(32+ 字节) |
| `[jwt]` | `access_ttl` / `refresh_ttl` | Access / Refresh Token 有效期(秒) |
| `[cors]` | `origin` | 允许的前端来源 |

## 🔌 自动生成引擎(核心亮点)

**原理**:后端通过 RTTI 扫描标注了 `[AdminResource]` 的 Entity → 构建 Schema 元数据 → 经 Schema API 暴露给前端 → 前端通用 `ResourcePage` 组件消费元数据动态渲染 Table/Form/Dialog。

**新增一个 CRUD 模块只需 4 步**:

```pascal
// ① Entity 类标注 Attribute(server/.../Entities/)
[AdminResource('my_order', '我的订单', '/order')]
TMyOrder = class(TAdminEntity)
private
  [MVCTableField('order_no')]
  [AdminField('单号', aftString, [affRequired, affSearchable, affListVisible])]
  FOrderNo: string;

  [MVCTableField('status')]
  [AdminField('状态', aftEnum, [affSearchable, affListVisible])]
  [AdminChoices('0=待处理,1=已完成')]
  FStatus: Integer;
protected
  function GetCustomTableName: string; override;
published
  property OrderNo: string read FOrderNo write FOrderNo;
  property Status: Integer read FStatus write FStatus;
end;
```

```pascal
// ② Controller 一行声明(server/.../Controllers/)
[MVCPath('/api/admin/my_order')]
TMyOrderAdminController = class(TAdminResourceController<TMyOrder>)
end;
```

```pascal
// ③ Bootstrap 注册(server/.../Server.Bootstrap.pas)
Result.AddController(TMyOrderAdminController);
```

```vue
<!-- ④ 前端菜单指向通用组件(无需写页面) -->
<ResourcePage resource="my_order" />
```

> 支持 9 种字段类型(String/Text/Integer/Decimal/Boolean/Enum/DateTime/Date/Relation)与 7 种字段标志(必填/可搜索/列表显示/表单显示/可排序/只读/密码),详见 `docs/adr/0008-admin-auto-generation-engine.md`。

## 📚 开发文档

- [领域术语表](CONTEXT.md)
- [架构决策记录 (ADR)](docs/adr/) — 9 个:部署形态、多租户、JWT 撤销、RBAC、ORM 选型、双数据库、自动生成引擎、编码规范
- [v2 规格说明](docs/specs/0002-delphiadmin-v2.md)
- [Ticket Breakdown](.scratch/delphiadmin-v2/README.md)

## 🤝 贡献

欢迎贡献!提交 PR 前请确认:

- 后端遵循现有 Entity/Controller/Service 分层与 Attribute 约定,源码编码为 **GBK**(见 ADR-0009)
- 前端遵循 `views/` 目录约定,CRUD 优先使用 `ResourcePage` 而非手写页面
- 新增/修改数据库结构时同步更新 `sql/sqlite/init.sql` 或 `sql/migration/`
- 编译通过 `compile.cmd`,后端测试通过 `DelphiAdminServerTests.exe`

## 📄 许可证

[MIT](LICENSE) © 2026 剑飞花