TNCSC_Odoo/HANDOFF.md

Handoff / Resume Notes

Read this first if you're picking this project back up — whether that's Claude Code in a future session or a human developer. The phase-by-phase build plan is in CommunityOS_Implementation_Plan_for_Claude_Code.md; this file is the "where things actually stand" companion to it.

Status at a glance

Phase	What it is	Status
0	Repo scaffold, Docker dev stack, CI + brand-leak guardrails	✅ Done, committed
1	community_membership	✅ Done, committed
2	event_qr_ticketing	✅ Done, committed
3	community_school	✅ Done, committed
4	community_classifieds + community_benefits	✅ Done, committed
5	community_interac (Interac e-Transfer payment provider)	✅ Done, committed
6	community_theme_base + community_portal	✅ Done, committed
7	tncsc_deployment (client config layer)	✅ Done, committed. Website pages content migrated from live tncsc.com in a later session — see "TNCSC website migration" below
8	TNCSC data migration scripts	✅ Done, committed (9a24691)
9	Packaging for resale + production go-live	🟡 9-A in progress (see below); 9-B not started

Every phase 0–7 commit was verified against a live Odoo 19 + Postgres 16 container before being committed — not just written and assumed to work. Run git log --oneline for the full commit list; each commit message documents what was built and how it was verified, including several real Odoo 19 API changes that don't match older docs/tutorials (see "Gotchas" below for the index).

Git remote is configured: origin -> https://git.metatroncube.in/admin/TNCSC_Odoo.git.

Resuming the dev environment

cd deploy
docker compose up -d

• Odoo: http://localhost:8069, database communityos_dev, login admin / password admin.
• This dev database has been used for all testing across every phase — it has real posted accounting entries in it (from Interac transaction confirmations, membership invoices, etc.). That's why Phase 7's tncsc_deployment module can't be installed on it directly (Odoo correctly refuses to change a company's currency once journal entries exist) — it was instead verified on throwaway fresh databases (tncsc_freshN, all dropped after verification). A real TNCSC production database should be a genuinely fresh install, not this dev one.
• tncsc_site is another fresh DB (with tncsc_deployment installed), used for the website content migration below — kept around this time (not dropped) since it's the one with the real seeded event/tiers to look at. Since multiple DBs coexist, a plain http://localhost:8069/ won't know which to serve — select one explicitly first, e.g. http://localhost:8069/web?db=tncsc_site, then it's remembered by cookie.
• After any module code change, the running deploy-odoo-1 container has a stale in-memory registry until you either upgrade the module (-u) and restart the container, or just restart it:

  docker compose restart odoo
  

  This bit repeatedly during development — don't skip it when testing.

Phase 8 — done, committed (9a24691)

All three migration scripts exist, are committed, and have been verified against a live Odoo instance (see "How each was tested" below).

• scripts/_migration_common.py — shared JSON-RPC helpers (auth, execute_kw, CSV normalization, a MigrationReport class) for the migration scripts.
• scripts/migrate_members.py — idempotent upsert by email, dry-run flag, tier lookup by code, report CSV.
• scripts/migrate_students.py — idempotent upsert of parent partner (by email, reusing a partner created by migrate_members.py if one exists)
  • child partner + community.school.student, matched by (parent, student name) since students don't have their own email in the source data. Enrolls into the matching class in the current open term (matched by community.school.level code) when one exists; otherwise still creates/updates the student record and reports why no enrollment happened.
• scripts/migrate_opening_balances.py — posts one account.move in the Miscellaneous Operations journal, dated the last fiscal year-end (computed from res.company.fiscalyear_last_day/month, or --date override). Refuses to post anything if the CSV doesn't balance (sum(debit) != sum(credit)) or references an unknown account code — checked before any Odoo write happens. Idempotent via a fixed ref ("Opening Balances Import"): re-running finds the existing posted entry and does nothing.

How each was tested

Followed the same pattern as scripts/migrate_classroom.py (Phase 3): dry-run first, then a real run, then a second real run to prove idempotency — against a fresh database, not communityos_dev. See "Why a fresh DB, not communityos_dev" below for why.

1. docker compose up -d, then created a throwaway DB with both product modules and the client layer: odoo -d tncsc_migration_test -i community_membership,tncsc_deployment --stop-after-init (installing tncsc_deployment alone pulls in community_school and everything else as dependencies). Restarted the container afterward.
2. migrate_members.py: synthetic CSV at data/raw/members_export_sample.csv (gitignored, left in place as a fixture) with 4 valid rows + 2 deliberately-bad rows (missing email, unknown tier code). Dry-run matched real-run output; second real run reported updated not created for all 4; confirmed via RPC that exactly one res.partner per email existed after both runs and membership_state was active.
3. migrate_students.py: needed a community.school.term (state=open), community.school.level (code=BEG), and community.school.class seeded first (the fresh DB has none) — also had to grant the admin user the School Coordinator group, since a fresh install doesn't put admin in it. Synthetic CSV at data/raw/students_export_sample.csv with 3 valid rows (2 matching the open term's class, 1 with no level_code) + 1 deliberately-bad row (missing parent). Confirmed via RPC after 2 runs: exactly 3 community.school.student records, exactly 2 community.school.enrollment records (no duplicates), parent partners correctly reused from step 2 instead of duplicated.
4. migrate_opening_balances.py: synthetic CSV at data/raw/opening_balances_sample.csv using real account codes from the fresh DB's TNCSC chart of accounts (111100 Cash, 112110 Trade AR, 322000 Retained Earnings as the balancing line). Verified the out-of-balance guard refuses to post (tested with a deliberately mismatched debit/credit CSV). Real run posted one balanced, posted account.move; second run detected the existing entry and did nothing. Confirmed via RPC: exactly one move, three correctly-valued lines, AR line correctly linked to the migrated Ravi Kumar partner.

Real TNCSC member/student/trial-balance data doesn't exist yet — all three scripts were intentionally designed against a documented, assumed CSV schema (see each script's docstring) since the real export formats aren't known yet. Confirm the assumed column names match the real exports before relying on them, or adjust the scripts to match.

Why a fresh DB, not communityos_dev

communityos_dev doesn't have tncsc_deployment installed (see the top of this file — it can't be, since it already has posted journal entries and Odoo refuses to change a company's currency once those exist). Testing the Phase 8 scripts there would exercise generic community_membership/ community_school behavior, not the actual TNCSC-configured target (TNCSC's real chart of accounts, company currency, groups). Since Phase 8's entire purpose is rehearsing the real TNCSC data load, a fresh DB with tncsc_deployment installed is the more representative target — and it avoids adding more synthetic test data to the one long-lived dev DB used across every other phase. tncsc_migration_test was not dropped after this session (unlike the Phase 7 tncsc_freshN throwaways) — it's left in place in case the next session wants to keep testing against it; drop it before it's mistaken for anything resembling real data.

To pick this back up

Either wait for real TNCSC export samples to validate the assumed CSV schemas against, or move on to Phase 9.

Phase 9 — 9-A in progress, 9-B not started

Two sub-parts with very different risk profiles:

• 9-A (productize): safe to do autonomously. Done so far — every community_* module has static/description/index.html, a real README.rst (Usage sections filled in past the Phase-0 placeholder), and a CHANGELOG.rst; manifests pass scripts/check_manifests.py. Still open:
  • Every product manifest's images key points at static/description/banner.png, but no module actually has that file — the Apps-list/App-Store banner image doesn't exist yet. Needs a real designed asset per module, not a placeholder.
  • No v1.0.0 git tag yet, and no release report — holding off on both until the banner-image gap above is resolved. (A later session did run --test-enable for tncsc_deployment specifically against live Odoo while doing the website migration below — 9/9 passing — but that wasn't a full suite-wide run across every community_* module.)
  • No role guides (admin/treasurer/teacher/parent) written yet.
• 9-B (go-live): not started. deploy/odoo.conf is still dev config (list_db = True, proxy_mode = False, no workers) and deploy/nginx-communityos.conf is an explicit "development skeleton" — SSL, DNS cutover, firewall rules, and backups on a real production server all remain. This needs a human in the loop with actual server access/credentials — don't let an agent run this unattended.

TNCSC website migration (from live tncsc.com, WordPress -> Odoo)

addons/tncsc_deployment/views/website_pages.xml was rewritten from the Phase 7 placeholder pages ("content to be finalized") into the real site content, adapted from tncsc.com (captured 2026-08-20). Tested against a dedicated fresh database, tncsc_site (not communityos_dev or tncsc_migration_test) — docker compose exec odoo odoo -d tncsc_site -i tncsc_deployment --stop-after-init recreates it from scratch.

• Real pages built: Home, About, About/Tamil Nadu (bilingual EN/Tamil), About/Board of Directors (12 real named members + photos), Membership hub, Membership Benefits (real 8-point benefit copy), Tamil Class, Contact, plus the pre-existing Sponsors placeholder. Nav restructured to match tncsc.com's real structure (Home / About dropdown / Events / Membership dropdown / Tamil Class / Contact) instead of the old flat Classifieds/Benefits/Sponsors list.
• Real assets pulled from tncsc.com and committed under addons/tncsc_deployment/static/src/img/ (~1.1MB: logo, board photos, section imagery) rather than hotlinking the WordPress site.
• Events, Membership, and Tamil Class are wired to the real product modules (event.event for the homepage's "Upcoming Events", live community.membership.tier records for pricing, /school/register for Tamil Class signup) instead of being static copies — see each page's QWeb for the exact query.
• One real event was seeded (data/events_data.xml): TNCSC's Summer Picnic 2026, matching what's live on tncsc.com/events.
• Deliberately not reproduced, because it isn't real: tncsc.com's own Sponsors page (generic client-01..09 stock logos, dead links) and its Contact page phone number (+7 (800) 123 45 69, a non-Canadian WordPress theme demo placeholder) are themselves unmigrated theme demo content on the live site, not real TNCSC data — confirmed by inspecting alt text/hrefs, not assumed. Contact page ships with the real, verified email (support@tncsc.ca) and social links (Facebook/YouTube/Instagram) instead.
• Real gap, not paved over: community_membership has no public self-service "join online" flow (portal only handles renewal for partners a staff member already created) — every "Become a Member" CTA points at /contact rather than a fake/broken signup link. Building that flow is follow-on work, not done here.
• Known cosmetic leftover: Odoo's own stock header/footer snippets ship a placeholder phone number (+1 555-555-5556) baked into core website module views (website.header_text_element, website.footer_custom, website.s_contact_info), independent of anything in this module. It's normal, editable-in-the-website-builder content on any fresh Odoo site, not something this module introduced — left for whoever does the go-live content pass to delete via the Website editor (Edit -> click the text -> delete), rather than patched with a defensive XML override here.
• Text throughout was reconstructed via automated extraction from the live pages, not copy-pasted from raw HTML — treat it as a faithful draft. Have TNCSC proofread the migrated copy against the original site before go-live.

Gotchas discovered this build (Odoo 19 API drift + environment quirks)

This Odoo 19 build (19.0-20260817, essentially a nightly) diverges from older tutorials/docs in several places that cost real debugging time. Each is documented in detail in the commit message where it was found — this is just the index so you know to search git log for it instead of re-discovering it:

• res.groups.category_id → replaced by privilege_id → res.groups.privilege.category_id (Session 1-A commit).
• Settings pages use a new <app>/<block>/<setting> structure inherited from base.res_config_settings_view_form, not the old raw-div layout (Session 1-A commit).
• ir.cron dropped numbercall entirely (Session 1-B commit).
• event.event has no state field anymore (replaced by a stage_id/event.stage kanban system) (Phase 2 commit).
• Route type='json' should be type='jsonrpc' ('json' still works but is deprecated) (Phase 2 commit).
• Search-view <group> elements for "Group By" sections no longer accept a string attribute, only name (Phase 3 / Phase 4 commits).
• res.groups.users → renamed to user_ids (Phase 4 commit).
• res.config.settings fields backed by config_parameter= only support boolean/integer/float/char/selection/many2one/datetime — not Binary. Using it on a Binary field breaks every Settings tab, not just the one you're adding, since they share one model (fix: commit after Phase 6).
• Anonymous visitors hitting an auth='user' + website=True route in this specific build crash with a raw 500 instead of a clean redirect to /web/login (Request._serve_db's finally: self.env = None runs before the website error handler tries to build the redirect). Worked around by switching those routes to auth='public' with a manual if request.env.user._is_public(): return request.redirect(...) check (fix: commit after Phase 6 — this is the fix to reach for if you add new member-only pages later, don't reintroduce auth='user' on a website=True route without it).
• Setting res.company.country_id on a brand-new company auto-schedules this build's own chart-template installer via a precommit hook, which races an explicit try_loading() call made in the same install transaction and silently reverts it afterwards. ir.cron code execution is also sandboxed and forbids direct attribute assignment (STORE_ATTR) — use .write(...). Both fully explained in the Phase 7 commit message, fix pattern is in addons/tncsc_deployment/models/res_company.py.
• Not version drift, but a real trap worth indexing here since it cost significant debugging time during the website migration: the website module auto-forks its own website-bound ("Copy-On-Write") copy of both the homepage (website.homepage) and the top nav tree (website.menu_id) the first time a website exists. A generic (website_id-unset) page or menu record renders fine at ordinary URLs, but is silently ignored for the homepage route and the rendered nav specifically — those two routes only resolve records explicitly bound to the current website_id, and on a same-URL tie the auto-forked stock copy wins over a same-priority custom one by insertion order. Confirmed empirically against a live container (not from docs). Fix pattern — explicitly bind website_id, and where a stock auto-forked duplicate exists, remove it — is in addons/tncsc_deployment/__init__.py (_remove_stock_homepage_page, _fix_website_menus), both run from post_init_hook. Relevant if you add more top-level pages/menu items later.
• Each product module's backend app (Membership, School, Benefits, Classifieds, Interac Payments) has its root ir.ui.menu restricted to its own manager/coordinator group, and a fresh tncsc_deployment install doesn't put the admin user in any of them by default. Result: admin's backend app switcher only shows stock apps (Events, eLearning, Settings, ...) and none of the CommunityOS ones, which looks exactly like "the modules aren't installed" even though ir.module.module.state is installed for all of them — confirmed by checking env['ir.ui.menu'].with_user(admin).search([('parent_id', '=', False)]), which is the right way to check what a user actually sees (menu visibility is group-based, not just install state). Fixed by adding admin to tncsc_deployment.group_tncsc_board_admin in security/tncsc_roles.xml (that group's implied_ids already covers every product manager group) — this used to be the manual per-group step described above for Phase 8's School Coordinator grant; it's now automatic on any fresh install. Note res.groups.implied_ids doesn't populate the implied group's own user_ids — checking membership via user in group.user_ids will wrongly say "no" for an implied group; use user.has_group('module.xml_id') instead, which does resolve the transitive closure correctly.

Handing off to a team

1. Repo is already pushed to origin (see above) — confirm the team has access to git.metatroncube.in.
2. Point them at CommunityOS_Implementation_Plan_for_Claude_Code.md (the plan) and this file (current status).
3. They'll need Docker Desktop (or equivalent) to run deploy/docker-compose.yml locally — no other local dependencies.
4. If they're using Claude Code to continue: just point it at this repo and this file. It doesn't need conversation history — everything load-bearing is either in a commit message or in this document.