1. 拓扑总览

                            DNS → 113.249.107.92
                                       ↓
                    nginx (sites-enabled)
                ┌──────────┬───────────────┬───────────────────┐
                ↓          ↓               ↓                   ↓
   zephyrian.site/   /api/auth/login  fleet.zephyrian.site  nempoi.zephyrian.site
   静态门户          反代 :3000        :3000 robovan          :3100 nempoi
   (portal/)         (door 门户登录)   Express + Vanilla JS   FastAPI + Vue 3
                                       ↓                       ↓
                                       └─→ vehicle_mgmt 库 ←─┐
                                       ↓                       │
                                       └─→ shared_auth 库 ←──┤
                                                              │
                                                              └─→ nem_poi 库
          

2. 库与表结构

shared_auth(SSO 共享)

• users — 跨 app 用户主表(id/username/password_hash/feishu_user_id/token_version/robovan_role/nempoi_role/nempoi_organization_id/nempoi_nem_token*/is_root_owner)
• sessions — 跨 app 单一 session 表(token/user_id/app/ip/expires_at/last_active_at)
• permissions — 权限主表(key/app/category/description)
• roles — 角色主表(id/app/name/description/is_system)
• role_permissions — 角色×权限映射

vehicle_mgmt(运力管理业务)

• vehicles / orders / trips / assignments / customers / vehicle_costs / order_costs / payments / payment_accounts / data_snapshots / login_events / audit_logs ...

nem_poi(NEMPOI 业务)

• organizations / pois / poi_pictures / login_logs / audit_logs

3. 关键路由

• POST /api/auth/login — 用户名密码登录(robovan + nempoi 各有自己的)
• POST /api/auth/feishu — 飞书 OAuth(robovan)
• POST /api/auth/logout — 登出 + 删 session
• GET /api/auth/me — 拉当前用户(各 app 自己的)
• GET /api/platform-admin/users — 跨 app 账号管理(本面板用)
• GET /api/platform-admin/roles + permissions — RBAC v2
• GET /api/platform-admin/sessions — 跨 app 登录日志
• GET /api/platform-admin/audit-logs — 操作日志(目前仅 fleet,nempoi 待集成)

4. 登录与会话

• cookie 名 zsess,domain=.zephyrian.site,跨 fleet/portal/nempoi 共享
• session token 32 字节 random base64url,存 shared_auth.sessions,TTL 8h
• 每请求心跳更新 last_active_at(节流 1 分钟一次)
• token_version 改密时 +1 → 该 user 所有 session 立即失效
• is_root_owner=TRUE 视为两边 app 的 superadmin(用于跨 app 操作)

5. 已知技术债

• RBAC v2 基础数据已上但应用层(robovan rbac.js / nempoi 路由 require_role)还在用硬编码角色等级 — 下个迭代切到 role_permissions 查表
• NEMPOI 操作日志跨库未实现(平台 audit_logs 暂仅显示 fleet)— 待加 trust 通道
• 角色权限矩阵保存仅生效到下次 app reload(需要清 user 端的 cookie/JWT 才即时生效)— 已通过 token_version 兜底
• SSO Phase 完成,下一步:监控仪表盘(登录次数/在线时长/NEM 调用统计)+ 文档门户(VitePress 收集各 app docs/)

6. 部署

• nempoi:cd /opt/nem-poi && git pull && bash scripts/build.sh && pm2 reload nem-poi
• robovan:严格 PR + tag deploy 流;bash scripts/deploy.sh v0.13.x
• 主域门户:静态文件 portal/,nginx serve;改完仅需 git pull(不需 build/reload)