diff --git a/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md b/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md index 6a5e515..d0c85a5 100644 --- a/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md +++ b/docs/superpowers/plans/2026-06-30-ai-ticket-platform-implementation-roadmap.md @@ -25,6 +25,7 @@ The product contains multiple independent subsystems. Do not implement the entir | 0 | Foundation and design system | Create the repo skeleton, local runtime, auth/RBAC baseline, audit baseline, frontend theme and component standards. | None | `docs/superpowers/plans/2026-06-30-stage-0-foundation-design-system.md` | | 1 | Ticket workflow and reusable solutions | Implement ticket lifecycle, comments, attachments, events, export, solution library, and solution links. | Stage 0 | Create after Stage 0 passes. | | 1.5 | shadcn enterprise UI foundation | Formalize shadcn/ui initialization, add a project-owned App component layer, redesign current ticket and solution pages, and enforce Chinese frontend text. | Stage 1 | `docs/superpowers/specs/2026-07-01-stage-1-5-shadcn-ui-foundation-design.md` | +| 1.6 | Enterprise governance and login | Add login/logout/current-user APIs, user/user-group/role/menu management, API permission enforcement, permission-driven frontend menus, and deployment bootstrap. | Stage 1.5 | `docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-design.md` | | 2 | Knowledge base and vector retrieval | Implement knowledge bases, documents, parsing jobs, chunks, embeddings, and retrieval. | Stage 0, partial Stage 1 | Create after Stage 1 model contracts stabilize. | | 3 | Model gateway and Agent/Skill runtime | Implement provider configs, model configs, model testing, Skill configs, built-in Agents, runs, steps, AI artifacts. | Stage 0, Stage 1, Stage 2 retrieval interfaces | Create after Stage 2 retrieval contracts exist. | | 4 | MCP tools and trust boundary | Implement MCP server registration, tool sync, risk levels, Agent tool binding, tool calls, confirmation, audit. | Stage 3 | Create after Agent runtime exists. | diff --git a/docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-design.md b/docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-design.md new file mode 100644 index 0000000..db38124 --- /dev/null +++ b/docs/superpowers/specs/2026-07-01-stage-1-6-enterprise-governance-design.md @@ -0,0 +1,480 @@ +# Stage 1.6 Enterprise Governance Design + +## Background + +Stage 0 established an RBAC seed baseline with Django's built-in `User`, `Group`, and `Permission` models. Stage 1 added ticket and solution workflows. Stage 1.5 formalized shadcn/ui and created the enterprise admin UI base. + +The current governance capability is still incomplete for an enterprise product: + +- No frontend login or logout flow. +- No current-user API for frontend permission and menu rendering. +- No user management page. +- No user group management page. +- No role and permission management page. +- No menu permission management page. +- No API-level permission enforcement policy across ticket, solution, audit, and system governance APIs. +- Docker deployment does not yet run a full governance bootstrap for default admin, roles, permissions, and menus. + +Stage 1.6 fills this gap before Stage 2 knowledge base and later Agent/model/MCP modules. Those later modules must not be built on top of anonymous APIs and hard-coded menus. + +## Decision + +Create a dedicated Stage 1.6 after Stage 1.5: + +```text +Stage 0 = project skeleton + RBAC seed baseline +Stage 1 = ticket workflow and solution library +Stage 1.5 = shadcn enterprise UI foundation +Stage 1.6 = login + users + user groups + roles + menus + permission enforcement +Stage 2 = knowledge base and vector retrieval +``` + +Stage 1.6 is a frontend and backend stage. It must use the current shadcn/ui component base for all frontend governance pages. + +## Goals + +1. Add login, logout, and current-user APIs. +2. Add frontend login experience and authenticated application shell. +3. Add backend CRUD APIs for users, user groups, roles, permissions, and menus. +4. Add frontend system governance pages using shadcn components. +5. Add menu permission data so frontend navigation is driven by backend permission results instead of hard-coded public menus. +6. Add API permission checks for ticket, solution, audit, and governance endpoints. +7. Add deployment bootstrap so a fresh Docker environment can create default admin, permissions, roles, user groups, and menus. + +## Non-Goals + +- No SSO, LDAP, SAML, OAuth, enterprise WeChat, or DingTalk login. +- No multi-tenant model. +- No organization tree or department hierarchy. +- No row-level data permission. +- No field-level permission. +- No approval workflow. +- No password complexity policy beyond Django's baseline validation. +- No MFA. +- No public self-registration. +- No Stage 2 knowledge base, model gateway, Agent, Skill, or MCP implementation. + +## Terminology + +| Product Term | Backend Representation | Notes | +|---|---|---| +| 用户 | Django `User` | Use Django's built-in user model for Stage 1.6. | +| 角色 | Django `Group` | Product UI calls it "角色"; backend reuses Django Group permissions. | +| 权限点 | Django `Permission` | Seeded by catalog. Canonical business code is like `ticket.view`. | +| 用户组 | New `UserGroup` model | Business grouping independent from permission roles. | +| 菜单权限 | New `MenuItem` model + permission code | Menus can require a permission code and are returned from `/me`. | +| 按钮/操作权限 | Permission codenames | Frontend hides actions; backend still enforces. | + +## Backend Design + +### Authentication + +Use Django session authentication for Stage 1.6. + +Required endpoints under `/api/accounts/auth`: + +| Method | Path | Purpose | +|---|---|---| +| `GET` | `/csrf` | Set CSRF cookie for SPA login requests. | +| `POST` | `/login` | Validate username/password and create Django session. | +| `POST` | `/logout` | Clear current session. | +| `GET` | `/me` | Return current user, roles, groups, permissions, and authorized menu tree. | + +Cross-origin local development must support session cookies: + +- Backend enables `CORS_ALLOW_CREDENTIALS = True`. +- Backend configures `CSRF_TRUSTED_ORIGINS` from env. +- Frontend API client sends `credentials: "include"`. +- Login flow fetches CSRF before posting credentials. + +### Data Models + +Add models to `backend/apps/accounts/models.py`. + +#### UserGroup + +Business user group separate from role permissions: + +| Field | Type | Notes | +|---|---|---| +| `name` | varchar unique | Chinese display name. | +| `code` | varchar unique | Stable code for integration and seeding. | +| `description` | text blank | Optional description. | +| `users` | many-to-many `User` | Group members. | +| `is_active` | boolean | Disabled groups are not shown in normal assignment. | +| `created_at` / `updated_at` | datetime | Audit-friendly timestamps. | + +#### MenuItem + +Backend-driven menu definition: + +| Field | Type | Notes | +|---|---|---| +| `code` | varchar unique | Stable menu code. | +| `title` | varchar | Chinese title. | +| `path` | varchar blank | Frontend hash route, such as `#/tickets`. | +| `icon` | varchar blank | Frontend icon key understood by AppSidebar. | +| `parent` | FK self nullable | Supports menu tree. | +| `sort_order` | int | Ordering inside parent. | +| `permission_code` | varchar blank | Business permission code required to see the menu. | +| `is_visible` | boolean | Hidden menus can still exist for permissions. | +| `is_enabled` | boolean | Disabled menus are excluded. | +| `created_at` / `updated_at` | datetime | Audit-friendly timestamps. | + +Roles continue to use Django `Group`. Permissions continue to use Django `Permission`. + +### Permission Catalog + +Extend the permission catalog with Chinese names and governance permissions. + +Required governance permission codes: + +```text +system.user.view +system.user.manage +system.user_group.view +system.user_group.manage +system.role.view +system.role.manage +system.menu.view +system.menu.manage +system.audit.view +system.setting.manage +``` + +Existing business permissions remain: + +```text +ticket.view +ticket.create +ticket.edit +ticket.export +ticket.assign +ticket.close +solution.view +solution.manage +knowledge.view +knowledge.manage +agent.use +agent.manage +model.manage +tool.manage +``` + +When checking permissions through Django, use `system.` because the seeded permission content type uses app label `system`. + +Example: + +```python +request.user.has_perm("system.ticket.view") +``` + +### Seed And Bootstrap + +Stage 1.6 should add a single bootstrap command that is safe to run repeatedly: + +```bash +python manage.py bootstrap_governance +``` + +The command must: + +1. Seed permissions. +2. Seed default roles. +3. Seed default user groups. +4. Seed default menus. +5. Create or update a default admin user from env vars. + +Recommended env vars: + +```dotenv +DJANGO_SUPERUSER_USERNAME=admin +DJANGO_SUPERUSER_PASSWORD=admin12345 +DJANGO_SUPERUSER_EMAIL=admin@example.com +``` + +Default roles: + +| Role | Meaning | +|---|---| +| 系统管理员 | All permissions. | +| 知识库管理员 | Knowledge and solution management. | +| 技术支持 | Ticket handling and Agent usage. | +| 普通建单人 | Create/view own relevant tickets first; broad row-level ownership is deferred. | +| 只读审计员 | View tickets, solutions, knowledge, and audit logs. | + +Default menus: + +```text +工作台 + 运营总览 +业务处理 + 工单中心 + 创建工单 + 解决方案库 +平台能力 + 知识库 + Agent 配置 + 模型与工具 +系统治理 + 用户管理 + 用户组管理 + 角色权限 + 菜单权限 + 操作审计 + 设计系统 +``` + +Menus for future modules may be seeded but hidden or disabled until their stage is implemented. + +### Governance APIs + +Add APIs under `/api/accounts`. + +#### Current User + +`GET /api/accounts/auth/me` returns: + +```json +{ + "id": 1, + "username": "admin", + "display_name": "系统管理员", + "email": "admin@example.com", + "is_superuser": true, + "roles": [{"id": 1, "name": "系统管理员"}], + "user_groups": [{"id": 1, "name": "默认用户组", "code": "default"}], + "permissions": ["ticket.view", "system.user.manage"], + "menus": [ + { + "code": "workbench", + "title": "工作台", + "path": "", + "icon": "home", + "children": [] + } + ] +} +``` + +#### User APIs + +| Method | Path | Permission | +|---|---|---| +| `GET` | `/users` | `system.user.view` | +| `POST` | `/users` | `system.user.manage` | +| `GET` | `/users/{id}` | `system.user.view` | +| `PATCH` | `/users/{id}` | `system.user.manage` | +| `POST` | `/users/{id}/reset-password` | `system.user.manage` | +| `POST` | `/users/{id}/roles` | `system.user.manage` | +| `POST` | `/users/{id}/user-groups` | `system.user.manage` | + +#### User Group APIs + +| Method | Path | Permission | +|---|---|---| +| `GET` | `/user-groups` | `system.user_group.view` | +| `POST` | `/user-groups` | `system.user_group.manage` | +| `PATCH` | `/user-groups/{id}` | `system.user_group.manage` | +| `POST` | `/user-groups/{id}/members` | `system.user_group.manage` | + +#### Role And Permission APIs + +| Method | Path | Permission | +|---|---|---| +| `GET` | `/roles` | `system.role.view` | +| `POST` | `/roles` | `system.role.manage` | +| `PATCH` | `/roles/{id}` | `system.role.manage` | +| `POST` | `/roles/{id}/permissions` | `system.role.manage` | +| `GET` | `/permissions` | `system.role.view` | + +#### Menu APIs + +| Method | Path | Permission | +|---|---|---| +| `GET` | `/menus` | `system.menu.view` | +| `POST` | `/menus` | `system.menu.manage` | +| `PATCH` | `/menus/{id}` | `system.menu.manage` | +| `POST` | `/menus/reorder` | `system.menu.manage` | + +### API Permission Enforcement + +Add a small accounts permission helper: + +```text +require_login(request) +require_permission(request, "ticket.view") +``` + +Enforcement rules: + +- `/api/system/health` remains public. +- `/api/accounts/auth/csrf` and `/api/accounts/auth/login` remain public. +- `/api/accounts/auth/me` requires login. +- Audit log list requires `system.audit.view`. +- Ticket list/detail/export require `ticket.view`. +- Ticket create requires `ticket.create`. +- Ticket update/status/comment/attachment operations require the closest ticket operation permission. +- Solution list/detail require `solution.view`. +- Solution create/link requires `solution.manage`. + +Frontend hiding is not security. Backend permission checks are mandatory for all protected operations. + +## Frontend Design + +### Auth Flow + +Add frontend auth state: + +```text +AuthProvider + ├─ load /api/accounts/auth/me + ├─ login(username, password) + ├─ logout() + └─ exposes user, permissions, menus, loading, authenticated +``` + +Application flow: + +```text +Unauthenticated → LoginPage +Authenticated → AppShell + Router +``` + +The login page must use shadcn components and Chinese text: + +- `Card` +- `Input` +- `Button` +- `Alert` +- `Label` or shadcn `Field` if installed + +### API Client + +Update `frontend/src/lib/api.ts`: + +- Send `credentials: "include"`. +- Include CSRF token for unsafe methods. +- Convert `401` into an auth state transition. +- Keep error messages Chinese where shown to users. + +### Sidebar Menus + +`AppSidebar` should no longer own the final hard-coded menu list. It should consume menu data from `AuthProvider`. + +Rules: + +- Backend returns only menus the user can see. +- Frontend still handles unknown future paths with disabled or placeholder behavior. +- Icon mapping is local and controlled, using lucide-react icons. +- All menu text is Chinese. + +### Governance Pages + +Add a new feature module: + +```text +frontend/src/features/system/ +``` + +Required pages: + +| Route | Page | Purpose | +|---|---|---| +| `#/system/users` | 用户管理 | List, create, edit active state, assign roles and user groups, reset password. | +| `#/system/user-groups` | 用户组管理 | List/create/edit business user groups and members. | +| `#/system/roles` | 角色权限 | List/create/edit roles and assign permissions. | +| `#/system/menus` | 菜单权限 | View/edit menu tree, menu metadata, and required permission. | +| `#/audit` | 操作审计 | Reuse existing audit API with protected access. | + +Required shadcn components: + +- Existing Stage 1.5 components: `button`, `badge`, `card`, `input`, `textarea`, `select`, `label`, `separator`, `sidebar`, `breadcrumb`, `dropdown-menu`, `table`, `tabs`, `sheet`, `dialog`, `tooltip`, `skeleton`, `sonner`. +- Add if not installed: `checkbox`, `switch`, `alert`, `empty`, `pagination`. + +Project App components should remain the page-level API: + +- `AppDataTable` +- `AppFilterBar` +- `AppPageHeader` +- `AppSection` +- `AppEmptyState` +- system-specific wrappers if useful, such as `PermissionMatrix` and `RolePermissionEditor`. + +### Page Experience + +The governance UI should feel like an enterprise admin console, not a demo: + +- Dense tables with Chinese column names. +- Dialog or Sheet for create/edit. +- Permission assignment grouped by module. +- Clear active/disabled status badges. +- Empty states in Chinese. +- Loading skeletons for initial data fetch. +- Toast feedback via `sonner`. + +## Deployment Initialization + +Docker/local startup should support a fresh database: + +```text +backend startup: + python manage.py migrate + python manage.py bootstrap_governance + python manage.py runserver 0.0.0.0:8000 +``` + +The exact startup implementation can be an entrypoint script or documented command. The important requirement is that a new developer can bring up Docker Compose and log in with the seeded admin account after migrations finish. + +## Security Notes + +- Default admin password is acceptable only for local/dev. Production deployments must override env vars. +- Backend permission checks are the source of truth. +- Superusers bypass permission assignment checks through Django's built-in behavior, but `/me` should still return all business permission codes. +- Passwords are never returned in API responses. +- User deletion should not be implemented in Stage 1.6; use deactivate instead. + +## Testing Requirements + +Backend tests: + +- Login succeeds with seeded admin. +- `/me` returns user, roles, permissions, and filtered menus. +- Anonymous access to protected endpoints returns 401 or 403. +- Permissioned users can access allowed endpoints. +- Users without permissions are denied. +- User CRUD, role permission assignment, user group membership, and menu update APIs work. +- Bootstrap command is idempotent. + +Frontend verification: + +- `npm run typecheck` +- `npm run build` +- Browser smoke test: + - anonymous user sees login page + - seeded admin can log in + - system governance menus appear + - user/role/menu pages render Chinese UI + - logout returns to login + +Full project verification: + +```bash +cd backend +python -m pytest -v +python -m ruff check . + +cd frontend +npm run typecheck +npm run build +``` + +## Acceptance Criteria + +- Fresh deployment can create database schema, seed governance data, and log in with the configured admin account. +- Frontend is no longer usable as an anonymous public app except for the login page. +- Sidebar menus come from backend-authorized menu data. +- Users, user groups, roles, permissions, and menus are manageable from Chinese frontend pages. +- Backend enforces permissions for ticket, solution, audit, and governance APIs. +- Frontend uses shadcn/ui primitives and project App components for all new governance UI. +- No Stage 2 knowledge base or AI platform features are implemented in this stage.