msk_admin/Lumina-MSK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update the repo

Browse Source
This commit is contained in:
DatTT127
2026-06-23 13:39:43 +07:00
parent 3283a8f8af
commit fdb384434d
61 changed files with 1450 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
AGENT_SKILL/interface_contract_hygiene/CHECKLIST.md Normal file
View File

@@ -0,0 +1,29 @@
# Checklist: interface_contract_hygiene
## New Module/Package Creation
- [ ] New module/package includes a `spec/` directory
- [ ] `spec/interface-contract.md` file exists in the new module
- [ ] Contract file is located at `<module_path>/spec/interface-contract.md`
## Contract Content Verification
- [ ] Contract includes a clear **Purpose** section
- [ ] Contract identifies an **Owner** (team or individual)
- [ ] Contract defines the **Boundary** (includes/excludes)
- [ ] Contract specifies a **Breaking-change Policy**
- [ ] Contract lists **Consumers** (other modules/systems that use this)
- [ ] Contract provides **References** to related documentation
- [ ] Contract follows the same format/structure as existing contracts in the same domain
## Contract Modification (Existing Modules)
When modifying a public API (changing function signatures, adding/removing endpoints, etc.):
- [ ] Breaking changes follow the versioning policy:
- Adding features: MINOR version bump
- Removing/changing types: MAJOR version with migration path and 60-day notice
- [ ] Deprecation warnings are added for removed/changed interfaces
- [ ] Migration documentation is provided for breaking changes
## Template Consistency Check
Before creating a new contract:
- [ ] Reviewed at least two existing interface-contract.md files in the same domain (backend/frontend/infra)
- [ ] Matched section headings and formatting conventions
- [ ] Used similar language and level of detail

161
AGENT_SKILL/interface_contract_hygiene/EXAMPLES.md Normal file
View File

@@ -0,0 +1,161 @@
# Examples: interface_contract_hygiene
## Correct Examples
### Backend Service Contract Example
File: `backend/services/patient_service/spec/interface_contract.md`
```markdown
# Patient Service Interface Contract
## Purpose
Handles all patient-related business operations including registration, updates, and retrieval of patient records. Provides a clean API for frontend and other backend services.
## Owner
Platform Team (platform-team@vkist.example.com)
## Boundary
**Includes:**
- Patient data validation
- Appointment scheduling logic
- Insurance verification workflows
- HL7 message parsing for patient demographics
**Excludes:**
- Image storage and retrieval (handled by Imaging Service)
- Payment processing (handled by Billing Service)
- User authentication (handled by Auth Service)
## Breaking-change Policy
- **MINOR version**: Adding new optional fields to patient schema, new endpoints for non-core features
- **MAJOR version**: Removing fields, changing data types of existing fields, removing endpoints
- Requires 60-day deprecation period
- Migration guide provided in release notes
- Deprecation warnings added 30 days prior to removal
## Consumers
- Frontend Patient Portal (`frontend/modules/patient_portal`)
- Appointment Scheduling Service (`backend/services/scheduling`)
- Billing Service (`backend/services/billing`)
- Mobile App API (`backend/services/mobile-api`)
## References
- [Patient Data Model](../models/patient_model.md)
- [API Specification](api-spec.yaml)
- [HL7 Interface Specification](../integrations/hl7-spec.md)
```
### Frontend Module Contract Example
File: `frontend/modules/appointment_scheduler/spec/interface_contract.md`
```markdown
# Appointment Scheduler Module Contract
## Purpose
Provides UI components and state management for scheduling, rescheduling, and cancelling patient appointments. Integrates with calendar services and sends notifications.
## Owner
Frontend Team (frontend-team@vkist.example.com)
## Boundary
**Includes:**
- Appointment booking form components
- Calendar view widgets
- Conflict detection logic
- Notification scheduling (email/SMS)
- Form validation for appointment constraints
**Excludes:**
- Patient identity verification (handled by Auth Module)
- Payment collection for appointments (handled by Billing Module)
- Actual calendar sync with external systems (handled by Calendar Integration Service)
## Breaking-change Policy
- **MINOR**: Adding new optional props to components, new utility functions
- **MAJOR**: Removing props, changing prop types, removing components
- Requires minor version bump in package.json
- Migration guide in CHANGELOG.md
- Deprecated props logged as warnings for 2 minor versions
## Consumers
- Main App Layout (`frontend/layout/MainLayout`)
- Patient Dashboard (`frontend/modules/patient_dashboard`)
- Provider Portal (`frontend/modules/provider_portal`)
## References
- [Component Library Guidelines](../../shared/components/README.md)
- [API Contract with Backend](../services/appointment_service/spec/interface-contract.md)
- [Accessibility Requirements](../../docs/accessibility.md)
```
### Infrastructure Module Contract Example
File: `infra/modules/networking/spec/interface_contract.md`
```markdown
# Networking Module Contract
## Purpose
Defines AWS/VPC networking infrastructure including subnets, route tables, security groups, and DNS configuration for the VKIST deployment.
## Owner
Infrastructure Team (infra-team@vkist.example.com)
## Boundary
**Includes:**
- VPC creation and CIDR allocation
- Public and private subnet configuration
- Internet gateway and NAT gateway setup
- Route table association
- Security group baseline rules
- DNS zone and record creation
**Excludes:**
- Compute resources (EC2/EKS) (handled by compute modules)
- Database infrastructure (handled by database module)
- Application-level security (handled by respective service modules)
## Breaking-change Policy
- **MINOR**: Adding new subnets, adding non-restrictive security group rules
- **MAJOR**: Changing VPC CIDR, removing subnets, altering route tables that break connectivity
- Requires terraform state migration plan
- 30-day review period with stakeholders
- Backward compatibility maintained via Terraform state import where possible
## Consumers
- Compute Module (`infra/modules/compute`)
- Database Module (`infra/modules/database`)
- EKS Cluster Module (`infra/modules/eks`)
- All environment-specific configurations (staging, production)
## References
- [AWS VPC Best Practices](../docs/aws_vpc_best practices.md)
- [Network Security Policy](../../docs/security/network_policy.md)
- [Terraform Module Guidelines](../../modules/README.md)
```
## Incorrect Examples (to avoid)
### Missing Contract
```diff
- // No spec/interface-contract.md exists for this new service
+ mkdir -p backend/services/new_service
+ touch backend/services/new_service/main.py
```
### Incomplete Contract
```markdown
# Incomplete Service
## Purpose
Handles user notifications.
// Missing: Owner, Boundary, Breaking-change Policy, Consumers, References
```
### Wrong Location
```diff
- // Contract should be in spec/ but is placed in root
+ NEW SERVICE/
+ interface_contract.md // WRONG LOCATION
+ main.py
+ requirements.txt
```

41
AGENT_SKILL/interface_contract_hygiene/SKILL.md Normal file
View File

@@ -0,0 +1,41 @@
# Skill: interface_contract_hygiene
## Trigger Conditions
- Creation of a new module, package, or component
- Any modification to a public API (function signatures, class interfaces, endpoints)
- Creation of a new directory that represents a logical boundary (e.g., new service, new frontend module)
## Rules
### 1. Interface Contract Requirement
- Every module boundary MUST have an `interface_contract.md` file in its `spec/` directory.
- Applies to: backend services, frontend modules, data access layers, infrastructure components.
- Severity: `[ERROR]`
### 2. Contract Content Requirements
Each `interface_contract.md` must include:
- **Purpose**: Brief description of what the module does
- **Owner**: Team or person responsible for the module
- **Boundary**: Clear definition of what is inside and outside the module
- **Breaking-change Policy**: How breaking changes are handled (versioning, deprecation)
- **Consumers**: List of other modules or systems that use this module
- **References**: Links to related documentation, diagrams, or external specifications
- Severity: `[ERROR]`
### 3. Versioning and Backward Compatibility
- Adding new fields, endpoints, or optional parameters: MINOR version bump (backward compatible)
- Removing or changing types of existing fields/endpoints: MAJOR version bump with:
- Migration path documentation
- 60-day deprecation notice minimum
- Deprecation warnings in code
- Severity: `[ERROR]`
### 4. Template Consistency
- When creating a new `interface_contract.md`, the author MUST review existing contracts in the same domain for naming and template consistency.
- Use the same section headings and format as neighboring contracts.
- Severity: `[WARN]`
### 5. Contract Location
- Contract must be located at `<module_path>/spec/interface_contract.md`
- If `spec/` directory does not exist, it must be created.
- Severity: `[ERROR]`