文档补充清单

这页解决什么问题

这份清单不是代码缺陷清单，而是 LuckyColor 当前文档站中“主干已经存在，但仍值得补强”的说明项。它的目标是帮助后续维护者快速判断：

哪些内容已经在代码里存在，但文档表达还不够完整
哪些页面已经补写
哪些地方后续改代码时仍要同步更新文档

本轮已补充的重点

1. 核心业务关系说明

已补一份独立说明页：核心关系说明

主要补了这些之前容易口头讲、但不容易从文档里一下看懂的内容：

租户、部门、角色、用户之间的真实关系
User <-> Role 是多对多，而不是一人一个角色
角色和部门不是归属关系，而是“数据权限范围关系”
租户初始化时到底会顺带创建哪些资源
平台管理员、租户管理员、租户成员三类边界如何区分

2. 身份边界矩阵

已补一份独立说明页：身份边界矩阵

主要补了这些之前容易散落在代码和口头约定里的内容：

平台管理员、租户管理员、普通成员三类身份的默认能力边界
哪些能力属于平台级，哪些更适合租户内治理
边界矩阵和菜单权限、按钮权限、数据权限的关系
排查“谁不该看到这里”时的默认判断思路

3. 前端会话恢复与联调模式

已补一份独立说明页：会话恢复与联调模式

主要补了这些当前很容易让接手者产生误解的点：

登录后前端真实初始化链路
页面刷新后如何恢复用户信息、租户上下文和菜单缓存
/api/auth/access、/api/auth/profile、/api/menus/tree 各自承担什么职责
pnpm dev、pnpm dev:springboot、pnpm dev:nestjs 三种入口命令各自对应什么后端模式

4. 现有页面中的关键修订

本轮同时把以下页面做了定向补充：

这些修订主要是为了把“新页面内容”挂回主阅读路径，而不是让补充页变成孤岛。

其中新增的“参考项目与文档改进思路”页，主要用来沉淀对 GitHub / Gitee 高星 SaaS 文档的观察结论，避免后续补文档时只凭感觉继续堆内容。

而新增的“Smoke 修复与功能链条任务板”页，主要用来做这一轮修复和后续补链路文档时的执行基线，要求每完成一个子任务就更新一次状态，避免重复修和遗漏。

当前最值得持续维护的文档点

下面这些点后续一旦改代码，建议优先同步改文档。

登录与初始化链路

当前前端真实链路是：

登录页调用 POST /api/auth/login
用登录返回的用户快照先建立本地会话
再调用 GET /api/menus/tree 初始化菜单与动态路由
页面刷新时，走 GET /api/auth/profile 与本地菜单缓存恢复状态

如果未来改成“登录后统一只调 /api/auth/access 初始化”，需要同步更新：

租户套餐能力边界

当前套餐不仅有基础 CRUD，还包含：

人数、角色数、菜单数上限
featureFlags 形式的能力开关
前端运营页中的“将套餐绑定到租户”流程

如果未来新增新的套餐能力字段，例如存储容量、短信额度、文件上传能力，建议同步更新：

租户状态与访问边界

当前后端会额外校验：

租户是否激活
是否冻结
是否禁用
是否过期

如果未来租户状态流转规则变化，建议同步更新：

角色与数据权限

当前角色数据范围不是前端自己算，而是后端根据角色集合收敛后决定：

ALL
DEPARTMENT
DEPARTMENT_AND_CHILDREN
SELF
CUSTOM

如果未来数据权限模型新增“租户全部”“项目级”“门店级”等维度，建议同步更新：

后续如要继续补写

如果下一轮还要继续补文档，我建议优先补这三类：

套餐 featureFlags 与菜单/权限/页面可见性的关系
前端菜单标准化兼容层与旧菜单迁移说明
平台级菜单与租户级菜单的收口说明

文档补充清单 ​

这页解决什么问题 ​

本轮已补充的重点 ​

1. 核心业务关系说明 ​

2. 身份边界矩阵 ​

3. 前端会话恢复与联调模式 ​

4. 现有页面中的关键修订 ​

当前最值得持续维护的文档点 ​

登录与初始化链路 ​

租户套餐能力边界 ​

租户状态与访问边界 ​

角色与数据权限 ​

推荐维护方式 ​

后续如要继续补写 ​