# Research Report Show + Update API — Curl / Postman

Prefill a category edit form with the values currently saved on a report (including featured image and PDF URLs), then POST the same fields back to the matching category update endpoint.

**Controller:** `DiverseResearchController`
**Middleware:** `jwt.auth`, `check.token`, `dynamic.permission`
(assign each route to the back-office user's role in route-API permissions first)

Base URL (XAMPP local):

```text
http://localhost/fintraBackend/fi_adm/public/api
```

Replace `YOUR_JWT_TOKEN` with the `access_token` from login.  
Updates are **POST** (multipart), not PUT, so existing files can be replaced.

---

## Locked rules

- `report_title` is regenerated server-side on every update using the same rules as the matching store method. Do not send it.
- `category_id` must match the report's existing category. Sending a different id returns 422. The report cannot be moved between categories.
- Files are **replace-only**. Omit `featured_image` / `english_pdf` / `bangla_pdf` to keep the saved file. There is no flag to clear a file without uploading a replacement.
- `updated_by` is set from `$request->users_id`. `created_by` is never changed.
- Pick the update URL that matches the report's category, the same way the store endpoints are picked.

| Category | Update URL | Controller method | Reuses request |
|---|---|---|---|
| Company Analysis | `POST /research-company/research-company-analysis-update/{id}` | `updateCompanyAnalysis` | `StoreCompanyAnalysisRequest` |
| Sector Analysis | `POST /research-company/research-sector-analysis-update/{id}` | `updateSectorAnalysis` | `StoreSectorAnalysisRequest` |
| Market Updates | `POST /research-company/research-market-updates-update/{id}` | `updateMarketUpdates` | `StoreMarketUpdatesRequest` |
| Macro Analysis | `POST /research-company/research-macro-analysis-update/{id}` | `updateMacroAnalysis` | `StoreMacroAnalysisRequest` |
| Special Feature | `POST /research-company/research-special-feature-update/{id}` | `updateSpecialFeatureReport` | `StoreSpecialFeatureReportRequest` |

---

## 0. Login (get JWT)

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/auth/login" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data-raw "{
    \"email\": \"your.backoffice@email.com\",
    \"password\": \"your_password\"
  }"
```

---

## 1. Show report (prefill the edit form)

**Method:** `GET`  
**URL:** `/research-company/research-report-show/{id}`  
**Controller:** `show`

One endpoint for all five forms. Each form ignores fields it does not render (Market Updates has no featured image, tags, or securities; Company Analysis has no `report_type_id`; etc.).

```bash
curl --location --request GET "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-report-show/17" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Success (200)

`tags` are **raw database names**, not the `#tag` display strings from Research History. Post those names back as-is.

`featured_image` / `english_pdf` / `bangla_pdf` are `{url, name}` when a file exists, otherwise `null` (empty `''` PDF columns are treated as missing).

```json
{
  "status": true,
  "data": {
    "id": 17,
    "category_id": 1,
    "category": { "id": 1, "name": "Company Analysis" },
    "report_type_id": null,
    "report_type": null,
    "report_title": "ACI_Q1_2026_2026-03-31",
    "sub_heading": "Q1 Company Snapshot",
    "quarter": "Q1",
    "report_date": "2026-03-31",
    "is_featured": true,
    "en_json": "{\"pages\":[]}",
    "bn_json": null,
    "featured_image": {
      "url": "http://localhost/storage/research_reports/hero.jpg",
      "name": "hero.jpg"
    },
    "english_pdf": {
      "url": "http://localhost/storage/research_reports/en.pdf",
      "name": "en.pdf"
    },
    "bangla_pdf": null,
    "stock_share_ids": [
      { "id": 42, "security_code": "ACI", "company_name": "ACI Limited" }
    ],
    "sector_ids": [],
    "tags": ["equity", "bank"]
  }
}
```

### Not found (404)

```json
{
  "status": false,
  "message": "Research report not found"
}
```

---

## 2. Update Company Analysis

Required (same as store): `report_date`, `stock_share_ids[]`, `category_id`.  
Optional: `sub_heading`, `quarter`, `is_featured`, `tags[]`, `en_json`, `bn_json`, and any replacement files.

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-company-analysis-update/17" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN" \
  --form "report_date=2026-03-31" \
  --form "stock_share_ids[]=42" \
  --form "sub_heading=Q1 Company Snapshot (revised)" \
  --form "quarter=Q1" \
  --form "is_featured=1" \
  --form "tags[]=equity" \
  --form "tags[]=bank" \
  --form "category_id=1" \
  --form "en_json={\"pages\":[]}" \
  --form "featured_image=@C:/path/to/new-hero.jpg"
```

Omitting `english_pdf` and `bangla_pdf` keeps the saved PDFs. Uploading `featured_image` replaces only that file.

---

## 3. Update Sector Analysis

Required: `report_date`, `sector_ids[]`, `category_id`.

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-sector-analysis-update/18" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN" \
  --form "report_date=2026-09-28" \
  --form "sector_ids[]=3" \
  --form "sub_heading=Banking sector note" \
  --form "is_featured=0" \
  --form "tags[]=banking" \
  --form "category_id=2"
```

---

## 4. Update Market Updates

Required: `report_type_id`, `report_date`, `category_id`.  
No featured image, tags, securities, or sectors. `is_featured` stays `false`.

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-market-updates-update/19" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN" \
  --form "report_type_id=5" \
  --form "report_date=2026-10-01" \
  --form "category_id=3" \
  --form "english_pdf=@C:/path/to/wrap-up.pdf"
```

---

## 5. Update Macro Analysis

Required: `report_date`, `report_type_id`, `category_id`.

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-macro-analysis-update/20" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN" \
  --form "report_date=2026-06-01" \
  --form "report_type_id=7" \
  --form "sub_heading=Budget note" \
  --form "is_featured=1" \
  --form "tags[]=macro" \
  --form "category_id=4"
```

---

## 6. Update Special Feature

Required: `report_date`, `report_type_id`, `stock_share_ids[]`, `category_id`.

```bash
curl --location --request POST "http://localhost/fintraBackend/fi_adm/public/api/research-company/research-special-feature-update/21" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_JWT_TOKEN" \
  --form "report_date=2026-10-01" \
  --form "report_type_id=9" \
  --form "stock_share_ids[]=42" \
  --form "sub_heading=Special note" \
  --form "is_featured=0" \
  --form "tags[]=feature" \
  --form "category_id=5"
```

---

## Error responses

### Category mismatch (422)

```json
{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "category_id": ["This report cannot be moved to another category."]
  }
}
```

### Validation failed (422)

Same shape as the matching store endpoint (missing `stock_share_ids`, invalid quarter, file too large, etc.).

### Not found (404)

```json
{
  "status": false,
  "message": "Research report not found"
}
```

---

## Per-category fields (what the form should submit)

| Field | Company | Macro | Market Updates | Sector | Special Feature |
|---|---|---|---|---|---|
| `category_id` | required, locked | required, locked | required, locked | required, locked | required, locked |
| `report_date` | required | required | required | required | required |
| `report_type_id` | — | required | required | — | required |
| `stock_share_ids[]` | required | — | — | — | required |
| `sector_ids[]` | — | — | — | required | — |
| `quarter` | optional Q1–Q4 | — | — | — | — |
| `sub_heading` | optional | optional | — | optional | optional |
| `is_featured` | optional | optional | always false | optional | optional |
| `tags[]` | optional | optional | — | optional | optional |
| `featured_image` | replace-only | replace-only | — | replace-only | replace-only |
| `english_pdf` / `bangla_pdf` | replace-only | replace-only | replace-only | replace-only | replace-only |
| `en_json` / `bn_json` | optional | optional | optional | optional | optional |

---

## Frontend notes

1. `GET research-report-show/{id}` when the user clicks Edit.
2. Bind every field the category form shows. Use `featured_image.url` / `english_pdf.url` / `bangla_pdf.url` as the current preview.
3. POST to the update URL for that category as `multipart/form-data`.
4. Only attach a file input when the user chose a new file.
5. Send `tags[]` as the raw names from show (not `#tag`).
6. `is_featured` is a boolean, not the `"Featured"` string from the client history API.

---

## route_apis insert query

```sql
INSERT INTO `route_apis` (`api_id`, `name`, `url`, `controller`, `function`, `prefix`, `method`, `details`, `api_activity_flag`, `created_by`, `create_date`, `create_time`, `update_by`, `update_date`, `update_time`, `created_at`, `updated_at`) VALUES
(NULL, 'research-report-show/{id}', 'research-report-show/{id}', 'DiverseResearchController', 'show', 'research-company', 'GET', 'research-report-show/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00'),
(NULL, 'research-company-analysis-update/{id}', 'research-company-analysis-update/{id}', 'DiverseResearchController', 'updateCompanyAnalysis', 'research-company', 'POST', 'research-company-analysis-update/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00'),
(NULL, 'research-sector-analysis-update/{id}', 'research-sector-analysis-update/{id}', 'DiverseResearchController', 'updateSectorAnalysis', 'research-company', 'POST', 'research-sector-analysis-update/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00'),
(NULL, 'research-market-updates-update/{id}', 'research-market-updates-update/{id}', 'DiverseResearchController', 'updateMarketUpdates', 'research-company', 'POST', 'research-market-updates-update/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00'),
(NULL, 'research-macro-analysis-update/{id}', 'research-macro-analysis-update/{id}', 'DiverseResearchController', 'updateMacroAnalysis', 'research-company', 'POST', 'research-macro-analysis-update/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00'),
(NULL, 'research-special-feature-update/{id}', 'research-special-feature-update/{id}', 'DiverseResearchController', 'updateSpecialFeatureReport', 'research-company', 'POST', 'research-special-feature-update/{id} API', 'R', '5', '2026-10-01', '11:00:00', NULL, NULL, NULL, '2026-10-01 11:00:00', '2026-10-01 11:00:00');
```
