---
name: step-01-screens
description: Define sections and resources with detailed UI specs per module
model: opus
next_step: steps/step-02-wireframes.md
---

# Step 01 — Screens (Define Sections & Resources)

## Objective

For each module, define all sections and resources with detailed interface specifications: SmartTable columns, SmartForm fields with types, SmartDashboard KPIs, SmartKanban columns.

## Context Recovery

Re-read session variables (do NOT rely on LLM memory from prior skill invocation):
```javascript
const config = readJSON('.business-analyse/config.json').currentFeature;
const { id: feature_id, docsDir: docs_dir, projectSlug, application: application_name,
        applicationCode, language } = config;

// Path helpers (ba-006)
function toKebabCase(code) {
  return code.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2').toLowerCase();
}
function resolveModuleDir(appCode, moduleCode) {
  return `${docs_dir}/${toKebabCase(appCode)}/${toKebabCase(moduleCode)}`;
}
```

> **screens.json output (ba-006):** Written to `resolveModuleDir(appCode, moduleCode)/screens.json`
> Example: `docs/projet-rh/v1.0/human-resources/employees/screens.json`

## Prerequisites

- `/business-analyse` completed (entities, usecases, permissions exist)
- Module index.json accessible via ba-reader

## Execution

### 1. Load Analysis Data

For each module (in dependency order from index.json):

```
Load via ba-reader:
  - entities.json → entity attributes with types, relationships
  - usecases.json → actor actions, CRUD operations
  - permissions.json → role matrix, permission paths
  - index.json → anticipatedSections from step-02
```

### 2. Define Sections & Resources

For each module, transform anticipatedSections into detailed screen specs.

**SmartTable resource:**
```json
{
  "code": "{entity-plural}-grid",
  "type": "SmartTable",
  "label": "Grille des {entity-plural}",
  "columns": [
    { "field": "code", "label": "Code", "type": "text", "sortable": true, "width": "100px" },
    { "field": "fullName", "label": "Nom", "type": "text", "sortable": true },
    { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
    { "field": "status", "label": "Statut", "type": "badge", "filterable": true, "options": ["Active", "Inactive"] }
  ],
  "actions": ["create", "edit", "delete", "export"],
  "filters": [
    { "field": "department", "type": "select", "label": "Departement" },
    { "field": "status", "type": "select", "label": "Statut" }
  ],
  "permission": "{AppCode}.{ModuleCode}.Read",
  "rowActions": ["edit", "view-detail"],
  "defaultSort": { "field": "code", "direction": "asc" },
  "pageSize": 25
}
```

**SmartForm resource:**
```json
{
  "code": "{entity}-form",
  "type": "SmartForm",
  "label": "Fiche {entity}",
  "tabs": [
    {
      "label": "Informations",
      "fields": [
        { "field": "firstName", "label": "Prenom", "type": "text", "required": true, "col": 6 },
        { "field": "lastName", "label": "Nom", "type": "text", "required": true, "col": 6 },
        { "field": "email", "label": "Email", "type": "email", "required": true, "validation": "unique" },
        { "field": "department", "label": "Departement", "type": "lookup", "entity": "Department", "required": true },
        { "field": "status", "label": "Statut", "type": "select", "options": ["Active", "Inactive"], "readonly": "onCreate" }
      ]
    },
    {
      "label": "Contrats",
      "type": "subtable",
      "entity": "Contract",
      "columns": ["contractType", "startDate", "endDate", "status"]
    }
  ],
  "permission": "{AppCode}.{ModuleCode}.Update"
}
```

**SmartDashboard resource:**
```json
{
  "code": "{module}-dashboard",
  "type": "SmartDashboard",
  "label": "Tableau de bord {module}",
  "kpis": [
    { "label": "Total actifs", "value": "count(status=Active)", "icon": "users", "color": "primary" },
    { "label": "En conge", "value": "count(status=OnLeave)", "icon": "calendar", "color": "warning" }
  ],
  "charts": [
    { "type": "pie", "label": "Repartition par departement", "dataSource": "employees", "groupBy": "department" },
    { "type": "bar", "label": "Evolution des effectifs", "dataSource": "employees", "groupBy": "hireDate.year" }
  ],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

**SmartKanban resource:**
```json
{
  "code": "{entity}-kanban",
  "type": "SmartKanban",
  "label": "Kanban {entity}",
  "statusField": "status",
  "columns": [
    { "value": "Draft", "label": "Brouillon", "color": "gray" },
    { "value": "Submitted", "label": "Soumis", "color": "blue" },
    { "value": "Approved", "label": "Approuve", "color": "green" }
  ],
  "cardFields": ["code", "assignee", "dueDate"],
  "permission": "{AppCode}.{ModuleCode}.Read"
}
```

### 3. Column/Field Type Mapping

Map entity attribute types to UI component types:

| Entity type | SmartTable type | SmartForm type |
|-------------|----------------|----------------|
| `string` | `text` | `text` |
| `int`, `decimal` | `number` | `number` |
| `date` | `date` | `datepicker` |
| `datetime` | `datetime` | `datetimepicker` |
| `bool` | `boolean` | `checkbox` |
| `enum` | `badge` | `select` |
| `guid` (FK) | `lookup` | `lookup` |
| `text` (long) | `text` (truncated) | `textarea` |

### 4. Write screens.json

For each module, write via ba-writer:

> **CANONICAL FORMAT (MANDATORY):** screens.json MUST use the `sections[]` wrapper format below.
> Keys MUST be `sectionCode` and `sectionLabel` (not `id`/`displayName`/`code`/`label`).
> Each section MUST have a `resources[]` array with typed resource objects (SmartTable, SmartForm, etc.).
> The flat `screens[]` format (one object per screen with componentType at top level) is **DEPRECATED**.
> All downstream consumers (business-analyse-html, business-analyse-handoff, business-analyse-develop) expect `sections[]`.

```json
{
  "sections": [
    {
      "sectionCode": "list",
      "sectionLabel": "Liste des employes",
      "resources": [
        {
          "code": "employees-grid",
          "type": "SmartTable",
          "label": "Grille des employes",
          "columns": [ /* ... */ ],
          "filters": [ /* ... */ ],
          "actions": ["create", "export"],
          "permission": "HumanResources.Employees.Read"
        }
      ]
    },
    {
      "sectionCode": "detail",
      "sectionLabel": "Fiche employe",
      "resources": [
        {
          "code": "employee-form",
          "type": "SmartForm",
          "label": "Fiche employe",
          "tabs": [ /* ... */ ],
          "actions": ["save", "cancel"],
          "permission": "HumanResources.Employees.Update"
        }
      ]
    },
    {
      "sectionCode": "dashboard",
      "sectionLabel": "Tableau de bord",
      "resources": [
        {
          "code": "employees-dashboard",
          "type": "SmartDashboard",
          "label": "Tableau de bord RH",
          "kpis": [ /* ... */ ],
          "charts": [ /* ... */ ],
          "permission": "HumanResources.Employees.Read"
        }
      ]
    }
  ]
}
```

> **Key naming:** Use `sectionCode` (not `id`, `code`). Use `sectionLabel` (not `displayName`, `label`).
> Resource `type` must be one of: `SmartTable`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`, `SmartFilter`.

Update `index.json` with screens.json hash and status.

## Validation

- [ ] Every resource has a valid `permission` referencing permissions.json
- [ ] Every SmartTable column references a valid entity attribute
- [ ] Every SmartForm field references a valid entity attribute
- [ ] Every section has at least one resource
- [ ] Every module has at least one section

## Transition

-> Step 02 (wireframes) — Generate visual mockups for each screen
