property-portal-template — Next.js 后台模板

SHA-256: e5866287980dcad72f09dac165cfbb1801985c4cdc128d79eb3b09edb2cb833f

2026-10-02T15:44:22.870Z

# Property Portal Template

[Deploy on Vercel](https://vercel.com/new/clone?repository-url=https://github.com/frankxai/property-portal-template) ·
[Use this template](https://github.com/frankxai/property-portal-template/generate) ·
[Download ZIP](https://github.com/frankxai/property-portal-template/archive/refs/heads/main.zip) ·
[Operating System Template](https://github.com/frankxai/property-os-template)

Vercel/Next.js template for a premium rental-property website, renter self-service portal, inquiry capture, support intake, owner dashboard, listing draft admin, and owner-controlled agent team.

## Principal owner workspace (v0.3)

The `/` workspace now runs a shared, deterministic investment engine: monthly amortization, scheduled refinancing, annual cash flow, pre-tax IRR/NPV and coordinated portfolio downside. It includes source provenance, document-review status, structured Kleinanzeigen reference intake, an adviser brief and category-specific tenant case drafts.

The public workspace begins with **fictional examples**. Inputs stay in the browser session; export the model JSON to retain it or import an authorized model pack. Editing a sample preserves its example lineage. Owner/admin records retain their existing authentication boundary and are not synchronized into this public workspace.

`/api/mcp` exposes three real, stateless official-SDK tools: `underwrite_property`, `stress_property_portfolio`, and `get_property_review_playbook`. The endpoint only calculates caller-supplied assumptions and returns public review procedures. See [ChatGPT setup](docs/chatgpt-connection.md), [financial methodology](docs/investment-model.md), and [workspace contract](docs/principal-workspace.md).

```bash
npm run validate
npm run typecheck
npm run build
npm run principal:smoke
npm run auth:smoke
```

A Kleinanzeigen reference is not a live account connection. Outbound OpenImmo delivery still requires the provider partnership, issued credentials and an approved test. No scraping, messaging or publication is added.

## Who This Is For

- property owners who want a premium renter-facing web experience
- agencies installing modern property websites and support workflows
- implementers who pair Vercel frontends with GitHub-approved property knowledge
- community builders who want a free, safe starting point for AI-assisted property operations

This is the portal half of Property Intelligence OS. Pair it with `property-os-template` for agent roles, MCP boundaries, owner runbooks, partner offer design, the schema-valid install planner, and Railway control-plane architecture.

## Routes

- `/`: operating dashboard entry point
- `/properties/[slug]`: public property page
- `/properties/[slug]/inquire`: inquiry capture
- `/stay/[accessCode]`: renter self-service portal
- `/support`: support and maintenance intake
- `/owner`: owner dashboard
- `/admin/setup`: owner setup checklist and missing-fact workflow
- `/admin/implementation`: installation readiness, agent architecture, production gates, and partner offer ladder
- `/admin/runtime`: runtime storage, notification, capability, and queue posture
- `/admin/notifications`: signed delivery, retry, fallback, and owner acknowledgement ledger
- `/admin/listings`: listing draft studio
- `/admin/integrations`: approved/manual/planned integration cockpit
- `/admin/control-center`: specialist missions, authority boundary, runtime posture, lifecycle, and outcome scorecard
- `/admin/agent-workbench`: approved-evidence, structured-draft, immutable-proof, and owner-review workflow
- `/admin/agent-runs`: owner-reviewed agent run ledger
- `/admin/ops`: server-timestamped weekly review, metric evidence, operating cadence, and release gates

## Setup

```bash
npm install
npm run validate
npm run agent:dry-run
npm run typecheck
npm run build
npm run smoke
npm run auth:smoke
npm run identity:smoke
npm run notification:smoke
npm run weekly:smoke
npm run weekly:visual
npm run visual:qa
npm run audit
npm run install:proof
npm run auth:hash -- "private owner passcode"
npm run db:rls:smoke
npm run identity:db:smoke
```

## Data Model

The starter uses repo content in `data/properties.ts` for approved public facts. Runtime submissions may use demo memory only in development or an explicit loopback test process. Production intake requires `DATABASE_URL`, records the submission and approval atomically, and returns `503` before notification when durable storage is unavailable. Send only sanitized summaries to GitHub issues or notification workers.

The first portal schema lives in `db/schema.sql`. It separates organizations, properties, units, knowledge articles, listing drafts, inquiries, support tickets, notifications, weekly owner reviews, immutable metric observations, approvals, portal agent runs, agent missions, transition proposals, approval receipts, controlled transitions, and audit events. Apply `db/rls.sql` after the schema to enable tenant-scoped row-level security, then use `db/seed-sample.sql` for a public-safe local production-mode smoke seed.

Production uses two tenant-isolated logical databases and separate runtime roles: this portal database on Vercel and the governed control-plane ledger on Railway. Never point both `DATABASE_URL` values at the same logical database; the authenticated MCP API is the boundary between them.

Runtime APIs:

- `/api/runtime/health`: environment, adapter, notification, and capability posture
- `/api/runtime/snapshot`: counts, recent demo queue items, audit posture, and production notes
- `/api/approved-evidence`: owner-authenticated, versioned evidence registration through MCP
- `/api/agent-drafts`: approved-evidence structured draft through MCP; no local fallback
- `/api/agent-run-reviews`: owner accept, revise, or reject outcome through MCP; no content apply

Production database order for a fresh install:

1. Apply `db/schema.sql`.
2. Apply `db/rls.sql`.
3. Seed with `db/seed-sample.sql` or a private owner seed.
4. Set `PROPERTY_OS_ORG_ID` to the seeded organization id.
5. Verify `/admin/runtime` in the deployed preview before real renter data.

Existing v0.2 portal databases apply `db/002-notification-lifecycle.sql`, `db/003-weekly-owner-review.sql`, and the transactional `db/004-tenant-oidc.sql` in order, then rerun `db/rls.sql` and the live database smokes before enabling production workflows.

## Owner Identity

Production must explicitly set `PROPERTY_OS_AUTH_MODE`; absent, unsupported, or incomplete modes lock owner access.

- `static-private-pilot` is the private one-owner path with a high-entropy signing secret and passcode digest.
- `oidc` is the agency path with pre-bound organization membership, signed ID-token verification against pinned JWKS, fixed server-backed sessions, PostgreSQL rate limits, role capabilities, and atomic member/session revocation.

The portal accepts no global owner API bearer. Machine-to-machine agent work crosses the separately authenticated MCP boundary. See `docs/owner-auth.md` for endpoint configuration, reviewed member binding, database role constraints, and deployed acceptance evidence.

## Implementation Cockpit

The route `/admin/implementation` turns the template into an installable product surface. It scores the current install across approved property knowledge, premium portal readiness, runtime storage, Codex/Claude/MCP agent substrate, listing operations, owner notifications, and business packaging.

The API route `/api/implementation/readiness` exposes the same contract for automation, partner audits, and future onboarding flows. It intentionally reports missing environment variables and blocked v1 actions instead of pretending the demo template is production-persistent.

## Agent Control Center

The protected route `/admin/control-center` converts the agent team into an operational surface: ten narrow specialist mandates, six mission states, an explicit authority contract, runtime proof counts, and owner/renter/property/partner success targets. `/api/agent-missions` records a draft-only mission with one property scope, objective, success metric, owner action, persistence receipt, notification receipt, and audit event.

When MCP is configured, the portal routes missions, approved evidence, structured drafts, and owner review outcomes through that single authenticated control plane. Governed draft routes never fall back to the portal database, and the legacy manual run ledger is disabled in connected or production mode. The paired `property-os-template` persists these records under forced RLS and implements proposal, owner decision, single-use receipt, exact internal apply, audit, and undo transactionally. External publication, messaging, dispatch, applicant decisions, access disclosure, pricing, and availability remain blocked.

The protected `/admin/agent-workbench` is the owner-facing four-stage loop: record a bounded mission, register exact approved evidence, generate a schema-checked draft, and record accept/revise/reject. The page exposes model, prompt, evidence, output hash, risk, latency, token, and no-action receipts. A review never applies or sends the draft.

## Self-Service Install Proof

The route `/admin/setup` includes the install proof cockpit: proof score, runtime posture, required commands, phase gates, missing production env names, owner approval boundaries, and blocked v1 actions.

The protected API route `/api/install/proof-packet` exposes the same evidence for partner audits and onboarding automation. The local command `npm run install:proof` prints a public-safe JSON proof packet that reports environment key names and configured booleans only; it does not print secret values.

Generate the upstream configuration packet in `property-os-template` with `npm run install:plan -- --config <public-safe-config.json>`, then attach its hashes and this portal's live proof packet to the handoff.

## Owner Notifications

Notifications use a durable tenant-scoped outbox and append-only event ledger. A separately authenticated worker sends HMAC-signed, sanitized webhooks, retries with bounded backoff, triggers the fallback route when urgent acknowledgement is late, and exposes evidence at `/admin/notifications`. See `docs/notification-lifecycle.md` and run `npm run notification:smoke` after the production build.

## Weekly Evidence

The protected `/admin/ops` workflow records one review per organization and UTC week, derives review duration and urgent acknowledgement from server evidence, accepts bounded FAQ and vacancy inputs, and stores five explicit `met`, `not-met`, or `unmeasured` observations. Completion is idempotent and performs no external action. See `docs/weekly-owner-review.md`.

## V1 Safety

- Static portal answers approved facts.
- Forms collect and sanitize demo submissions.
- Availability, rent, lease terms, refunds, urgent repairs, and private data require owner approval.
- No listing channel auto-posting in v1.

## Vercel

Deploy as a normal Next.js project or use the deploy button above after the repository is public. Use preview deployments for owner review before production.

The v0.3 release uses Next.js 16.3.5 and React 19.2.8. `sharp` and `postcss` are pinned to patched versions through npm overrides. Run the dependency audit in CI before deploying; the inherited v0.2 dependency lock is superseded by this release.

## v0 Path

Use `docs/v0-implementation-brief.md` as the v0 prompt brief for remixing the interface while preserving the safety model: approved facts, human approval, no automatic commitments, and operational dashboard density.

## Operating Docs

- `docs/operator-runbook.md`
- `docs/owner-auth.md`
- `docs/self-service-install.md`
- `docs/implementation-cockpit.md`
- `docs/runtime-adapter.md`
- `docs/portal-scene-brief.md`
- `docs/agent-control-center-spec.md`
- `docs/agent-workbench-spec.md`
- `docs/weekly-owner-review.md`
- `docs/product-roadmap.md`
- `docs/production-hardening.md`
- `docs/v0-implementation-brief.md`
- `docs/success-criteria.md`
- `docs/taste-standard.md`
- `docs/release-gate.md`

## Support Boundary

The public template can run as an explicit local demo, but production owner access fails closed. Do not use it with real renter data until the target database, selected auth mode, notifications, legal review, monitoring, and owner approval flows have deployment evidence.