# Codebase Structure

**Analysis Date:** 2026-04-21

## Directory Layout

```
D:\code\php\amlhc\
├── application/                          # ThinkPHP application code
│   ├── admin/                            # Backend admin module
│   │   ├── behavior/                     # Admin behavior hooks
│   │   ├── command/                      # CLI commands
│   │   │   ├── Addon.php                 # Addon command
│   │   │   ├── Api.php                   # API doc generator
│   │   │   │   ├── lang/zh-cn.php
│   │   │   │   └── library/              # Builder.php, Extractor.php
│   │   │   ├── Crud.php                  # CRUD code generator
│   │   │   │   └── stubs/                # Template stubs
│   │   │   ├── Install/                  # Installation wizard
│   │   │   │   ├── install.lock
│   │   │   │   └── zh-cn.php
│   │   │   ├── Menu.php                  # Menu generator
│   │   │   └── Min.php                   # JS/CSS minifier
│   │   ├── controller/                   # Admin controllers (18 total)
│   │   │   ├── Addon.php                 # Plugin management
│   │   │   ├── Ajax.php                  # Shared AJAX endpoints
│   │   │   ├── Category.php              # Category management
│   │   │   ├── Command.php               # Online command execution
│   │   │   ├── Dashboard.php             # Dashboard statistics
│   │   │   ├── History.php               # Lottery history management
│   │   │   ├── Index.php                 # Admin login/home/logout
│   │   │   ├── Num.php                   # Lottery number/color mapping
│   │   │   ├── auth/
│   │   │   │   ├── Admin.php             # Admin user management
│   │   │   │   ├── Adminlog.php          # Admin operation log
│   │   │   │   ├── Group.php             # Role group management
│   │   │   │   └── Rule.php              # Permission rule management
│   │   │   ├── general/
│   │   │   │   ├── Attachment.php        # File attachment management
│   │   │   │   ├── Config.php            # System configuration
│   │   │   │   └── Profile.php           # Admin profile management
│   │   │   └── user/
│   │   │       ├── Group.php             # User group management
│   │   │       ├── Rule.php              # User rule management
│   │   │       └── User.php              # Member management
│   │   ├── lang/zh-cn/                   # Admin language (17 files)
│   │   │   ├── addon.php                 # Addon language
│   │   │   ├── ajax.php                  # Ajax language
│   │   │   ├── category.php              # Category language
│   │   │   ├── command.php               # Command language
│   │   │   ├── config.php                # Config language
│   │   │   ├── dashboard.php             # Dashboard language
│   │   │   ├── history.php               # History language
│   │   │   ├── index.php                 # Login/home language
│   │   │   ├── auth/
│   │   │   │   ├── admin.php             # Admin management language
│   │   │   │   ├── group.php             # Group management language
│   │   │   │   └── rule.php              # Rule management language
│   │   │   ├── general/
│   │   │   │   ├── attachment.php        # Attachment language
│   │   │   │   ├── config.php            # Config language
│   │   │   │   └── profile.php           # Profile language
│   │   │   └── user/
│   │   │       ├── group.php             # User group language
│   │   │       ├── rule.php              # User rule language
│   │   │       └── user.php              # User management language
│   │   ├── library/                      # Admin-specific libraries
│   │   │   └── traits/
│   │   │       └── Backend.php           # CRUD trait (index/add/edit/del/etc.)
│   │   │   └── Auth.php                  # Admin auth (extends fast\Auth)
│   │   ├── model/                        # Admin models (11 files)
│   │   │   ├── Admin.php                 # Admin user model
│   │   │   ├── AdminLog.php              # Admin log model
│   │   │   ├── AuthGroup.php             # Auth group model
│   │   │   ├── AuthGroupAccess.php       # Admin-group pivot model
│   │   │   ├── AuthRule.php              # Auth rule model
│   │   │   ├── Command.php               # Command execution log model
│   │   │   ├── History.php               # Lottery history model
│   │   │   ├── Num.php                   # Lottery number model
│   │   │   ├── User.php                  # Admin-side user model (with hooks)
│   │   │   ├── UserGroup.php             # User group model
│   │   │   └── UserRule.php              # User rule model
│   │   ├── validate/                     # Admin validators (8 files)
│   │   │   ├── Admin.php                 # Admin user validation
│   │   │   ├── AuthRule.php              # Auth rule validation
│   │   │   ├── Category.php              # Category validation
│   │   │   ├── Command.php               # Command validation
│   │   │   ├── History.php               # History validation (empty rules)
│   │   │   ├── User.php                  # User validation
│   │   │   ├── UserGroup.php             # User group validation
│   │   │   └── UserRule.php              # User rule validation
│   │   └── view/                         # Admin view templates (48 HTML files)
│   │       ├── addon/                    # Addon views
│   │       │   ├── add.html
│   │       │   ├── config.html
│   │       │   └── index.html
│   │       ├── auth/
│   │       │   ├── admin/
│   │       │   │   ├── add.html
│   │       │   │   ├── edit.html
│   │       │   │   └── index.html
│   │       │   ├── adminlog/
│   │       │   │   ├── detail.html
│   │       │   │   └── index.html
│   │       │   ├── group/
│   │       │   │   ├── add.html
│   │       │   │   ├── edit.html
│   │       │   │   └── index.html
│   │       │   └── rule/
│   │       │       ├── add.html
│   │       │       ├── edit.html
│   │       │       ├── index.html
│   │       │       └── tpl.html
│   │       ├── category/
│   │       │   ├── add.html
│   │       │   ├── edit.html
│   │       │   └── index.html
│   │       ├── command/
│   │       │   ├── add.html
│   │       │   ├── detail.html
│   │       │   └── index.html
│   │       ├── common/                   # Shared admin partials
│   │       │   ├── control.html
│   │       │   ├── header.html
│   │       │   ├── menu.html
│   │       │   ├── meta.html
│   │       │   └── script.html
│   │       ├── dashboard/
│   │       │   └── index.html
│   │       ├── general/
│   │       │   ├── attachment/
│   │       │   │   ├── add.html
│   │       │   │   ├── edit.html
│   │       │   │   ├── index.html
│   │       │   │   └── select.html
│   │       │   └── config/
│   │       │       └── index.html
│   │       ├── history/
│   │       │   ├── add.html
│   │       │   ├── edit.html
│   │       │   └── index.html
│   │       ├── index/
│   │       │   ├── index.html            # Admin home page
│   │       │   └── login.html            # Admin login page
│   │       ├── layout/
│   │       │   └── default.html          # Main admin layout
│   │       └── user/
│   │           ├── group/
│   │           │   ├── add.html
│   │           │   ├── edit.html
│   │           │   └── index.html
│   │           ├── rule/
│   │           │   ├── add.html
│   │           │   ├── edit.html
│   │           │   └── index.html
│   │           └── user/
│   │               ├── edit.html
│   │               └── index.html
│   ├── api/                              # REST API module
│   │   ├── controller/                   # API controllers (8 files)
│   │   │   ├── Common.php                # Common API (upload endpoint)
│   │   │   ├── Demo.php                  # Demo API endpoints
│   │   │   ├── Ems.php                   # Email verification API
│   │   │   ├── Index.php                 # API homepage
│   │   │   ├── Sms.php                   # SMS verification API
│   │   │   ├── Token.php                 # Token management API
│   │   │   ├── User.php                  # User auth/profile API
│   │   │   └── Validate.php              # Validation testing API
│   │   ├── lang/zh-cn/                   # API language packs
│   │   └── library/                      # API-specific libraries
│   ├── common/                           # Shared code across modules
│   │   ├── behavior/                     # Shared behavior hooks
│   │   │   └── Common.php
│   │   ├── controller/                   # Base controllers (3 files)
│   │   │   ├── Backend.php               # Admin base controller
│   │   │   ├── Frontend.php              # Frontend base controller
│   │   │   └── Api.php                   # API base controller
│   │   ├── exception/                    # Custom exceptions
│   │   │   └── UploadException.php       # Upload failure exception
│   │   ├── lang/zh-cn/                   # Shared language packs
│   │   ├── library/                      # Shared libraries (10 files)
│   │   │   ├── Auth.php                  # User authentication (token-based)
│   │   │   ├── Email.php                 # Email sending (PHPMailer)
│   │   │   ├── Ems.php                   # Email verification code
│   │   │   ├── Log.php                   # Logging utility
│   │   │   ├── Menu.php                  # Menu generation
│   │   │   ├── Security.php              # Security utilities
│   │   │   ├── Sms.php                   # SMS verification code
│   │   │   ├── Token.php                 # Token storage manager
│   │   │   ├── Upload.php                # File upload handler
│   │   │   └── token/
│   │   │       ├── Driver.php            # Token driver interface
│   │   │       └── driver/
│   │   │           ├── Mysql.php         # MySQL token driver
│   │   │           └── Redis.php         # Redis token driver
│   │   ├── model/                        # Shared models (12 files)
│   │   │   ├── Area.php                  # Province/city/area data
│   │   │   ├── Attachment.php            # File attachment model
│   │   │   ├── Category.php              # Category model
│   │   │   ├── Config.php                # System config model
│   │   │   ├── Em s.php                   # Email verification log
│   │   │   ├── MoneyLog.php              # User money change log
│   │   │   ├── ScoreLog.php              # User score change log
│   │   │   ├── Sms.php                   # SMS verification log
│   │   │   ├── User.php                  # User model
│   │   │   ├── UserGroup.php             # User group model
│   │   │   ├── UserRule.php              # User rule model
│   │   │   └── Version.php               # Version info model
│   │   └── view/tpl/                     # Shared templates
│   │       ├── dispatch_jump.tpl         # Redirect template
│   │       └── think_exception.tpl       # Exception page template
│   ├── index/                            # Frontend (user-facing) module
│   │   ├── controller/                   # Frontend controllers (3 files)
│   │   │   ├── Ajax.php                  # Frontend AJAX (lang, icon, upload)
│   │   │   ├── Index.php                 # Homepage + lottery scraping
│   │   │   └── User.php                  # Member center (login/register/profile)
│   │   ├── lang/                         # Frontend language packs
│   │   │   ├── en/
│   │   │   └── zh-cn/
│   │   └── view/
│   │       ├── common/
│   │       ├── index/
│   │       │   └── index.html            # Homepage
│   │       ├── layout/
│   │       │   └── default.html          # Frontend layout
│   │       └── user/
│   ├── extra/                            # Extra config files
│   │   ├── addons.php                    # Addon hooks and routes
│   │   ├── queue.php                     # Queue configuration
│   │   ├── site.php                      # Site configuration
│   │   └── upload.php                    # Upload configuration
│   ├── common.php                        # Global helper functions
│   ├── config.php                        # Main ThinkPHP config
│   ├── database.php                      # Database connection config
│   ├── command.php                       # CLI command registry
│   └── route.php                         # Route definitions
├── extend/                               # Custom extension classes
│   └── fast/                             # FastAdmin helper classes
│       ├── Auth.php                      # RBAC permission checker
│       ├── Date.php                      # Date formatting utilities
│       ├── Form.php                      # Form builder
│       ├── Http.php                      # HTTP client utility
│       ├── Pinyin.php                    # Chinese pinyin conversion
│       ├── Random.php                    # Random string generation
│       ├── Rsa.php                       # RSA encryption
│       ├── Tree.php                      # Tree data structure
│       └── Version.php                   # Version comparison
├── addons/                               # Plugin/addon directory
├── public/                               # Web root
│   ├── index.php                         # Web entry point
│   └── assets/                           # Static assets (JS, CSS, images)
├── runtime/                              # Runtime files (cache, logs, temp)
├── think                                 # CLI entry point
├── thinkphp/                             # ThinkPHP framework core
├── vendor/                               # Composer dependencies
└── sql/                                  # SQL migration files
```

## Directory Purposes

### `application/admin/` — Backend Administration
- Purpose: Complete backend management system with RBAC
- Contains: 18 controllers, 11 models, 8 validators, 48 view templates, 17 language files
- Subdirectories:
  - `controller/auth/` — Admin RBAC (admin users, groups, rules, logs)
  - `controller/general/` — System utilities (attachments, config, profile)
  - `controller/user/` — Frontend user management from admin panel
  - `command/` — CLI code generators (CRUD, menu, min, api, addon)
  - `library/` — Auth class + Backend CRUD trait
  - `view/layout/default.html` — Main admin layout template

### `application/index/` — Frontend User Portal
- Purpose: Public-facing website and member center
- Contains: 3 controllers (Index, User, Ajax)
- Custom domain files:
  - `controller/Index.php::get_history()` — Lottery data scraping from macaumarksix.com
  - Uses `\GuzzleHttp\Client` to fetch lottery results
  - Writes to `fa_history` table via raw `Db` queries (not ORM)

### `application/api/` — REST API
- Purpose: API for mobile/third-party clients
- Contains: 8 controllers, all extend `app\common\controller\Api`
- Standard response format: `{code, msg, time, data}`

### `application/common/` — Shared Code
- Purpose: Base controllers, shared models, utility libraries
- Contains: 3 base controllers, 12 shared models, 10 libraries, 1 exception
- Token driver pattern: pluggable MySQL or Redis storage

### `extend/fast/` — Framework Utilities
- Purpose: FastAdmin core utility classes (not in composer autoload)
- Contains: Tree (hierarchical data), Auth (RBAC base), Date, Random, Http, Form, Rsa, Pinyin, Version

## Admin Controller → Model → View → Validate → Lang Mapping

### auth/admin — 管理员管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/auth/Admin.php` |
| Model | `application/admin/model/Admin.php` |
| Model (pivot) | `application/admin/model/AuthGroupAccess.php` |
| Model (group) | `application/admin/model/AuthGroup.php` |
| View (list) | `application/admin/view/auth/admin/index.html` |
| View (add) | `application/admin/view/auth/admin/add.html` |
| View (edit) | `application/admin/view/auth/admin/edit.html` |
| Validate | `application/admin/validate/Admin.php` |
| Lang | `application/admin/lang/zh-cn/auth/admin.php` |

### auth/adminlog — 管理员日志
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/auth/Adminlog.php` |
| Model | `application/admin/model/AdminLog.php` |
| View (list) | `application/admin/view/auth/adminlog/index.html` |
| View (detail) | `application/admin/view/auth/adminlog/detail.html` |
| Validate | *(none — read-only)* |
| Lang | *(uses auth/admin.php)* |

### auth/group — 角色组管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/auth/Group.php` |
| Model | `application/admin/model/AuthGroup.php` |
| View (list) | `application/admin/view/auth/group/index.html` |
| View (add) | `application/admin/view/auth/group/add.html` |
| View (edit) | `application/admin/view/auth/group/edit.html` |
| Validate | *(none — uses inline validation)* |
| Lang | `application/admin/lang/zh-cn/auth/group.php` |

### auth/rule — 权限规则管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/auth/Rule.php` |
| Model | `application/admin/model/AuthRule.php` |
| View (list) | `application/admin/view/auth/rule/index.html` |
| View (add) | `application/admin/view/auth/rule/add.html` |
| View (edit) | `application/admin/view/auth/rule/edit.html` |
| View (template) | `application/admin/view/auth/rule/tpl.html` |
| Validate | `application/admin/validate/AuthRule.php` |
| Lang | `application/admin/lang/zh-cn/auth/rule.php` |

### general/attachment — 附件管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/general/Attachment.php` |
| Model | `application/common/model/Attachment.php` |
| View (list) | `application/admin/view/general/attachment/index.html` |
| View (add) | `application/admin/view/general/attachment/add.html` |
| View (edit) | `application/admin/view/general/attachment/edit.html` |
| View (select) | `application/admin/view/general/attachment/select.html` |
| Validate | *(none — uses model validation)* |
| Lang | `application/admin/lang/zh-cn/general/attachment.php` |

### general/config — 系统配置
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/general/Config.php` |
| Model | `application/common/model/Config.php` |
| View (list) | `application/admin/view/general/config/index.html` |
| Validate | *(none — inline validation)* |
| Lang | `application/admin/lang/zh-cn/general/config.php` |

### general/profile — 个人资料
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/general/Profile.php` |
| Model | `application/admin/model/Admin.php` + `application/admin/model/AdminLog.php` |
| View (list) | `application/admin/view/general/profile/index.html` |
| Validate | *(none)* |
| Lang | `application/admin/lang/zh-cn/general/profile.php` |

### user/user — 会员管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/user/User.php` |
| Model | `application/admin/model/User.php` |
| Model (group) | `application/admin/model/UserGroup.php` |
| View (list) | `application/admin/view/user/user/index.html` |
| View (edit) | `application/admin/view/user/user/edit.html` |
| Validate | `application/admin/validate/User.php` |
| Lang | `application/admin/lang/zh-cn/user/user.php` |

### user/group — 会员组管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/user/Group.php` |
| Model | `application/admin/model/UserGroup.php` |
| View (list) | `application/admin/view/user/group/index.html` |
| View (add) | `application/admin/view/user/group/add.html` |
| View (edit) | `application/admin/view/user/group/edit.html` |
| Validate | `application/admin/validate/UserGroup.php` |
| Lang | `application/admin/lang/zh-cn/user/group.php` |

### user/rule — 会员规则管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/user/Rule.php` |
| Model | `application/admin/model/UserRule.php` |
| View (list) | `application/admin/view/user/rule/index.html` |
| View (add) | `application/admin/view/user/rule/add.html` |
| View (edit) | `application/admin/view/user/rule/edit.html` |
| Validate | `application/admin/validate/UserRule.php` |
| Lang | `application/admin/lang/zh-cn/user/rule.php` |

### history — 彩票历史记录
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/History.php` |
| Model | `application/admin/model/History.php` |
| View (list) | `application/admin/view/history/index.html` |
| View (add) | `application/admin/view/history/add.html` |
| View (edit) | `application/admin/view/history/edit.html` |
| Validate | `application/admin/validate/History.php` (empty rules) |
| Lang | `application/admin/lang/zh-cn/history.php` |

### num — 数字波色
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Num.php` |
| Model | `application/admin/model/Num.php` |
| View | *(no dedicated views — uses trait defaults)* |
| Validate | *(none)* |
| Lang | *(none — uses generic)* |

### category — 分类管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Category.php` |
| Model | `application/common/model/Category.php` |
| View (list) | `application/admin/view/category/index.html` |
| View (add) | `application/admin/view/category/add.html` |
| View (edit) | `application/admin/view/category/edit.html` |
| Validate | `application/admin/validate/Category.php` (empty rules) |
| Lang | `application/admin/lang/zh-cn/category.php` |

### command — 在线命令
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Command.php` |
| Model | `application/admin/model/Command.php` |
| View (list) | `application/admin/view/command/index.html` |
| View (add) | `application/admin/view/command/add.html` |
| View (detail) | `application/admin/view/command/detail.html` |
| Validate | `application/admin/validate/Command.php` (empty rules) |
| Lang | `application/admin/lang/zh-cn/command.php` |

### dashboard — 控制台
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Dashboard.php` |
| Model | *(multiple — Admin, User, Attachment, Category via direct queries)* |
| View (list) | `application/admin/view/dashboard/index.html` |
| Validate | *(none)* |
| Lang | `application/admin/lang/zh-cn/dashboard.php` |

### addon — 插件管理
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Addon.php` |
| Model | *(none — uses Service class directly)* |
| View (list) | `application/admin/view/addon/index.html` |
| View (add) | `application/admin/view/addon/add.html` |
| View (config) | `application/admin/view/addon/config.html` |
| Validate | *(none)* |
| Lang | `application/admin/lang/zh-cn/addon.php` |

### index (admin) — 后台首页/登录
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Index.php` |
| Model | `application/admin/model/Admin.php` |
| View (home) | `application/admin/view/index/index.html` |
| View (login) | `application/admin/view/index/login.html` |
| Validate | *(inline in login method)* |
| Lang | `application/admin/lang/zh-cn/index.php` |

### ajax (admin) — 通用异步接口
| Layer | File |
|-------|------|
| Controller | `application/admin/controller/Ajax.php` |
| Model | *(various — Attachment, Category, Area via Db queries)* |
| View | *(none — JSON responses only)* |
| Validate | *(none)* |
| Lang | `application/admin/lang/zh-cn/ajax.php` |

## Custom Domain Files (Lottery Feature)

| File | Purpose |
|------|---------|
| `application/index/controller/Index.php` | Homepage + `get_history()` scrapes Macau lottery data from macaumarksix.com |
| `application/admin/controller/History.php` | Admin CRUD for lottery history (read-only display) |
| `application/admin/controller/Num.php` | Num→color mapping API via `getColorMap()` |
| `application/admin/model/History.php` | History model: table `fa_history`, fields `expect`, `openTime`, `num1`~`num7` |
| `application/admin/model/Num.php` | Num model: table `fa_num`, fields `num`, `color` |
| `application/admin/validate/History.php` | Empty validator (no validation rules defined) |
| `application/admin/view/history/index.html` | List view with add/edit buttons hidden |
| `application/admin/view/history/add.html` | Add form template (unused) |
| `application/admin/view/history/edit.html` | Edit form template (unused) |
| `application/admin/lang/zh-cn/history.php` | Chinese language strings for history module |

## Common Models (Shared Across Modules)

| File | Table | Purpose |
|------|-------|---------|
| `application/common/model/User.php` | `fa_user` | Frontend user with money/score log hooks |
| `application/common/model/UserGroup.php` | `fa_user_group` | User group |
| `application/common/model/UserRule.php` | `fa_user_rule` | User permission rule |
| `application/common/model/Category.php` | `fa_category` | Hierarchical category system |
| `application/common/model/Config.php` | `fa_config` | System configuration |
| `application/common/model/Attachment.php` | `fa_attachment` | File upload metadata |
| `application/common/model/Attachment.php` | `fa_area` | Province/city/area data |
| `application/common/model/MoneyLog.php` | `fa_money_log` | User balance change log |
| `application/common/model/ScoreLog.php` | `fa_score_log` | User score change log |
| `application/common/model/Ems.php` | `fa_ems` | Email verification log |
| `application/common/model/Sms.php` | `fa_sms` | SMS verification log |
| `application/common/model/Version.php` | `fa_version` | Version info |

## API Controllers (Complete List)

| Controller | File | Key Methods |
|------------|------|-------------|
| Index | `application/api/controller/Index.php` | `index()` |
| User | `application/api/controller/User.php` | `login()`, `mobilelogin()`, `register()`, `logout()`, `profile()`, `changeemail()`, `changemobile()`, `third()`, `resetpwd()` |
| Token | `application/api/controller/Token.php` | Token management endpoints |
| Ems | `application/api/controller/Ems.php` | Email verification |
| Sms | `application/api/controller/Sms.php` | SMS verification |
| Common | `application/api/controller/Common.php` | Shared upload endpoint |
| Demo | `application/api/controller/Demo.php` | Demo/test endpoints |
| Validate | `application/api/controller/Validate.php` | Validation testing |

## Naming Conventions

**Files:**
- Controllers: PascalCase (`AuthRule.php`, `Dashboard.php`, `History.php`)
- Models: PascalCase (`AdminLog.php`, `UserGroup.php`, `AuthGroupAccess.php`)
- Validators: PascalCase matching model name (`Admin.php`, `User.php`, `History.php`)
- Libraries: PascalCase (`Upload.php`, `Auth.php`, `Email.php`)
- Views: lowercase with `.html` (`index.html`, `add.html`, `edit.html`)
- Language files: lowercase PHP (`user.php`, `category.php`)
- Commands: PascalCase (`Crud.php`, `Menu.php`, `Min.php`)

**Directories:**
- Controller subdirectories: lowercase (`auth/`, `general/`, `user/`)
- View subdirectories: mirror controller structure (`view/auth/admin/`, `view/general/config/`)

**Namespaces:**
- Controllers: `app\{module}\controller\{sub?}\{Name}`
- Models: `app\admin\model\{Name}` or `app\common\model\{Name}`
- Libraries: `app\admin\library\{Name}` or `app\common\library\{Name}`
- Validators: `app\admin\validate\{Name}`
- Commands: `app\admin\command\{Name}`
- Extensions: `fast\{Name}` (PSR-4 from `extend/fast/`)

## Where to Add New Code

**New Admin Module (CRUD):**
1. Controller: `application/admin/controller/{SubDir}/{Name}.php` — extend `app\common\controller\Backend`
2. Model: `application/admin/model/{Name}.php` — extend `think\Model`, set `$name` to table name
3. View: `application/admin/view/{subdir}/{name}/index.html` (list), `add.html`, `edit.html`
4. Validate: `application/admin/validate/{Name}.php` — extend `think\Validate`
5. Lang: `application/admin/lang/zh-cn/{subdir}/{name}.php`
6. Generate menu: run `php think menu --controller={subdir/name}`

**New Admin Module (Custom Logic):**
- Same as CRUD but override trait methods in controller as needed
- Set `$model` property in `_initialize()` to link controller to model

**New API Endpoint:**
- Controller: `application/api/controller/{Name}.php` — extend `app\common\controller\Api`
- Use `$noNeedLogin = ['*']` for public endpoints
- Return via `$this->success($data)` or `$this->error($msg)`

**New Frontend Page:**
- Controller: `application/index/controller/{Name}.php` — extend `app\common\controller\Frontend`
- View: `application/index/view/{name}/{action}.html`

**New Shared Model:**
- `application/common/model/{Name}.php` — extend `think\Model`
- Used by multiple modules (admin + index + api)

**New Library:**
- `application/common/library/{Name}.php` for cross-module utilities
- `application/admin/library/{Name}.php` for admin-only utilities
- `extend/fast/{Name}.php` for framework-level utilities

**New CLI Command:**
- `application/admin/command/{Name}.php` — extend `\think\console\Command`
- Register in `application/command.php`

## Special Directories

**`runtime/`:**
- Purpose: ThinkPHP runtime cache, logs, compiled templates
- Generated: Yes (by ThinkPHP)
- Committed: No

**`addons/`:**
- Purpose: Plugin directory for FastAdmin addon system
- Generated: Yes (when installing addons via admin panel)
- Committed: No

**`vendor/`:**
- Purpose: Composer dependencies
- Generated: Yes (`composer install`)
- Committed: No

**`extend/fast/`:**
- Purpose: FastAdmin core utilities not distributed via composer
- Committed: Yes (part of application)
- Key classes: `Tree`, `Auth` (RBAC base), `Date`, `Random`, `Http`

**`public/assets/`:**
- Purpose: Static frontend/backend assets (JS, CSS, images)
- `public/assets/js/backend/` — Admin panel JavaScript (matches controller names)
- `public/assets/js/frontend/` — Frontend JavaScript
- `public/assets/js/backend/command.js` — Command module JS
- `public/assets/js/backend/history.js` — History module JS

**`sql/`:**
- Purpose: SQL migration/schema files
- Contains database dumps and migration scripts

---

*Structure analysis: 2026-04-21*