mirror of https://gitee.com/zoujingli/ThinkAdmin.git synced 2026-06-07 04:28:11 +08:00

Anyon 6f4056f64d docs(architecture): 完善 v8 架构与迁移说明

补充 v8 重构后的架构文档、组件说明和迁移记录，方便后续维护者理解插件边界。

主要内容：

- 更新根 README，说明 v8 插件分层、系统模块、交付命令和验证流程。

- 新增组件明细、插件边界、路由分发、软删除和稳定性文档。

- 记录 Storage 合并到 System、旧 View 移除和 Helper 并入 System 的决策。

- 补充文档注释报告和后续重构计划，便于持续演进。

2026-05-08 15:31:22 +08:00

9.9 KiB

Raw Blame History

System Module Refactor Plan

目标

基于当前 think-library 的 FormBuilder / PageBuilder 重构 System 模块。
以控制器注释为 RBAC 权限源头，数据库只保存同步后的角色、节点、菜单和用户授权关系。
在重构阶段允许直接调整 System 主安装脚本字段，并通过新库重建验证结果。
为后续其他插件重构建立统一的数据库脚本命名、Builder 分层和字段命名规范。

当前结论

1. Builder 体系

不恢复旧的动态 Builder 模块。
当前 System 模块已经在使用新的 Controller + Service + Builder 结构。
现阶段应该继续复用：
- plugin/think-library/src/builder/form/*
- plugin/think-library/src/builder/page/*
- plugin/think-plugs-system/src/builder/*

2. RBAC 体系

节点来源于控制器注释扫描。
当前约定已经存在：
- @auth true 表示权限节点
- @menu true 表示菜单节点
- @login true 表示仅登录可访问
运行时节点解析当前由 think\admin\service\NodeService 完成。

3. 数据库脚本约束

plugin/think-plugs-system/stc/database/20241010000001_install_system20241010.php 是 System 主维护源。
根目录 database/migrations/*.php 视为发布产物，不是主维护源。
每个插件只保留一个主安装脚本，不在重构期间增加多份临时 install 脚本。

重构范围

第一批

Auth
User
Menu

第二批

Base
Config
File

第三批

Queue
Oplog
Plugin
Index
Login

统一设计原则

1. Source of Truth

权限节点来源：控制器注释
插件菜单来源：插件 composer.json > extra.xadmin.menu
系统菜单来源：数据库中的运行时配置和覆盖
角色授权来源：角色与节点关系表
用户授权来源：用户与角色关系表

2. 分层职责

Controller 只负责输入输出、Builder 响应和异常转换
Service 负责业务编排、同步逻辑、字段适配和约束校验
Builder 负责页面结构、表单结构和前端交互装配
Model 只保留领域对象、关联和必要的属性转换

3. 命名原则

外键统一使用 *_id
时间字段统一使用 create_time / update_time / delete_time
状态字段统一使用 status
备注字段统一使用 remark
URL/路由字段区分：
- route_path 表示站内路由
- link_url 表示完整外链
JSON 字段只存结构化数据，不再混存纯文本和结构对象

目标数据模型

Phase 1 落地说明

第一批 Auth / User / Menu 当前采用兼容式字段重命名方案，优先保证现有页面、测试和安装脚本能平滑过渡。

第一批优先落地字段：

system_auth.code
system_auth.remark
system_user.base_code
system_user.auth_ids
system_user.remark

第一批暂不强制引入新的用户角色关系表，避免一次性改动过大。system_user_auth 保留为第二阶段可选增强。

1. system_auth

定位：角色定义表

建议保留表名，调整字段语义。

建议字段：

id
code：角色编码，唯一
title：角色名称
remark：角色说明
sort
status
create_time
update_time

当前问题：

utype 语义不清
desc 命名不统一
缺少角色编码字段

处理建议：

删除或废弃 utype
desc 统一为 remark
新增 code

2. system_auth_node

定位：角色与权限节点关系表

建议字段：

id
auth_id
node_code
plugin_code
create_time

当前问题：

auth 命名不清晰
node 缺少领域表达
无法直接表达插件归属

处理建议：

auth -> auth_id
node -> node_code
增加 plugin_code

3. system_user

定位：系统后台用户表

建议字段：

id
username
password
nickname
avatar
identity_code
contact_phone
contact_mail
contact_qq
login_ip
login_time
login_num
remark
sort
status
create_time
update_time
delete_time

当前问题：

authorize 用逗号串保存角色编号，扩展性差
headimg、describe 为历史命名
login_at 当前是字符串时间
缺少 update_time

处理建议：

删除 authorize，改为独立关联表
headimg -> avatar
describe -> remark
login_at -> login_time
增加 update_time

4. system_user_auth

定位：用户与角色关系表

这是第二阶段可选增强表，不作为第一批强制落地点。

建议字段：

id
user_id
auth_id
create_time

价值：

替代 system_user.authorize 的逗号串模式
便于多角色扩展、审计、筛选和后续插件授权复用

5. system_menu

定位：系统后台菜单表

建议字段：

id
parent_id
plugin_code
source_type
source_code
title
icon
route_path
link_url
auth_node
query_params
target
sort
status
create_time
update_time

当前问题：

pid 命名是历史风格
url 同时承载站内路由和外链
node 与 url 职责交叉
params 只是字符串

处理建议：

pid -> parent_id
拆分 url 为 route_path / link_url
node -> auth_node
params -> query_params
增加 plugin_code / source_type / source_code

6. system_base

定位：系统数据字典表

建议字段：

id
type
code
name
text_value
meta_json
sort
status
create_time
update_time
delete_time
deleted_by

当前问题：

content 同时保存纯文本和 JSON 元数据
插件归属通过 content 间接表达，不利于约束

处理建议：

将内容拆分为文本值和元数据
插件归属等扩展信息只进入 meta_json

7. system_data

定位：系统分组配置表

建议字段：

id
name
value
create_time
update_time

当前结论：

这张表结构可以暂时保留
重点是确保 value 只保存结构化 JSON

8. system_file

定位：系统文件与存储记录表

建议字段：

id
storage_type
file_hash
tags
file_name
extension
file_url
storage_key
mime_type
file_size
system_user_id
biz_user_id
is_fast_upload
is_safe
status
create_time
update_time

当前问题：

xext / xurl / xkey 为历史命名
uuid / unid 不利于理解
字段语义和业务语义脱节

处理建议：

历史字段全部改成业务化命名
文件表作为第二批落地

9. system_oplog

定位：操作日志表

建议字段：

id
node_code
request_ip
action
content
username
create_time

当前问题：

geoip 实际存的是 IP，不是地理信息

处理建议：

geoip -> request_ip

RBAC 重构目标

1. 节点同步

扫描控制器注释
生成标准节点树
识别插件归属
写入角色节点授权关系
刷新节点缓存

2. 菜单同步

插件声明的菜单作为静态源
system_menu 作为运行时覆盖层
后台手工新增菜单只作为 custom 来源处理

3. 权限判断顺序

超级管理员直接放行
判断登录态
判断节点是否需要授权
判断用户关联角色
判断角色是否命中节点

Builder 重构目标

1. 公共 Builder 资产

SystemListPage
SystemListTabs
SystemTablePreset
公共的模块化表单片段

2. 第一批要抽离的交互

权限树筛选与选择
用户角色分组选择
菜单路由/权限节点自动补全
系统配置中的主题选择和存储驱动选择

3. 输出要求

保持 HTML 渲染可用
保持 Builder JSON 渲染可用
避免在模板中继续回退到旧式条件模板和拼接式脚本

实施顺序

Phase 1: 结构冻结

输出字段改造清单
输出目标表结构
输出脚本命名规范
确认第一批改造对象为 Auth / User / Menu

Phase 2: 数据库脚本重写

直接修改 System 主安装脚本
第一批先完成兼容式字段替换
更新测试里的 SQLite 建表定义
使用新库重建验证安装结果

Phase 3: 模型与 Service 适配

更新 SystemAuth
更新 SystemUser
更新 SystemMenu
新增 SystemUserAuth
把历史字段兼容逻辑收敛到 Service 层

Phase 4: Builder 与控制器重构

先改 Auth
再改 User
再改 Menu
完成角色、用户、菜单三条链路联调

Phase 5: 第二批模块落地

重构 Base
重构 Config
重构 File

Phase 6: 收尾

清理旧字段兼容逻辑
更新文档和测试
重新发布 database/migrations

数据库脚本命名规范

主安装脚本

目录：plugin/<plugin>/stc/database/
模式：{version}_install_{plugin_code}{date}.php
plugin_code 统一使用 snake_case

示例：

20241010000001_install_system20241010.php
20241010000009_install_wechat_service20241010.php

当前阶段规则

System 模块允许直接修改主 install 脚本
不新增第二份 install 脚本
根目录迁移文件通过发布流程重建

验收标准

新库可直接安装 System 模块
注释扫描可以生成 RBAC 节点
用户、角色、菜单权限关系闭环可用
Auth / User / Menu 页面同时支持 HTML 和 Builder JSON
第一批模块测试可通过
第二批模块不会继续引入历史字段命名

下一步

第一轮实施直接从下面三项开始：

改造 system_auth / system_auth_node / system_user / system_menu
更新 System 主安装脚本与 SQLite 测试表结构
重做 Auth / User / Menu 的 Model、Service、Builder 和控制器适配

当前进度

截至当前工作区状态，第一批已经采用以下字段重命名方向推进：

system_auth.utype -> code
system_auth.desc -> remark
system_user.usertype -> base_code
system_user.authorize -> auth_ids
system_user.describe -> remark

并且 Auth / User / Menu 相关测试已经可以通过。

9.9 KiB Raw Blame History Unescape Escape

System Module Refactor Plan

目标

当前结论

1. Builder 体系

2. RBAC 体系

3. 数据库脚本约束

重构范围

第一批

第二批

第三批

统一设计原则

1. Source of Truth

2. 分层职责

3. 命名原则

目标数据模型

Phase 1 落地说明

1. system_auth

2. system_auth_node

3. system_user

4. system_user_auth

5. system_menu

6. system_base

7. system_data

8. system_file

9. system_oplog

RBAC 重构目标

1. 节点同步

2. 菜单同步

3. 权限判断顺序

Builder 重构目标

1. 公共 Builder 资产

2. 第一批要抽离的交互

3. 输出要求

实施顺序

Phase 1: 结构冻结

Phase 2: 数据库脚本重写

Phase 3: 模型与 Service 适配

Phase 4: Builder 与控制器重构

Phase 5: 第二批模块落地

Phase 6: 收尾

数据库脚本命名规范

主安装脚本

当前阶段规则

验收标准

下一步

当前进度

9.9 KiB

Raw Blame History