@yuku123/z-frontend-common 0.2.9 → 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+<<<<<<< HEAD
+Copyright (c) 2026 z-opc-foundation‌
+=======
+Copyright (c) 2026 z-opc-foundation
+>>>>>>> 037d896 (feat: z-frontend-common 独立仓首版 1.0.0（lead 008 §1-§16 唯一承载仓）)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,59 +1,72 @@
-# @yuku123/z-frontend-common
+# z-frontend-common
 
-> z-opc 共享前端组件库 · React 19 + Ant Design 6
+> z-opc-foundation 全仓共享前端基座 —— lead 008《前端开发规范》§1-§16 的唯一承载仓。
 
-## 安装
+40+ 个 `z-*` 产品仓的 suit 通过同一份 AppLayout / LoginPage 获得一致的
+左菜单架子、登录流程与右上角用户组件；21 个 `<repo>-component` 的 services
+层消费同一份 axios 拦截器工厂。**改一处，全仓同步**。
 
-```bash
-npm install @yuku123/z-frontend-common
-# 国内用户加速
-# .npmrc: @yuku1231:registry=https://registry.npmmirror.com/
-```
-
-## 导出能力
+---
 
-### 组件
-- `AppLayout` — 统一布局（Sider + Header + Content）
-- `StatusTag` — 状态标签
-- `LoginPage` — 统一登录页
-- `ErrorBoundary` — React 错误边界
+## 基本信息
 
-### 请求工具
-- `request` — 默认实例（`baseURL=/api`，识别 `{code, data, message}` 后端响应）
-- `authRequest` — 同上（语义区分）
-- `createRequest({baseURL, tokenKey, userInfoKey, unauthorizedRedirect, timeout})` — 工厂
-- `setupInterceptors(instance, options)` — 自定义拦截器
+| 字段 | 值 |
+|------|-----|
+| 仓 | `z-opc-foundation/z-frontend-common`（本仓） |
+| npm 包 | `@yuku123/z-frontend-common`（scope 沿用 yuku123，与 0.1.x/0.2.x 旧线连续） |
+| 当前版本 | `1.0.0` —— 1.0 语义：§1-§16 规范化起点。0.1.x 是 pre-§16 形态；0.2.x 内嵌 react-dom 已废弃 |
+| 技术栈 | React 19 + antd 6 + react-router-dom 7 + Vite 6（lead 005 §3.0 版本线单一尺子） |
+| 产物 | ESM 单文件 `dist/index.js`；react / antd / @ant-design/icons / react-router-dom 全部 external |
+| axios | `dependencies` 内联（`_shared/` vendoring 时期的决策保留：避免消费方从无 node_modules 的目录解析 axios） |
 
-## 使用示例
-
-```jsx
-import { AppLayout, LoginPage, request } from '@yuku123/z-frontend-common'
+## 对外 API（与 0.1.1 完全兼容 + 三处升级）
 
-// 业务模块推荐：在 src/utils/request.js 写 2-10 行适配层
-import { createRequest } from '@yuku123/z-frontend-common'
-const request = createRequest({ baseURL: '/meta', tokenKey: 'token' })
-export default request
-```
+| 导出 | 说明 |
+|------|------|
+| `AppLayout` | **升级**：§1 sider 双模式品牌区（暗主题显式白字 / 折叠 36×36 圆角图标 + Tooltip）、§11 selectedKey 最长菜单前缀、§12 sider 顶 `产品名@版本`、§15 Header 48px + 1px 下边线、§16 `appUser` 右上角下拉（profile + 退出登录，`loginPath` 按 `menuItems[0].key` 自动推导可覆盖） |
+| `LoginPage` | **升级**：`mockAuth` 双模式 —— 传 `{username, password, user}` 走纯前端校验（CTC/SSO 接入前短期形态）；缺省走 `loginApi` 真实端点 |
+| `EmptyState`（占位） | 目录已建，组件下一波随 §2 列表页规范收口时进 |
+| `StatusTag` / `defaultStatusMap` | 0.1.1 契约原样保留 |
+| `ErrorBoundary` | 0.1.1 契约原样保留（antd Result 形态重绘） |
+| `createRequest(options)` | axios 实例工厂：`{baseURL='/api', timeout=10000, tokenKey, userInfoKey, unauthorizedRedirect}`；21 个 component 仓 services 层消费 |
+| `request` / `authRequest` | 预建实例（`createRequest()` 双份，0.1.1 契约） |
+| `setupInterceptors` | 拦截器装配（Bearer token 注入 + 401 清凭跳登录 + 响应解包） |
+| `unwrapResponse` | **新增显式导出**：`{code, data}` 包装解包 / 裸数据透传（z-opc Spring MVC 统一返回体兼容） |
+| `default`（桶） | `{AppLayout, StatusTag, defaultStatusMap, LoginPage, ErrorBoundary, request, authRequest, createRequest}` —— 0.1.1 形状原样 |
 
-## 统一后端响应格式
+## AppLayout props
 
-```json
-{ "code": 200, "data": T, "message": "ok" }
+```jsx
+<AppLayout
+    menuItems={menuConfig}        // antd Menu items，每项必须带 icon（§10）
+    appTitle="z-vector"           // sider 展开态文字
+    appShort="ZV"                 // 无 appIcon 时折叠态缩写
+    appVersion="1.0.5"            // §12：展开态渲染 z-vector@1.0.5（不要 "v" 前缀）
+    appIcon={{icon, color, label}} // §1：折叠态 36×36 圆角色板 + Tooltip
+    appUser={{name, role}}        // §16：右上角 Avatar+name+DownOutlined 下拉
+    loginPath="/z-vector/login"   // 可选，缺省按 menuItems[0].key 自动推导 /<产品>/login
+    headerExtra={<.../>}          // Header 右侧追加内容（版本号别放这，§12）
+    loading={false}               // 菜单区 loading 占位
+/>
 ```
 
-- `code=200` → 自动返回 `data`
-- 其他 code → reject
-- 响应无 `code` 字段 → pass-through 透传
+## suit 接入模板（lead 008 §16）
 
-## 长期方案
+```jsx
+import { AppLayout, LoginPage, ErrorBoundary } from '@yuku123/z-frontend-common'
+import { menuConfig, routes, appMeta } from '@yuku123/<repo>-component/pages'
 
-- 模板从 z-meta 拉取（数据库驱动）
-- 业务侧 `res.data.xxx` 写法统一
+const MOCK_AUTH = { username: 'admin', password: '123456', user: { name: 'admin', role: '管理员' } }
 
-## 仓库
+// <Route path="/<repo>/login" element={<LoginPage title="<repo> 管理台" mockAuth={MOCK_AUTH} redirectUrl="/<repo>/home" />} />
+// <Route element={<ProtectedShell/>}> 内挂 <AppLayout menuItems={menuConfig} appTitle={appMeta.title} appVersion="…" appUser={user} />
+```
 
-https://github.com/yuku123/z-opc/tree/main/z-frontend-common
+完整模板见 lead 008 §16；出厂自检清单见 §9。
 
-## License
+## 历史
 
-MIT
+- `0.1.0 – 0.1.6`：早期形态（pre-§16），源码曾位于 `yuku123/z-opc` 仓的 `z-frontend-common/` 子目录
+- `0.2.x`：内嵌 react-dom 的失败尝试线，已废弃
+- 应急过渡：`z-opc-foundation/_shared/z-frontend-common-local/` vendoring（不入 git，1.0.0 发版后退役）
+- `1.0.0`：独立仓首版 —— 源码自 vendoring 迁入，API 契约兼容 0.1.1，AppLayout/LoginPage 升级 §1-§16 规范版

package/dist/index.js

@@ -0,0 +1 @@
+import{Avatar as H,Button as j,Dropdown as W,Layout as R,Menu as N,Spin as J,Tooltip as A}from"antd";import{DownOutlined as G,LoginOutlined as Q,MenuFoldOutlined as X,MenuUnfoldOutlined as Y}from"@ant-design/icons";import{Outlet as Z,useLocation as _,useNavigate as U}from"react-router-dom";import{useState as V}from"react";import{jsx as o,jsxs as m}from"react/jsx-runtime";var{Header:ee,Sider:te,Content:re}=R;function oe(e,t=.85){let n=/^#?([0-9a-f]{6})$/i.exec(e||"");if(!n)return e;let l=parseInt(n[1],16),f=Math.max(0,Math.min(255,Math.round((l>>16&255)*t))),r=Math.max(0,Math.min(255,Math.round((l>>8&255)*t))),s=Math.max(0,Math.min(255,Math.round((l&255)*t)));return"#"+(f<<16|r<<8|s).toString(16).padStart(6,"0")}function L({menuItems:e=[],appTitle:t="One Company",appShort:n="OC",appVersion:l,appIcon:f,appUser:r,loginPath:s,headerExtra:v,loading:C=!1}){let[i,c]=V(!1),F=U(),$=_(),P=({key:d})=>{F(d)},M=()=>{if(s)return s;let d=e&&e[0],a=d&&d.key;return typeof a=="string"&&a.endsWith("/home")?a.slice(0,-4)+"login":"/login"},z=(d,a=[])=>{for(let u of d||[])u?.key&&a.push(u.key),u?.children&&z(u.children,a);return a},D=(()=>{let d=z(e),a=$.pathname;return d.filter(u=>a===u||a.startsWith(u+"/")).sort((u,b)=>b.length-u.length)[0]||a})();return m(R,{style:{minHeight:"100vh"},children:[m(te,{trigger:null,collapsible:!0,collapsed:i,children:[o("div",{style:{height:64,display:"flex",alignItems:"center",justifyContent:"center"},children:(()=>{if(i){if(f){let{icon:d,color:a="#7c3aed",label:u=t}=f,b=o("div",{style:{width:36,height:36,borderRadius:9,background:`linear-gradient(135deg, ${a}, ${oe(a,.7)})`,display:"flex",alignItems:"center",justifyContent:"center",color:"#fff",fontSize:20,boxShadow:"0 2px 6px rgba(0,0,0,0.25)",overflow:"hidden"},children:d});return o(A,{title:u,placement:"right",children:b})}return n}return m("span",{style:{color:"#fff",fontWeight:600,fontSize:16,whiteSpace:"nowrap"},children:[t,l&&m("span",{style:{color:"rgba(255,255,255,0.55)",fontWeight:400,fontSize:12,marginLeft:4},children:["@",l]})]})})()}),C?o("div",{style:{padding:16,textAlign:"center"},children:o(J,{size:"small"})}):o(N,{theme:"dark",mode:"inline",selectedKeys:[D],items:e,onClick:P})]}),m(R,{children:[m(ee,{style:{height:48,lineHeight:"48px",padding:"0 16px",background:"#fff",display:"flex",alignItems:"center",justifyContent:"space-between",borderBottom:"1px solid #f1f5f9"},children:[o("span",{onClick:()=>c(!i),style:{fontSize:18,cursor:"pointer"},children:i?o(Y,{}):o(X,{})}),m("div",{style:{display:"flex",alignItems:"center",gap:12},children:[r&&o(W,{menu:{items:[{key:"profile",label:`${r.name}\uFF08${r.role||"\u7528\u6237"}\uFF09`,disabled:!0},{type:"divider"},{key:"logout",label:"\u9000\u51FA\u767B\u5F55",onClick:()=>{localStorage.removeItem("token"),localStorage.removeItem("userInfo"),window.location.href=M()}}]},placement:"bottomRight",children:m("span",{style:{cursor:"pointer",display:"inline-flex",alignItems:"center",gap:6},children:[o(H,{size:28,style:{background:"#7c3aed"},children:(r.name||"?").slice(0,1).toUpperCase()}),o("span",{style:{fontSize:13,color:"#0f172a"},children:r.name}),o(G,{style:{fontSize:10,color:"#94a3b8"}})]})}),!r&&o(j,{type:"primary",size:"small",icon:o(Q,{}),onClick:()=>{window.location.href=M()},children:"\u767B\u5F55"}),v]})]}),o(re,{style:{margin:16,padding:24,background:"#fff",minHeight:280},children:o(Z,{})})]})]})}import{useState as se}from"react";import{Alert as ae,Button as ie,Card as le,Form as S,Input as K,message as h}from"antd";import{LockOutlined as fe,UserOutlined as ue}from"@ant-design/icons";import ne from"axios";import"antd";function B(e){return e&&typeof e=="object"&&"code"in e&&"data"in e?e.code!==200?Promise.reject(new Error(e.message||"\u8BF7\u6C42\u5931\u8D25")):e.data:e}function O(e,t={}){let{tokenKey:n="token",userInfoKey:l="userInfo",unauthorizedRedirect:f="/login"}=t;return e.interceptors.request.use(r=>{let s=localStorage.getItem(n);return s&&(r.headers.Authorization=`Bearer ${s}`),r}),e.interceptors.response.use(r=>B(r.data),r=>{let s=r.response?.status;return s===401?(localStorage.removeItem(n),localStorage.removeItem(l),window.location.href=f):s===403?console.error("\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u8BE5\u8D44\u6E90"):s===500&&console.error("\u670D\u52A1\u5668\u5185\u90E8\u9519\u8BEF"),Promise.reject(r)}),e}function y(e={}){let t=ne.create({baseURL:e.baseURL??"/api",timeout:e.timeout??1e4});return O(t,{tokenKey:e.tokenKey,userInfoKey:e.userInfoKey,unauthorizedRedirect:e.unauthorizedRedirect})}var x=y(),q=y();import{jsx as p,jsxs as T}from"react/jsx-runtime";function I({title:e="\u7EDF\u4E00\u7BA1\u7406\u5E73\u53F0",mockAuth:t,loginApi:n="/auth/login",redirectUrl:l="/",onSuccess:f}){let[r,s]=se(!1),v=i=>{localStorage.setItem("token",t?"mock-"+t.username:i?.token||"token"),localStorage.setItem("userInfo",JSON.stringify(i||{})),h.success("\u767B\u5F55\u6210\u529F"+(t?"\uFF08mock \u6A21\u5F0F\uFF0C\u5F85 CTC/SSO \u63A5\u5165\uFF09":"")),f?f(i):window.location.href=l},C=async i=>{s(!0);try{if(t){i.username===t.username&&i.password===t.password?v(t.user):h.error("\u7528\u6237\u540D\u6216\u5BC6\u7801\u9519\u8BEF");return}let c=await x.post(n,i);c?.token?(localStorage.setItem("token",c.token),localStorage.setItem("userInfo",JSON.stringify(c.user||c)),h.success("\u767B\u5F55\u6210\u529F"),f?f(c):window.location.href=l):h.error("\u767B\u5F55\u5931\u8D25\uFF1A\u672A\u83B7\u53D6\u5230 token")}catch(c){h.error(c.response?.data?.message||c.message||"\u767B\u5F55\u5931\u8D25")}finally{s(!1)}};return p("div",{style:{height:"100vh",display:"flex",justifyContent:"center",alignItems:"center",background:"#f0f2f5"},children:T(le,{title:e,style:{width:400},children:[t&&p(ae,{type:"info",showIcon:!0,style:{marginBottom:16},message:`Mock \u6A21\u5F0F\uFF1A\u7528\u6237\u540D ${t.username} / \u5BC6\u7801 ${t.password}`}),T(S,{onFinish:C,size:"large",children:[p(S.Item,{name:"username",rules:[{required:!0,message:"\u8BF7\u8F93\u5165\u7528\u6237\u540D"}],children:p(K,{prefix:p(ue,{}),placeholder:"\u7528\u6237\u540D"})}),p(S.Item,{name:"password",rules:[{required:!0,message:"\u8BF7\u8F93\u5165\u5BC6\u7801"}],children:p(K.Password,{prefix:p(fe,{}),placeholder:"\u5BC6\u7801"})}),p(S.Item,{children:p(ie,{type:"primary",htmlType:"submit",loading:r,block:!0,children:"\u767B \u5F55"})})]})]})})}import{Tag as ce}from"antd";import{jsx as de}from"react/jsx-runtime";var w={1:{color:"green",text:"\u6B63\u5E38"},0:{color:"red",text:"\u7981\u7528"},pending:{color:"orange",text:"\u5F85\u5904\u7406"},approved:{color:"blue",text:"\u5DF2\u901A\u8FC7"},rejected:{color:"red",text:"\u5DF2\u62D2\u7EDD"}};function k({status:e,map:t}){let n=t?.[e]||w[e]||{color:"default",text:String(e)};return de(ce,{color:n.color,children:n.text})}import{Component as pe}from"react";import{Button as me,Result as ge}from"antd";import{jsx as E}from"react/jsx-runtime";var g=class extends pe{constructor(t){super(t),this.state={hasError:!1,error:null,errorInfo:null},this.handleReset=()=>{this.setState({hasError:!1,error:null,errorInfo:null}),typeof this.props.onReset=="function"&&this.props.onReset()}}static getDerivedStateFromError(t){return{hasError:!0,error:t}}componentDidCatch(t,n){console.error("[ErrorBoundary] caught error:",t,n),this.setState({errorInfo:n})}render(){return this.state.hasError?E(ge,{status:"error",title:"\u9875\u9762\u51FA\u9519\u4E86",subTitle:String(this.state.error?.message||this.state.error),extra:E(me,{type:"primary",onClick:this.handleReset,children:"\u91CD\u8BD5"})}):this.props.children}};var Ae={AppLayout:L,StatusTag:k,defaultStatusMap:w,LoginPage:I,ErrorBoundary:g,request:x,authRequest:q,createRequest:y};export{L as AppLayout,g as ErrorBoundary,I as LoginPage,k as StatusTag,q as authRequest,y as createRequest,Ae as default,w as defaultStatusMap,x as request,O as setupInterceptors,B as unwrapResponse};

package/package.json

@@ -1,64 +1,69 @@
 {
   "name": "@yuku123/z-frontend-common",
-  "version": "0.2.9",
-  "private": false,
-  "description": "z-opc 共享前端组件库 - AppLayout / StatusTag / LoginPage / ErrorBoundary + 统一 createRequest 工厂",
-  "keywords": [
-    "react",
-    "antd",
-    "vite",
-    "frontend",
-    "z-opc"
-  ],
-  "license": "MIT",
-  "author": {
-    "name": "zifang",
-    "email": "1340947819@qq.com"
-  },
-  "homepage": "https://github.com/yuku123/z-opc-frontend/tree/main/packages/z-frontend-common#readme",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/yuku123/z-opc-frontend.git",
-    "directory": "packages/z-frontend-common"
-  },
-  "bugs": {
-    "url": "https://github.com/yuku123/z-opc-frontend/issues"
-  },
-  "main": "./dist/z-frontend-common.umd.js",
-  "module": "./dist/z-frontend-common.es.js",
+  "version": "1.0.0",
+  "description": "z-opc 全仓共享前端基座 — AppLayout(§1/§11/§12/§15/§16) + LoginPage(mockAuth 双模式) + EmptyState/StatusTag/ErrorBoundary + createRequest 工厂。lead 008 前端开发规范唯一承载仓",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/z-frontend-common.es.js",
-      "require": "./dist/z-frontend-common.umd.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist",
-    "src",
-    "README.md"
+    "src"
   ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
   "scripts": {
-    "dev": "vite --port 3099",
     "build": "vite build",
-    "preview": "vite preview"
-  },
-  "peerDependencies": {
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "antd": "^6.3.3",
-    "react-router-dom": "^7.13.1"
+    "dev": "vite build --watch",
+    "prepublishOnly": "vite build"
   },
   "dependencies": {
     "axios": "^1.16.1"
   },
+  "peerDependencies": {
+    "@ant-design/icons": "^6.0.0",
+    "antd": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0"
+  },
   "devDependencies": {
+    "@ant-design/icons": "^6.1.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
     "@vitejs/plugin-react": "^4.2.1",
-    "vite": "^6.2.0"
+    "antd": "^6.3.3",
+    "axios": "^1.16.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.13.1",
+    "vite": "^6.2.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/z-opc-foundation/z-frontend-common.git"
   },
-  "style": "./dist/z-frontend-common.css"
+  "bugs": {
+    "url": "https://github.com/z-opc-foundation/z-frontend-common/issues"
+  },
+  "homepage": "https://github.com/z-opc-foundation/z-frontend-common#readme",
+  "keywords": [
+    "react",
+    "antd",
+    "vite",
+    "z-opc",
+    "frontend-common",
+    "applayout",
+    "admin-shell"
+  ],
+  "author": "yuku123",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
 }

package/src/components/ErrorBoundary/index.jsx

@@ -1,93 +1,40 @@
-import React from 'react'
-import {Alert, Button, Space} from 'antd'
-import {BugOutlined, ReloadOutlined} from '@ant-design/icons'
+import { Component } from 'react'
+import { Button, Result } from 'antd'
 
 /**
- * React Error Boundary — 捕获子组件的 render/lifecycle/effect 异常，
- * 用 fallback UI 替代冒泡到整棵 React 树导致整体卸载。
- *
- * 用法：
- *   <ErrorBoundary fallbackTitle="流程编辑器加载失败">
- *     <WorkflowEditor />
- *   </ErrorBoundary>
+ * 兜底错误边界（0.1.1 契约保留）：render 崩了显示错误 + 重置按钮。
+ * props: children + 可选 onReset（点「重试」时回调，缺省只清内部态）。
  */
-export default class ErrorBoundary extends React.Component {
+export default class ErrorBoundary extends Component {
     constructor(props) {
         super(props)
-        this.state = {hasError: false, error: null, errorInfo: null}
+        this.state = { hasError: false, error: null, errorInfo: null }
+        this.handleReset = () => {
+            this.setState({ hasError: false, error: null, errorInfo: null })
+            typeof this.props.onReset === 'function' && this.props.onReset()
+        }
     }
 
     static getDerivedStateFromError(error) {
-        return {hasError: true, error}
-    }
-
-    componentDidCatch(error, errorInfo) {
-        // eslint-disable-next-line no-console
-        console.error('[ErrorBoundary] caught error:', error, errorInfo)
-        this.setState({errorInfo})
+        return { hasError: true, error }
     }
 
-    handleReset = () => {
-        this.setState({hasError: false, error: null, errorInfo: null})
-        if (typeof this.props.onReset === 'function') {
-            this.props.onReset()
-        }
+    componentDidCatch(error, info) {
+        console.error('[ErrorBoundary] caught error:', error, info)
+        this.setState({ errorInfo: info })
     }
 
     render() {
-        if (!this.state.hasError) {
-            return this.props.children
-        }
-
-        const {fallbackTitle = '组件加载失败', fallbackDescription, showReload = true} = this.props
-        const errMsg = (this.state.error && (this.state.error.message || String(this.state.error))) || '未知错误'
-
-        return (
-            <div
-                style={{
-                    padding: 24,
-                    background: '#fff2f0',
-                    border: '1px solid #ffccc7',
-                    borderRadius: 8,
-                    minHeight: 200,
-                }}
-            >
-                <Alert
-                    type="error"
-                    showIcon
-                    icon={<BugOutlined/>}
-                    message={fallbackTitle}
-                    description={
-                        <div>
-                            <div style={{marginBottom: 8}}>
-                                {fallbackDescription || '当前组件发生了异常，已被错误边界捕获。其他功能仍可正常使用。'}
-                            </div>
-                            <div
-                                style={{
-                                    fontFamily: 'Menlo, Monaco, Consolas, monospace',
-                                    fontSize: 12,
-                                    color: '#cf1322',
-                                    background: '#fff',
-                                    padding: 8,
-                                    borderRadius: 4,
-                                    border: '1px solid #ffccc7',
-                                    wordBreak: 'break-word',
-                                    whiteSpace: 'pre-wrap',
-                                }}
-                            >
-                                {errMsg}
-                            </div>
-                        </div>
-                    }
+        if (this.state.hasError) {
+            return (
+                <Result
+                    status="error"
+                    title="页面出错了"
+                    subTitle={String(this.state.error?.message || this.state.error)}
+                    extra={<Button type="primary" onClick={this.handleReset}>重试</Button>}
                 />
-                {showReload && (
-                    <Space style={{marginTop: 16}}>
-                        <Button icon={<ReloadOutlined/>} onClick={this.handleReset}>
-                            重试
-                        </Button>
-                    </Space>
-                )}
-            </div>
-        )
+            )
+        }
+        return this.props.children
     }
 }

package/src/components/Layout/index.jsx

@@ -1,69 +1,172 @@
-import {Layout, Menu, Spin} from 'antd'
-import {MenuFoldOutlined, MenuUnfoldOutlined} from '@ant-design/icons'
-import {Outlet, useLocation, useNavigate} from 'react-router-dom'
-import {useState} from 'react'
+import { Avatar, Button, Dropdown, Layout, Menu, Spin, Tooltip } from 'antd'
+import { DownOutlined, LoginOutlined, MenuFoldOutlined, MenuUnfoldOutlined } from '@ant-design/icons'
+import { Outlet, useLocation, useNavigate } from 'react-router-dom'
+import { useState } from 'react'
 
-const {Header, Sider, Content} = Layout
+const { Header, Sider, Content } = Layout
+
+function shade(hex, amount = 0.85) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex || '')
+    if (!m) return hex
+    const n = parseInt(m[1], 16)
+    const r = Math.max(0, Math.min(255, Math.round(((n >> 16) & 0xff) * amount)))
+    const g = Math.max(0, Math.min(255, Math.round(((n >> 8) & 0xff) * amount)))
+    const b = Math.max(0, Math.min(255, Math.round((n & 0xff) * amount)))
+    return '#' + ((r << 16) | (g << 8) | b).toString(16).padStart(6, '0')
+}
 
 /**
- * 统一布局组件
- * @param {Object} props
- * @param {Array} props.menuItems - antd Menu items 格式
- * @param {string} props.appTitle - 应用标题
- * @param {string} props.appShort - 折叠时标题缩写
- * @param {ReactNode} props.headerExtra - 头部右侧额外内容
- * @param {boolean} props.loading - 是否加载中
+ * 通用左菜单架子 AppLayout — lead 008 §1/§11/§12/§15/§16 全 46 仓 suit 强制落地。
+ *
+ * props:
+ *   - menuItems / appTitle / appShort / appIcon / headerExtra / loading: 同 z-vector-component 原版
+ *   - appVersion?: string — sider 展开态展示「z-vector@1.0.5」格式
+ *   - appUser?: { name, role } — Header 右上角 avatar+name+下拉（profile/退出登录）
+ *   - loginPath?: string — 退出登录跳转目标，缺省按 menuItems[0].key 自动推导（/home → /login）
  */
-export default function AppLayout({
-                                      menuItems = [],
-                                      appTitle = 'One Company',
-                                      appShort = 'OC',
-                                      headerExtra,
-                                      loading = false,
-                                  }) {
+export function AppLayout({
+                             menuItems = [],
+                             appTitle = 'One Company',
+                             appShort = 'OC',
+                             appVersion,
+                             appIcon,
+                             appUser,
+                             loginPath,
+                             headerExtra,
+                             loading = false,
+                         }) {
     const [collapsed, setCollapsed] = useState(false)
     const navigate = useNavigate()
     const location = useLocation()
 
-    const handleMenuClick = ({key}) => {
-        navigate(key)
+    const handleMenuClick = ({ key }) => { navigate(key) }
+
+    // 退出登录跳转：loginPath 显式传优先；否则按 menuItems[0].key 自动推导 /<产品>/home → /<产品>/login
+    const computeLoginPath = () => {
+        if (loginPath) return loginPath
+        const first = menuItems && menuItems[0]
+        const k = first && first.key
+        if (typeof k === 'string' && k.endsWith('/home')) {
+            return k.slice(0, -4) + 'login'
+        }
+        return '/login'
+    }
+
+    // URL 即状态（lead 008 §11）：用 location.pathname 的最长菜单前缀作 selectedKey
+    const collectKeys = (items, acc = []) => {
+        for (const it of items || []) {
+            if (it?.key) acc.push(it.key)
+            if (it?.children) collectKeys(it.children, acc)
+        }
+        return acc
+    }
+    const selectedKey = (() => {
+        const keys = collectKeys(menuItems)
+        const p = location.pathname
+        return keys.filter((k) => p === k || p.startsWith(k + '/'))
+            .sort((a, b) => b.length - a.length)[0] || p
+    })()
+
+    const renderBrand = () => {
+        if (collapsed) {
+            if (appIcon) {
+                const { icon, color = '#7c3aed', label = appTitle } = appIcon
+                const node = (
+                    <div style={{
+                        width: 36, height: 36, borderRadius: 9,
+                        background: `linear-gradient(135deg, ${color}, ${shade(color, 0.7)})`,
+                        display: 'flex', alignItems: 'center', justifyContent: 'center',
+                        color: '#fff', fontSize: 20, boxShadow: '0 2px 6px rgba(0,0,0,0.25)',
+                        overflow: 'hidden',
+                    }}>{icon}</div>
+                )
+                return <Tooltip title={label} placement="right">{node}</Tooltip>
+            }
+            return appShort
+        }
+        return (
+            <span style={{ color: '#fff', fontWeight: 600, fontSize: 16, whiteSpace: 'nowrap' }}>
+                {appTitle}
+                {appVersion && (
+                    <span style={{
+                        color: 'rgba(255,255,255,0.55)', fontWeight: 400, fontSize: 12, marginLeft: 4,
+                    }}>@{appVersion}</span>
+                )}
+            </span>
+        )
     }
 
     return (
-        <Layout style={{minHeight: '100vh'}}>
+        <Layout style={{ minHeight: '100vh' }}>
             <Sider trigger={null} collapsible collapsed={collapsed}>
                 <div style={{
                     height: 64, display: 'flex', alignItems: 'center', justifyContent: 'center',
-                    color: 'white', fontSize: collapsed ? 14 : 18, fontWeight: 'bold',
                 }}>
-                    {collapsed ? appShort : appTitle}
+                    {renderBrand()}
                 </div>
                 {loading ? (
-                    <div style={{padding: 16, textAlign: 'center'}}>
-                        <Spin size="small"/>
-                    </div>
+                    <div style={{ padding: 16, textAlign: 'center' }}><Spin size="small" /></div>
                 ) : (
-                    <Menu theme="dark" mode="inline"
-                          selectedKeys={[location.pathname]}
-                          items={menuItems}
-                          onClick={handleMenuClick}
+                    <Menu
+                        theme="dark"
+                        mode="inline"
+                        selectedKeys={[selectedKey]}
+                        items={menuItems}
+                        onClick={handleMenuClick}
                     />
                 )}
             </Sider>
             <Layout>
                 <Header style={{
-                    padding: '0 16px', background: '#fff',
+                    height: 48, lineHeight: '48px', padding: '0 16px', background: '#fff',
                     display: 'flex', alignItems: 'center', justifyContent: 'space-between',
+                    borderBottom: '1px solid #f1f5f9',
                 }}>
-          <span onClick={() => setCollapsed(!collapsed)} style={{fontSize: 18, cursor: 'pointer'}}>
-            {collapsed ? <MenuUnfoldOutlined/> : <MenuFoldOutlined/>}
-          </span>
-                    {headerExtra}
+                    <span onClick={() => setCollapsed(!collapsed)} style={{ fontSize: 18, cursor: 'pointer' }}>
+                        {collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+                    </span>
+                    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+                        {appUser && (
+                            <Dropdown
+                                menu={{
+                                    items: [
+                                        { key: 'profile', label: `${appUser.name}（${appUser.role || '用户'}）`, disabled: true },
+                                        { type: 'divider' },
+                                        {
+                                            key: 'logout', label: '退出登录', onClick: () => {
+                                                localStorage.removeItem('token')
+                                                localStorage.removeItem('userInfo')
+                                                window.location.href = computeLoginPath()
+                                            },
+                                        },
+                                    ],
+                                }}
+                                placement="bottomRight"
+                            >
+                                <span style={{ cursor: 'pointer', display: 'inline-flex', alignItems: 'center', gap: 6 }}>
+                                    <Avatar size={28} style={{ background: '#7c3aed' }}>
+                                        {(appUser.name || '?').slice(0, 1).toUpperCase()}
+                                    </Avatar>
+                                    <span style={{ fontSize: 13, color: '#0f172a' }}>{appUser.name}</span>
+                                    <DownOutlined style={{ fontSize: 10, color: '#94a3b8' }} />
+                                </span>
+                            </Dropdown>
+                        )}
+                        {!appUser && (
+                            <Button type="primary" size="small" icon={<LoginOutlined />}
+                                    onClick={() => { window.location.href = computeLoginPath() }}>
+                                登录
+                            </Button>
+                        )}
+                        {headerExtra}
+                    </div>
                 </Header>
-                <Content style={{margin: 16, padding: 24, background: '#fff', minHeight: 280}}>
-                    <Outlet/>
+                <Content style={{ margin: 16, padding: 24, background: '#fff', minHeight: 280 }}>
+                    <Outlet />
                 </Content>
             </Layout>
         </Layout>
     )
 }
+
+export default AppLayout