tkmind_go/documentation/docs/guides/mindspace/02-module-breakdown.md

---
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`

事件消费者必须幂等，事件不能替代关键事务中的一致性校验。