tailscale-custom/.agent/workflows/ins-develop.md

---
description: INS Module feature development workflow. Full lifecycle from planning to verification. Standard for all INS modules (HRM, PRO, CDE, WJC, etc.)
---

# /ins-develop - INS Module Feature Development

$ARGUMENTS

---

## Architecture Context

All INS modules follow the same architecture:

```
┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser    │────▶│  INS.{MOD}.Backend│────▶│ sso-instratech  │
│  (Blazor     │     │  localhost:{PORT} │gRPC │ 10.0.0.1:8082   │
│   WASM)      │     │                  │     │ (Auth/SSO)       │
└──────────────┘     └────────┬─────────┘     └─────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │                    │
               ┌────▼─────┐      ┌──────▼──────┐
               │ INS_{MOD}│      │  INS_SYS    │
               │ Module DB│      │  Auth DB    │
               └──────────┘      └─────────────┘
```

| Component | Description |
|-----------|-------------|
| **Frontend** | `src/INS.{MOD}.Frontend/` — Blazor WASM, AdminLTE sidebar |
| **Backend** | `src/INS.{MOD}.Backend/` — ASP.NET 8, Kestrel |
| **Auth DLL** | `INS.ModuleControllers.dll` — gRPC auth, SSO, navigation |
| **Module DB** | Business data (employees, projects, documents, etc.) |
| **Auth DB** | `INS_SYS` on `dev.instratech.net` — users, permissions, navigation |
| **gRPC** | `sso-instratech` container at `10.0.0.1:8082` |

---

## Phase 0: KNOWLEDGE DISCOVERY (🔴 BẮT BUỘC — Luôn chạy đầu tiên)

> **KHÔNG ĐƯỢC BỎ QUA.** Trước khi làm bất cứ gì, phải tìm kiếm knowledge base.

1. **Search knowledge base** — Tìm quy tắc dự án, patterns, conventions
   ```
   mcp_knowledge_search_knowledge(query="{tên tính năng hoặc domain liên quan}")
   mcp_knowledge_search_knowledge(query="INS component")
   mcp_knowledge_search_knowledge(query="coding conventions")
   ```

2. **Read relevant KI artifacts** — Đọc chi tiết các KI tìm được (architecture, component usage rules, past implementations)

3. **Check module-specific knowledge** — Tìm theo module
   ```
   mcp_knowledge_list_modules(solution="ins-pro") // hoặc module đang phát triển
   mcp_knowledge_get_module_context(solution="...", moduleName="...")
   ```

4. **Check global standards** — Đọc coding standards chung
   ```
   mcp_knowledge_get_global_standards()
   ```

5. **Result:** Ghi nhận tất cả rules/constraints phải tuân thủ trước khi code.

---

## Phase 1: RESEARCH (Bắt buộc)

// turbo-all

6. **Identify module** — Determine ModuleCode (e.g., `INS.HRM`, `INS.PRO`, `INS.CDE`)
7. **Check DB schema** — Connect to module DB and inspect tables
   ```powershell
   # Query schema
   $connStr = "<module connection string from appsettings.json>"
   # SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES
   # SELECT COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = '...'
   ```
8. **Check existing code** — Search for related `.razor`, `.cs` files, controllers
9. **Check permissions** — Query `[Auth].[ApplicationRules]` for existing FuncCodes of this module
10. **Check navigation** — Verify sidebar entries in module DB (e.g., `BranchInfo` table)

---

## Phase 2: PLAN

7. **Create implementation plan** — Break into:
   - [ ] DB changes (tables, seed data, migrations)
   - [ ] Backend (controllers, services, DTOs)
   - [ ] Frontend (pages, components, sidebar entries)
   - [ ] Permissions (new FuncCodes in `INS_SYS`)
   - [ ] Navigation (sidebar menu items)

8. **Present plan to user** — Wait for approval before coding.

---

## Phase 3: IMPLEMENT

### 3a. Database First
9. **Create/modify tables** — EF Core migrations or raw SQL
10. **Seed reference data** — Insert into module DB
11. **Add permission rules** — Insert into `INS_SYS`
    ```sql
    -- AuthDb connection: Server=dev.instratech.net;Database=INS_SYS;User Id=spm34d.ins;Password=SPM2025@#;...
    
    -- 1. Add rule definition
    INSERT INTO [Auth].[ApplicationRules] (ModuleCode, Category, FuncCode, Description, IsActive, CreatedAt, UpdatedAt)
    VALUES ('INS.{MOD}', '{Category}', '{MOD}_{CAT}_{ACTION}', N'{Description}', 1, GETDATE(), GETDATE());
    
    -- 2. Assign to root user
    INSERT INTO [Auth].[UserApplicationRules] (UserId, RuleId, IsAllowed, AssignedBy, AssignedAt)
    SELECT 'root', ar.Id, 1, 'system', GETDATE()
    FROM [Auth].[ApplicationRules] ar
    WHERE ar.FuncCode = '{MOD}_{CAT}_{ACTION}'
    AND NOT EXISTS (SELECT 1 FROM [Auth].[UserApplicationRules] uar WHERE uar.UserId = 'root' AND uar.RuleId = ar.Id);
    ```

### 3b. Backend
12. **Create DTOs** in `Models/`
13. **Create Controller** — follow existing controller patterns in the module
14. **Register services** in `Program.cs` if needed
15. **Middleware check** — ensure new endpoints work with gRPC validation pipeline

### 3c. Frontend
16. **Create page** in `Pages/` — follow existing page patterns
17. **Add sidebar entry** — Insert navigation record (e.g., `BranchInfo`)
18. **Use INS components** — `INS_DataGrid`, `INS_Popup`, `INS_RuleInit` (check KB!)
19. **Wire API calls** — `HttpClient` with auth token from `IModuleAuthenticationService`

---

## Phase 4: BUILD & TEST

// turbo-all

20. **Stop server**
    ```powershell
    Stop-Process -Name "INS.{MOD}.Backend" -Force -ErrorAction SilentlyContinue
    ```

21. **Build**
    ```powershell
    dotnet build src/INS.{MOD}.Backend/INS.{MOD}.Backend.csproj
    ```

22. **Fix build errors** — Check `error CS` output, fix, rebuild

23. **Start server**
    ```powershell
    dotnet run --project src/INS.{MOD}.Backend/INS.{MOD}.Backend.csproj
    ```

24. **Verify startup logs** — Must see:
    - `Now listening on: http://localhost:{PORT}` ✅
    - No gRPC connection errors ✅
    - No DB errors ✅

---

## Phase 5: VERIFY

25. **API test** via PowerShell
    ```powershell
    $login = Invoke-RestMethod -Method Post -Uri "http://localhost:{PORT}/api/auth/login" `
      -Body (@{email="root@local.instratech";password="admin123"} | ConvertTo-Json) -ContentType "application/json"
    $h = @{ "Authorization" = "Bearer $($login.token)" }
    Invoke-RestMethod -Uri "http://localhost:{PORT}/{mod}/api/{endpoint}" -Headers $h
    ```

26. **Browser test** — Login, navigate, verify:
    - All buttons visible (permissions loaded correctly)
    - Data displays, CRUD works
    - Popup/modal margins follow INS component guidelines

27. **Permission verify** — `api/applicationrule/user` returns new FuncCodes

---

## Phase 6: REVIEW

28. **Check logs** for warnings/errors
29. **Remove debug code**
30. **Report** to user with change summary

---

## Troubleshooting

| Symptom | Root Cause | Fix |
|---------|-----------|-----|
| gRPC connection refused | `sso-instratech` stopped | `ssh root@36.50.176.30 "docker start sso-instratech"` |
| 401 on data API | Token not validated by gRPC | Check `GrpcTokenValidationMiddleware` logs |
| 401 on `/api/applicationrule` | Path not bypassed | `UseWhen` must exclude `/api/applicationrule` |
| Buttons missing | FuncCode not in DB | Insert into `[Auth].[ApplicationRules]` + assign to user |
| DB already exists | `EnsureCreated()` | Wrap in try-catch |
| Build locked file | Previous process | `Stop-Process -Name "INS.{MOD}.Backend" -Force` |
| SSO register-session fail | gRPC server unreachable | Check `appsettings.json > GrpcClient.ServerUrl` |
| Popup margins wrong | Component misuse | Check knowledge base for INS component rules |

---

## Server Infrastructure

| Container | Host Port | Internal | Purpose |
|-----------|-----------|----------|---------|
| `sso-instratech` | **8082** | 8082 | SSO/Auth gRPC (ALL modules use this) |
| `ins-sys` | 8083/7001 | 8082/8080 | INS.SYS Backend |
| `epm-sqlserver` | 1434 | 1433 | SQL Server |
| `epm-gateway` | 5000 | 5000 | API Gateway |

SSH: `ssh root@36.50.176.30`

---

## Examples

```
/ins-develop thêm module quản lý hợp đồng
/ins-develop thêm chức năng export PDF cho báo cáo
/ins-develop thêm trang dashboard thống kê
/ins-develop thêm CRUD cho bảng mới
```