feat(server): 增加根路径服务首页，完善文档中的访问地址说明

README.md

@@ -99,11 +99,17 @@ pnpm dev
 
 启动后访问：
 
-| 服务               | 地址                             |
+| 服务                                       | 地址                             |
-| ------------------ | -------------------------------- |
+| ------------------------------------------ | -------------------------------- |
-| Web 管理端（开发） | http://127.0.0.1:5173            |
+| Web 管理端（开发）                         | http://127.0.0.1:5173            |
-| 后端 API           | http://127.0.0.1:4000/api        |
+| 后端服务首页（浏览器可读，列出已挂载模块） | http://127.0.0.1:4000            |
-| 健康检查           | http://127.0.0.1:4000/api/health |
+| 后端 API                                   | http://127.0.0.1:4000/api        |
+| 健康检查                                   | http://127.0.0.1:4000/api/health |
+
+> 后端只提供 REST API 与 WebSocket，没有业务网页界面。直接访问
+> `http://127.0.0.1:4000/` 会返回服务首页（带 `Accept: application/json` 时返回结构化信息）；
+> 其它未匹配路径统一返回 `{ "success": false, "code": "NOT_FOUND" }`。
+> Web 管理端地址是 **5173** 端口，请勿访问 80 端口（会连接被拒绝）。
 
 也可以分开启动：`pnpm dev:server`（仅后端）、`pnpm dev:web`（仅 Web 端）。
 

packages/server/src/app.ts

@@ -25,6 +25,55 @@ async function healthHandler(_req: Request, res: Response): Promise<void> {
   );
 }
 
+/**
+ * 根路径落地页。
+ * API 全部挂在 /api 下，根路径本身不是接口；这里给出一个可读的服务首页，
+ * 避免浏览器直接访问 4000 端口时看到 404 JSON 而误以为服务没起来。
+ */
+function renderLandingPage(): string {
+  const moduleRows = apiModules
+    .map((module) => `<li><code>${API_PREFIX}${module.basePath}</code> <span>${module.name}</span></li>`)
+    .join('');
+  return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>班级小助手 · 后端服务</title>
+    <style>
+      body { margin: 0; padding: 40px; font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; background: #f5f7fa; color: #303133; }
+      .card { max-width: 720px; margin: 0 auto; background: #fff; border: 1px solid #e4e7ed; border-radius: 12px; padding: 28px 32px; }
+      h1 { margin: 0 0 6px; font-size: 20px; }
+      p.sub { margin: 0 0 20px; color: #909399; font-size: 13px; }
+      .ok { display: inline-block; padding: 2px 10px; border-radius: 999px; background: #f0f9eb; color: #67c23a; font-size: 12px; }
+      ul { columns: 2; padding-left: 18px; margin: 12px 0 0; }
+      li { margin: 6px 0; font-size: 13px; }
+      li span { color: #c0c4cc; }
+      code { background: #f5f7fa; padding: 1px 6px; border-radius: 4px; font-size: 12px; }
+      a { color: #409eff; text-decoration: none; }
+      .hint { margin-top: 22px; padding-top: 16px; border-top: 1px dashed #e4e7ed; font-size: 13px; color: #606266; line-height: 1.9; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>班级小助手 · 后端服务 <span class="ok">running</span></h1>
+      <p class="sub">版本 0.1.0 · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
+      <p class="sub">
+        健康检查：<a href="${API_PREFIX}/health">${API_PREFIX}/health</a> ·
+        管理端开发地址：<a href="http://127.0.0.1:5173">http://127.0.0.1:5173</a>
+      </p>
+      <strong>已挂载模块（${apiModules.length} 个）</strong>
+      <ul>${moduleRows}</ul>
+      <div class="hint">
+        提示：本服务只提供 REST API 与 WebSocket，没有网页界面。<br />
+        网页界面请访问 Web 管理端 <code>http://127.0.0.1:5173</code>（pnpm dev:web），
+        WebSocket 端点为 <code>ws://127.0.0.1:${env.port}/socket.io</code>。
+      </div>
+    </div>
+  </body>
+</html>`;
+}
+
 /** 组装 Express 应用：中间件 -> 健康检查 -> 模块路由 -> 404 -> 统一错误处理 */
 export function createApp(): Express {
   const app = express();
@@ -39,6 +88,31 @@ export function createApp(): Express {
     next();
   });
 
+  // 服务首页（浏览器可读）；如果客户端显式要 JSON，则返回结构化信息
+  app.get('/', (req, res) => {
+    if (req.accepts(['html', 'json']) === 'json') {
+      sendOk(
+        res,
+        {
+          service: 'class-helper-server',
+          version: '0.1.0',
+          apiPrefix: API_PREFIX,
+          webAdmin: 'http://127.0.0.1:5173',
+          socket: `/socket.io`,
+          modules: apiModules.map((module) => `${API_PREFIX}${module.basePath}`),
+        },
+        '服务运行正常，API 前缀为 /api',
+      );
+      return;
+    }
+    res.type('html').send(renderLandingPage());
+  });
+
+  // 浏览器会自动请求 favicon，直接返回 204，避免污染日志
+  app.get('/favicon.ico', (_req, res) => {
+    res.status(204).end();
+  });
+
   // 健康检查（同时暴露已挂载模块列表，便于确认模块化装配结果）
   app.get(`${API_PREFIX}/health`, healthHandler);
   app.get('/health', healthHandler);