hyb-oa/.trellis/tasks/05-29-frontend-ux-wave4-5-finance-admin-refresh/implement.md

# Implementation Plan

## Current Decision

This task completes the remaining frontend wave work by combining:

1. Wave4 finance/operations refresh after the newer Wave0-3 baseline.
2. Wave5 admin/config gap fill for pages that were not fully covered by the historical Wave4 task.

It is not a blank rebuild of finance/admin pages.

## Recommended Implementation Order

1. Baseline audit:
   - Compare current finance/admin pages against `frontend-design`, Wave0-3 shell/header conventions and historical Wave4 classes.
   - Identify pages that need code changes versus pages that only need test coverage.
2. Wave5 gap pages:
   - `ApprovalRulesPage`
   - `PeoplePage`
   - `OrganizationPage`
   - `WorkspaceSetupPage`
3. Wave4 refresh pages:
   - `PaymentBatchesPage`
   - `ApOperationsPage`
   - `InvoicePoolPage`
4. Regression surfaces:
   - `UserManagementPage`
   - `MasterDataPage`
   - `NotificationChannelsPage`
   - `SystemSettingsPage`
   - `FeatureFlagsPage`
   - `WorkflowDefinitionsPage`
   - `AuditLogsPage`
5. Test baseline:
   - Extend or replace the existing focused Wave4 Playwright spec so it covers Wave4 plus Wave5 gaps.
   - Keep public deployment gated by explicit approval.

## Guardrails

- No backend, schema, permission, payment-state, approval-rule semantic, WeCom or env changes.
- Do not remove existing business actions.
- Payment, export, sync, enable/disable and config-publish actions keep original confirmation and permission behavior.
- Do not add a new design language; reuse existing finance/admin/ops classes.
- Do not claim user-test readiness until public deployment and public checks pass.

## Local Verification Plan

```bash
cd client && npm run typecheck
cd client && npm run build
cd client && npx playwright test tests/e2e/pc-finance-admin-visual-wave4.spec.ts --workers=1 --reporter=list
node scripts/qa/check-ui-design-rules.mjs --strict
python3 ./.trellis/scripts/task.py validate 05-29-frontend-ux-wave4-5-finance-admin-refresh
node scripts/qa/check-trellis-governance.mjs
git diff --check
```

## Completed Implementation

2026-05-29:

- Refreshed `ApprovalRulesPage` with Wave5 admin summary metrics, a command-oriented creation panel and a cleaner rule-list surface.
- Refreshed `PeoplePage` to use the shared workspace/header baseline, finance/admin metrics, WeCom HR command surface, filter panel, batch-action panel and focused table container.
- Refreshed `OrganizationPage` to use the shared management shell, organization summary metrics and admin command panels while keeping hierarchy readability.
- Refreshed `WorkspaceSetupPage` to use the shared management shell, module visibility metrics, role preset tiles and a focused module table with Chinese visibility labels.
- Extended `client/tests/e2e/pc-finance-admin-visual-wave4.spec.ts` from historical Wave4 coverage to Wave4-5 coverage.
- Kept Wave4 finance pages on the existing approved surface; no backend or business-state changes were made.

## Local Verification Result

- `cd client && npm run typecheck` passed.
- `cd client && npx playwright test tests/e2e/pc-finance-admin-visual-wave4.spec.ts --workers=1 --reporter=list` passed: 3 tests.
- `cd client && npm run build` passed.
- `node scripts/qa/check-ui-design-rules.mjs --strict` passed with 0 findings.
- `python3 ./.trellis/scripts/task.py validate 05-29-frontend-ux-wave4-5-finance-admin-refresh` passed.
- `node scripts/qa/check-trellis-governance.mjs` passed after task metadata was completed.
- `git diff --check` passed.

## Spec Update Decision

No `.trellis/spec/` update is needed for this implementation. The task applied existing frontend conventions (`ListWorkspace`, `WorkspaceHeader`, `finance-status-strip`, `admin-command-panel`, `PrimaryTable`) and did not introduce a new reusable frontend contract, API signature, env key, schema, permission rule or deployment behavior.

## Deployment Plan

Only after explicit approval:

```bash
SYNC_ENV=0 LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash deploy/trialrun/deploy.sh
LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh
OAOPS1_REPORT_DIR=.trellis/tasks/05-29-frontend-ux-wave4-5-finance-admin-refresh/research/postdeploy-<date>-wave4-5-public \
  LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-oa-real-use-daily.sh
```

## Deployment Result

2026-05-29 user-approved public deployment completed.

- Deployed commit: `bfb1cb6 完成 Wave4-5 财务与管理页刷新（05-29-frontend-ux-wave4-5-finance-admin-refresh）`.
- Deploy command used `SYNC_ENV=0`, so the remote `.env` was not overwritten.
- Deploy script passed env contract, remote build, seed/config, seed/trialrun, `/ready`, external dependency smoke, runtime smoke and public bundle copy scan.
- Remote migrations had no pending migration.
- Deploy rsync reported a non-fatal warning for an old non-empty artifacts directory; deployment continued and runtime checks passed.
- Automatic deploy-time live smoke was skipped because the deploy shell did not include the full live smoke variables; manual postdeploy checks below covered it.

## Postdeploy Verification Result

Final passing evidence is stored under:

`research/postdeploy-20260529-wave4-5-public-rerun/`

- `run-live-smoke-readiness.sh`: `PASS`.
  - `/ready` passed.
  - Public bundle copy scan passed with 0 findings.
  - Live smoke Playwright passed: 3 tests.
  - Live OCR sample passed: 1 test. The sample produced the expected duplicate/same-invoice style OCR outcome for the already-used sample file.
  - Pending OCR scan skipped because the local command environment did not include `DATABASE_URL`.
- `run-oa-real-use-daily.sh`: `PASS_OA_REAL_USE_DAILY_READY`, `findingCount=0`.
  - `public-ready`: PASS.
  - `live-smoke-env`: PASS.
  - `live-readiness`: PASS.
  - `oa-only-smoke-readiness`: PASS.
  - `live-feature-flags`: PASS.
  - `authenticated-readonly-probe`: PASS.
  - `mobile-entry-matrix`: PASS.
  - `wecom-rendering-matrix`: PASS.
  - `wecom-entry`: PASS.
  - `report-privacy-smoke`: PASS.

## Report Privacy Fix

The first OAOPS1 run failed only at `report-privacy-smoke` because the live smoke env report emitted secret-looking env key names as boolean presence fields. It did not expose actual secret values.

`scripts/qa/check-live-smoke-env.mjs` now emits safe readiness labels such as `adminCredentialReady`, `employeeCredentialReady`, `managerCredentialReady` and `financeCredentialReady` instead of raw env key names containing password-like words. The rerun passed privacy smoke.

## Spec Update Expectation

Only update `.trellis/spec/` if implementation introduces a reusable frontend convention beyond the existing finance/admin surfaces. If the task only applies existing conventions, record that no spec update is needed.