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

sidebar_position, title, sidebar_label, description

sidebar_position	title	sidebar_label	description
3	Module Breakdown	Modules	MindSpace frontend, backend, storage, security, agent, and operations modules

模块拆分与职责边界

模块总图

客户端
  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

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