tkmind_go/documentation/docs/guides/mindspace/09-implementation-guide.md

sidebar_position, title, sidebar_label, description

sidebar_position	title	sidebar_label	description
10	Frontend and Backend Implementation	Implementation	Practical frontend, backend, storage, migration, and integration tasks

前后端开发规范

开发顺序

每个垂直功能按以下顺序完成：

1. 领域类型和状态规则。
2. 数据库迁移和 repository。
3. 应用服务、权限和事务。
4. API DTO、路由和 OpenAPI。
5. 前端数据层、页面和状态。
6. 自动化测试。
7. 指标、日志和审计。
8. 手工验收。

后端模块

Account

任务：

• 用户注册、登录、登出和当前用户。
• 密码哈希和会话。
• 注册事务内初始化 Space 和分类。
• 用户状态中间件。

Space and Quota

任务：

• 套餐配置。
• 配额读取。
• 原子预留、确认、释放和对账。
• 分类计数和空间首页摘要。

Storage and Assets

任务：

• StorageProvider 抽象。
• 本地存储实现和对象存储预留接口。
• 上传 session。
• MIME、checksum 和扫描。
• 资产列表、详情、预览、下载、移动和删除。
• 资产版本。

Pages

任务：

• 创建空白页和模板页。
• 从聊天消息保存。
• 从 Agent 输出创建草稿。
• 编辑和乐观锁。
• 页面版本和关联资产。
• 封面任务。

Publishing

任务：

• 发布检查。
• 构建不可变 bundle。
• 公开和 owner-only 访问。
• slug、下线和重新发布。
• 缓存失效。

Security

任务：

• 扫描任务接口。
• PII finding。
• HTML sanitization。
• 私有资源引用检查。
• 风险决策。
• 脱敏副本。

Agent Jobs

任务：

• job 创建、绑定资产、调度和状态。
• job token。
• 内部资产读取和输出提交。
• 取消、超时、重试和 heartbeat。
• goose worker 适配。

Audit and Analytics

任务：

• 统一 audit writer。
• 高风险同步审计。
• 公开页面浏览计数。
• 第二期加入聚合统计。

Rust 实现约定

遵循仓库规则：

• 错误使用 anyhow::Result，边界处映射为稳定 API 错误。
• 不添加重复说明代码行为的注释。
• 服务端变更后运行 just generate-openapi，不要手工编辑 ui/desktop/openapi.json。
• 新依赖使用 cargo add。
• 完成编辑后必须运行 cargo fmt。

建议领域类型：

struct Actor {
    user_id: UserId,
    role: Role,
}

enum CategoryCode {
    Oa,
    Private,
    Public,
    Draft,
    Archive,
}

enum AccessMode {
    Public,
    Password,
    PrivateLink,
    TimeLimited,
    LoginRequired,
    OwnerOnly,
}

repository 方法示例：

async fn get_asset_for_actor(
    &self,
    actor: &Actor,
    asset_id: AssetId,
) -> anyhow::Result<Asset>;

不要提供不带 actor 的公共资产查询方法。

前端功能目录

建议：

src/features/mindspace/
  api/
  auth/
  dashboard/
  assets/
  upload/
  pages/
  publishing/
  security/
  jobs/
  templates/
  shared/

每个 feature 包含：

• API types 和 client。
• 页面组件。
• feature 内组件。
• 状态和错误映射。
• 测试。

前端路由

建议路由：

/login
/register
/space
/space/oa
/space/private
/space/public
/space/drafts
/space/assets/:assetId
/space/pages/:pageId
/space/pages/:pageId/edit
/space/pages/:pageId/publish
/space/publishing
/space/security
/templates
/u/:userSlug
/u/:userSlug/pages/:pageSlug
/s/:token

前端状态

区分：

• 服务端实体状态。
• 页面筛选和弹窗状态。
• 上传和任务进度。
• 草稿编辑状态。

不要将完整服务端数据复制到多个全局 store。列表更新后使用查询失效或局部一致更新。

上传实现

• 支持多文件队列。
• 每个文件独立 upload session。
• 上传前显示配额结果。
• 使用流式或分片策略，MVP 小文件可先单次上传。
• 浏览器刷新后可查询未完成 session。
• 取消时调用服务端释放配额。

页面编辑器

MVP 可以先使用受控模板 + 结构化内容：

• 标题。
• 摘要。
• Markdown 或 block JSON。
• 封面。
• 模板参数。

不要首期直接提供任意 HTML/JS 在线编辑器。已有 AI HTML 输出必须经过 sanitizer 和 sandbox 预览。

卡片和列表

统一数据模型：

• id
• title
• cover_url
• content_type
• source_type
• status
• visibility/access_mode
• view_count
• updated_at
• allowed_actions

allowed_actions 由服务端返回或前端基于服务端能力字段渲染，但最终仍由服务端授权。

加载和错误状态

每个页面至少实现：

• skeleton。
• 空状态。
• 网络错误重试。
• 401 重新登录。
• 403/404 不泄露资源信息。
• 409 版本冲突。
• 429 配额或限流。
• Agent 失败和重试。
• 风险阻断和处理入口。

移动端

• 底部导航固定。
• 卡片单列或双列按宽度响应。
• 上传使用系统文件选择器。
• 发布设置分步骤展示。
• 详情页操作使用底部操作栏。
• 表格内容提供横向滚动或摘要视图。
• 不在手机首屏展示目录树。

API 类型同步

• goose-server 路由是 OpenAPI 来源。
• 服务端 schema 变化后生成 OpenAPI。
• 前端生成或更新 API 类型。
• CI 检查生成文件是否最新。
• 不手改生成的 OpenAPI 文件。

数据库迁移顺序

1. users 扩展和 user_spaces。
2. categories、assets、asset_versions、upload_sessions。
3. pages、page_versions。
4. security_scans、findings 和脱敏表。
5. publications 和 publication_events。
6. agent_jobs 和绑定表。
7. audit、usage 和 page views。
8. templates 和后台配置。

每个迁移附：

• 新表和索引。
• 默认数据。
• 回滚方式。
• 现有用户补齐 Space 的 backfill。
• 验证 SQL 或应用检查。

功能开关

建议：

• mindspace_enabled
• mindspace_upload_enabled
• mindspace_publish_enabled
• mindspace_private_enabled
• mindspace_agent_jobs_enabled
• mindspace_password_share_enabled
• mindspace_analytics_enabled

功能关闭不能导致已有公开链接失效，除非明确执行全局下线。

代码完成清单

• 权限检查在服务端。
• 状态转换集中实现。
• 写操作有事务。
• 高风险操作有审计。
• API 有稳定错误码。
• 前端覆盖所有状态。
• 移动端可用。
• OpenAPI 已更新。
• cargo fmt 已运行。
• 仅在用户要求测试时按仓库规则运行构建、测试和 clippy。