diff --git a/docs/TNCSC_Handbook.md b/docs/TNCSC_Handbook.md new file mode 100644 index 0000000..af946e9 --- /dev/null +++ b/docs/TNCSC_Handbook.md @@ -0,0 +1,359 @@ +# TNCSC CommunityOS Handbook + +A plain-language guide for TNCSC board members and volunteers to configure +settings and run the system day-to-day — no developer required for any of +this. If something isn't covered here, or doesn't work the way this guide +describes, that's a question for your technical support contact, not +something to guess at. + +**Where to log in:** your production site's `/web/login` page (ask your +technical contact for the exact address if you don't have it). Use the +account and password you were given. + +--- + +## Contents + +1. [Understanding the system](#1-understanding-the-system) +2. [User roles — who can do what](#2-user-roles--who-can-do-what) +3. [Branding: colours, logo, fonts](#3-branding-colours-logo-fonts) +4. [Membership](#4-membership) +5. [Events](#5-events) +6. [Tamil Class (School)](#6-tamil-class-school) +7. [Classifieds](#7-classifieds) +8. [Benefits](#8-benefits) +9. [Interac e-Transfer Payments](#9-interac-e-transfer-payments) +10. [Website content](#10-website-content) +11. [Accounting basics](#11-accounting-basics) +12. [Troubleshooting & getting help](#12-troubleshooting--getting-help) + +--- + +## 1. Understanding the system + +Once you log in, you'll see an **app switcher** — a grid of icons, one per +area of the system: + +| App | What it's for | +|---|---| +| **Membership** | Members, tiers/pricing, renewals | +| **Events** | Creating events, ticketing, check-in | +| **School** | Tamil Class terms, classes, students, attendance | +| **Classifieds** | The member classifieds board and its moderation queue | +| **Benefits** | Benefit centres (partner businesses) and member benefits | +| **Interac Payments** | Confirming e-Transfer payments | +| **Website** | The public website — pages, menus, content | +| **Settings** | Branding, org-wide configuration, user accounts | + +**If an app is missing from your switcher**, it's almost always a +permissions issue, not a broken install — see +[section 2](#2-user-roles--who-can-do-what) and +[troubleshooting](#12-troubleshooting--getting-help). + +Two databases exist during development/testing (`tncsc_migration_test`, +`tncsc_site`) — your technical contact will tell you which one is live +production once you go live. Everything in this guide applies the same way +regardless of which database you're in. + +--- + +## 2. User roles — who can do what + +Go to **Settings → Users & Companies → Users**, click a person's name, and +under their groups you'll find **TNCSC Roles**. Check the box for the role +that matches what they do: + +| Role | What it grants | +|---|---| +| **Board Admin** | Everything — membership, school, classifieds, benefits, events, and Interac payments. Give this only to whoever runs the system day-to-day. | +| **Treasurer** | Confirms Interac payments and has invoicing access. | +| **Events Officer** | Creates/manages events and staffs check-in. | +| **School Coordinator** | Manages Tamil Class terms, classes, students, enrollment. | +| **Teacher** | Can only take attendance for their own classes. | +| **Classifieds Moderator** | Reviews and publishes classified listings. | + +A person can hold more than one role — e.g. someone can be both **School +Coordinator** and **Teacher**. Members themselves don't need a role +checked here at all: once someone is a member, they get their own +self-service **member portal** automatically (see +[section 4](#4-membership)) — that's separate from these backend roles, +and doesn't require a staff login. + +**Adding a new staff/volunteer account:** Settings → Users & Companies → +Users → **New**, fill in their name and email, save, then check the +role(s) above. They'll get an email to set their own password. + +--- + +## 3. Branding: colours, logo, fonts + +**Settings → General Settings → Theme** (left-hand tab list). + +- **Primary / Secondary / Accent Colour** — enter a colour as a hex code + (e.g. `#05091E`). These apply instantly across the website, the member + portal, and PDF documents like the membership card — no other setting + to touch. +- **Logo** — upload the image file to use in the site header and on + generated PDFs. If left blank, the company logo (Settings → General + Settings → Companies) is used instead. +- **Heading Font / Body Font** — enter a font name, e.g. `Inter, + sans-serif`. Needs to be a font available to browsers (a "web-safe" + font, or one already loaded via Google Fonts) — ask your technical + contact before entering something unusual. + +Click **Save** at the top of the page after any change. + +--- + +## 4. Membership + +### 4.1 Settings + +**Settings → General Settings → Membership**: + +- **Organization Name** — used in renewal emails and the membership card. +- **Member ID Format** — the pattern new member IDs follow, e.g. + `TNCSC-{year}-{seq}` produces `TNCSC-2026-014`. Don't change the + `{year}`/`{seq}` placeholders unless your technical contact confirms + the change is safe — they drive the auto-numbering. +- **Renewal Reminder Offsets** — comma-separated days-before-expiry to + send reminder emails, e.g. `30,14,7` sends reminders 30, 14, and 7 days + before a membership expires. +- **Member Portal** — toggle to turn the self-service portal (`/my/membership`) + on or off site-wide. + +### 4.2 Membership tiers and pricing + +**Membership → Configuration → Membership Tiers.** + +Each row is a plan (Individual, Family, Student, Senior, Life, or +whatever TNCSC offers). To **change a price**, open the tier and edit +**Price** — this is the only place pricing lives; there's no separate +price to update anywhere else. To **add a new tier**, click New and fill +in: + +- **Name** — shown to members, e.g. "Corporate Sponsor" +- **Code** — a short internal code, e.g. `CORP` (no spaces) +- **Price** and **Currency** +- **Period** — Annual, One-Time, or Monthly +- **Sequence** — controls display order (lower numbers show first) + +Deactivating a tier (rather than deleting it) keeps historical records +intact for members who already hold it — use the **Active** toggle, +found via the tier's kebab (⋮) menu → "Archive", instead of deleting. + +### 4.3 Day-to-day membership work + +- **Membership → Members** — the full member list. Open a member to see + their tier, status (active/renewal due/expired), and expiry date. +- Renewal reminders and draft renewal invoices are generated + **automatically** by a daily background job — you don't need to run + anything manually. What you *do* need to do periodically: check + **Invoicing → Customer Invoices** for draft renewal invoices and + confirm/send them once payment is expected. +- Each member can view their status, download their QR membership card, + and renew from `/my/membership` once logged into the website — you + don't need to email cards out manually. +- The membership card's QR code links to a public verification page + (`/membership/verify/`) — anyone scanning it (e.g. at an + event door) sees only "valid" / "expired" / "not found," never personal + details. + +--- + +## 5. Events + +**Events → Events → New.** This is standard Odoo event creation: + +1. Name, start/end date and time, location. +2. Under **Website**, check **Is Published** to make it visible on the + public Events page and the homepage's "Upcoming Events" section — + *unpublished events won't appear anywhere on the public site,* even + though they exist in the system. +3. Add ticket types under the event's **Registration** tab if you're + charging for entry (e.g. "General $0–$30"). + +Every registration automatically gets a signed QR ticket, emailed with +the confirmation. At the door, staff with the **Events Officer** role use +**Events → Registration Desk** to scan tickets (or type the ticket +reference manually) — it shows valid / already checked-in / invalid, and +a live count of registered vs. checked-in. + +**Events → Reporting → Attendees / Revenues** gives you numbers after the +fact without any setup. + +--- + +## 6. Tamil Class (School) + +### 6.1 Settings + +**Settings → General Settings → School**: **At-Risk Attendance +Threshold** — the attendance percentage below which a student is flagged +"at-risk" in the report (see below). + +### 6.2 Configuration — set these up before each school year + +**School → Configuration → Terms** — create a term (e.g. "2026-27"), +set start/end dates, and open it (**State = Open**) once registration +should begin. Only one term should normally be open at a time. + +**School → Configuration → Levels** — define your levels however TNCSC +teaches (e.g. "Beginner" through "Advanced", or "Grade 1" through "Grade +12"). Each needs a short **Code** (e.g. `BEG`) and optional min/max age. + +**Classes** aren't under Configuration — create them directly from +**School → Classes → New**: pick the term, level, teacher, weekday, +time, location, and max students. This is what shows up as an option +when a parent registers online. + +### 6.3 Day-to-day + +- **School → Students / Enrollments** — see who's enrolled where. +- **School → Attendance Report** — a pivot table of attendance by class. +- **School → At-Risk Students** — students below the configured + attendance threshold, so you can follow up. +- Teachers take attendance themselves from their own portal page + (`/school/attendance`) — a roster of today's/this-week's classes with a + batch Present/Absent/Late/Excused save. An absence automatically emails + the parent. Teachers only see their own classes there. +- Parents register their child at `/school/register` on the public + website (parent → student → class + payment, in three steps). If a + class is full, the student is waitlisted and notified automatically + when a seat frees up — no manual waitlist management needed. +- Each class auto-creates and manages its own online course/materials + channel — enrolling or withdrawing a student automatically + enrols/unenrols them there too. + +--- + +## 7. Classifieds + +**Settings → General Settings → Classifieds**: **Listing Duration** — how +many days a published listing stays live before auto-expiring. + +**Classifieds → Moderation** is where every new submission lands first +(state: Pending Review). Open one to **Publish** or **Reject** it — only +published listings appear on the public `/classifieds` board. Posting +requires the member to be logged in with an active membership, so this +queue should only ever contain genuine member submissions. + +--- + +## 8. Benefits + +Two things to set up, then one thing to log ongoing: + +- **Benefits → Benefit Centres** — the businesses/organizations offering + a member benefit. Add their name, category, description, and logo. +- **Benefits → Benefits** — the actual discount/perk, linked to one or + more **Membership Tiers** (only members holding one of those tiers will + see it). Set the discount type (percent / fixed amount / perk) and + validity dates. +- **Benefits → Redemptions** — a log a benefit centre (or staff) creates + when a member actually uses a benefit, after confirming the member is + active. This is mostly for your own record-keeping of usage, not + something you need to set up in advance. + +Members see only what their own tier qualifies them for at +`/my/benefits`; the public directory of participating centres is at +`/benefits`. + +--- + +## 9. Interac e-Transfer Payments + +### 9.1 One-time setup + +**Invoicing → Configuration → Online Payments → Payment Providers** → +open **Interac e-Transfer**: + +- **Interac Recipient Email** — the real e-transfer address payments + should be sent to. +- **Interac Deadline Hours** — how long an unconfirmed payment stays + pending before it's automatically cancelled (defaults to 48 hours if + left blank). +- Set the provider's **State** to **Enabled** so it appears as a + checkout option. + +### 9.2 Day-to-day (Treasurer role) + +When someone chooses Interac at checkout, they're emailed instructions +(recipient address, amount, a reference code, and the deadline) — this +happens automatically, nothing for you to send. + +Once you actually receive the e-transfer in your real bank/e-transfer +account, go to **Interac Payments → Pending Payments**, find the matching +transaction (match by amount and reference code), and click **Payment +Received**. This confirms the linked invoice/registration/order. If +nobody confirms it before the deadline, it auto-cancels and the payer is +notified by email. + +--- + +## 10. Website content + +**Website** app, then click **Edit** on any page while viewing it on the +public site to change text, images, and layout directly (drag-and-drop +editor) — no code involved for routine copy changes. **Site → Menu +Editor** lets you add, remove, or reorder navigation items. + +Two things worth knowing about the current site before you edit it: + +- The **Sponsors** page and a few header/footer text blocks (e.g. a + placeholder phone number) still contain placeholder content carried + over from the original site design — safe to edit or delete through + the Website editor whenever real sponsor logos or a real phone number + are ready. +- **"Become a Member" buttons currently point to the Contact page**, not + a self-service signup form — TNCSC doesn't have public online + membership signup yet (only renewal, for existing members). Don't + redirect these to a form that doesn't exist; talk to your technical + contact if/when online signup becomes a priority. + +For anything beyond content edits — new page types, new sections with +custom behaviour, structural changes — that's a developer task, not a +Website-editor task. + +--- + +## 11. Accounting basics + +The chart of accounts, tax setup, and journals were seeded for a Canadian +non-profit when the system was set up, including dedicated revenue +accounts (Membership Dues, Event Revenue, Sponsorship, School Fees, +Donations) and a **Donations** journal. You generally don't need to +create new accounts for normal operations — membership tiers, event +tickets, and school fees are already wired to the right ones. + +**Do not** rename or delete existing accounts, or change the company's +currency/country, without your accountant and technical contact both +signing off — several of these are load-bearing for other parts of the +system (e.g. renaming the dues account could silently break where +membership payments post to). Day-to-day invoicing/payment work happens +under the **Invoicing** app as normal. + +--- + +## 12. Troubleshooting & getting help + +| Symptom | Likely cause / fix | +|---|---| +| An app I should have access to isn't in my switcher | You're missing the matching role — see [section 2](#2-user-roles--who-can-do-what). Ask a Board Admin to check the box for you. | +| I changed a setting and nothing changed on the site | Make sure you clicked **Save**. If it still looks wrong after a minute, it may need a technical restart — contact support rather than repeating the change. | +| A member says their QR card doesn't work | Check their membership **state** on their member record — the verify page only shows "valid" for members currently in the *active* state. | +| An event isn't showing on the website | Confirm **Is Published** is checked on the event (see [section 5](#5-events)) — unpublished events are invisible on the public site by design. | +| A parent can't register for a class | Check the term is **Open** and the class isn't already full (School → Classes) — full classes waitlist automatically rather than blocking registration outright. | +| An Interac payment doesn't confirm | Double-check the reference code and amount match exactly before clicking Payment Received — mismatches usually mean it's a different transaction. | + +For anything not covered here — a genuine error message, something that +looks broken rather than misconfigured, or a request for new +functionality — contact your technical support contact rather than +experimenting on the live site. Screenshots and the exact steps you took +help them fix it faster. + +--- + +*This handbook covers the CommunityOS suite as configured for TNCSC. It +does not cover server maintenance, backups, or deployment — those remain +your technical contact's responsibility.*