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

---
sidebar_position: 10
title: Frontend and Backend Implementation
sidebar_label: Implementation
description: 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`。

建议领域类型：

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

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

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

repository 方法示例：

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

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

## 前端功能目录

建议：

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

每个 feature 包含：

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

## 前端路由

建议路由：

```text
/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。