System_Management/docs/guide.md

通用系统管理脚手架 · 开发帮助手册

面向 fork 本工程进行二次开发的工程师。读完能跑起来、能看懂结构、能照着新增功能。 更底层的架构与 spec 约定见 docs/architecture.md、docs/spec-conventions.md，工作流见根目录 CLAUDE.md。

---

0. 功能介绍与功能清单

一套可 fork 的「通用系统管理脚手架」：开箱即用后台基础能力，fork 后只改业务、不重复造轮子。后端 NestJS + Prisma + MySQL，前端 Vue 3 + Vite + Pinia + UnoCSS。

功能块	说明
认证	登录 / 登出；JWT（access 2h + refresh 7d），401 自动刷新；首登强制改密；注册/忘记密码默认隐藏（showRegister/showForgetPassword 可开启）
权限管理	用户（增删改/重置密码/启停/锁定解锁）、角色（分配资源 + 数据权限）、资源（菜单/按钮/接口统一资源树）、组织（部门树）
系统管理	租户、字典（类型 + 项，支持内置保护）、参数配置（键值）
系统监控	操作日志、登录日志（只读查询）、在线会话（强退单会话 / 踢全部）
布局与主题	多布局（左右 / 上下 / 纯上下 + MixBar）、暗黑模式、主题色、多页签（keep-alive 状态保留）、面包屑、全屏
平台能力	多租户隔离（tenantCode）、RBAC（资源表统一授权 + 数据权限 data_scope）、审计日志落库、字典驱动渲染

代码规范：本工程用 openspec 追踪需求与变更（spec-driven），新增功能走 propose → apply → archive 流程，见 CLAUDE.md。本文只讲「代码怎么改」，不讲「流程怎么走」。

---

1. 快速开始

1.1 环境要求

依赖	版本
Node	22.23.1（以 .nvmrc / engines 为准）
pnpm	12.10.1（以 packageManager 为准）
MySQL	8.x
Redis	6+

1.2 拉取与安装

git clone <仓库地址> && cd <目录>
git submodule update --init --recursive   # 拉取 sysmgr-nest / sysmgr-admin

# 后端
cd sources/sysmgr-nest
cp .env.example .env                       # 若无 .env.example 则手建，见下
pnpm install
npx prisma migrate deploy                  # 应用已有迁移（开发期可用 migrate dev）
pnpm seed                                  # 初始化租户/用户/角色/资源/内置字典

# 前端
cd ../sysmgr-admin
pnpm install

1.3 .env（后端）

DATABASE_URL="mysql://root:密码@127.0.0.1:3306/sysmgr"
REDIS_HOST="127.0.0.1"
REDIS_PORT=6379
REDIS_DB=0
REDIS_KEY_PREFIX="sysmgr:"
JWT_SECRET="请替换为强密钥（生产至少 32 位）"
JWT_ACCESS_TTL=7200
JWT_REFRESH_TTL=604800
PORT=3000

1.4 启动

# 后端（:3000，全局前缀 /api/v1）
cd sources/sysmgr-nest && pnpm start:dev

# 前端（Vite，直连 VITE_API_BASE_URL，默认 http://localhost:3000/api/v1，见 .env）
cd sources/sysmgr-admin && pnpm dev:dev

1.5 默认账号

项	值
租户	touyun
用户名	touyun
密码	Touyun@123
角色	super_admin（超管，绕过权限校验、数据权限看全量）

---

2. 后端开发指南（sysmgr-nest）

2.1 目录与分层

src/
├── auth/          # 认证：登录/刷新/登出、菜单树、JWT 守卫、权限守卫、装饰器、请求上下文
├── users/ roles/ resources/ orgs/ dicts/ configs/ tenants/ audit-logs/ login-logs/ sessions/
│                  # 每个域一个目录：<name>.module.ts / controller / service / dto
├── prisma/        # PrismaService：统一注入多租户过滤 + 软删过滤
├── common/        # BaseCrudService、enums、permissions、page.dto、拦截器/过滤器、Redis
└── logging/       # pino 日志、请求体日志拦截器

每个域遵循同构结构（以 tenants 为例）：

tenants/
├── tenants.module.ts      # 声明 controller + service
├── tenants.controller.ts  # 路由 + @RequirePermissions + @AuditLog
├── tenants.service.ts     # extends BaseCrudService，写业务
└── dto.ts                 # class-validator DTO（创建/更新/查询）

2.2 Prisma 约定

• 表名 sys_ 前缀，列名 snake_case（模型 camelCase + @map）。
• 主键 UUID v7：id String @id @default(uuid(7)) @db.VarChar(36)。
• 业务键关联用 code（角色/资源/组织/字典/租户），引用用户用 id，树引用用 parent_code。
• 业务软删实体带 created_at / created_by / updated_at / deleted_at；日志/会话实体无 deleted_at。
• 多租户：业务实体一律带 tenant_code。

2.3 BaseCrudService + PrismaService

所有域 service 继承 BaseCrudService(prisma, '模型名')，直接获得：

方法	说明
paginate(page, pageSize, where?, orderBy?)	分页，返回 { list, total, page, pageSize }
list(where?, orderBy?)	列表
findById(id)	按 id 查
create(data)	创建，自动注入 tenantCode（Tenant 除外）
update(id, data)	更新
softRemove(id)	软删（置 deletedAt）

PrismaService 通过 $extends 全局拦截，无需手写：

• 读操作自动追加 tenantCode 过滤（Tenant 模型除外）；
• 软删模型（User/Role/Resource/Org/DictType/DictItem/Config）读操作自动追加 deletedAt: null。

因此业务 service 里写 this.list({ status: 'enabled' }) 即可，租户与软删已由框架兜底。

2.4 RBAC：资源表统一授权

• 菜单、按钮、接口统一在 resource 表，type ∈ { menu, button, api }。
• api/button 型资源的 code 即权限码，形如 domain:action（user:list、user:create）。
• 权限码清单在 src/common/permissions.ts，控制器与 seed 共用。

三级鉴权（由全局 JwtAuthGuard + PermissionsGuard 实现）：

层级	写法	效果
公开	@Public()	无需 token
仅登录	不加权限装饰器	只要登录态
权限码	@RequirePermissions(Permissions.user.list)	登录 + 拥有该权限码

@Get()
@RequirePermissions(Permissions.user.list)   // 登录 + user:list
list(@Query() q: PageQuery) { return this.service.paginate(q.page, q.pageSize) }

• 角色 code === 'super_admin' 自动绕过权限码校验、data_scope 看全量。
• 数据权限 role.data_scope ∈ { all, dept, dept_and_child, self, custom }，custom 时经 role_org 关联可见部门。

资源注册（新模块接 RBAC）：菜单/接口/按钮资源的单一来源是 src/common/tenant-template.ts 的 MENUS / APIS / BUTTONS，权限码来源是 src/common/permissions.ts。新增模块三步：

1. permissions.ts 加 domain:action 权限码；
2. tenant-template.ts 的 MENUS/APIS/BUTTONS 加资源（parent 挂到上级菜单 code）；
3. 存量租户跑 pnpm sync:resources 补齐（幂等，不触碰用户/密码）；新租户经 createTenant 自动带全。

2.5 装饰器与拦截器

项	用途
@Public()	跳过登录校验
@RequirePermissions(...codes)	要求权限码
@AuditLog('模块', '动作')	写操作自动落 sys_audit_log（异步，失败不阻塞业务）
@CurrentUser	取当前登录用户

全局拦截器/过滤器（app.module.ts 注册）：TransformInterceptor（响应封装 {code,message,data}）、AuditLogInterceptor（审计）、AllExceptionsFilter（异常→code = HTTP*100）。

2.6 字典域（内置字典 + 保护）

• 字典类型/字典项在 dicts/；内置字典 built_in=true。
• 保护规则：内置类型不可删、内置项不可删、内置项 value 不可改；label/sort/color_type 可改；内置类型下可新增非内置项。
• GET /dicts（仅登录态）一次返回当前租户全部启用类型 + 启用项，供前端缓存。
• 内置字典取值与 src/common/enums.ts 一一对应，由 seed 预置（common_status / user_status / resource_type / data_scope / login_status）。

2.7 seed 与资源同步

prisma/seed.ts 只初始化平台租户 touyun（租户/用户/角色/资源/字典）。资源与字典的真实单一来源在 tenant-template.ts 的 MENUS/APIS/BUTTONS/DICTS，seed 与 createTenant 都调用 initTenant；新增资源后对存量租户跑 pnpm sync:resources 补齐。

2.8 账号与会话安全

• 首登强制改密：user.must_change_password 标记临时密码（管理员创建默认强制、重置密码、建租户随机密码）；登录响应返回 mustChangePassword，JwtAuthGuard 对未改密用户只放行 PATCH /auth/me/password，其余接口 403。
• 账号锁定：user.locked_at / lock_reason 独立于 status（停用）；管理员锁定即踢全部会话，解锁同时清登录失败计数。
• 在线会话：会话 = refresh_token，sid 标识单次登录（刷新轮换沿用同一 sid）；GET /sessions 列活跃会话，POST /sessions/:sid/kick 单会话强退（吊销 refresh + sid 黑名单），POST /users/:id/kick-sessions 踢全部（复用 tokenVersion）。

2.9 定时任务

用 @nestjs/schedule 的 @Cron 声明定时任务；ScheduleModule.forRoot() 已在 app.module.ts 注册。现有任务：src/common/cleanup.service.ts 每天 03:07 清理过期/吊销的 refresh token 与超过 90 天的审计/登录日志。

新增定时任务：

1. 新建 service，方法挂 @Cron('秒 分 时 日 月 周')（cron 表达式，如 @Cron('0 3 * * *') 每天 03:00）；
2. 在 app.module.ts 的 providers 注册该 service；
3. 任务体内 try/catch 并记录日志（失败不抛出，避免 Cron 中断）。

本期定时任务仅清理一个，暂不做「任务注册表 + 界面手动触发」；有需要再扩展。

---

3. 前端开发指南（sysmgr-admin）

3.1 目录与自动导入

src/
├── api/            # http.ts（axios 封装）+ 每域 api（user/role/resource/org/dict/...）
├── components/     # ty-* 组件库（全局自动导入，无需 import）
├── composables/    # useRequest、useDict
├── config/         # layout.ts（布局设置）、login.ts（登录页配置）、menu.ts（兜底菜单）
├── layouts/        # default.vue（后台壳）、blank.vue（登录页等）
├── pages/          # 页面（unplugin-vue-router 按目录自动生成路由）
├── stores/modules/ # Pinia：app/auth/menu/tabs/dict
├── types/          # crud.ts（JsonSchema/TableColumn 等）、resource.ts
└── utils/          # dialog.ts（showDialog）、tree.ts、token.ts、theme.ts

已配置 unplugin-auto-import + unplugin-vue-components：Vue API、Element Plus、@/components 下的组件均无需手动 import。

3.2 网络请求：axios 封装 + useRequest

统一用全局 http（@/api/http）：

const data = await http.get<User[]>('/users', { params: { page: 1 } })  // 自动解包，直接拿 data

• 自动注入 Authorization；响应自动拆 {code,message,data}（code=0 返回 data）；401 自动刷新 token 并重放；失败抛 ApiError。
• 方法：http.get/post/put/patch/delete/request<T>(url, data?, config?)。

useRequest（@/composables/useRequest）管理请求状态：

const { data, loading, run, refresh } = useRequest((signal: AbortSignal) => listUsers(q, signal))
// 或手动触发：useRequest(fetcher, { manual: true }) → run(...args)

3.3 字典：dict store + useDict + dictCode

登录后自动缓存全部启用字典，页面/组件通过 dictCode 或 useDict 读取，不要硬编码中文/颜色映射。

const { items, tagMap, options } = useDict('common_status')
// items  : [{ label:'启用', value:'enabled', colorType:'success', sort:1 }, ...]
// tagMap : { enabled: { label:'启用', type:'success' }, ... }
// options: [{ label:'启用', value:'enabled' }, ...]

在 JSON Schema / 表格列里直接写 dictCode 即可（见 §3.7 组件 API）。

3.4 菜单 / 路由 / 布局

• 路由由 unplugin-vue-router 按 src/pages/** 目录自动生成；页面用 <route lang="yaml"> 自定义块声明 meta.layout（default | blank）选择布局：

<route lang="yaml">
meta:
  layout: blank
  requiresAuth: false
</route>

• 菜单从后端 GET /auth/menus 拉取（超管=全部启用菜单，普通用户=角色可访问菜单+祖先），存 menu store。
• 页签存 tabs store，登出/401 清空。
• 多页签 keep-alive：布局用 <keep-alive :include> 缓存打开页签的组件，切换保留状态、关闭销毁；页面默认缓存，在 <route> 里声明 meta.keepAlive: false 可关闭。每个菜单页面须 defineOptions({ name })（name = 路径末段，如 user/login-log/dashboard），作为缓存标识；name 须与路径末段一致且全局唯一（避免未来同末段路径互相影响 keep-alive）。

3.5 样式：UnoCSS @apply

优先用 @apply 工具类，少写裸 CSS。注意主题色工具类写法：

.foo {
  @apply bg-bg-base text-text-primary;   // 背景/文字主题色：bg-bg-* / text-text-*
  @apply border-solid rounded-base;       // 语义色：primary/success/warning/danger/info
}

3.6 组件 API 文档

下面 5 个业务组件 + 2 个 composable 是日常开发主力。布局类组件（ty-header/ty-sidebar/ty-tabs 等）由 layouts/default.vue 组装，一般业务页无需直接使用。

3.6.1 ty-form（JSON Schema 表单）

Props

属性	类型	默认	说明
schema	JsonSchema	—	必填，表单结构描述
modelValue	Record<string, any>	—	必填，表单数据（就地绑定）
inline	boolean	false	行内布局（搜索用）
mode	'create' | 'edit'	undefined	配合字段 showOn 过滤
enterToSubmit	boolean	false	输入框回车触发 submit
readonlyKeys	string[]	[]	强制只读的字段名

Expose（通过 ref 调用）

方法	说明
submit()	校验并返回表单数据（校验失败抛错）
validate()	仅校验
resetFields()	重置
clearValidate()	清空校验状态

Emits：submit。

JsonSchemaProperty 字段速查

字段	类型	说明
type	'string'|'integer'|'number'|'boolean'	控件类型
title	string	标签
placeholder	string	占位
enum / enumNames	(string|number|boolean)[] / string[]	下拉选项（一一对应）
dictCode	string	字典 code，声明后自动生成下拉（优先于 enum）
format	'password'|'email'|'textarea'|'tree-select'|'date'|'datetime'	特殊控件；date/datetime 目前按普通输入框渲染
default	unknown	默认值
readOnly	boolean	只读
showOn	('create'|'edit')[]	仅指定模式显示
when	{ field; equals?; in? }	依赖字段值联动显隐
minLength/maxLength/minimum/maximum	number	校验
prefixIcon	string	输入框前缀 iconify 图标
width	string	控件宽度
treeData/treeProps	—	format:'tree-select' 时的树数据与字段映射

type:'boolean' 渲染为开关（el-switch），配合 default:true/false 设定默认值；布尔字段常用 showOn: ['create'] 只在新增时出现。

const schema: JsonSchema = {
  type: 'object',
  properties: {
    status: { type: 'string', title: '状态', dictCode: 'common_status', default: 'enabled' },
    path: { type: 'string', title: '路由', when: { field: 'type', equals: 'menu' } },
  },
  required: ['status'],
}

3.6.2 ty-search-form（搜索 + 折叠）

Props

属性	类型	默认	说明
schema	JsonSchema	—	搜索字段
modelValue	Record<string, any>	—	搜索条件
collapseCount	number	3	折叠时显示字段数，超出「展开」

Emits：search、reset。

3.6.3 ty-table（表格）

Props

属性	类型	默认	说明
columns	TableColumn[]	—	列配置
data	Record<string, any>[]	—	行数据
loading	boolean	false	加载态
selection	boolean	false	多选列
total / page / pageSize / pageSizes	number/number[]	0/1/10/[10,20,50]	分页
actionsWidth	number|string	200	操作列宽
rowKey	string	'id'	行唯一键（树形用 code）
treeProps	Record<string,string>	{children:'children'}	树形字段映射
defaultExpandAll	boolean	false	树形默认展开

Emits：update:page、update:pageSize、selection-change。 Slots：actions（作用域 { row }）。

TableColumn 字段

字段	类型	说明
prop	string	字段名
label	string	列标题
width / minWidth	number|string	列宽
align	'left'|'center'|'right'	对齐
type	'text'|'tag'|'datetime'	渲染类型（默认 text）
tagMap	Record<string, {label,type}>	type:'tag' 的值→标签映射
dictCode	string	type:'tag' 时按字典渲染（优先于 tagMap）
formatter	(value, row) => string	自定义格式化

const columns: TableColumn[] = [
  { prop: 'status', label: '状态', width: 90, type: 'tag', dictCode: 'common_status' },
  { prop: 'createdAt', label: '创建时间', width: 160, type: 'datetime' },
]

3.6.4 ty-crud（整页 CRUD）

组合「搜索 + 工具栏 + 表格 + 弹窗表单 + 删除」，多数单表页面用它几行搞定。

Props

属性	类型	默认	说明
entityName	string	—	实体名（标题/确认文案）
columns	TableColumn[]	—	列
formSchema	JsonSchema	—	新增/编辑表单
searchSchema	JsonSchema	—	搜索（可选）
list	(query, signal?) => Promise<PageResult>	—	分页查询
create	(data) => Promise<unknown>	—	新增
update	(id, data) => Promise<unknown>	—	更新
remove	(id) => Promise<unknown>	—	删除
idKey / nameKey	string	'id'/'name'	主键/删除确认显示字段
editReadonlyKeys	string[]	[]	编辑只读字段
getEditReadonlyKeys	(row) => string[]	—	按行计算只读（优先）
actions	CrudAction[]	['edit','delete']	操作列（内置或自定义 {label,type,onClick,show}）
collapseCount	number	2	操作按钮折叠数
selection	boolean	false	多选（配合 #toolbar-right）
actionsWidth	number|string	140	操作列宽

Slots：toolbar、toolbar-right（作用域 { selectedRows }）。 Expose：reload()。

<ty-crud
  entity-name="用户"
  :columns="columns"
  :search-schema="searchSchema"
  :form-schema="formSchema"
  :list="list" :create="create" :update="update" :remove="remove"
  id-key="id" name-key="username" :edit-readonly-keys="['username']"
/>

3.6.5 showDialog / ty-dialog（弹窗）

showDialog(options) 打开弹窗，返回 Promise（确认 resolve 内容组件 submit() 数据，取消/关闭 resolve null）。<ty-dialog /> 需挂载一次作为宿主（通常已在根组件）。

const data = await showDialog({
  component: TyForm,                       // 内容组件（通常传 TyForm）
  title: '新增用户',
  width: '520px',
  props: { schema, modelValue: model, mode: 'create' },
})
if (data == null) return                    // 取消
await createUser(data)

DialogOptions

字段	类型	说明
component	Component	内容组件（须 expose submit()）
title / width	string	标题/宽度（默认 480px）
props	Record<string, any>	传给内容组件的 props
confirmText / cancelText	string	按钮文案
showFooter	boolean	默认显示取消/确定；false 时内容组件自带底部
onConfirm	(data) => void|Promise	确认回调

3.6.6 useRequest

useRequest<TData, TParams>(fetcher, options?)
// fetcher: (...args: [...TParams, AbortSignal]) => Promise<TData>

Options：manual（默认 false 自动请求）、defaultParams、refreshDeps（依赖变化重请求）、onBefore/onSuccess/onError/onFinally。 返回：data、loading、error、run(...args)、refresh()、cancel()、mutate(data|fn)。

3.6.7 useDict

useDict(code)  // → { items, tagMap, options }，均响应式

---

4. 联调契约

4.1 响应封装

{ "code": 0, "message": "ok", "data": { } }

• code=0 成功；失败 code 为业务码（5 位 [域码 2 位][序 3 位]，单一注册表见 src/common/error-codes.ts，如 10001 账号或密码错误、11002 用户名已存在）；未登记业务码的异常回退 HTTP状态码 × 100（40000/40100/40300/40400/40900/50000）。
• 前端 http 已自动拆包：成功拿 data，失败抛 ApiError(code, message)。

4.2 分页

列表接口 page/pageSize，返回 { list, total, page, pageSize }。

4.3 三级鉴权

公开（@Public）→ 仅登录（无装饰器）→ 权限码（@RequirePermissions），见 §2.4。

4.4 契约锚点

shared/api-contract（响应/错误码/分页/鉴权/接口目录）与 shared/data-model（字段字典）是前后端唯一锚点，字段/接口变更先改 shared/。

---

5. 常用操作手册（Cookbook）

5.1 新增一个业务实体（含权限码 + 页面）完整走查

以新增「岗位 post」为例，完整跑通「后端 → 前端 → 资源注册 → 授权验证」：

后端

1. prisma/schema.prisma 加 Post 模型（sys_post，带 tenant_code + 公共字段）。
2. npx prisma migrate dev --name add_post + prisma generate。
3. src/common/permissions.ts 加 post: { list, create, update, delete }。
4. 新建 src/posts/（module/controller/service/dto），service extends BaseCrudService。
5. controller 挂 @RequirePermissions(Permissions.post.xxx) + 写操作 @AuditLog('post', 'xxx')。
6. app.module.ts 注册 PostsModule。
7. 资源注册：src/common/tenant-template.ts 的 APIS 加 4 条接口资源（code=权限码、method、path、parent='post'），MENUS 加菜单节点（parent、path、component、icon）。
8. 存量租户补资源：pnpm sync:resources（幂等）；新租户 createTenant 自动带全。

前端

1. src/api/post.ts 加类型 + listPosts/createPost/updatePost/deletePost。
2. src/pages/system/post/index.vue：<script setup> 顶部加 defineOptions({ name: 'post' })（keep-alive 缓存标识），用 ty-crud 组装（列用 dictCode，表单用 JSON Schema，路由由文件路径自动生成）。
3. 若该页不要缓存，加 <route lang="yaml">meta: keepAlive: false</route>。

授权验证

1. 用超管登录「角色管理」给某角色分配 post 菜单 + 接口资源。
2. 切到该角色的用户登录，应看到「岗位管理」菜单、能操作；无权限用户看不到。

5.2 新增一个字典类型

1. 登录进入「系统管理 → 字典管理」→ 新增字典类型（填 code/name）。
2. 选中类型 → 新增字典项（label/value/标签色/排序）。
3. 页面/组件里用 dictCode: '<code>' 或 useDict('<code>') 引用。

内置字典（seed 预置）的 value 与内置项受保护，只能改 label/排序/颜色；普通字典完全自由。

5.3 新增一个权限码 / 按钮

1. common/permissions.ts 加 domain.action。
2. tenant-template.ts 的 APIS（接口）或 BUTTONS（纯前端按钮）加对应资源；存量租户跑 pnpm sync:resources。
3. 后端 controller 用 @RequirePermissions(...)；前端按钮用 v-permission 或资源 code 下发渲染。

5.4 新增租户

「系统管理 → 租户管理」新增；或 seed 里 upsert。租户之间 tenant_code 隔离，登录时按账号+租户识别当前租户。

5.5 扩展资源 / 字典

改 tenant-template.ts 的 MENUS / APIS / BUTTONS / DICTS 常量；新租户自动生效，存量租户跑 pnpm sync:resources 补齐（幂等，重复运行不重复插入）。

---

6. 规范与约定

• 提交信息：Conventional Commits（feat/fix/chore/docs/refactor）。
• 命名：后端模型 camelCase + @map snake_case；业务键统一 code；权限码 domain:action。
• 样式：UnoCSS @apply，少写裸 CSS；主题色用 bg-bg-* / text-text-*。
• 自测后停服务：冒烟测试临时起的服务，测完立即停掉。
• 单一事实源：字段/接口以 shared/data-model、shared/api-contract 为准，不各自命名。

---

7. 排障 FAQ

现象	原因 / 处理
启动报 EADDRINUSE :3000	端口被占，换 PORT=3100 或停掉旧进程
prisma migrate dev 非交互报错	用 prisma migrate diff 生成 SQL + prisma migrate deploy，或开发期用 prisma db push
seed 重复插入报唯一约束	检查 upsert 的 where 是否用了唯一键（如 tenantCode_code）
接口返回 401	token 缺失/过期；前端会自动刷新，刷新失败跳登录
接口返回 403	权限码未授权；确认 resource 表登记了该接口、角色已分配
字典下拉/标签不显示	确认登录后 dictStore.fetch() 成功；字典类型/项 status=enabled；dictCode 拼写一致
改字典 label 页面没变	字典缓存未刷新：重新登录，或字典页保存后 dictStore.fetch(true) 强制刷新
登录失败	确认 seed 已跑、账号 touyun / Touyun@123、租户 touyun 存在且 enabled
内置项 value 改不动	内置项受保护，仅 label/排序/颜色可改（有意为之）
首登登录后所有接口 403	must_change_password=true，需先改密：仅 PATCH /auth/me/password 放行，前端会强制跳改密页
强退后 token 仍短暂可用	access 最长 2h 内失效（sid 黑名单）；refresh 已被吊销无法续期
切页签数据没保留	该页声明了 meta.keepAlive:false，或页面缺 defineOptions({ name }) 导致缓存标识失效

---

8. 升级与定制（fork 后如何同步上游）

脚手架是「通用底座」，fork 成具体项目后，业务代码和脚手架代码必须物理分离，才能在上游升级时干净合并。

8.1 升级同步（git upstream + merge）

git clone <脚手架地址> my-project
cd my-project
git remote rename origin upstream            # 脚手架 = upstream
git remote add origin <我的业务仓库地址>      # 业务 = origin
# 日常在 main 上开发业务，升级时：
git fetch upstream
git merge upstream/main                       # 冲突只在「你改过脚手架文件」的地方出现

• 业务代码纯新增（新模块/新页面/新资源）→ 升级几乎零冲突。
• 业务代码改了脚手架文件 → 上游升级该文件即冲突，改得越深越痛。
• 将来项目变多、需要版本语义时，再评估把脚手架抽成 npm 包 / monorepo 依赖（彻底隔离、按版本升级）。

8.2 可定制面（三条铁律）

铁律	说明
框架代码只读	脚手架自带模块/页面/服务（users/roles/system/*/common/*/ty-*…）只读不改
业务代码落点	新增放独立业务目录：后端新域 src/<domain>/，前端新页面 src/pages/<biz>/，不侵入框架目录
定制走扩展点	外观/权限优先走数据驱动扩展点：租户品牌（tenant.brand_*）、字典、主题色、资源注册（tenant-template.ts + pnpm sync:resources），而非改源码