feat: role CRUD

CLAUDE.md

@@ -123,4 +123,16 @@ Lessons from splitting `frontend/app/features/schedules/state/schedulesStore.ts`
 
 ### Frontend coupling
 
-- **`UserManagementPage.tsx` and `api.ts` still call `/api/v1/admin/employees`.** Don't migrate them in the same change as a `/api/v1/platform/employees` addition — the contract surface is intentionally duplicated.
+- **`UserManagementPage.tsx` and `api.ts` still call `/api/v1/admin/employees`.** Don't migrate them in the same change as a `/api/v1/platform/employees` addition — the contract surface is intentionally duplicated.
+
+### File size: 500 lines hard cap
+
+- **每个文件最多 500 行** — 超过时主动拆分,不要等 review 才动。
+- 常见拆分维度:
+  - **后端 — 按资源 / 端点分组**:例如 `api/platform.py` (1600 行 / 20 endpoint) → `api/platform/{__init__,_deps,employees,roles,workspaces}.py`。原文件改为 thin shim,只 re-export 公共符号,保持 `from backend.api.platform import router` 等既有 import path 不变。
+  - **后端 — 按层级**:参考 `schedule/` 已有的 `domain/` / `application/` / `infrastructure/` 分层。
+  - **前端 — 按职责**:`types.ts` / `helpers.ts` / `slices/` / `useXStore.ts`(参考 `useSchedulesStore` 拆 8-slice 的纪律)。
+  - **前端 — 页面 vs 路由 wrapper**:Page 组件持有 useState,route 文件只做 `<Page key={...} />` 重挂载,二者不要混在一起。
+- **拆分前先列调用面**(`grep "from <old_path>"`),任何外部 import 路径必须仍然可用 — 用 re-export 或 shim 兜底,不要让调用方被迫改。
+- **拆分后**每个新文件 ≤ 500 行是硬约束,验证方式:`wc -l <file>` 或 CI 脚本。
+- 拆分本身是**纯结构调整**,endpoint 行为 / URL / 响应 schema 零变化 — 不要顺手"清理"。