# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Chinese Tobacco AI Contract and Case Audit System** (中国烟草AI合同及卷宗审核系统) - a Remix-based full-stack application for intelligent document review and evaluation. The system provides AI-powered contract auditing, risk assessment, and compliance checking.

**Tech Stack:**
- Frontend: Remix (React) + TypeScript + Vite
- Styling: Tailwind CSS + custom CSS
- Icons: Remixicon (locally hosted)
- Document Processing: react-pdf, mammoth, docx-preview
- Backend API: PostgreSQL + PostgREST
- Authentication: OAuth2.0 + JWT + cookie-based sessions
- Deployment: Docker + PM2 (multi-instance setup)

## Core Commands

### Development
```bash
npm run dev                          # Start dev server (port 5173)
npm run typecheck                    # Run TypeScript type checking
npm run lint                         # Run ESLint
```

### Building
```bash
npm run build                        # Production build
npm run build:production:multi       # Build for production multi-instance
npm run build:test:multi             # Build for testing multi-instance
npm run build:dev                    # Build for development
```

### Production Deployment
```bash
npm start                            # Start production server (single instance)
npm run start:pm2:production:multi   # Build and start PM2 multi-instance (production)
npm run start:pm2:multi              # Build and start PM2 multi-instance (testing)
```

### JWT Secret Generation
```bash
npm run generate:jwt-secret          # Generate a secure JWT secret for production
```

### Docker Deployment
```bash
# Build image
docker build -t docreview-app .

# Run with docker-compose
docker-compose up -d

# The system exposes 6 ports for different regional clients:
# 51703: Meizhou (main)
# 51704: Yunfu
# 51705: Jieyang
# 51706: Chaozhou
# 51707: Province
# 51708: Test instance (limited to /cross-checking routes)
```

## Architecture

### Multi-Instance Deployment Strategy

The system uses a **port-based multi-client architecture** where:
- One codebase serves multiple regional clients
- Each client runs on a different port with isolated configurations
- Port-specific API configurations are defined in `app/config/api-config.ts`
- PM2 manages multiple instances via `ecosystem.config.cjs`
- Each instance has its own environment variables (PORT, CLIENT_ID, API_PORT_CONFIG)

### Authentication Flow

1. **OAuth2.0 Integration** (IDaaS-based):
   - OAuth client configuration in `app/api/login/oauth-client.ts`
   - Callback handling in `app/routes/callback.tsx`
   - User info sync with local PostgreSQL database

2. **JWT Token Management**:
   - Frontend JWT generated after OAuth success (`app/api/jwt-helper.server.ts`)
   - JWT contains user info, role, and permissions
   - Stored in encrypted cookie session
   - Auto-refresh when OAuth token refreshes
   - **CRITICAL**: JWT_SECRET must be set in `.env` (use `npm run generate:jwt-secret`)

3. **Session Management**:
   - Cookie-based sessions via `createCookieSessionStorage`
   - Global authentication check in `app/root.tsx` loader
   - Role-based access control (common vs developer roles)
   - Developer-only paths: /settings, /config-lists, /document-types, /prompts

### API Configuration System

**Port-Based Configuration** (`app/config/api-config.ts`):
- Automatically detects current port and applies correct API config
- Each port maps to specific backend services (PostgreSQL, MinIO, etc.)
- Environment variables can override port configs:
  - `NEXT_PUBLIC_API_BASE_URL` - PostgreSQL API base URL
  - `NEXT_PUBLIC_DOCUMENT_URL` - MinIO document storage URL
  - `NEXT_PUBLIC_UPLOAD_URL` - File upload endpoint

**Configuration Priority**: Port-specific config > Environment variables > Default environment config

### Route Structure

- `app/routes/` - Remix file-based routing
  - `_index.tsx` - Home page (redirects to /documents or /cross-checking based on port)
  - `login.tsx` - Login page with OAuth flow
  - `callback.tsx` - OAuth callback handler
  - `documents.tsx` / `documents._index.tsx` - Document management
  - `cross-checking.tsx` - Cross-examination system
  - `contract-template.tsx` - Contract template search
  - `chat-with-llm._index.tsx` - AI chat interface
  - `api.*.tsx` - API routes for backend proxy

### API Layer Organization

- `app/api/` - API client modules
  - `axios-client.ts` - Configured axios instance with auth headers
  - `postgrest-client.ts` - PostgREST API client
  - `db-client.server.ts` - Server-side database client
  - `jwt-helper.server.ts` - JWT generation and validation
  - `login/auth.server.ts` - Authentication service (getUserSession, logout)
  - `login/oauth-client.ts` - OAuth2.0 client implementation
  - `login/token-manager.server.ts` - Token refresh and management

**Important**: Always use `axios-client.ts` for API calls. It automatically:
- Adds JWT authentication headers
- Handles API base URL configuration
- Includes proper error handling

### Component Architecture

**Design System** (`app/components/ui/`):
- All components follow BEM naming convention
- Primary color: `#00684a` (tobacco corporate green)
- Components are self-contained with co-located styles
- Import styles in `app/styles/main.css`

**Key Components**:
- `Layout.tsx` - Main layout with sidebar and header
- `Sidebar.tsx` - Navigation sidebar (role-based menu filtering)
- `MessageModal.tsx` - Confirmation/alert modal system
- `Toast.tsx` - Toast notification provider
- `LoadingBar.tsx` - Top loading bar for route transitions
- `FilePreview.tsx` - PDF/Word document preview

**RemixIcon Usage**:
- Icons are locally hosted in `public/fonts/`
- Use class syntax: `<i className="ri-home-line"></i>`
- Preloaded via link tag for instant display
- **CRITICAL**: When using CSS isolation (like `all: unset`), add exception rules for RemixIcon classes (see `docs/docreview-development-standards.md` for examples)

### Cross-Checking System

**Overview**: Democratic proposal and voting system for document evaluation disputes.

**Key Concepts**:
- **Tasks**: Evaluation assignments with multiple reviewers
- **Proposals**: Suggestions to modify evaluation scores
- **Voting**: Democratic decision-making with approval threshold
- **Arbitration**: Automatic status determination based on vote counts

**Database Tables**:
- `cross_examination_tasks` - Task assignments
- `cross_task_document_mapping` - Document-task relationships
- `cross_scoring_proposals` - Score modification proposals
- `cross_opinion_votes` - Vote records

**API Routes** (via `app/routes/api.*.tsx` proxies):
- `POST /admin/cross_review/tasks/assign` - Assign cross-checking task
- `POST /admin/cross_review/proposals` - Create proposal
- `POST /admin/cross_review/proposals/{id}/votes` - Vote on proposal
- `DELETE /admin/cross_review/proposals/{id}` - Withdraw proposal

See `docs/交叉评查系统完整文档.md` for complete documentation.

## Environment Variables

**Required** (create `.env` file):
```bash
# JWT Secret - MUST be set for production
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# OAuth2.0 Configuration (set in PM2 config or env)
OAUTH_CLIENT_SECRET=your-oauth-client-secret

# API Configuration (optional, overrides port-based config)
NEXT_PUBLIC_API_BASE_URL=http://10.79.97.17:8000
NEXT_PUBLIC_DOCUMENT_URL=http://10.76.244.156:9000/docauditai/
NEXT_PUBLIC_UPLOAD_URL=http://10.79.97.17:8000/admin/documents
```

**PM2 Instance Variables** (set in `ecosystem.config.cjs`):
- `NODE_ENV` - Environment (production/testing/development)
- `PORT` - Server port
- `CLIENT_ID` - Regional client identifier
- `API_PORT_CONFIG` - Port-based API configuration selector

## Development Guidelines

### Code Style

**TypeScript**:
- Use explicit types for function parameters and return values
- Interface naming: PascalCase (e.g., `DocumentUI`, `ApiConfig`)
- Use string literal unions for status types
- Avoid `any` - use `unknown` if type is truly unknown

**React Components**:
- Use function declarations, not arrow functions: `export function Component() {}`
- Group hooks at top: useState first, then useEffect
- Event handlers: `handleClick`, `handleSubmit` naming
- Props interface: `ComponentNameProps`

**File Naming**:
- Components: `PascalCase.tsx` (Button.tsx)
- Routes: `kebab-case.tsx` (user-profile.tsx)
- Utilities: `camelCase.ts` (utils.ts)

**Import Order**:
1. React and Remix imports
2. Third-party libraries
3. Internal components with `~/` alias
4. Type imports
5. Styles

### Styling

**Color Variables** (defined in `app/root.tsx`):
```css
--color-primary: #00684a;           /* Tobacco green */
--color-primary-hover: #005a3f;
--color-primary-light: rgba(0, 104, 74, 0.1);
--color-success: #52c41a;
--color-warning: #faad14;
--color-error: #f5222d;
```

**Spacing**: Use Tailwind defaults (4px base: p-4, mt-6, etc.)
**Border Radius**: `rounded-md` (6px) for buttons/cards
**Shadows**: `shadow-sm` default, `shadow-md` on hover

### Error Handling

- Use `ErrorBoundary` component for route-level errors
- API errors: Log and return appropriate Response.json with status
- Display user-friendly messages via MessageModal or Toast
- Never expose sensitive error details to users

### Performance

- Use `React.memo` for pure components that re-render frequently
- Lazy load heavy components (PDF viewers, code editors)
- Debounce search inputs (300ms standard)
- Optimize images and use appropriate formats

## Security Considerations

1. **JWT Secret**: NEVER commit JWT_SECRET to version control
2. **OAuth Client Secret**: Store in environment variables, not code
3. **API Keys**: Use server-side only (no NEXT_PUBLIC_ prefix)
4. **Session Cookies**: httpOnly, secure in production
5. **Port 51708 Restrictions**: Limited to /cross-checking routes only

## Testing

- Test OAuth flow with IDaaS server at `http://10.79.112.85`
- Verify JWT generation and validation
- Check port-based API configuration switching
- Test role-based access control (common vs developer)
- Validate cross-checking voting logic and thresholds

## Common Pitfalls

1. **RemixIcon not showing**: Check for CSS rules overriding `font-family: 'remixicon'`
2. **API config not updating**: Port detection may need window.location.port on client
3. **JWT expired**: Implement token refresh or re-authenticate
4. **PM2 env vars not working**: Ensure NEXT_PUBLIC_ prefix for client-side vars
5. **File upload fails**: Check UPLOAD_URL configuration for current port

## Additional Documentation

Detailed documentation is available in `docs/`:
- `docreview-development-standards.md` - Comprehensive coding standards
- `交叉评查系统完整文档.md` - Cross-checking system specification
- `JWT_IMPLEMENTATION.md` - JWT authentication implementation
- `OAuth2.0认证协议集成指南.md` - OAuth integration guide
- `docker-deployment.md` - Docker deployment instructions
- `deployment-config.md` - Multi-instance deployment configuration