@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/blank/apps/api/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@app/api",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/main.js",
+    "worker": "node dist/worker.js"
+  },
+  "dependencies": {
+    "@app/domain": "workspace:*",
+    "@yss123/cage-http": "0.3.0"
+  }
+}

package/templates/blank/apps/api/src/main.ts

@@ -0,0 +1,14 @@
+// 业务声明决定接口。这个入口只装配框架，不需要另建连接池或手写 CRUD 路由。
+// 数据库连接由框架读取项目 .env；生产环境的 WEB_DIR 指向前端构建目录。
+// 初始化组织和数据库迁移必须在独立受控步骤完成，启动服务不会自动创建管理员或授予业务能力。
+import { createServer } from '@yss123/cage-http';
+import * as domain from '@app/domain';
+
+// 默认不接受转发头；部署在代理后时，仅在这里填写实际可信代理的地址或网段。
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 业务工作台', trustProxy: false });
+// 等待安全插件、生成路由和扩展就绪后才监听；异步事件和任务另由 worker 入口执行。
+await server.listen();
+
+// 退出时释放连接池及数据库通知连接，便于部署时平滑替换进程。
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());

package/templates/blank/apps/api/src/worker.ts

@@ -0,0 +1,10 @@
+// worker 处理框架异步任务；增加事件反应、审批或数据导入导出后也沿用此入口。
+// 空白项目没有第三方演示连接器，真实外部服务按业务需求声明和配置。
+// API 与 worker 必须加载同版本 domain；框架统一负责消费者发现、轮询、租约、重试及定时调度。
+import { startWorker } from '@yss123/cage-http/worker';
+import * as domain from '@app/domain';
+
+// 不在入口重复创建连接池或自行扫表；停止句柄等待在途工作并释放框架资源。
+const worker = await startWorker({ domain });
+process.once('SIGINT', () => void worker.stop());
+process.once('SIGTERM', () => void worker.stop());

package/templates/blank/apps/api/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

package/templates/blank/apps/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<!-- 浏览器文档外壳：提供 React 挂载节点与模块入口；业务路由、会话及数据加载由 src/main.tsx 装配的应用处理。 -->
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="theme-color" content="#173e35" />
+    <title>Cage · 业务工作台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/blank/apps/web/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@app/web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "@tanstack/react-query": "^5.87.1",
+    "@yss123/cage-client": "0.3.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.5",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.4"
+  }
+}

package/templates/blank/apps/web/src/app/app.tsx

@@ -0,0 +1,106 @@
+/**
+ * 空白应用的路由组合层，连接登录、工作台和成员目录的公开模块入口。
+ * 先恢复会话，再按 URL 展示页面；认证失败与网络错误分开处理，保留可回跳的原始地址。
+ * 新业务路由在此组合到 Outlet，模块内部实现不直接跨目录互相导入。
+ */
+// 页面身份交给 React Router；会话恢复、布局和业务模块在应用层组合。
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
+import { LoginPage } from '../modules/auth';
+import { HomePage } from '../modules/workspace';
+import { UsersPage, UserDetailPage } from '../modules/directory';
+import { Brand } from '../shared/ui/brand';
+import { PageState } from '../shared/ui/page-state';
+import { RequireCapability } from '../shared/ui/require-capability';
+import { loginReturnTo } from '../shared/lib/navigation';
+import { useSession } from './use-session';
+import { WorkspaceLayout } from './workspace-layout';
+
+/**
+ * 安装 BrowserRouter 作为页面身份来源；生产服务器须为业务深链接提供 SPA 回退。
+ */
+export function App() {
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  );
+}
+
+/**
+ * 依据 useSession 的加载、未认证、就绪和故障状态生成路由。
+ * 登录回跳经 loginReturnTo 验证；成员列表和详情要求 User.read，未知路径呈现独立 404 状态。
+ * 前端守卫只控制交互，成员的可见范围和字段掩码仍由服务端执行。
+ */
+function AppRoutes() {
+  const { session, restore, onLogin, onLogout } = useSession();
+  const location = useLocation();
+
+  if (session === 'loading')
+    return (
+      <main className="session-state" role="status">
+        <Brand />
+        <p>正在打开工作空间…</p>
+      </main>
+    );
+  if (session === 'error')
+    return (
+      <main className="session-state">
+        <Brand />
+        <h1>暂时无法连接工作台</h1>
+        <p role="alert">请检查网络和 API 服务，然后重新尝试。</p>
+        <button className="primary" onClick={restore}>
+          重新连接<span aria-hidden="true">↗</span>
+        </button>
+      </main>
+    );
+  const login = `/login?returnTo=${encodeURIComponent(location.pathname + location.search + location.hash)}`;
+  return (
+    <Routes>
+      <Route
+        path="/login"
+        element={
+          session === 'ready' ? (
+            <Navigate to={loginReturnTo(location.search, '/workspace')} replace />
+          ) : (
+            <LoginPage onLogin={onLogin} />
+          )
+        }
+      />
+      <Route
+        element={
+          session === 'ready' ? <WorkspaceLayout onLogout={onLogout} /> : <Navigate to={login} replace />
+        }
+      >
+        <Route index element={<Navigate to="/workspace" replace />} />
+        <Route path="workspace" element={<HomePage />} />
+        <Route
+          path="directory/users"
+          element={
+            <RequireCapability capability="User.read" home="/workspace">
+              <UsersPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="directory/users/:id"
+          element={
+            <RequireCapability capability="User.read" home="/workspace">
+              <UserDetailPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="*"
+          element={
+            <PageState
+              title="页面不存在"
+              description="请检查地址，或从工作空间导航进入已有页面。"
+              to="/workspace"
+              label="返回工作台"
+            />
+          }
+        />
+      </Route>
+    </Routes>
+  );
+}