gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

optimize docs

Browse Source
This commit is contained in:
thanhnv
2026-07-23 23:30:43 +07:00
parent a6c3a5d02f
commit 2ca1eabca9
7 changed files with 390 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+36 -148
View File
@@ -17,7 +17,7 @@ copy toàn bộ CASAN hoặc dựng lại project shell.
- [CASAN Project Shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md)
- [Requirements](#requirements)
- [Input for Flow](#input-for-flow)
- [Output for FLow](#output-for-flow)
- [Output for Flow](#output-for-flow)
- [Full AI-SDLC Flow](#full-ai-sdlc-flow)
- [Flow Steps](#flow-steps)
- [Flow Diagram](#flow-diagram)
@@ -28,7 +28,6 @@ copy toàn bộ CASAN hoặc dựng lại project shell.
- [AI-SDLC Usage Guide](#ai-sdlc-usage-guide)
- [Directory Structure](#directory-structure)
- [Directory Details](#directory-details)
- [OKR Web Application — Quick Start](#okr-web-application--quick-start)
## CASAN Quick Start
@@ -100,6 +99,15 @@ Mặc định production là `--mode enforce`. Chỉ dùng `--mode observe` cho
Nếu ứng dụng tự gọi LLM API qua backend riêng, ngoài Claude Code/Codex/Copilot,
luồng đó không tự động đi qua project hooks và cần adapter CASAN riêng.
Với project đã adopt CASAN theo mô hình cũ và đang chứa
`packages/casan-harness`, init nhận diện đây là vendored application thay vì
source hub:
- Không cần `--force`.
- Không xóa harness, scripts, workflow hoặc evidence cũ.
- Tự nâng cấp các block nằm giữa marker `CASAN_PROMPT_ENFORCEMENT_START/END`.
- Báo rõ file nào còn prose legacy ngoài marker cần review thủ công.
### 3. Hành vi chat theo client
| Client đã enable | Prompt đi qua CASAN | Onboarding bắt buộc |
@@ -143,9 +151,9 @@ Apply AI to the SDLC process to automate and optimize the creation of software p
## Input for Flow
- `apps/okr/domain/input/okr-requirement.md` — Raw requirements from customers
- `docs/technical_architecture.md` — Technical stack decisions and constraints
- `apps/okr/domain/input/change-request/` — Change requests (e.g., `change-0406.md`)
- `apps/<project-id>/domain/input/requirement.md` — project requirements
- `apps/<project-id>/domain/input/architecture.md` — architecture and constraints
- Project-owned input, reference, agent, and skill directories remain untouched
## Output for Flow
@@ -155,7 +163,7 @@ Apply AI to the SDLC process to automate and optimize the creation of software p
| **AI Agent Logs** | `docs/output/output_logs/` | Execution logs from AI agents |
| **SRS-Systems** | `docs/output/srs-systems/` | System-wide SRS (generated once during input clarification phase, not part of the main flow steps) |
| **Spec-Kit Artifacts** | `specs/[FEATURE_NAME]/` | Feature artifacts generated by Spec-Kit agents (`spec.md`, `plan.md`, `tasks.md`, contracts, checklists) |
| **Source Code** | `apps/okr/backend/` + `apps/okr/frontend/` | Application source code (NestJS backend + React frontend) |
| **Source Code** | Project-defined locations | CASAN does not impose an application framework or source layout |
---
@@ -280,7 +288,7 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
## AI-SDLC Usage Guide
1. **Adopt governance**: Run `casan init`, select the IDE clients, complete any trust/VSIX onboarding, then run `casan doctor`
2. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md`
2. **Prepare Input**: Place requirements and architecture under `apps/<project-id>/domain/input/`
3. **Configuration**: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
4. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/`
5. **Run AI Flow**: Invoke `casan.pipeline` to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
@@ -289,7 +297,7 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
- `docs/output/output_logs/` — AI agent execution logs
- `docs/output/srs-systems/` — System-wide SRS (generated once)
- `specs/[FEATURE_NAME]/` — Spec-Kit artifacts (`spec.md`, `plan.md`, `tasks.md`, etc.)
- `apps/okr/backend/` + `apps/okr/frontend/` — Source code (NestJS backend + React frontend)
- Source code remains in the locations defined by the adopted project
---
@@ -329,11 +337,16 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
│ ├── bd-ipa-template.md
│ └── dd-ipa-template.md
│
├── apps/
│ └── <project-id>/domain/ # Per-project CASAN domain pack
│ ├── input/
│ │ ├── requirement.md # Project requirements
│ │ └── architecture.md # Architecture and constraints
│ ├── corpus/ # Benign/red-team evaluation corpus
│ ├── golden-runs/ # Golden outputs for drift checks
│ └── traceability-map.json
│
├── docs/
│ ├── input/ # Input for the entire AI-SDLC flow
│ ├── change-request/ # Change requests
│ │ └── okr-requirement.md # Raw requirements from customers
│ ├── technical_architecture.md # Technical stack decisions and constraints
│ └── output/ # Output of the AI-SDLC process
│ ├── ipa-docs/ # IPA documents
│ │ ├── srs/ # SRS documents per module
@@ -344,21 +357,9 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
│ ├── output_logs/ # AI agent execution logs (per feature)
│ └── srs-systems/ # System-wide SRS (generated once, pre-flow)
│
├── specs/ # Spec-Kit feature artifacts (per feature)
│ ├── 001-access-authentication/
│ ├── 002-workspace-dashboard/
│ ├── 003-objective-keyresult/
│ └── 004-review-collaboration/
│
├── e2e/ # End-to-end tests (Playwright)
│ └── auth/ # Auth E2E tests
│
├── apps/okr/frontend/ # React + Vite SPA (source code)
│
├── apps/okr/backend/ # NestJS API service (source code)
│
├── docker/ # Docker utilities
└── docker-compose.yml # Docker Compose orchestration
├── specs/ # Optional Spec-Kit feature artifacts
├── <existing-source-directories>/ # Project-owned; CASAN init preserves them
└── <existing-ci-and-tooling>/ # Project-owned; CASAN init preserves them
```
### Directory Details
@@ -381,15 +382,10 @@ Spec-Kit configuration directory. Stores project-wide principles, scripts, and a
- **`scripts/`** — Utility scripts in `bash/` and `powershell/` for automation tasks.
- **`templates/`** — Format templates used by agents to generate artifacts. Includes Spec-Kit templates (`spec-template.md`, `plan-template.md`, `tasks-template.md`, `constitution-template.md`, `checklist-template.md`, `agent-file-template.md`) and IPA templates (`srs-template.md`, `bd-ipa-template.md`, `dd-ipa-template.md`).
#### `apps/okr/domain/input/`
Input data for the AI-SDLC flow:
- **`okr-requirement.md`** — Raw requirement documents from the customer.
#### `docs/technical_architecture.md`
Technical stack decisions and constraints (languages, frameworks, infrastructure).
#### `apps/okr/domain/input/change-request/`
Change requests applied during the project lifecycle (e.g., `change-0406.md`).
#### `apps/<project-id>/domain/input/`
Per-project requirements and architecture used by CASAN gates and traceability.
The L2 initializer creates missing domain-pack files without overwriting existing
project content.
#### `docs/output/`
All artifacts produced by the AI-SDLC process:
@@ -402,115 +398,7 @@ All artifacts produced by the AI-SDLC process:
Each folder contains `spec.md`, `plan.md`, `tasks.md`, `checklists/`, and `contracts/`. This directory serves as the **knowledge base** for agents.
#### Source Code
Source code generated by Agents during `speckit.implement` (STEP 10).
`apps/okr/backend/` and `apps/okr/frontend/` contain the application source code, co-located with the monorepo root:
- **`apps/okr/backend/`** — NestJS application. `src/` contains feature modules (`auth/`, `users/`, `objectives/`, `workspaces/`, `common/`). `prisma/` contains `schema.prisma`, migrations, and `seed.ts`. `test/` contains unit tests organized by module (`auth/`, `objectives/`, `users/`). Includes `Dockerfile`.
- **`apps/okr/frontend/`** — React + Vite SPA (TypeScript). `src/pages/` for route-level components (Login, ForgotPassword, Dashboard, CreateObjective, EditObjective, ObjectiveDetail, KeyResultDetail); `src/components/` organized by feature (`auth/`, `dashboard/`, `objective-detail/`, `objective-form/`), `layout/` (Sidebar, AppHeader, AppLayout) and `ui/` (Button, Input, Alert). `src/hooks/` (useAuth, useObjectives, useUsers, useWorkspaces), `src/lib/` (api, queryClient), `src/schemas/`, `src/types/`. `test/` contains unit tests (`hooks/`, `pages/`). Includes `Dockerfile`.
- **`e2e/`** — End-to-end tests using Playwright, organized by feature (e.g., `auth/auth.spec.ts`).
- **`docker/`** — Docker utilities. Main orchestration is in `docker-compose.yml` at the project root.
---
## OKR Web Application — Quick Start
### Description
The **OKR Web Application** is a full-stack web app for managing Objectives and Key Results (OKR). It consists of:
- **Backend**: NestJS REST API with Prisma ORM and MySQL
- **Frontend**: React + Vite SPA with Tailwind CSS
- **Database**: MySQL 8.0
### Prerequisites
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
- Node.js 20.x and npm (for local development without Docker)
### Quick Start (Docker)
```bash
# Navigate to the repository root
cd <repo-root>
# Build and start all services (MySQL + Backend + Frontend)
docker compose up --build
# To run in detached mode
docker compose up --build -d
```
Docker Compose will automatically:
1. Start MySQL and wait for it to be healthy
2. Run Prisma migrations (`prisma migrate deploy`)
3. Seed the database with default data (`prisma db seed`)
4. Start the NestJS backend
5. Start the React frontend dev server
### Default Credentials
| Role | Email | Password |
|------|-------|----------|
| Admin | `admin@okr.local` | `Password@123` |
| Manager | `manager@okr.local` | `Password@123` |
| Employee | `employee@okr.local` | `Password@123` |
### Service URLs
| Service | URL |
|---------|-----|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:3000 |
| API Documentation (Swagger) | http://localhost:3000/api/docs |
| MySQL | localhost:3307 |
### Development Without Docker
#### Backend
```bash
cd apps/okr/backend
# Install dependencies
npm install
# Copy and configure environment variables
cp .env.example .env
# Edit .env — set DATABASE_URL to point to your local MySQL instance
# Run database migrations
npx prisma migrate dev
# Seed the database
npx prisma db seed
# Start the development server
npm run start:dev
```
#### Frontend
```bash
cd apps/okr/frontend
# Install dependencies
npm install
# Copy and configure environment variables
cp .env.example .env
# Edit .env if the backend runs on a different port
# Start the Vite dev server
npm run dev
```
The frontend will be available at http://localhost:5173 and proxies API requests to http://localhost:3000/api/v1.
### Stopping Services
```bash
# Stop all containers
docker compose down
# Stop and remove volumes (resets the database)
docker compose down -v
```
CASAN does not prescribe NestJS, React, Java, .NET, or any other application
stack. Existing source, CI, `.claude`, `.github`, agents, skills, prompts, and
project instructions remain project-owned. Hybrid init only adds or merges the
CASAN integration files documented above.