Be

Shared Context (read before doing anything)

You own backend + database development for PetCare end-to-end. That includes:

• All Python code under backend/
• The hand-managed schema at database/db_schema.sql and seed data at database/staging_data.json
• DBA responsibilities: tables, columns, indexes, FK design, CHECK constraints, triggers, soft-delete (is_active), updated_at wiring
• Migrations: there is no ORM and no migration tool. Schema changes are made by editing db_schema.sql directly. When you change it you MUST also give the user the exact SQL to run manually against staging / prod.

You DO NOT own:

• Frontend code (frontend/) — out of scope for this skill
• Writing backend tests — this is delegated to /bte. You design what should be tested and hand off; /bte writes the tests.

Backend layering (router → service → db)

• backend/main.py — FastAPI app factory; registers routers, lifespan inits the asyncpg pool.
• backend/routers/<domain>_router.py — thin HTTP layer. Validation, auth deps, delegate to service.
• backend/services/<domain>_service.py — all business logic. Each service exposes a db property that lazily calls get_db().
• backend/models/<domain>.py — Pydantic schemas + table-name constants (e.g. user_table = "users").
• backend/core/db_manager.py — singleton DatabaseManager exposing get_db(), init_database(), close_database().
• backend/core/postgres_database.py — asyncpg Pool wrapper. Small surface (~6 methods: read_one, read, insert_one, insert, execute, execute_returning).
• backend/core/environment.py — single source of truth for env detection. CORS, debug, storage path all branch off it.

When adding a new resource the canonical order is: model → service → router → register in main.py → schema entry in database/db_schema.sql → tell /bte what tests are needed.

HTTP verb convention (NON-NEGOTIABLE)

The backend uses only GET and POST. There is no PUT, DELETE, or PATCH in this codebase and there will not be one. Update / delete operations are POST with the verb in the URL path, e.g.:

• POST /pet/{pet_id}/update
• POST /pet/{pet_id}/delete
• POST /meal/{meal_id}/update
• POST /food/{food_id}/delete
• POST /weight/update/{weight_id}
• POST /group/{group_id}/update_role

The position of the verb relative to the id segment is not strictly consistent (some routers use /{id}/update, others /update/{id}). When adding new endpoints, match the nearest sibling endpoint in the same router. Do not invent a third layout.

If you are tempted to write @router.put, @router.delete, or @router.patch, stop — that is always wrong in this codebase. Rewrite as @router.post with the verb in the path.

Database conventions (you own these)

• id columns are short varchars (8-13 chars) generated in application code, not serial PKs. Reuse the existing id helpers in the relevant service; do not invent new ones.
• Every table has is_active (boolean, soft delete), created_at, and updated_at timestamps.
• Every table needs an update_updated_at_column() trigger wired up.
• Foreign keys are explicit. Choose ON DELETE policies that match the domain (cascade for child rows that cannot exist alone, restrict for shared parents).
• Group-based scoping: pet / food / meal / weight tables carry group_id, never just user_id. Authorization always goes through group membership.
• Indexes: add for FK columns and for any column referenced in a WHERE clause by services.
• When you change db_schema.sql, you MUST also tell the user the exact SQL to run against staging / prod, since there is no migration tool. Format it as a copy-pasteable code block per environment.

Authorization model

• Two auth mechanisms: API key (api_keys table, Authorization: Bearer {api_key}:{api_secret}) and JWT (access_tokens table, Authorization: Bearer {jwt}).
• Group roles: creator, member, viewer. Any service method that touches pet / food / meal / weight MUST check group membership and role. See backend/services/group_service.py for canonical patterns.
• Authorization gaps are bugs, not feature requests — call them out explicitly even if the issue did not mention them.

Response envelope

All endpoints return {"status": 1, "data": {...}, "message": "..."}. Errors raise HTTPException with structured detail. Do not invent a new envelope.

Pydantic response model consistency (NON-NEGOTIABLE)

Pydantic v2 defaults to extra="ignore" on BaseModel, which means any kwarg passed to a model constructor that is not a declared field is silently dropped — no warning, no error. This has already bitten the project: PetDetails was being constructed in pet_service.create_pet with user_permission="owner", but PetDetails never declared user_permission, so the field disappeared and the POST /pet response was inconsistent with GET /pet/{id} (which returns PetInfo, where the field IS declared).

Whenever you touch a response model or its constructor call:

1. Every kwarg the service passes to a response model constructor MUST be a declared field on that model. Read the model file (backend/models/<domain>.py) and the call site (backend/services/<domain>_service.py) side-by-side to confirm.
2. If you add a new computed / derived value to a service's return path (user_permission, calories_per_unit, user_role_in_group, etc.), declare the corresponding field on the response model first, then update the constructor call.
3. Cross-check sibling response shapes for the same domain — e.g. PetInfo (list) vs PetDetails (detail) — and keep context fields aligned where it makes sense. Drift between the two shapes confuses the frontend, which often expects the same field name in both responses.
4. If a field is genuinely optional in some responses, declare it as Optional[T] = None rather than relying on extra="ignore" to hide its absence.

This is a self-review item in Step 6 below — do not skip it.

Code quality gate

Before declaring an issue "done":

• cd backend && pre-commit run --all-files must pass (black + isort + flake8 + basic checks).
• No print statements; use the existing logger if logging is needed.
• New service methods have type hints. Add docstrings only where the logic is non-obvious.
• No new dependencies without explicit user confirmation.
• Diffs stay minimal — do not refactor unrelated code, do not "improve" things that were not asked for.

Files to know

• backend/main.py, backend/routers/, backend/services/, backend/models/, backend/core/
• database/db_schema.sql — source of truth for the schema
• backend/.env — local secrets (do not read or echo values)
• .github/workflows/ci.yml — CI shape

Subcommand: issue numbers (default)

Invoked as /be 12 or /be 12,15,18.

Run the following steps in order, synchronously, all in the user's main checkout per CLAUDE.md > Dev Flow. There is no background worktree, no Agent tool dispatch — every step is visible to the user as it happens.

When more than one issue number is given, treat them as a related batch and produce one combined plan + one combined implementation pass — unless the issues turn out to be clearly unrelated, in which case stop at Step 2 and ask the user whether to handle them separately.

Step 1 — Read the issue content

For each issue number, run:

gh issue view <number> --json number,title,body,labels,state,comments

Read the full content including comments. If gh fails (auth, not-found, network), stop and report the error to the user verbatim; do not guess at the issue content.

For each issue, summarise in Traditional Chinese:

• Issue #N — <title>
• 需求 / Bug 描述
• 驗收條件（明示或推測；推測的條目要標 推測）
• 受影響的 domain（auth / user / group / pet / food / meal / weight / schema）

Step 2 — Implementation plan

Produce a structured plan in Traditional Chinese:

1. 影響範圍 — every file you expect to touch, grouped by layer (model / service / router / schema / main.py / other). Include file:line refs when modifying existing code.
2. 資料庫變更 — if db_schema.sql needs editing, show the exact CREATE TABLE / ALTER TABLE / CREATE INDEX / trigger SQL inline. Flag whether the change is backwards-compatible or needs a manual migration step.
3. API 變更 — new / changed endpoints (remember: only GET and POST, verb-in-path for updates and deletes), request/response shape, status codes, auth requirement, group-role requirement.
4. Authorization 檢查 — for every new or modified service method, state which group-role check applies. If none, justify why explicitly.
5. 邊界與錯誤處理 — what 4xx errors are raised and when.
6. 不在這次範圍內的事 — explicitly list anything in the issue you are deferring, and why.

Step 3 — Confirmation gate

Pause and ask the user for confirmation before proceeding to Step 4 if any of the following are true:

• The plan touches db_schema.sql
• The plan adds or removes a Python dependency
• The plan changes the response envelope or auth flow
• The issues in the batch turn out to be unrelated
• You are uncertain about any acceptance criterion

Otherwise proceed to Step 4 immediately.

Step 4 — Pre-flight + worktree creation

Run the pre-flight checks from CLAUDE.md > Dev Flow in order, one tool call at a time. Pre-flight runs in the user's main checkout (read-only). Do NOT touch the main checkout's working tree.

git fetch origin master                                       # must succeed
git ls-remote --heads origin claude/issue-<N>-<slug>          # collision check (remote)
git branch --list claude/issue-<N>-<slug>                     # collision check (local)
git worktree list                                             # collision check (existing worktree)

Compute:

• Branch name: claude/issue-<N>-<slug> for a single issue, claude/issues-<N1>-<N2>-<slug> for a batch. Slug is a kebab-case 2–4 word summary of the issue title (e.g. add-meal-tags).
• Worktree path: ~/codebase-worktrees/PetCare-issue-<N>-<slug> (or PetCare-issues-<N1>-<N2>-<slug> for batch). Use the absolute path ($HOME/codebase-worktrees/... or the literal expansion).

Failure modes:

• git fetch fails → report verbatim and stop.
• Branch-name collision (local or remote) → append -2, -3, ... until unique.
• Worktree path already exists on disk OR git worktree list already contains this path → append -2, -3, ... until unique. Never delete an existing worktree on the user's behalf — it may contain in-progress work from another session.

Then create the worktree in a single command:

git worktree add <abs-worktree-path> -b <branch> origin/master

The chosen worktree path AND branch name must appear in your reply to the user before any code is written.

Critical: from this point onward, every Bash call is cd <abs-worktree-path> && <command> (or git -C <abs-worktree-path> ...). Every Read / Edit / Write uses an absolute path under <abs-worktree-path>. Never edit a file under the main checkout. The user's IDE checkout is not touched by anything past this step.

Step 5 — Implement

Write the code inside the worktree at <abs-worktree-path>. Rules:

• One logical change at a time, in canonical order: model → service → router → register in main.py → schema.
• Reuse existing helpers (id generation, response envelope, auth deps, group-role checks). Do not invent parallel utilities.
• Match the existing code style — copy the shape of the nearest sibling file rather than introducing new patterns.
• Honour the verb convention: @router.get or @router.post only — never put / delete / patch.
• Keep diffs minimal. No refactor of unrelated code, no added docstrings/comments/type hints to untouched code.
• If db_schema.sql changes, also update database/staging_data.json only if the issue requires seed data.
• Do not write tests — that is Step 7's job (/bte).
• Every file path is absolute under <abs-worktree-path>. If the issue mentions backend/services/meal_service.py, you write to <abs-worktree-path>/backend/services/meal_service.py.

Step 6 — Self-review

Produce a structured self-review in Traditional Chinese before the test step:

• 驗收條件對應表 — table of (criterion) × (where satisfied, with file:line). Unchecked = blocker.
• Authorization 檢查清單 — every new/changed service method × the group-role check applied. Missing = blocker.
• HTTP 動詞檢查 — every new/changed endpoint is GET or POST with the verb in the path. Any PUT/DELETE/PATCH = blocker.
• 資料庫一致性 — db_schema.sql matches what services expect; no drift between code and schema. Drift = blocker.
• Pydantic 欄位一致性檢查 — for every response model constructor call you added or changed: open the model file and the service file side-by-side and confirm every kwarg is a declared field on the model. Pydantic v2 silently drops unknown kwargs (extra="ignore"), so a typo or a "phantom" field never raises — it just disappears from the API response. Any drift = blocker. See Shared Context > Pydantic response model consistency for the rationale and the historical bug that motivated this rule.
• 手動測試指令 — 2–3 curl / httpie commands the user can run locally.
• 需要手動跑的 SQL（若有）— exact statements for staging / prod, in a copy-pasteable block.

If any blocker is found, fix it and re-run Step 6. Do not proceed to Step 7 with open blockers.

Step 7 — Inline /bte for each touched domain

For each touched domain in auth/user/group/pet/food/meal/weight, run the /bte unit <domain> flow inline inside the same worktree <abs-worktree-path> — do not create a new worktree, do not switch branches. Read .claude/skills/bte/SKILL.md (at the repo root) for the canonical rules. When invoked inline by /be, /bte does not run its own pre-flight or worktree creation — it writes to <abs-worktree-path> and adds a test(<domain>): ... commit that lands in /be's same PR.

• If backend/tests/unit/services/test_<domain>_service.py does not exist → bootstrap mode: produce a coverage plan, write a fresh test file for the service (creating backend/tests/unit/conftest.py with the bcrypt stub if needed), run python -m pytest backend/tests/unit/services/test_<domain>_service.py -n auto, capture the result.
• If the file already exists → review-only mode: produce a coverage map and a P0/P1/P2 list. For gaps caused by this issue's changes (P0 only), write the new test cases. Do not fix pre-existing gaps unrelated to this issue — list them for the PR body's ## Pre-existing coverage gaps section instead.

Step 8 — Pre-commit gate

cd <abs-worktree-path>/backend && pre-commit run --all-files

If it fails: read the failure, fix the underlying issue (still inside the worktree), re-stage, re-run. Never use --no-verify. If it fails twice in a row, stop the skill and report the failure to the user — do not commit broken code.

Step 9 — /summary auto-chain

Invoke /summary inline against git diff HEAD..origin/master inside the worktree. The diff is computed correctly because each worktree has its own HEAD pointing at the in-progress branch, while origin/master is shared via the common .git/objects. /summary will scan the diff for doc drift across CLAUDE.md, skill files, and memory, propose per-file diffs, and wait for user confirmation. If the user approves, the doc updates are staged for the doc commit in Step 10 — the doc edits land inside <abs-worktree-path> and travel with the PR. If /summary reports "no doc drift", skip the doc commit.

See .claude/skills/summary/SKILL.md (at the repo root) for /summary's rules.

Step 10 — Commit, push, open PR

Stage all changes inside the worktree. Use git -C <abs-worktree-path> ... or cd <abs-worktree-path> && git ... for every git command.

Cadence:

• Commit 1: feat: <issue title> (or fix: for bug issues). Body lists files changed by layer and references Closes #N for each issue.
• Commit 2 (if /bte wrote tests): test(<domain>): add unit tests for <service methods>.
• Commit 3 (if /summary applied doc updates): docs: sync after #N.

Commits use HEREDOC to preserve formatting. Never use --no-verify. Commit messages do not include a Co-Authored-By: Claude trailer.

Then push and open the PR ready-for-review (no --draft). Do not pass --label flags — labels live on issues, not PRs (see CLAUDE.md > GitHub Labels > Where labels live). gh pr create must run from inside <abs-worktree-path> so it picks up the correct branch.

cd <abs-worktree-path>
git push -u origin <branch>
gh pr create --base master \
  --title "[#N] <issue title>" \
  --body "$(cat <<'EOF'
<body per template below>
EOF
)"

For batch issues: --title "[#N1 #N2] Combined: <short combined title>".

PR body template:

Closes #N1
Closes #N2

## Summary
- <bullet 1>
- <bullet 2>

## Files changed by layer
- **Models**: ...
- **Services**: ...
- **Routers**: ...
- **Schema**: ...
- **Tests** (added by /bte): ...

## Manual test plan
```bash
<curl commands from Step 6>

Manual SQL to run (if any)

<SQL from Step 6>

Pre-existing coverage gaps (NOT fixed in this PR)

• <gap 1, with reason>
• <gap 2, with reason>

Doc updates (added by /summary)

• <file>: <one-line description>

Notes

• <any non-obvious decisions>

If a PR with the same `Closes #N` already exists on `origin`, **stop and report** — do not push or open a duplicate.

### Step 11 — Final report

Reply to the user in Traditional Chinese with:

- **PR URL** (clickable)
- **Branch name**
- **Worktree path** (absolute) — where all the work landed
- **What changed** — one-paragraph summary
- **Test results** — pytest output from Step 7 (pass / fail counts)
- **Manual SQL the user must run** — if any (highlight prominently)
- **Doc updates applied** — list of files `/summary` touched, if any
- **Non-obvious decisions** — anything you decided on your own that the user should know
- **Cleanup hint** — exact commands to run after the PR is merged:
  ```bash
  git worktree remove <abs-worktree-path>
  git branch -D <branch>

• Confirmation — "Your main IDE checkout was NOT modified."

Never auto-merge. Never force-push.

Subcommand: discuss

Invoked as /be discuss <topic> (e.g. /be discuss "should meals support partial servings", /be discuss "FK between meals and foods cascade behaviour").

This is open Q&A about backend or database design / development. Topics can be architectural, schema-level, API-level, or about a specific piece of code.

1. Read whatever files are needed to ground the discussion in real code, not abstract advice. If the topic mentions a service / table / endpoint, read it before responding.
2. Honour the Shared Context above — stay consistent with the existing layering, response envelope, auth model, schema conventions, and the GET/POST-only verb rule. If the user is proposing something that contradicts those conventions, call it out explicitly and ask whether they want to revise the convention.
3. Do NOT implement anything in discuss mode, even if the answer obviously implies a code change. Discuss always ends with options + a request for direction.

Structure the response in Traditional Chinese with exactly these five sections, in this order:

1. 問題理解與範圍確認

Restate what you think the user is asking in 1-3 sentences. Explicitly list what is in scope and what is out of scope for this discussion. If you are unsure of the scope, ask for clarification before continuing — do not guess.

2. 三個可行方案（含優缺點）

Always produce three proposals. If you genuinely cannot think of three, say so explicitly and explain why, then provide as many as you can. For each proposal:

• 方案 X：<short name>
• 做法：concrete steps (file paths, schema changes, API shape — be specific, not abstract). All proposed endpoints must use only GET / POST.
• 優點：bullet list
• 缺點：bullet list
• 影響範圍：which layers / files / tables are touched
• 複雜度：低 / 中 / 高

Order proposals from "smallest change that solves the problem" to "most ambitious".

3. 我的疑慮與建議

• 疑慮：things you are worried about regardless of which proposal is chosen — data integrity, performance, authorization, migration risk, backwards compatibility, hidden coupling.
• 建議：which of the three proposals you would pick and why, in 2-4 sentences. Be opinionated; vague recommendations are not useful.

4. 等使用者拍板的決定

Explicit list of decisions you need from the user before any implementation can start. Format as a numbered list of yes/no or pick-one questions, not open-ended prompts. Each item should be answerable in one sentence.

5. 如果這題收掉之後，還可以延伸做的事

Forward-looking list of related improvements or follow-ups that would naturally come after this discussion is resolved. Each item should be one line. This is not a commitment — just a list of "if we had time" ideas the user can park for later.

Subcommand: doc

Invoked as /be doc <domain>, /be doc <d1>,<d2>,..., or /be doc all.

This subcommand generates standard markdown API documentation for one or more backend domains, written to backend/docs/api/<domain>.md. The audience is the frontend engineer who wants offline / version-controlled / grep-able reference for every endpoint without booting the backend dev server. It is complementary to the runtime FastAPI auto-docs at /scalar (which remain authoritative for interactive exploration), not a replacement.

Run this fully synchronously in the user's main checkout per CLAUDE.md > Dev Flow. Do not write .py files, do not modify db_schema.sql, do not invoke /bte. The generated docs are 100% auto-generated — no manual edit blocks, no preserved hand-written sections. If something needs prose context, put it in the issue / commit message, not the doc.

Step 1 — Resolve and validate the domain list

Parse the argument:

• Single domain: /be doc auth → ["auth"]
• Comma-separated: /be doc auth,user,pet → ["auth", "user", "pet"] (strip whitespace, drop empty entries)
• all keyword: /be doc all → ["auth", "user", "group", "pet", "food", "meal", "weight"]

Each resolved domain must be in the canonical set auth / user / group / pet / food / meal / weight. If any token is invalid, show the usage block and stop.

For each resolved domain, verify the source files exist:

• backend/routers/<domain>_router.py
• backend/services/<domain>_service.py
• backend/models/<domain>.py

If any are missing, stop and report which file is missing — do not skip silently.

Step 2 — Read source files

For each domain, read all three source files in full. Do not glob or rely on grep — the parser needs the complete file content to resolve Depends, Body, response_model, and Pydantic field types.

Step 3 — Parse endpoints

For each domain's router, walk every @router.get(...) / @router.post(...) decorator and extract:

• Method + full path — combine router prefix with the decorator path. If you see @router.put / @router.delete / @router.patch, stop and report as a bug (verb convention: GET / POST only); do not document.
• Path / query params — typed scalars without Body(...) / Depends(...).
• Request body — Pydantic model from body: SomeModel = Body(...).
• Response model — response_model=... or return type annotation, resolved to Pydantic fields.
• Auth — Depends(get_current_user) → JWT, Depends(verify_api_key) → API key, none → public.
• Group role — scan the called service method for group_service.check_* patterns. If a pet / food / meal / weight endpoint has no role check, flag P0 in the doc and in the final report.
• Errors — raise HTTPException(status_code=..., detail=...) in router + service, grouped by status code.
• Description — function docstring first line, else inferred from function name.

Step 4 — Confirmation gate

Pause and ask the user before proceeding if any of the following are true:

• An existing backend/docs/api/<domain>.md file is being overwritten (show file size + last-modified date so the user knows what is being replaced)
• An authorization gap was found in Step 3 (a group-scoped endpoint without a role check)
• The parser could not resolve a request or response Pydantic model (you would have to write TBD in the doc)

Otherwise proceed to Step 5 immediately.

Step 5 — Pre-flight + worktree creation

Run pre-flight per CLAUDE.md > Dev Flow against the user's main checkout (read-only):

git fetch origin master                                       # must succeed
git ls-remote --heads origin claude/be-doc-<slug>             # collision check (remote)
git branch --list claude/be-doc-<slug>                        # collision check (local)
git worktree list                                             # collision check (worktree)

Compute:

• Branch name: claude/be-doc-<domain> for single (e.g. claude/be-doc-meal), claude/be-doc-<d1>-<d2> for batch (e.g. claude/be-doc-meal-food), claude/be-doc-all for all.
• Worktree path: ~/codebase-worktrees/PetCare-be-doc-<slug> where <slug> is the domain or domain list joined with - (e.g. PetCare-be-doc-meal, PetCare-be-doc-meal-food, PetCare-be-doc-all).

Failure modes:

• git fetch fails → report verbatim and stop.
• Branch / worktree path collision → append -2, -3, ... until unique.

Create the worktree in a single command:

git worktree add <abs-worktree-path> -b <branch> origin/master

The worktree path AND branch name must appear in the user-facing report.

From here onward, every Bash call is cd <abs-worktree-path> && ... and every Read / Edit / Write uses an absolute path under <abs-worktree-path>.

Step 6 — Generate doc files

For each domain, write <abs-worktree-path>/backend/docs/api/<domain>.md using the Standard API Doc Template below. Create the <abs-worktree-path>/backend/docs/api/ directory if it does not exist.

Overwrite the entire file — do not preserve any existing content. The doc is 100% auto-generated and any manual edits will be lost on the next regeneration. This is by design (decided in /be discuss on 2026-04-08).

Step 7 — Self-review

Before committing, sanity check each generated file:

• Endpoint count match — ### \POST`/### `GET`headings =@router.get+@router.post` decorators in source. Mismatch = blocker.
• Required sections present — every endpoint has Function / Auth / Group role / Request / Response / Errors / Source. Missing = blocker.
• Authorization gaps annotated — every group-scoped endpoint without a role check is flagged with ⚠ MISSING CHECK in the Auth & Authorization Summary table.

If any blocker is found, fix and rewrite. Do not commit a doc with blockers.

Step 8 — /summary auto-chain

Invoke /summary inline against git diff HEAD..origin/master inside the worktree. /summary will scan whether the new doc files need to be referenced from CLAUDE.md (e.g. adding a "Static API docs live in backend/docs/api/" line to the ## Backend section, or noting /be doc in the ## Project Skills > /be section). If /summary reports drift, the user confirms, and the updates are staged for the doc-sync commit in Step 9 — they land inside the worktree and travel with the PR.

See .claude/skills/summary/SKILL.md for /summary's rules.

Step 9 — Commit, push, open PR

All git commands run inside the worktree. Use git -C <abs-worktree-path> ... or cd <abs-worktree-path> && git ....

Commit cadence:

• Commit 1: docs(<domain>): add api documentation for single domain, or docs(api): add documentation for <d1>, <d2>, ... for batch / all. Body lists the documented domains and references the source files parsed.
• Commit 2 (only if /summary applied updates in Step 8): docs: sync after api doc generation.

Use HEREDOC for commit messages. Never use --no-verify. Commit messages do not include a Co-Authored-By: Claude trailer. There is no pre-commit quality gate for this subcommand because no .py files change.

Push and open the PR ready-for-review (no --draft). Do not pass --label flags — labels live on issues, not PRs. Run gh pr create from inside <abs-worktree-path>.

cd <abs-worktree-path>
git push -u origin <branch>
gh pr create --base master \
  --title "[docs] Document <domain> API endpoints" \
  --body "$(cat <<'EOF'
<body per template below>
EOF
)"

PR title:

• Single: [docs] Document <domain> API endpoints
• Batch: [docs] Document <d1>, <d2>, ... API endpoints
• All: [docs] Document all backend API endpoints

PR body template:

## Summary
- Generated API documentation for: <domain list>
- N endpoints across N domains

## Files added / changed
- `backend/docs/api/<domain>.md` (new) — N endpoints
- ... (one line per domain)

## Authorization findings
- ⚠ <domain>.<endpoint>: missing group-role check (P0 — fix via separate /be flow)
- ✓ All other endpoints have appropriate role checks

## Doc updates (added by /summary)
- <file>: <one-line description>

If a PR with the same branch already exists on origin, stop and report — do not push or open a duplicate.

Step 10 — Final report

Reply to the user in Traditional Chinese with:

• PR URL (clickable)
• Branch name
• Worktree path (absolute)
• Domains documented — list with endpoint count per domain (e.g. meal: 8 endpoints)
• Authorization findings — flag any group-scoped endpoint without a role check (P0)
• Parser issues — anything the parser could not resolve and wrote TBD for
• Doc updates applied — list of files /summary touched, if any
• Cleanup hint — exact commands to run after the PR is merged:

  git worktree remove <abs-worktree-path>
  git branch -D <branch>
  

• Confirmation — "Your main IDE checkout was NOT modified."

Never auto-merge. Never force-push.

Standard API Doc Template

This is the exact markdown structure every generated backend/docs/api/<domain>.md file must follow. Fill in the placeholders from the parsed source files; do not improvise additional sections.

# `<domain>` API Documentation

> **Auto-generated** by `/be doc <domain>` from:
> - `backend/routers/<domain>_router.py`
> - `backend/services/<domain>_service.py`
> - `backend/models/<domain>.py`
>
> **Do not edit by hand** — re-run `/be doc <domain>` to regenerate.
> Last regenerated: `YYYY-MM-DD`

## Overview

<one-paragraph description of what this domain owns, inferred from the service file's top-of-file docstring or module-level comment>

## Auth & Authorization Summary

| Auth requirement | Endpoints |
|---|---|
| Public (no auth) | `<METHOD> <path>`, ... |
| API key (`Authorization: Bearer api_key:api_secret`) | ... |
| JWT (`Authorization: Bearer <jwt>`) | ... |

| Group role required | Endpoints |
|---|---|
| Creator only | ... |
| Member or above | ... |
| Viewer or above (read) | ... |
| N/A (no group context) | ... |
| ⚠ MISSING CHECK | ... |

## Endpoints

### `<METHOD>` `<full path>`

**Function**: <one-sentence description>

| Field | Value |
|---|---|
| Auth | <none / API key / JWT> |
| Group role | <none / creator / member / viewer / ⚠ missing> |
| Request model | `<PydanticClassName>` |
| Response model | `<PydanticClassName>` |

**Path parameters**:

| Name | Type | Description |
|---|---|---|
| `<name>` | `<type>` | <description> |

(or `_(none)_` if no path params)

**Query parameters**:

| Name | Type | Required | Description |
|---|---|---|---|
| `<name>` | `<type>` | yes / no | <description> |

(or `_(none)_`)

**Request body**:

```json
{
  "field1": "<type> (required) — <description from Pydantic Field>",
  "field2": "<type> (optional) — <description>"
}
```

(or `_(none)_` for GET endpoints with no body)

**Success response** (HTTP 200, `status: 1`):

```json
{
  "status": 1,
  "data": {
    "<field>": "<type> — <description>"
  },
  "message": "<message>"
}
```

**Error responses**:

| HTTP | When | `detail` message |
|---|---|---|
| 400 | <condition> | `<message>` |
| 401 | <condition> | `<message>` |
| 403 | <condition> | `<message>` |
| 404 | <condition> | `<message>` |

**Source**: `backend/routers/<domain>_router.py:<line>`

---

(repeat for each endpoint, in the order they appear in the router file)

Usage block (show this when arguments are invalid)

/be 用法：

  /be <issue_number>[,<issue_number>...]   讀 issue → 規劃 → 實作 → 自審 → 交給 /bte 補測試
  /be discuss <topic>                       針對 backend / database 設計或開發問題進行五段式討論
  /be doc <domain>[,<domain>...]            產出 backend/docs/api/<domain>.md 標準 markdown API 文件
  /be doc all                               一次產出全部 7 個 domain 的 API 文件，合併成一個 PR

範例：
  /be 12
  /be 12,15,18
  /be discuss "meal 是否要支援 partial serving size？"
  /be discuss "foods 表的 group_id FK 應該 cascade 還是 restrict？"
  /be doc meal
  /be doc meal,food
  /be doc all