smart-project/.github/copilot-instructions.md

Smart Project repository instructions

Commands

• There is currently no repo-defined build, test, or lint command. The repository has no package.json, Makefile, or CI workflow, so there is also no defined single-test command yet.

High-level architecture

• Treat this repository as two layers:
  • Design source of truth in SPEC.md and docs/, which describes the intended production system.
  • Current implementation in h5/, which is a framework-free H5 prototype built from static HTML/CSS/JS files.
• The intended production system in the docs is:
  • Backend API: Node.js / Express + TypeScript
  • Database: MySQL 8.0
  • Storage: Aliyun OSS for uploaded images and files
  • Device ingestion: Henan Sannong devices push data into /input/post/call
  • Client: mobile H5 pages under the same domain as the API
• The most important cross-cutting backend rule from the docs is project-level tenant isolation: business tables carry project_id, JWT resolves the current user's project_id, and middleware must inject that filter into every query.
• The h5/ prototype mirrors the planned product modules from the docs: dashboard, devices, alerts, hazards/reports, construction logs, AI analyses, and profile pages. Page routes are file-based (devices.html, device.html?id=..., report.html, reports.html, etc.).

Key conventions

• Use the docs to resolve product behavior. When implementation details in h5/ are incomplete or inconsistent, prefer SPEC.md, docs/architecture.md, docs/api.md, docs/database.md, docs/h5.md, and docs/offline.md as the canonical intent.
• Assume the current codebase is a prototype, not a finished full-stack app. The backend described in the docs does not exist in this repository yet.
• Preserve the static-page architecture in h5/. Each feature is a standalone HTML file with page-specific inline script at the bottom and shared browser-global helpers from js/mock.js, js/api.js, and js/app.js.
• Do not introduce module tooling assumptions when editing h5/. The prototype uses browser globals, not imports/exports or a bundler.
• Shared state and helpers are global. mock.js exposes mock datasets and lookup helpers on window; api.js provides async wrapper functions like apiGetDevices() and apiGetAlerts(); app.js owns auth and UI helpers such as getToken(), setToken(), requireAuth(), showToast(), getQueryParam(), and initTabBar().
• Auth in the prototype is localStorage-based. Protected pages call requireAuth() and login stores a token in localStorage. Keep that flow consistent unless you are explicitly replacing the prototype auth model.
• API response shape in the prototype is uniform. Frontend code expects objects like { code: 0, data: ... }, and mutating operations update the in-memory mock arrays directly.
• Keep terminology aligned with the domain docs. Use the existing Chinese product language and status names where they already exist in the repo, especially for hazards, alerts, device types, and AI analysis modules.
• Keep tenant isolation visible in any future backend work. If you add server code later, carry project_id through schema, auth context, and every data query rather than treating it as an optional filter.
• Styling is token-driven and CDN-based. h5/css/variables.css defines theme variables; h5/css/style.css contains shared component styles; pages load WeUI and Remix Icon from CDNs. Reuse existing classes like tab-bar, tab-item, stat-card, alert-item, log-item, and related token variables before adding new patterns.
• Bottom navigation is a shared product convention. Main app pages use the same four-tab structure: home, devices, reports, and logs. Keep those links and active-state patterns consistent.
• Prototype pages often combine list/create/detail flows across separate files inconsistently. Check both the docs and the existing HTML before renaming or merging pages; for example, the docs describe report.html?id=... and log.html?id=..., while the prototype also includes report-detail.html and log-detail.html.