FastapiAdmin/REQUIREMENTS.md

SaaS 多租户平台需求文档

版本：v3.6.0 最后更新：2026-06-03

---

Part 1：平台架构与基础设施

---

1. 概述

1.1 背景

FastapiAdmin 是一个基于 FastAPI + SQLAlchemy 的管理后台框架，需要支持 SaaS 多租户模式。平台提供完善的多租户隔离和授权体系，包含平台管理端、套餐体系、租户独立授权、插件系统、工单系统等能力。

1.2 核心目标

1. 数据隔离：不同租户间的业务数据严格隔离，通过 tenant_id 行级过滤实现
2. 权限分层：平台层（菜单/套餐/插件）→ 租户层（可见菜单/配额/配置）→ 用户层（角色/数据权限）
3. 灵活授权：通过套餐体系预设权限 + 自定义授权相结合，简化租户开通流程
4. 资源管控：租户配额管理（用户数/角色数/存储空间等）防止资源滥用

1.3 角色定义

角色	说明	租户范围
超级管理员 (Super Admin)	平台拥有者，管理所有租户和套餐，不受租户过滤	平台
租户管理员 (Tenant Admin)	被指定为租户的 owner/admin，管理租户内部资源	单个租户
租户用户 (Tenant User)	普通业务用户，使用租户内的功能	单个租户

1.4 模块总览

模块	类型	租户隔离	核心用途
Auth	系统	无	登录认证、OAuth、JWT
User	系统	✅ TenantMixin	用户管理、角色/岗位分配
Role	系统	✅ TenantMixin	角色定义、菜单/部门权限分配
Dept	系统	✅ TenantMixin	树形部门管理
Position	系统	✅ TenantMixin	岗位管理
Menu	系统	无	平台菜单树（纯平台资源）
Dict	系统	✅ TenantMixin（平台共享）	字典类型+数据
Notice	系统	✅ TenantMixin	通知公告
Params	系统	✅ TenantMixin	系统参数配置
LoginLog	平台	无	登录日志（平台级）
OperationLog	系统	✅ TenantMixin	操作日志（租户级）
Tenant	平台	无（自身为租户定义）	租户管理
Package	平台	无	套餐管理
Ticket	系统	✅ TenantMixin	工单反馈
Plugin	平台	无（平台资源）	插件注册表
Cronjob	插件	✅ TenantMixin	定时任务
Workflow	插件	✅ TenantMixin	工作流引擎
AI Chat	插件	✅ TenantMixin	AI 对话
CodeGen	插件	✅ TenantMixin	代码生成器
Invoice	平台	无（关联 order）	发票管理（普票/专票）
AuditLog	平台	无	审计日志（不可篡改）
Dashboard	平台	无	运营数据大盘

---

2. 平台架构

2.1 整体架构

┌─────────────────────────────────────────────────┐
│                  Controller 层                    │
│    路由定义 / 参数校验 / 响应封装 / 操作日志      │
├─────────────────────────────────────────────────┤
│                  Service 层                       │
│    业务逻辑编排 / 数据校验 / 权限检查             │
├─────────────────────────────────────────────────┤
│                   CRUD 层                         │
│    CRUDBase 通用增删改查 / 租户过滤 / 权限过滤     │
├─────────────────────────────────────────────────┤
│                   Model 层                        │
│    SQLAlchemy ORM / Mixin 体系 / 关系定义         │
├─────────────────────────────────────────────────┤
│   DB (MySQL/PgSQL/SQLite)    │    Redis 缓存      │
└─────────────────────────────────────────────────┘

2.2 请求链路

请求 → Middleware链 → 租户中间件(解析token,设置ContextVar) →
路由匹配 → 依赖注入(DI) → Controller → Service → CRUD →
ORM(自动注入tenant_id) → DB → 反向响应 → ContextVar清理

2.3 模块目录结构

每个业务模块遵循统一结构：

module_xxx/
├── __init__.py
├── controller.py    # API 路由定义
├── service.py       # 业务逻辑
├── crud.py          # 数据操作（继承 CRUDBase）
├── model.py         # SQLAlchemy 模型
└── schema.py        # Pydantic 请求/响应模型

---

3. 数据隔离模型

3.1 核心设计原则

平台资源（无 tenant_id）
  ├── platform_menu              ← 菜单定义，纯平台资源
  ├── platform_package      ← 套餐定义
  ├── platform_plugin       ← 插件注册表
  └── platform_tenant       ← 租户定义

租户资源（含 tenant_id，ORM 自动过滤）
  ├── sys_user              ← 用户
  ├── sys_role              ← 角色
  ├── sys_dept              ← 部门
  ├── sys_position          ← 岗位
  ├── sys_notice            ← 通知公告
  ├── sys_param             ← 系统参数
  ├── sys_log               ← 日志
  ├── platform_ticket       ← 工单
  └── 插件业务表

平台共享资源（tenant_id=1 的平台数据对所有租户可读）
  ├── sys_dict_type         ← 字典类型
  └── sys_dict_data         ← 字典数据

3.2 三层隔离机制

层级	实现文件	机制说明
ORM 事件层	tenant_filter.py	SQLAlchemy do_orm_execute 事件自动注入 WHERE tenant_id = ?
CRUD 层	base_crud.py	__build_conditions / __tenant_condition 二次确认
权限策略层	permission.py	基于角色 data_scope 字段精细化控制

ORM 事件层行为

操作	超管	普通用户
SELECT	不过滤	自动追加 WHERE tenant_id = ?（__platform_data_shared__ 模型跳过此层过滤，由 CRUD 层处理）
INSERT	不自动设置	自动设置 tenant_id = 当前租户
UPDATE/DELETE	不过滤	自动追加 WHERE tenant_id = ?
系统表(platform_tenant)	不过滤	不过滤

⚠️ 特别注意：标记了 __platform_data_shared__ = True 的模型（DictType/DictData），ORM 事件层跳过自动 tenant_id 过滤，由 CRUD 层的 __tenant_condition(read_mode=True) 统一处理 WHERE tenant_id = current OR tenant_id = 1 逻辑。防止 ORM 事件层覆盖了"平台共享"读取策略。

权限策略层

策略	枚举值	说明	适用模型
ROLE_BASED	1	仅显示用户角色授权的数据	Menu
DEPT_BASED	2	基于部门范围过滤	Dept
USER_ROLE	3	仅显示用户绑定的角色	Role
SELF_ONLY	4	仅本人数据	预留
DATA_SCOPE	5	基于 data_scope 字段	Tenant（通用）

data_scope 数据范围

值	说明
1	仅本人数据
2	本部门数据
3	本部门及以下数据
4	全部数据
5	自定义数据（通过 sys_role_depts 指定可见部门）

3.3 Mixin 体系

MappedBase (声明式基类)
  ├── ModelMixin (id, uuid, status, description, 时间戳, 软删除)
  ├── TenantMixin (tenant_id FK → platform_tenant.id, NOT NULL, default=1, ON DELETE RESTRICT)
  └── UserMixin (created_id, updated_id, deleted_id FK → sys_user)

ModelMixin 通用字段

字段	类型	说明
id	Integer PK AI	主键
uuid	String(64) UNIQUE	UUID 全局唯一标识
status	Integer	default=0
description	Text nullable	备注/描述
created_time	DateTime	创建时间
updated_time	DateTime	更新时间（onupdate）
is_deleted	Boolean default=False	软删除标记
deleted_time	DateTime nullable	删除时间

platform_data_shared 机制

标记了 __platform_data_shared__ = True 的模型（DictType/DictData），在 CRUD 层查询时：

• 超管：不过滤，可查看/修改所有租户的数据
• 普通用户：WHERE tenant_id = current_tenant_id OR tenant_id = 1

---

Part 2：核心业务模块需求

---

4. Auth 认证模块

4.1 业务描述

提供用户认证、授权、会话管理功能，支持多种登录方式（密码登录、OAuth2 第三方登录），支持验证码安全校验。

4.2 业务流程

登录请求 → 验证码校验(启用时) → 用户认证(用户名+密码) →
检查用户状态 → 更新最后登录时间 → 查询用户关联租户列表 →
判断租户数量:
  ├── 单租户: 直接生成 JWT(含 tenant_id) → 返回 token
  └── 多租户: 生成临时 JWT(不含 tenant_id, 仅限调用 /auth/select-tenant) →
           返回 租户选择 token + 租户列表 →
           用户选择 → /auth/select-tenant/{id} → 生成含 tenant_id 的正式 token
记录在线会话 → 返回正式 token

多租户登录说明：

• 临时 token（不含 tenant_id）：仅能调用 POST /auth/select-tenant/{id}，其他任何接口均返回 403
• 正式 token（含 tenant_id）：正常访问所有已授权的 API
• 超管用户跳过租户选择，直接生成含 is_super_admin=True 的正式 token（不绑定任何 tenant_id）

4.3 核心规则

规则	说明
验证码	配置控制是否启用，API 文档请求（docs/redoc）跳过验证码
密码校验	Bcrypt 哈希比对
状态检查	用户 status="1"（禁用）时拒绝登录
JWT 载荷	包含 session_id, user_id, tenant_id, is_super_admin, 登录信息
Token 刷新	refresh_token 专用，不可用 access_token 刷新
多租户登录	登录后判断：单租户用户直接签发含 tenant_id 的正式 token；多租户用户签临时 token（不含 tenant_id，仅可访问 POST /auth/select-tenant/{id}），选择租户后签正式 token
在线记录	登录成功后 Redis 记录在线会话，含 IP/OS/浏览器/登录位置
日志记录	操作日志路由类自动记录登录日志

4.4 数据模型

无独立数据表，使用 Redis 存储会话和验证码。

4.5 用户自助注册

POST /auth/register
  ├── 接收：username, password, email, tenant_name(可选)
  ├── 校验：用户名/邮箱唯一性
  ├── 创建租户记录（platform_tenant）
  │     ├── name = tenant_name 或 "{username}的租户"（默认名）
  │     ├── code = 自动生成（基于 name 拼音首字母 + 4位随机数）
  │     ├── package_id → 取全局默认套餐（platform_package.is_default=true 的第一条，若无则 id=1）
  │     ├── end_time = now + trial_days(取套餐的 trial_days，默认 7 天)
  │     ├── max_users/max_roles/max_depts → 取套餐配额默认值（见 §16.2）
  │     └── status = 0(active)
  ├── 创建用户记录（sys_user，tenant_id=新租户ID）
  ├── 创建 owner 角色（sys_role，code="owner"）
  ├── 将用户绑定到 owner 角色
  ├── 将租户可用菜单全量分配给 owner 角色
  └── 返回注册成功（用户需邮箱验证后激活）

默认套餐获取优先级：套餐 is_default=true > id=1 > 无套餐(仅自定义菜单)。若平台未配置任何套餐，新租户仅有自定义菜单体系，需超管后续手动配置。

4.6 API 端点

方法	路径	说明
POST	/auth/login	登录（多租户用户返回临时 token + 租户列表）
POST	/auth/token/refresh	刷新 token
POST	/auth/logout	退出登录（清除 Redis 会话）
GET	/auth/captcha	获取验证码（Base64 图片）
POST	/auth/register	用户注册（创建用户 → 自动创建默认租户并设为 owner）
POST	/auth/select-tenant/{id}	选择/切换租户（生成含 tenant_id 的正式 token）
POST	/auth/forgot-password	忘记密码（发送重置邮件）
GET	/auth/auto-login/{token}	免登录（用于邮件/消息免登链接）
GET	/auth/oauth/{provider}/login	OAuth2 授权跳转
GET	/auth/oauth/{provider}/callback	OAuth2 回调处理（需用户预绑定第三方账号；首次 OAuth 登录不绑定租户，需选择/创建租户）

---

5. User 用户模块

5.1 业务描述

管理平台和租户下的用户账号，支持角色分配、岗位分配、部门归属、密码管理、Excel 导入导出。用户数据按租户严格隔离。

5.2 数据模型

表名：sys_user（TenantMixin, UserMixin）

字段	类型	约束	说明
username	String(64)	NOT NULL, UNIQUE(tenant_id)	用户名/登录账号
password	String(255)	NOT NULL	Bcrypt 密码哈希
name	String(32)	NOT NULL	昵称/姓名
mobile	String(11)	nullable	手机号
email	String(64)	nullable	邮箱
gender	String(1)	default="2"	性别（0:男 1:女 2:未知）
avatar	String(255)	nullable	头像 URL
is_superuser	Boolean	default=False	是否超级管理员
last_login	DateTime	nullable	最后登录时间
dept_id	FK→sys_dept.id	nullable, ON DELETE SET NULL	所属部门
gitee_login	String(32)	nullable	Gitee 第三方登录
github_login	String(32)	nullable	Github 第三方登录
wx_login	String(32)	nullable	微信第三方登录
qq_login	String(32)	nullable	QQ 第三方登录

关联关系：

关联表	关系类型	说明
sys_user_roles	多对多	用户 ↔ 角色
sys_user_positions	多对多	用户 ↔ 岗位
platform_user_tenant	多对多	用户 ↔ 租户（跨租户支持）

5.3 业务规则

类别	规则
创建	username 字母开头、3~32位；不允许创建超管；username/mobile/email 唯一
修改	不可修改超管；username/mobile/email 唯一性检查；部门必须存在且可用
删除	仅已禁用(status=1)用户可删除；不可删除超管；不可删除当前登录用户
密码	Bcrypt 加密存储；修改需验证原密码；重置不可操作超管
导入导出	支持 Excel 导入导出；导入时密码字段处理策略：密码列为空 → 系统自动生成12位随机密码并通过邮件发送给用户；密码列有值 → Bcrypt 加密后存储，首次登录强制修改密码
状态	批量启用/禁用；不可操作超管

5.4 当前用户菜单权限

get_current_user_info_service:
  ├── 超管 → 返回全部 PC 端菜单（type=1/2/4, client=pc）
  └── 普通用户：
        ├── 收集角色菜单 ID（角色→菜单，去重）
        ├── 与租户可用菜单取交集
        └── 构建菜单树返回

5.5 API 端点

方法	路径	说明
GET	/user/detail/{id}	用户详情
GET	/user/list	用户列表
POST	/user/create	创建用户
PUT	/user/update/{id}	更新用户
DELETE	/user/delete	删除用户（批量）
PATCH	/user/status/batch	批量设置用户状态
GET	/user/current/info	获取当前用户信息（含菜单树）
PUT	/user/current/update	更新当前用户信息
PUT	/user/current/password/change	修改密码（本人操作，需验证原密码）
PUT	/user/password/reset	重置密码（管理员操作，跳过原密码）
POST	/user/import	导入用户（Excel）
POST	/user/export	导出用户（Excel）

---

6. Role 角色模块

6.1 业务描述

角色是权限分配的核心载体，每个角色可绑定多个菜单（功能权限）和多个部门（数据权限）。角色数据按租户严格隔离。

6.2 数据模型

表名：sys_role（TenantMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	角色名称
code	String(64)	NOT NULL, UNIQUE(tenant_id)	角色编码
order	Integer	default=999	显示排序
data_scope	Integer	default=1	数据权限范围（1~5）

关联关系：

关联表	关系类型	说明
sys_role_menus	多对多	角色 ↔ 菜单
sys_role_depts	多对多	角色 ↔ 部门（仅 data_scope=5 时使用）
sys_user_roles	多对多	用户 ↔ 角色

6.3 业务规则

规则	说明
编码规则	字母开头，仅含字母/数字/下划线
租户唯一	(tenant_id, code) 唯一约束
权限策略	USER_ROLE — 非超管用户只能看到自己绑定的角色
菜单约束	非超管只能为角色分配租户可用菜单内的菜单，越权时抛出异常含菜单名称
数据范围	1=仅本人 2=本部门 3=本部门及以下 4=全部 5=自定义（绑定部门）
默认 owner 角色	创建租户时自动创建 code="owner" 的角色，不可删除、不可禁用。自动分配租户全部可用菜单

6.4 API 端点

方法	路径	说明
GET	/role/detail/{id}	角色详情
GET	/role/list	角色列表
POST	/role/create	创建角色
PUT	/role/update/{id}	更新角色
DELETE	/role/delete	删除角色（批量）
PATCH	/role/status/batch	批量设置角色状态
PUT	/role/menus	设置角色菜单
PUT	/role/permission	设置角色权限（含数据范围+部门）

---

7. Dept 部门模块

7.1 业务描述

部门是组织架构的核心，采用树形结构支持无限层级。部门数据按租户严格隔离。

7.2 数据模型

表名：sys_dept（TenantMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	部门名称
code	String(64)	NOT NULL, UNIQUE(tenant_id, code)	部门编码
parent_id	Integer FK	nullable	父级部门
order	Integer	default=999	显示排序
leader	String(32)	nullable	负责人
phone	String(20)	nullable	联系电话
email	String(128)	nullable	邮箱

7.3 业务规则

规则	说明
树形结构	parent_id 自引用，支持无限层级。创建/更新 parent_id 时需检测循环引用
编码规则	字母开头，仅含字母/数字/下划线
租户唯一	(tenant_id, code) 唯一约束
权限策略	DEPT_BASED — 基于部门范围过滤
删除约束	有子部门的父部门不可删除
状态级联	父部门禁用时子部门同步禁用（业务层实现）

7.4 API 端点

方法	路径	说明
GET	/dept/detail/{id}	部门详情
GET	/dept/list	部门列表（树形）
POST	/dept/create	创建部门
PUT	/dept/update/{id}	更新部门
DELETE	/dept/delete	删除部门（批量）
PATCH	/dept/status/batch	批量设置部门状态

---

8. Position 岗位模块

8.1 业务描述

岗位用于定义用户在组织内的职务角色，一个用户可绑定多个岗位。

8.2 数据模型

表名：sys_position（TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	岗位名称
order	Integer	default=1	显示排序

8.3 API 端点

方法	路径	说明
GET	/position/detail/{id}	岗位详情
GET	/position/list	岗位列表
POST	/position/create	创建岗位
PUT	/position/update/{id}	更新岗位
DELETE	/position/delete	删除岗位（批量）
PATCH	/position/status/batch	批量设置岗位状态

---

9. Menu 菜单模块

9.1 业务描述

菜单是系统功能权限的基础定义单元，属于平台级资源（无 tenant_id），由超级管理员统一管理。菜单以树形结构组织，支撑前端动态路由和后端权限控制。

9.2 数据模型

表名：platform_menu（ModelMixin，无 TenantMixin）

字段	类型	约束	说明
name	String(50)	NOT NULL	菜单名称
type	Integer	NOT NULL, default=2	类型（1:目录 2:菜单 3:按钮 4:外链）
order	Integer	NOT NULL, default=999	显示排序
permission	String(100)	nullable	权限标识（如 system:user:query）
icon	String(50)	nullable	菜单图标
route_name	String(100)	nullable	路由名称
route_path	String(200)	nullable	路由路径（以 / 开头）
component_path	String(200)	nullable	组件路径（不能以 / 开头）
redirect	String(200)	nullable	重定向地址
hidden	Boolean	default=False	是否隐藏
keep_alive	Boolean	default=True	是否缓存
always_show	Boolean	default=False	是否始终显示
title	String(50)	nullable	菜单标题
params	JSON	nullable	路由参数
affix	Boolean	default=False	是否固定标签页
client	String(20)	NOT NULL, default="pc"	终端（pc/app）
parent_id	FK→platform_menu.id	nullable, ON DELETE SET NULL	父菜单

9.3 菜单类型

类型	说明	路由	前端行为
1	目录	无	展开项，不可点击
2	菜单	有	可点击进入页面
3	按钮/权限	无	页面内操作权限标识
4	外部链接	有	跳转外部 URL

9.4 业务规则

规则	说明
平台资源	无 tenant_id，所有租户共享菜单池
路由规则	route_path 以 / 开头，component_path 不能以 / 开头
类型校验	ge=1, le=4
client 过滤	前端菜单渲染仅取 client="pc" 的菜单
权限策略	ROLE_BASED — 非超管用户按角色菜单过滤
树形结构	parent_id 自引用，children 按 order 排序。创建/更新 parent_id 时需检测循环引用（如 A→B→C→A），禁止导致循环的操作

9.5 API 端点

方法	路径	说明
GET	/menu/detail/{id}	菜单详情
GET	/menu/list	菜单列表（树形）
POST	/menu/create	创建菜单
PUT	/menu/update/{id}	更新菜单
DELETE	/menu/delete	删除菜单（批量）
PATCH	/menu/status/batch	批量设置菜单状态

---

10. Dict 字典模块

10.1 业务描述

字典模块提供统一的类型-数据管理，用于维护系统中固定的下拉选项和枚举值。字典数据支持平台共享（tenant_id=1 的平台字典对所有租户可读）。

10.2 数据模型

DictType（sys_dict_type）

字段	类型	约束	说明
dict_name	String(64)	NOT NULL	字典名称
dict_type	String(255)	NOT NULL, UNIQUE(tenant_id)	字典类型编码

平台共享：__platform_data_shared__ = True

DictData（sys_dict_data）

字段	类型	约束	说明
dict_sort	Integer	default=0	排序
dict_label	String(255)	NOT NULL	字典标签
dict_value	String(255)	NOT NULL	字典键值
css_class	String(255)	nullable	样式属性
list_class	String(255)	nullable	表格回显样式
is_default	Boolean	default=False	是否默认
dict_type	String(255)	NOT NULL	字典类型（冗余字段）
dict_type_id	FK→sys_dict_type.id	NOT NULL, ON DELETE CASCADE	字典类型 ID

10.3 业务规则

规则	说明
平台共享	tenant_id=1 的字典对所有租户可读。写保护：修改/删除 tenant_id=1 的平台字典数据时，仅允许超管操作，普通租户管理员不可修改平台字典
编码规则	dict_type 以小写字母开头，仅含小写字母/数字/下划线
级联删除	删除 DictType 时，关联的 DictData 自动级联删除
双关联	DictData 同时保留 dict_type（字符串冗余）和 dict_type_id（FK）双重关联。dict_type 为冗余字段，用于避免频繁 JOIN DictType 表获取类型编码。两者应保持一致，业务层插入时自动填充 dict_type 并与 dict_type_id 对应
唯一约束	DictData 表：UNIQUE(tenant_id, dict_type_id, dict_value)，同一字典类型下不可有重复的 dict_value

10.4 API 端点

字典类型

方法	路径	说明
GET	/dict/type/detail/{id}	字典类型详情
GET	/dict/type/list	字典类型列表
POST	/dict/type/create	创建字典类型
PUT	/dict/type/update/{id}	更新字典类型
DELETE	/dict/type/delete	删除字典类型（批量）
PATCH	/dict/type/status/batch	批量设置字典类型状态

字典数据

方法	路径	说明
GET	/dict/data/detail/{id}	字典数据详情
GET	/dict/data/list	字典数据列表
POST	/dict/data/create	创建字典数据
PUT	/dict/data/update/{id}	更新字典数据
DELETE	/dict/data/delete	删除字典数据（批量）
PATCH	/dict/data/status/batch	批量设置字典数据状态

---

11. Notice 通知公告模块

11.1 业务描述

管理租户内部的通知和公告发布。通知数据按租户严格隔离。

11.2 数据模型

表名：sys_notice（TenantMixin, UserMixin）

字段	类型	约束	说明
notice_title	String(64)	NOT NULL	公告标题
notice_type	String(1)	NOT NULL	类型（1:通知 2:公告）
notice_content	Text	nullable	公告内容（富文本，XSS 过滤）

已读状态表：sys_notice_read（按租户隔离）

字段	类型	约束	说明
user_id	FK→sys_user.id	PK, ON DELETE CASCADE	用户ID
notice_id	FK→sys_notice.id	PK, ON DELETE CASCADE	通知ID
read_time	DateTime	NOT NULL, default=now	已读时间

唯一约束：UNIQUE(user_id, notice_id)。未建立记录即代表未读。

11.3 业务规则

规则	说明
类型校验	仅支持 "1"(通知) 和 "2"(公告)
XSS 防护	notice_content 经过 sanitize_html 清洗
已读追踪	使用后端 sys_notice_read 表记录已读状态（多设备同步）。未读数量通过 LEFT JOIN 统计；通知列表返回未读数量标记

11.4 API 端点

方法	路径	说明
GET	/notice/detail/{id}	公告详情
GET	/notice/list	公告列表
POST	/notice/create	创建公告
PUT	/notice/update/{id}	更新公告
DELETE	/notice/delete	删除公告（批量）
PATCH	/notice/status/batch	批量设置公告状态
POST	/notice/read/{id}	标记已读（写入 sys_notice_read）
POST	/notice/read-all	全部标记已读
GET	/notice/unread-count	获取当前用户未读通知数量

---

12. Params 系统参数模块

12.1 业务描述

管理系统级别的配置参数，支持区分系统内置参数（不可删除）和自定义参数。参数数据按租户隔离。

12.2 数据模型

表名：sys_param（TenantMixin）

字段	类型	约束	说明
config_name	String(64)	NOT NULL	参数名称
config_key	String(500)	NOT NULL	参数键名
config_value	String(500)	nullable	参数键值
config_type	Boolean	default=False	是否系统内置

12.3 业务规则

规则	说明
键名规则	小写字母开头，仅含小写字母/数字/_.-
系统内置	config_type=True 的参数不允许删除（业务层实现）

12.4 API 端点

方法	路径	说明
GET	/params/detail/{id}	参数详情
GET	/params/list	参数列表
POST	/params/create	创建参数
PUT	/params/update/{id}	更新参数
DELETE	/params/delete	删除参数（批量）

---

13. LoginLog 登录日志模块

13.1 业务描述

记录用户登录行为，用于安全审计和登录统计。登录日志为平台级资源，不受租户隔离限制，平台管理员可查看所有租户的登录记录。

13.2 数据模型

表名：platform_login_log（ModelMixin, UserMixin）

字段	类型	约束	说明
status	Integer	NOT NULL, default=1	登录状态（1:成功 2:失败）
login_ip	String(50)	nullable	登录 IP
login_location	String(255)	nullable	登录位置
request_os	String(64)	nullable	操作系统
request_browser	String(64)	nullable	浏览器
msg	String(255)	nullable	提示消息

13.3 API 端点

方法	路径	说明	权限
GET	/platform/loginlog/detail/{id}	登录日志详情	平台管理员
GET	/platform/loginlog/list	登录日志列表	平台管理员
DELETE	/platform/loginlog/delete	删除登录日志（批量）	平台管理员

---

14. OperationLog 操作日志模块

14.1 业务描述

记录系统的操作日志，用于审计和问题追踪。通过 OperationLogRoute 路由类自动记录操作日志。日志数据按租户隔离，租户管理员仅能查看本租户的操作日志。

14.2 数据模型

表名：sys_operation_log（ModelMixin, TenantMixin, UserMixin）

字段	类型	约束	说明
request_path	String(255)	NOT NULL	请求路径
request_method	String(10)	NOT NULL	请求方法
request_payload	LONGTEXT/TEXT	nullable	请求体
request_ip	String(50)	nullable	请求 IP
request_os	String(64)	nullable	操作系统
request_browser	String(64)	nullable	浏览器
response_code	Integer	NOT NULL	响应状态码
response_json	LONGTEXT/TEXT	nullable	响应体
process_time	String(20)	nullable	处理耗时

14.3 存储适配

数据库	大字段类型
MySQL	LONGTEXT
PostgreSQL	TEXT
SQLite	Text

14.4 API 端点

方法	路径	说明	权限
GET	/system/operationlog/detail/{id}	操作日志详情	租户管理员
GET	/system/operationlog/list	操作日志列表	租户管理员
DELETE	/system/operationlog/delete	删除操作日志（批量）	租户管理员

14.5 日志保留策略

操作日志表数据量大（生产环境可能每天数十万条），需配置自动清理机制：

配置项	说明	默认值
operation_log_retention_days	日志保留天数	90 天
operation_log_cleanup_enabled	是否启用自动清理	true
operation_log_cleanup_cron	定时清理 cron 表达式	每天凌晨 3:00

• 定时任务 cleanup_operation_log 删除 create_time < now - retention_days 的记录
• 清理前可选归档到外部存储（OSS/本地文件），由 operation_log_archive_enabled 控制
• 登录日志（platform_login_log）同样受此策略管理

---

15. Tenant 租户管理模块

15.1 业务描述

租户是 SaaS 平台的核心概念，代表一个独立的组织。租户管理包含：租户定义、配额管理、配置管理、用户关联、自定义菜单授权。

15.2 数据模型

核心表：platform_tenant（ModelMixin，无 TenantMixin）- 单一大表设计

将配额和配置字段直接集成到主表，简化结构便于管理。

字段	类型	约束	说明
name	String(100)	NOT NULL, UNIQUE	租户名称
code	String(100)	NOT NULL, UNIQUE	租户编码（字母数字）
contact_name	String(64)	nullable	联系人
contact_phone	String(20)	nullable	联系电话
contact_email	String(128)	nullable	联系邮箱
address	String(255)	nullable	地址
domain	String(255)	nullable	自定义域名
logo_url	String(500)	nullable	Logo URL
description	Text	nullable	租户描述
version	String(20)	nullable	版本号
sort	Integer	default=0	排序
status	Integer	NOT NULL, default=0	生命周期：0=active(正常) 1=grace(宽限期) 2=suspended(暂停) 3=frozen(冻结) 4=expired(过期) 5=archived(归档)
package_id	FK→platform_package.id	nullable, ON DELETE SET NULL	关联套餐
start_time	DateTime	nullable	开始时间
end_time	DateTime	nullable	结束时间
grace_period_days	Integer	default=7, ge=0	宽限期天数（到期后延迟禁用天数）
grace_start_time	DateTime	nullable	宽限期开始时间（自动写入）
max_users	Integer	default=50, ge=1	最大用户数
max_roles	Integer	default=20, ge=1	最大角色数
max_storage_mb	Integer	default=500, ge=1	最大存储(MB)
max_depts	Integer	default=50, ge=1	最大部门数
favicon	String(500)	nullable	网站图标
login_bg	String(500)	nullable	登录背景图
copyright	String(255)	nullable	版权信息
help_doc	String(500)	nullable	帮助文档地址
privacy	String(500)	nullable	隐私政策地址
clause	String(500)	nullable	服务条款地址
keep_record	String(100)	nullable	ICP 备案号
git_code	String(500)	nullable	源码地址

关联表（必要的多对多关系）

表名	说明	关键字段
platform_user_tenant	用户-租户关联	user_id, tenant_id, role(owner/admin/member), is_default
platform_tenant_menu	租户自定义菜单	tenant_id, menu_id, UNIQUE(tenant_id, menu_id)

15.3 核心业务流程

创建租户

POST /tenant/create
  ├── 创建租户记录（platform_tenant）
  ├── 生成初始管理员：{code}_admin + 随机12位密码（含特殊字符）
  ├── 密码不返回、不记录日志；生成一次性密码重置链接（含时效 Token，有效期24小时）
  ├── 向 contact_email 发送重置链接邮件（若未填 contact_email 则跳过，超管需手动处理）
  ├── 创建默认 owner 角色（sys_role），编码固定为 "owner"
  ├── 将初始管理员绑定到 owner 角色（sys_user_roles）
  ├── 将租户可用菜单（套餐菜单 + 自定义授权菜单）全量分配给 owner 角色（sys_role_menus）
  ├── 初始化租户配额（默认值写入 platform_tenant 主表）
  └── 返回租户信息（不含密码）

安全说明：初始管理员密码仅通过邮件中的一次性链接设置，不通过日志、API 响应等任何渠道明文传递。首次登录强制修改密码。

删除租户

DELETE /tenant/delete
  ├── 系统租户(id=1)不可删除
  ├── 仅支持删除 archived 状态的租户
  ├── 有关联数据时拒绝删除，提示需先清理
  └── 通过则物理删除（不可恢复）

租户生命周期状态机

                    ┌── 冻结 ──┐
                    ↓          │
创建 → active(0) ──┤          ├→ archived(5) → deleted(已删除)
                    │          │      ↑
                    └→ grace(1) → suspended(2) → expired(4) ┘
                         ↑            │
                         └── 续期 ←──┘

状态说明：

状态	编码	触发方式	说明
active	0	创建/续期/恢复	正常访问，读写开放
grace	1	到期后自动	宽限期：可登录但提示续费，功能正常
suspended	2	宽限期结束后自动	暂停：禁止写操作，仅可查看数据
expired	4	暂停超过保留期后自动	过期：禁止登录，数据保留待归档
frozen	3	超管手动冻结	冻结：立即禁止访问（不经过宽限期），可恢复为 active。保留全部数据
archived	5	冻结/过期后定时归档	归档：禁止访问，数据保留。唯一可被物理删除的状态
deleted	—	物理删除	已移除记录，不可逆

冻结/归档/删除操作流：

冻结(PATCH /tenant/status/batch → status=3)
  ├── 仅超管可操作
  ├── 系统租户(id=1)不可冻结
  ├── 仅 active(0) 状态可冻结
  └── 租户内所有用户 session 失效（Redis token 缓存清除）

归档(定时任务自动或手动)
  ├── 扫描 status=3 且冻结超过 archive_after_days(默认30天) 的租户
  ├── 扫描 status=4 且过期超过 archive_after_days 的租户
  └── 自动将 status 设置为 5(archived)

物理删除(DELETE /tenant/delete)
  ├── 仅 archived(status=5)状态的租户可删除
  ├── 系统租户(id=1)不可删除
  ├── 检查关联数据：用户/部门/角色/岗位
  ├── 有关联数据时拒绝删除，提示需先清理
  └── 无关联数据 → 物理删除

套餐变更影响预览

套餐变更前，系统返回影响预览，超管确认后再执行：

PUT /tenant/update/{id} (package_id 变更)
  ├── 仅超管可操作
  ├── 调用预检接口 GET /tenant/{id}/package-change-preview?new_package_id=xxx
  │     返回：
  │     - 受影响的角色列表（名称、用户数）
  │     - 将被移除的菜单清单（名称、路径）
  │     - 配额变化对比（max_users/max_roles/max_depts 当前值 → 新值）
  │     - 受影响用户数总计
  ├── 前端展示影响明细，超管确认
  ├── 更新 tenant.package_id
  ├── 获取新可用菜单 ID（套餐菜单 ∪ 自定义菜单）
  ├── 清理角色中不在可用菜单内的 RoleMenus 记录
  ├── 更新租户配额（max_users/max_roles/max_depts 同步为新套餐限制值）
  │     ├── 升级：配额只增不减（新值 > 旧值时才更新）
  │     └── 降级：当前使用量 > 新配额时降级操作可执行但不缩减已有数据，仅限制后续新增
  ├── 发送通知给租户管理员（站内信，列出被回收的菜单和配额变化）
  └── 完成

预检接口：GET /platform/tenant/{id}/package-change-preview?new_package_id={id} 通知内容：本次套餐变更收回了 X 个菜单权限，涉及 Y 个角色，请知悉。

15.4 业务规则

类别	规则
系统租户	id=1 不可删除、禁用（冻结/归档）、修改编码
编码	仅含字母和数字，用于生成初始管理员用户名
初始管理员	自动创建，用户名 {code}_admin，密码 12 位随机（含特殊字符）。同时自动创建 owner 角色，将初始管理员绑定为 owner，并将租户当前可用菜单（套餐菜单 ∪ 自定义菜单）全量分配给该角色。初始管理员登录后即可看到完整的租户菜单，无需超管手动介入
配额	创建租户时，配额默认值从所选套餐的 max_users/max_roles/max_depts 复制到 platform_tenant 主表。无套餐时使用硬编码默认值（users=10, roles=5, depts=10）。超管可在租户管理页手动调整
owner 保护	每个租户至少保留一个 owner。从租户移除用户时，检查该用户是否为该租户的唯一 owner，是则拒绝移除。修改用户租户角色时，禁止将最后一个 owner 降级为 member。默认 owner 角色（code="owner"）不可删除、不可禁用，确保租户始终有可用角色来管理
配额执行	租户配额在创建资源时执行检查。UserCRUD.create 检查 max_users，RoleCRUD.create 检查 max_roles，DeptCRUD.create 检查 max_depts。达到上限时拒绝创建并提示
默认租户	用户首次加入的租户自动设为默认，设置新默认时清除旧默认
多租户	一个用户可关联多个租户
生命周期	租户状态流转：active(0)→grace(1)→suspended(2)→expired(4)→archived(5)→物理删除。超管可人工冻结 active→frozen(3)→archived(5)。frozen 可恢复为 active。仅 archived 状态可物理删除。expired/frozen 超过 archive_after_days(默认30天) 后由定时任务自动归档为 archived(5)
冻结后失效	租户冻结后，Redis 中该租户所有用户的 token 缓存立即清除，用户下次请求时因 token 无效被拒绝访问
续期	active/grace/suspended 状态的租户可通过 PUT /tenant/renew/{id} 续期，传入 end_time 延长有效期并恢复为 active(0)；expired/frozen/archived 状态不可续期

15.5 配置缓存策略

机制	说明
缓存 key	tenant_config:{tenant_id}:{config_key}
读取策略	优先读 Redis，未命中回源 DB 并写回缓存
更新策略	更新后自动同步刷新 Redis
预热	应用启动时 init_tenant_config_cache 预加载所有配置

15.6 API 端点

方法	路径	说明
GET	/tenant/detail/{id}	租户详情
GET	/tenant/list	租户列表
POST	/tenant/create	创建租户（自动配管理员）
PUT	/tenant/update/{id}	修改租户
DELETE	/tenant/delete	删除租户（仅 archived 状态可删）
PATCH	/tenant/status/batch	批量修改状态（含冻结/恢复）
PUT	/tenant/status/{id}	启/禁用（冻结/恢复）
PUT	/tenant/renew/{id}	续期（延长 end_time）
GET	/tenant/{id}/users	获取租户用户列表
POST	/tenant/{id}/users	向租户添加用户
DELETE	/tenant/{id}/users/{uid}	从租户移除用户
GET	/tenant/{id}/quota	获取租户配额
PUT	/tenant/{id}/quota	修改租户配额
GET	/tenant/{id}/config	获取租户配置
GET	/tenant/{id}/config/info	获取租户配置（公开，缓存）
PUT	/tenant/{id}/config	批量更新配置
GET	/tenant/{id}/menus	获取租户自定义菜单
PUT	/tenant/{id}/menus	设置租户自定义菜单

---

16. Package 套餐模块（module_package）

16.1 业务描述

套餐模块是独立的功能模块，用于管理租户的功能套餐配置。套餐是预定义的功能菜单集合，用于标准化租户授权流程。通过套餐体系可以减少逐个分配菜单的工作量，实现基础版/专业版/企业版等分级授权。

16.2 数据模型

platform_package

字段	类型	约束	说明
name	String(100)	NOT NULL, UNIQUE	套餐名称
code	String(100)	NOT NULL, UNIQUE	套餐编码
status	Integer	default=0	状态（0:启动 1:停用）
is_default	Boolean	default=False	是否为默认套餐（自助注册时自动选用）
price	Integer	default=0	价格（分），0=免费
period	String(10)	nullable	计费周期：month/year/once
trial_days	Integer	default=0	试用天数，0=无试用
max_users	Integer	default=10	套餐用户数上限
max_roles	Integer	default=5	套餐角色数上限
max_depts	Integer	default=10	套餐部门数上限
max_tenants	Integer	nullable	该套餐最大租户数限制（平台运营管控），null=不限制
sort	Integer	default=0	排序

platform_package_menu

字段	类型	约束	说明
package_id	FK→platform_package.id	PK, ON DELETE CASCADE	套餐 ID
menu_id	FK→platform_menu.id	PK, ON DELETE CASCADE	菜单 ID

唯一约束：(package_id, menu_id)

16.3 核心流程

租户可用菜单合并逻辑

get_tenant_available_menu_ids(tenant_id):
  可用菜单 = set()
  
  # 1. 如果租户关联了套餐，取出套餐的所有菜单
  if tenant.package_id:
      可用菜单.add(套餐菜单...)
  
  # 2. 取出租户自定义授权菜单（platform_tenant_menu）
  可用菜单.add(自定义菜单...)
  
  return list(可用菜单)  # 并集

套餐变更后清理

套餐变更 → 取新可用菜单 ID →
查询该租户所有角色 → 删除角色中不在可用菜单内的 RoleMenus 记录 → 完成

16.4 业务规则

规则	说明
套餐变更	仅超管可操作
删除约束	删除前检查是否有租户使用，有则拒绝
级联策略	套餐删除时，租户 package_id SET NULL
菜单设置	套餐菜单全量替换（先删后插）
套餐禁用	套餐 status=1 时，已关联该套餐的租户在 get_tenant_available_menu_ids 中不再计入套餐菜单，仅保留租户自定义菜单（platform_tenant_menu）。恢复 status=0 后套餐菜单自动恢复
套餐已删	套餐被删除（package_id SET NULL）后，租户降级为仅有自定义菜单，需及时为受影响租户迁移或补配权限

16.5 API 端点

方法	路径	说明
GET	/platform/package/detail/{id}	套餐详情
GET	/platform/package/list	套餐列表
POST	/platform/package/create	创建套餐
PUT	/platform/package/update/{id}	修改套餐
DELETE	/platform/package/delete	删除套餐
GET	/platform/package/{id}/menus	获取套餐菜单
PUT	/platform/package/{id}/menus	设置套餐菜单（全量替换）

---

17. Ticket 工单模块

17.1 业务描述

工单系统用于用户提交反馈、建议和缺陷报告，支持指派处理人进行跟踪处理。工单数据按租户隔离。

17.2 数据模型

表名：platform_ticket（TenantMixin, UserMixin）

字段	类型	约束	说明
title	String(200)	NOT NULL	工单标题
ticket_content	Text	nullable	工单内容（富文本）
summary	Text	nullable	工单内容（纯文本摘要）
ticket_type	String(20)	NOT NULL, default="suggestion"	类型（suggestion/bug/optimize/other）
status	Integer	NOT NULL, default=0	状态（0:待处理 1:处理中 2:已完成 3:已关闭）
images	Text	nullable	图片 URL 列表（JSON 数组）
reply	Text	nullable	回复内容
assigned_id	FK→sys_user.id	nullable, ON DELETE SET NULL	处理人

17.3 状态流转

待处理(0) → 处理中(1) → 已完成(2)
   ↑            │
   └──── 已关闭(3)

状态转换规则

源状态	目标状态	允许角色	说明
待处理(0)	处理中(1)	创建人/处理人/超管	确认受理
待处理(0)	已关闭(3)	创建人/超管	取消提交
处理中(1)	已完成(2)	处理人/超管	处理完成
处理中(1)	已关闭(3)	创建人/处理人/超管	强行关闭（需填写原因）
已完成(2)	已关闭(3)	创建人/超管	确认关闭
已关闭(3)	待处理(0)	超管	仅超管可重新打开

非法转换（如已完成→处理中）应在 Service 层校验并拒绝 |

17.4 API 端点

方法	路径	说明
GET	/ticket/detail/{id}	工单详情
GET	/ticket/list	工单列表
POST	/ticket/create	创建工单
PUT	/ticket/update/{id}	更新工单
DELETE	/ticket/delete	删除工单（批量）
PUT	/ticket/batch/status	批量更新工单状态

---

18. Plugin 插件模块

18.1 业务描述

插件系统是平台的扩展机制。platform_plugin 作为插件注册表（平台级资源），记录所有可用插件的元数据。租户通过 platform_tenant_plugin 关联表安装插件。

18.2 数据模型

platform_plugin（平台资源，无 TenantMixin）

字段	类型	约束	说明
name	String(100)	NOT NULL, UNIQUE	插件名称
code	String(50)	NOT NULL, UNIQUE	插件编码（module_xxx）
description	Text	nullable	插件描述
version	String(20)	NOT NULL, default="1.0.0"	版本号
author	String(100)	nullable	作者
icon	String(500)	nullable	图标 URL
category	String(20)	NOT NULL, default="tool"	分类（tool/ai/monitor/business）
price	Integer	NOT NULL, default=0	价格（分，0=免费）
menu_path	String(200)	nullable	菜单路径（安装后显示）
permission_prefix	String(100)	nullable	权限前缀
dependencies	Text	nullable	依赖插件编码（JSON 数组）
sort	Integer	NOT NULL, default=0	排序

platform_tenant_plugin

字段	类型	约束	说明
tenant_id	FK→platform_tenant.id	NOT NULL, ON DELETE CASCADE	租户 ID
plugin_id	FK→platform_plugin.id	NOT NULL, ON DELETE CASCADE	插件 ID
enabled	String(1)	NOT NULL, default="1"	启用（1:启用 0:禁用）
installed_time	DateTime	NOT NULL	安装时间

唯一约束：(tenant_id, plugin_id)

18.3 插件目录结构

plugin/module_xxx/
├── __init__.py
├── plugin.toml          # 插件元数据（名称、版本、路由前缀等）
├── controller.py
├── service.py
├── crud.py
├── model.py
└── schema.py

已内置插件：

• module_ai/chat — AI 对话
• module_example/demo — 示例
• module_generator/gencode — 代码生成器
• module_task/cronjob — 定时任务
• module_task/workflow — 工作流引擎

18.4 API 端点

方法	路径	说明
GET	/plugin/detail/{id}	插件详情
GET	/plugin/list	插件列表（含当前租户安装状态）
POST	/plugin/create	创建插件
PUT	/plugin/update/{id}	更新插件
DELETE	/plugin/delete	删除插件（批量）
POST	/plugin/install	租户安装插件
POST	/plugin/uninstall	租户卸载插件

---

19. 到期处理

19.1 到期阶段定义

租户到期后分三个阶段处理，避免粗暴直接禁用（编码与 §15.2 生命周期统一）：

阶段	编码	说明
active	0	正常，在有效期内
grace	1	宽限期：到期后可登录但每次登录提示续费，功能正常
suspended	2	暂停：宽限期结束后禁用写操作，仅可查看数据
expired	4	过期：暂停超过保留期后，禁止登录

阶段流转（与生命周期统一）：

active(0) → grace(1) → suspended(2) → expired(4) → archived(5)
   ↑            │            │
   └── 续期 ←──┘────────────┘

19.2 自动处理逻辑

定时任务 check_tenant_expiry 定期扫描所有正常状态的租户：

1. 遍历 status=0(active) 或 status=1(grace) 或 status=2(suspended) 的租户
2. 未到达生效时间：start_time 存在且 start_time > now → 暂不处理，登录时提示"租户尚未生效"
3. 进入宽限期：status=0 且 end_time 存在且 now > end_time → 设 status=1，记录 grace_start_time
4. 进入暂停：status=1(grace) 且 now > grace_start_time + grace_period_days（默认7天）→ 设 status=2(suspended)
5. 进入过期：status=2(suspended) 且暂停超过 expire_after_days（默认30天）→ 设 status=4(expired)
6. 宽限期内续期：若 status=1/2 时发现 end_time 已续期至未来 → 恢复 status=0(active)，清除 grace_start_time
7. 即将到期提醒：end_time 在 30天/7天/1天 内 → 触发到期提醒

19.3 各阶段行为

阶段	登录	读操作	写操作	提示
active(0)	✅	✅	✅	无
grace(1)	✅	✅	✅	每次登录弹窗提示"您的租户已到期，请尽快续费"
suspended(2)	✅	✅	❌ 拒绝写入	提示"租户已暂停，请联系管理员续费"
expired(4)	❌	—	—	提示"租户已过期"

19.4 到期配置参数

字段	位置	说明
grace_period_days	platform_tenant 表，Integer，default=7	宽限期天数
expire_after_days	全局配置，Integer，default=30	暂停→过期天数（suspended 超过此天数后自动标记为 expired）
archive_after_days	全局配置，Integer，default=30	frozen/expired 超过此天数后自动归档为 archived(5)

19.5 提醒方式

触点	触发时机	渠道
30天前	end_time - 30d <= now	站内信（sys_notice）
7天前	end_time - 7d <= now	站内信 + 邮件（contact_email）
1天前	end_time - 1d <= now	站内信 + 邮件 + 短信（contact_phone，可选）
已到期（grace）	每次登录	弹窗提示

当前邮件/短信为预留扩展点，未配置渠道时降级为站内信。

---

Part 3：附录

---

20. API 接口汇总

20.1 认证模块

方法	路径	说明
POST	/auth/login	登录
POST	/auth/token/refresh	刷新 token
POST	/auth/logout	退出登录
GET	/auth/captcha	验证码
POST	/auth/register	用户注册（自动创建默认租户）
POST	/auth/select-tenant/{id}	选择租户（生成正式 token）
GET	/auth/tenants	获取可选租户列表
POST	/auth/forgot-password	忘记密码
GET	/auth/auto-login/users	获取免登录用户列表
POST	/auth/auto-login/token	获取免登录Token
POST	/auth/auto-login	免登录
GET	/auth/oauth/{provider}/login	OAuth2 授权跳转
GET	/auth/oauth/{provider}/callback	OAuth2 回调处理

20.2 用户模块

方法	路径	权限标识	说明
GET	/user/detail/{id}	user:query	详情
GET	/user/list	user:query	列表
POST	/user/create	user:create	创建
PUT	/user/update/{id}	user:update	更新
DELETE	/user/delete	user:delete	删除
PATCH	/user/status/batch	user:patch	批量设状态
GET	/user/current/info	-	当前用户信息
PUT	/user/current/info/update	-	更新当前用户
PUT	/user/password/change	-	改密码（本人操作）
PUT	/user/password/reset/{id}	user:update	重置密码（管理员操作）
GET	/user/import/template	user:download	导入模板
POST	/user/import/data	user:import	导入
POST	/user/export	user:query	导出

20.3 角色模块

方法	路径	权限标识	说明
GET	/role/detail/{id}	role:query	详情
GET	/role/list	role:query	列表
POST	/role/create	role:create	创建
PUT	/role/update/{id}	role:update	更新
DELETE	/role/delete	role:delete	删除
PATCH	/role/status/batch	role:patch	批量设状态
PUT	/role/menus	role:update	设置菜单
PUT	/role/permission	role:update	设置权限

20.4 部门模块

方法	路径	权限标识	说明
GET	/dept/detail/{id}	dept:query	详情
GET	/dept/list	dept:query	列表
POST	/dept/create	dept:create	创建
PUT	/dept/update/{id}	dept:update	更新
DELETE	/dept/delete	dept:delete	删除
PATCH	/dept/status/batch	dept:patch	批量设状态

20.5 岗位模块

方法	路径	权限标识	说明
GET	/position/detail/{id}	position:query	详情
GET	/position/list	position:query	列表
POST	/position/create	position:create	创建
PUT	/position/update/{id}	position:update	更新
DELETE	/position/delete	position:delete	删除
PATCH	/position/status/batch	position:patch	批量设状态

20.6 菜单模块

方法	路径	权限标识	说明
GET	/menu/detail/{id}	menu:query	详情
GET	/menu/list	menu:query	列表
POST	/menu/create	menu:create	创建
PUT	/menu/update/{id}	menu:update	更新
DELETE	/menu/delete	menu:delete	删除
PATCH	/menu/status/batch	menu:patch	批量设状态

20.7 字典模块

方法	路径	权限标识	说明
GET	/dict/type/detail/{id}	dict:query	字典类型详情
GET	/dict/type/list	dict:query	字典类型列表
POST	/dict/type/create	dict:create	创建字典类型
PUT	/dict/type/update/{id}	dict:update	更新字典类型
DELETE	/dict/type/delete	dict:delete	删除字典类型
PATCH	/dict/type/status/batch	dict:patch	批量设状态
GET	/dict/data/detail/{id}	dict:query	字典数据详情
GET	/dict/data/list	dict:query	字典数据列表
POST	/dict/data/create	dict:create	创建字典数据
PUT	/dict/data/update/{id}	dict:update	更新字典数据
DELETE	/dict/data/delete	dict:delete	删除字典数据

20.8 通知公告

方法	路径	权限标识	说明
GET	/notice/detail/{id}	notice:query	详情
GET	/notice/list	notice:query	列表
POST	/notice/create	notice:create	创建
PUT	/notice/update/{id}	notice:update	更新
DELETE	/notice/delete	notice:delete	删除
PATCH	/notice/status/batch	notice:patch	批量设状态

20.9 系统参数

方法	路径	权限标识	说明
GET	/param/detail/{id}	params:query	详情
GET	/param/list	params:query	列表
POST	/param/create	params:create	创建
PUT	/param/update/{id}	params:update	更新
DELETE	/param/delete	params:delete	删除
PATCH	/param/status/batch	params:patch	批量设置状态

20.10 登录日志模块

方法	路径	权限标识	说明
GET	/platform/loginlog/detail/{id}	module_platform:loginlog:query	详情
GET	/platform/loginlog/list	module_platform:loginlog:query	列表
DELETE	/platform/loginlog/delete	module_platform:loginlog:delete	删除（批量）

20.11 操作日志模块

方法	路径	权限标识	说明
GET	/system/operationlog/detail/{id}	module_system:operationlog:query	详情
GET	/system/operationlog/list	module_system:operationlog:query	列表
DELETE	/system/operationlog/delete	module_system:operationlog:delete	删除（批量）

20.12 工单模块

方法	路径	权限标识	说明
GET	/ticket/detail/{id}	ticket:query	详情
GET	/ticket/list	ticket:query	列表
POST	/ticket/create	ticket:create	创建
PUT	/ticket/update/{id}	ticket:update	更新
DELETE	/ticket/delete	ticket:delete	删除
PATCH	/ticket/status/batch	ticket:patch	批量设置状态

20.13 插件模块

方法	路径	权限标识	说明
GET	/plugin/detail/{id}	plugin:query	详情
GET	/plugin/list	plugin:query	列表
POST	/plugin/create	plugin:create	创建
PUT	/plugin/update/{id}	plugin:update	更新
DELETE	/plugin/delete	plugin:delete	删除
PATCH	/plugin/status/batch	plugin:patch	批量设置状态
POST	/plugin/install	-	安装插件
POST	/plugin/uninstall	-	卸载插件

20.14 租户模块

方法	路径	权限标识	说明
GET	/tenant/detail/{id}	tenant:query	详情
GET	/tenant/list	tenant:query	列表
POST	/tenant/create	tenant:create	创建
PUT	/tenant/update/{id}	tenant:update	更新
DELETE	/tenant/delete	tenant:delete	删除
PATCH	/tenant/status/batch	tenant:patch	批量设置状态
PUT	/tenant/status/{id}	tenant:update	启/禁用
GET	/tenant/{id}/users	tenant:query	用户列表
POST	/tenant/{id}/users	tenant:update	添加用户
DELETE	/tenant/{id}/users/{uid}	tenant:update	移除用户
GET	/tenant/{id}/quota	tenant:query	获取配额
PUT	/tenant/{id}/quota	tenant:update	修改配额
GET	/tenant/{id}/config	tenant:query	获取配置
PUT	/tenant/{id}/config	tenant:update	更新配置

20.15 套餐模块

方法	路径	权限标识	说明
GET	/platform/package/detail/{id}	package:query	详情
GET	/platform/package/list	package:query	列表
POST	/platform/package/create	package:create	创建
PUT	/platform/package/update/{id}	package:update	更新
DELETE	/platform/package/delete	package:delete	删除
GET	/platform/package/{id}/menus	package:query	获取菜单
PUT	/platform/package/{id}/menus	package:update	设置菜单

20.16 监控模块

方法	路径	权限标识	说明
GET	/monitor/online/list	module_monitor:online:query	在线用户列表
DELETE	/monitor/online/delete	module_monitor:online:delete	强制下线
DELETE	/monitor/online/clear	module_monitor:online:delete	清空所有在线用户
GET	/monitor/cache/info	module_monitor:cache:query	获取缓存监控统计
GET	/monitor/cache/get/names	module_monitor:cache:query	获取缓存名称列表
GET	/monitor/cache/get/keys/{cache_name}	module_monitor:cache:query	获取缓存键名列表
GET	/monitor/cache/get/value/{cache_name}/{cache_key}	module_monitor:cache:query	获取缓存值
DELETE	/monitor/cache/delete/name/{cache_name}	module_monitor:cache:delete	清除指定缓存名称
DELETE	/monitor/cache/delete/key/{cache_key}	module_monitor:cache:delete	清除指定缓存键
DELETE	/monitor/cache/clear	module_monitor:cache:delete	清除所有缓存
GET	/monitor/resource/list	module_monitor:resource:query	目录列表(分页)
POST	/monitor/resource/upload	module_monitor:resource:upload	上传文件
GET	/monitor/resource/download	module_monitor:resource:download	下载文件
DELETE	/monitor/resource/delete	module_monitor:resource:delete	删除文件
POST	/monitor/resource/move	module_monitor:resource:move	移动文件
POST	/monitor/resource/copy	module_monitor:resource:copy	复制文件
POST	/monitor/resource/rename	module_monitor:resource:rename	重命名文件
POST	/monitor/resource/mkdir	module_monitor:resource:mkdir	创建目录
POST	/monitor/resource/export	module_monitor:resource:export	导出资源列表
GET	/monitor/server/info	module_monitor:server:query	服务器监控信息

20.17 文件与健康探针

方法	路径	权限标识	说明
POST	/file/upload	module_common:file:upload	上传文件
POST	/file/download	module_common:file:download	下载文件
GET	/monitor/health	—	基础健康检查
GET	/monitor/health/live	—	存活探针
GET	/monitor/health/ready	—	就绪探针
GET	/monitor/health/stream	—	健康实时流（SSE，30s 快照）
GET	/metrics	—	Prometheus 指标端点

20.18 邮件服务

方法	路径	权限标识	说明
GET	/platform/email/config	platform:email:query	获取 SMTP 配置
PUT	/platform/email/config	platform:email:update	更新 SMTP 配置
POST	/platform/email/test	platform:email:update	发送测试邮件
GET	/platform/email/template/list	platform:email:query	模板列表
POST	/platform/email/template/create	platform:email:create	创建模板
PUT	/platform/email/template/update/{id}	platform:email:update	更新模板
GET	/platform/email/log/list	platform:email:query	发送日志列表

20.19 订单与支付

方法	路径	权限标识	说明
POST	/platform/order/create	platform:order:create	创建订单
GET	/platform/order/detail/{id}	platform:order:query	订单详情
GET	/platform/order/list	platform:order:query	订单列表
POST	/platform/order/cancel/{id}	platform:order:update	取消订单
POST	/platform/payment/callback/alipay	—	支付宝回调
POST	/platform/payment/callback/wxpay	—	微信支付回调
GET	/platform/payment/record/list	platform:payment:query	支付记录列表

20.20 租户自助服务

方法	路径	权限标识	说明
GET	/tenant/package/available	tenant:package:query	可选套餐列表
GET	/tenant/package/preview	tenant:package:query	套餐变更影响预览
POST	/tenant/order/create	tenant:order:create	创建自助订单
GET	/tenant/order/list	tenant:order:query	我的订单列表
GET	/tenant/order/detail/{id}	tenant:order:query	订单详情

20.21 用量统计

方法	路径	权限标识	说明
GET	/platform/api-usage/daily	platform:api_usage:query	按天用量统计
GET	/platform/api-usage/tenant/{id}	platform:api_usage:query	指定租户用量
GET	/platform/api-usage/rank	platform:api_usage:query	租户用量排行
GET	/platform/api-usage/anomalies	platform:api_usage:query	异常调用记录

20.22 用户邀请

方法	路径	权限标识	说明
POST	/tenant/invite/send	tenant:invite:create	发送邀请
GET	/tenant/invite/list	tenant:invite:query	邀请列表
DELETE	/tenant/invite/cancel/{id}	tenant:invite:delete	取消邀请
GET	/invite/validate/{code}	—	校验邀请码（公开）
POST	/invite/accept/{code}	—	接受邀请（需登录）

20.23 发票管理

方法	路径	权限标识	说明
POST	/tenant/invoice/apply	tenant:invoice:create	申请开票
GET	/tenant/invoice/list	tenant:invoice:query	我的发票列表
GET	/tenant/invoice/{id}/download	tenant:invoice:download	下载发票 PDF
GET	/platform/invoice/list	platform:invoice:query	全部发票列表
PUT	/platform/invoice/issue/{id}	platform:invoice:update	开具发票
PUT	/platform/invoice/void/{id}	platform:invoice:update	作废发票

20.24 审计日志

方法	路径	权限标识	说明
GET	/platform/audit/list	platform:audit:query	审计日志列表
GET	/platform/audit/detail/{id}	platform:audit:query	审计日志详情
GET	/platform/audit/export	platform:audit:export	导出审计日志

20.25 运营大盘

方法	路径	权限标识	说明
GET	/platform/dashboard/overview	platform:dashboard:query	运营概览
GET	/platform/dashboard/revenue	platform:dashboard:query	收入趋势
GET	/platform/dashboard/tenants	platform:dashboard:query	租户统计
GET	/platform/dashboard/api-usage	platform:dashboard:query	API 用量趋势

---

21. 数据库表结构

21.1 平台资源表（无 tenant_id）

表名	说明	关键索引
platform_tenant	租户（单一大表，含配额+配置字段）	UNIQUE(name), UNIQUE(code)
platform_package	套餐	UNIQUE(name), UNIQUE(code)
platform_package_menu	套餐-菜单关联	UNIQUE(package_id, menu_id)
platform_menu	菜单	-
platform_plugin	插件注册表	UNIQUE(name), UNIQUE(code)
platform_email_config	邮件 SMTP 配置	单例表
platform_email_template	邮件模板	UNIQUE(code)
platform_email_log	邮件发送日志	-
platform_order	订单	UNIQUE(order_no)
platform_payment_record	支付记录	UNIQUE(transaction_id)

21.2 租户关联表（FK→tenant，无独立 tenant_id 列）

表名	说明	关键索引
platform_tenant_menu	租户自定义菜单	UNIQUE(tenant_id, menu_id)
platform_tenant_plugin	租户安装插件	UNIQUE(tenant_id, plugin_id)
platform_user_tenant	用户-租户关联	UNIQUE(user_id, tenant_id)

21.3 平台级租户关联业务表（含 tenant_id）

表名	说明	关键索引
platform_invite_record	用户邀请记录	UNIQUE(invite_code)
platform_api_usage_daily	API 用量日统计	UNIQUE(tenant_id, date, api_path)

21.4 租户隔离业务表（含 tenant_id）

表名	说明	关键索引
sys_user	用户	UNIQUE(tenant_id, username)
sys_role	角色	UNIQUE(tenant_id, code)
sys_dept	部门	UNIQUE(tenant_id, code)
sys_position	岗位	-
sys_notice	通知公告	-
sys_param	系统参数	-
sys_operation_log	操作日志（租户隔离）	-
platform_login_log	登录日志（平台级，无 tenant_id）	-
platform_ticket	工单	-

21.4 平台共享业务表（含 tenant_id，platform_data_shared）

表名	说明	关键索引
sys_dict_type	字典类型	UNIQUE(tenant_id, dict_type)
sys_dict_data	字典数据	UNIQUE(tenant_id, dict_type_id, dict_value)

21.5 关联表

表名	说明	约束
sys_user_roles	用户-角色关联	PK(user_id, role_id)，ON DELETE CASCADE
sys_user_positions	用户-岗位关联	PK(user_id, position_id)，ON DELETE CASCADE
sys_role_menus	角色-菜单关联	PK(role_id, menu_id)，ON DELETE CASCADE
sys_role_depts	角色-部门关联	PK(role_id, dept_id)，ON DELETE CASCADE
sys_notice_read	通知已读记录	PK(user_id, notice_id)，ON DELETE CASCADE

21.6 插件表

表名	模块	说明	前缀规则
task_workflow	module_task/workflow	工作流定义	task_ = module_task
task_workflow_node_type	module_task/workflow	工作流节点类型	task_ = module_task
task_node	module_task/cronjob	定时任务节点类型	task_ = module_task
task_job	module_task/cronjob	任务执行日志	task_ = module_task
gen_table	module_generator/gencode	代码生成表	gen_ = module_generator
gen_table_column	module_generator/gencode	代码生成字段	gen_ = module_generator
example_demo	module_example/demo	示例表	example_ = module_example
example_demo01	module_example/demo01	示例表01	example_ = module_example

命名规范：platform_ = 平台模块，sys_ = 系统模块，task_ = 任务插件，gen_ = 生成器插件，example_ = 示例模块

21.7 商业运营表

表名	模块	说明
platform_invoice	Invoice	发票记录
platform_refund	Order	退款记录
platform_audit_log	AuditLog	审计日志

---

22. 安全性要求

1. JWT 租户上下文：从 Token 中提取 tenant_id 和 is_super_admin，通过 ContextVar 在整个请求周期传递
2. 白名单路径：登录、验证码、健康检查等公开接口不设置租户上下文
3. 系统租户保护：
   • id=1 不可删除
   • id=1 不可禁用
   • id=1 的编码不可修改
4. 数据删除保护：删除租户前检查关联数据，防止孤立记录
5. 租户 owner 保护：每个租户至少保留一个 owner
6. 菜单越权防护：非超管用户只能在租户可用菜单范围内分配角色菜单
7. ContextVar 清理：请求结束后清理 ContextVar，防止跨请求泄漏
8. 密码安全：Bcrypt 哈希存储，不存储明文；普通用户密码最低 8 位（含字母+数字）；初始管理员密码 12 位随机（含大小写字母+数字+特殊字符）
9. XSS 防护：通知公告内容经过 sanitize_html 清洗
10. 登录限流：同一 IP/账号连续登录失败 5 次后锁定 15 分钟（Redis 计数 + TTL），防止暴力破解
11. 级联策略：所有 FK 均有 ON DELETE/ON UPDATE 级联策略，保证数据完整性
12. 路径越权防护：文件资源管理禁止路径遍历（..），防止越权访问
13. CORS 配置：通过白名单配置允许的来源域名，拒绝未授权的跨域请求

---

23. Email 邮件服务模块

23.1 业务描述

邮件服务是 SaaS 平台的通信基础设施，为密码重置、邀请通知、到期提醒、工单通知等业务提供统一的邮件发送能力。支持 SMTP 配置、模板管理、发送日志追踪。

23.2 数据模型

platform_email_config

字段	类型	约束	说明
smtp_host	String(255)	NOT NULL	SMTP 服务器地址
smtp_port	Integer	NOT NULL, default=465	SMTP 端口
smtp_username	String(255)	NOT NULL	SMTP 用户名
smtp_password	String(255)	NOT NULL, 加密存储	SMTP 密码
sender_name	String(100)	NOT NULL	发件人名称
sender_email	String(255)	NOT NULL	发件人邮箱
use_tls	Boolean	default=True	是否使用 TLS
status	Integer	default=0	状态（0:启用 1:禁用）

单例表：仅一条记录。超管在平台配置中管理。

platform_email_template

字段	类型	约束	说明
code	String(50)	NOT NULL, UNIQUE	模板编码（如 password_reset、tenant_invite、expiry_reminder、ticket_notify）
name	String(100)	NOT NULL	模板名称
subject	String(255)	NOT NULL	邮件主题（支持 {变量} 占位符）
body	Text	NOT NULL	邮件正文（HTML，支持 {变量} 占位符）
variables	Text	nullable	可用变量说明（JSON 数组，如 ["{username}", "{reset_link}"]）
status	Integer	default=0	状态（0:启用 1:禁用）

platform_email_log

字段	类型	约束	说明
template_code	String(50)	nullable	使用的模板编码
to_email	String(255)	NOT NULL	收件人邮箱
to_user_id	FK→sys_user.id	nullable	收件人用户 ID
subject	String(255)	NOT NULL	实际发送的主题
body	Text	NOT NULL	实际发送的正文（渲染后）
status	Integer	NOT NULL, default=0	发送状态（0:待发送 1:成功 2:失败）
error_msg	Text	nullable	失败原因
sent_time	DateTime	nullable	实际发送时间
retry_count	Integer	default=0	重试次数

23.3 业务规则

规则	说明
发送模式	支持同步发送和异步队列两种模式。默认异步（Redis 队列），避免阻塞主请求
重试策略	发送失败自动重试，最多 3 次，间隔 5 分钟。3 次仍失败则标记失败状态
频率限制	同一收件人同一模板 1 小时内最多发送 5 封，防止滥用
模板渲染	调用 send_email(template_code, to, variables) 时，自动从模板渲染 subject 和 body
链路追踪	每次发送记录 platform_email_log，关联 template_code 和 to_user_id

23.4 业务集成点

场景	模板编码	触发时机	变量
密码重置	password_reset	创建租户初始管理员 / 用户忘记密码	{username}, {reset_link}
租户邀请	tenant_invite	管理员邀请用户加入租户	{inviter}, {tenant_name}, {invite_link}
到期提醒(30/7/1天)	expiry_reminder	定时任务检测到期	{tenant_name}, {expire_date}, {days_left}
工单通知	ticket_notify	工单创建/分配/关闭	{ticket_title}, {status}, {assignee}
套餐变更通知	package_change	租户套餐被超管变更	{old_package}, {new_package}, {removed_menus}

23.5 降级策略

当邮件服务不可用时（SMTP 故障、配置缺失），自动降级为站内信（sys_notice），确保关键信息不丢失。

23.6 API 端点

方法	路径	说明	权限
GET	/platform/email/config	获取 SMTP 配置	超管
PUT	/platform/email/config	更新 SMTP 配置	超管
POST	/platform/email/test	发送测试邮件	超管
GET	/platform/email/template/list	模板列表	超管
POST	/platform/email/template/create	创建模板	超管
PUT	/platform/email/template/update/{id}	更新模板	超管
GET	/platform/email/log/list	发送日志列表	超管

---

24. Order 订单与支付模块

24.1 业务描述

订单与支付模块是 SaaS 平台的商业化基础，覆盖订单创建、支付回调、开通激活、续费/升级的完整交易闭环。对接支付宝和微信支付，支持套餐购买、续费和升级三种业务场景。

24.2 业务流程

用户/超管选择套餐 → 生成订单 → 跳转支付 → 支付回调 → 激活/变更套餐
                             ↓ 超时(15分钟)
                          订单自动取消

24.3 数据模型

platform_order

字段	类型	约束	说明
order_no	String(32)	NOT NULL, UNIQUE	订单号（年月日+6位随机数）
tenant_id	FK→platform_tenant.id	NOT NULL	购买租户
package_id	FK→platform_package.id	NOT NULL	购买套餐
order_type	String(20)	NOT NULL	类型：new(新购) renew(续费) upgrade(升级) downgrade(降级)
amount	Integer	NOT NULL	金额（分，≥0；0=免费套餐）
period_count	Integer	NOT NULL, default=1	购买周期数（1个月=1）
status	Integer	NOT NULL, default=0	状态：0=待支付 1=已支付 2=已取消 3=已退款
pay_method	String(20)	nullable	支付方式：alipay(支付宝) / wxpay(微信支付)
pay_time	DateTime	nullable	支付时间
expire_time	DateTime	NOT NULL	订单过期时间（创建后+15分钟），超时未支付自动取消

platform_payment_record

字段	类型	约束	说明
order_id	FK→platform_order.id	NOT NULL	关联订单
transaction_id	String(64)	nullable	第三方交易号
pay_method	String(20)	NOT NULL	支付方式
amount	Integer	NOT NULL	支付金额（分）
status	Integer	NOT NULL	支付结果：0=处理中 1=成功 2=失败
raw_response	Text	nullable	支付平台原始回调数据（JSON）
pay_time	DateTime	nullable	支付完成时间

24.4 支付回调处理流程

POST /platform/payment/callback/{method}
  ├── IP 白名单校验（仅允许支付宝/微信支付官方 IP 段）
  ├── 验证签名（支付宝 RSA / 微信支付 APIv3 签名）
  ├── 分布式锁（Redis SETNX，key=callback_lock:{transaction_id}，TTL=30s）
  ├── 校验金额一致性（回调金额 == 订单金额）
  ├── 校验订单状态（仅 status=0(待支付) 可处理，防止重复激活）
  ├── 更新 platform_order.status=1、pay_time=now
  ├── 写入 platform_payment_record（transaction_id UNIQUE 约束，第二次写入自动失败）
  ├── 根据 order_type 执行激活逻辑：
  │   ├── new/renew → 更新 tenant.end_time、恢复 status=0(active)
  │   ├── upgrade   → 更新 tenant.package_id、执行套餐变更影响预览逻辑（菜单+配额同步）
  │   └── downgrade → 更新 tenant.package_id、清理超出的菜单关联、更新配额
  ├── 发送通知给租户管理员（邮件 + 站内信）
  ├── 释放分布式锁
  └── 返回 success 给支付平台（防止重复回调）

安全要点：

• IP 白名单：仅允许支付宝/微信支付的官方回调 IP，在 Nginx/LB 层配置
• 分布式锁：解决支付平台可能同时回调多条相同交易的并发问题
• 状态校验：status≠0 的订单拒绝处理，防止恶意/重复回调
• 金额校验：回调金额与订单金额不一致时，标记异常并人工介入

24.5 业务规则

规则	说明
订单号生成	{YYYYMMDD}{6位随机数字}，创建时检查唯一性
过期取消	定时任务 cancel_expired_orders 每分钟扫描 status=0 且 expire_time < now 的订单，设为 status=2(已取消)
幂等性	同一 transaction_id 的回调只处理一次（transaction_id UNIQUE 约束 + 分布式锁双重保障）
金额校验	回调金额必须与订单金额一致，不一致则拒绝并告警
IP 白名单	回调接口仅允许支付宝/微信支付官方 IP 调用，在 Nginx/负载均衡层配置
免费套餐	amount=0 时不跳转支付，直接走激活流程
退款	退款为预留扩展，当前仅支持手动标记 status=3

24.7 退款流程

租户管理员申请退款
  ├── POST /tenant/order/refund/apply/{order_id}
  │     条件：订单 status=1(已支付) 且支付时间在 7 天内
  │     body: {reason: "误购/重复支付/服务不满意"}
  ├── 更新 platform_order.refund_status=1(申请中)
  ├── 创建 platform_refund 记录
  ├── 通知超管审核（站内信）
  └── 返回申请结果

超管审核退款
  ├── GET /platform/refund/list（待审核列表）
  ├── PUT /platform/refund/approve/{id}
  │     触发原路退款（调用支付宝/微信退款 API）
  │     更新 platform_refund.status=2(已退款)
  │     更新 platform_order.status=3(已退款)
  │     更新租户套餐（撤销本次购买升级效果，恢复至购买前套餐/到期时间）
  └── PUT /platform/refund/reject/{id}
        更新 platform_refund.status=3(已驳回)
        记录驳回原因

platform_refund

字段	类型	约束	说明
order_id	FK→platform_order.id	NOT NULL, UNIQUE	关联订单
refund_no	String(32)	NOT NULL, UNIQUE	退款单号
amount	Integer	NOT NULL	退款金额（分）
reason	Text	NOT NULL	退款原因
status	Integer	NOT NULL, default=1	1=申请中 2=已退款 3=已驳回 4=已取消
refund_transaction_id	String(64)	nullable	退款交易号（第三方返回）
reviewer_id	FK→sys_user.id	nullable	审核人
review_time	DateTime	nullable	审核时间
reject_reason	Text	nullable	驳回原因

退款规则	说明
可退款条件	支付后 7 天内，订单 status=1(已支付)
退款金额	全额退款（暂不支持部分退款）
退款方式	原路退回（支付宝→支付宝，微信→微信）
套餐回退	退款后恢复至购买前的套餐和到期时间（若为升级/降级订单）
降级补偿	若退款订单为降级类型，退款后套餐回升至降级前套餐
免费套餐	amount=0 的免费套餐订单不支持退款

24.8 API 端点

方法	路径	说明	权限
POST	/platform/order/create	创建订单	超管
GET	/platform/order/detail/{id}	订单详情	超管
GET	/platform/order/list	订单列表	超管
POST	/platform/order/cancel/{id}	取消订单	超管
POST	/platform/payment/callback/alipay	支付宝回调（外网可访问，签名验证）	公开
POST	/platform/payment/callback/wxpay	微信支付回调（外网可访问，签名验证）	公开
GET	/platform/payment/record/list	支付记录列表	超管
POST	/tenant/order/create	租户端创建订单（自助购买/续费/升级）	租户管理员
POST	/tenant/order/refund/apply/{id}	申请退款	租户管理员
GET	/platform/refund/list	退款审核列表	超管
PUT	/platform/refund/approve/{id}	批准退款（触发原路退回）	超管
PUT	/platform/refund/reject/{id}	驳回退款	超管

---

25. TenantSelfService 租户自助服务（代码位于 module_platform/self_service）

25.1 业务描述

租户管理员可在租户管理后台自助选择套餐、购买、续费或升级，无需超管介入。是 SaaS 产品商业化的核心用户侧功能。

25.2 自助套餐选择流程

GET /tenant/package/available
  ├── 返回所有启用的套餐列表
  ├── 标注当前套餐（is_current=true）
  ├── 展示价格/周期/试用天数/功能对比
  ├── 标注可执行的操作：[购买][续费][升级][降级]
  └── 限制：同一套餐已是当前套餐时不展示"升级"按钮

用户选择操作 → 创建订单 → 支付 → 自动激活

25.3 套餐变更影响预览（自助版）

// GET /tenant/package/preview?target_package_id=xxx 返回
{
  "current_package": "basic",
  "target_package": "pro",
  "action": "upgrade",
  "amount": 29900,
  "period": "month",
  "gained_menus": [
    {"name": "数据报表", "path": "/report/dashboard"},
    {"name": "API 管理", "path": "/api/manage"}
  ],
  "lost_menus": [],
  "affected_roles": [],
  "affected_users": 0
}

25.4 自助升级/降级流程

POST /tenant/order/create (body: {package_id, order_type: "upgrade"})
  ├── 校验权限：租户管理员及以上
  ├── 校验租户状态：仅 active(0)/grace(1)/suspended(2) 可操作
  ├── 校验目标套餐：状态启用且不等于当前套餐
  ├── amount > 0 → 跳转支付 → 支付回调激活
  ├── amount = 0 → 直接激活（免费套餐切换）
  └── 激活时执行套餐变更影响预览逻辑（同超管操作 §15.3）

25.5 API 端点

方法	路径	说明	权限
GET	/tenant/package/available	获取可选套餐列表（含当前套餐标记和可执行操作）	租户管理员
GET	/tenant/package/preview	套餐变更影响预览	租户管理员
POST	/tenant/order/create	创建自助订单（购买/续费/升级/降级）	租户管理员
GET	/tenant/order/list	我的订单列表	租户管理员
GET	/tenant/order/detail/{id}	我的订单详情	租户管理员

---

26. APIUsage 用量统计模块

26.1 业务描述

租户级别 API 调用量/频率统计，按天/月聚合，支持计费挂钩、安全异常检测和运营分析。

26.2 数据模型

platform_api_usage_daily

字段	类型	约束	说明
tenant_id	FK→platform_tenant.id	NOT NULL	租户
date	Date	NOT NULL	统计日期
api_path	String(255)	NOT NULL	API 路径
request_count	Integer	NOT NULL, default=0	请求次数
total_duration_ms	BigInt	NOT NULL, default=0	总耗时（毫秒）
error_count	Integer	NOT NULL, default=0	错误次数（4xx/5xx）

唯一约束：UNIQUE(tenant_id, date, api_path)

26.3 统计机制

请求中间件（每个 API 调用）
  ├── 提取 tenant_id、api_path、status_code、响应时间
  ├── Redis 计数器原子递增：api_usage:{tenant_id}:{date}:{api_path}:count
  ├── Redis 计数器：api_usage:{tenant_id}:{date}:{api_path}:duration
  ├── 错误计数（status_code >= 400）：api_usage:{tenant_id}:{date}:{api_path}:errors
  └── 定时任务（每小时）：读取 Redis → UPSERT 到 platform_api_usage_daily → 清理旧 Redis key

26.4 异常检测规则

规则	条件	动作
频率突变	同一 API 调用量超过过去 7 天均值的 5 倍	站内信告警
错误率过高	错误率 > 20% 且请求数 > 100	站内信告警
高频调用	单租户单 API 超过 1000 次/分钟	临时限流（返回 429）

限流配置：rate_limit_enabled（全局开关），rate_limit_threshold（阈值），均可在平台配置中调整。

26.5 API 端点

方法	路径	说明	权限
GET	/platform/api-usage/daily	按天用量统计（支持租户/日期范围筛选）	超管
GET	/platform/api-usage/tenant/{id}	指定租户用量详情	超管
GET	/platform/api-usage/rank	租户用量排行	超管
GET	/platform/api-usage/anomalies	异常调用记录	超管

---

27. UserInvite 用户邀请流程

27.1 业务描述

租户管理员可通过邀请链接或邀请码邀请新用户加入租户。被邀请人通过邮箱接收邀请，点击链接完成注册并自动关联到指定租户和角色。

27.2 数据模型

platform_invite_record

字段	类型	约束	说明
invite_code	String(32)	NOT NULL, UNIQUE	邀请码（UUID，一次性链接参数）
tenant_id	FK→platform_tenant.id	NOT NULL	目标租户
target_role_id	FK→sys_role.id	NOT NULL	预设角色
inviter_id	FK→sys_user.id	NOT NULL	邀请人
invitee_email	String(255)	NOT NULL	被邀请人邮箱
status	Integer	NOT NULL, default=0	状态：0=待接受 1=已接受 2=已过期 3=已取消
expire_time	DateTime	NOT NULL	过期时间（创建后+7天）
accepted_user_id	FK→sys_user.id	nullable	接受邀请后创建的用户 ID
accepted_time	DateTime	nullable	接受时间

27.3 邀请流程

租户管理员发起邀请
  ├── POST /tenant/invite/send
  │     body: {emails: [...], role_id, message?}
  ├── 批量创建 platform_invite_record 行，生成唯一 invite_code
  ├── 发送邮件（模板 `tenant_invite`，含邀请链接）
  ├── 邮件内容：{inviter} 邀请你加入 {tenant_name}，点击链接注册
  └── 链接格式：{domain}/invite/{invite_code}，有效期 7 天

被邀请人接受邀请
  ├── 访问 /invite/{code} 页面
  ├── 校验邀请码：存在、未过期(expire_time > now)、未使用(status=0)
  ├── 如果用户已注册：
  │   ├── 直接关联到租户（sys_user_tenant 插入记录）
  │   ├── 分配预设角色（sys_user_role 插入记录）
  │   └── 更新 invite_record.status=1
  ├── 如果用户未注册：
  │   ├── 跳转到注册页面（邮箱已预填，不可修改）
  │   ├── 用户完成注册
  │   ├── 自动关联到租户，分配预设角色
  │   └── 更新 invite_record.status=1, accepted_user_id
  └── 通知邀请人"XXX 已接受您的邀请"

27.4 业务规则

规则	说明
邀请码唯一性	每次生成全局唯一的 UUID，即使同一邮箱被重复邀请也不同
有效期	默认 7 天，到期后自动标记 status=2（过期），不再可用
重复邀请	同一租户内，同一邮箱有"待接受"的邀请时，提示"该邮箱已有待接受的邀请"，不重复发送
角色预分配	被邀请人加入租户时自动获得 target_role_id 指定的角色
权限	仅租户管理员(owner/admin)可发送邀请
邀请人可见	可查看自己发出的邀请列表及状态
降级	若邮件服务不可用，邀请码可通过站内消息手动复制链接

27.5 过期清理

定时任务 cleanup_expired_invites 每天扫描 status=0 且 expire_time < now 的记录，标记为 status=2。

27.6 API 端点

方法	路径	说明	权限
POST	/tenant/invite/send	发送邀请	租户管理员
GET	/tenant/invite/list	邀请列表（含状态）	租户管理员
DELETE	/tenant/invite/cancel/{id}	取消邀请	租户管理员
GET	/invite/validate/{code}	校验邀请码（公开接口，返回租户名/邀请人）	公开
POST	/invite/accept/{code}	接受邀请（需登录）	登录用户

---

28. 未来扩展建议

28.1 已规划（短期）

1. 知识库/帮助中心：租户自助查阅帮助文档、常见问题。富文本编辑器管理，支持多语言
2. 数据导出/备份：租户自助数据导出（CSV/JSON），满足 GDPR/个保法合规要求。平台级全量备份还原（数据库级）
3. 租户自定义域名：支持通过 domain 字段实现租户专属域名，需配合 Nginx 反向代理配置

28.2 中期扩展

能力	说明	优先级
单点登录（SSO）	支持 SAML/OIDC 协议，企业客户可使用自有 IdP（如 Okta/Azure AD/自有 LDAP）登录	低
多语言支持	租户级 i18n 配置，支持不同租户使用不同语言	低
Webhook 通知	关键事件（支付成功/到期提醒/套餐变更）的 webhook 回调，支持第三方集成	中

28.3 API 路径规范

问题	当前	建议
参数模块名不一致	/param/（单数）vs 模块名 params（复数）	统一为 /param/（与代码一致）
日志层级问题	操作日志 /system/operationlog/ 与其他模块不统一	建议保持现状。登录日志为平台级、操作日志为租户级，层级分开是合理的

28.4 非功能性需求（NFR）

指标	要求
API 响应时间	P95 ≤ 500ms（查询），P95 ≤ 2s（写入/批操作）
并发用户	单实例支持 500+ 并发租户用户（需压测验证）
可用性	99.5%（不包含计划运维窗口）
数据安全	传输层 TLS 1.3，存储层 Bcrypt/AES-256，日志脱敏（手机号/邮箱部分掩码）
兼容性	支持 MySQL 8.0+ / PostgreSQL 14+ / SQLite（开发环境）；Python ≥ 3.12；Node.js ≥ 20
数据库备份	每日全量备份（保留 30 天），每小时增量备份（保留 7 天）。备份异地存储，定期恢复演练（每季度 1 次）
容灾恢复	RTO ≤ 4 小时，RPO ≤ 1 小时。主库故障时自动切换只读副本，30 分钟内完成主从切换
版本升级策略	数据库迁移采用 Alembic 管理，所有 schema 变更通过 migration 脚本执行。升级前自动备份，升级失败可回滚至上一个备份点。主版本升级需提前通知租户（7 天），次版本/补丁版可灰度发布
i18n 基础	后端 API 错误消息统一使用 i18n key（如 errors.user.not_found），前端使用 vue-i18n。初始版本仅提供中文，保留英文翻译文件占位。租户级语言首选项存储在 platform_tenant.lang 字段（预留）
缓存键命名规范	格式：{namespace}:{sub_namespace}:{identifier}。示例：tenant:config:123、api:usage:456:2026-06-03、auth:session:abc123。所有 key 设置 TTL，禁止无过期时间的 key

---

29. 术语表（Glossary）

术语	英文	说明
租户	Tenant	SaaS 平台上的一个独立组织/客户
平台资源	Platform Resource	无 tenant_id 的资源，所有租户共享（菜单/套餐/插件）
租户资源	Tenant Resource	含 tenant_id 的资源，按租户隔离（用户/角色/部门等）
平台共享数据	Shared Platform Data	tenant_id=1 的字典数据，所有租户可读
超管	Super Admin	平台级管理员，is_super_admin=true，可管理所有租户
租户管理员	Tenant Admin	租户内的管理员，角色为 owner/admin
数据权限范围	Data Scope	角色绑定的数据可见范围（全部/本部门及子部门/仅本部门等）
RBAC	Role-Based Access Control	基于角色的访问控制
Mixin	Mixin	SQLAlchemy 混入模式，用于给模型添加通用字段（如 TenantMixin 自动添加 tenant_id）
处理人	Assignee	工单中指派的处理人员
生命周期	Lifecycle	租户的完整状态流转路径：active(0)→grace(1)→suspended(2)→expired(4)→archived(5)→deleted。人工冻结路径：active(0)→frozen(3)→archived(5)
宽限期	Grace Period	租户到期后的缓冲期（默认7天），允许正常使用但提示续费
订单	Order	套餐购买/续费/升级的交易凭证，关联支付回调激活套餐
邀请码	Invite Code	租户管理员邀请用户加入的一次性链接参数（UUID，7天有效）
用量统计	API Usage	租户级别 API 调用量按天聚合统计，用于计费和安全分析
邮件模板	Email Template	预定义的邮件格式（密码重置/邀请/到期提醒），支持变量占位符渲染
支付回调	Payment Callback	支付宝/微信支付完成后异步通知平台更新订单状态的机制
默认套餐	Default Package	标记 is_default=true 的套餐，自助注册时自动选用
分布式锁	Distributed Lock	Redis SETNX 实现的并发互斥机制，防止支付回调等场景的重复处理
数据库迁移	Database Migration	使用 Alembic 管理的版本化 schema 变更脚本，支持升级和回滚
发票	Invoice	订单支付后开具的电子发票（增值税普票/专票），一单一票
审计日志	Audit Log	不可篡改的合规操作记录，仅超管可查阅，保留 3 年
运营大盘	Dashboard	平台运营数据的可视化看板，聚合租户/收入/API 用量等核心指标
原路退回	Refund	支付退款按原支付路径返回（支付宝→支付宝，微信→微信）

---

30. 变更记录

版本	日期	变更内容
v3.1.0	2026-06-01	初始版本，完整的模块化需求文档
v3.2.0	2026-06-02	新增 Plugin 子模块需求：AI Chat/Cronjob/Workflow/CodeGen/Demo；新增 Monitor 监控模块：Online/Cache/Resource/Server；新增 Common 公共模块：File/Health/Metrics
v3.2.1	2026-06-03	需求审查修复：修复全部章节子标题编号错位；统一表名为 platform_* 前缀（与代码一致）；移除已废弃的 sys_tenant_quota/sys_tenant_config 独立表引用；拆分 sys_log 为 sys_operation_log + platform_login_log；统一 Auth 端点路径；明确多租户登录临时/正式 token 机制；补充用户注册租户自动创建流程；添加 start_time 未生效校验；补充通知公告已读机制；补全 Tenant 模型遗漏字段（description/version/privacy 等）；新增安全性要求（登录限流/密码复杂度/CORS）；更新未来扩展建议
v3.2.2	2026-06-03	命名规范统一：修复文档中 sys_login_log→platform_login_log、sys_ticket→platform_ticket 两处表名错误；在 §21 新增 §21.6 插件表汇总（8 张 task_/gen_ 表）；明确全模块命名规范：platform_=平台模块，sys_=系统模块，task_=任务插件，gen_=生成器插件
v3.3.0	2026-06-03	SaaS 产品需求审查修订：P0-1 租户生命周期状态机（active→frozen→archived→deleted）；P0-2 定时任务/工作流代码执行安全性（任意代码→预定义处理器白名单）；P0-3 套餐模型补充定价字段（price/period/trial_days/max_tenants）；P0-4 初始管理员密码交付改为邮件一次性重置链接；P1-1 通知已读机制改为后端 sys_notice_read 表；P1-2 工单增加 close_reason/closed_time/closed_by 字段；P1-3 租户到期增加宽限期和阶段性处理（grace→suspended→expired）；P1-4 用户导入密码处理策略；P1-5 套餐变更增加影响预览和确认流程；P2 操作日志保留策略、API 路径规范、缺失 SaaS 能力规划（用户邀请/数据导出/API用量/审计日志/SSO）；新增 NFR 非功能性需求、术语表
v3.4.0	2026-06-03	业务架构闭环补全：Fix-1 统一 status 编码（String(1)→Integer，合并生命周期与到期阶段编码：0=active/1=grace/2=suspended/3=frozen/4=expired/5=archived）；Fix-2 新增 §23 Email 邮件服务模块（SMTP 配置/模板管理/发送日志/5大业务集成点/站内信降级）；Fix-3 新增 §24 Order 订单与支付模块（订单表/支付记录表/支付宝&微信支付回调/开通续费升级流程）；Fix-4 新增 §25 TenantSelfService 租户自助服务（套餐选择/影响预览/自助升级降级）；Fix-5 新增 §26 APIUsage 用量统计模块（按天聚合/Redis计数器/异常检测/限流）；Fix-6 新增 §27 UserInvite 用户邀请流程（邀请码/邮件邀请/角色预分配/过期清理）；Fix-7 清理残留与全面重编号（移除 §19.4 残留 TODO、§20 新增 §20.18-§20.22 API端点、§21 新增7张新表、§28-§30 重编号、§31-§37 Plugin模块重编号、§29 术语表扩充8个词条、§30 变更记录更新）
v3.5.0	2026-06-03	PRD 正式评审修复：P0-1 修正 Part 4 Plugin 子模块编号（§31-§37 子节编号 25.x-31.x→31.x-37.x，共 34 处）；P0-2 修复初始管理员体验断层（创建租户时自动创建 owner 角色并分配全量菜单，§6.3/§15.3/§15.4 同步更新）；P0-3 统一 status 字段类型（package/ticket/order/payment/invite 全部从 String→Integer，保持与 tenant.status 一致）；P1-1 标题版本号修正（v3.2.2→v3.5.0）；P1-2 自助注册新增默认套餐/配额/到期时间来源（§4.5 注册流程、§16.2 is_default 字段）；P1-3 套餐配额体系补充（§16.2 新增 max_users/max_roles/max_depts 配额字段）；P1-4 套餐变更同步更新配额（§15.3 增加配额对比预览和升级/降级处理逻辑）；P1-5 支付回调安全细节增强（§24.4/§24.5 新增 IP 白名单、分布式锁、状态校验）；P2-1 API 路径规范（§16.5 套餐路径统一为 /platform/package/）；P2-2 新增数据备份与容灾策略（§28.4 NFR）；P2-3 新增版本升级/迁移策略（§28.4 NFR）；P2-4 新增 i18n 基础设计（§28.4 NFR）；P2-5 新增 Redis 缓存键命名规范（§28.4 NFR）；术语表扩充 4 个词条（默认套餐/分布式锁/数据库迁移/冗余恢复）
v3.6.0	2026-06-03	PRD 100% 完整度达标：Fix-1 修正 §26.2/§27.2 子节编号错误（32.2→26.2、33.2→27.2）；Fix-2 修正 §28 节编号排序（28.5→28.3、删除重复 28.5）；Fix-3 §24.7 新增退款流程（platform_refund 表、申请→审核→原路退回、套餐回退逻辑）；Fix-4 新增 §38 Invoice 发票管理模块（普票/专票、百望云等第三方对接、一单一票、30天开票时限）；Fix-5 新增 §39 AuditLog 审计日志模块（不可篡改、JSON 变更对比、13 种审计事件、3年保留策略）；Fix-6 新增 §40 Dashboard 运营大盘模块（MRR/退款率/API用量/套餐分布/收入趋势 9 项指标）；Fix-7 更新 §1.4 模块总览（新增 3 个模块）、§20 新增 §20.23-§20.25 API端点、§21 新增 §21.7 商业运营表、§28 移除已实现项、§29 术语表扩充 4 个词条

---

Part 4：Plugin 子模块需求

---

31. AI Chat 聊天模块（module_ai/chat）

31.1 业务描述

AI 对话模块，提供用户与大模型进行对话的能力。支持多会话管理、WebSocket 流式对话、非流式对话。ChatSession 数据按租户隔离。

31.2 数据模型

聊天会话数据存储在 ChatService 后端（支持内存存储/Redis/数据库三种模式，由配置决定）。Schema 层定义如下：

ChatSessionCreateSchema

字段	类型	约束	说明
title	str	NOT NULL, min_length=1, max_length=200	会话标题

ChatSessionUpdateSchema

字段	类型	约束	说明
title	str	NOT NULL, min_length=1, max_length=200	会话标题

AiChatRequestSchema

字段	类型	约束	说明
message	str	NOT NULL, min_length=1	用户消息内容
session_id	str	nullable	会话ID，不传则创建新会话

AiChatResponseSchema

字段	类型	约束	说明
response	str	NOT NULL	AI 回复内容
session_id	str	NOT NULL	会话ID
function_calls	list[dict]	nullable	函数调用信息
action	dict	nullable	建议执行的操作

31.3 API 端点

方法	路径	权限标识	说明
GET	/chat/detail/{session_id}	module_ai:chat:detail	会话详情
GET	/chat/list	module_ai:chat:query	会话列表
POST	/chat/create	module_ai:chat:create	创建会话
PUT	/chat/update/{session_id}	module_ai:chat:update	更新会话
DELETE	/chat/delete	module_ai:chat:delete	删除会话
POST	/chat/ai-chat	module_ai:chat:query	AI 对话（非流式）
WS	/chat/ws	—	WebSocket 流式对话

---

32. Cronjob 定时任务模块（module_task/cronjob）

32.1 业务描述

定时任务模块提供动态节点定义（NodeModel）和任务执行日志记录（JobModel）。节点定义执行代码块、触发器和参数，通过 APScheduler 调度执行。

32.2 数据模型

NodeModel（task_node，TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	节点名称
code	String(32)	NOT NULL, UNIQUE(tenant_id, code)	节点编码
jobstore	String(64)	nullable, default="default"	存储器
executor	String(64)	nullable, default="default"	执行器
trigger	String(64)	nullable	触发器
trigger_args	Text	nullable	触发器参数
func	Text	NOT NULL	预定义处理器标识符（如 handlers.send_email）。禁止租户提交任意代码
args	Text	nullable	位置参数
kwargs	Text	nullable	关键字参数
coalesce	Boolean	nullable, default=False	是否合并运行
max_instances	Integer	nullable, default=1	最大并发实例数
start_date	String(64)	nullable	开始时间
end_date	String(64)	nullable	结束时间

JobModel（task_job，TenantMixin）

字段	类型	约束	说明
job_id	String(64)	NOT NULL, index	任务ID
job_name	String(128)	nullable	任务名称
trigger_type	String(32)	nullable	触发方式：cron/interval/date/manual
status	String(16)	NOT NULL, default="pending"	执行状态：pending/running/success/failed/timeout/cancelled
next_run_time	String(64)	nullable	下次执行时间
job_state	Text	nullable	任务状态信息
result	Text	nullable	执行结果
error	Text	nullable	错误信息

32.3 业务规则

规则	说明
Node 编码	字母开头，仅含字母/数字/下划线
触发器类型	仅支持 now/cron/interval/date
非立即执行	trigger != "now" 时必须提供 trigger_args
时间校验	end_date 不能早于 start_date
func 必填	Node 创建时 func 不能为空，须为已注册的处理器标识符
处理器白名单	func 字段只能填写平台预注册的处理器（如 handlers.send_email、handlers.call_api），禁止填写任意代码。超管可在 platform_handler_registry 中注册新处理器
Job 状态	仅支持 pending/running/success/failed/timeout/cancelled
trigger_type	仅支持 cron/interval/date/manual

32.4 API 端点

Node（节点）

方法	路径	权限标识	说明
GET	/cronjob/node/detail/{id}	module_task:cronjob:query	节点详情
GET	/cronjob/node/list	module_task:cronjob:query	节点列表
POST	/cronjob/node/create	module_task:cronjob:create	创建节点
PUT	/cronjob/node/update/{id}	module_task:cronjob:update	更新节点
DELETE	/cronjob/node/delete	module_task:cronjob:delete	删除节点
PATCH	/cronjob/node/status/batch	module_task:cronjob:patch	批量设置状态
POST	/cronjob/node/execute/{id}	module_task:cronjob:update	执行节点

Job（执行日志）

方法	路径	权限标识	说明
GET	/cronjob/job/detail/{id}	module_task:cronjob:query	日志详情
GET	/cronjob/job/list	module_task:cronjob:query	日志列表
DELETE	/cronjob/job/delete	module_task:cronjob:delete	删除日志

---

33. Workflow 工作流模块（module_task/workflow）

33.1 业务描述

工作流模块提供可视化流程编排和执行能力。基于 Vue Flow 画布定义流程节点和连线，通过 Prefect 引擎执行。数据按租户隔离。

33.2 数据模型

WorkflowModel（task_workflow，TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(128)	NOT NULL	流程名称
code	String(64)	NOT NULL, UNIQUE(tenant_id, code)	流程编码
workflow_status	String(32)	NOT NULL, default="draft"	状态：draft/published/archived
nodes	JSON	nullable	Vue Flow nodes JSON
edges	JSON	nullable	Vue Flow edges JSON

WorkflowNodeTypeModel（task_workflow_node_type，TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(128)	NOT NULL	显示名称
code	String(64)	NOT NULL, UNIQUE(tenant_id, code)	节点编码，对应画布 node.type
category	String(32)	NOT NULL, default="action"	分类：trigger/action/condition/control
func	Text	NOT NULL	预定义处理器标识符（如 handlers.approve、handlers.send_http）。禁止租户提交任意代码
args	Text	nullable	默认位置参数，逗号分隔
kwargs	Text	nullable	默认关键字参数 JSON
sort_order	Integer	NOT NULL, default=0	排序
is_active	Boolean	NOT NULL, default=True	是否启用

33.3 业务规则

规则	说明
Workflow 编码	字母开头，仅含字母/数字/下划线
Workflow 状态	仅支持 draft（草稿）、published（已发布）、archived（已归档）
NodeType 分类	仅支持 trigger（触发器）、action（动作）、condition（条件）、control（控制）
发布流程	发布时可选备注（remark），由 draft → published
执行流程	需传入 workflow_id 和可选的 variables/business_key/job_id
执行结果	返回 completed/failed 状态及各节点执行结果

33.4 API 端点

Workflow（流程定义）

方法	路径	权限标识	说明
GET	/workflow/flow/detail/{id}	module_task:workflow:query	流程详情
GET	/workflow/flow/list	module_task:workflow:query	流程列表
POST	/workflow/flow/create	module_task:workflow:create	创建流程
PUT	/workflow/flow/update/{id}	module_task:workflow:update	更新流程
DELETE	/workflow/flow/delete	module_task:workflow:delete	删除流程
POST	/workflow/flow/publish/{id}	module_task:workflow:update	发布流程
POST	/workflow/flow/execute/{id}	module_task:workflow:update	执行流程

NodeType（节点类型）

方法	路径	权限标识	说明
GET	/workflow/nodes/detail/{id}	module_task:workflow:query	节点详情
GET	/workflow/nodes/list	module_task:workflow:query	节点列表
POST	/workflow/nodes/create	module_task:workflow:create	创建节点
PUT	/workflow/node-type/update/{id}	module_task:workflow:update	更新节点
DELETE	/workflow/node-type/delete	module_task:workflow:delete	删除节点

---

34. CodeGen 代码生成器模块（module_generator/gencode）

34.1 业务描述

代码生成器模块，通过读取数据库表结构自动生成 CRUD 代码（Python 后端 + Vue 前端 + TypeScript API 层）。支持主子表结构。数据按租户隔离。

34.2 数据模型

GenTableModel（gen_table，TenantMixin, UserMixin）

字段	类型	约束	说明
table_name	String(200)	NOT NULL	数据库表名
table_comment	String(500)	nullable	表描述
class_name	String(100)	NOT NULL	实体类名称
package_name	String(100)	nullable	生成包路径（module_xxx）
module_name	String(30)	nullable	生成模块名
business_name	String(30)	nullable	功能子目录/路由段
function_name	String(100)	nullable	生成功能名
sub_table_name	String(64)	nullable	关联子表的表名
sub_table_fk_name	String(64)	nullable	子表关联的外键名
parent_menu_id	Integer	nullable	父菜单ID

GenTableColumnModel（gen_table_column，TenantMixin, UserMixin）

字段	类型	约束	说明
table_id	FK→gen_table.id	NOT NULL, ON DELETE CASCADE	归属表ID
column_name	String(200)	NOT NULL	列名称
column_comment	String(500)	nullable	列描述
column_type	String(100)	NOT NULL	列类型
column_length	String(50)	nullable	列长度
column_default	String(200)	nullable	列默认值
is_pk	Boolean	NOT NULL, default=False	是否主键
is_increment	Boolean	NOT NULL, default=False	是否自增
is_nullable	Boolean	NOT NULL, default=True	是否允许为空
is_unique	Boolean	NOT NULL, default=False	是否唯一
python_type	String(100)	nullable	Python 类型
python_field	String(200)	nullable	Python 字段名
is_insert	Boolean	NOT NULL, default=True	是否为新增字段
is_edit	Boolean	NOT NULL, default=True	是否编辑字段
is_list	Boolean	NOT NULL, default=True	是否列表字段
is_query	Boolean	NOT NULL, default=False	是否查询字段
query_type	String(50)	nullable	查询方式
html_type	String(100)	nullable, default="input"	显示类型
dict_type	String(200)	nullable, default=""	字典类型
sort	Integer	NOT NULL, default=0	排序

34.3 业务规则

规则	说明
表名校验	table_name/class_name 非空去空白
包名规范	package_name 必须以 module_ 开头
业务名规范	business_name 支持斜杠多段（如 demo/demo01）
同步预览	支持 DB→Gen 差异预览（新增/删除/变更字段）
建表SQL	支持从 CREATE TABLE SQL 导入表结构
模板生成	支持 Python/TS/Vue 三端代码模板（Jinja2）
主子表	通过 sub_table_name/sub_table_fk_name 配置主子表关联

34.4 API 端点

方法	路径	权限标识	说明
GET	/gencode/detail/{id}	module_generator:gencode:query	业务表详情
GET	/gencode/list	module_generator:gencode:query	业务表列表
POST	/gencode/create	module_generator:gencode:create	创建业务表
PUT	/gencode/update/{id}	module_generator:gencode:update	更新业务表
DELETE	/gencode/delete	module_generator:gencode:delete	删除业务表
PATCH	/gencode/status/batch	module_generator:gencode:patch	批量设置状态
GET	/gencode/db/list	module_generator:gencode:query	数据库表列表
POST	/gencode/import	module_generator:gencode:create	导入表结构
POST	/gencode/sync/preview/{id}	module_generator:gencode:query	同步预览
POST	/gencode/sync/{id}	module_generator:gencode:update	同步表结构
POST	/gencode/create/table	module_generator:gencode:create	从SQL建表
POST	/gencode/preview/{id}	module_generator:gencode:query	预览代码
POST	/gencode/zip/{id}	module_generator:gencode:query	下载代码ZIP
POST	/gencode/gen/{id}	module_generator:gencode:update	生成代码到本地
POST	/gencode/current/select	module_generator:gencode:query	切换当前业务表

---

35. Demo 示例模块（module_example/demo）

35.1 业务描述

示例模块，演示 CRUD 标准开发模式和多种数据类型的用法。数据按租户隔离。

35.2 数据模型

DemoModel（example_demo，TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	名称
a	Integer	nullable	整数
b	BIGINT	nullable	大整数
c	Float	nullable	浮点数
d	Boolean	NOT NULL, default=True	布尔型
e	Date	nullable	日期
f	Time	nullable	时间
g	DateTime	nullable	日期时间
h	Text	nullable	长文本
i	JSON	nullable	元数据 JSON

Demo01Model（example_demo01，TenantMixin, UserMixin）

字段	类型	约束	说明
name	String(64)	NOT NULL	名称

35.3 业务规则

规则	说明
名称校验	2-50 位，仅含字母/数字/下划线/中划线
状态校验	仅支持 0(正常)、1(禁用)

35.4 API 端点

方法	路径	权限标识	说明
GET	/example/demo/detail/{id}	module_example:demo:query	详情
GET	/example/demo/list	module_example:demo:query	列表
POST	/example/demo/create	module_example:demo:create	创建
PUT	/example/demo/update/{id}	module_example:demo:update	更新
DELETE	/example/demo/delete	module_example:demo:delete	删除
PATCH	/example/demo/status/batch	module_example:demo:patch	批量设置状态

Demo01

方法	路径	权限标识	说明
GET	/example/demo01/detail/{id}	module_example:demo01:query	详情
GET	/example/demo01/list	module_example:demo01:query	列表
POST	/example/demo01/create	module_example:demo01:create	创建
PUT	/example/demo01/update/{id}	module_example:demo01:update	更新
DELETE	/example/demo01/delete	module_example:demo01:delete	删除
PATCH	/example/demo01/status/batch	module_example:demo01:patch	批量设置状态

---

36. Monitor 监控模块（module_monitor）

36.1 业务描述

监控模块提供系统运行状态的实时监控能力，包括在线用户追踪、Redis 缓存监控、服务器资源监控和文件系统管理。该模块属于平台级功能，不受租户隔离限制，超级管理员可查看所有数据。

36.2 在线用户（online）

36.2.1 业务描述

在线用户监控来自 Redis 存储的会话数据，实时追踪当前登录用户。数据不按租户隔离，超级管理员可查看所有在线用户。

36.2.2 数据模型

OnlineOutSchema（Redis 数据结构）

字段	类型	约束	说明
user_id	int	NOT NULL	用户ID
tenant_id	int	NOT NULL	租户ID
user_name	str	NOT NULL	用户名
name	str	NOT NULL	用户名称
session_id	str	NOT NULL	会话编号
is_super_admin	bool	NOT NULL, default=False	是否超管
ipaddr	str	nullable	登录IP
login_location	str	nullable	登录地
os	str	nullable	操作系统
browser	str	nullable	浏览器
login_time	DateTime	nullable	登录时间
login_type	str	nullable	登录类型(PC/移动)

36.2.3 业务规则

规则	说明
数据来源	数据存储在 Redis，会话过期自动移除
强制下线	超级管理员可强制指定用户下线
清空全部	超级管理员可清空所有在线用户会话

36.2.4 API 端点

方法	路径	权限标识	说明
GET	/monitor/online/list	module_monitor:online:query	在线用户列表
DELETE	/monitor/online/delete	module_monitor:online:delete	强制下线
DELETE	/monitor/online/clear	module_monitor:online:delete	清空所有在线用户

---

36.3 缓存监控（cache）

36.3.1 业务描述

Redis 缓存监控，提供缓存统计信息、缓存名称列表、键值查看和清除功能。数据不按租户隔离，属于平台级功能。

36.3.2 数据模型

CacheMonitorSchema

字段	类型	约束	说明
command_stats	list[dict]	NOT NULL, default=[]	Redis 命令统计
db_size	int	NOT NULL, default=0	Key 总数
info	dict	NOT NULL, default={}	Redis 服务器信息

CacheInfoSchema

字段	类型	约束	说明
cache_key	str	NOT NULL	缓存键名
cache_name	str	NOT NULL	缓存名称
cache_value	Any	nullable	缓存值
remark	str	nullable	备注说明

36.3.3 业务规则

规则	说明
统计信息	获取 Redis 命令统计和服务器信息
键值管理	支持查看和清除指定缓存
批量清除	支持按名称清除和清空所有缓存

36.3.4 API 端点

方法	路径	权限标识	说明
GET	/monitor/cache/info	module_monitor:cache:query	获取缓存监控统计
GET	/monitor/cache/get/names	module_monitor:cache:query	获取缓存名称列表
GET	/monitor/cache/get/keys/{cache_name}	module_monitor:cache:query	获取缓存键名列表
GET	/monitor/cache/get/value/{cache_name}/{cache_key}	module_monitor:cache:query	获取缓存值
DELETE	/monitor/cache/delete/name/{cache_name}	module_monitor:cache:delete	清除指定缓存名称
DELETE	/monitor/cache/delete/key/{cache_key}	module_monitor:cache:delete	清除指定缓存键
DELETE	/monitor/cache/clear	module_monitor:cache:delete	清除所有缓存

---

36.4 资源管理（resource）

36.4.1 业务描述

资源文件管理，提供服务器文件系统的浏览、上传、下载、删除、移动、复制、重命名、创建目录等操作。支持文件列表分页、关键词搜索和 Excel 导出。

36.4.2 数据模型

ResourceItemSchema

字段	类型	约束	说明
name	str	NOT NULL	文件名
file_url	str	NOT NULL	文件URL路径
relative_path	str	NOT NULL	相对路径
is_file	bool	NOT NULL	是否为文件
is_dir	bool	NOT NULL	是否为目录
size	int	nullable	文件大小(字节)
created_time	DateTime	nullable	创建时间
modified_time	DateTime	nullable	修改时间
is_hidden	bool	NOT NULL, default=False	是否隐藏文件

ResourceUploadSchema

字段	类型	约束	说明
filename	str	NOT NULL	文件名
file_url	str	NOT NULL	访问URL
file_size	int	NOT NULL	文件大小
upload_time	DateTime	NOT NULL	上传时间

ResourceMoveSchema

字段	类型	约束	说明
source_path	str	NOT NULL	源路径
target_path	str	NOT NULL	目标路径
overwrite	bool	NOT NULL, default=False	是否覆盖

ResourceRenameSchema

字段	类型	约束	说明
old_path	str	NOT NULL	原路径
new_name	str	NOT NULL, max_length=255	新名称

ResourceCreateDirSchema

字段	类型	约束	说明
parent_path	str	NOT NULL	父目录路径
dir_name	str	NOT NULL, max_length=255	目录名称

36.4.3 业务规则

规则	说明
路径安全	禁止路径遍历(..)，防止越权访问
文件/目录互斥	不能同时为文件和目录
隐藏文件	以 . 开头的文件自动标记为隐藏
分页查询	目录列表支持分页和关键词搜索
上传限制	仅 resource 类型支持指定目标目录
导出功能	支持将资源列表导出为 Excel

36.4.4 API 端点

方法	路径	权限标识	说明
GET	/monitor/resource/list	module_monitor:resource:query	目录列表(分页)
POST	/monitor/resource/upload	module_monitor:resource:upload	上传文件
GET	/monitor/resource/download	module_monitor:resource:download	下载文件
DELETE	/monitor/resource/delete	module_monitor:resource:delete	删除文件
POST	/monitor/resource/move	module_monitor:resource:move	移动文件
POST	/monitor/resource/copy	module_monitor:resource:copy	复制文件
POST	/monitor/resource/rename	module_monitor:resource:rename	重命名文件
POST	/monitor/resource/mkdir	module_monitor:resource:mkdir	创建目录
POST	/monitor/resource/export	module_monitor:resource:export	导出资源列表

---

36.5 服务器监控（server）

36.5.1 业务描述

服务器监控，采集服务器运行时的 CPU、内存、磁盘、Python 进程等信息，供运维人员了解系统资源使用情况。

36.5.2 数据模型

CpuInfoSchema

字段	类型	约束	说明
cpu_num	int	NOT NULL	CPU 核心数
used	float	NOT NULL, 0-100	用户使用率(%)
sys	float	NOT NULL, 0-100	系统使用率(%)
free	float	NOT NULL, 0-100	空闲率(%)

MemoryInfoSchema

字段	类型	约束	说明
total	str	NOT NULL	内存总量
used	str	NOT NULL	已用内存
free	str	NOT NULL	剩余内存
usage	float	NOT NULL, 0-100	使用率(%)

SysInfoSchema

字段	类型	约束	说明
computer_ip	str	NOT NULL	服务器IP
computer_name	str	NOT NULL	服务器名称
os_arch	str	NOT NULL	系统架构
os_name	str	NOT NULL	操作系统
user_dir	str	NOT NULL	项目路径

PyInfoSchema

字段	类型	约束	说明
name	str	NOT NULL	Python 名称
version	str	NOT NULL	Python 版本
start_time	str	NOT NULL	启动时间
run_time	str	NOT NULL	运行时长
home	str	NOT NULL	安装路径
memory_used	str	NOT NULL	内存占用
memory_usage	float	NOT NULL, 0-100	内存使用率(%)
memory_total	str	NOT NULL	总内存
memory_free	str	NOT NULL	剩余内存

DiskInfoSchema

字段	类型	约束	说明
dir_name	str	NOT NULL	磁盘路径
sys_type_name	str	NOT NULL	文件系统类型
type_name	str	NOT NULL	磁盘类型
total	str	NOT NULL	总容量
used	str	NOT NULL	已用容量
free	str	NOT NULL	可用容量
usage	float	NOT NULL, 0-100	使用率(%)

ServerMonitorSchema

字段	类型	约束	说明
cpu	CpuInfoSchema	NOT NULL	CPU 信息
mem	MemoryInfoSchema	NOT NULL	内存信息
py	PyInfoSchema	NOT NULL	Python 信息
sys	SysInfoSchema	NOT NULL	系统信息
disks	list[DiskInfoSchema]	NOT NULL	磁盘信息列表

36.5.3 业务规则

规则	说明
实时采集	每次请求实时采集系统信息
百分比范围	使用率字段限制在 0-100 范围

36.5.4 API 端点

方法	路径	权限标识	说明
GET	/monitor/server/info	module_monitor:server:query	服务器监控信息

---

37. Common 公共模块（module_common）

37.1 业务描述

公共模块提供跨模块复用的基础服务，包括统一文件上传下载、健康检查和指标监控。该模块属于平台级基础设施，不受租户隔离限制。

37.2 文件管理（file）

37.2.1 业务描述

统一文件上传下载服务，支持多种上传类型（通用文件、头像、参数配置、监控资源），支持指定目标目录。预留 Excel 导入功能，待后续实现。

37.2.2 数据模型

上传响应数据

字段	类型	约束	说明
file_name	str	NOT NULL	文件名
file_url	str	NOT NULL	访问URL
file_size	int	NOT NULL	文件大小
upload_time	DateTime	NOT NULL	上传时间

预留：Excel导入字段映射模型（ImportFieldModel）

字段	类型	约束	说明
base_column	str	nullable	数据库字段名
excel_column	str	nullable	Excel 字段名
default_value	str	nullable	默认值
is_required	bool	nullable	是否必传
selected	bool	nullable	是否勾选

预留：Excel导入请求模型（ImportModel）

字段	类型	约束	说明
table_name	str	nullable	目标表名
sheet_name	str	nullable	Sheet 名
filed_info	list[ImportFieldModel]	nullable	字段映射列表
file_name	str	nullable	文件名

37.2.3 业务规则

规则	说明
上传类型	file=通用, avatar=头像, param=参数配置, resource=监控资源
目标目录	仅 resource 类型支持指定 target_path
下载选项	支持下载后自动删除源文件
Excel导入预留	ImportFieldModel 和 ImportModel 为预留功能，当前未实现对应接口

37.2.4 API 端点

方法	路径	权限标识	说明
POST	/file/upload	module_common:file:upload	上传文件
POST	/file/download	module_common:file:download	下载文件

---

37.3 健康检查（health）

37.3.1 业务描述

三级健康检查体系，用于不同场景的健康探测：

• /monitor/health: 基础健康检查（负载均衡器探测）
• /monitor/health/live: 存活探针（K8s livenessProbe）
• /monitor/health/ready: 就绪探针（K8s readinessProbe，检测数据库和 Redis）
• /monitor/health/stream: 健康实时流（SSE；服务端单例快照循环每 30s 一拍，探活成本与连接数无关）

37.3.2 数据模型

健康检查响应

字段	类型	约束	说明
status	str	NOT NULL	healthy/alive/ready/not_ready
timestamp	DateTime	NOT NULL	检查时间戳
version	str	NOT NULL	系统版本
uptime_seconds	float	NOT NULL	运行时间(秒)
dependencies	dict	nullable	依赖检查结果
disk_usage	float	nullable	磁盘使用率(%)

依赖检查结果

字段	类型	约束	说明
database	dict	NOT NULL	数据库状态 {status, latency_ms}
redis	dict	NOT NULL	Redis 状态 {status, latency_ms}

37.3.3 业务规则

规则	说明
基础检查	仅检查进程是否存活，返回 healthy
存活探针	进程已启动即可返回 200
就绪探针	检测数据库和 Redis 连接，失败返回 503
依赖状态	up=正常, down=异常, disabled=已禁用

37.3.4 API 端点

方法	路径	权限标识	说明
GET	/health	—	基础健康检查
GET	/health/live	—	存活探针
GET	/health/ready	—	就绪探针
GET	/health/stream	—	健康实时流（SSE，事件名 health，30s 快照一拍）

---

37.4 指标监控（metrics）

37.4.1 业务描述

Prometheus 指标监控，集成 prometheus-fastapi-instrumentator 自动采集 HTTP 请求指标，暴露 /metrics 端点供 Prometheus 抓取。

37.4.2 采集指标

指标名称	类型	说明
http_requests_total	Counter	HTTP 请求总数（按 method/endpoint/status 分组）
http_request_duration_seconds	Histogram	请求延迟直方图
http_requests_in_progress	Gauge	当前处理中的请求数
http_request_size_bytes	Histogram	请求体大小
http_response_size_bytes	Histogram	响应体大小

37.4.3 排除端点

以下端点不纳入指标采集：

• /metrics: Prometheus 抓取端点
• /health, /health/live, /health/ready: 健康检查端点
• /docs, /redoc, /openapi.json: API 文档
• /static/*, /favicon.ico: 静态资源

37.4.4 API 端点

方法	路径	权限标识	说明
GET	/metrics	—	Prometheus 指标端点

---

Part 5：商业运营模块

---

38. Invoice 发票管理模块

38.1 业务描述

发票管理是中国 B2B SaaS 的法律合规要求。租户在完成订单支付后可申请开具电子发票（增值税普通发票/增值税专用发票），平台审核后对接第三方开票 API（如百望云/票通）生成电子发票，支持下载 PDF。

38.2 发票类型

类型	编码	适用场景	税率
增值税普通发票	vat_normal	个人/小规模纳税人，不可抵扣	1%/3%/6%
增值税专用发票	vat_special	一般纳税人，可抵扣进项税额	6%/13%

38.3 数据模型

platform_invoice

字段	类型	约束	说明
invoice_no	String(32)	NOT NULL, UNIQUE	发票号码（平台自增号）
order_id	FK→platform_order.id	NOT NULL, UNIQUE	关联订单（一单一票）
tenant_id	FK→platform_tenant.id	NOT NULL	开票租户
invoice_type	String(20)	NOT NULL	类型：vat_normal(普票) vat_special(专票)
title	String(200)	NOT NULL	发票抬头（公司全称/个人姓名）
tax_no	String(50)	nullable	纳税人识别号（普票可选，专票必填）
bank_info	Text	nullable	开户行及账号（专票必填）
address_info	Text	nullable	注册地址及电话（专票必填）
amount	Integer	NOT NULL	发票金额（分）
tax_amount	Integer	NOT NULL, default=0	税额（分）
status	Integer	NOT NULL, default=0	0=待开票 1=已开票 2=开票失败 3=已作废
pdf_url	String(500)	nullable	电子发票 PDF 下载地址
api_response	Text	nullable	第三方开票 API 原始响应
remark	Text	nullable	备注

38.4 业务流程

租户申请开票
  ├── POST /tenant/invoice/apply
  │     body: {order_id, invoice_type, title, tax_no?, bank_info?, address_info?}
  ├── 校验：订单已支付(status=1)、未开过票(order_id UNIQUE)
  ├── 专票额外校验：tax_no/bank_info/address_info 必填
  ├── 创建 platform_invoice 记录（status=0 待开票）
  └── 返回申请成功

超管审核开票
  ├── GET /platform/invoice/list（待开票列表）
  ├── PUT /platform/invoice/issue/{id}
  │     ├── 调用第三方开票 API（百望云等）
  │     ├── 成功 → 更新 status=1、pdf_url、api_response
  │     ├── 失败 → 更新 status=2、记录错误信息
  │     └── 通知租户（站内信 + 邮件，含下载链接）
  └── PUT /platform/invoice/void/{id}（发票作废，仅已开票可作废）

38.5 业务规则

规则	说明
一单一票	每个订单仅可开具一张发票（order_id UNIQUE），杜绝重复开票
开票时限	订单支付后 30 天内可申请，超期不再支持（税务合规）
金额匹配	发票金额必须等于订单实付金额
专票校验	增值税专用发票必须填写税号+开户行+地址，缺一不可
第三方对接	对接百望云/票通等电子发票平台，API 调用失败时自动重试 3 次后标记失败
PDF 存储	电子发票 PDF 上传至文件服务（§37.2），按 invoice/{tenant_id}/{invoice_no}.pdf 路径存储
作废规则	当月开具的发票可作废，跨月发票需冲红（暂不支持，预留扩展）

38.6 API 端点

方法	路径	说明	权限
POST	/tenant/invoice/apply	申请开票	租户管理员
GET	/tenant/invoice/list	我的发票列表	租户管理员
GET	/tenant/invoice/{id}/download	下载发票 PDF	租户管理员
GET	/platform/invoice/list	全部发票列表（支持筛选）	超管
PUT	/platform/invoice/issue/{id}	开具发票（调用第三方 API）	超管
PUT	/platform/invoice/void/{id}	作废发票	超管

---

39. AuditLog 租户审计日志模块

39.1 业务描述

记录平台级和租户级的关键管理操作，形成不可篡改的审计轨迹。满足企业内部合规审查、SOC2/ISO27001 认证中的数据追溯要求。审计日志与操作日志（§14）的区别在于：操作日志面向业务操作的查询追踪，审计日志面向合规要求的不可否认性记录。

39.2 操作分类

分类	说明	示例
租户管理	租户生命周期操作	创建/启禁用/冻结/删除/变更套餐
权限变更	角色/菜单/授权操作	角色创建/删除、菜单分配/回收
套餐变更	套餐相关操作	套餐价格修改、套餐菜单变更
支付与退款	财务相关操作	订单创建、退款批准/驳回
发票管理	开票相关操作	开具发票、作废发票
用户邀请	团队管理操作	发送邀请、取消邀请

39.3 数据模型

platform_audit_log

字段	类型	约束	说明
action	String(50)	NOT NULL	操作类型：tenant.create/tenant.package_change/role.delete 等
target_type	String(50)	NOT NULL	操作对象类型：tenant/package/role/order/invoice
target_id	Integer	NOT NULL	操作对象 ID
target_name	String(200)	nullable	操作对象名称（冗余存储，防删除后无法追溯）
tenant_id	FK→platform_tenant.id	nullable	关联租户（平台级操作可为 null）
operator_id	FK→sys_user.id	NOT NULL	操作人
operator_name	String(50)	NOT NULL	操作人名称（冗余）
detail	JSON	NOT NULL	操作详情（变更前/后的关键字段）
ip_address	String(45)	nullable	操作 IP
user_agent	String(500)	nullable	浏览器 UA

设计要点	说明
不可篡改	无 Update/Delete API，仅支持 Insert 和 Read
变更对比	detail JSON 字段存储 {"before": {...}, "after": {...}} 格式的变更对比
冗余存储	target_name/operator_name 冗余存储，确保删除关联数据后仍可追溯
保留策略	默认保留 3 年，超期归档至冷存储（S3/OSS），支持按需导出 CSV/JSON

39.4 审计事件清单

action	target_type	触发场景	detail 示例
tenant.create	tenant	创建租户	{after: {code, name, package_id}}
tenant.status_change	tenant	启禁/冻结/归档	{before: {status}, after: {status}}
tenant.package_change	tenant	变更套餐	{before: {package_id, name}, after: {package_id, name}}
tenant.quota_change	tenant	调整配额	{before: {max_users}, after: {max_users}}
tenant.delete	tenant	删除租户	{before: {code, name, deleted_at}}
package.price_change	package	修改套餐价格	{before: {price}, after: {price}}
package.menu_change	package	变更套餐菜单	{added: [...], removed: [...]}
role.delete	role	删除角色	{before: {name, user_count}}
order.refund_approve	order	批准退款	{order_no, amount, reason}
order.refund_reject	order	驳回退款	{order_no, amount, reject_reason}
invoice.issue	invoice	开具发票	{invoice_no, amount, type}
invoice.void	invoice	作废发票	{invoice_no, reason}
invite.send	invite	发送邀请	{invitee_email, target_role}

39.5 业务规则

规则	说明
全量记录	所有审计事件在业务操作的事务中同步写入，不依赖异步任务（防止丢失）
不可删除	审计日志无 DELETE API，管理员不可手动删除（如需清理需走冷存储归档流程）
权限	仅超管可查阅审计日志，租户端不可见
分页与筛选	支持按 action/target_type/tenant_id/operator_id/时间范围 多条件筛选分页查询
保留策略	定时任务 archive_audit_logs 每月扫描，将 3 年前的日志导出至 OSS 后从主表删除

39.6 API 端点

方法	路径	说明	权限
GET	/platform/audit/list	审计日志列表（支持筛选/分页）	超管
GET	/platform/audit/detail/{id}	审计日志详情	超管
GET	/platform/audit/export	导出审计日志（CSV/JSON）	超管

---

40. Dashboard 运营大盘

40.1 业务描述

平台运营数据可视化看板，基于已有数据（订单/支付/API用量/租户/工单）聚合展示核心运营指标，帮助超管快速掌握平台健康状况。

40.2 核心指标

指标	数据源	说明
租户总数	platform_tenant	按状态分布（active/suspended/expired）
本月新增租户	platform_tenant	按月统计新建租户数
今日活跃租户	platform_api_usage_daily	当日有 API 调用的租户数
月收入（MRR）	platform_order	status=1 订单按月汇总金额
退款率	platform_refund	退款金额/总收入 × 100%
API 调用总量	platform_api_usage_daily	按天/月聚合调用次数
待处理工单数	platform_ticket	status=0/1 的工单数量
套餐分布	platform_tenant JOIN platform_package	各套餐租户数量（饼图）
收入趋势	platform_order	近 12 个月收入折线图

40.3 API 端点

方法	路径	说明	权限
GET	/platform/dashboard/overview	运营概览（总览数据）	超管
GET	/platform/dashboard/revenue	收入趋势（按月）	超管
GET	/platform/dashboard/tenants	租户统计	超管
GET	/platform/dashboard/api-usage	API 用量趋势	超管

---