BitzOrcas Suite 可视化架构工作台

在领域驱动设计（DDD）与整洁架构（Clean Architecture）的规模化工程实践中，研发团队通常在两种极端之间反复拉扯：

1. 纯代码驱动的机械消耗：实现一个包含状态机与租户隔离的业务聚合根，开发者需要在 Domain（聚合根、枚举、不变量）、Contracts（CQRS 命令、查询 DTO）、Application（命令处理器、验证器）和 Infrastructure（持久化实体、EF Core / SqlSugar 映射、仓储实现）四个工程中手动创建十几个样板文件。稍有疏忽，导航属性配置错误或外键命名偏差只能推迟到集成测试或数据库迁移崩溃时才暴露；
2. 重型低代码平台的黑盒失控：许多试图解决样板代码的商业可视化工具采用封闭式代码生成器，生成高度耦合且难以审查的胶水代码，剥夺了资深工程师对核心领域模型与 SQL 物理执行计划的微观控制权。

BitzOrcas Suite（通过命令 bitz suite 或 bitz suite --web 启动）是面向企业微内核架构研发的轻量级本地可视化架构工作台。它并非替代代码编写的黑盒系统，而是作为开发者的架构副驾驶（Architecture Co-Pilot）：在内存中完成领域建模、实时渲染 VFS（虚拟文件系统）代码差异、可视化验证实体拓扑与 SQL Server / PostgreSQL DDL 语句，并在审阅确认后原子落盘到真实的物理解决方案中。

架构体系与通信机制

BitzOrcas Suite 拒绝了动辄数百兆运行时代价的重型 Electron 壳应用方案，而是采用无外部依赖的嵌入式微内核架构：

关键工程权衡（Trade-offs）

1. 零安装负担 vs 丰富交互： 前端单页应用（SPA）在编译期打包为高压缩静态资源，通过 <EmbeddedResource> 直接内嵌至 BitzOrcas.Cli.dll 中。用户无需安装 Node.js、npm 或任何额外组件，单文件即可运行；
2. 回环安全隔离（Loopback Security）： 本地 HTTP 服务严格仅绑定 127.0.0.1，拒绝一切公网或局域网访问；每次启动生成高强度加密一次性安全令牌（Token），杜绝同机其他恶意进程通过本地端口嗅探或篡改代码；
3. 内存级 VFS 防污染（Virtual File System）： 所有实体建模与切片生成优先在内存中组装，结合 Roslyn 语法分析器实施即时诊断。未通过原子确认前，绝不向磁盘写入任何文件，保障 Git 工作区清洁。

核心工作台功能深度解析

1. 实体建模与属性网格设计器

工作台提供了符合企业级数据建模标准的实体设计器，支持定义字段名称、C# 强类型、可空标识、长度约束、精度标度以及业务描述：

核心能力支持

• 类型自动推导与约束补齐：选择 string 类型自动激活最大长度约束；选择 decimal 类型提供精度与标度校验；
• 微内核架构特性开关：一键声明「多租户隔离（TenantAggregateRoot<T>）」与「软删除过滤（ISoftDelete）」；
• 智能主键生成策略：内置 Twitter Snowflake（雪花算法）分布式递增主键规范，统一主键为 long 或 string，规避数据库自增 ID 的分表分库瓶颈。

2. 内存级切片生成与 Monaco Diff 差异审阅

在设计器完成属性定义后，点击顶部「生成并审阅」或快捷键，即可切换至代码审阅视窗。Suite 会调用内核 Scriban 模板引擎在内存中生成全套代码，并提取物理磁盘中的现有文件生成精确的双栏比对：

审阅视窗特性

• 智能单双屏分流：新增文件自动使用单屏 Monaco 语法高亮视图；已有物理文件的修改自动切换至 Monaco 双栏 Diff 视图；
• 全屏沉浸开发模式：支持点击右上角全屏展开，左侧切片文件树与右侧编辑器并列铺满全屏，支持 Esc 键一键退出；
• 原子写入二次确认（防呆机制）：落盘前弹出模态框，直观汇总本次将变更的物理文件清单与变更类型，要求开发者二次确认以防止误覆盖。

3. 多方言 DDL 预览与 ORM 迁移代码生成

数据底座的稳定性决定了生产系统的可靠性。Suite 内置了生产级 DDL 迁移生成器，满足不同数据库选型的落地需求：

迁移脚本特性

• 完整 SQL Server 注释生成：使用 sys.sp_addextendedproperty 存储过程为表名、雪花主键列、租户 ID 列、审计列（CreatedAt, CreatedBy 等）及业务列添加中文扩展属性；
• 多数据库方言支持：一键切换生成 PostgreSQL（带 COMMENT ON COLUMN 与部分软删除索引）、MySQL 8.0+ 以及 SQL Server DDL；
• 双 ORM 映射同源物化：基于 [BitzTable] 与 [BitzColumn] 元数据同步生成 EF Core IEntityTypeConfiguration<T> 与 SqlSugar 实体映射配置，杜绝双 ORM 配置漂移；
• 工业级弹窗交互：支持按住弹窗头部自由拖拽位移，支持双击头部或点击最大化按钮铺满屏幕进行长脚本审阅。

4. 领域实体关系拓扑图 (ER Diagram)

Suite 会解析选定模块中的全部聚合根与实体定义，动态构建拓扑依赖关系：

交互与导出能力

• 以光标为锚点的平滑缩放（Zoom-towards-cursor）：鼠标滚轮缩放时自动计算视口偏移补偿，光标所指位置保持稳定，彻底告别跳跃式缩放；
• 多格式导出与交付：
  • Retina 2x PNG：根据节点与连线精确计算包围盒，离屏 Canvas 高清采样导出；
  • W3C 标准 SVG：导出独立矢量图，可直接嵌入架构设计汇报或 Wiki 文档；
  • Mermaid 脚本复制：一键提取标准 Mermaid erDiagram 代码并复制到剪贴板。

5. Git 物理提交时间轴与多维检索

在「模块全景概览」面板中，Suite 提供了对齐 JetBrains Rider 与 GitKraken 的高密度版本追踪体验：

检索与排版维度

• 5 大全文检索维度：支持「全部 (All)」、「Commit ID」、「主题说明 (Subject)」、「提交正文 (Body)」与「提交人 (Author)」精准检索；
• Conventional Commits 语义过滤：智能解析 feat, fix, refactor, test, chore 等前缀，提供彩色胶囊快速分类过滤；
• 双模式时间线：支持「按日期分组（今天、昨天、具体日期分类折叠）」与「扁平高密度列表」切换；
• 一键复制完整 Commit ID：所有 Commit ID 显示处均支持点击复制完整 40 位 SHA 哈希。

6. Git 修改代码对比抽屉 (Commit Diff Drawer)

点击任意历史提交的「查看对比」按钮，即可唤起全局提交对比抽屉：

抽屉交互架构

• Portal 根挂载 (z-[100])：采用 React createPortal 直接挂载至 document.body，彻底摆脱父级容器 Stacking Context 限制，头部工具条完整可见，绝不被 Studio Header 遮挡；
• 默认开阔视野（第二宽预设）：默认 Preset 设为 'wide'，宽度动态计算为 calc(100vw - 280px)，精准对齐左侧解决方案菜单边沿，提供最大化的双栏对比视野；
• 左侧文件列表导轨化：
  • 点击收起按钮可将文件列表折叠为 36px 垂直语义导轨，将 100% 宽度让渡给 Monaco Diff；
  • 右边缘支持鼠标拖拽，可在 200px ~ 600px 之间自由拉伸列表宽度。

7. 代码详情与逆向工程抽屉 (File Inspector Drawer)

在左侧解决方案树或模块概览中点击任意源码文件，即可在右侧滑出深度审阅抽屉：

规范控制与实体语义化

• 对齐 BitzOrcas Design System 1.2 视窗规范 (OperationWindowControls)：
  • 停靠方位切换：支持右侧停靠与底部停靠无缝切换；
  • 4 档微缩预设：提供纯 CSS 微缩示意图标，支持 25% (narrow)、45% (standard)、70% (wide)、100% (full) 快速切换；
• 三级实体语义徽标精准识别：
  • 聚合根（青色徽标）：继承自 TenantAggregateRoot<T> 的领域统一聚合根；
  • 实体（绿色徽标）：继承自 Entity<T> 的领域从属业务实体；
  • PO（紫色徽标）：严格限定于 Persistence 层的持久化数据模型（如 *Po.cs）；
• Roslyn C# 逆向同步建模：打开任意既有实体 .cs 源码，点击右上角「同步建模」，系统将自动解析类结构、属性与特性，直接反向填充至实体设计器表单中。

领域实战案例：法律科技案件收案与费用切片

以下是使用 BitzOrcas Suite 设计并生成的真实 LegalTech 业务切片示例，严格遵循四层整洁架构与统一聚合根规范：

领域聚合根定义 (MatterIntake.cs)

namespace BitzOrcas.LegalTech.Domain.MatterIntakes;

using System;
using System.ComponentModel;
using BitzOrcas.Domain.Entities;
using BitzOrcas.Domain.Results;
using BitzOrcas.Domain.Tenancy;
using BitzOrcas.Persistence.Metadata;

/// <summary>
/// 案件收案登记聚合根（兼任持久化模型与业务聚合边界，杜绝 1:1 贫血实体膨胀）
/// </summary>
[BitzTable("LegalMatterIntake", IsTenant = true, IsSoftDelete = true, Description = "案件收案登记聚合根")]
public sealed class MatterIntake : TenantAggregateRoot<string>
{
    /// <summary>
    /// 案件唯一业务案号（编码规则自动由 Numbering 平台能力生成）
    /// </summary>
    [BitzColumn(Length = 64, IsRequired = true, Description = "案件唯一业务案号")]
    public string MatterCode { get; private set; } = string.Empty;

    /// <summary>
    /// 案件标题与委托人全称
    /// </summary>
    [BitzColumn(Length = 200, IsRequired = true, Description = "委托人全称")]
    public string ClientName { get; private set; } = string.Empty;

    /// <summary>
    /// 涉案预估标的金额（严格采用 decimal(18,2) 并指定数值精度）
    /// </summary>
    [BitzColumn(Precision = 18, Scale = 2, IsRequired = true, Description = "涉案预估标的金额")]
    public decimal EstimatedAmount { get; private set; }

    /// <summary>
    /// 利益冲突审查状态（已通过、待人工复核、存在冲突阻断）
    /// </summary>
    [BitzColumn(IsRequired = true, Description = "利益冲突审查状态")]
    public ConflictCheckStatus ConflictStatus { get; private set; }

    /// <summary>
    /// 仅供 ORM 持久化物化使用的无参构造
    /// </summary>
    [Obsolete("仅供 ORM 持久化物化使用。请使用 Create 工厂方法。", error: true)]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public MatterIntake() : base("0") { }

    private MatterIntake(
        string id,
        string tenantId,
        string matterCode,
        string clientName,
        decimal estimatedAmount) : base(id)
    {
        TenantId = tenantId;
        MatterCode = matterCode;
        ClientName = clientName;
        EstimatedAmount = estimatedAmount;
        ConflictStatus = ConflictCheckStatus.PendingReview;
    }

    /// <summary>
    /// 领域行为工厂方法：确保在创建之初满足业务完整性不变量
    /// </summary>
    public static Result<MatterIntake> Create(
        string? tenantId,
        string? matterCode,
        string? clientName,
        decimal estimatedAmount)
    {
        if (string.IsNullOrWhiteSpace(tenantId) || !TenancyDefaults.IsValid(tenantId))
        {
            return Result<MatterIntake>.Failure(MatterIntakeErrors.TenantRequired);
        }

        if (string.IsNullOrWhiteSpace(matterCode))
        {
            return Result<MatterIntake>.Failure(MatterIntakeErrors.MatterCodeRequired);
        }

        if (string.IsNullOrWhiteSpace(clientName))
        {
            return Result<MatterIntake>.Failure(MatterIntakeErrors.ClientNameRequired);
        }

        if (estimatedAmount < 0)
        {
            return Result<MatterIntake>.Failure(MatterIntakeErrors.EstimatedAmountInvalid);
        }

        return Result<MatterIntake>.Success(new MatterIntake(
            Guid.NewGuid().ToString("N"),
            tenantId,
            matterCode.Trim(),
            clientName.Trim(),
            estimatedAmount));
    }
}

/// <summary>
/// 案件收案模块强类型错误字典
/// </summary>
public static class MatterIntakeErrors
{
    public static readonly Error TenantRequired = Error.Unauthorized("Legal.Matter.TenantRequired", "租户标识缺失或非法。");
    public static readonly Error MatterCodeRequired = Error.Validation("Legal.Matter.MatterCodeRequired", "案件案号不能为空。");
    public static readonly Error ClientNameRequired = Error.Validation("Legal.Matter.ClientNameRequired", "委托人全称不能为空。");
    public static readonly Error EstimatedAmountInvalid = Error.Validation("Legal.Matter.EstimatedAmountInvalid", "预估标的金额不能为负数。");
}

CLI 启动命令与运行模式速查

Suite 提供了灵活的命令行参数，适应本地交互、脚本调用及远程部署等多种场景：