系统对象架构与命名规范统一升级提案

[hotlong]

系统对象架构与命名规范统一提案

背景

本项目目前存在系统对象、系统设置相关的元数据、API、权限、命名多处定义分散与不一致的问题：

• 系统对象（如 user、role、org、audit_log 等）目前部分定义在 plugin-auth、部分定义在 plugin-security、部分为业务层（objectui）手动副本。
• 命名规范混乱：对象名、表名、文件名、API 路由、权限声明等未有统一设计。
• 不同插件/包之间的对象导出、注册与消费方式不一致。

这导致：

• 元数据冗余，定义难以追踪、维护。
• 新增/变更系统对象时需多处同步，易产生技术债。
• 消费端（前端与 API client）难以一致性消费和自动生成界面。
• 权限声明、事件、路由等常因命名不统一出现混乱。

长期统一架构方案提案

1. 系统对象统一归属与结构

• 在 objectstack-ai/spec 项目的系统插件层（如 plugin-auth、plugin-security、plugin-audit），所有系统对象统一在 objects 文件夹以 ObjectSchema 定义。
• 每个对象设定 namespace: 'sys'，如：

  export const SysUser = ObjectSchema.create({
    namespace: 'sys',
    name: 'user',
    tableName: 'sys_user',
    // ...
  });

• 新增/补齐对象：
  • sys_user、sys_account、sys_session、sys_verification、sys_org、sys_member、sys_invitation, sys_api_key （plugin-auth, better-auth 内核和插件用到的所有对象）。
  • sys_role、sys_permission_set（plugin-security）。
  • sys_audit_log（新建 plugin-audit）。
  • 等，如有需求补充。
• 文件命名全部采用 sys-{name}.object.ts，如 sys-user.object.ts、sys-role.object.ts。
• 导出常量全部采用 PascalCase，如 SysUser、SysRole。

2. 命名规范分层与自动推导

• ObjectSchema 层：
  • namespace: 'sys' —— 消费者视角分类统一。
  • name: 'user' —— 逻辑标识，snake_case，不带前缀。
  • tableName: 'sys_user' —— 物理表名，自动推导：{namespace}_{name}，减少手动冗余。
• 文件名：sys-{name}.object.ts（全部系统对象统一化）。
• 路由与 API：前端统一 /system/{name}，API /api/v1/objects?namespace=sys。
• 权限声明、事件类型、关联关系也统一以 sys::{name} 进行辨识和管理。
• 消费方无需关心对象来源插件，全部系统对象都属于 sys 域。

3. 架构分包与对象注册

• 保持插件分包：plugin-auth、plugin-security、plugin-audit 等分别注册自己的系统对象（sys 域），避免合并为单一包，保证内聚、可选、解耦。
• 每个插件注册时，按 namespace 归类，消费端自动聚合。
• 补齐所有遗失的 ObjectSchema 层定义，不再允许只写 Zod/schema 或手动前端副本。

Ω

收益与影响

• 彻底解耦对象名与表名、文件名、插件归属，追求长期维护与自动化的可扩展能力。
• 系统对象一眼可见、零冗余，新增/变更只需一处。
• 路由、权限声明、API、界面渲染全平台统一，消除技术债。
• 推动平台架构与成熟 SaaS/企业平台看齐（Salesforce/Strapi/Payload 的对象体系）。
• 为未来自动生成、批量运维、对象 discovery，和 DSL/低代码场景打下基本盘。

需要执行的具体工程任务

1. 在各系统插件补齐所有系统对象 ObjectSchema 并统一命名。
2. 扩展 ObjectSchema 协议，明确 namespace/tableName 自动推导规范。
3. 改造对象注册流程 plugin 内统一归档。
4. 前端同步全量消费 sys namespace 对象。
5. 路由、权限、事件等所有系统对象管理统一。
6. 升级文档、ROADMAP，并记录 breaking change。

附加参考资料

• plugin-auth 对象定义示例
• plugin-security RBAC 权限模型
• 系统对象命名规范调整建议

---

建议本议题为平台长期唯一的系统对象与命名规范架构方案指导，所有相关改动或讨论均以此 issue 为准。