mahdahar
09a1c6715f
- Update UnVal visibility condition from ISVAL check to VAL1USER && VAL2USER - Fix validated-but-incomplete requests missing the UnVal action button - Align isValidated() function with same logic for consistency - Refactor AGENTS.md formatting
159 lines
5.6 KiB
Markdown
159 lines
5.6 KiB
Markdown
# AGENTS.md
|
|
Guidance for coding agents working in `D:\data\www\gdc_cmod`.
|
|
|
|
## 1) Repository Summary
|
|
- Stack: CodeIgniter 4 + PHP 8.1+.
|
|
- Package manager: Composer.
|
|
- Test framework: PHPUnit 10 (`phpunit.xml.dist`).
|
|
- App domain: laboratory workflow (requests, samples, validation, reporting).
|
|
- Auth: session-based, route filters (`role`, `guest`).
|
|
- Data sources: SQL Server (`GDC_CMOD.dbo`) + legacy Firebird integration.
|
|
- Frontend: PHP views with Tailwind/DaisyUI/Alpine assets from `public/`.
|
|
|
|
## 2) Rule Files Check
|
|
- Cursor rules: not found (`.cursor/rules/` and `.cursorrules` absent).
|
|
- Copilot rules: not found (`.github/copilot-instructions.md` absent).
|
|
- If these files are later added, treat them as high-priority instructions.
|
|
|
|
## 2.1) Codebase-Memory MCP Workflow (Default)
|
|
- This repository is indexed in `codebase-memory-mcp` (session project `D-data-www-gdc_cmod`).
|
|
- Before broad architecture analysis, run:
|
|
- `index_status` (confirm graph is ready)
|
|
- `get_architecture` for `languages`, `packages`, `layers`, `file_tree`
|
|
- Prefer `search_graph` + `get_code_snippet` + `trace_call_path` for impact/call-chain questions.
|
|
- For change impact before commits, use `detect_changes(scope='all'|'branch')`.
|
|
- Important: results can be noisy due to minified vendor assets in `public/js/*.min.js`.
|
|
- When querying routes/hotspots, scope to app PHP files (`file_pattern='app/**/*.php'`) where possible.
|
|
|
|
## 3) Core Commands
|
|
```bash
|
|
# install deps
|
|
composer install
|
|
|
|
# run dev server
|
|
php spark serve
|
|
|
|
# list spark commands
|
|
php spark
|
|
|
|
# list routes (preferred)
|
|
php spark routes
|
|
|
|
# alternate command used in this repo
|
|
php spark list
|
|
```
|
|
|
|
## 4) Test Commands (Use These)
|
|
```bash
|
|
# full suite
|
|
composer test
|
|
|
|
# full suite (direct)
|
|
./vendor/bin/phpunit
|
|
|
|
# windows direct
|
|
vendor\bin\phpunit
|
|
|
|
# single test file
|
|
./vendor/bin/phpunit tests/unit/ReportTest.php
|
|
|
|
# single test class
|
|
./vendor/bin/phpunit --filter ReportTest
|
|
|
|
# single test method
|
|
./vendor/bin/phpunit tests/unit/HealthTest.php --filter testIsDefinedAppPath
|
|
|
|
# single test directory
|
|
./vendor/bin/phpunit tests/unit
|
|
```
|
|
|
|
## 5) Lint / Static Analysis
|
|
- No dedicated linter/formatter configs were found (`phpcs`, `php-cs-fixer`, `pint`).
|
|
- No static analysis configs were found (`phpstan`, `psalm`).
|
|
- Use syntax lint for changed PHP files:
|
|
```bash
|
|
php -l app/Controllers/RequestsController.php
|
|
php -l app/Config/Routes.php
|
|
```
|
|
- If you add QA tooling, update this file with exact commands.
|
|
|
|
## 6) Code Organization
|
|
- Controllers: `app/Controllers` and `app/Controllers/Pages`.
|
|
- Filters: `app/Filters`, aliases in `app/Config/Filters.php`.
|
|
- Routes: `app/Config/Routes.php`.
|
|
- Views: `app/Views/...`.
|
|
- Tests: `tests/unit`, `tests/database`, `tests/session`, `tests/_support`.
|
|
- Most DB access uses raw SQL (`\Config\Database::connect()`), not CI models.
|
|
|
|
## 7) Style Rules (PHP)
|
|
|
|
### Imports and namespaces
|
|
- Keep valid namespace per folder.
|
|
- Use `use` imports for frequently referenced classes.
|
|
- Remove unused imports.
|
|
- Keep one class per file.
|
|
|
|
### Formatting
|
|
- Prefer 4 spaces in new/edited code.
|
|
- Existing files may contain mixed tabs/spaces; avoid full-file reformat churn.
|
|
- Keep methods small; extract helpers for complex branching.
|
|
- Keep comments sparse; only explain non-obvious logic.
|
|
|
|
### Types
|
|
- Add parameter and return types in new/modified methods when practical.
|
|
- Prefer explicit casts for session/DB values used in role or numeric logic.
|
|
- Prefer strict comparisons (`===`, `!==`) over loose comparisons.
|
|
|
|
### Naming
|
|
- Classes: `PascalCase`.
|
|
- Methods/variables: `camelCase`.
|
|
- Constants: `UPPER_SNAKE_CASE` (`ROLE_NAMES`).
|
|
- SQL identifiers follow existing DB naming (often uppercase).
|
|
- Views use existing naming conventions (lowercase/underscores).
|
|
|
|
## 8) Imports, Responses, and Controller Patterns
|
|
- API endpoints commonly use `CodeIgniter\API\ResponseTrait`.
|
|
- JSON responses: `$this->response->setJSON([...])` or `$this->respond([...])`.
|
|
- HTML responses: `return view('path/to/view', $data);`.
|
|
- Inputs: `getGet()`, `getPost()`, `getJSON(true)` based on content type.
|
|
- Validate required inputs early and return errors promptly.
|
|
|
|
## 9) SQL and Data Safety
|
|
- Prefer parameterized queries for all user/session-controlled values.
|
|
- Good: `$db->query('... WHERE ACCESSNUMBER = ?', [$accessNumber]);`
|
|
- Avoid: SQL string interpolation with raw request/session data.
|
|
- Use transactions for multi-step writes that must be atomic.
|
|
- Preserve dual-validation behavior (`ISVAL1/ISVAL2`, two distinct users).
|
|
- Keep audit logging writes (`AUDIT_EVENTS`, `AUDIT_REQUESTS`) intact when changing flows.
|
|
|
|
## 10) Error Handling and Logging
|
|
- Return consistent JSON shape for API failures (`status`, `message`).
|
|
- For external HTTP/cURL calls, check HTTP code and handle failures explicitly.
|
|
- Use `log_message('error', ...)` for operational failures.
|
|
- Do not expose secrets, stack traces, or sensitive internals to clients.
|
|
|
|
## 11) Security Requirements
|
|
- Escape user-facing output in views with `esc()`.
|
|
- Enforce auth + role checks through route filters and session state.
|
|
- Use `password_hash()` and `password_verify()` for credentials.
|
|
- Never commit `.env` or secrets.
|
|
|
|
## 12) Role and Routing Conventions
|
|
- Role IDs:
|
|
- `0` Superuser
|
|
- `1` Admin
|
|
- `2` Lab
|
|
- `3` Phlebo
|
|
- `4` CS
|
|
- Route filter examples:
|
|
- Single role: `['filter' => 'role:1']`
|
|
- Multiple roles: `['filter' => 'role:0,1,2']`
|
|
|
|
## 13) Agent Change Checklist
|
|
- Make minimal, targeted changes.
|
|
- Do not revert unrelated local modifications.
|
|
- Keep backward compatibility for response payloads unless asked otherwise.
|
|
- Run at least one relevant test file after code changes.
|
|
- If no tests exist for a changed behavior, add focused tests when feasible.
|
|
- Update this file when commands/conventions/tooling change.
|