用户文档 - 量潮项目管理工具箱

一套跨语言的项目管理 SDK，覆盖数据模型、API 路由、UI 组件。

安装¶

Python

FastAPI

Dart

Flutter

pip install quanttide-project

核心概念¶

数据模型分为 Project（项目）和 Task（任务）两种资源。

Project¶

项目有唯一标识、名称、标题、描述和审计信息。

Python

Dart

from quanttide_project import Project

p = Project(
    id="proj-1",
    name="my-project",
    title="我的项目",
    description="项目描述",
)

Task¶

任务比项目多了分类、状态、优先级、负责人和时间计划。

Python

Dart

from datetime import datetime, timezone
from quanttide_project import Task

t = Task(
    id="task-1",
    title="实现登录功能",
    type="task",
    status="in_progress",
    priority="high",
    assignee="alice",
    tags={"module": "auth"},
    start_at=datetime(2026, 5, 1, tzinfo=timezone.utc),
    end_at=datetime(2026, 5, 15, tzinfo=timezone.utc),
)

import 'package:quanttide_project/quanttide_project.dart';

final t = Task(
  id: 'task-1',
  title: '实现登录功能',
  type: 'task',
  status: 'in_progress',
  priority: 'high',
  assignee: 'alice',
  tags: {'module': 'auth'},
  startAt: DateTime.utc(2026, 5, 1),
  endAt: DateTime.utc(2026, 5, 15),
);

JSON 序列化¶

所有模型支持 JSON 序列化和反序列化。

Python

Dart

# 序列化
data = p.model_dump(mode="json", exclude_none=True)
# 反序列化
p2 = Project.model_validate(data)

通过 FastAPI CRUD 层收发 JSON 时，字段名自动在 Python snake_case 与 JSON camelCase 之间转换（created_at ↔ createdAt）。

更新 Task¶

Task 是不可变模型，通过 replace（Python）或 copyWith（Dart）创建修改后的新实例。

Python

Dart

updated = t.replace(status="done", priority="high")

仅可修改 type、category、status、priority、assigner、assignee、start_at、end_at，标识和审计字段不可变。

CRUD API（Python FastAPI）¶

fastapi-quanttide-project 为 Project 和 Task 自动生成标准 CRUD 端点。

from fastapi import FastAPI
from fastapi_quanttide_project import ProjectRouter, TaskRouter

app = FastAPI()

app.include_router(ProjectRouter.build_default())
app.include_router(TaskRouter.build_default())

启动后获得：

方法	路径	说明
POST	`/projects`	创建项目
GET	`/projects`	项目列表
GET	`/projects/{id}`	项目详情
PATCH	`/projects/{id}`	更新项目
DELETE	`/projects/{id}`	删除项目

Task 同理，路径为 /tasks。

JSON 请求与响应使用 camelCase，Python 代码保持 snake_case，自动映射：

POST /projects
{"id": "p1", "name": "test", "title": "测试项目", "createdBy": "alice"}

→ 200
{"id": "p1", "name": "test", "title": "测试项目", "description": "", "createdBy": "alice", "createdAt": "...", "updatedBy": null, "updatedAt": "..."}

UI 组件（Flutter）¶

flutter_quanttide_project 提供看板 UI 组件。

import 'package:flutter_quanttide_project/flutter_quanttide_project.dart';

BoardView(
  header: Text('项目看板'),
  columns: [
    (child: BoardColumn(
      title: Text('待办'),
      content: ListView(children: [
        BoardCard(
          title: Text('实现登录'),
          onTap: () { /* 点击事件 */ },
        ),
      ]),
    ), flex: 1),
    (child: BoardColumn(
      title: Text('进行中'),
      content: ListView(children: [
        BoardCard(
          title: Text('编写文档'),
          description: Text('完成 API 文档'),
        ),
      ]),
    ), flex: 1),
  ],
)

BoardView 自动响应桌面端（横向排列）和移动端（纵向堆叠）。

包关系¶

dart ── 数据模型（参考实现）
 │
 ├── python ── Pydantic 模型
 │     │
 │     └── fastapi ── CRUD 路由
 │
 └── flutter ── 看板 UI 组件