first commit

docs/api-stack/api/api-plugin-file-upload/src/routes/build-routes.md

@@ -0,0 +1,51 @@
+# `build-routes.ts`
+
+## Purpose
+
+Builds the 6 OpenAPI route entries the plugin mounts on the host Hono app: single-shot `POST /`, chunked-init `POST /initiate`, chunk append `PUT /{uploadId}/chunks/{chunkIndex}`, finalise `POST /{uploadId}/complete`, abort `DELETE /{uploadId}`, and status `GET /{uploadId}`. Each route uses `RouteBuilder` from `@suaveplan/api-openapi` so request/response schemas flow through end-to-end, keeping the served `/openapi.json` document accurate against the live wire surface.
+
+## Features
+
+- Six routes registered with typed request bodies, params, and responses.
+- Single shared service handle (`FileUploadService`) wired into every handler, so the routes do not own any per-request state.
+- Reuses the same `SingleShotResponseSchema` across `POST /` and `POST /{uploadId}/complete` so clients have a uniform success shape regardless of which upload mode they used.
+
+## Usage: Basic
+
+```ts
+import { buildUploadRoutes } from "@suaveplan/api-plugin-file-upload/routes/routes";
+import { definePluginRoutes } from "@suaveplan/api-openapi";
+
+definePluginRoutes(buildUploadRoutes(service), {
+    app,
+    registry: openAPIRegistry,
+    pluginName: "file-upload",
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { buildUploadRoutes } from "@suaveplan/api-plugin-file-upload";
+
+const entries = buildUploadRoutes(service);
+for (const entry of entries) {
+    console.log(entry.route.method, entry.route.path);
+}
+// → post /
+// → post /initiate
+// → put /{uploadId}/chunks/{chunkIndex}
+// → post /{uploadId}/complete
+// → delete /{uploadId}
+// → get /{uploadId}
+```
+
+## API Reference
+
+- `buildUploadRoutes(service: FileUploadService): PluginRouteEntry[]` — returns the 6 ready-to-mount entries.
+
+## Implementation Notes
+
+- The paths use OpenAPI `{name}` placeholders (not Hono's `:name`) because `RouteBuilder` emits OpenAPI 3.1 path templates. `@hono/zod-openapi` translates back to Hono's parameter syntax at registration.
+- The single-shot route uses `POST /` — Hono mounts it under `basePath`, so the final URL is `POST {basePath}` (default `POST /uploads`).
+- All routes return JSON. Multipart parsing for the single-shot path happens INSIDE the handler so the route table stays declarative.