# AI 开发入口 [!IMPORTANT]

- **本文档要求**：本文档为当前仓库的项目级规范和重要导航，进入源码前必须先读。
- **本文档要求**：优先在现有目录职责内做增删改；若要新增一级目录、基础设施或工程约定，必须先更新本文档和对应文档。
- **本文档要求**：后续新增/删除 `.ai-specs` 文档时，必须同步更新 `## 项目文档`。
- **文档要求**：规范型文档是给 AI 的顶层入口文档，要求短、硬、可判定，不写泛泛背景说明。
- **代码优化**：先复用再新增；允许抽公共逻辑，但边界必须清晰。
- **代码优化**：优化时必须同时考虑冗余、命名、复杂度、边界条件、兼容性和包体积，不能只追求功能跑通。不要擅自修改 UI/UX 视觉效果，除非需求明确。
- **代码默认遵循**：业务实现优先采用微信原生小程序主流做法，保持可维护、可调试、可发布。
- **代码默认遵循**：强制工作流：按 `## 项目文档` 定位需要的文档 -> 读取匹配文档 -> 进入源码。

## 工具使用规则

- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `node_modules`、`miniprogram_npm`、`coverage` 等生成或依赖目录。
- **读写**：所有文件读取/写入统一使用 UTF-8（建议无 BOM）。
- **读写**：PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`。
- **生成产物**：不要直接编辑微信开发者工具生成目录，例如 `miniprogram_npm`。
- **画图**：优先使用 `mermaid flowchart`。
- **对话/文档编写**：必须以中文为主体语言，技术术语保留英文原文。
- **命令执行**：运行依赖、测试、格式化、CI 前，先读取 `package.json` 中已有 scripts，不重复发明命令入口。

## 项目架构

- **技术栈**：本项目为 `微信原生小程序 + JavaScript + npm + TDesign`，运行时采用 `glass-easel` 组件框架；工程化使用 `ESLint`、`Prettier`、`Jest`、`miniprogram-ci`。
- **代码链路**：本项目采用 `Page / Component -> services/api -> services/request -> RuntimeConfig / SessionStore -> Backend`。
- **状态与配置**：`config` 管理环境与常量，`stores` 管理跨页共享状态，`utils` 只放纯工具函数。

    ├── app.js / app.json / app.wxss     (应用初始化、路由注册、全局样式)
    ├── pages                            (主包页面：首屏、登录、公共能力)
    ├── packages                         (分包页面，按业务域拆分)
    ├── components
    │   ├── base                         (基础组件)
    │   └── biz                          (业务组件)
    ├── services
    │   ├── api                          (按业务模块封装接口)
    │   └── request                      (统一请求、鉴权、重试、去重)
    ├── stores
    │   └── modules                      (跨页共享状态)
    ├── config                           (环境配置、常量)
    ├── utils                            (纯工具函数)
    ├── tests                            (Jest 测试)
    └── scripts/ci                       (小程序 CI 脚本)

| 层级 | 职责 | 命名规范 |
|:---|:---|:---|
| App | 初始化运行时配置、注册全局拦截与跳转、同步 `globalData` | 固定使用 `app.js`、`app.json`、`app.wxss` |
| Page | 承载页面数据、交互、路由跳转；不直接承载通用请求封装与跨页状态持久化 | 主包目录固定 `pages/<name>/index.*`；分包目录固定 `packages/<pkg>/pages/<name>/index.*` |
| Component | 承载可复用视图和局部交互，通过 `properties` / `events` 与页面通信 | 基础组件放 `components/base/<name>`；业务组件放 `components/biz/<name>` |
| API | 按业务封装接口方法，屏蔽 URL / Method / payload 细节；不直接持有页面 UI 状态 | 目录固定 `services/api/<module>.js`；聚合出口固定 `services/api/index.js` |
| Request | 统一处理 `baseURL`、header、token、超时、鉴权失效、重试和请求去重 | 目录固定 `services/request/index.js` |
| Store | 管理跨页共享和本地持久化状态；不与具体页面强耦合 | 模块固定 `stores/modules/<name>.js`；聚合出口固定 `stores/index.js` |
| Config | 管理环境、常量、timeout、storage key；避免魔法值散落 | 目录固定 `config/*.js` |
| Utils | 存放纯函数；禁止依赖页面实例、组件实例或全局 UI 状态 | 目录固定 `utils/*.js` |

- 主包只放首屏、登录、Tab 和全局公共能力；新业务页面优先考虑放进对应分包。
- 页面和组件里不要直接调用 `wx.request`；统一走 `services/request`。
- 跨页共享状态统一放 `stores`；页面局部状态留在 `Page` / `Component` 的 `data` 内。
- 环境切换、`baseURL` 和 `timeout` 统一走 `config/env.js` 与 `config/constants.js`。
- 新增接口模块时，先补 `services/api/<module>.js`，再决定页面如何消费；不要把请求细节散落到页面。

### 架构关系

- 关系总线：`Page / Component -> API -> Request -> Env + SessionStore -> Backend`，其中 `app.js` 负责运行时初始化、登录态同步和未授权跳转。

```mermaid
flowchart LR
    APP["app.js<br/>运行时初始化 / 未授权跳转"] --> SESSION["stores/modules/session.js<br/>登录态持久化"]
    PAGE["Page / Component"] --> API["services/api/*.js"]
    PAGE --> COMPONENT["components/base + components/biz"]
    API --> REQUEST["services/request/index.js"]
    REQUEST --> ENV["config/env.js"]
    REQUEST --> SESSION
    SESSION --> STORAGE["wx storage"]
    REQUEST --> BACKEND["Backend API"]
```

- 改 `app.json`：必须同步检查 `pages`、`subPackages`、`preloadRule`、实际目录路径和页面跳转路径是否一致。
- 改 `pages/*` 或 `packages/*`：必须同步检查路由注册、导航目标、页面 JSON 中的组件注册、对应 API / Store 依赖。
- 改 `components/base/*` 或 `components/biz/*`：必须同步检查 `index.js`、`index.json`、`index.wxml`、`index.wxss` 四件套，以及引用方的 `properties` / `events` 契约。
- 改 `services/api/*`：必须同步检查 URL、Method、payload、response contract 和所有调用页的 loading / error / empty state。
- 改 `services/request/index.js`：必须同步检查 `config/env.js`、`config/constants.js`、`stores/modules/session.js`、`app.js` 的未授权处理，以及所有 API 模块的调用预期。
- 改 `stores/modules/session.js`：必须同步检查 storage key、`app.js` 中的 hydrate / subscribe、登录页和依赖权限的页面逻辑。
- 改 `config/env.js` 或 `config/constants.js`：必须同步检查请求层默认值、环境切换行为、CI 脚本和登录态相关逻辑。
- 新增/修改业务功能时，默认顺序是：先定页面归属与路由 -> 再定 API / Store 契约 -> 再落页面与组件 -> 最后回查 `app.json`、聚合导出和项目文档；禁止只改单点不回查上下游。

## 项目文档

- **当前已启用文档**：根目录 `README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md`、`.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md`、`.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-implementation-plan.md`
- **预留扩展目录**：`.ai-specs`（已创建；后续新增/删除文档必须在本节登记）
- **要求**：开始修改前，先按任务类型定位文档；有对应文档必须先读；未命中时按本文件通用规则和现有同层代码风格实现。

### root-docs

| 路径 | 用途 | 说明 |
|:---|:---|:---|
| `README.md` | 项目启动、目录、命令、CI、分包落点说明 | 涉及本地运行、构建 npm、测试、格式化、CI 上传、目录归属时必读 |

### .ai-specs 规划

| 分类 | 用途 | 说明 |
|:---|:---|:---|
| `coding-specs` | 存放页面分包、接口封装、状态管理、组件复用等实现规范 | 仓库复杂度上来后优先补齐 |
| `logic-specs` | 存放业务流程、页面信息架构、角色权限等业务说明 | 涉及多页面串联和复杂交互时补齐 |
| `sys-specs` | 存放环境、发布、CI、版本管理等系统级规则 | 涉及发布流程和工程治理时补齐 |

### .ai-specs 已启用文档

| 路径 | 用途 | 说明 |
|:---|:---|:---|


### 后端接口文档
D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-dict  字典参考
D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-api\admin  后端 api文档

## 可复用代码/组件

| 中文 | 代码文件名 | 说明 |
|:---|:---|:---|
| 统一请求封装 | `services/request/index.js` | 统一处理 `baseURL`、token 注入、鉴权失效、超时、重试和请求去重 |
| 用户接口模块 | `services/api/user.js` | 用户资料查询与更新的 API 封装示例 |
| Session Store | `stores/modules/session.js` | 登录态持久化、hydrate、订阅变更 |
| Store 聚合出口 | `stores/index.js` | 统一导出 store，供 `app.js` 和页面引用 |
| App Button | `components/base/app-button` | 基础按钮组件，透出常用主题、尺寸和形态 |
| Entry Card | `components/biz/entry-card` | 首页 / 工作台入口卡片组件 |
| 运行时环境配置 | `config/env.js` | 根据微信环境选择 `baseURL` 与 `timeout` |