技术图示

当前网站的技术图与数据读取流程：网页、工作项 API 和数据访问层。

图表使用 Mermaid 编写，便于阅读、修改并与源代码对照。下方图表描述现有原型，不代表 Võ 游戏的后端。

本节解释技术组件如何连接。了解谁接收 CEO 请求、分配工作及交付结果，请阅读团队协作流程.

现有系统图表版本1.0.0

当前系统图

浏览器从Astro接收页面。需要新数据的页面调用服务器数据访问层；工作API是独立读取路径。

在框内滚动可查看完整尺寸的图表。选中框后可使用方向键。

图表进入可视区域时渲染。下方可阅读完整步骤。

静态页在build时生成，SSR页在请求时生成HTML；两者均通过浏览器读取。
SSR页直接调用repository。工作API也使用同一repository返回JSON，并非SSR页必经中间层。
工作使用本地数据。成员档案结合成员目录与本地活动记录，仅提供允许公开的部分。
原型尚无运营数据库、公开写API、登录或支付系统。

查看 Mermaid 源码 · v1.0.0

flowchart TB
  accTitle: 当前网站系统图
  accDescr: 浏览器读取静态页、SSR页或工作API。SSR页和API通过repository读取本地数据。
  browser["浏览器"]
  staticPages["Astro静态页"]
  ssrPages["Astro SSR页"]
  ticketApi["工作API · 仅GET"]
  ticketRepo["工作Repository"]
  teamRepo["成员Repository"]
  ticketData[("本地工作数据")]
  teamData[("成员目录与活动")]
  browser -->|"读取页面"| staticPages
  browser -->|"读取页面"| ssrPages
  browser -->|"调用GET"| ticketApi
  ssrPages --> ticketRepo
  ssrPages --> teamRepo
  ticketApi --> ticketRepo
  ticketRepo --> ticketData
  teamRepo --> teamData

QT0006流程版本1.1.0

现有系统图表版本1.0.0

按ID读取一个工作项

GET /api/tickets/{id} 区分格式错误的 ID、不存在的工作项与有效结果。详情页使用同一数据层生成 HTML。

在框内滚动可查看完整尺寸的图表。选中框后可使用方向键。

图表进入可视区域时渲染。下方可阅读完整步骤。

应用使用工作项的稳定 ID 发送 GET /api/tickets/{id}。
格式错误的ID返回HTTP 400；有效ID通过repository查询。
无记录返回HTTP 404；有记录返回HTTP 200及含公开字段的ticket对象。
/tickets/{id}/ 路径是独立的 SSR HTML 页面：直接调用 repository，并在 ID 无效或不存在时返回 404 页面。

查看 Mermaid 源码 · v1.0.0

sequenceDiagram
 accTitle: API 按 ID 读取工作项
 accDescr: API 校验 ID 格式，查询 repository，并返回错误 400、错误 404 或公开数据 200。
 participant client as 调用方
 participant api as 工作 API
 participant repo as Repository
 client->>api: GET /api/tickets/{id}
 alt ID 格式错误
 api-->>client: 400 · invalid_id
 else ID 有效
 api->>repo: get(id)
 repo-->>api: 记录或 null
 alt 未找到
 api-->>client: 404 · not_found
 else 找到记录
 api->>api: 选择公开字段
 api-->>client: 200 · ticket
 end
 end

QT0007流程版本1.1.0

现有系统图表版本1.0.0

逐页读取列表

GET /api/tickets接收项目编号、数量限制和后续游标；每次响应最多50个工作项。

在框内滚动可查看完整尺寸的图表。选中框后可使用方向键。

图表进入可视区域时渲染。下方可阅读完整步骤。

首次请求含gameId与limit，默认vo和20；limit须为1至50的整数。
Repository校验查询。有after时，其ID须存在且属于同一项目；无效查询或游标返回HTTP 400。
结果含公开items与nextCursor。编号格式有效但没有工作的项目返回空列表。
nextCursor非null时，与同一gameId一起作为after发送以续读。null表示当前列表结束；响应限制不证明大规模运营能力。

查看 Mermaid 源码 · v1.0.0

sequenceDiagram
  accTitle: 工作列表分页API
  accDescr: Repository检查项目、数量限制与游标，然后返回公开列表与下一游标。
  participant client as 调用方
  participant api as 工作API
  participant repo as Repository
  Note over client,api: gameId=vo, limit=20
  client->>api: GET /api/tickets
  api->>repo: list(gameId, limit, after)
  alt 查询或游标无效
    repo-->>api: InvalidTicketQuery
    api-->>client: 400 · invalid_query
  else 有效
    repo-->>api: items与nextCursor
    api->>api: 选择各项公开字段
    api-->>client: 200 · items与nextCursor
    opt nextCursor非null
      client->>api: GET同一gameId，after=nextCursor
      api->>repo: 读取下一页
      repo-->>api: items与新nextCursor
      api-->>client: 200 · 公开字段
    end
  end

提议 · 尚未实施

当数据与需求增长时

Repository 在界面与数据存储之间提供契约。下一步可用数据库替代本地数据集，采用有索引的 ID 查询与数据源分页。这是扩展方向；当前原型尚未证明大规模服务能力。

关于团队协作