FPSMS-backend/AGENTS.md

# FPSMS Agent Notes

## Repository Relationship

- Current backend repo: `FPSMS-backend`
- Paired frontend repo location: `../FPSMS-frontend`

## Working Convention

- If a task is about UI behavior (charts, clicks, page rendering, dialogs), check `../FPSMS-frontend`.
- If a task is about API/business logic/data query, check this backend repo.
- For end-to-end changes, update both repos and keep API request/response fields aligned.

## M18 ↔ MTMS data mapping

- Handbook: [`docs/MTMS_M18_DATA_MAPPING.md`](docs/MTMS_M18_DATA_MAPPING.md)
- Auto tables: [`docs/generated/`](docs/generated/) — regenerate with `python scripts/generate_m18_mapping_docs.py` after changing `ItemType` / `M18ItemType` or product-type `when` in `M18MasterDataService`.
- Word / Excel (readable exports): `python scripts/export_m18_mapping_office.py` → [`docs/exports/`](docs/exports/)

## User guides (UI-oriented)

- Source Markdown: [`docs/user-guides/`](docs/user-guides/)
- Export Word: `python scripts/export_user_guide_office.py` → `docs/exports/*.docx`
- Guides (UI labels in 「」):
  - 排程 → 工單 → `MTMS_Schedule_JobOrder_UserGuide.docx`
  - BOM 匯入／啟停／應用 → `MTMS_BOM_UserGuide.docx`
  - 工單提料／報工／上架 → `MTMS_JO_Pick_Production_PutAway_UserGuide.docx`
  - 送貨訂單／放單／成品出倉 → `MTMS_DO_Shipping_UserGuide.docx`

## Deploy / QA notes (what changed + how to test)

- **How-to for the team:** [`docs/deploy/HOW_TO_GENERATE_COMMIT_TEST_PLANS.md`](docs/deploy/HOW_TO_GENERATE_COMMIT_TEST_PLANS.md)
- **In Cursor:** say `gen test plan` / `產測試計畫`, or slash **`/gen-commit-test-plans`**
- Template: [`docs/deploy/TEMPLATE.md`](docs/deploy/TEMPLATE.md)
- Filled notes: [`docs/deploy/`](docs/deploy/) (e.g. `YYYYMMDD_short-topic.md`)
- **Auto Word test plan per commit** (folder):
  ```bash
  pip install python-docx
  python scripts/generate_commit_test_plans_docx.py HEAD~10..HEAD
  ```
  → [`docs/deploy/commit-plans/`](docs/deploy/commit-plans/) (`YYYY-MM-DD_<sha>_<slug>.docx` + `_index.md`)
  Optional: `--also-md` / `--out-dir path` / `--limit N`
- Scaffold one range note: `python scripts/generate_deploy_test_plan.py HEAD~5..HEAD --out docs/deploy/draft.md`
- For critical deploys, ask the agent to refine steps against the real diff (Cursor rule: deploy-test-plan)