@yuku123/z-frontend-common 0.2.9 → 1.1.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 规范版