部署优化

2026-08-03 20:59:59 +08:00
parent 5294edab89
commit 727643f1f2
18 changed files with 358 additions and 130 deletions
--- a/.project-docs/20-architecture/system-overview.md
+++ b/.project-docs/20-architecture/system-overview.md
@@ -25,7 +25,7 @@ from committed `ARRIVAL` facts, publishes a validated workbook, and records meta
 | `arr_web.job_trace` | Read-only programmatic trace from persisted run/attempt/delivery/version/outbox facts |
 | `monthly_reports.worker` | Dedicated leased outbox consumer with retry/dead-letter behavior |
 | `monthly_reports.repository` / `reporting` schema | ARRIVAL-derived snapshots, report versions, lineage, manifests and artifact identities |
-| `monthly_reports`, `channel_analytics`, `company_reports` | Deterministic downstream consumers of committed facts |
+| `monthly_reports`, `channel_analytics`, `company_reports` | Deterministic downstream consumers of committed facts; company reports build official XLSX files in Python/openpyxl inside Web |
 | Web + Caddy Compose | Web-owned login/session boundary behind Caddy HTTPS; no browser-native Basic Auth and no MCP service |

 ## Important Boundaries
@@ -52,4 +52,4 @@ from committed `ARRIVAL` facts, publishes a validated workbook, and records meta

 ## Last Updated

-2026-07-31
+2026-08-03
--- a/.project-docs/30-worklog/current-state.md
+++ b/.project-docs/30-worklog/current-state.md
@@ -13,8 +13,19 @@ blocked. A not-yet-ended period keeps its fixed C/O cutoff and must be rerun aft
 workbook needs those facts. Duplicate publication of the same semantic snapshot is idempotent: the first validated
 archive/result pair remains authoritative even if a retry rebuilds different XLSX bytes.

+Company-channel XLSX generation is now Web-container deployable without the private `@oai/artifact-tool` npm package:
+`company_reports.publishing.ArtifactToolBuilder` builds and reopens workbooks with Python/openpyxl, validates sheet
+names/headers/row counts/no-formulas, and treats blank Excel cells as business-empty strings. Node/artifact-tool remains
+only a monthly-worker packaging concern.
+
 ## Completed On 2026-08-03

+- Removed the private npm dependency from the company-channel report deployment path after CentOS Docker build failed
+  with `@oai/artifact-tool` 404. The company workbook builder now uses Python/openpyxl inside Web, keeps formula-injection
+  text escaping, produces no preview PNGs, and validates regenerated workbooks after saving. `compose.yaml` starts Web
+  with `--enable-company-reports`; HTTP/IP test overrides must keep that flag while omitting `--secure-cookies`.
+  Focused company-report and deployment-entrypoint tests pass 19/19. No database migration or live server deployment was
+  performed from this workstation.
 - Made the mobile H5 dashboard publicly readable without weakening the desktop/operator boundary. Anonymous users can
  load `/h5`, its H5 assets and purpose-built `/api/public/h5/months` plus `/api/public/h5/analytics` aggregate routes;
  the public projection omits source hashes and operational metadata. Generic analytics, legacy H5 APIs, desktop pages,
@@ -439,9 +450,10 @@ archive/result pair remains authoritative even if a retry rebuilds different XLS
  detached and are not reboot-persistent.
 - The latest operator-selected Web credentials were rotated on 2026-07-31, but the password still matches the username.
  Rotate it again to a distinct high-entropy value in Keychain, followed by one controlled Web restart.
- The workstation runs Web and worker as separate processes. The checked-in Compose image intentionally does not claim
-  to run the worker because it does not package the workstation-only artifact-tool module; a production image/process
-  manager must supply Node/artifact-tool and the shared output volume before enabling that service.
+- The workstation runs Web and worker as separate processes. The checked-in Compose image now supports company-channel
+  XLSX generation through Python/openpyxl in Web, but intentionally does not claim to run the monthly worker because it
+  does not package the workstation-only monthly artifact-tool module; a production image/process manager must supply
+  Node/artifact-tool and the shared output volume before enabling that monthly service.
 - A formally controlled no-PII server acceptance run remains appropriate after that deployment packaging is complete.
 - ARR2.0 now has Git metadata; `main` tracks `origin/main`. Runtime credential values remain outside Git and project
  files.
--- a/.project-docs/30-worklog/task-history.md
+++ b/.project-docs/30-worklog/task-history.md
@@ -4,6 +4,7 @@

 | Date | Task | Outcome | Docs Updated |
 |---|---|---|---|
+| 2026-08-03 | Make company-report XLSX generation deploy without private npm | Replaced the company-report builder's Node/private `@oai/artifact-tool` runtime dependency with Python/openpyxl workbook generation and self-validation, removed the private package dependency, enabled `--enable-company-reports` in Compose Web, and documented that only the monthly worker still needs Node/artifact-tool packaging. Focused company-report and deployment-entrypoint tests pass 19/19; no migration or live deployment was performed | Current state/history, architecture, deployment evidence/index, stale item, runbooks |
 | 2026-08-03 | Execute controlled fix and live-accept 2026-08 `01-10` company report | With explicit confirmation, stopped only the stale PID 11176 and started new listener PID 54127 through the existing Keychain-backed launcher. One authorized job `05cc547d…` succeeded 5/5 with row counts `54/18/7/1/15`, captured active Booking batch-7 source metadata, reused the existing version/artifact identities, and passed five HTTP download/hash checks. Logout and temporary-file cleanup completed; no Booking/Finance source or fact mutation occurred | Current state, runtime evidence/index, stale item, commitments, scoped planning record |
 | 2026-08-03 | Diagnose the latest 2026-08 `01-10` official-Excel save failure | Read-only evidence confirms newest job `087dceca...` built all five companies (`54/18/7/1/15`) and failed only at publish. Port 8766 is still PID 11176 from 2026-08-02, older than the semantic-reuse publisher fix; the earlier successful five-file archive/result/current set remains hash-consistent and intact. The launcher preflight is ready and six publisher tests pass. Repair is an exact controlled listener replacement followed by one authorized rerun; no restart, report write or business-data mutation was performed | Current state, runtime evidence/index, stale item, scoped planning record |
 | 2026-08-03 | Check whether company-report retries show reused-file identity | Confirmed the publisher can reuse an existing archive/result pair, but the outcome, job API and frontend expose only success/version/download; users cannot see that the file was reused or which prior artifact supplied it. No code or business-data change was made | Current state, retry-semantics evidence/index |
--- a/.project-docs/50-evidence/evidence-index.md
+++ b/.project-docs/50-evidence/evidence-index.md
@@ -4,6 +4,7 @@ Use this index for searchable, traceable evidence records.

 | Date | Topic | Status | Source | Detail |
 |---|---|---|---|---|
+| 2026-08-03 | Company-report openpyxl builder for deployment | Implemented; focused deployment checks pass | [Evidence topic](topics/2026-08-03-company-report-openpyxl-builder.md) | CentOS Docker build failed because public npm cannot install private `@oai/artifact-tool`. Company-report XLSX generation now runs through Python/openpyxl in Web, while monthly worker packaging remains the only Node/artifact-tool concern. Focused company-report/deployment tests pass 19/19. |
 | 2026-08-03 | Booking source and company-report retry semantics | Source contract confirmed; reuse visibility gap identified; live acceptance pending restart | [Evidence topic](topics/2026-08-03-company-report-retry-semantics.md) | Byte-identical XLSX uploads reuse the activated source; same rows with different file bytes are new drafts. Same report snapshots reuse complete publication pairs, changed Finance/Booking pins create new versions, and an activated subset changes Booking detail coverage while retaining Finance rows. The current API/UI do not expose whether a retry reused an existing artifact. |
 | 2026-08-03 | Company-report retry after reported 8766 restart | Resolved by controlled listener replacement and live 5/5 rerun | [Evidence topic](topics/2026-08-03-company-source-runtime-diagnosis.md) | PID 11176 was replaced by PID 54127. Job `05cc547d…` succeeded all five August `01-10` companies, reused the prior version/artifact identities, and all five authenticated downloads returned hash-matching 200 responses. No Booking/Finance source or fact changed. |
 | 2026-08-03 | Remove redundant company-report Excel provenance module | Implemented; Web/company checks pass | [Evidence topic](topics/2026-08-03-company-report-status-copy-fix.md) | The job-detail source card and history source column are removed because reports consume the Booking database snapshot; upload/review source UI and server-side provenance remain available. |
--- a/.project-docs/50-evidence/topics/2026-08-03-company-report-openpyxl-builder.md
+++ b/.project-docs/50-evidence/topics/2026-08-03-company-report-openpyxl-builder.md
@@ -0,0 +1,33 @@
+# Company-Report Openpyxl Builder
+
+Date: 2026-08-03
+
+## Finding
+
+The CentOS test-server Docker build failed at `npm --prefix company_reports/xlsx install` because
+`@oai/artifact-tool@2.8.33` is not available from the public npm registry. This is a packaging/runtime dependency
+failure, not a database, migration or Docker memory issue.
+
+## Change
+
+- `company_reports.publishing.ArtifactToolBuilder` now builds official company-channel workbooks with Python/openpyxl.
+- The builder writes the three expected sheets, preserves the existing headers/styles, escapes text that could be
+  interpreted as formulas, reopens the saved workbook and validates sheet names, dimensions, headers, row values and
+  zero formula cells.
+- Blank cells read back from Excel as `None` are normalized to the business-empty string during validation.
+- `company_reports/xlsx/package.json` no longer declares the private `@oai/artifact-tool` dependency.
+- `compose.yaml` enables `--enable-company-reports` for Web. IP/HTTP test overrides should keep that flag but omit
+  `--secure-cookies`.
+
+## Verification
+
+- Watched the new builder test fail against the old Node/private-runtime implementation with
+  `BuildError('the XLSX builder runtime is unavailable')`.
+- Focused verification passed:
+  `python -m unittest tests.test_company_reports_publishing tests.test_company_reports_integration tests.test_company_reports_acceptance tests.test_company_reports_service tests.test_deployment_entrypoints`
+  with 19 tests passing.
+
+## Remaining Boundaries
+
+The monthly worker still uses its separate Node/artifact-tool workbook builder. This change makes company-channel detail
+Excel generation deployable in the Web image; it does not package or supervise the monthly worker.
--- a/.project-docs/90-maintenance/stale-items.md
+++ b/.project-docs/90-maintenance/stale-items.md
@@ -16,7 +16,7 @@
 | 2026-07-30 | `booking_test` current Finance projection | The earlier 417-row snapshot included accepted run `mvp-v1-fixture-20260727` from `synthetic.xml`/`local_fixture`. A 2026-07-31 14:17 read-only company-report recheck found 986 current supported-company facts, so the old 416/417 remediation target is no longer a complete description of current Finance state | Re-audit current daily-version pins and source provenance before any fixture retirement; require explicit authorization for version changes, then verify the clean target and watermark |
 | 2026-07-30 | Channel BI refresh lifecycle | Resolved 2026-08-03. Desktop and public H5 now check selected-month metadata every five seconds while visible and reload full analytics only after `updated_at` changes; hidden views pause and transient failures preserve the last good snapshot | Refresh the browser once to load the new static assets, then observe the next authorized publication as a live acceptance check |
 | 2026-07-30 | Channel BI KPI label | The card labeled `公司数` renders worksheet-level `channel_count`; LianTai GROUP/FIT are two channels, so six does not mean six companies | Decide whether to relabel it `渠道/子表数` or implement an explicit five-company aggregation |
-| 2026-07-30 | Production worker packaging | Local Web/worker separation is live, but the checked-in Compose image does not contain the workstation-only Node/artifact-tool runtime required by the XLSX builder | Package an approved builder runtime and shared output volume before adding/enabling the managed production worker service |
+| 2026-07-30 | Production monthly-worker packaging | Local Web/worker separation is live, and company-report XLSX generation now runs in Web through Python/openpyxl. The checked-in Compose image still does not contain the workstation-only Node/artifact-tool runtime required by the monthly workbook builder | Package an approved monthly builder runtime and shared output volume before adding/enabling the managed production monthly-worker service |

 ## Superseded For ARR2.0