# AI_GUIDELINES — Claude Code Control Document (Yii2 NetSuite Extension)

**Last verified:** 2026-02-25 00:00 (Europe/London)
**Scope:** Dev-only. This repository is a Yii2 extension (`yii2-extension`) for NetSuite ERP integration.
**Primary goal:** Enable safe, deterministic audit, documentation, and development assistance.
**Default mode:** Read-only.

> **Note:** This file replaces an earlier version that incorrectly referenced Magento and getAddress.io.
> This project is **not** a Magento module.

---

## 0) Non-Negotiables (behavioural contract)

1. **Read-only by default**
   - Do not change code, configuration, or documentation unless explicitly instructed by a human maintainer.

2. **No invention**
   - Do not invent architecture, integrations, auth models, deployment details, or behaviours.
   - If something is unclear, mark it **TBD** and add a verification task to `/docs/TODO.md`.

3. **Dev-only documentation**
   - Do not reference production.
   - Do not add environment matrices (Dev / Staging / Prod).

4. **Evidence-based documentation**
   - Prefer evidence order: code > repo docs > changelog.
   - If docs and code disagree: do not fix silently. Record the discrepancy in `/docs/TODO.md`.

5. **Scope boundary**
   - Document only this Yii2 extension and its direct interactions with:
     - The host Yii2 application (events, components, config)
     - The NetSuite REST API (OAuth 2.0, record endpoints, SuiteQL)
   - Do not document host application internals unless they are directly referenced in this module's source code.

---

## 1) Mandatory Read Order (before any audit conclusions)

1. `README.md`
2. `SETTINGS.md`
3. `composer.json`
4. `src/Module.php` — bootstrap, events, config loading
5. `src/NetSuiteApiAuth.php` — JWT auth implementation
6. `src/NetSuiteClient.php` — HTTP client
7. `src/components/NetSuiteComponent.php` — high-level CRUD wrapper
8. `src/components/SearchBuilder.php` — query DSL
9. `src/models/` — record model classes
10. `src/controllers/` — SettingsController, NetsuiteController
11. `src/jobs/Sendtonetsuite.php` — async queue job
12. `src/config/ns.php.template` — configuration template

Then read:
13. `docs/SYSTEM_MAP.md`
14. `docs/ARCHITECTURE.md`
15. `docs/API.md`
16. `docs/SECURITY.md`
17. `docs/GDPR.md`
18. `docs/TODO.md`
19. `docs/AUDIT.md`

If `/docs/*` files do not exist yet, create them using evidence from code only.

---

## 2) Project Structure Reference

```
ahs-netsuite/
├── src/
│   ├── Module.php                  # Bootstrap, events, config load
│   ├── NetSuiteApiAuth.php         # OAuth 2.0 JWT client (extends yii\authclient\OAuth2)
│   ├── NetSuiteClient.php          # HTTP client (Bearer token, GET/POST/PATCH/DELETE)
│   ├── NetSuiteApi.php             # Legacy OAuth 1.0 wrapper (deprecated)
│   ├── assets/                     # Yii2 AssetBundle (CSS, JS)
│   ├── components/
│   │   ├── NetSuiteComponent.php   # High-level CRUD wrapper + SendOrderToNetsuite (legacy)
│   │   └── SearchBuilder.php       # Fluent query builder (REST filter + SuiteQL)
│   ├── config/
│   │   ├── ns.php.template         # Configuration template (ns.php must NOT be committed)
│   │   └── README.md               # Private key placement guide
│   ├── controllers/
│   │   ├── SettingsController.php  # Admin settings + connection test
│   │   └── NetsuiteController.php  # Order link modal
│   ├── jobs/
│   │   └── Sendtonetsuite.php      # Queue job for async order sync
│   ├── models/
│   │   ├── NetSuiteRecord.php      # Abstract base model
│   │   ├── Customer.php            # customer record
│   │   ├── Item.php                # inventoryitem record
│   │   ├── SalesOrder.php          # salesorder record
│   │   ├── SettingsForm.php        # Admin settings form model
│   │   ├── carts/Netsuite.php      # Cart integration model
│   │   └── products/Netsuite.php   # Product integration model
│   └── views/                      # Admin UI views (settings, cart tabs, product tabs)
├── docs/                           # All project documentation
├── examples/                       # Usage examples (dev reference)
└── composer.json
```

---

## 3) Key Facts About This Project

- **Framework:** Yii2 (not Laravel, not Symfony, not Magento)
- **Package type:** `yii2-extension` — bootstrapped via `extra.bootstrap` in `composer.json`
- **Auth:** OAuth 2.0 JWT Client Credentials (ES256 / ECDSA P-256 private key)
- **HTTP:** `yii\httpclient\Client` wrapping GuzzleHTTP
- **Queue:** Expects a `netsuitequeue` component on the host Yii2 application
- **Events:** All integration hooks use `Event::on()` in `Module::setEvents()`
- **No database models** — this is a pure API client; no Yii2 `ActiveRecord` classes

---

## 4) Audit Output Requirements

When performing a documentation audit, produce:

### Output A — Findings
- Bootstrap and registration wiring (`Module.php` → `composer.json` → host app config)
- Auth flow (JWT token construction and endpoint)
- Event hook catalogue (all `Event::on()` calls and their effects)
- Config loading and encryption path
- Known bugs and security findings
- Discrepancies between docs and code

### Output B — Documentation Set (evidence-based)
- `/docs/SYSTEM_MAP.md` (L0 context only)
- `/docs/ARCHITECTURE.md` (L1 containers + L2 module components + L3 key flows)
- `/docs/API.md` (endpoints, record types, field mappings, SearchBuilder operators)
- `/docs/SECURITY.md`
- `/docs/GDPR.md` (if not already present)
- `/docs/TODO.md` (verification tasks + known issues)
- `/docs/AUDIT.md` (full findings summary)

### Output C — Fix Plan (no code changes)
- Prioritised findings
- Minimal-change repair proposals
- Files likely to be touched
- Risks and rollback notes

---

## 5) PII / Secrets Rules (hard constraints)

- Never log or echo API keys, JWT tokens, consumer secrets, or private key content.
- Do not log full addresses, order contents, or user emails in debug output.
- If evidence shows plaintext credential logging, flag as a critical finding (see [SECURITY.md](docs/SECURITY.md)).
- `ns.php` must never be committed. It is excluded via `src/config/.gitignore`.

---

## 6) "TBD" Discipline

Mark as TBD when evidence is absent:
- Queue component interface details (host app specific)
- Custom NetSuite field IDs beyond what is in source (`custbody_*`, `custcol_*`)
- Actual NetSuite account ID in use (beyond `4465021` hardcoded in `NetSuiteApiAuth.php`)
- RBAC role names for settings access restrictions

All TBDs must appear in `/docs/TODO.md` as verification tasks.

---

## 7) Definition of Done (audit + docs)

Done when:
- All `/docs` files exist and match code evidence
- All uncertain areas are marked TBD and tracked in `/docs/TODO.md`
- No production assumptions were introduced
- No integrations were invented
- Mermaid diagrams follow `/docs/MERMAID_DIAGRAM_STANDARDS.md`
