# nexuscrm-pingcap-pack

PingCAP-specific tenant pack for NexusCRM.

This repository carries PingCAP's L2 customizations (custom fields, business
workflows, approval processes, layouts, validation rules) on top of the
generic CRM L1 pack provided by [pingcap-inc/NexusCRM](https://github.com/pingcap-inc/NexusCRM).

This repo is also the deployment orchestrator for the PingCAP distribution:
it assembles downstream pack artifacts and supplies L2 deployment semantics to
the independent local deployment scripts and remote deploy paths.

Tracked repo docs for this stack model live under:

- `docs/stack-test-model.md`
- `docs/l2-ui-pack-guide.md`

## Layout

- `docs/epics/` — strategic body-of-work documents (Epic level), reviewed via PR
- `docs/MIGRATION_NOTICE.md` — the consolidated record of the legacy
  `MetaDrivenPlatform4AI` migration (filled at the end of the migration)
- `.claude/skills/migration-*` — Claude Code skills used during the
  legacy-issue migration (Epic / Story / Task / Bug + test scaffolding)
- `.github/ISSUE_TEMPLATE/` — story / task / bug templates
- `migration_audit.csv` — issue-level disposition audit (one row per legacy
  issue), permanent record

## Issue convention

Every story / task / bug filed in this repo must start its body with:

```
**Epic:** docs/epics/<epic-id>.md
```

`type:*` labels distinguish role: `type: story` / `type: task` / `type: bug`.

## OSS boundary

PingCAP-specific content stays in this repo. Generic L1 / L0 platform
content belongs in [pingcap-inc/NexusCRM](https://github.com/pingcap-inc/NexusCRM)
which is the open-source baseline.

The legacy migration explicitly does **not** write to NexusCRM. Engineers
later identify generic content for OSS upstream as a separate workstream.

## Independent local deployment

For a fresh local environment, use the separate L0, App installation, and L1
entrypoints in [Independent local deployment](docs/local-independent-deployment.md).
They accept local images without deployment version or provenance comparisons.

Test and Staging can be used for production-simulation verification through
[the environment controllers](deployments/README.md). Local first-install
success does not establish upgrade, release provenance, or production acceptance.

## Pack Generation

The unified pack is generated from frozen repo-local inputs:

- generated pack:
  - `packs/NOT-EDIT-final-merged-packs`
- intermediate pack:
  - `packs/Salesforce-PingCAP-L2`
- official standard source:
  - `pingcap-inc/nexuscrm-app-packs@main -> salesforce-crm-standard`
  - optional override: `OFFICIAL_APP_PACKS_REF`
- upstream runtime source:
  - `pingcap-inc/NexusCRM@main`
- raw source bundle:
  - `packs/_source-bundles/salesforce-metadata-sample-20260503.tar.gz`
- build script:
  - `scripts/build_pingcap_salesforce_sample_pack.sh`

Current workflow:

1. run the XML conversion once to materialize `packs/Salesforce-PingCAP-L2`
2. check in `packs/Salesforce-PingCAP-L2`
3. later maintain `packs/Salesforce-PingCAP-L2` by hand
4. day-to-day build assembles an install-only final pack into `packs/NOT-EDIT-final-merged-packs`

Contract notes:

- `packs/Salesforce-PingCAP-L2` is downstream source material, not the final install contract
- `packs/NOT-EDIT-final-merged-packs` is the only artifact install/bootstrap should consume
- final assembly must fail closed if upstream `object_spec` contract drifts
- final build lineage is recorded in:
  - `packs/NOT-EDIT-final-merged-packs/.build-lineage.json`

## AUTO_GEN Product-pack Mirror

This repo can also track a read-only mirror of the live production metadata
state:

- mirror root:
  - `packs/AUTO_GEN_Product-pack`
- live component-shaped export:
  - `packs/AUTO_GEN_Product-pack/live`
- generated diff reports:
  - `packs/AUTO_GEN_Product-pack/reports`
- sync workflow:
  - `.github/workflows/sync-product-pack.yml`

This mirror is for visibility and drift review only.

Compare final pack vs AUTO_GEN mirror:

```bash
python3 scripts/product_pack_live/compare_final_pack_vs_autogen_product_pack.py
```

Generate stable diff reports:

```bash
python3 scripts/product_pack_live/generate_final_pack_vs_autogen_reports.py
```

Generate the first-pass L2-filtered AUTO_GEN pack and the focused L2 diff report:

```bash
python3 scripts/product_pack_live/generate_autogen_product_l2_filter_pack.py
python3 scripts/product_pack_live/generate_l2_vs_autogen_filter_reports.py
```

Operational note:

1. the hourly schedule only takes effect when `.github/workflows/sync-product-pack.yml`
   is present on the repository default branch
2. the workflow runs from default branch code, but it updates the dedicated `product-pack-live` branch
3. before that, it can still be run manually with `workflow_dispatch`

It is not:

1. the source material for downstream authoring
2. the final install artifact
3. the official app-pack authority

Rebuild final from the pinned official pack + checked-in L2:

```bash
bash scripts/build_pingcap_salesforce_sample_pack.sh --reset
```

Run the one-time XML -> L2 generation helper:

```bash
bash scripts/convert_issue157_object_census_pack.sh --reset --upstream-pack-dir /path/to/nexuscrm-app-packs/salesforce-crm-standard
```