1165 lines
25 KiB
Markdown
1165 lines
25 KiB
Markdown
# 企业级目标业务架构文档
|
|
|
|
本文档定义的是本项目后续重构应对齐的**目标态企业级业务架构**。
|
|
如果当前实现与本文档不一致，以本文档作为未来架构和业务规则的基线。
|
|
|
|
本文档只讨论：
|
|
|
|
- 业务目标
|
|
- 领域划分
|
|
- 核心业务对象
|
|
- 模块职责
|
|
- 核心流程
|
|
- 统一业务规则
|
|
- 状态定义与状态流转
|
|
- 权限模型
|
|
|
|
本文档不讨论：
|
|
|
|
- 实施计划
|
|
- 任务排期
|
|
- 测试清单
|
|
- 当前实现细节的迁移步骤
|
|
|
|
## 1. 文档目标与适用范围
|
|
|
|
### 1.1 文档目标
|
|
|
|
这份文档用于建立一个可长期演进的企业级业务架构基线，使后续开发、重构、测试设计和 Code Review 都围绕同一套业务语义进行，而不是继续围绕局部实现细节做增量修补。
|
|
|
|
### 1.2 适用范围
|
|
|
|
本文适用于以下业务域：
|
|
|
|
- 身份与访问控制
|
|
- 用户工作空间
|
|
- 文件内容资产
|
|
- 分享与外部分发
|
|
- 快传
|
|
- 后台任务
|
|
- 存储治理
|
|
- 运营与管理
|
|
|
|
## 2. 系统定位
|
|
|
|
系统定位为：
|
|
|
|
**以个人和组织成员文件资产为中心的统一文件服务平台**
|
|
|
|
平台的核心价值不是“存文件”本身，而是：
|
|
|
|
1. 统一身份
|
|
2. 统一文件资产模型
|
|
3. 统一分享与传输能力
|
|
4. 统一治理、审计和存储策略
|
|
|
|
平台面向三类对象：
|
|
|
|
- 最终用户
|
|
- 运营/支持人员
|
|
- 系统管理员
|
|
|
|
## 3. 架构原则
|
|
|
|
### 3.1 业务规则必须有唯一归属
|
|
|
|
每一条核心业务规则都必须有唯一归属域，不允许在多个 Service、多个控制器或多个前端页面中各自实现一套。
|
|
|
|
### 3.2 逻辑文件与物理内容分离
|
|
|
|
用户看到的文件、目录、分享、回收站等都属于**逻辑资产层**。
|
|
对象存储中的字节内容、版本、缩略图、转码产物等属于**内容资产层**。
|
|
|
|
### 3.3 权限模型独立于页面和接口
|
|
|
|
权限必须由统一授权模型决定，而不是由页面入口、控制器路径或配置白名单临时拼接。
|
|
|
|
### 3.4 同类能力统一入口
|
|
|
|
分享、上传、后台任务、管理设置等同类能力必须有统一入口和统一语义，不允许长期双轨并存。
|
|
|
|
### 3.5 业务状态优先于技术状态
|
|
|
|
系统对外表达的状态必须是业务状态，而不是底层实现状态的直接暴露。
|
|
|
|
### 3.6 删除是业务动作，不是物理动作
|
|
|
|
删除、恢复、过期清理必须服从业务生命周期，不允许把物理对象操作直接等同于业务删除。
|
|
|
|
## 4. 角色模型
|
|
|
|
目标态采用四层角色模型：
|
|
|
|
- `VISITOR`
|
|
- `MEMBER`
|
|
- `OPERATOR`
|
|
- `ADMIN`
|
|
|
|
### 4.1 `VISITOR`
|
|
|
|
定义：
|
|
|
|
- 未登录访问者
|
|
|
|
可执行：
|
|
|
|
- 访问公开分享
|
|
- 接收公开可接收的传输会话
|
|
|
|
不可执行：
|
|
|
|
- 访问个人工作空间
|
|
- 创建需要归属主体的业务对象
|
|
- 执行管理操作
|
|
|
|
### 4.2 `MEMBER`
|
|
|
|
定义：
|
|
|
|
- 普通登录用户
|
|
|
|
可执行：
|
|
|
|
- 管理自己的工作空间
|
|
- 上传、下载、删除、恢复、复制、移动、重命名自己的文件
|
|
- 创建和管理自己的分享
|
|
- 创建和管理自己的传输会话
|
|
- 导入外部文件到自己的工作空间
|
|
- 查看和管理自己的后台任务
|
|
|
|
### 4.3 `OPERATOR`
|
|
|
|
定义：
|
|
|
|
- 运营或支持角色
|
|
|
|
职责：
|
|
|
|
- 处理支持型治理工作
|
|
- 查看全局业务对象
|
|
- 处理受控的运营动作
|
|
|
|
限制：
|
|
|
|
- 不直接拥有系统级配置权限
|
|
- 不直接替代系统管理员
|
|
|
|
### 4.4 `ADMIN`
|
|
|
|
定义：
|
|
|
|
- 系统治理角色
|
|
|
|
职责：
|
|
|
|
- 管理系统级策略、权限、存储、任务与全局设置
|
|
|
|
### 4.5 角色模型规则
|
|
|
|
- 角色是授权模型的一部分，不是页面装饰字段
|
|
- 所有管理能力必须绑定 `OPERATOR` 或 `ADMIN`
|
|
- 工作空间资源的所有权规则优先于角色扩权
|
|
- 高风险管理动作必须具备审计记录
|
|
|
|
## 5. 领域划分
|
|
|
|
目标态系统划分为八个核心业务域。
|
|
|
|
### 5.1 身份与访问控制域
|
|
|
|
职责：
|
|
|
|
- 注册
|
|
- 登录
|
|
- 会话管理
|
|
- 令牌刷新
|
|
- 账号状态
|
|
- 角色授权
|
|
- 邀请码控制
|
|
|
|
产出对象：
|
|
|
|
- 账号
|
|
- 会话
|
|
- 角色
|
|
- 授权上下文
|
|
|
|
### 5.2 用户工作空间域
|
|
|
|
职责：
|
|
|
|
- 管理用户视角下的目录树
|
|
- 管理逻辑文件节点
|
|
- 管理回收站生命周期
|
|
- 管理工作空间内的复制、移动、重命名、恢复
|
|
|
|
产出对象：
|
|
|
|
- 工作空间
|
|
- 工作空间节点
|
|
- 回收站记录
|
|
|
|
### 5.3 内容资产域
|
|
|
|
职责：
|
|
|
|
- 管理物理内容对象
|
|
- 管理内容版本
|
|
- 管理内容引用关系
|
|
- 管理派生产物
|
|
|
|
产出对象：
|
|
|
|
- 内容资产
|
|
- 内容版本
|
|
- 派生资产
|
|
|
|
### 5.4 分享与外部分发域
|
|
|
|
职责：
|
|
|
|
- 管理公开分享
|
|
- 管理分享口令、额度、有效期、权限范围
|
|
- 管理通过分享进入系统的导入动作
|
|
|
|
产出对象：
|
|
|
|
- 分享链接
|
|
- 分享策略
|
|
- 分享访问记录
|
|
|
|
### 5.5 快传域
|
|
|
|
职责：
|
|
|
|
- 管理在线传输会话
|
|
- 管理离线传输会话
|
|
- 管理传输文件清单
|
|
- 管理传输接收、导入与过期
|
|
|
|
产出对象：
|
|
|
|
- 传输会话
|
|
- 传输条目
|
|
- 取件码
|
|
|
|
### 5.6 后台任务域
|
|
|
|
职责：
|
|
|
|
- 管理异步任务生命周期
|
|
- 管理任务重试
|
|
- 管理租约、心跳、进度
|
|
- 承载需要异步执行的文件处理任务
|
|
|
|
产出对象：
|
|
|
|
- 任务
|
|
- 任务执行记录
|
|
|
|
### 5.7 存储治理域
|
|
|
|
职责：
|
|
|
|
- 管理存储策略
|
|
- 管理对象落点规则
|
|
- 管理上传能力矩阵
|
|
- 管理存储策略迁移
|
|
|
|
产出对象：
|
|
|
|
- 存储策略
|
|
- 存储能力
|
|
- 存储迁移批次
|
|
|
|
### 5.8 运营与管理域
|
|
|
|
职责：
|
|
|
|
- 提供全局治理能力
|
|
- 管理系统配置
|
|
- 提供运营视图与审计入口
|
|
|
|
产出对象：
|
|
|
|
- 系统设置
|
|
- 审计记录
|
|
- 管理操作记录
|
|
|
|
## 6. 核心业务对象
|
|
|
|
目标态采用以下统一业务对象模型。
|
|
|
|
### 6.1 `Account`
|
|
|
|
表示平台主体账号。
|
|
|
|
关键属性：
|
|
|
|
- `accountId`
|
|
- `username`
|
|
- `email`
|
|
- `phoneNumber`
|
|
- `status`
|
|
- `role`
|
|
- `quotaPolicy`
|
|
|
|
### 6.2 `Session`
|
|
|
|
表示一个被授权的登录会话。
|
|
|
|
关键属性：
|
|
|
|
- `sessionId`
|
|
- `accountId`
|
|
- `clientType`
|
|
- `status`
|
|
- `issuedAt`
|
|
- `expiresAt`
|
|
|
|
### 6.3 `Workspace`
|
|
|
|
表示用户的逻辑文件空间。
|
|
|
|
关键属性：
|
|
|
|
- `workspaceId`
|
|
- `ownerAccountId`
|
|
- `status`
|
|
|
|
### 6.4 `WorkspaceNode`
|
|
|
|
表示工作空间中的逻辑节点。
|
|
|
|
节点类型：
|
|
|
|
- `DIRECTORY`
|
|
- `FILE`
|
|
|
|
关键属性：
|
|
|
|
- `nodeId`
|
|
- `workspaceId`
|
|
- `parentNodeId`
|
|
- `name`
|
|
- `nodeType`
|
|
- `lifecycleState`
|
|
- `contentBinding`
|
|
|
|
说明：
|
|
|
|
- 目录节点只承担层级结构
|
|
- 文件节点绑定内容资产引用
|
|
|
|
### 6.5 `ContentAsset`
|
|
|
|
表示可被逻辑节点引用的内容资产。
|
|
|
|
关键属性：
|
|
|
|
- `assetId`
|
|
- `assetType`
|
|
- `currentVersionId`
|
|
- `ownerScope`
|
|
- `retentionPolicy`
|
|
|
|
### 6.6 `ContentVersion`
|
|
|
|
表示一份具体内容版本。
|
|
|
|
关键属性：
|
|
|
|
- `versionId`
|
|
- `assetId`
|
|
- `objectKey`
|
|
- `storagePolicyId`
|
|
- `size`
|
|
- `contentType`
|
|
- `checksum`
|
|
- `versionState`
|
|
|
|
规则：
|
|
|
|
- 内容版本一旦完成写入后应视为不可变
|
|
|
|
### 6.7 `ShareGrant`
|
|
|
|
表示一条对外分享授权。
|
|
|
|
关键属性：
|
|
|
|
- `shareId`
|
|
- `ownerAccountId`
|
|
- `targetNodeId`
|
|
- `accessPolicy`
|
|
- `status`
|
|
- `expiresAt`
|
|
|
|
### 6.8 `TransferSession`
|
|
|
|
表示一条临时传输会话。
|
|
|
|
关键属性：
|
|
|
|
- `transferId`
|
|
- `mode`
|
|
- `ownerAccountId`
|
|
- `status`
|
|
- `pickupCode`
|
|
- `expiresAt`
|
|
|
|
模式：
|
|
|
|
- `ONLINE`
|
|
- `OFFLINE`
|
|
|
|
### 6.9 `TransferItem`
|
|
|
|
表示一条传输会话中的文件项。
|
|
|
|
关键属性：
|
|
|
|
- `transferItemId`
|
|
- `transferId`
|
|
- `name`
|
|
- `relativePath`
|
|
- `size`
|
|
- `contentType`
|
|
- `state`
|
|
|
|
### 6.10 `AsyncJob`
|
|
|
|
表示系统异步任务。
|
|
|
|
关键属性：
|
|
|
|
- `jobId`
|
|
- `jobType`
|
|
- `ownerAccountId`
|
|
- `status`
|
|
- `retryPolicy`
|
|
- `lease`
|
|
|
|
### 6.11 `StoragePolicy`
|
|
|
|
表示一类存储落点规则。
|
|
|
|
关键属性：
|
|
|
|
- `storagePolicyId`
|
|
- `policyType`
|
|
- `capabilitySet`
|
|
- `maxObjectSize`
|
|
- `status`
|
|
- `isDefault`
|
|
|
|
### 6.12 `SystemSetting`
|
|
|
|
表示系统级业务配置。
|
|
|
|
关键属性：
|
|
|
|
- `settingKey`
|
|
- `settingScope`
|
|
- `value`
|
|
- `mutability`
|
|
|
|
## 7. 模块职责与协作边界
|
|
|
|
### 7.1 身份模块
|
|
|
|
负责：
|
|
|
|
- 账号生命周期
|
|
- 会话与令牌
|
|
- 角色与授权上下文
|
|
|
|
不得负责：
|
|
|
|
- 文件配额判断
|
|
- 工作空间结构
|
|
- 存储策略选择
|
|
|
|
### 7.2 工作空间模块
|
|
|
|
负责：
|
|
|
|
- 目录树
|
|
- 文件节点生命周期
|
|
- 删除、恢复、移动、复制、重命名
|
|
|
|
不得负责：
|
|
|
|
- 内容对象的物理写入
|
|
- 分享规则
|
|
- 传输协议
|
|
|
|
### 7.3 内容资产模块
|
|
|
|
负责：
|
|
|
|
- 内容对象写入完成后的登记
|
|
- 版本不可变规则
|
|
- 引用关系
|
|
- 内容级派生产物
|
|
|
|
不得负责：
|
|
|
|
- 工作空间路径语义
|
|
- 分享口令和访问额度
|
|
|
|
### 7.4 分享模块
|
|
|
|
负责：
|
|
|
|
- 对外访问授权
|
|
- 过期、口令、额度和权限范围
|
|
|
|
不得负责：
|
|
|
|
- 目录树变更
|
|
- 内容落库存储
|
|
|
|
### 7.5 快传模块
|
|
|
|
负责：
|
|
|
|
- 传输会话组织
|
|
- 在线传输的时效和接收关系
|
|
- 离线传输的文件接收与导入
|
|
|
|
不得负责：
|
|
|
|
- 普通分享
|
|
- 工作空间目录治理
|
|
|
|
### 7.6 后台任务模块
|
|
|
|
负责：
|
|
|
|
- 长耗时业务处理
|
|
- 重试和失败分类
|
|
|
|
不得负责：
|
|
|
|
- 同步主流程判断
|
|
|
|
### 7.7 存储治理模块
|
|
|
|
负责：
|
|
|
|
- 定义上传能力
|
|
- 定义内容落点
|
|
- 定义迁移规则
|
|
|
|
不得负责：
|
|
|
|
- 页面或客户端自己决定上传模式
|
|
|
|
### 7.8 管理模块
|
|
|
|
负责：
|
|
|
|
- 全局治理入口
|
|
- 系统设置和审计入口
|
|
|
|
不得负责：
|
|
|
|
- 绕开领域规则直接改写核心业务对象
|
|
|
|
## 8. 核心业务流程
|
|
|
|
### 8.1 账号注册流程
|
|
|
|
1. 用户提交注册信息
|
|
2. 系统校验唯一性与注册策略
|
|
3. 系统验证邀请码
|
|
4. 创建 `Account`
|
|
5. 初始化 `Workspace`
|
|
6. 签发首个 `Session`
|
|
|
|
### 8.2 登录流程
|
|
|
|
1. 用户提交凭证
|
|
2. 系统校验账号状态
|
|
3. 创建或替换对应客户端的 `Session`
|
|
4. 发放访问令牌与刷新令牌
|
|
|
|
### 8.3 文件接入流程
|
|
|
|
1. 用户发起上传
|
|
2. 系统依据 `StoragePolicy` 返回可用上传策略
|
|
3. 内容写入完成后登记 `ContentVersion`
|
|
4. 创建或绑定 `ContentAsset`
|
|
5. 在 `Workspace` 中创建 `WorkspaceNode`
|
|
|
|
### 8.4 文件操作流程
|
|
|
|
1. 用户选择目标节点
|
|
2. 工作空间模块校验所有权和路径规则
|
|
3. 执行重命名、移动、复制或删除
|
|
4. 如为复制，仅复制逻辑节点，不复制内容版本
|
|
|
|
### 8.5 删除与恢复流程
|
|
|
|
1. 删除动作只改变 `WorkspaceNode.lifecycleState`
|
|
2. 被删除节点进入回收区
|
|
3. 恢复时校验路径冲突和配额
|
|
4. 真正的物理清理由保留策略驱动
|
|
|
|
### 8.6 分享流程
|
|
|
|
1. 用户选择一个文件节点创建 `ShareGrant`
|
|
2. 系统记录分享访问策略
|
|
3. 访客通过分享入口访问
|
|
4. 系统按口令、期限、额度和动作权限进行授权判断
|
|
5. 允许时执行下载或导入
|
|
|
|
### 8.7 快传流程
|
|
|
|
#### 在线快传
|
|
|
|
1. 创建 `TransferSession(mode=ONLINE)`
|
|
2. 接收方加入
|
|
3. 完成信令交换
|
|
4. 传输完成或会话过期
|
|
|
|
#### 离线快传
|
|
|
|
1. 创建 `TransferSession(mode=OFFLINE)`
|
|
2. 写入 `TransferItem` 清单
|
|
3. 上传离线内容
|
|
4. 全部完成后进入可接收状态
|
|
5. 接收方下载或导入
|
|
|
|
### 8.8 异步处理流程
|
|
|
|
1. 主流程触发 `AsyncJob`
|
|
2. Worker 认领任务
|
|
3. 执行中上报租约和进度
|
|
4. 成功、失败、重试或取消
|
|
|
|
### 8.9 存储迁移流程
|
|
|
|
1. 创建迁移批次
|
|
2. 读取符合条件的 `ContentVersion`
|
|
3. 复制到目标存储策略
|
|
4. 切换引用
|
|
5. 清理旧内容对象
|
|
|
|
## 9. 统一业务规则
|
|
|
|
### 9.1 身份规则
|
|
|
|
- 账号必须有明确状态
|
|
- 被停用账号不得继续生成有效会话
|
|
- 一个客户端类型同一时刻只能有一个活跃会话
|
|
- 会话失效必须是统一规则，而不是接口局部处理
|
|
|
|
### 9.2 工作空间规则
|
|
|
|
- 所有文件和目录都必须存在于某个 `Workspace`
|
|
- `WorkspaceNode` 的路径语义由父子关系决定，不允许把完整路径字符串当作唯一真相
|
|
- 同一父节点下名称必须唯一
|
|
- 文件复制复制的是节点，不是内容版本
|
|
|
|
### 9.3 内容规则
|
|
|
|
- 内容版本写入完成后不可变
|
|
- 逻辑节点与物理内容必须解耦
|
|
- 派生产物属于内容资产域，不属于工作空间域
|
|
- 物理对象删除必须晚于业务生命周期结束
|
|
|
|
### 9.4 删除与保留规则
|
|
|
|
- 删除是进入回收区，不是直接物理删除
|
|
- 恢复必须回到原有工作空间语义下
|
|
- 物理清理只能由保留策略和引用关系共同决定
|
|
|
|
### 9.5 分享规则
|
|
|
|
- 分享是对单一目标节点的授权对象
|
|
- 分享权限必须显式区分查看、下载、导入
|
|
- 分享过期、额度耗尽、被撤销后必须立即失效
|
|
- 公开访问规则必须只由分享模块负责
|
|
|
|
### 9.6 传输规则
|
|
|
|
- 分享与快传是两个独立能力，不允许语义混用
|
|
- 在线快传是临时连接能力，不承担长期存储责任
|
|
- 离线快传是临时托管能力，不等于工作空间文件
|
|
- 导入动作必须显式把传输内容转化为工作空间资产
|
|
|
|
### 9.7 上传规则
|
|
|
|
- 上传能力由服务器根据存储策略决定
|
|
- 客户端只能消费上传策略，不自行定义上传模式
|
|
- 上传完成之前不得产生正式工作空间节点
|
|
|
|
### 9.8 任务规则
|
|
|
|
- 所有长耗时业务必须通过 `AsyncJob` 进入统一任务体系
|
|
- 相同语义的自动任务必须具备幂等键
|
|
- 任务状态机必须统一
|
|
|
|
### 9.9 管理规则
|
|
|
|
- 所有管理写操作必须具备审计能力
|
|
- 管理能力应基于角色和权限模型，不基于用户名白名单硬编码
|
|
- 系统设置必须区分可变业务配置和只读运行快照
|
|
|
|
## 10. 状态定义与状态流转
|
|
|
|
## 10.1 `AccountStatus`
|
|
|
|
状态：
|
|
|
|
- `PENDING`
|
|
- `ACTIVE`
|
|
- `SUSPENDED`
|
|
- `CLOSED`
|
|
|
|
流转：
|
|
|
|
- `PENDING -> ACTIVE`
|
|
- `ACTIVE -> SUSPENDED`
|
|
- `SUSPENDED -> ACTIVE`
|
|
- `ACTIVE/SUSPENDED -> CLOSED`
|
|
|
|
## 10.2 `SessionStatus`
|
|
|
|
状态：
|
|
|
|
- `ACTIVE`
|
|
- `REVOKED`
|
|
- `EXPIRED`
|
|
|
|
流转：
|
|
|
|
- `ACTIVE -> REVOKED`
|
|
- `ACTIVE -> EXPIRED`
|
|
|
|
## 10.3 `WorkspaceNodeLifecycleState`
|
|
|
|
状态：
|
|
|
|
- `ACTIVE`
|
|
- `RECYCLED`
|
|
- `PURGED`
|
|
|
|
流转：
|
|
|
|
- `ACTIVE -> RECYCLED`
|
|
- `RECYCLED -> ACTIVE`
|
|
- `RECYCLED -> PURGED`
|
|
|
|
## 10.4 `ContentVersionState`
|
|
|
|
状态：
|
|
|
|
- `PENDING_UPLOAD`
|
|
- `AVAILABLE`
|
|
- `ARCHIVED`
|
|
- `DELETED`
|
|
|
|
流转：
|
|
|
|
- `PENDING_UPLOAD -> AVAILABLE`
|
|
- `AVAILABLE -> ARCHIVED`
|
|
- `ARCHIVED -> DELETED`
|
|
|
|
## 10.5 `ShareGrantStatus`
|
|
|
|
状态：
|
|
|
|
- `ACTIVE`
|
|
- `LOCKED`
|
|
- `EXHAUSTED`
|
|
- `EXPIRED`
|
|
- `REVOKED`
|
|
|
|
流转：
|
|
|
|
- `ACTIVE -> LOCKED`
|
|
- `ACTIVE -> EXHAUSTED`
|
|
- `ACTIVE -> EXPIRED`
|
|
- `ACTIVE/LOCKED -> REVOKED`
|
|
|
|
## 10.6 `TransferSessionStatus`
|
|
|
|
状态：
|
|
|
|
- `CREATED`
|
|
- `AWAITING_UPLOAD`
|
|
- `READY`
|
|
- `IN_PROGRESS`
|
|
- `COMPLETED`
|
|
- `EXPIRED`
|
|
- `CANCELLED`
|
|
|
|
流转：
|
|
|
|
- 在线快传：`CREATED -> IN_PROGRESS -> COMPLETED/EXPIRED/CANCELLED`
|
|
- 离线快传：`CREATED -> AWAITING_UPLOAD -> READY -> COMPLETED/EXPIRED/CANCELLED`
|
|
|
|
## 10.7 `AsyncJobStatus`
|
|
|
|
状态：
|
|
|
|
- `QUEUED`
|
|
- `RUNNING`
|
|
- `RETRY_WAITING`
|
|
- `SUCCEEDED`
|
|
- `FAILED`
|
|
- `CANCELLED`
|
|
|
|
流转：
|
|
|
|
- `QUEUED -> RUNNING`
|
|
- `RUNNING -> SUCCEEDED`
|
|
- `RUNNING -> RETRY_WAITING`
|
|
- `RETRY_WAITING -> RUNNING`
|
|
- `RUNNING/RETRY_WAITING -> FAILED`
|
|
- `QUEUED/RUNNING/RETRY_WAITING -> CANCELLED`
|
|
|
|
## 11. 权限模型
|
|
|
|
目标态采用三层授权模型：
|
|
|
|
### 11.1 第一层：身份层
|
|
|
|
回答：
|
|
|
|
- 用户是谁
|
|
- 是否已登录
|
|
- 会话是否有效
|
|
|
|
### 11.2 第二层：角色层
|
|
|
|
回答：
|
|
|
|
- 用户具有什么系统级能力
|
|
|
|
例如：
|
|
|
|
- `MEMBER`
|
|
- `OPERATOR`
|
|
- `ADMIN`
|
|
|
|
### 11.3 第三层：资源层
|
|
|
|
回答：
|
|
|
|
- 用户是否可以对某个具体资源执行某个动作
|
|
|
|
资源授权判断必须同时考虑：
|
|
|
|
- 资源所有权
|
|
- 资源状态
|
|
- 角色权限
|
|
- 动作策略
|
|
|
|
### 11.4 授权规则
|
|
|
|
- 公开资源只允许暴露明确可公开的动作
|
|
- 所有者默认拥有自己资源的成员级权限
|
|
- 管理角色拥有治理权限，但不应破坏审计边界
|
|
- 导入、删除、恢复、迁移都属于高风险动作，必须有明确授权检查
|
|
|
|
## 12. 企业级目标模块结构
|
|
|
|
目标态后端应围绕业务域而不是技术层进行组织，建议演进为以下模块边界：
|
|
|
|
- `identity-access`
|
|
- `workspace`
|
|
- `content-asset`
|
|
- `sharing`
|
|
- `transfer`
|
|
- `async-job`
|
|
- `storage-governance`
|
|
- `operations-admin`
|
|
- `common-kernel`
|
|
|
|
每个模块内部再区分：
|
|
|
|
- domain
|
|
- application
|
|
- infra
|
|
- api
|
|
|
|
前端也应围绕业务域组织，而不是单纯围绕页面散落：
|
|
|
|
- account
|
|
- workspace
|
|
- sharing
|
|
- transfer
|
|
- admin
|
|
- common
|
|
|
|
## 13. 统一架构结论
|
|
|
|
目标态架构的核心不是“把当前代码整理得更漂亮”，而是把系统重构成以下稳定形态：
|
|
|
|
1. 账号、会话、角色、授权是独立的身份域
|
|
2. 工作空间节点与物理内容版本彻底分离
|
|
3. 分享与快传是两个独立分发域
|
|
4. 上传只是内容接入机制，不直接等同于业务文件创建
|
|
5. 后台任务是统一异步处理底座
|
|
6. 存储策略是系统级治理能力，不是控制器附属逻辑
|
|
7. 管理端是治理入口，不是绕过业务规则的特殊通道
|
|
|
|
后续所有重构都应围绕上述七条进行对齐。
|
|
|
|
## 14. 规则判定矩阵
|
|
|
|
本矩阵用于明确“某类规则到底由哪个业务域负责判定”，避免后续继续把同一规则散落在多个模块中。
|
|
|
|
| 规则类别 | 判定主体 | 触发时机 | 输出结果 | 不应由谁判定 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 是否允许注册 | `identity-access` | 用户提交注册请求时 | 允许注册 / 拒绝注册 | 页面层、管理台聚合层 |
|
|
| 邀请码是否有效 | `identity-access` | 注册前 | 有效 / 无效 / 已消费 | Controller 私有分支 |
|
|
| 会话是否有效 | `identity-access` | 每次受保护请求进入时 | 允许访问 / 拒绝访问 | 业务 Service 各自重复判断 |
|
|
| 用户是否具备系统管理能力 | `identity-access` | 访问管理能力前 | `OPERATOR` / `ADMIN` 是否可执行 | 用户名白名单硬编码 |
|
|
| 用户是否可操作某个工作空间节点 | `workspace` + 授权层 | 文件相关动作前 | 允许 / 拒绝 | Controller 层手写所有权判断 |
|
|
| 路径是否合法 | `workspace` | 创建、移动、复制、恢复前 | 合法 / 非法 | 上传模块重复实现 |
|
|
| 同目录是否允许重名 | `workspace` | 节点写入前 | 允许 / 拒绝 | 分享模块、传输模块各自决定 |
|
|
| 是否允许创建正式文件节点 | `workspace` | 内容接入完成后 | 创建 / 拒绝 | 上传接入层直接决定 |
|
|
| 内容版本是否可复用 | `content-asset` | 导入、复制、分享导入时 | 复用 / 新建版本 | 工作空间模块 |
|
|
| 是否允许物理删除对象 | `content-asset` | 清理流程中 | 删除 / 保留 | 工作空间模块直接删除对象 |
|
|
| 上传模式如何选择 | `storage-governance` | 创建上传会话时 | `PROXY` / `DIRECT_SINGLE` / `DIRECT_MULTIPART` | 前端、自定义工具类 |
|
|
| 上传大小是否超限 | `storage-governance` + `identity-access` | 上传前 | 允许 / 拒绝 | `FileService` 和 `UploadSessionService` 各自重复算 |
|
|
| 分享是否允许访问 | `sharing` | 访问分享链接时 | 允许查看 / 拒绝查看 | 工作空间模块 |
|
|
| 分享是否允许下载 | `sharing` | 下载分享文件时 | 允许下载 / 拒绝下载 | Controller 查询参数分支 |
|
|
| 分享是否允许导入 | `sharing` | 导入分享文件时 | 允许导入 / 拒绝导入 | 工作空间模块 |
|
|
| 分享是否过期或额度耗尽 | `sharing` | 每次分享动作前 | 可用 / 不可用 | 前端缓存判断 |
|
|
| 传输会话是否允许加入 | `transfer` | 加入在线快传时 | 允许加入 / 拒绝加入 | 信令基础设施 |
|
|
| 离线传输是否可接收 | `transfer` | 下载/导入前 | 可接收 / 不可接收 | 文件接入层 |
|
|
| 离线传输是否超出全局容量 | `transfer` + `storage-governance` | 离线上传前 | 允许上传 / 拒绝上传 | 管理指标聚合层 |
|
|
| 是否需要进入异步任务 | `async-job` 的调用方域 | 长耗时动作提交时 | 直接处理 / 创建任务 | Controller 层直接排队 |
|
|
| 任务是否允许重试 | `async-job` | 任务失败后 | 自动重试 / 人工重试 / 不可重试 | 具体任务 handler 自己决定 |
|
|
| 任务是否重复 | `async-job` | 创建任务时 | 新建 / 幂等忽略 | broker 消费者临时判断 |
|
|
| 设置是否允许修改 | `operations-admin` + 授权层 | 管理写操作时 | 可写 / 只读 | 聚合 DTO 提示字段单独决定 |
|
|
|
|
### 14.1 矩阵使用规则
|
|
|
|
- 所有新业务规则必须先映射到矩阵中的一个判定主体。
|
|
- 如果某条规则找不到唯一判定主体，说明领域边界还没有收敛。
|
|
- 同一规则只能有一个“最终判定主体”，其他模块只能消费判定结果，不能复制规则。
|
|
|
|
## 15. 高风险测试场景清单
|
|
|
|
本清单不是为了堆测试数量，而是定义目标架构下必须被自动化约束的关键业务场景。
|
|
|
|
### 15.1 身份与授权
|
|
|
|
1. 同一客户端类型再次登录后，旧会话失效
|
|
2. 桌面端与移动端会话可并存，但互不覆盖
|
|
3. 改密后所有活跃会话和 refresh token 失效
|
|
4. 账号被停用后无法继续访问受保护资源
|
|
5. `OPERATOR` 与 `ADMIN` 的授权边界按统一角色模型生效
|
|
|
|
### 15.2 工作空间
|
|
|
|
1. 同一父节点下禁止重名文件或目录
|
|
2. 目录不能移动到自身或自身子树
|
|
3. 目录不能复制到自身或自身子树
|
|
4. 删除进入回收区而不是立即物理删除
|
|
5. 恢复时如果原位置冲突则整体拒绝恢复
|
|
6. 恢复时如果超出配额则整体拒绝恢复
|
|
|
|
### 15.3 内容资产
|
|
|
|
1. 复制逻辑节点时不复制物理内容版本
|
|
2. 多个逻辑节点绑定同一内容版本时，删除其中一个不会删除物理对象
|
|
3. 最后一个逻辑引用消失后，物理对象才允许清理
|
|
4. 内容版本一旦 `AVAILABLE` 后不可变
|
|
|
|
### 15.4 上传与存储治理
|
|
|
|
1. 上传模式严格由存储策略能力决定
|
|
2. 非法路径、非法名称、超大小、超配额都会被统一拒绝
|
|
3. 已完成、已取消、已失败、已过期的上传会话不能继续写入
|
|
4. 分片上传必须完整记录分片后才能完成
|
|
5. 上传完成前不创建正式工作空间节点
|
|
|
|
### 15.5 分享
|
|
|
|
1. 有口令的分享必须先验密
|
|
2. 过期分享不可查看、不可下载、不可导入
|
|
3. `allowDownload` 与 `allowImport` 必须分别生效
|
|
4. 分享额度耗尽后所有授权动作失效
|
|
5. 分享被撤销后立即失效
|
|
|
|
### 15.6 快传
|
|
|
|
1. 在线快传只允许有效接收方进入会话
|
|
2. 离线快传只有全部文件上传完成后才可接收
|
|
3. 匿名可接收，但不可导入到工作空间
|
|
4. 离线传输容量达到上限时拒绝继续上传
|
|
5. 过期传输会话不可继续接收或导入
|
|
|
|
### 15.7 异步任务
|
|
|
|
1. 相同业务语义的自动任务不会重复创建
|
|
2. 任务租约过期后能够安全回收
|
|
3. retryable 失败会进入统一重试流程
|
|
4. non-retryable 失败进入终态
|
|
5. 只有允许人工重试的任务才能被人工重试
|
|
|
|
### 15.8 管理与治理
|
|
|
|
1. 只读系统快照不可通过写接口修改
|
|
2. 可写业务设置必须经过统一管理授权
|
|
3. 高风险治理动作必须产生审计记录
|
|
4. 存储迁移只能在合法策略组合下执行
|
|
|
|
## 16. 重构迁移与模块落地顺序
|
|
|
|
本顺序定义的是目标架构的落地路径，不是一次性重写方案。
|
|
|
|
### 16.1 第一阶段：身份与授权先行
|
|
|
|
目标：
|
|
|
|
- 统一角色模型
|
|
- 统一会话失效规则
|
|
- 统一管理权限事实源
|
|
|
|
优先原因：
|
|
|
|
- 如果权限模型不先收敛，后续所有模块重构都会继续携带错误边界
|
|
|
|
落地模块：
|
|
|
|
- `identity-access`
|
|
- `operations-admin` 中与授权入口直接相关的部分
|
|
|
|
### 16.2 第二阶段：工作空间与内容资产拆分
|
|
|
|
目标：
|
|
|
|
- 把逻辑节点与物理内容彻底拆开
|
|
|
|
优先原因：
|
|
|
|
- 这是后续分享、快传、上传、删除、恢复、迁移的共同基础
|
|
|
|
落地模块：
|
|
|
|
- `workspace`
|
|
- `content-asset`
|
|
|
|
### 16.3 第三阶段：上传与存储治理收口
|
|
|
|
目标：
|
|
|
|
- 让上传成为内容接入能力
|
|
- 让存储策略成为系统级能力
|
|
|
|
优先原因：
|
|
|
|
- 当前上传规则和文件业务耦合过深，不先切开，内容资产域无法稳定
|
|
|
|
落地模块：
|
|
|
|
- `storage-governance`
|
|
- `content-asset` 接入层
|
|
|
|
### 16.4 第四阶段：分享域收口
|
|
|
|
目标：
|
|
|
|
- 统一旧分享和新分享
|
|
- 让分享只围绕 `ShareGrant` 和逻辑节点授权
|
|
|
|
优先原因：
|
|
|
|
- 分享对外暴露面大，必须建立在稳定工作空间与内容模型之上
|
|
|
|
落地模块：
|
|
|
|
- `sharing`
|
|
|
|
### 16.5 第五阶段：快传域拆分
|
|
|
|
目标：
|
|
|
|
- 分开在线快传与离线快传
|
|
- 明确临时传输与正式工作空间资产的边界
|
|
|
|
优先原因：
|
|
|
|
- 快传与分享的边界只有在工作空间与分享域稳定后才容易落定
|
|
|
|
落地模块：
|
|
|
|
- `transfer`
|
|
|
|
### 16.6 第六阶段：异步任务统一底座
|
|
|
|
目标：
|
|
|
|
- 让 `AsyncJob` 成为跨域底座
|
|
|
|
优先原因：
|
|
|
|
- 当工作空间、内容资产、分享、快传都稳定后，异步任务才可以真正服务多个领域，而不是继续附属在文件模块里
|
|
|
|
落地模块：
|
|
|
|
- `async-job`
|
|
|
|
### 16.7 第七阶段：管理域治理化
|
|
|
|
目标：
|
|
|
|
- 管理端只做治理编排
|
|
- 业务规则回归各自领域
|
|
|
|
优先原因：
|
|
|
|
- 管理端必须建立在稳定的领域边界之上，否则只会继续膨胀为超级入口
|
|
|
|
落地模块：
|
|
|
|
- `operations-admin`
|
|
|
|
### 16.8 第八阶段：前端按领域重组
|
|
|
|
目标：
|
|
|
|
- 前端与后端围绕同一业务域组织
|
|
|
|
优先原因：
|
|
|
|
- 前端结构必须跟随稳定后的后端领域，而不是反向牵引后端设计
|
|
|
|
落地模块：
|
|
|
|
- `account`
|
|
- `workspace`
|
|
- `sharing`
|
|
- `transfer`
|
|
- `admin`
|
|
- `common`
|
|
|
|
### 16.9 模块落地顺序总表
|
|
|
|
1. `identity-access`
|
|
2. `workspace`
|
|
3. `content-asset`
|
|
4. `storage-governance`
|
|
5. `sharing`
|
|
6. `transfer`
|
|
7. `async-job`
|
|
8. `operations-admin`
|
|
9. 前端领域化重组
|
|
|
|
### 16.10 落地顺序约束
|
|
|
|
- 未统一身份与授权前，不进入大规模治理侧重构
|
|
- 未拆开工作空间与内容资产前，不收口分享和快传
|
|
- 未收口上传与存储治理前，不把内容资产域视为稳定
|
|
- 未稳定后端领域边界前，不开始前端大规模域化重组
|
|
|