Revise Copilot instructions for clarity and updates
Updated Copilot instructions to clarify no-code planning mode and functional requirements.
This commit is contained in:
GitHub
parent
06b0074cee
commit
6dba37ed5e
1 changed files with 96 additions and 151 deletions
247
.github/copilot-instructions.md
vendored
247
.github/copilot-instructions.md
vendored
|
|
@ -1,151 +1,96 @@
|
||||||
Repo of truth: GameServerPanel/GSP, branch Panel-unstable.
|
# GSP (GameServerPanel) — Copilot Instructions (No-Code)
|
||||||
Prime directive: Read this document first. Propose changes that align with our repo and specs. Only search for external info if something contradicts this file.
|
|
||||||
|
**Repo of truth:** `GameServerPanel/GSP`, branch `Panel-unstable`.
|
||||||
1) What to read first (paths & context)
|
**Prime directive:** Read this document first. Propose changes that align with our repo and specs. Only search for external info if something contradicts this file.
|
||||||
|
|
||||||
_website/ — canonical website storefront and Checkout/Webhooks flow.
|
## 1) What to read first (paths & context)
|
||||||
|
- `_website/` — canonical website storefront and Checkout/Webhooks flow.
|
||||||
modules/config_games/server_configs/ — authoritative game catalog XMLs (all supported games live here).
|
- `modules/config_games/server_configs/` — authoritative game catalog XMLs (all supported games live here).
|
||||||
|
- `modules/` — panel modules (legacy `billing/` exists; its **schema** is authoritative for multi-remote, but the **pages** are deprecated).
|
||||||
modules/ — panel modules (legacy billing/ exists; its schema is authoritative for multi-remote, but the pages are deprecated).
|
- `includes/` — panel configuration and DB connectors.
|
||||||
|
- `ogp_api.php` — internal API entry point for panel-side actions.
|
||||||
includes/ — panel configuration and DB connectors.
|
- `paypal/` — PayPal code if present in this branch.
|
||||||
|
|
||||||
ogp_api.php — internal API entry point for panel-side actions.
|
## 2) No-Code Planning Mode (default)
|
||||||
|
- Do **not** emit PHP, SQL, XML, or shell commands unless a maintainer explicitly asks: **“Generate code now.”**
|
||||||
paypal/ — PayPal code if present in this branch.
|
- While in planning mode, produce only:
|
||||||
|
- Impacted paths and files,
|
||||||
2) No-Code Planning Mode (default)
|
- Step-by-step plans with acceptance criteria,
|
||||||
|
- Risks, rollbacks, and test/validation checklists,
|
||||||
Do not emit PHP, SQL, XML, or shell commands unless a maintainer explicitly asks: “Generate code now.”
|
- Data mappings that reference existing tables/fields.
|
||||||
|
|
||||||
While in planning mode, produce only:
|
## 3) Scope & principles
|
||||||
|
- **Website ↔ Panel on the same host.** Website uses the **panel DB for authentication** and the **panel’s internal APIs** for provisioning. **Sessions remain separate** (website session ≠ panel session).
|
||||||
Impacted paths and files,
|
- **Catalog = XML.** Enable **every game** present under `modules/config_games/server_configs/`. The website reads those XMLs for ports, params, install/update metadata. New XMLs should become available without code changes.
|
||||||
|
- **Regions/Nodes = panel DB.** Regions and nodes are configured in the panel and must be **queried live** from the panel DB. Never hardcode or mirror region lists on the website.
|
||||||
Step-by-step plans with acceptance criteria,
|
- **Slotless model.** Pricing/UX must not enforce slot caps. If an engine requires a player count parameter, set a safe high default and surface engine limits transparently if they exist.
|
||||||
|
- **Auth compatibility.** Panel users use legacy MD5 in `ogp_users`. The website should prefer a modern hashing shadow and upgrade transparently on successful login, **without breaking panel login**.
|
||||||
Risks, rollbacks, and test/validation checklists,
|
- **Checkout/Webhooks.** Follow the working **PayPal Checkout** flow in `_website/`. Use **REST Webhooks** only. Mark orders paid **only** after webhook verification.
|
||||||
|
- **Legacy billing module.** Treat `modules/billing/` **pages** as deprecated. Reuse the **existing tables/fields** introduced there for **multi-remote** support. Do not invent parallel schema.
|
||||||
Data mappings that reference existing tables/fields.
|
|
||||||
|
## 4) Functional requirements (design-level only)
|
||||||
3) Scope & principles
|
### 4.1 Catalog (from XML)
|
||||||
|
- Parse all XMLs under `modules/config_games/server_configs/`.
|
||||||
Website ↔ Panel on the same host. Website uses the panel DB for authentication and the panel’s internal APIs for provisioning. Sessions remain separate (website session ≠ panel session).
|
- Normalize game key, display name, required ports, startup parameters, install/update routines, and any engine constraints.
|
||||||
|
- Support hot-add: new XMLs become available to the storefront after a repo update.
|
||||||
Catalog = XML. Enable every game present under modules/config_games/server_configs/. The website reads those XMLs for ports, params, install/update metadata. New XMLs should become available without code changes.
|
|
||||||
|
### 4.2 Authentication & sessions
|
||||||
Regions/Nodes = panel DB. Regions and nodes are configured in the panel and must be queried live from the panel DB. Never hardcode or mirror region lists on the website.
|
- Website registration creates a panel user (legacy-compatible) and stores a **modern hash shadow** linked 1:1 to that user.
|
||||||
|
- Login prefers the modern hash; on MD5 success, upgrade silently to the modern hash.
|
||||||
Slotless model. Pricing/UX must not enforce slot caps. If an engine requires a player count parameter, set a safe high default and surface engine limits transparently if they exist.
|
- Maintain **separate sessions** for website and panel.
|
||||||
|
|
||||||
Auth compatibility. Panel users use legacy MD5 in ogp_users. The website should prefer a modern hashing shadow and upgrade transparently on successful login, without breaking panel login.
|
### 4.3 Checkout → Webhooks → Provisioning
|
||||||
|
- Mirror `_website/` structure and flows for Checkout.
|
||||||
Checkout/Webhooks. Follow the working PayPal Checkout flow in _website/. Use REST Webhooks only. Mark orders paid only after webhook verification.
|
- On verified webhook events: transition order state to paid, create service records, and **provision** a panel Home using internal panel APIs.
|
||||||
|
- Derive ports and startup parameters **from the XML metadata**.
|
||||||
Legacy billing module. Treat modules/billing/ pages as deprecated. Reuse the existing tables/fields introduced there for multi-remote support. Do not invent parallel schema.
|
|
||||||
|
### 4.4 Regions/Nodes (multi-remote)
|
||||||
4) Functional requirements (design-level only)
|
- At checkout or during provisioning, present or auto-select regions/nodes by reading **the panel DB**.
|
||||||
4.1 Catalog (from XML)
|
- If a node is hidden/disabled in the panel, it must not appear in the website UI.
|
||||||
|
|
||||||
Parse all XMLs under modules/config_games/server_configs/.
|
### 4.5 Billing automation (website-side)
|
||||||
|
- Reconcile renewals and invoke panel APIs to suspend/reactivate/terminate services.
|
||||||
Normalize game key, display name, required ports, startup parameters, install/update routines, and any engine constraints.
|
- Operations must be idempotent and observable (logs/metrics defined at design time).
|
||||||
|
|
||||||
Support hot-add: new XMLs become available to the storefront after a repo update.
|
## 5) Data model alignment (no DDL)
|
||||||
|
- Use the **panel DB as the source of truth**.
|
||||||
4.2 Authentication & sessions
|
- **Multi-remote** tables and fields already exist (introduced by the legacy billing work). Reuse them.
|
||||||
|
- Only propose new fields/tables if strictly necessary; when doing so, reference existing naming conventions and provide a migration plan (still no SQL while in planning mode).
|
||||||
Website registration creates a panel user (legacy-compatible) and stores a modern hash shadow linked 1:1 to that user.
|
|
||||||
|
## 6) Coding standards & security (what to enforce when code is requested)
|
||||||
Login prefers the modern hash; on MD5 success, upgrade silently to the modern hash.
|
- **Repository-first:** Before proposing file names, endpoints, or structures, search `Panel-unstable` to reuse existing helpers, patterns, and locations.
|
||||||
|
- **Strictness:** Prefer strict comparisons; parameterized DB access; centralized input validation and output escaping.
|
||||||
Maintain separate sessions for website and panel.
|
- **Session & CSRF:** Harden website sessions and require CSRF tokens on state-changing requests.
|
||||||
|
- **Webhooks:** Verify signatures and event types server-side; never trust client redirects for payment state.
|
||||||
4.3 Checkout → Webhooks → Provisioning
|
- **XML:** Harden parsing (no external entities; size/complexity limits). Treat XML as untrusted input even though it’s in-repo.
|
||||||
|
- **Observability:** Define success/failure metrics, audit logs for state changes, and trace IDs for provisioning flows.
|
||||||
Mirror _website/ structure and flows for Checkout.
|
- **Licensing:** Preserve upstream notices and ensure our additions stay license-compatible.
|
||||||
|
|
||||||
On verified webhook events: transition order state to paid, create service records, and provision a panel Home using internal panel APIs.
|
## 7) Validation checklist (pre-PR / pre-merge)
|
||||||
|
- Read `_website/`, `modules/config_games/server_configs/`, `modules/`, `includes/`, `paypal/` (if present), and `ogp_api.php` to anchor proposals to actual code.
|
||||||
Derive ports and startup parameters from the XML metadata.
|
- Catalog uses only the XML metadata; no hardcoded ports/params.
|
||||||
|
- Regions/nodes are read live from the panel DB; no duplicates on the website.
|
||||||
4.4 Regions/Nodes (multi-remote)
|
- Auth plan preserves panel compatibility and modernizes website hashing; **sessions remain separate**.
|
||||||
|
- Checkout mirrors `_website/`; uses **REST Webhooks**; paid state changes occur only after verification.
|
||||||
At checkout or during provisioning, present or auto-select regions/nodes by reading the panel DB.
|
- Provisioning calls panel internals (e.g., `ogp_api.php`), respects selected/auto node, and records mappings consistently.
|
||||||
|
- Legacy billing module pages are not extended; its schema is reused for multi-remote.
|
||||||
If a node is hidden/disabled in the panel, it must not appear in the website UI.
|
- Security items from §6 are addressed in the plan: CSRF, webhook verification, strict comparisons, hardened XML.
|
||||||
|
|
||||||
4.5 Billing automation (website-side)
|
## 8) Deliverables for Copilot (when planning)
|
||||||
|
- A concise change plan that lists:
|
||||||
Reconcile renewals and invoke panel APIs to suspend/reactivate/terminate services.
|
- Files to create/modify/remove and their locations,
|
||||||
|
- Data sources and mappings to existing tables/fields,
|
||||||
Operations must be idempotent and observable (logs/metrics defined at design time).
|
- UX notes (e.g., region selector vs auto-placement),
|
||||||
|
- Risks, rollback approach, and test coverage,
|
||||||
5) Data model alignment (no DDL)
|
- Acceptance criteria aligned to these instructions.
|
||||||
|
- Update `CHANGELOG.md` with a brief, high-signal entry (date, scope, rationale).
|
||||||
Use the panel DB as the source of truth.
|
- Append a single line item to `docs/COPILOT_TODO.md` for any UI follow-ups or next steps.
|
||||||
|
|
||||||
Multi-remote tables and fields already exist (introduced by the legacy billing work). Reuse them.
|
## 9) Prohibited while in planning
|
||||||
|
- No PHP/SQL/XML.
|
||||||
Only propose new fields/tables if strictly necessary; when doing so, reference existing naming conventions and provide a migration plan (still no SQL while in planning mode).
|
- No shell commands or system setup steps.
|
||||||
|
- No scaffolding diffs or auto-generated file dumps.
|
||||||
6) Coding standards & security (what to enforce when code is requested)
|
|
||||||
|
---
|
||||||
Repository-first: Before proposing file names, endpoints, or structures, search Panel-unstable to reuse existing helpers, patterns, and locations.
|
|
||||||
|
**End of Copilot Instructions (No-Code).**
|
||||||
Strictness: Prefer strict comparisons; parameterized DB access; centralized input validation and output escaping.
|
|
||||||
|
|
||||||
Session & CSRF: Harden website sessions and require CSRF tokens on state-changing requests.
|
|
||||||
|
|
||||||
Webhooks: Verify signatures and event types server-side; never trust client redirects for payment state.
|
|
||||||
|
|
||||||
XML: Harden parsing (no external entities; size/complexity limits). Treat XML as untrusted input even though it’s in-repo.
|
|
||||||
|
|
||||||
Observability: Define success/failure metrics, audit logs for state changes, and trace IDs for provisioning flows.
|
|
||||||
|
|
||||||
Licensing: Preserve upstream notices and ensure our additions stay license-compatible.
|
|
||||||
|
|
||||||
7) Validation checklist (pre-PR / pre-merge)
|
|
||||||
|
|
||||||
Read _website/, modules/config_games/server_configs/, modules/, includes/, paypal/ (if present), and ogp_api.php to anchor proposals to actual code.
|
|
||||||
|
|
||||||
Catalog uses only the XML metadata; no hardcoded ports/params.
|
|
||||||
|
|
||||||
Regions/nodes are read live from the panel DB; no duplicates on the website.
|
|
||||||
|
|
||||||
Auth plan preserves panel compatibility and modernizes website hashing; sessions remain separate.
|
|
||||||
|
|
||||||
Checkout mirrors _website/; uses REST Webhooks; paid state changes occur only after verification.
|
|
||||||
|
|
||||||
Provisioning calls panel internals (e.g., ogp_api.php), respects selected/auto node, and records mappings consistently.
|
|
||||||
|
|
||||||
Legacy billing module pages are not extended; its schema is reused for multi-remote.
|
|
||||||
|
|
||||||
Security items from §6 are addressed in the plan: CSRF, webhook verification, strict comparisons, hardened XML.
|
|
||||||
|
|
||||||
8) Deliverables for Copilot (when planning)
|
|
||||||
|
|
||||||
A concise change plan that lists:
|
|
||||||
|
|
||||||
Files to create/modify/remove and their locations,
|
|
||||||
|
|
||||||
Data sources and mappings to existing tables/fields,
|
|
||||||
|
|
||||||
UX notes (e.g., region selector vs auto-placement),
|
|
||||||
|
|
||||||
Risks, rollback approach, and test coverage,
|
|
||||||
|
|
||||||
Acceptance criteria aligned to these instructions.
|
|
||||||
|
|
||||||
Update CHANGELOG.md with a brief, high-signal entry (date, scope, rationale).
|
|
||||||
|
|
||||||
Append a single line item to docs/COPILOT_TODO.md for any UI follow-ups or next steps.
|
|
||||||
|
|
||||||
9) Prohibited while in planning
|
|
||||||
|
|
||||||
No PHP/SQL/XML.
|
|
||||||
|
|
||||||
No shell commands or system setup steps.
|
|
||||||
|
|
||||||
No scaffolding diffs or auto-generated file dumps.
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue