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 |
| 8 | TNCSC data migration scripts | 🟡 Barely started, **not committed** — see below |
| 9 | Packaging for resale + production go-live | ⬜ 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).

**No git remote is configured.** This repo only exists on this machine
right now. Before handing off to a team, push it somewhere (GitHub/GitLab/
etc.) — see "Handing off to a team" below.

## Resuming the dev environment

```bash
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.
- **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:
  ```bash
  docker compose restart odoo
  ```
  This bit repeatedly during development — don't skip it when testing.

## Phase 8 — exactly where it was left off

Two files exist, committed as WIP (see the `wip:` commit), inert (not
imported by anything, not installed, no manifest references them):

- `scripts/_migration_common.py` — shared JSON-RPC helpers (auth, execute_kw,
  CSV normalization, a `MigrationReport` class) for the migration scripts.
  Finished, not yet tested against anything.
- `scripts/migrate_members.py` — first pass at the member migration script
  (idempotent upsert by email, dry-run flag, tier lookup by code, report
  CSV). Written but **not tested at all** — no live run against Odoo yet.

Still to do for Phase 8 (see the plan's Phase 8 section):
- `scripts/migrate_students.py` — not started.
- `scripts/migrate_opening_balances.py` — not started.
- Test all three against synthetic/sample CSV data on a live instance,
  the same way `scripts/migrate_classroom.py` was tested (see that file
  and Phase 3's commit for the pattern: dry-run first, then a real run,
  then a second real run to prove idempotency).
- Real TNCSC member/student data doesn't exist yet — these scripts were
  intentionally designed against a *documented, assumed* CSV schema (see
  each script's docstring) since the real export format isn't known yet.
  Confirm the assumed column names match the real export before relying on
  them, or adjust the scripts to match.

To pick this back up: either continue `migrate_members.py`'s testing and
write the other two scripts, or decide the assumed CSV schemas are wrong
and redesign first once real export samples exist.

## Phase 9 — not started

Two sub-parts with very different risk profiles:
- **9-A (productize)**: static description pages, READMEs, CHANGELOGs,
  release tagging for the product modules. Safe to do autonomously.
- **9-B (go-live)**: SSL, DNS cutover, firewall rules, backups on a **real
  production server**. This needs a human in the loop with actual server
  access/credentials — don't let an agent run this unattended.

## 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`.

## Handing off to a team

1. **Push this repo to a real remote** (GitHub/GitLab/etc.) — right now it
   only exists locally.
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.