
Business outcome
A sales team can import messy CSV data, trace every accepted or rejected row, manage sales records, and produce reports whose breakdowns always reconcile with the grand total.
Evidence
Layered domain, API, and UI tests; MySQL CI; static analysis; 25 documented defects; clean-room acceptance testing; and auditable import results.
Delivery scope
A similar system can include role-based access, workflow screens, integrations, migration and import rules, acceptance criteria, test evidence, deployment documentation, and staged production handoff.
sales-manager
A full-stack sales management web application built with Laravel (API) and Vue (SPA).



日本語版: README.ja.md
What this is
A portfolio project built to demonstrate two things: full-stack delivery with Laravel and Vue, and the quality practices that go around it — layered tests with PHPUnit and Vitest, CI, and written design documents.
It is a rebuild of an earlier project of mine, sales-report (Python, CLI, test-heavy), as a web application on the same domain. The feature set is deliberately small. The strength is meant to come from the architecture, the tests, and the documentation rather than from the number of features.
Screens
CSV import — you can trace what happened to every row
The result of importing 4 data rows. Rows 2 and 5 are the same line item (same date, store, product and unit price), so they are merged. Invalid rows are skipped with a row number and a reason — the import is never aborted as a whole.
Reporting only "2 imported / 1 error" would leave the user unable to tell where the remaining row went. So the input row count is shown alongside the result, and every imported line item reports which source rows it was built from. That makes the accounting — input rows = rows that contributed to an import + error rows — verifiable on screen (see DEF-024 in the defect log).

Summary report — the total always equals the sum of every breakdown

Sales list / Sales form


Features
Authentication — Laravel Sanctum (SPA, cookie based)
Sales CRUD — store, product, quantity and unit price (0 is a valid boundary value for both quantity and unit price)
CSV import — header validation, character encoding fallback (UTF-8 / Shift-JIS), per-row validation, merging of duplicate line items, and a per-row error report with reasons
Summary report — totals by store, product and date, where the grand total is guaranteed to equal the sum of each breakdown
Approach to quality
Architecture — write paths and use cases follow one consistent route: Controller (thin) → FormRequest → Serv
Need a secure internal operations system? My Secure Business Operations Portal & Workflow App service covers workflow design, role-aware screens, integrations, testing, deployment documentation, and staged handoff.
https://contra.com/s/eZLWvUYv-secure-business-operations-portal-and-workflow-app ice → Domain → Repository (interface). Adding a feature means adding a Service and an endpoint without disturbing what exists. Places where a layer is deliberately skipped (simple master-data reads) are documented as intentional exceptions in docs/design.md.
Test design — test conditions are derived from equivalence partitioning and boundary value analysis, and tracked in a condition-ID table (docs/test-design.md).
Layered tests — domain (PHPUnit unit), API (PHPUnit feature) and UI (Vitest). Exact counts are not quoted here because they move; the measured numbers live in the CI artifact
junit-php-*.Static analysis — Larastan (PHPStan) and vue-tsc. Some defects were only ever caught here, with every test green (see DEF-005 in the defect log).
CI — GitHub Actions runs a PHP version matrix on SQLite, a separate MySQL job, linting (Pint / ESLint), static analysis (Larastan level 6 / vue-tsc), and the frontend test and build. The MySQL job exists to close a real class of bug — a schema overflow that passes on SQLite and breaks on MySQL (DEF-010).
Coverage is measured but never used as a pass/fail gate. It is collected in CI and kept as an artifact, with no threshold gate. I hit "100% coverage with defects still present" on the previous project, so coverage is not treated as a proxy for quality here. Quality is carried by what the tests actually assert — boundaries, error paths and invariants.
Install and usage
Requirements
PHP 8.4+, Composer
Node.js 22+, npm (Vite 8 requires ^20.19 || >=22.12; CI verifies on 22)
Setup
Running in development
Open
http://localhost:8000 — not http://localhost:5173. This project uses laravel-vite-plugin: Laravel itself serves the SPA shell and Vite only serves assets and HMR during development. The API is therefore same-origin, and SANCTUM_STATEFUL_DOMAINS must match the host in APP_URL (see DEF-023).Seeded login:
test@example.com / password.Production build
Testing
Domain (unit) —
Money (all amounts are decimal; float is never used), SalesAggregator (the invariant that the grand total equals the sum of every breakdown), CsvImporter (boundaries, invalid values, duplicate merging, encoding fallback — see docs/test-design.md)API (feature) — authentication, sales CRUD, CSV import, reporting, master data
UI (component) — Vitest + @vue/test-utils for login, list, import result and report
Design notes
All money is computed with
Brick\Math\BigDecimal — float is never used. The display contract is always 2 decimal places, ROUND_HALF_UP (app/Domain/Money.php).CSV import separates parsing/validation (
CsvImporter) from persistence (ImportService). The former is pure logic with no database dependency, so it can be unit tested quickly and exhaustively.The merge key for duplicate line items is date + store + product + unit price — a deliberate decision so that rows with different unit prices are never merged (ADR-001).
Each sale stores the unit price as a snapshot at the time of entry, so changing a product's master price does not rewrite historical amounts.
Repositories are abstracted behind interfaces and bound to their Eloquent implementations in
AppServiceProvider. The limits of that abstraction are stated explicitly in the design document rather than overclaimed.Authentication is Sanctum SPA (cookie based) (ADR-003).
Documents
These are written in Japanese. The tables, diagrams, code identifiers and file paths are readable as-is, and machine translation handles the prose well.
Document Contents docs/design.md Architecture (layering, extensibility) docs/db-design.md Database design (ER diagram, table definitions) docs/api-design.md API design (endpoint specifications) docs/screen-design.md Screen design (navigation, component structure) docs/test-design.md Test design (condition-ID table) docs/adr/ Architecture Decision Records docs/defects.md Defect log — only defects actually found during development docs/manual-verification.md Manual verification record (procedures and measured results for what cannot be automated, e.g. CSRF)
On the defect log
docs/defects.md is the document I would point at first. It records every defect found during development (DEF-001 to DEF-025), how it was detected, and what was changed. It also classifies the recurring ones into three types and states the countermeasure for each:
Type A — a document or test name claims more than the implementation guarantees. Countermeasure:
DocumentationConsistencyTest, which mechanically detects drift between documents and code.Type B — the test is green, but green for a different reason than claimed. Countermeasure: verify discriminating power by removing the guarded implementation and confirming the test fails, then record that check.
Type C — the premise of the test environment differs from reality. Countermeasure: a clean-room acceptance run before release.
Type C is the one worth reading. With every automated test green and four rounds of external review passed, the application returned 500 on every request in a real browser (DEF-023). The whole test environment had been built on a premise that does not occur in production, so no amount of additional tests could have found it. It was caught only by cloning the repository into a fresh directory and following the README.
Possible extensions
The scope is intentionally small, but the layering is designed so the following can be added without restructuring (see docs/design.md).
Budget vs actual comparison
User roles and permissions (store manager, read-only, and so on)
Additional aggregation axes (weekly, by category) and a dashboard
A mobile client on the same API (API-first; the
User model already supports HasApiTokens)Ingestion from external SaaS sources beyond CSV
Known limitations
There is no single-record endpoint (
GET /api/sales/{id}). The edit screen fetches the list and looks up the ID, so a record outside the first page cannot be edited. In that case the form is not rendered with default values and no save is performed — a deliberate safe degradation so existing data is never overwritten with defaults (verified in SalesFormView.test.ts). Adding the endpoint resolves this.The list screen has no pagination UI. The API returns
meta, but there is no way to reach page 2 from the UI (this is also the cause of the edit constraint above).Importing the same CSV twice double-counts. Merging happens within a single file only; there is no detection of already-imported files (by hash or otherwise) and no uniqueness constraint on line items. A production system would need idempotency here.
Authorization is "any authenticated user may do anything" (every
FormRequest returns true from authorize()). This assumes a single tenant and a single role; separation of privileges is listed above as an extension.Encoding handling on CSV import is a fallback, not detection.
mb_convert_encoding always substitutes unknown bytes with safe characters, so a genuinely corrupted file may surface as a header mismatch rather than an exception (see DEF-003).The summary report loads all line items into memory. This does not scale; a production-sized dataset would need SQL-side aggregation or chunking.
CSV import inserts line items one row at a time. Store and product master resolution is batched so it does not grow with row count (
resolveIdsByNames), but the line item inserts themselves are not. Bulk inserts would be needed for large files.Development
PHP 8.4+, Node.js 22+. See
composer.json and package.json for dependencies.License
MIT
0 likes · 2 views · Aug 26, 2026
Built a reliable sales operations portal with auditable CSV imports, reconciled reporting, layered tests, CI, and documented defect evidence.