Imported from boiawang0620/style_plan (AGENTS.md). Install upstream with npx skills add boiawang0620/style_plan. Copyright stays with the author.

AGENTS.md

Project Overview

This project is a family study check-in app for elementary school use.

• Child-facing app: /
• Parent admin: /admin
• Server-rendered database view: /data
• Runtime: Node.js
• Persistence: SQLite at /data/study_plan.sqlite

The app is designed for self-hosting on a Mac mini and daily use from iPhone or iPad.

Core Product Model

• Subjects are fixed: math, chinese, english, science, other
• Weekly plans are managed by parents
• Children check in per task item
• Reward values are configurable per subject
• Bonus reward tasks can be added temporarily
• Monthly backfill and revoke actions are handled in admin

Important Files

• /server.js Serves static files, API routes, and the /data SQLite truth page.

• /shared.js Shared browser-side state model, normalization, migration helpers, and server API sync.

• /child.js Child home page logic.

• /admin.js Parent admin logic, including weekly plans, rewards, and monthly backfill.

• /index.html Child-facing UI shell.

• /admin/index.html Admin UI shell.

• /styles.css Shared styling for child, admin, and data pages.

• /manifest.webmanifest, /pwa.js, /service-worker.js PWA-related files. The current setup avoids aggressive caching to prevent stale data issues.

• /.deploy.env.example Local deployment config template for Tencent Cloud deployment.

• /scripts/deploy.sh One-click deployment script. Uploads a new release, preserves shared SQLite, and reloads pm2.

• /scripts/bootstrap_remote.sh, /scripts/bootstrap_lighthouse.sh First-time Tencent Cloud server bootstrap scripts.

• /deploy/ecosystem.config.cjs pm2 runtime definition used by the deployment flow.

Data Source Rules

• SQLite is the single source of truth.
• Normal app usage should read and write through /api/state.
• localStorage exists only for legacy migration diagnostics and import support.
• /data is the most trustworthy inspection page because it is rendered directly by the server from SQLite.

UI Conventions

• Keep the child experience simple and action-oriented.
• Keep admin optimized for fast parent configuration.
• Prefer card-based layouts over dense form grids when presenting task lists.
• For monthly backfill UI, treat the entire task card as the toggle target instead of relying on native checkbox UI.

Development Notes

• Use ASCII by default.
• Keep the app dependency-light unless there is a strong reason to add packages.
• Be careful with caching changes. localhost and LAN IP origins behave differently in browsers.
• When debugging data mismatches, compare /admin or / against /data.
• When changing state shape, update both normalization logic in /shared.js and any rendering assumptions in /child.js and /admin.js.

Manual Verification Checklist

• Open /data and verify SQLite content looks correct.
• Open /admin and confirm weekly plan, rewards, and monthly backfill reflect /data.
• Open / and confirm child tasks and reward summary match the same server state.
• Verify both http://localhost:8000 and LAN IP access behave consistently.