Files
streamline/docs/product-profiles.md
2026-11-16 17:26:44 -08:00

125 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Product profiles
Management → **Products & branches** configures product profiles for Bug and Feature tasks. Only admins may save settings.
**TikTok** is the built-in default (branch `develop` on both platforms). Creating a task selects TikTok unless the user picks another enabled product. Lemon8 and Notes start as disabled drafts; verify the remote branches and Bits configuration before enabling them.
The create dialog’s More options lists **Product profile** above **Custom branch**. Picking a non-default product fills Custom branch once with that product’s base branch; the user can still edit it afterwards. Each profile option is `id (repo path)`. A snapshot of the selected product is stored on the task for display; execution follows Custom branch (the same `baseRef` path Bug already used).
| Draft | Platform | Repository | Base / requested target |
| --- | --- | --- | --- |
| TikTok (default, enabled) | iOS | ugc/TikTok | develop |
| TikTok (default, enabled) | Android | ugc-android/TikTok | develop |
| Lemon8 | iOS | ugc/TikTok | lemon8/develop |
| Lemon8 | Android | ugc-android/TikTok | develop |
| Notes | iOS | ugc/TikTok | notes/develop |
| Notes | Android | ugc-android/TikTok | notes/develop |
These targets are proposed request values, not verified Bits final-target mappings. Bits can rewrite the target through its own workflow.
## Compatibility and scope
- TikTok (or an omitted `productProfileId`) retains legacy behavior, including independent node/control-plane `BASE_BRANCH` defaults. Old satellites can still claim TikTok tasks. No profile is inferred from task text or KB context.
- Selection resolves after platform classification. Meego platform metadata still wins over the creation dialog's platform button. A bulk import uses one settings revision; unsupported-platform tickets are returned in `skipped`.
- Tasks store a server-authored `productProfile` snapshot in `tasks.product_profile` / `features.product_profile`. Later management edits, disabling the product and satellite updates cannot rewrite it. A newly created cross-platform port resolves the same product ID for its destination platform from current enabled settings; it fails explicitly if unavailable.
- Custom branch is `baseRef` on both Bug and Feature. An explicit value always wins. A non-default product fills it at create time when the caller left it empty. Empty still means trunk `develop`. `baseRef` only decides where the fix branch is cut from and where the MR points — merges always go through Bits; the executor merge-back that used to run on approval (2026-10-26) is gone.
- Sidecar repositories retain their registry-owned defaults, including `tt_im_monorepo` → `master`. They do not inherit the client product's branches.
- Only the already registered iOS/Android delivery repositories are selectable. Adding arbitrary repositories, changing GitLab/Bits identities, credentials, checkout paths or deployment pools is not part of this form.
- Non-default (Lemon8 / Notes) tasks still require satellites that advertise `productProfilesVersion: 1`. Those nodes verify the exact repository origin and fetch the configured remote branches before a profiled run. Failure does not fall back to another product's checkout.
## Product prompt
Each product × platform has an optional **Product prompt** textarea (≤ 8000 characters) in Management → Products & branches. Use it for facts the default prompts and the node workspace get wrong for this product: the app under test and its package name, the build command, usable accounts, known pitfalls.
- **Where it lands.** At dispatch the control plane appends it, under a `## 产品定制说明(<product> · <platform>)` heading that states it overrides conflicting defaults, to the end of the Bug / Feature main prompts: `eval` / `regen`, `feature.eval` / `feature.regen`, `bug.run`, `feature.run.first` / `feature.run.second`. Not `bug.critic`, and not security / prototype / verification yet. RSI lab reruns keep their own wording.
- **Which text.** Looked up from the *current* settings by the task's snapshot `profileId` and platform, so an edit applies to everything not yet claimed — it is deliberately not part of the write-once snapshot. A task without a snapshot (no product chosen at create) uses the default product, TikTok. A disabled product still supplies its text to tasks already created under it.
- **No satellite upgrade.** Prompt bodies already ride down with the work item, so the control plane edits the text it sends; older satellite bundles pick it up as is. `{{` / `}}` in the text are split so node-side variable substitution cannot touch it.
- **Visibility.** Only the admin endpoints return it; `GET /api/product-profiles` and the open-platform view strip it.
- **This is the one prompt that does not live in code** (see `CLAUDE.md` → 改 prompt). It has no git history: the settings row keeps only the latest revision. Keep stage wording in `shared/src/*_prompt.ts`; put only product facts here.
## API
`GET /api/product-profiles` exposes enabled profiles (TikTok is present by default). `GET /api/admin/product-profiles` includes drafts; `PUT /api/admin/product-profiles` accepts `{ revision, profiles }`. Saves validate repository/platform compatibility and branch syntax; optimistic revision conflicts return 409. Storage is one versioned settings row (`product_profiles_v1`), with no boot-time seed writes.
Creation endpoints accept optional `productProfileId` (default TikTok in the UI) and optional `baseRef` (Custom branch), e.g. `"notes"`: `/api/import`, `/api/features`, `/api/openapi/tasks`, and the open-platform v1 creation endpoints (`/meego-import`, `/tasks`, `/features`; on v1 an invalid branch name is a 400, see `docs/openapi.md`). Callers send an ID, not their own snapshot. Existing deduplication still returns the existing task without changing its configuration.
`GET /api/product-profiles` is the console's own shape: it is unauthenticated on the panel host but it is not a versioned contract for external integrators. Those callers get a purpose-built, API-key-authenticated view of the same selectable set, from the same source and with the same enabled-only filter, at `GET /api/openapi/v1/product-profiles`. That response adds `defaultProfileId` and renders each platform's registered `repoPath` (the console shows `id (repo path)`) instead of `repoKey`, and omits `enabled` because only enabled profiles are returned. The task view (`GET /api/openapi/v1/tasks[/:id]`) and the feature view (`GET /api/openapi/v1/features[/:id]`) echo `productProfileId` / `productProfileName` from the stored snapshot, so a caller can confirm the selection took effect (`null` = omitted at create, i.e. no snapshot and the trunk default applies).
Omitting `productProfileId` is not byte-for-byte the same as sending `tiktok`: an omitted value stores no snapshot and follows the node/control-plane trunk default (`BASE_BRANCH`), while an explicit profile follows the profile's configured `baseBranch`. They agree only while the default product still points at `develop`. See `docs/openapi.md` for the open-platform surface.
## Rollout (not performed by this change)
1. Apply `drizzle/0023_product_profiles.sql` before deploying the new control plane (nullable columns, no backfill). The migration also adds `features.base_ref`.
2. Deploy control plane and web. Keep Lemon8 / Notes drafts disabled while verifying configuration. TikTok is already enabled.
3. Upgrade the intended iOS/Android satellites before enabling Lemon8 / Notes. Their claim requests advertise `productProfilesVersion: 1`; older nodes are SQL-filtered out of **non-TikTok** profiled tasks only. TikTok / unprofiled work still runs on older nodes.
4. Verify repository access, base and requested target branches, the product build environment and actual Bits target mapping. Enable a profile and try one task in the intended pool before broader use.
### Operator checklist
The deployment script **checks** migrations but does not apply them. After the
merged code is available in the deployment checkout, and before restarting the
control plane, the authorized operator runs the existing migration workflow:
```sh
bun scripts/apply-migration.ts drizzle/0023_product_profiles.sql
# Only after reviewing the dry run and approving the production schema change:
bun scripts/apply-migration.ts drizzle/0023_product_profiles.sql --commit
bun scripts/check-migrations.ts
```
Run these in the configured deployment environment as its repository owner;
do not copy production credentials into a local development shell. The migration
adds nullable text columns only, is idempotent, and needs no historical backfill.
Allow for PostgreSQL's brief ALTER TABLE lock when scheduling it.
Then use `.claude/skills/streamline-deploy/deploy.sh` for the normal control-plane,
web and satellite deployment. `bun run build` alone does not rebuild satellites.
The deployment script's default satellite scope is the `default` pool: separately
coordinate upgrades for any other pool that will run Lemon8 / Notes. Do not
force-restart busy nodes; queued or offline nodes have not adopted the new
capability until they actually restart and claim with `productProfilesVersion: 1`.
Before enabling a non-default profile, confirm the node's `TikTok` checkout origin matches
the configured registered repository, both remote branches exist and are
fetchable, and isolated evaluation worktrees are enabled (`EVAL_WORKTREE` must
not be `0`). Verify the product-specific build/device setup and Bits' final
target mapping with an authorized canary. No new secret or global `BASE_BRANCH`
change is required by this MR; repository registration, credentials and Bits
integration remain outside the management form. No active prompt version needs
to be edited: Custom branch uses the same first-run note Bug already injects.
Rollback: disable non-default profiles to stop new opt-ins. Existing snapshots remain intact. Do not roll the control plane back to a version without claim gating while non-TikTok profiled tasks are queued.
## Verification
Run `bun run typecheck`, `bun run build`, and `bun run test`. The ordinary suite never requires a database. For DB integration, create an isolated local database **named `streamline_profiles_test`**, apply the schema, then point both `TEST_DATABASE_URL` and `PRODUCT_PROFILES_TEST_DATABASE_URL` at it and run `bun test control-server/test/product_profiles_pg.test.ts`. The test rejects non-local or differently named databases and stubs all external HTTP requests.
For manual UI verification, start Vite with `API_TARGET=http://127.0.0.1:1` and open `/test/fixtures/product-profiles.html`. This renders the real Management/ImportDialog components with an in-memory API; saves and creates cannot reach production. It is not included in the production entry point.
### Real local service
For persistent manual testing, create a dedicated PostgreSQL database named
`streamline_profiles_dev` on `127.0.0.1`, then run from the repository root:
```sh
DATABASE_URL=postgres://streamline_test@127.0.0.1:55438/streamline_profiles_dev bun --no-env-file x drizzle-kit push --force
DATABASE_URL=postgres://streamline_test@127.0.0.1:55438/streamline_profiles_dev bun --no-env-file scripts/local-dev.ts
```
The example assumes PostgreSQL is already running on port 55438 and the local
role `streamline_test` exists. Schema initialization is **only** for this new,
disposable database, never a shared or production database.
Open `http://127.0.0.1:63868/manage` → **Products & branches**. The real API runs
on port 63869 and settings/tasks persist in PostgreSQL. The frontend signs in as
a local test admin through a serve-only SSO adapter; the normal backend identity
resolver and admin checks still run. This is not production SSO. Enable a draft
locally, then create a plain-text Bug or Feature to test its saved snapshot.
The launcher refuses other database hosts/names, does not inherit production
credentials or load env files, blocks outbound HTTP integrations and execution
routes, and does not start schedulers or satellites. Tasks remain queued for
evaluation; no code repair, MR submission or notification runs. The normal Vite
and server entrypoints are unchanged. `Ctrl-C` stops both local application
processes; PostgreSQL data remains available for the next run.