docs: add user service JSDoc

apps/api/src/routes/users.ts

@@ -1,20 +1,19 @@
 import { Router } from "express";
 
+import { createUser, listUsers } from "../services/userService";
+
 const router = Router();
 
 router.get("/", (_req, res) => {
   res.json({
-    data: [],
+    data: listUsers(),
     message: "User listing is not implemented yet."
   });
 });
 
 router.post("/", (req, res) => {
   res.status(201).json({
-    data: {
-      id: "stub-user-id",
-      ...req.body
-    },
+    data: createUser(req.body),
     message: "User creation is not implemented yet."
   });
 });

apps/api/src/services/userService.ts

@@ -0,0 +1,28 @@
+export type CreateUserInput = Record<string, unknown>;
+
+export type UserRecord = {
+  id: string;
+} & CreateUserInput;
+
+/**
+ * Returns the current user list.
+ *
+ * This service is a placeholder until persistence is added, so callers receive
+ * an empty collection while the route contract remains stable.
+ */
+export function listUsers(): UserRecord[] {
+  return [];
+}
+
+/**
+ * Builds a stub user record from the submitted request body.
+ *
+ * The generated ID makes the create-user route behave like a successful
+ * creation endpoint without requiring a database connection yet.
+ */
+export function createUser(input: CreateUserInput): UserRecord {
+  return {
+    id: "stub-user-id",
+    ...input
+  };
+}