expand manual prospect intelligence workflows
This commit is contained in:
Marco0300
@@ -1,16 +1,26 @@
|
||||
# Prospect Intelligence Platform
|
||||
|
||||
A safety-first MVP vertical slice for evidence-led prospect discovery and qualification. It stores normalized businesses, scores transparent opportunity signals, preserves reviewable fields, and blocks suppressed records. **Automated outreach is disabled.**
|
||||
A safety-first Phase 3 vertical slice for **manual**, evidence-led prospect qualification. It stores tenant-owned businesses and their child intelligence records, keeps provenance with each evidence item, supports a review pipeline, and records operationally relevant changes. **Automated discovery, DNS/website scanning, and outreach are not part of this release. Automated outreach is disabled.**
|
||||
|
||||
## Included
|
||||
|
||||
- Dependency-free Python/SQLite API under `apps/api`.
|
||||
- Normalization, conservative website classification, exact deduplication, versioned scoring, suppression checks.
|
||||
- JSON API under `/api/v1` for health, dashboard summary, businesses, suppression, and CSV-style import preview.
|
||||
- Responsive static dashboard under `apps/web` with explorer filters, evidence/freshness labels, detail review, manual intake, and browser-only CSV preview.
|
||||
- Tenant-scoped business detail APIs with child intelligence/evidence records, provenance fields, notes, pipeline state, and audit history.
|
||||
- Server-side normalization, conservative website classification, exact deduplication, versioned scoring, and suppression checks.
|
||||
- Bounded list pagination and server-side filters so a tenant cannot request an unbounded prospect collection.
|
||||
- Responsive static dashboard under `apps/web` with authenticated explorer filters, paginated results, detail review, manual intake, notes/pipeline context, evidence provenance, and browser-only CSV preview.
|
||||
- Docker Compose runtime with non-root containers, read-only filesystems, health checks, and a named SQLite data volume.
|
||||
- Browser authentication with server-side sessions and an optional first-run admin bootstrap.
|
||||
- Security and operations guidance in `docs/`.
|
||||
|
||||
## Phase 3 workflow
|
||||
|
||||
1. A permitted workspace member manually creates or reviews a prospect.
|
||||
2. The business detail response is the aggregate record for that tenant; related intelligence/evidence rows are returned only through the tenant-scoped detail surface.
|
||||
3. Each manually entered intelligence item should retain its source/provenance (for example, source label or URL, observed value, and captured/verified time). Missing provenance is a data-quality limitation, not permission to infer facts.
|
||||
4. Members use the pipeline state and notes to coordinate human review. A state change or note is an application event and is included in the record's audit/activity history where exposed by the API.
|
||||
5. Suppression remains a hard safety boundary. Suppressed or unreviewed records must not be treated as eligible for contact.
|
||||
|
||||
The API applies the organization/tenant boundary server-side to list, detail, child-record, notes, pipeline, and audit reads and writes. Clients must use the returned pagination metadata and follow `next`/`previous` links or tokens rather than assuming that one response contains the whole tenant dataset. See `apps/api/README.md` for the route contract and limits.
|
||||
|
||||
## Run locally
|
||||
|
||||
@@ -33,12 +43,15 @@ Open `http://127.0.0.1:8080`. Set `window.API_BASE` in the browser console to `h
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/api/v1/health/live
|
||||
curl http://127.0.0.1:8000/api/v1/businesses
|
||||
curl 'http://127.0.0.1:8000/api/v1/businesses?page=1&page_size=25&pipeline_stage=new'
|
||||
curl http://127.0.0.1:8000/api/v1/businesses/1
|
||||
curl -X POST http://127.0.0.1:8000/api/v1/businesses \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"name":"Example Plumbing","website":"https://example.invalid","email":"info@example.invalid","phone":"+27 21 555 0100"}'
|
||||
```
|
||||
|
||||
The protected calls require the authenticated session cookie. Exact child-record, notes, pipeline, and audit routes are documented in `apps/api/README.md` and are never cross-tenant addressable by changing an ID.
|
||||
|
||||
## Compose
|
||||
|
||||
```bash
|
||||
@@ -54,13 +67,15 @@ Compose passes the optional `BOOTSTRAP_ADMIN_EMAIL` and `BOOTSTRAP_ADMIN_PASSWOR
|
||||
|
||||
Authenticated browser requests use a server-side session cookie; login creates a session and logout invalidates it. The liveness endpoints (`GET /api/v1/health/live` and `GET /healthz`) intentionally remain unauthenticated so Docker, ingress, and monitoring health checks can use them. Authentication is not a substitute for tenant/authorization checks: protected routes must enforce the session and organization boundary server-side.
|
||||
|
||||
The initial pilot still omits Postgres, Redis, Celery, external discovery adapters, DNS/HTTP scanning, and outbound messaging. Before production use, complete the production security gates described in `docs/SECURITY.md`, including Argon2id password hashing, MFA for administrator accounts, TLS, CSRF protection, rate limiting, audit logging, migrations, SSRF-safe scanners, approved source registry, queue idempotency, and tested backups/restores.
|
||||
## Explicit non-goals and remaining limitations
|
||||
|
||||
This Phase 3 release still has no automated discovery, DNS resolution, website/HTTP scanning, enrichment scheduler, external source adapter, email/SMS sender, or outreach endpoint. CSV remains a browser/API preview flow and does not silently persist rows. SQLite and the named local volume are suitable for the pilot only; there is no production migration runner, queue, or tested backup/restore command. The development password fallback is PBKDF2 rather than production Argon2id. Before production, complete the gates in `docs/SECURITY.md` and `docs/OPERATIONS.md`, including MFA, TLS, CSRF protection, rate limiting, durable audit retention, migrations, approved source policy, SSRF-safe fetching if a future scanner is approved, and tested backups/restores.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -v -s apps/api/tests -t apps/api
|
||||
php -l /dev/null 2>/dev/null || true # no PHP application is used here
|
||||
python3 -m compileall -q apps/api apps/web
|
||||
git diff --check
|
||||
docker compose config --quiet
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user