---
name: design-complex-business-module
description: Use when designing a complex enterprise business module that needs RBAC permissions, frontend/backend permission controls, state transitions, illegal transition handling, audit logging, exception states, dashboard metrics, interface contracts, or acceptance-ready design assets.
---

# Design Complex Business Module

## Core Principle

Design the control surfaces before designing code. For complex business modules, produce permission, state, audit, exception, dashboard, and acceptance assets before implementation planning.

Do not jump from a requirement to CRUD code. Every business rule must have an owner, a source, and a verification method.

## Inputs

Collect what exists, then mark gaps explicitly:

- Business requirement or user stories.
- Target project paths and project constraints.
- Existing roles, permissions, menus, routes, API layer, backend controllers/services, data model, and audit/logging patterns.
- Known non-goals and delivery deadline.
- Existing rules, checklists, or project knowledge docs.

If project evidence is missing, label outputs as `建议` or `待确认`, not `事实`.

## Workflow

1. Define scope: module name, actors, key workflows, non-goals, and acceptance boundary.
2. Build the RBAC matrix: roles x features, with `允许`, `拒绝`, or `条件允许`.
3. Translate RBAC into a permission control plan: page/menu, button, backend API, and data scope.
4. Design the state machine: states, actions, allowed roles, preconditions, post-actions, and terminal states.
5. List illegal transitions and rejection behavior.
6. Design audit logging: actions, write timing, actor, target, old/new values, source/request id, masking, and failure behavior.
7. Complete exception states: permission denied, missing data, invalid state, duplicate submit, validation failure, concurrency, empty dashboard, empty audit log.
8. Define dashboard metrics: meaning, formula, dimensions, filters, data source, permission, empty state, and manual verification.
9. Produce interface and acceptance notes only after the above assets are consistent.

## Output Contract

Generate these assets unless the user narrows scope:

```text
RBAC权限矩阵
权限控制方案
状态流转表
非法流转清单
审计日志SOP
异常态清单
看板指标字典
看板接口验收记录
不确定点清单
```

Use the templates in `assets/` when creating files.

## Quality Gates

- Every sensitive action has frontend visibility control and backend enforcement.
- Data permissions are not replaced by button hiding.
- Every state transition has a reverse or rejection story, or is explicitly terminal.
- Every illegal transition has expected system response and validation method.
- Every successful critical operation has an audit record; failed operations do not write success audit.
- Every dashboard metric has a formula or filter logic that can be manually checked.
- Every output distinguishes `事实`, `推断`, `建议`, and `待确认`.

## Common Mistakes

- Do not design UI first and add permissions later.
- Do not use "admin can do everything" as a complete RBAC design.
- Do not put all status rules into prose; use a state table.
- Do not write "record audit log" without naming fields and write timing.
- Do not define dashboard cards without metric formulas and data scope.
- Do not turn project-specific permission strings into facts without source evidence.