--- sidebar_position: 3 title: Module Breakdown sidebar_label: Modules description: MindSpace frontend, backend, storage, security, agent, and operations modules --- # 模块拆分与职责边界 ## 模块总图 ```text 客户端 Chat / MindSpace / Upload / Pages / Publish / Security / Settings | API Gateway / Session Auth / Rate Limit | MindSpace Platform Account Space & Quota Asset Page Publication Security Audit Agent Job Analytics Template | Database / Object Storage / Queue / Cache | goose Agent Execution ``` ## 1. 账户与身份模块 职责： - 注册、登录、登出、会话刷新和账号状态。 - 用户名、slug、头像、套餐和个人资料。 - 密码哈希、登录限流、会话撤销和管理员冻结。 首期任务： - 注册和登录 API。 - 唯一用户名、邮箱和 slug 校验。 - 当前用户接口。 - 禁用、冻结和注销状态拦截。 验收： - 未登录请求不能访问私人 API。 - 被冻结用户不能创建、修改或发布内容。 - slug 冲突有稳定错误码。 ## 2. 空间与配额模块 职责： - 注册时创建默认 Space 和内置分类。 - 维护空间总量、已用量、保留量和套餐限制。 - 提供配额预检查、占用、确认和释放。 首期任务： - 默认 5 MB。 - OA、私人、公开、草稿分类。 - 配额展示和上传前检查。 关键规则： - 正在上传的文件先占用 `reserved_bytes`，成功后转入 `used_bytes`。 - 失败、超时和取消上传必须释放预留配额。 - 版本、封面、缩略图和页面资源是否计费必须统一定义。 ## 3. 资产模块 职责： - 上传、列表、详情、预览、下载、重命名、移动和软删除。 - 文件类型识别、checksum、版本和逻辑目录。 - 存储 key 与业务路径解耦。 首期支持： - Word、Excel、PDF、图片、Markdown、CSV、TXT、PPT。 - HTML 页面包仅允许由受控生成流程写入公开候选区。 必须防止： - 路径穿越。 - MIME 伪造。 - 跨用户 asset ID 访问。 - 公开 HTML 引用私有资源。 ## 4. 页面模块 职责： - 从聊天、资产或模板创建页面。 - 页面草稿、内容、封面、来源和版本管理。 - 预览、编辑、复制和归档。 页面类型： - `report` - `landing_page` - `profile` - `gallery` - `article` - `dashboard` - `html_page` 关键规则： - Page 是业务对象，HTML 文件只是它的一个版本产物。 - 每次保存可以更新草稿；每次发布必须生成不可变版本。 - 来源会话删除后，页面仍保留必要的来源快照和可追溯 ID。 ## 5. 发布模块 职责： - 公开、密码、私密链接、限时、登录可见和仅自己可见。 - slug、token、密码、过期时间、上线和下线。 - 发布版本切换、链接复制和发布历史。 首期： - 公开访问。 - 仅自己可见。 第二期： - 密码、私密链接、限时访问和访问统计。 ## 6. 安全与脱敏模块 职责： - 文件风险扫描。 - PII 识别和脱敏建议。 - HTML、资源引用和外链检查。 - 发布阻断、风险确认和扫描报告。 风险等级： - `none` - `low` - `medium` - `high` - `critical` 扫描结果必须保存规则版本、命中位置、处理动作和确认人。 ## 7. 审计模块 职责： - 记录上传、删除、私有读取、Agent 访问、生成、发布、下线、下载、分享和脱敏。 - 提供管理员查询和用户自己的安全记录。 - 保证日志不可由普通业务 API 修改。 审计失败策略： - 高风险写操作在审计持久化失败时应失败关闭。 - 普通浏览统计失败不能阻断公开页面访问。 ## 8. Agent Job 模块 职责： - 将自然语言任务转换为明确的输入资产、输出分类和权限范围。 - 创建、调度、取消、重试和查询任务。 - 将 goose 的执行结果回写为资产或页面草稿。 权限最小化： - Agent 只获得短期 job token。 - token 只能读取 `allowed_asset_ids`。 - token 只能写入指定 `output_category_id`。 - 任务结束、取消或超时后立即失效。 ## 9. 访问统计模块 职责： - 页面浏览、唯一访客、来源、设备和时间趋势。 - 隐私合规、机器人过滤和异常流量限制。 首期可只记录总浏览量；第二期增加趋势和来源。 ## 10. 模板模块 职责： - 模板分类、预览、适用场景、输入要求和版本。 - 从模板创建草稿。 - 控制模板允许的脚本、资源和组件。 模板类别： - 个人 - 办公 - 商业 - 教育 - 健康 ## 11. 个人主页模块 职责： - 展示用户公开作品卡片。 - 按类型、状态和更新时间筛选。 - 支持头像、简介、封面和公开内容排序。 原则： - 主页只查询已发布且在线的 Publication。 - 私有和草稿卡片只在本人登录态下展示。 ## 12. 管理后台模块 首期最小能力： - 用户查询和冻结。 - 配额查看与修正。 - 风险发布下线。 - 审计日志查询。 - 系统模板开关。 后台操作也必须写审计日志。 ## 13. 通知模块 第二期起提供： - Agent 任务完成或失败。 - 页面发布成功、即将过期或被下线。 - 配额即将用完。 - 高风险内容检测。 通知渠道首选站内通知，邮件和短信后续接入。 ## 14. 存储适配模块 职责： - 统一本地文件和对象存储接口。 - 生成内部读取流和受控下载。 - 支持 checksum、原子写入、临时文件清理和迁移。 禁止其他业务模块拼接磁盘路径。 ## 15. 后台任务模块 任务类型： - 文件扫描。 - 文档解析。 - AI 生成。 - 缩略图和封面。 - 发布包构建。 - 过期链接下线。 - 临时上传清理。 - 配额对账。 每个任务必须具备幂等 key、状态、重试次数、最后错误和超时。 ## 模块依赖顺序 1. 账户与身份。 2. 空间、分类和配额。 3. 资产和存储。 4. 页面和版本。 5. 安全扫描。 6. 发布。 7. Agent Job。 8. 主页、统计和模板。 9. 管理后台、通知和商业化。 ## 跨模块事件 建议事件： - `user.registered` - `asset.uploaded` - `asset.deleted` - `agent_job.completed` - `page.created` - `page.version_created` - `security_scan.completed` - `publication.published` - `publication.offlined` - `publication.viewed` - `quota.threshold_reached` 事件消费者必须幂等，事件不能替代关键事务中的一致性校验。