OASBP Evaluation Tool

日本語版はこちら

A self-hosted tool that classifies and visualizes an employee's organizational adaptation state along two axes: internal resource state (the Sufficiency/Deficiency axis) and the form of response to organizational boundaries (the Acceptance/Resistance axis), based on a framework called OASBP (Organizational Adaptation State Bi-axial Principle). It also visualizes the gap between self-assessment and supervisor assessment.

The theoretical framework (OASBP) itself is based on a paper outside this repository, but the measurement items, scoring method, partition settings, and prescriptive guidance are not defined by that theory — they are entirely this tool's own design.

• System specification: OASBP_System_Specification.md
• Design notes (scoring logic, DB design, access-control rationale — the current design, always in sync with the code): DESIGN_NOTES.md
• History of design changes and bugs found during implementation: DESIGN_HISTORY.md

(Note: the three documents above are in Japanese only. The application UI itself is bilingual — see "Architecture" below.)

This is a personal tool, built and open-sourced for my own use and shared in case it's useful to others. I'm not providing ongoing support or an SLA. Bug reports are welcome via Issues, but I can't promise a response time. It's designed to be run self-hosted, at your own responsibility (see "Architecture" below).

Deploying directly from the badge above tracks this repository's main branch, meaning future pushes to this repo will automatically propagate to your deployment. If you'd rather control that yourself, fork this repository first and deploy from your fork.

• BYODB (Bring Your Own Database): each organization brings its own Supabase project. The developer never has access to any organization's evaluation data. Conversely, securing, backing up, and managing access to your own Supabase project is your responsibility. Given this tool handles sensitive personnel evaluation data, manage your Service Role key carefully and back up regularly.
• Frontend: Streamlit. A single server-side process connects to Supabase using only the Service Role key; end users never have a direct path to Supabase (see DESIGN_NOTES.md §4.2).
• Questions, weights, partition granularity, and prescriptive text are all built via external CSV import — nothing is hardcoded (§2.2).
• The UI chrome is bilingual (Japanese/English), switchable at any time from the sidebar. Adding a new language is as simple as adding a file under lang/ (DESIGN_NOTES.md §4.8). Master data itself (question text, classification labels, etc.) is out of scope for translation — it's shown as entered by the administrator.

1. Create a Supabase project and run db/schema.sql in the SQL Editor.
2. Copy .streamlit/secrets.toml.example to .streamlit/secrets.toml and fill in SUPABASE_URL / SUPABASE_SERVICE_KEY (the Service Role key) with your actual values. Do not commit secrets.toml (already excluded via .gitignore).
3. pip install -r requirements.txt (or pip install -r requirements-dev.txt if you also want to run the tests — it just adds pytest/pglast on top of the same application dependencies).
4. streamlit run app.py
5. On first launch you'll see the admin account setup screen. After that, the regular login screen becomes the entry point.

Until the question/weight/partition masters are imported into the DB, the app runs on the sample CSVs under examples/ (core/config.get_master()). Upload production data from the "Master Import" tab on the admin dashboard to replace them.

This section doesn't apply to a fresh setup (above) — db/schema.sql always represents the latest, complete schema, so running it once is enough. It only matters for an already-running deployment picking up new code, which may also need a matching DB update.

1. Update the code (git pull, etc.)
2. Run the following in the Supabase SQL Editor to see how far the DB has caught up:

   select version from schema_migrations order by version;

   (If this table doesn't exist yet, no migration has been applied.)
3. Look under db/migrations/ and run, in ascending order, any files whose number isn't in the result above. See db/migrations/README.md for how to use each file.

If a code change doesn't come with a new migration file (i.e. it doesn't touch the DB schema), this step isn't needed.

• Admin: register staff (individually or via CSV), link supervisors to staff, reset passwords, import master data, create/close evaluation cycles, view the organization-wide distribution map.
• Supervisor: select a staff member and submit an evaluation; after the cycle closes, view the composite value plus your own shadow.
• Staff: submit a self-evaluation; after the cycle closes, view the composite value plus your own shadow.

No role can see the other party's (supervisor ↔ staff) raw responses. What's visible is only your own submitted data and the organization-wide composite value (DESIGN_NOTES.md §2.5).

python -m pytest tests/ -v

221 tests as of this writing (the exact count will drift — check the output of the command above for the current number). Full flows — first-time setup → login → evaluation → cycle close → viewing results, admin features (staff registration/CSV import, master import, organization distribution map, activity log), and English-locale rendering (tests/test_i18n.py) — are verified through the real code paths using streamlit.testing.v1.AppTest (a headless UI test harness that runs the actual Streamlit execution engine). See tests/test_app.py, tests/test_admin_ui.py, tests/test_activity_log.py, tests/test_i18n.py.

DB access is replaced with an in-memory fake Supabase client (tests/fakes.py), so no real Supabase connection is required to run the suite.

db/schema.sql and db/migrations/*.sql are syntax-checked against the real PostgreSQL parser (pglast) via an automated test in tests/test_schema_sql.py (included in pytest tests/).

• See DESIGN_NOTES.md §2.1 for how multiple supervisors' evaluations are aggregated, and §4.2 for the rationale behind the RLS policy design.
• Bugs found (and fixed) during implementation and real-database testing — timezone mismatches, an unconditional DELETE being rejected, double-encoding of jsonb columns, why config.get_master() must never raise, crash prevention when the schema hasn't been applied yet, the None fallback in get_open_cycle(), and more — are collected in DESIGN_HISTORY.md under "M1". Read that before touching this area.

Initial sample data lives under examples/ (questions.csv, question_points.csv, axis_role_weights.csv, partitions_zones.csv). See DESIGN_NOTES.md §3 for what each column means.

MIT License